On the communication component of the API

How to send messages to the railway track?

Implementing your own stack

Use find the protobuf definition of the Network messages that are used by the system. You should generate the Java / C++ / Python / etc. classes from those definitions and connect to the network via MQTT.

Using the services provided by the API

1. You should extend from the AbstractRailRoadCommunicationComponent (v1.1 API), or from the AbstractCommunicationComponent (v2.0 API).

2. In order to create a CommunicationStack (v1.1 API) use the CommunicationStackFactory (v1.1 API). In the v2.0 API you should use the MessagingService and the MessagingServiceFactory classes.

3. In the AbstractRailRoadCommunicationComponent (v1.1 API) or the AbstractCommunicationComponent (v2.0 API) you should find a field called locator, which has a TrackCommunicationServiceLocator v1.1, v2.0. You should use its fields, if you would like to:

   • send commands to the network (set segment’s enabledness, set turnout’s direction, set train’s speed)

   • get status information about various elements (segment’s occupancy, segment’s enabledness, turnout’s direction)

   • register your listener for a particular message

How to use the TrackCommunicationServiceLocator?

• Should you use the v2.0 API, you can find example classes, in the sample project, which explain how you can send commands and retrieve status information. These examples can be used in the v1.1 API in a similar way though.

• The main difference between v1.1 and v2.0 versions of the *Locator is, in the latter version there are separate commanders for Train annd DCC commands, while in the first version they are included in the TrackElementCommander.

Fields of the TrackCommunicationServiceLocator v1.1:

Fields of the TrackCommunicationServiceLocator v2.0:

What is the difference between: IMessageHandler<T>, I*[Command/State]Listener interfaces, *Client, *Callback, *StateRegistry, *Commander classes in the communication component?

IMessageHandler<T>

This interface has declares a handleMessage(T message) method that should handle the arrival of a message. Usually it disassembles the field of a message

I*[Command/State]Listener

This interface declares a on*[Command/State](..) method which has several arguments, depending upon what message’s arrival should trigger this method to be invoked. The arguments should be the disassembled fields of the message.

I*StateChangeListener

This interface declares a on*StateChanged(..) method which has several arguments, depending upon what status change should trigger it. E.g. if a segment’s occupancy has been changed, then the segmentId, the old occupancy (occupied/free) and the new occupancy will be the arguments of this method.

*Client

This class usually implements the IMessageHandler<T> interface, and has a *Callback field to which it forwards the disassembled message.

*Callback

This class has a constructor which expects a ProtobufMessageDispatcher (v1.1 API) or an AbstractMessageDispatcher (v2.0 API), and it implicitly creates a *Client and registers it as a MessageHandler in the dispatcher. So that if a particuar message arrives, this callback can be invoked.

What is more, it implements the I*CommandListener interface, so it can register listeners which will be invoked upon a particular message arrives. The user can register its message handler, if it should be notified about a particular message’s arrival.

*StateRegistry

This class is only implemented in case of a message which reports status info (see Network messages page for more info).

In its constructor it expects a ProtobufMessageDispatcher (v1.1 API) or an AbstractMessageDispatcher (v2.0 API), and it implicitly creates a *Callback and registers listeners inside the callback so that whenever a particular status message arrives, they will be invoked. In the listeners it usually stores each status message if it is different from the previous one. E.g. if a section’s status has changed, then it updates its status in a data structure.

What’s more, it offers a I*ChangeListener interface to be invoked, so whenever a status changes, the listener can be notified about it.

Moreover, each status can be queried by a getter method, based on the message for which this *StateRegistry was instantiated.

*Commander

This class is implemented in order to send particular commands. It requires a MessagingService both in v1.1 and v2.0 API. It usually implements those interfaces which correspond to what commands we want to send. The arguments of these interfaces should have the fields of the message that should be sent by the commander. The commander creates the message itself and forwards it to the MessagingService.

Example

If we want to receive DccOperationsStateMessage message, we should add a new IMessageHandler<DccOperationsStateMessage> field to the ProtobufMessageDispatcher (v1.1) or the AbstractMessageDispatcher (v2.0). Then, we should implement the DccStateClient class that disassembles the fields of the state message and invokes the onDccOperationsState method of the DccStateCallback field. After that we should implement the DccStateCallback which can register the message handler in the dispatcher and invoke our listener whenever a disassembled message arrives. Finally, we can implement the ˙DccStateRegistry` in order to track the changes of the status and send change notifications if we need them.

You can find the implementation of these classes in the hu.bme.mit.inf.modes3.messaging.communication.state.dcc package of the hu.bme.mit.inf.modes3.messaging.communication project on the refactoring (v2.0 API) branch.

What does an IMessageDispatcher do?

The interface declares two methods for conversions between the serialized and the deserialized representations of a message. By serialized representation we mean the representation that is forwarded on the network, and by deserialized repsentation we mean the representation that is used in the particular component.

1. In the v1.1 API, the serialization (internal to network format) is done by the ProtobufMessageDispatcher class, while the deserialization is done by the particular *Client classes.

2. This concept is changed in the v2.0 API. There is a new, abstract dispatcher which only defines what messages it will handle, but it is not directly responsible for the translation. Instead, it can delegate this task to other classes and only get the necessarry representations from them. E.g. the ProtobufMessageDispatcher (v2.0) has two fields. One for the internal to protobuf conversion (InternalToProtobufConverter) and one for the other way around (ProtobufToInternalConverter). In this way the dispatcher is only responsible for invoking the particular message handlers and the conversion is done by dedicated classes. What’s more the *Client classes will be responsible only for disassembling the internal message and they do not have to deserialize them anymore.