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.

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 behavior. 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,
    "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".

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,
            "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" : "portAllVlansTagged",
    "arg" : "ethX1",
    "byte" : 24,
    "bit" : 1
},
{
    "type" : "portFlooding",
    "arg" : "ethX1",
    "byte" : 24,
    "bit" : 2
},
{
    "type" : "portAutoNeg",
    "arg" : "ethX1",
    "byte" : 24,
    "bit" : 3
},
{
    "type" : "value2",
    "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:

• One zero bit (padding), always set to 0. (bit 0)
• portAllVlansTagged (bit 1)
• portFlooding (bit 2)
• portAutoNeg (bit 3)
• One zero bit (the first bit of the static value2), always set to 0. (bit 4)
• One zero bit (the second bit of the static value2), always set to 0. (bit 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.

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.

Custom telegrams CLI commands

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 fulfill 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.

no

Remove any stored SHA256 hash of the dataset definition data file.

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.

Timeout behavior 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 behavior 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

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.