WeOS
5.29.0

# TTDP (IEC 61375-2-5)

## Glossary

- CN - Consist Network
- ECN - Ethernet Consist Network
- ECSC - ETB Control Service Client 1
- ECSP - ETB Control Service Provider 1
- ETB - Ethernet Train Backbone
- ETBN - Ethernet Train Backbone Node
- TCMS - Train Control and Management System
- UUID - Universally Unique IDentifier 2
- TRDP - Train Real-Time Data Protocol

## Introduction

Train Topology Discovery Protocol (TTDP) is part of the IEC 61375 series of protocols.

In short, TTDP dynamically discovers the backbone routers (ETBNs) and consist networks (ECNs) in the train, and the way that they are connected. Furthermore, TTDP assigns IP addresses to the ETBNs and ECNs, and establishes routing and NAT entries in ETBNs based on these IP assignments. TTDP is designed to accomplish this as a distributed protocol running on the ETBNs.

## Overview

TTDP is managing train backbone inauguration (ETB inauguration) in train networks adopting the IEC 61375 train topology model. TTDP is a distributed protocol running on the train router nodes, here referred to as ETB nodes or simply ETBNs.

The TTDP protocol provides a wide range of services described in the sections below.

### Link Aggregation Control

TTDP acts as a link aggregation control protocol on the backbone network. Each ETBN sends a message, called TTDP HELLO, on each port on each aggregated link, i.e., aggregates `dir1` and `dir2`. This process gives both information of the MAC address of the neighbouring ETBN and control over which ports are available in the aggregate. The aggregates are setup as redundant communication links. All communication is done over one link until that link is not available any more, which is discovered by time outs on TTDP HELLO messages.

### Discovery of Train Topology

With TTDP, ETBNs will discover other ETBNs present on the backbone and exchange information. This TTDP signalling in turn allows each ETBN to gather information about:

- Consists: The identity of present consists (Consist Universally Unique Identifier, or simply `CstUUID`) and their order/position in the train backbone.

- ETBNs: The identity (ETBN MAC address) and order of the ETBNs on the backbone, and also the consist where each of the ETBNs reside. The ETBNs even learn the position of “missing” ETBNs (known, but currently down); this is true as long as at least one ETBN in each consist is up and running.

- ECNs: Every ETBN advertises information about the consist networks (ECNs) present in its consist. Thereby, each ETBN is able to gather information on all ETBNs and ECNs, and how they are interconnected.

Agreement on the network topology layout is accomplish in the following steps, each ETBN sends out a TTDP TOPOLOGY frame on a high priority VLAN, i.e., ID 492. The frame contains information of the IDs of the neighbouring ETBNs and the ETBN’s view of how all ETBNs in the backbone are connected. The frame also contains the ECN connections for the consist that the ETBN reside within. A CRC called `etbTopoCnt` is calculated, by each ETBN, over its correct view of the network. Once all nodes have the same view, i.e., the same `etbTopoCnt` value, the network can be inaugurated if inauguration is not inhibited.

### IP Address Assignment

TTDP is capable of assigning IP addresses dynamically based on the discovered topology. Addresses are allocated from a range defined in IEC 61375-2-5, and concern:

- ETBN addresses on the ETB subnet: An IP address is allocated to each ETBN on the ETB subnet.
- Train-wide IP subnet allocation for ECN subnets: ECNs typically make use of local (private) addresses in range 10.0.0.0/18. TTDP allocates a train-wide/18-subnet to each of the discovered ECNs.
- Virtual addresses on ETB subnet: In topologies where ECNs are connected to two or more ETBNs for redundancy, TTDP allocates a virtual IP address to be shared between the ETBNs on the ETB subnet. A virtual IP address is assigned for each ECN with redundant ETBNs.

It should be noted that the multicast DNS discovery service is not intended to be used on the ETB subnet, and WeOS will not send mDNS broadcasts from the ETB interface.

### External Interfaces

The canonical interface used for control, status, and diagnostics between the ETBNs and devices on the ECNs consists of the TRDP telegrams defined in IEC61375-2-3 Annex E.

          .---------------------------.
         /           CstUUID           \ cst1
         '-----------------------------'
            .-------.    .-------.
          --+       +----+       +--
      <-dir1| ETBN1 |    | ETBN2 |dir2->
          --+       +----+       +--
            '-+--+--'    '--+--+-'
              |  |          |  |
            --+----------------+-- CN1
                 |          |
              ---+----------+-------- CN2

Figure 1: A consist with two consist networks managed by two redundant ETB nodes.

## Usage Recommendations

### Configuration Boundaries

When configuring the ECNs connected to the ETBNs it is recommended that the ECN with ID 1 is connected to ETBN with `local-id` 1. Once all IDs for ECNs connected to the first ETBN has been assigned, the ECNs connected to the next ETBN can be assigned. The IDs must be in sequence without any gaps. The configuration of the consist topology is done though the `node` command. It is important that the `node` configuration is identical on all nodes within a consist. The information is shared in the TTDP TOPOLOGY frame and is used by other ETBNs to discover the topology and calculate the `etbTopoCnt` value.

The configuration of ECN ID to VLAN ID is done through `ecn`. In the consist shown in Figure 1, it is possible to connect different VLAN IDs to the same CN if the ports in the VLAN are untagged. The `ecn` setting is local information that is not shared in the TTDP TOPOLOGY frame.

The ports configured to be included in the aggregates `dir1` and `dir2` must be bypass ports. This requirement makes it possible to handle black car scenarios, i.e., that some ETBN do not have power and should instead acts as cables.

### Inauguration Inhibition

Inauguration must be inhibited on all ETBNs/ECSPs by means of ECSC_Control TRDP messages (or SNMP) once the train composition is in inaugurated state.

Even when TOPOLOGY frames received from other ETBNs indicate inauguration inhibition an ETBN can join once the correct `etbTopoCnt` has been calculated. A so called `NodeRecovery` can be made if either the ETBN is an intermediate node, which was previously a known node, that disappeared and is back again. Or, the ETBN is an intermediate node and wakes up late in a consist containing at least an already inaugurated ETBN.

With the command `recovery-mode` it is possible to change this behaviour to require a recovering ETBN to wait for ECSP_CTRL data from a specific multicast IP. This will make the node wait to join the ETB until inauguration inhibition has been lifted.

Nodes not having Inauguration Inhibition locally set can re-inaugurate as a new train composition, and become lost from the remainder of the train, in cases of ETB instability, malfunction or overload. This will lead to loss of connectivity between these nodes and the remainder of the train.

This gets indicated with a lengthening indication in the train with Inhibit still active and can be resolved by all nodes by removing Inhibition to allow the lost nodes back in again. Having Inauguration Inhibition set locally on every node prevents this from occurring.

#### Remote Inhibition

When using the “remote inhibition” functionality as mentioned in IEC61375-2-5:2014 section 8.7.6, there are different options available for how the value should be reported to the ECSC and other applications. The `inhibit-report-mode` command, described below, controls the semantics of the `etbInhibit` field in the ECSP_STATUS telegram, which can be used for this purpose.

### ETB Sink/Source Data Handling

All ETB data should be verified based on the current `etbTopoCnt` value to make sure no data from previous inauguration is sent or received by end devices.

When an inauguration occurs, all end devices shall disable ETB traffic until the ETBN again is in state inaugurated and a new `etbTopoCnt` value is available and stable. This is recommended even for traffic sent with a `etbTopoCnt` value of 0, intended for intra-consist communication.

### Multicast Streams

When setting up and sending/receiving multicast streams that is not TRDP related, it is highly recommended to not use TRDP ports 17224 and 17225, since the TRDP stack will attempt to parse data coming in through these ports, leading to reduced performance.

Additionally, it is highly recommended to not use the TRDP related multicast group 239.193.0.1, unless the traffic is meant for all ECSPs.

Also, please ensure that the train backbone can handle the loads of all multicast streams being sent/received from/to the consist networks.

## Configuration

TTDP can be activated from the top-level configuration context in the CLI.

    example:/#> configure
    example:/config/#> ttdp
    Activating TTDP with default settings.
    example:/config/ttdp/#>

Note

TTDP will be enabled by default when entering the configuration context.

For configuration examples, see

- Single consist net with one ETB node
- Single consist net with two redundant ETB nodes
- Two consist nets with two redundant ETB nodes
- Port settings for ETB backbone ports
- ECN-over-ETB with ECN subnetting

### Syntax

`[no] enable`

  Enable TTDP.

  Note

  Simply entering the TTDP config context will enable TTDP when leaving the TTDP context or config context.

  no

    Disable TTDP. The current configuration is saved, for when you re-enable the service again.

    Note

    The TTDP configuration can be completely removed from the config context using no ttdp.

`[no] operational-mode <full|etbn|off>`

  Select operational mode, either full, etbn, or off mode.

  In `full` mode, all ECSP and ETBN services are available. This includes the ETBN functionality as specified in IEC61375-2-5, used for ETB inauguration among other things, and the ECSP functionality as specified in IEC61375-2-3, which includes CSTINFO message exchange, TCN-DNS, TRDP services, and so on.

  In `etbn` mode, all functionality related to IEC61375-2-3, specifically the ECSP functionality, is turned off for this node. The node will not read the static consist information 1, take part in the exchange of CSTINFO messages, and so on. This applies regardless of any other settings related to the ECSP functionality described herein.

  In `off` mode, all ECSP and ETBN services are disabled. No other configuration options are available, with the exception of those that relate to the custom TRDP telegrams functionality.

  Note

  This setting is independent of the custom TRDP telegrams functionality, which is configured separately. That functionality remains available, regardless of which operational mode is selected. See the documentation section about custom TRDP telegrams for more information.

  Note

  Selecting `etbn` mode disables the TRDP interfaces specified in IEC61375-2-3 Annex E.

`[no] uuid <UUID-STRING>`

  Set the consist UUID. Each ETBN belonging to the same consist must use the exact same UUID, and no two consists may have the same UUIDs. Thus, the UUID is what defines individual consists.

  UUID-STRING

    One of the following:

    - A literal UUID string, in the RFC 4122 format. This is the preferred method of setting the consist UUID.

            etbn1:/config/ttdp/#> uuid 11111111-1111-1111-1111-111111111111

    - The string “auto-string”, followed by a seed string used to generate the UUID automatically. In this case, the seed string is used to generate the UUID using the algorithm in RFC 4122 chapter 4.3 (“Name-Based UUID”). Devices configured to use the same seed string will generate the same consist UUID.

            etbn1:/config/ttdp/#> uuid auto-string “uic948002343044”

    - The string “auto-mac”. In this case, the UUID is generated, using the same algorithm as above, based on the base MAC address of the device. Different devices will generate different UUIDs.

            etbn1:/config/ttdp/#> uuid auto-mac

  no
    Reset UUID to all zeros.
`[no] node ETBN_NB ecn ECN_ID[,ECN_ID]`

  Add ECN(s) to an ETBN to describe the consist topology.

  ETBN_NB
    The static relative position of an ETBN in the consist. Not to be confused with ETBN id which is assigned to the ETBN during inauguration and depends on the train composition. Valid range: 1-32.
  ECN_ID

    The consist net id. Valid range: 1-4.

    Note

    Limited to max 4 consist networks per consist.

  no
    Remove all ECNs from ETBN_NB. Syntax: no node ETBN_NB.
`[no] ecn ECN_ID IFΑCE <PREFIX_LEN>`

  Map ECN with ECN_ID to interface IFACE.

  ECN_ID

    ECN id. Valid range: 1-4.

    Note

    ECN_ID must fulfil the following criterias:

    1. Each CN must have a unique number
    2. There must be one and only one CN with the number 1
    3. There can be no gaps in the sequence of assigned numbers

    Note

    Limited to max 4 consist networks per consist.

  IFACE
    The interface used for the ECN_ID.
  PREFIX_LEN
    The prefix length of this ECN, if different to the address used by the ECN interface. When the ECN is locally split, this optional parameter must be specified (most often as 18) to specify the prefix length of the entire ECN, for TTDP R-NAT purposes.
  no

    Remove the ECN_ID’s interface mapping.

    Note

    This does not remove the Interface itself, just the mapping to the ECN.

`[no] dir1 PORT[,PORT]`

  Set ETBN backbone port(s) for direction 1.

  PORT

    The port(s) to be added to aggregate in direction 1.

    Note

    Limited to max 2 ports per direction.

  no
    Remove all ports from dir1’s aggregate.
`[no] dir2 PORT[,PORT]`

  Set ETBN backbone port(s) for direction 2.

  PORT

    The port(s) to be added to aggregate in direction 2.

    Note

    Limited to max 2 ports per direction.

  no
    Remove all ports from dir2’s aggregate.
`[no] local-id ETBN_NB`

  Set this ETBN’s static position within the consist.

  ETBN_NB

    The static relative position of an ETBN in the consist. Not to be confused with ETBN id which is assigned to the ETBN during inauguration and depends on the train composition. Valid range: 1-32.

    Note

    ETBN_NB must fulfil the following criterias:

    - Each node must have a unique number
    - There must be one node with the number 1
    - There can be no gaps in the sequence of assigned numbers
  no
    Set to 0.
`[no] backbone-id <ID>`

  Set backbone id to `ID`.

  ID

    Backbone id. Default: 0 (TCMS).

    Valid values:

    - `0` or `tcms` — Operational backbone (TCMS)

    - `1`, `multimedia` or `mm` — Multimedia backbone

    Note

    Backbone id 2 and 3 are not supported.

  no
    Reset to defalut 0 (TCMS)
`[no] backbone-iface <IFACE>`

  Set VLAN used for TTDP signalling on the ETB. Default: vlan2.

  IFACE

    Interface to be used on ETB.

    Note

    Ensure that IGMP snooping is disabled on IFACE.

  no
    Reset to default (vlan2).
`[no] ecsp-addr <IP-ADDRESS>`

  Local ECSP address. Should be set to a local address of the `ecsp-iface` interface, on which the CN-facing ECSP service runs.

  IP-ADDRESS
    Local ECSP address. Default 10.0.0.1.
  no
    Reset to default (10.0.0.1).

  This setting is only available if the operational mode is set to `full`.

`[no] ecsc-addr IP-ADDRESS`

  ECSC address. Telegrams to the local ECSC will be sent to this address.

  IP
    ECSC address. Default 10.0.0.99.
  no
    Reset to default (10.0.0.99).

  This setting is only available if the operational mode is set to `full`.

`[no] ecsp-leader-addr <IP-ADDRESS>`

  To enable sync of TTDB set this to the virtual IP address for the CN that governs ECSP Master/Backup mode.

  Note

  Only set this when using redundant ETBN’s in a consist. That is, when VRRP instance(s) for TTDP redundancy have been configured in this consist.

  IP-ADDRESS
    ECSP leader address. Default 0 (disabled)
  no
    Disable sync of TTDB between Master/Backup ECSP.

  This setting is only available if the operational mode is set to `full`.

`[no] ecsp-iface <IFACE>`

  Local ECSP interface. The CN-facing ECSP service will run on this interface.

  IFACE
    Local ECSP interface. Default: vlan1.
  no
    Reset to default (vlan1).
`[no] mroute group <MULTICAST_GROUP> out <NET_ID[,NET_ID]>`

  Configure custom IEC 61375 multicast routes.

  The specified MULTICAST_GROUP will be routed to NET_ID from every other connected ECN as well as from the local ETB.

  MULTICAST_GROUP
    Must be a valid multicast group (RFC2365) that is not within the reserved IEC61375-2-5 group range 239.192.0.0/24.
  NET_ID
    NET_ID can be a numeric ECN_ID or the special value “etb”, which maps to the ETB that the local ETBN is connected to. In this case the multicast group will be routed from all local CNs to the ETB.
  no
    Removes all configured multicast routes.

  Note

  This setting needs to be configured on all the potential source and receiver ETBNs.

`[no] recovery-mode <default|wait IP-ADDRESS>`

  Specifiy how to handle recovery of a lost node.

  wait <IP-ADDRESS>
    The IP-Address as listening address in wait/deferred mode
  no
    Reset to default recovery mode.

  Note

  In `wait` mode, the node will wait until it receives ECSP_CTRL data on the multicast address `IP-ADDRESS`, and positively reads that inhibition is not set from that data, before activating the bypass relays (i.e. joining the ETB) and starting to transmit TOPOLOGY frames. Thus, an ECSC must be up and running, signalling ECSP_CTRL inhibit off (0), before the node will function properly.

`[no] cn-bitmask-endianness <little|big>`

  Select CN bit mask endianness little (default) or big.

  no
    Reset to default CN bit mask endianness (little).

  Note

  This setting is only useful for interoperability.

`[no] dns-lookup-mode <local|global>`

  Set the (TCN-)DNS lookup preference mode to “local scope first” or “global scope always”.

  no
    Reset to default lookup order, i.e. Static Consist Info
  local
    Sets the lookup order to try the local scope before the global scope
  global
    Sets the lookup to always use the global scope

  This setting is only available if the operational mode is set to `full`.

`[no] etbn-ctrl-bypass`

  Enable (or disable) control of ETB bypass relays via the ETBN Control Interface (see IEC61375-2-3 Annex E)
  Disabled: the byPassCtrl field of the ETBN_CTRL telegram is ignored
  Enabled: the byPassCtrl field of the ETBN_CTRL telegram is used used for controlling the ETB bypass relays
  The semantics of the byPassCtrl field is specified in IEC61375-2-3 Annex E.

  no
    Disable control of ETB bypass relays via ETBN Control interface

  This setting is only available if the operational mode is set to `etbn` or `full`.

`[no] inhibit-report-mode <mode>`

  Choose how the etbInhibit field of the ECSP_STATUS telegram should be populated.

  The semantics of this field are specified in IEC61375-2-3 Annex E, though not very clearly. As an additional limitation of the service interface specified in Annex E, there is no way for the ECSC or any other ECN device to read the global “remote inhibition” flag. To resolve this, this configuration option makes it possible to alter the behaviour of the etbInhibit field in the periodic ECSP_STATUS telegram to allow it to be used for that purpose.

  The following options are available:

  0

    Default behaviour. As specified in IEC61375-2-3 Annex E

    - 0: n/a
    - 1: inhibit not requested on ETB
    - 2: inhibit set on local ETBN
    - 3: inhibit set on remote ETBN
    - 4: inhibit set on local and remote ETBN

    “Remote ETBN” only considers ETBNs in the local train composition. This is the default.

  1
    As mode 0, but “remote ETBN” now means “non-local ETBN in the local, or the remote, train composition”.
  2

    Bitfield mode. The etbInhibit field is now a bitmask containing the following bits:

    - 1: local ETBN
    - 2: remote ETBN in local train composition
    - 4: remote ETBN in remote train composition
  3
    As mode 0, but “ETBN” now means “train composition”.

  This setting is only available if the operational mode is set to `full`.

`[no] ecsp-inhibit-sync`

  Enable or Disable synchronisation of inauguration inhibition between redundant ETBNs (ECSPs).

  When Enabled, and this node is a backup ECSP (i.e. backup VRRP router) for the ECN with local CN ID 1, it will attempt to copy the local inauguration inhibition value from the master ECSP in the local consist. The master node will have had its local value set by the ECSC or some other external agent. This copying is performed by passively monitoring the TTDP TOPOLOGY frames from the local consist.

  After the value is copied, the backup ECSP will behave as if the value had been set locally on itself, until a ECSP masterhood change takes place. In case there are several backup ECSPs, all backups that have this setting enabled will copy the value from the master ECSP as described above.

  The purpose of this function is to allow for seamless master router/ECSP failover without losing the global inauguration inhibition state, in case it is only set in one consist. The function performs best if used on relatively simple consist ECN configurations, and will in certain more complex cases not work, if the local master ECSP cannot be unambiguously identified.

  When Disabled, no special action is taken when this node is a backup router/ECSP. The inauguration inhibition value will not be copied from the master ECSP.

  This setting is only available if the operational mode is set to `full`.

`[no] ecsp-ttdb-sync`

  Select the behaviour of the ECSP-SYNC function. This function lets backup ECSPs sync their internal -2-3 state with that of the master ECSP in the local consist. The following options are available:

  0
    Disable this function. Note that the backups will still sync from the master, in certain cases when this is required. Backups will not take part in the -2-3 inauguration process on the ETB and will transmit CSTINFOCTRL messages and fetch fetch CSTINFO for other consists as normal, over the ETB. This is the default.
  1
    Sync non-local consists only. The backups will only request CSTINFO for other consists from the local master ECSP. Backups will not transmit CSTINFOCTRL.
  2
    Sync all consists. Backups will request the entire TTDB from the local master.
  no
    Disable synchronisation of the TTDB between ECSPs (0).

  This setting is only available if the operational mode is set to `full`.

`[no] tcp`

  Enable/disable TCP support for certain TRDP telegrams.

  This setting affects the following telegrams:

  ComID | Name
  --- | ---
  102/103 | Train directory info
  104/105 | Static consist information
  106/107 | Train network directory
  108/109 | Operational train directory
  110/111 | Read complete TTDB
  122/123 | Confirm/correction
  140/141 | TCN DNS

  This setting is only available if the operational mode is set to `full`.

`[no] cst-mgrp-dnat`
  Enable or disable dynamic NAT for multicast groups.
`[no] ecn-over-etb VID[,VID...]`

  Enable or disable automatic forwarding of ECNs (and/or other VLANs) over the ETB.

  This setting is used to automatically forward selected VLANs over the ETB, and is useful for consists without dedicated ECN cabling. Note that such cabling may not be used in conjunction with this feature, unless measures are taken to avoid switching loops.

  The traffic is sent over the ETB cabling using VLAN tags, and not forwarded outside of the local consist.

  The VLANs are specified as a comma-separated list of VLAN IDs. Up to four VIDs can be specified.

  VID
    List of VLAN IDs to automatically forward over the ETB while respecting consist boundaries. Up to four VIDs can be specified.
  no
    Disable this function.
`[no] cstinfo-validate`

  Validate and verify the CSTINFO data file (`/cfg/cstinfo.json`).

  Attempt to validate a preexisting CSTINFO 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 upon (re)start of the IP-TCN stack.

  The results of the verification will be stored in the WeOS audit log. If syntactically and semantically correct, the CSTINFO data file will be used by the IP-TCN software regardless of the result of the hash verification.

  no
    Remove any stored SHA256 hash of the CSTINFO data file.
`[no] custom-trdp NAME`

  Enter or create a custom TRDP telegram context.

  This command is used to configure the custom TRDP telegram function. See the custom TRDP telegrams configuration section for more information.

`[no] trdp-validate`

  Validate the dataset used for the custom TRDP telegram function.

  This command is used to configure the custom TRDP telegram function. See the custom TRDP telegrams configuration section for more information.

`show`
  Show a summary of ttdp settings. This includes the relevant user-configurable parameters in this context, as well as the custom TRDP telegram configuration.

# Status

To see the current status of TTDP, run the `show ttdp` command in `Admin context`, like so:

    example:/#> show ttdp
    TTDP NODE
    backbone-id  : 0 (tcms)
    etbn-id      : 1
    etbn-ip      : 10.128.0.1
    local-id     : 1
    own-mac      : 0c:40:79:45:55:00
    uuid         : 11111111-1111-1111-1111-111111111111
    connTableCnt : 0x7af91a80
    EtbTopoCnt   : 0xec518201
    Inauguration : INAUGURATED
    Inhibition   : Self: Off,  Others: Off,  Train: Off

    CST-NET  IFACE     IP              CONNECTED ETBNs
       1     vlan1     10.0.0.1/21     1

    NODE ID      MAC ADDRESS            ORIENTATION
          1      0c:40:79:45:55:00      Direct
          2      0c:40:79:71:03:00      Direct

    CONSIST                               NODES   DIRECTION  NETWORKS
    11111111-1111-1111-1111-111111111111  1       Direct     10.128.64.0/18
    22222222-2222-2222-2222-222222222222  2       Direct     10.128.128.0/18

# Custom multicast routes

See a simple multicast example on how to configure custom multicast routes.

1. See communication profile ↩↩↩

2. See RFC 4122 ↩

« Previous Next »