OTA / MQTT messages used and produced by RuterSalg [3.3]
- Monika Zidonyte
- Frode Nilsen
- marius.waldal
Ingen endring fra 3.2
High-level view of communication
RuterSalg both consumes and produces MQTT messages on the local MQTT broker in the vehicle. The schemas are documented externally for ADT 2.x and ADT 3.x, but we will here describe which topics RuterSalg consume, and how they are utilized, and which topics we produce.
Â
ADT 3.3
Consumed:
Local Topic | Data | Direction | Link | Description |
|---|---|---|---|---|
operational/assignment/attempt/request |  | OUT | signOff → code: FINISHED | |
pe/sales/current_stop | A variety of data needed by the RuterSalg app | IN | With ADT 3, the RuterSalg backend starts producing a topic sent to the vehicle, containing a variety of data that is used by the app, like the current stop and zone, NEXT stop and zone, lineId and chainId. RuterSalg uses this topic from version 2.6 | |
pe/vehicle/api | ADT-version, VIN | IN | Â |
Produced:
Local topic | Remote topic | Link | Description |
|---|---|---|---|
pe/sales/diagnostics | ruter/<sender>/<vehicleRef>/adt/v3/pe/sales/diagnostics | Primary use: This topic is intended for health status for the RuterSalg application on each vehicle. The health status is intended both as a real time surveillance of health status for each individual bus as well as aggregating data per operator to see larger, more general issues. The topic can also, when enriched with other data, determine whether or not RuterSalg was used and working on a specific departure. Failure to have a working sales setup during a journey constitutes an SLA breach. Possible secondary use: This topic may also be used by the operators to quickly discover issues with their own devices, as well as getting a general fleet-wide status if aggregated. | |
pe/sales/sla | ruter/<sender>/<vehicleRef>/adt/v3/pe/sales/sla | New topic in ADT 3.3. Up until 3.3 we have been using the loggedIn field in the diagnostics message to measure whether the driver has logged onto the TETSalg app, but having an internal MQTT topic as basis for SLA measurements is not ideal. We have therefore created a new external message which will follow normal ADT versioning and restrictions as the basis for measurements. The loggedIn field will still exist in the diagnostics messages, but will no longer be used for SLA measurement. |
ADT 2.x
(Deprecated and will be removed from ADT v4)
Consumed:
Local Topic | Data | Direction | Link | Description |
|---|---|---|---|---|
di/assignment_attempt/block | VIN | OUT | assignmentType: SIGNON assignmentType: SIGNOFF | |
pe/dpi/nextstop | Next stop ID (NeTeX) | IN | Some time after leaving a stop, the vehicle receives a NextStop message. The message contains the field stopPlaceId which contains a NeTeX ID for the stop the vehicle is now approaching. RuterSalg uses this ID to lookup the corresponding tariffZone to set as the current zone in the app. This has been replaced by oi/current_vehicle_journey/expected_call (see below). No longer needed. | |
pe/dpi/journey | sorted list of next stops (stopPlaceId) | IN | List of stop places: journeyRef: | |
oi/current_vehicle_journey/expected_call | Next quay | IN | In early 2022 we were told that the nextstop topic would be deprecated and that the data we needed would be available in expected_call. We changed RuterSalg to first handle both nextstop and expected_call, and later to no longer consume nextstop. This now has the same function as nextstop did before. | |
pe/vehicle/api | ADT-version | IN | The sales app uses this topic to determine which ADT version the vehicle uses. |
Produced:
Local topic | Remote topic | Link | Description |
|---|---|---|---|
pe/sales/diagnostics | ruter/<sender>/<vehicleRef>/pe/sales/diagnostics | Primary use: This topic is intended for health status for the RuterSalg application on each vehicle. The health status is intended both as a real time surveillance of health status for each individual bus as well as aggregating data per operator to see larger, more general issues. The topic can also, when enriched with other data, determine whether or not RuterSalg was used and working on a specific departure. Failure to have a working sales setup during a journey constitutes an SLA breach. Possible secondary use: This topic may also be used by the operators to quickly discover issues with their own devices, as well as getting a general fleet-wide status if aggregated. | |
pe/sales/saleresult | ruter/<sender>/<vehicleRef>/pe/sales/saleresult | No longer in use by Ruter | |
pe/sales/validationresult | ruter/<sender>/<vehicleRef>/pe/sales/validationresult | No longer in use by Ruter |
Diagnostics message behaviour details
Change based dispatching
The diagnostics message is from v2.9 of Ruter/AKT/Brakar/ØKTSalg dispatched only when the content changes, as opposed to previous versions where the diagnostics message was dispatched every minute regardless of state. This means that as soon as any of the metrics of the message body changes, a new message will be dispatched. Detailes of the contents and behaviour is described below.
Triggers
There are 7 different events in the system that may cause a new Diagnostics message to be dispatched. These are called "triggers" and the value of the field "context.trigger" denotes the reason. This section explains them in detail:
Startup
This trigger is simply the application doing a cold startup. Usually after a reboot, but can also be after the operating system has put the app to "sleep" by killing the process and some user action now restarts the process. Read more about app lifecycles on the official Android documentation pages.
The system may or may not have established a connection to the printer or terminal and internet at this time. If the connection to any peripherals change after tha Startup-triggered message, a new message will be dispatched with updated status.
LoginStatusChanged
This trigger indicates the user has either logged in or out. The metrics fields of the diagnostics message will contain the updated user identificators.
StopPlace
Happens when the bus or boat closes into the next stop place. On ADT3 this is a consequence of the system receiving a message on the pe/sales/current_stop topic. The fields "context.tarriffZone" and "context.stopPlaceId" will be updated.
PrinterStatusChanged
Triggers as soon as the system becomes aware of a changed connection status to a printer or terminal. How fast this happens after the actual connection status change vary greatly between the different hardware and connection types. As a rule of thumb all USB-connected devices will report connection loss/regain immediately while bluetooth and ethernet connections will have a delay. For a full overview see chapter "Printer and terminal connection change detection" below.
NfcStatusChanged
Happens when we detect change in connection status to an NFC device. There are two external types of conncetion and one internal, denoted by "metrics.nfcStatus.interfaceType" in ADT3:
integrated:Â The onboard NFC hardware found on many Android devices, in particular off-the-shelf handheld phones and tablets. This may be turned on and off through system menus and this will trigger a "NfcStatusChanged" diagnostics dispatch if this is the only NFC hardware present.
usb: denotes a USB-connected NFC reader/writer, typically ACR1252U. This connection type has higher priority than "integrated" so the type will be "usb" if both a "usb" and "integrated" connection is present. When the cable is disconnected or connected, and we are successfully able to identify the hardware type when connected, a "NfcStatusChanged" diagnostics dispatch will happen.
mqtt: denotes a MQTT-connected NFC reader/writer has reported to be present or absent over an agreed upon MQTT topic not part of the ADT specification. This connection type has the highest priority.Â
InternetConnectionStatusChanged
Triggered when the Android Operating System reports to us that we have lost or reestablished connection to internet. This includes 3G/4G telecom connections as well as WiFi connections. It does not matter if we have a full route to internet or not. The system will report "connected: true" as long as we have a connection to any router, regardless of the route configuration from that point onwards.Â
Of course the system needs connection with the MQTT broker to actually be able to dispatch the message. If the internet connection goes down, the system buffers up to 100 diagnostics messages before discarding the oldest ones. As soon as the connection comes back up, all buffered messages are sent. The timestamp of the event denotes the time of the event, not the time of dispatching.
Example of flow
The illustration below describes how four different events triggers dispatching -
Startup once, PrinterStatusChanged twice and finally a StopPlace:
Printer and terminal connection change detection
To be able to actively report on the connection status to a printer or terminal we are dependent on the hardware and software vendors providing us with means to do so. This varies greatly between the devices we integrate with. We have investigated to which level of urgency we are able to determine a change in device connection into three categories:
Immediately:Â The device will instantly report a change in connection to us
Poll:Â The device will not report a change in connection and the sales system needs to actively poll to detect a change in the state.
None:Â The device cannot report connection state or the connection state is irrellevant
When we need to poll, we poll every 60 seconds.
Some devices also differ in urgency when it comes to state change from conneted to disconnected and vice versa. The table below describes the behaviour of each device:
Device | Connection | When disconnecting | When connecting |
|---|---|---|---|
Epson TM-m30 | Ethernet | Poll | Poll |
Epson TM-T20III | Ethernet | Poll | Poll |
Bixolon SPP-R200III | USB | Event | Event |
Star 230i USB mode | USB | Event | Event |
Star 230i BT mode | Bluetooth | Poll | Poll |
Star mC-Print3 BT | Bluetooth | Poll | Poll |
Verifone v400c (1) | Ethernet TCP/IP | Event | Poll |
Verifonev 400m (1) | Bluetooth TCP/IPÂ | None | None |
Softpay | Integrated | N/A | N/A |
(1) When it comes to the Verifone terminal what matters is actually not the device model but how they are configured. For our sales system we enforce "ECR Connection Mode" for v400m, which makes the conection detection unusable due to the deep sleep functionality activating in this mode. For v400c in "Terminal Connection Mode" this is not a problem and we can poll for connection status.