WeOS
5.29.0

# TRDP custom telegrams

## Introduction

The Custom Telegrams function is a feature that allows for the creation and management of user-defined telegrams using the TRDP communications protocol. This functionality is designed to enhance the flexibility and adaptability of train communication systems, enabling the integration of custom messages and data structures with existing TRDP-based applications.

To understand this section, the reader should have a basic understanding of IP-TCN and the TRDP protocol as defined in IEC61375-2-3.

## Overview

WeOS includes an implementation of the TRDP protocol, as part of IP-TCN. This implementation includes certain interfaces, most notably the ones described in IEC61375-2-3 chapter 5 (CSTINFO exchange and related functionality) and Annex E (the service interface) from the same standard.

Additionally, WeOS provides infrastructure for custom telegrams. There is a predefined set of data items, each with its own semantics and meaning, available for inclusion in datasets. These datasets can then be used as the payloads for individual telegrams.

Currently, only TRDP Process Data (TRDP type ‘Pd’, not ‘Pr’ nor ‘Pp’) telegrams are supported, both incoming (TRDP subscribers) and outgoing (TRDP publishers). The addressing, periodicity/timeout, and ComID of these telegrams is user configurable, along with the payload (which consists of one of the previously mentioned datasets).

### Configuration

Configuration of custom telegrams in WeOS involves two steps. First, datasets are constructed from data items, and the dataset definition file is uploaded to the device. Then, telegrams are configured to use these datasets as their payloads.

The data items themselves are listed and described in detail in an external document. Consider reviewing this document carefully to understand the available options and their implications.

#### Selecting data items

WeOS provides a set of predefined data items that can be used in custom telegrams. These data items are defined in an external document. The selection of the appropriate data items depends on the specific requirements of the application.

Data items have defined sizes, which must be taken into account when constructing datasets. They also have a predefined direction, which limits the context in which they can be used (input, output, or both).

The following sections describe how to use the data items to create datasets and configure telegrams.

#### Defining datasets

First, datasets are constructed by choosing the appropriate data items, and ordering them by specifying their offsets in the dataset. Note that each data item has an intrinsic size, in bits, but the dataset is constructed as a series of bytes. Certain data items, smaller than one byte, can be packed into the available space within a byte, but all other items must start at the beginning of a byte.

Note

Gaps are allowed in the dataset. While the custom telegrams configuration does not enforce data alignment (other than what was described above), it is recommended to ensure that natural alignment is preserved, and to only place data items at offsets which are multiples of their sizes.

The following constraints apply when defining datasets:

- Each dataset must have a unique identifier.
- Up to 20 datasets may be defined in the dataset definition file.
- Each dataset may contain up to 1000 data items. This in effect also limits the number of data items in a telegram to 1000.
- The size of a dataset is limited to 1432 bytes. The size must be a multiple of 4 bytes.
- When adding data items that refer to device resources (e.g. ports or VLANs), the following limits apply:
- Data from up to 32 device ports can be included across all defined datasets.
- Data from up to 8 VLANs can be included across all defined datasets.
- Data from up to 4 FRNTv2 rings can be included across all defined datasets. FRNTv2 is the only ring protocol currently supported.

##### Creating a dataset definition file

The datasets are defined in the form of a JSON file. This file must conform to the provided JSON schema file, and must be uploaded to the WeOS device before it can be used.

The file must be named `custom-trdp-dataset.json` and placed in the `/cfg` directory on the device. The file can be edited and uploaded to the device using any available method, as long as it is placed in the correct location. See the uploading section below for more information.

The dataset definition file consists of a JSON objects, each representing a single variable, which in turn refers to a data item:

    {
        "type" : "...",
        "arg" : "...",
        "comment" : "...",
        "byte" : 0,
        "bit" : 0
    }

The `"type"` field must correspond to the name of one of the predefined data item types. The list of available items is fixed, and available in the WeOS distribution along with descriptions of their behaviour. The `"comment"` field can be used to provide additional context or information about the data item - this is ignored by the WeOS runtime.

The position of each data item within the dataset is determined by the `"byte"` and `"bit"` attributes. These attributes specify the exact location of the item within the dataset, allowing for precise control over the layout of the data. The `"bit"` attribute is only used for packing items smaller than one byte.

Finally, the `"arg"` field contains the argument(s) provided for the data item. Whether an item needs arguments, and what they represent, depends on the specific item. This information is also available in the data item master list, included with the WeOS distribution. Commonly, this field is used to further specify which specific resource the data item refers to. For instance, a data item that represents a statistical value (e.g. a packet counter) for a port might require the port name (e.g. “eth0”) as its argument.

Note that duplicates of the same data item may be used in the same dataset, often with different arguments. This can, for instance, be used to extract multiple statistics for different ports.

Each item also has a predefined direction (“in”, “out”, or “both”) that determines how it can be used. For most items, the direction is determined by the item’s semantics - it is, for instance, not reasonable to set the value of a packet counter on the device - while certain items may be used in both directions (e.g. an item that represents a CRC32 of the dataset it is contained in).

Once data items have been chosen and ordered, they are bundled together into dataset objects. A dataset object contains data items in the `"dataItems"` array, and has the following structure:

    {
        "id" : "...",
        "dir" : "...",
        "size" : 0,
        "aliases" : ["alias1", "alias2"],
        "dataItems" : [
            {
                "type" : "...",
                "arg" : "...",
                "comment" : "...",
                "byte" : 0,
                "bit" : 0
            },
            // ... more data items ...
        ]
    }

Note that a dataset object with an empty `"dataItems"` array is still considered valid. This can, for instance, be used to quickly construct “empty” datasets containing only zeros (by using the `"size"` attribute) for use in “empty” telegrams.

The `"id"` field is a unique identifier for the dataset, and must be specified. If several datasets are defined, they must each have a unique `"id"`. The identifier provided here will later be used to select a dataset for use in each configured telegram.

Note that the dataset object has a specified `"size"`, which must be equal to or larger than the sum of the sizes of its data items. This is to allow a gap (empty space) at the trailing end of the dataset, in which case the dataset size will be larger than the sum of the `"byte"` value, and the size, of the final item.

The `"dir"` field specifies the direction of the dataset, which can be either `"in"` or `"out"` (or even `"both"`, though the practical use for this is limited). This indicates whether the dataset is used for input or output purposes, and the value must be consistent with the direction of all individual data items contained within it. The following rules must be respected:

- If a dataset is marked as `"in"`, no contained data item may be of the type `"out"`.
- If a dataset is marked as `"out"`, no contained data item may be of the type `"in"`.
- If a dataset is marked as `"both"`, all contained data items must also be of the type `"both"`.

The `"aliases"` field specifies the alias keys, these can be used as placeholders in the arg field below to replace a string value. Instead of using the name of a vlan, example vlan1 one can use a key vlanA, and instead of a port ethX5 one might use the alias portA.

These aliases can then be configured in the cli to assign the value vlan1 to key vlanA and ethX5 to vlanA. This enable the usage of a generic dataset file, and unique configuration will be done in the cli for each device.

Datasets are then put in an array called `"datasets"`, which serves as the top-level object of the JSON file:

    {
        "datasets" : [
            {
                "id" : "dataset1",
                "dir" : "in",
                "size" : 10,
                "aliases" : ["portA"],
                "dataItems" : [
                    {
                        "type" : "...",
                        "arg" : "...",
                        "comment" : "...",
                        "byte" : 0,
                        "bit" : 0
                    },
                    // ... more data items in dataset1 ...
                ]
            },
            // ... more dataset objects ...
        ]
    }

##### Packing data items into bytes

Data items smaller than 8 bits in size are packed into the available space within a byte. This is done by using the `"bit"` attribute of the item when constructing the dataset. Gaps are allowed in the byte (similarly to how they are allowed between bytes).

Items with sizes less than one byte are not allowed to span byte boundaries. For instance, an item with size 4 bits must be placed at a bit offset of 0, 1, 2, or 3 in a byte.

Items which have a size of 8 or more bits must be placed starting at byte boundaries - in this case, the `"bit"` attribute is not used (it is implicitly 0).

Other than the above, sub-byte items are added to the dataset as usual.

Consider the following configuration excerpt:

    // ...
    {
        "type" : "portAggregated",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 0
    },
    {
        "type" : "portVlansAllTagged-C",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 1
    },
    {
        "type" : "portMulticastAware",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 2
    },
    {
        "type" : "portAutoNeg",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 3
    },
    {
        "type" : "portMdixStatus-C",
        "arg" : "0",
        "byte" : 24,
        "bit" : 4
    },
    {
        "type" : "portLinkState",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 6
    },
    {
        "type" : "portEnabled",
        "arg" : "ethX1",
        "byte" : 24,
        "bit" : 7
    },
    // ...

With the configuration above, byte 24 will look as follows, starting from the least significant bit:

- `portAggregated` (bit 0)
- `portVlanAllTagged-C` (bit 1)
- `portMulticastAware` (bit 2)
- `portAutoNeg` (bit 3)
- `portMdixStatus-C` (bit 4-5)
- `portLinkState` (bit 6)
- `portEnabled` (bit 7)

##### A note about data marshalling

When a dataset has been defined, it can be used as the payload of TRDP telegrams configured separately. Using the TRDP protocol, there are a few different ways that this can be done. TRDP includes a marshalling mechanism that allows the application to provide the TRDP layer with both the structure (in essence, type information), along with data, and then let the TRDP implementation take care of the details of formatting and transmitting said data, abstracting away such responsibilities from the application. This is termed marshalling and is intended to allow for TRDP to transmit data between different systems and implementations without each individual application needing to concern itself with the data representation details.

This functionality is not used in the current implementation. Instead, the implementation does the following: once the custom telegrams datasets have been prepared as described as above, and after the definition file has been uploaded to and validated by the device as discussed below, the implementation will use the `"size"` attribute of each dataset to create a static buffer of fixed length which will later be used as the payload for the corresponding telegram, bypassing any TRDP marshalling completely. As far as the TRDP layer is concerned, the telegram payload consists of one array of UINT8 values, the length of which is equal to the specified dataset size. This means that the data sent through the TRDP protocol is, for all intents and purposes, a raw byte stream. Any specific requirements such as data alignment, padding, etc. must therefore be included into the dataset definition from the beginning.

When the telegram is sent on the wire, the first byte of the TRDP PD-PDU payload (see IEC61375-2-3 Figure A.11) will contain the first byte of the custom telegram dataset.

Note

Since TRDP marshalling is not used, it is up to the application to ensure that the custom telegram dataset is correctly interpreted on the other end of the TRDP transmission. The WeOS device will transmit and receive all custom telegram payloads as TRDP arrays of UINT8s.

##### Uploading the dataset definition file to the device

Once the dataset definition file is created, it needs to be uploaded to the device. Currently, there are two methods for performing this task:

- Using the WeOS Web interface, by navigating to “`Configure / Routing / TCN`” and using the “Upload” button.
- By manually copying the file to `/cfg/custom-trdp-dataset.json`, on the filesystem (e.g. using the external USB storage) and then using the WeOS user interface to validate it (see the `trdp-validate` command below).

In either case, the file must be located at `/cfg/custom-trdp-dataset.json` on the WeOS device, and must be validated before it can be used by the system. Validation entails two steps:

1. Syntax validation: The WeOS system checks the file for any structural or syntax errors or inconsistencies. This is done by validating the file against the provided JSON schema.
2. Semantic validation: The WeOS system verifies that the dataset conforms to certain logical rules (e.g. that no two data items in any dataset overlap).

This step is performed automatically by WeOS. Using the Web interface to upload the file is recommended - if the external USB storage method is used, the file will be validated automatically at a later point. In either case, only validated files can be used for configuring telegrams.

#### Configuring telegrams

Once a dataset definition file has been successfully uploaded and validated, the next step is to configure the telegrams that will use this dataset. Telegram configuration is performed in the WeOS CLI. At least one telegram must be configured in order for the custom telegrams functionality to be enabled; however, datasets can be defined, and the dataset definition file can be validated, independently of the datasets being used in telegrams.

Configuring a telegram involves selecting exactly one from the previously defined datasets, and then supplying additional data as needed by the TRDP layer. Each telegram has a `direction` setting, which determines whether the telegram is incoming (received by the WeOS device) or outgoing (transmitted by the WeOS device). The available direction(s) depend on the selected dataset.

Once a direction has been set, the telegram can be further configured. Depending on the direction, either the destination IP address (for outgoing telegrams) or the listening IP address (for incoming telegrams) must be specified. The former determines the address that the telegram is sent to (which would, in nearly all cases, be a remote address) while the latter determines the address on which the device will be listening for the incoming telegrams. This must be a local address that is already owned by the device.

The following constraints apply when configuring telegrams:

- Each telegram must have a unique identifier.
- Up to 20 custom telegrams may be defined.
- The lowest periodicity for a telegram is 100 ms.
- The ComID of a telegram must be larger than 1000.

##### CLI configuration

The following CLI commands are available in the `ttdp` context, directly under the `config` context of the WeOS CLI. Note that this is the same context that is used for configuring IP-TCN. More information about the commands available in this context is available in the corresponding section of the documentation.

`show`

  List the current IP-TCN configuration, along with a list of the configured custom telegrams.

  Using `show custom-trdp` will show only the configured custom telegrams.

`[no] custom-trdp NAME`

  Enter a custom telegram configuration sub-context, or create a new one.

  NAME

    The identifier of an existing, or new, custom telegram object

    Note

    `NAME` must fulfil the following criteria:

    - Each name must be unique (it identifies the telegram)
    - Only upper- and lowercase letters and numbers are allowed
    - The name must not be empty, and the maximum allowed length is 31
  no
    Delete all configuration for the telegram `NAME`.
`[no] trdp-validate`

  Validate and verify the dataset definition data file (`/cfg/custom-trdp-dataset.json`).

  This command is used to manually request validation of the dataset file.

  Attempt to validate a preexisting dataset definition data file against the internal JSON schema and the additional semantic rules. If successful, calculate a SHA256 hash over the contents of the file, and optionally store this hash on the device for future verification by the custom telegrams implementation.

  Once the hash has been calculated, the user will be asked whether to store it.

  The custom telegrams feature will only be available if this validation is successful.

  If the hash is updated for a new file, the configured custom-trdp instances will be removed to ensure no faulty configuration persist.

  no
    Remove any stored SHA256 hash of the dataset definition data file. Remove all configured custom-trdp instances.

##### Telegram context CLI commands

Once inside the sub-context that corresponds to a specific telegram instance, the following commands become available:

`show`
  Show the current configuration of the custom telegram object.
`[no] enable`

  Enable or disable the custom telegram.

  This command can be used to enable or disable the current telegram, while retaining any configuration. Disabled telegrams are neither sent nor received.

  Note

  Disabling all telegrams effectively disables the custom telegrams feature.

`[no] dataset DSID`

  Link this telegram to a previously defined dataset.

  DSID
    The identifier (`"id"`) of an existing dataset object.
  no
    Remove the link to the dataset. This prevents further configuration of the telegram until a new dataset is linked.
`dir <in|out>`

  Set the direction of the telegram.

  in
    Set the direction to incoming. This makes the `listen-addr` setting mandatory and forbids the `dst-addr` setting.
  out
    Set the direction to outgoing. This makes the `dst-addr` setting mandatory and forbids the `listen-addr` setting.
`[no] comid NUM`

  Set the TRDP ComID for the telegram.

  NUM
    The TRDP ComID to assign to the telegram. This is an unsigned 32-bit integer in decimal format and must be larger than `1000`.
  no
    Remove the TRDP ComID assignment from the telegram. This is equivalent to setting it to `0`, which is an illegal value.
`[no] dst-addr ADDR`

  Set the destination address for the telegram (the address the telegram will be sent to).

  This setting is only relevant for outgoing telegrams.

  ADDR
    The destination address to assign to the telegram. This must be a valid IP address in the format `X.X.X.X`, where `X` is a decimal number between `0` and `255`.
  no
    Remove the destination address assignment from the telegram.
`[no] listen-addr ADDR`

  Set the listen address for the telegram (the local address on which to listen for the telegram).

  This setting is only relevant for incoming telegrams.

  ADDR
    The listen address to assign to the telegram. This must be a valid IP address in the format `X.X.X.X`, where `X` is a decimal number between `0` and `255`.
  no
    Remove the listen address assignment from the telegram.
`[no] period TIME`

  Set the periodicity for the telegram.

  This setting is only relevant for outgoing telegrams.

  TIME

    The periodicity in milliseconds. This determines the nominal value of the telegram’s transmission interval.

    Must be a value between 100 and 3600000.

  no
    Remove the periodicity assignment from the telegram.

  Note

  The real-world wall clock periodicity of the telegram may vary depending on network conditions and other factors.

`[no] timeout TIME`

  Set the timeout for the telegram. See below for details.

  This setting is only relevant for incoming telegrams.

  TIME

    The timeout in milliseconds. This determines the maximum time to wait for a response before considering the transmission failed.

    Must be a value between 100 and 3600000.

  no
    Remove the timeout assignment from the telegram. This is equivalent to setting the timeout to infinite (which disables it).

  Note

  It is recommended to set the timeout 3 times longer than the expected periodicity of the incoming telegram.

`[no] transmit <always|active-ecsp>`

  Set the transmission option of the telegram.

  always
    This setting makes the device to always send the custom telegram no matter if the device is an ECSP or not.
  active-ecsp
    This setting makes the device to only transmit the custom telegram when it is an active ECSP.
  no
    Sets the transmit option to always.

  Note

  The transmit setting is only available for outgoing custom telegrams when operational mode is set to `full`.

### Timeout behaviour of incoming telegrams

As shown above, every incoming telegram (with `dir` set to `in`) can have a timeout value configured. Currently, WeOS only uses this value to determine when (or whether) to write a message, indicating that the telegram has timed out, to the system log. If the timeout is disabled no such message will be written. Thus, in other words, not setting the timeout effectively means that the timeout is infinite.

Note that this functionality is not the same as the different timeout behaviour settings provided by TRDP and certain TRDP implementations. This is because the custom telegrams functionality in WeOS is always event driven and edge-triggered, meaning that incoming telegrams are consumed and processed if and when they are received. In other words, if a telegram is no longer being received, no action will be performed based on the data it contained.

### Using custom telegrams

Note

Configuring a large number of telegrams, or using low transmission periods, may impact system performance. It is important to monitor the system closely in such cases.

Once datasets and telegrams have been configured, and the configuration has been committed, transmission and reception of the telegrams is managed automatically. No further user action is required.

Certain incoming telegrams may contain data items that will change the WeOS state, and this state can then be monitored or queried by users using the normal WeOS mechanisms. This includes, for instance, the `date` command in the top level context of the WeOS CLI, which can be used to display the current date and time - a value which can in turn be set using the syncDateTime-C data item.

Outgoing telegrams can not be monitored on the WeOS device directly, with the exception of indirect means such as port packet transmission statistics. To monitor the outgoing data in greater detail, either software tools on the receiving device, or network monitoring equipment, must be used.

Note however that the TRDP layer conforms to the statistics layer described in IEC61375-2-3 Annex D. The interfaces specified therein can be used to extract statistics about the TRDP publishers and subscribers that have been set up on the device, which includes those set up by the custom telegrams function.

Some information, including a list of the configured telegrams, can be shown using the `show custom-trdp` command in the Admin context of the WeOS CLI.

« Previous Next »