Link Search Menu Expand Document

Configuration

Before you run tests, you must setup a configuration for the equipment you want to tests.

For example, the validator needs to know the SXL (type of equipment), because the SXL is not send by the equipment when connecting.

Config files

Configurations are stored as YAML files in the folder config/.

The config file contains network settings, timeouts and intervals, list RSMP components, etc. used to run tests.

When you test a site, the config is used to start a local supervisor, using the rsmp gem).

Similarly, when you test a supervisor, the config is used to start a local site.

Note: The folder config/private is ignored by git can can be used for experimenting with configs that you don’t want to store in git.

Choosing what config to use

After creating your test configuration, you need to point the validator to it.

One option is is to use the config/validator.yaml file. It’s a YAML file, with either a site or supervisor key, depending on what you’re testing. The value should contain the path to your config file.

For example, if you’re testing a site, your .validator.yaml file might look like this:

site: config/my_site_validation_config.yaml

You can use the file config/validator_example.yaml as a template.

Note: The file config/validator.yaml is ignored by git.

The other option is to set either SITE_CONFIG or SUPERVISOR_CONFIG to the path to your config, depending on whether you’re testing a site or a supervisor. For example, if you’re testing a site, you can run all site test with:

SITE_CONFIG=config/my_site_validation_config.yaml bundle exec spec/site

If the relevant environment variable is set, the file config/validator.yaml will not be read.

Options for Site testing

The config is used to start the local supervisor that will communicate with the site you’re, but includes additional options used by the validator, like timeouts and options to restrict what tests to run.

All settings except components and items can be left out, in which case the default values will be used.

port: 13111             # port to listen on
ips: all                # allowed ip addresses. either 'all' or a list
rsmp_versions: all      # allowed core version(s). either 'all' or a list
sxl: tlc                # sxl of the connecting site, options are 'core' or 'tlc'
intervals:
  timer: 1              # main timer interval (resolution), in seconds
  watchdog: 1           # how often to send watchdog messages, in seconds
  update_date: 0        # requested update rate when subscribing to statuses, in seconds
timeouts:
  watchdog: 2           # max time bewteen incoming watchdogs, in seconds
  acknowledgement: 2    # max time until acknowledgement is received, in seconds
  connect: 1            # max time until site connects, in seconds
  ready: 1              # max time until site completes connecton sequence, in seconds
  status_response: 1    # max time until site responds to a status request, in seconds
  status_update: 1      # max time until site sends a status update, in seconds
  subscribe: 1          # max time until site sends a status update, in seconds
  command: 1            # max time until a command results in a status update, in seconds
  command_response: 1   # max time until site responds to a command request, in seconds
  alarm: 1              # max time until site raises an alarm, in seconds
  disconnect: 1         # max time until site disconnects, in seconds
  shutdown: 1           # max time until site shuts down for a restart, in seconds
components:             # list of rsmp components, organized by type and name, in seconds
  main:                 # type
    TC:                 # name. note that this is an (empty) options hash
  signal_group:
    A1:
    A2:
  detector_logic:       
    DL1:
items:                  # other configurations that should be tested
  plans: [1,2]                # list of plans
  traffic_situations: [1,2]   # list of traffic situations
  emergency_routes: [1]       # list of emergency route
  inputs: [1]                 # list of emergency inputs (I/O)
restrict_testing:       # restrict what tests are run, default is to run all
  core_version: 3.1.5   # skip unless relevant for core 3.1.5
  sxl_version: 1.0.13   # skip unless relevant for sxl 1.0.13
secrets:                # place secrets or in a separate file, see below
  security_codes:       # RSMP security codes. there are no defaults for these
    1: '1111'           # level 1
    2: '2222'           # level 2

The following settings will be copied into a configuration for the local supervisor: port, sxl, intervals, timeouts, components, rsmp_versions.

The supervisor config will also have max_sites: 1 and ips: all meaning it will allow connections from any ip and with any RSMP site id, but will only allow one site to be connected at a time. Multiple connections will be flagged as an error.

See the rsmp gem for more details about these settings.

Options for Supervisor testing

When testing a supervisor, the settings are used by the local site without modifications.

# Config for testing a supervisor running on localhost (e.g. one from the rsmp gem)
# The settings are used for starting a local site connecting to the supervisor tested
type: tlc               # type of local site to run
site_id: RN+SI0001      # site id of local site
supervisors:          # what supervisor the local site should connect to
  - ip: 127.0.0.1       # ip
    port: 13111         # port
sxl: tlc                # sxl to use, options are 'core' or 'tlc'
sxl_version: 1.0.15     # sxl version to use
components:           # components of local site, organized by type and name
  main:                 # type
    TC:                 # name
      cycle_time: 6     # options for component 'TC'
  signal_group:
    A1:
      plan: '11NBBB'
    A2:
      plan: '1NBBBB'
    B1:
      plan: 'BBB11N'
    B2:
      plan: 'BBB1NB'
  detector_logic:
    DL1:
intervals:            # intervals
  timer: 0.1            # basic timer resolution in seconds, in seconds
  watchdog: 0.1         # time between sending watchdog messages, in seconds
  reconnect: 0.1        # interval between retries if supervisor is unreachable, in seconds
timeouts:             # timeouts
  connect: 1            # max time it should take to connect, in seconds
  ready: 1              # max time to complete handshake sequence, in seconds
  watchdog: 0.2         # max time between receiving watchdogs, in seconds
  acknowledgement: 0.2  # max time unless a message we send is acknowledged, in seconds
restrict_testing:       # restrict what tests are run, default is to run all
  core_version: 3.1.5   # skip unless relevant for core 3.1.5
  sxl_version: 1.0.13   # skip unless relevant for sxl 1.0.13
secrets:                # place secrets or in a separate file, see below
  security_codes:       # RSMP security codes. there are no defaults for these
    1: '1111'           # level 1
    2: '2222'           # level 2

SXL Option

The sxl attribute of a configuration specifies what SXL to use for communication. Curently, the only valid options are:

  • core: Generic RSMP communication. No alarms, commands or status are allowed, only core messages.
  • sxl: Traffic Light Controllers.

The sxl will choose the JSON Schema used to validate all ingoing and outgoing messages. It also restrict what type of components can be listed under the components attribute in the configuration.

Equipment that doesn’t yet have a standardized SXL cannot be fully validated using the RSMP validator, because there are no tests for these types yet, and because there is no JSON Schema to validate the command and statuses for such types of equipment.

However, you can still use the RSMP Validator to valiate the core part of the communication, including connecting, Aggregated Status and Watchdog messages. Use ‘core’ as the sxl type in the configuration and then running only the tests in the folder spec/site/core/. Remember to also set sxl version to version of the core specification used, e.g. 3.1.5.

Components Option

RSMP equipment has a list of RSMP components. For example a traffic light controller will have some signal groups and detector logics. In addition all RSMP equipment must have a main component.

To know what to test, your validator configuration must list the components in the equipment under the components attribute. Components are organized by type.

For example, here’s the component part of a configuration for a traffic light controller with two signal groups, two detector logics, and the main component:

components:
  main:                   # typer
    KK+AG9998=001TC000:   # component id (a hash, due to the colon)
  signal_group:
    KK+AG9998=001SG001:
    KK+AG9998=001SG002:
  detector_logic:
    KK+AG9998=001DL001:
    KK+AG9998=001DL002:

The component ids (e.g. KK+AG9998=001TC000 in the example above) must match the components in the equipment. Otherwise tests will fail.

Note that each component must be defined as a hash in the YAML file, be using a training colon. As the example above show, the hash will ususally be empty. (Items are used to configure components when you run local RSMP site, e.g. a TLC emulator.)

Timeouts

Timeouts are defined in seconds. Timeouts should be set as low as possible while, still giving the site time to respond correctly before tests times out and report errors.

Configuring the actual site/supervisor

You should make sure that the actual site or supervisor you want to test is configured to match the validator configuration file, i.e. that the components match and intervals and timeouts are compatible.

When testing a site, you need to configure it to connect to the validator. This typically includes setting an ip address and port. If the site and the validator is running in the same machine, the ip address will typically be localhost or 127.0.0.1.

When testing a supervisor, you need to configure it to listen for connections on the same port as the validator uses, and make it does reject the connection due to firewalls, ip filtering, or rsmp site id filtering.

RSMP Traffic Light Controllers be default communicate on port 12111, but to avoid interfering with real installations, the validator uses port 13111 by default. You can use another port if you like, just be sure to configure the equipment and the validator to use the same port.

If the site cannot connect to the validator, check the ip and port, and make sure firewalls, etc are not blocking the connection.

Secrets

Some tests involve commands that require RSMP security codes.

You can place security codes either directly in your config file, or in a separate file.

Note: Files with names ending in _secrets.yaml are git-ignored.

Secrets have the following structure when in a separate file:

security_codes:
  1: '0000'
  2: '0000'

Restricting tests based on Core and SXL version

Usually there is no need to run tests that relate to core or sxl versions newer than what the site or supervisor your testing is using.

Each test is tagged with the core and sxl version it’s relevant for. For example S0027 was added in the SXL version 1.0.13, which is why the test for S0027 is tagged with sxl: '>=1.0.13. This means the test is relevant if testing is either unrestricted or restricted to sxl 1.0.13 or higher.

specify 'day table is read with S0027', sxl: '>=1.0.13'  do |example|
  request_status_and_confirm "command table",
    { S0027: [:status] }
end

This following test run only if testing is unrestricted or restricted to exactly core version 3.1.5.

it 'is correct for rsmp version 3.1.5',  core: '3.1.5' do |example|
  check_sequence '3.1.5'
end

You can limit the tests that will run by adding restrict_testing options in the config file for the test:

restrict_testing:
  core_version: 3.1.2
  sxl_version: 1.0.7 

In this case, the S0027 test above will not run, because it requires sxl 1.0.13 or higher, but we limited to 1.0.7.

Usaully you will want to set restrict_testing version to what the site or supervisor is actually using, but it’s possible to use other values.