On the communication component of the API
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.
-
You should extend from the AbstractRailRoadCommunicationComponent (v1.1 API), or from the AbstractCommunicationComponent (v2.0 API).
-
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.
-
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
-
-
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?
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
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.
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.
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.
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