Avtale om digitale tjenester - ADT 1.x

Ruters digitale plattform

This specification contains interfaces to be used between PTOs (operators) and Ruter. The API describes a set of MQTT topics which are used to distribute data onboard public transport vehicles/vessels as well as between the vehicle/vessel and Ruter’s Back Office or vv.

General information

Upgrades to the API

The API follows the upgrade cycles of ADT. Major releases are done more or less once a year and usually include breaking changes.

Minor/build releases are performed as continual deliveries and are non-breaking. New versions of this document will be published when new topics and/or fields are added.

Consumer Client Requirements

Clients consuming information posted on the topics must be tolerant to:

  • That optional properties can be null or left out.
  • That arrays can contain any number of elements including zero.
  • That returned data can be extended with new properties without notice.

Quality of Service, Retained Flag and Persistence

Generally, QoS level 1 is applied for most topics and the retain flag is true for most topics. See the respective topic for precise info.

Subscribers should start with Clean Session set to True to assure that they get the latest information at reconnection (the retained info) and avoid first having to process a long queue of outdated old information that in reality hinders new relevant information to reach the subscriber.

Translation of topic names

Global topic names are generally written on the format of {recipient}/{sender}/{vehicleid}/{topic} to make it easy to identify the source and destination of the messages. Local topic names have omitted the {recipient}/{sender}/{vehicleid} part in order to have onboard equipment pre-configured with vehicle independent settings.

All topic names must thus be rewritten local/global in the MQTT bridge according to a provided configuration file.

Data format

All data must be JSON and UTF-8 encoded.

Overview

The diagram below shows an overview of the most important messages that manage the assignment and journey of a vehicle.

Overview of important messages

  1. The vehicle signs on
  2. Ruter sends a textual message with the status of the signon to the vehicle
  3. Based on the location of the vehicle, Ruter calculates which journey in the assignment the vehicle is on, which stop it is going to next, etc.
  4. If the position matches a journey in the assignmment, Ruter sends a journey message to the vehicle,
  5. ...and Ruter changes external display

Comments or suggestions

Please open an issue here: ADT-DOC Issues

Servers

  • mqtt.transhub.iomqttmqtt.transhub.io

    Ruters central MQTT broker

    port
    required
    string

    The mqtt broker is available through TCP (:8883) and Websockets (:9883)

    Default value:"8883"
      Allowed values:
    • "8883"
    • "9883"
    Security:

Operations

  • PUB signon/json

    Signon Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/signon/json
    Schema signon.json
    Notify PTA BO that the bus is starting a block.

    Accepts the following message:

    Signon Message
    object
    uid: http://schema.ruter.no/signon.json

    Notification to PTA BO that a block is being started or resumed, or completed

    Examples

  • PUB signoff/json

    signoff Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/signoff/json
    Schema signon.json
    Notify PTA BO that the bus has completed a block.

    The content of signoff is the same as signon and uses the same schema.

    Accepts the following message:

    Signoff Message
    object
    uid: http://schema.ruter.no/signon.json

    Notification to PTA BO that a block is being started or resumed, or completed

    Examples

  • PUB avl/json

    AVL Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/avl/json
    Schema avl.json

    Automatic Vehicle Location. Reporting of the buss position, course and speed to PTA BO.

    Accepts the following message:

    AVL MQTT Message
    object
    uid: http://schema.ruter.no/avl.json

    Automatic Vehicle Location

    Examples

  • PUB telemetry/{telemetryId}/json

    Telemetry data

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/telemetry/{telemetryId}/json
    Schema avl.json

    Vehicle telemetry from systems on the bus.

    Several different kinds of telemetry are available varying by vehicle type. For traditional busses, FMS is the standard defines what data about the vehicle is published on the FMS bus and out by FMStoIP. For trams VehicleToIP defines a a different and more limited set of data. In addition, electrical and hydrogen have proprietary data that is not captured by either.

    This topic generalizes all such data as telemetry defined by a unique id. We will use FMS PGN ids (4-digit hex values) but otherwise use unique ids to identify data from other sources.

    If we define the ids along the lines of FMS we can have 32-bit ids that use the following pattern:

    Bytes Description
    1 Source identifier
    2-4 Source-specific id, e.g. FMS PGNs

    Source identifiers will be:

    Id Description
    0x00 FMS
    0x01 non-FMS
    ... new sources

    Therefore all FMS PGNs become "0000" + 4-digit hex PGN.

    Learn more about the telemetry concept in this wiki article.

    FMS

    Each of the available data points is defined with a Parameter Group Number (PGN) with fields defined by Suspect Parameter Number (SPN).

    The FMS-to-IP service in the ITxPT standard makes the desired data available on the bus's own network over UDP (multicast broadcast). It sends out only the PGNs previously requested by calling a service. The messages are sent every second, according to ITxPT, and includes all the requested PGNs. The format is in XML.

    We therefore define which PGNs are needed by Ruter and that the XML message should be broken up per PGN and forwarded as JSON.

    FMS Parameter Group Number (PGN)

    This is the list of required PGNs. It should be possible to expand this over time.

    Code Description PGN SPN Purpose ID Local topic
    DC1 Door Control 1 FE4E 3411 Status 2 of doors
    1820 Ramp/Wheel chairlift
    1821 Position of doors    		 Doors open / closed 0000FE4E telemetry/0000fe4e/json
    DC2 Door Control 2 FDA5 XXXX Lock Status Door N
    XXXX Enable Status Door N
    XXXX Open Status Door N    		 Alternative to DC1? 0000FDA5 telemetry/0000fda5/json
    VDHR High Resolution Vehicle Distance FEC1 917 High resolution total vehicle distance Supplements position 0000FEC1 telemetry/0000fec1/json
    telemetryId
    required
    string
    uid: telemetryId

    The telemetry / sensor ID.

    Accepts the following message:

    FMS-to-IP data
    object
    uid: http://schema.ruter.no/fmstoip.json

    Translation of FMS data to MQTT messages

    Examples

  • PUB apc/{sensorId}/json

    APC Sensors Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/apc/{sensorId}/json
    Schema apc-sensors.json
    sensorId
    required
    string
    uid: sensorId

    The sensor ID.

    Accepts the following message:

    Automatic passenger counter data
    object
    uid: http://schema.ruter.no/apc.json

    Automatic Passaneger Count

    Examples

  • PUB sensors/activecab/json

    Active Cab message:

    Field Value
    Central Topic -
    Schema active-cab.json

    Accepts the following message:

    ActiveCab Message
    object
    uid: https://schemas.ruter.no/adt/ota/api/v2.1/proprietary-extensions/active-cab.json

    Used to keep track of what direction the train is driving

    Examples

  • PUB sensors/door

    Door Sensor MQTT Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/sensors/door
    Schema door.json

    Accepts the following message:

    Door Sensors Message
    object
    uid: https://schemas.ruter.no/adt/ota/api/v2.1/sensor/door.json

    Describes if any door is open (or to be more precise – if the door lock is released). Also see topic pe/doors_individually for status on individual doors.

      Examples values:
    • {"doorOpen":true,"atDateTime":"2021-11-30T23:45:52.006Z"}

    Examples

  • PUB sensors/doorlock/json

    Door Lock message:

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/sensors/doorlock/json
    Schema door-lock.json

    This message is used to track if the vehicle doors are locked or unlocked.

    Accepts the following message:

    Doorlock Sensors Message
    object
    uid: https://schemas.ruter.no/adt/ota/api/v2.1/proprietary-extensions/door-lock.json

    Door lock event

      Examples values:
    • {"eventTimestamp":"2020-10-31T08:38:02.749Z","locked":false}

    Examples

  • PUB stopsignal/json

    Stop signal status:

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/stopsignal/json
    Schema stopsignal.json

    This message should be produced whenever the stop signal is turned on or off.

    Accepts the following message:

    Stop signalled MQTT Message
    object
    uid: http://schema.ruter.no/stopsignal.json

    Notification that passengers have requested a stop

    Examples

  • PUB pe/dpi/ack

    DPI Ack Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v1/pe/dpi/ack
    Schema dpi-acknowledge.json
    Producer PTO, Ruter DPI
    Consumer Ruter DPI

    The DPI Ack topic is used to inform the Ruter BO about the correct transfer and interpretation of messages to the vehicle.

    Ruter shall receive an acknowledgment message for the following topics:

    Topic Responsible for producing ack
    External display messages PTO
    Audio messages PTO
    Journey messages DPI application
    NextStop messages DPI application

    Notice! Due to late introduction of this topic, no messages are to be expected by PTOs on this version of ADT api.

    The ack message should be produced as soon as the message is received and validated. This is a confirmation that the system on board the vehicle have received the data and is capable of acting on it.

    No confirmation message should be returned if the system is unable to playback the content. (e.g. invalid message format)

    Accepts the following message:

    DpiAcknowledge
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/ack/dpi-acknowledge.json

    The DPI Ack topic.

    Examples

  • PUB pe/dpi_diagnostics

    DPI Diagnostics message:

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/pe/dpi_diagnostics
    Schema dpi-diagnostics.json

    Report to PTA BO about a screen.

    The DPI application itself produces diagnostic messages. The payload is defined as an object with no pre-defined structure to provide flexibility.

    Accepts the following message:

    DPI Diagnostics message
    object
    uid: http://example.com/root.json

    Examples

  • PUB pe/sales/diagnostics

    RuterSalg diagnostics

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/pe/sales/diagnostics
    Schema salediagnostics.json

    Diagnostics message generated by RuterSalg. More details about fields can be found at https://ruter.atlassian.net/wiki/spaces/TAAS/pages/948928517/OTA+MQTT-Meldinger+benyttet+av+Ruter+Salg.

    This topic is intended for applications interested in health status for the RuterSalg application on each bus. The health status is intended both as a real time surveillance of health status for each individual bus as well as for aggregating data per operator to see larger, more general issues. The topic can also, when enriched by other data, determine whether or not RuterSalg was used and working on a specific departure.

    Accepts the following message:

    RuterSalg Diagnostics MQTT Message
    object
    uid: http://schema.ruter.no/salediagnostics.json

    Examples

  • PUB pe/sales/saleresult

    Saleresult Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/pe/sales/diagnostics
    Schema saleresult.json

    Sale result message generated by RuterSalg. More details about fields can be found at https://ruterwiki.ruter.no/display/PNS/MQTT+Topics+consumed+and+produced+by+RuterSalg.

    This topic is intended as a live view of sales, and must not be used as the complete truth. This is done elsewhere. This topic is intended for health surveillance, for anyone interesting in whether or not tickets are being sold, and also how many and what kind of tickets.

    Some operators have suggested that they might be interested in using this topic to display sales results on screens separate from the RuterSalg application, intended as information to the travelers purchasing tickets. This topic is well suited for this use case.

    Accepts the following message:

    Saleresult MQTT Message
    object
    uid: http://schema.ruter.no/saleresult.json

    Result of sale made with the RuterSalg application

    Examples

  • PUB pe/sales/validationresult

    Validationresult Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/pe/sales/validationresult
    Schema validationresult.json

    Validation result message generated by RuterSalg. This topic is intended as a live view of validation. This topic is intended for health surveillance, for anyone interesting in whether or not validations are being performed, as well as validation results.

    Accepts the following message:

    Validationresult MQTT Message
    object
    uid: http://schema.ruter.no/validationresult.json

    Result of validation made with the RuterSalg application

    Examples

  • PUB infohub/dpi/emergency/json

    Infohub Emergency message:

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/infohub/dpi/emergency/json
    Schema dpi-emergency.json

    Topic used to trigger the displays to show the emergency message instead of the regular passenger information.

    ⚠️ Notice! The MADT is to send this message every X sec while the emergency is in progress. This is to make sure the message reaches all the displays in case of package loss on the network.

    Accepts the following message:

    DPI Emergency message
    object
    uid: http://example.com/root.json

    Examples

  • PUB infohub/dpi/diagnostics/json

    Infohub DPI Diagnostics message:

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/infohub/dpi/diagnostics/json
    Schema dpi-diagnostics.json

    Report to PTA BO about a screen.

    The DPI application itself produces diagnostic messages. The payload is defined as an object with no pre-defined structure to provide flexibility.

    ⚠️ Deprecated! Will be removed in a later release.

    Accepts the following message:

    DPI Diagnostics message
    object
    uid: http://example.com/root.json
    • #Deprecated

    Examples

  • PUB infohub/sales/diagnostics/json

    RuterSalg diagnostics

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/sales/diagnostics/json
    Schema salediagnostics.json

    Diagnostics message generated by RuterSalg. More details about fields can be found at https://ruter.atlassian.net/wiki/spaces/TAAS/pages/948928517/OTA+MQTT-Meldinger+benyttet+av+Ruter+Salg.

    This topic is intended for applications interested in health status for the RuterSalg application on each bus. The health status is intended both as a real time surveillance of health status for each individual bus as well as for aggregating data per operator to see larger, more general issues. The topic can also, when enriched by other data, determine whether or not RuterSalg was used and working on a specific departure.

    ⚠️ Deprecated! Will be removed in a later release. Use pe/sales/diagnostics instead.

    Accepts the following message:

    RuterSalg Diagnostics MQTT Message
    object
    uid: http://schema.ruter.no/salediagnostics.json
    • #Deprecated

    Examples

  • PUB infohub/sales/saleresult/json

    Saleresult Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/sales/saleresult/json
    Schema saleresult.json

    Sale result message generated by RuterSalg. More details about fields can be found at https://ruterwiki.ruter.no/display/PNS/MQTT+Topics+consumed+and+produced+by+RuterSalg.

    This topic is intended as a live view of sales, and must not be used as the complete truth. This is done elsewhere. This topic is intended for health surveillance, for anyone interesting in whether or not tickets are being sold, and also how many and what kind of tickets.

    Some operators have suggested that they might be interested in using this topic to display sales results on screens separate from the RuterSalg application, intended as information to the travelers purchasing tickets. This topic is well suited for this use case.

    ⚠️ Deprecated! Will be removed in a later release. Use pe/sales/saleresult instead.

    Accepts the following message:

    Saleresult MQTT Message
    object
    uid: http://schema.ruter.no/saleresult.json

    Result of sale made with the RuterSalg application

    • #Deprecated

    Examples

  • PUB infohub/sales/validationresult/json

    Validationresult Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/itxpt/ota/sales/validationresult/json
    Schema validationresult.json

    Validation result message generated by RuterSalg. This topic is intended as a live view of validation. This topic is intended for health surveillance, for anyone interesting in whether or not validations are being performed, as well as validation results.

    ⚠️ Deprecated! Will be removed in a later release. Use pe/sales/validationresult instead.

    Accepts the following message:

    Validationresult MQTT Message
    object
    uid: http://schema.ruter.no/validationresult.json

    Result of validation made with the RuterSalg application

    • #Deprecated

    Examples

  • SUB pe/dpi/journey

    Journey message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/journey
    Schema dpi-journey.json

    Message containing the stops included in the journey, connections to other lines, positions ++.

    Accepts the following message:

    Journey Message
    object
    uid: http://schema.ruter.no/journey.json

    List of stops for current journey in block

    Examples

  • SUB pe/dpi/nextstop

    Next Stop message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/nextstop
    Schema dpi-nextstop.json

    Next stop on the buss route after leaving a stop.

    Accepts the following message:

    Next Stop MQTT Message
    object
    uid: http://schema.ruter.no/nextstop.json

    Notification that vehicle has a new next stop

    Examples

  • SUB pe/dpi/eta

    ETA message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/eta
    Schema dpi-eta.json

    Estimated arrival at the remaining stops.

    Accepts the following message:

    ETA MQTT Message
    object
    uid: http://schema.ruter.no/eta.json

    Estimated time of arrival for future stops on a journey

    Examples

  • SUB pe/dpi/externaldisplay

    External Display message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/externaldisplay
    Schema dpi-externaldisplay.json

    Message to be shown on the external destination display. Usually line number (publicCode) and routeName, with support for alternative message.

    Accepts the following message:

    External Display MQTT Message
    object
    uid: http://schema.ruter.no/externaldisplay.json

    Notification that the external displays should show new destination information

    Examples

  • SUB pe/dpi/pa

    Passenger Announcement message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/pa
    Schema dpi-pa.json

    Message to be shown on internal displays. May contain references to videos, html, images, text etc.

    Accepts the following message:

    Passenger Announcement message
    object
    uid: https://schema.ruter.no/pamessage.json

    Examples

  • SUB pe/dpi/arriving

    Arriving message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/arriving
    Schema dpi-arriving.json

    Notice to passengers that the bus is approaching a stop.

    Accepts the following message:

    Arriving Message
    object
    uid: http://schema.ruter.no/arriving.json

    For display of arriving information to passengers

    Examples

  • SUB pe/dpi_command

    DPI Command message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi_command
    Schema dpi-command.json

    This channels is reserved for command and control messages originated by Ruter. Typical use cases include:

    • Diagnostics / debugging
      • Trigger transfer of debug information
      • Trigger screenshot of DPI screen
      • Trigger clearing of cache and refresh of webpage
    • Content
      • Trigger display of campaign

    The payload is defined as an object with no structure to provide flexibility.

    Accepts the following message:

    C2 MQTT Message
    object
    uid: http://schema.ruter.no/c2.json

    Message sent to bus to control DPI functions

    Examples

  • SUB pe/dpi/connections

    Connections message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/connections
    Schema dpi-connections.json

    List of connections for the remaining stops on a journey with expected departures.

    Accepts the following message:

    The Connections Schema
    object
    uid: http://schema.ruter.no/connections.json

    This schema defines the connection message sent as an MQTT message to buses

    Examples

  • SUB pe/dpi/key_stops

    Key Stops message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/key_stops
    Schema dpi-key_stops.json

    List of X number of most trafficked stops in the rest of the journey. Based on predicted number of passengers leaving on each stop

    Accepts the following message:

    Key Stops message
    object
    uid: https://schemas.ruter.no/dpi-key_stops.json

    This schema defines the Key Stops message sent as an MQTT message to vehicles

    Examples

  • SUB pe/dpi/deviation

    Deviation message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/deviation
    Schema deviation.json

    Notice to passengers that the bus is approaching a stop.

    ⚠️ Deprecated! No longer in use. Replaced with Passenger Announcement message.

    Accepts the following message:

    Deviation MQTT Message
    object
    uid: http://schema.ruter.no/deviation.json

    For display of deviation information to passengers

    • #Deprecated

    Examples

  • SUB pe/dpi/announcement

    Announcement message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/dpi/announcement
    Schema announcement.json

    Announcement to the passengers (ad hoc). Message contains a reference to the scope of the message, if applicable. Typically NSR stopplaceid / lineId or similar.

    ⚠️ Deprecated! No longer in use.

    Accepts the following message:

    Announcement MQTT Message
    object
    uid: http://schema.ruter.no/announcement.json
    • #Deprecated

    Examples

  • SUB tsp/json

    Traffic Preemption MQTT Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/itxpt/ota/tsp/json
    Schema tsp.json

    The message to be sent to VHF to ensure that the bus is prioritized at the traffic lights. This message is generated by Ruter when approaching an intersection or, when a stop is just before an intersection, after the doors have closed.

    Accepts the following message:

    Traffic Preemption MQTT Message
    object
    uid: http://schema.ruter.no/tsp.json

    Notification that vehicle should transmit a traffic preemption message

    Examples

  • SUB infohub/dpi/audio/json

    Audio message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/itxpt/ota/dpi/audio/json
    Schema audio.json

    Topic used exclusively to transmit audio messages to be played by the speaker system. The audio messages may contain an array of sound bites, that are to be played in the sequence they have been received.

    Accepts the following message:

    Audio MQTT Message
    object
    uid: http://schema.ruter.no/audio.json

    All audio is sent over one topic and message may contain multiple audio segments that must be played in the order listed

    Examples

  • SUB infohub/dpi/externaldisplay/json

    External Display message:

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/itxpt/ota/dpi/externaldisplay/json
    Schema dpi-externaldisplay.json

    Message to be shown on the external destination display. Usually line number (publicCode) and routeName, with support for alternative message.

    Accepts the following message:

    External Display MQTT Message
    object
    uid: http://schema.ruter.no/externaldisplay.json

    Notification that the external displays should show new destination information

    Examples

  • SUB itxpt/ota/madt/notification/json

    MADT Notification

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/itxpt/ota/madt/notification/json
    Schema notification.json

    Notification message sent to the MADT (Multi-Application Driver Terminal) device inside the bus. To be used to inform the bus driver from the Ruter backoffice. The text message may contain the "Line Feed" character (\n), indicating line breaks.

    Accepts the following message:

    Notification MQTT Message
    object
    uid: http://schema.ruter.no/notification.json

    Message to driver

    Examples

  • SUB pe/vehicle/api

    Vehicle API

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/pe/vehicle/api
    Schema api.json

    Message used by Ruter to distribute information about the vehicle and it's supported APIs as provided by the PTO.

    Accepts the following message:

    Api
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/vehicle/api/api.json

    Vehicle API topic

    Examples