Avtale om digitale tjenester - ADT 3.0.3

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.

More info

For more information, please go to: Ruter’s ADT agreement.

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 operational/assignment/attempt/request

    AssignmentAttemptRequest Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/operational/assignment/attempt/request
    Schema assignment-attempt-request.json
    Producer PTO
    Consumer Ruter Assignment
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    AssignmentAttemptRequest Usage

    Follows the request/response/state pattern. When a request is made to the request topic, a response will be available at the response topic once Ruter has finished processing. In addition, if the request results in a change of state, the status topic will be updated to reflect the current state as seen by Ruter.

    An AssignmentAttemptRequest can be made for:

    Action Description
    SignOn Creating an Assignment for a vehicle. Signing a vehicle on to a set of planned journeys/stops
    SignOff Signing a vehicle off from an assigned assignment
    Update Altering an existing assigned assignment
    • The message is composed of three operations (signOn, signOff, update). Only one operation will be processed per message received by Ruter. This gives that each message should only contain one operation. If the message contains more than one operation, the order of precedence is the following:
      1. signOn
      2. signOff
      3. update
    • Attempt request will get an attempt response under the response topic
    • Any request leading to a change of existing assignment state is reflected under the status topic
      • This topic will also be updated when Ruter has initiated any change to the existing assignment
    • Please provide all fields marked as reqired in the schema specifications.

    Definitions

    • A block contains a set of journeys.
    • A vehicleTask is a set of one or more blocks that can be served by one vehicle during one operating day. In the example below, the vehicle task with vehicleTaskId=59001 consists of the 2 Blocks with <PrivateCode>59001</PrivateCode>.
    Example of NeTEx definition of a vehicle task with 2 blocks
    <VehicleScheduleFrame version="20220908125021" id="RUT:VehicleScheduleFrame:1">
      <blocks>
        <Block version="20220908125021" id="RUT:Block:168197-59001mut-202209081312000">
          <PrivateCode>59001</PrivateCode>
          <StartTime>11:12:00</StartTime>
          <EndTime>14:41:00</EndTime>
          <dayTypes>
            <DayTypeRef ref="RUT:DayType:2022-09-08"/>
          </dayTypes>
          <StartPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
          <EndPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
          <journeys>
            <DeadRunRef ref="RUT:DeadRun:006723-008020-131200"/>
            <VehicleJourneyRef ref="RUT:ServiceJourney:003565-004003-131500"/>
            ...
          </journeys>
        </Block>
        <Block version="20220908125021" id="RUT:Block:168197-59001muwt-202209080359000">
          <PrivateCode>59001</PrivateCode>
          <StartTime>01:59:00</StartTime>
          <EndTime>06:16:00</EndTime>
          <dayTypes>
            <DayTypeRef ref="RUT:DayType:2022-09-08"/>
          </dayTypes>
          <StartPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
          <EndPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
          <journeys>
          <DeadRunRef ref="RUT:DeadRun:006713-008006-035900"/>
          <VehicleJourneyRef ref="RUT:ServiceJourney:002521-002932-041700"/>
          ...
          </journeys>
        </Block>
      </blocks>
    </VehicleScheduleFrame>
    

    Sign On

    • Any pre-existing assigned assignments will be signed off AssignmentState.assigned=true
    • If the attempt request succeeds, the vehicle will be assigned the new plan AssignmentState.assigned=true
    • If the attempt request fails, the state of the vehicle is AssignmentState.assigned=false
    • All signOn-attempts require the fields vehicleTaskId and serviceWindow.
      • vehicleTaskId: Can be found in the common file in the NeTEx export under this path VehicleScheduleFrame.blocks[].Block.PrivateCode
      • serviceWindow: Defines a time range for which journeys the vehicle should be signed on. The vehicle will be signed on to all the journeys in the vehicle task between provided times. Signed on journeys may be part of 1 or more Blocks. Times provided may belong to the same calendar date, or 2 consecutive dates. Attempts not containing valid date times for firstDepartureDateTime and lastArrivalDateTimes will be rejected, resulting in AssignmentState.assigned=false
    Sign On - PLANNED

    The vehicle will be signed on to service the pre-existing plans for the specified serviceWindow

    Sign On - EXTRA

    Used if additional vehicles are demanded to serve the pre-existing plans for the specified serviceWindow

    Sign On - REPLACEMENT

    Used if another vehicle can not service parts of its assignment. The operator should sign off the other vehicle using either SHORTENING or BREAKDOWN.

    Note: Ruter will not sign off the other vehicle automatically.

    Sign Off

    Sign Off - FINISHED

    The vehicle has serviced all journeys in the assignment

    Sign Off - BREAKDOWN

    The vehicle has broken down, or in some way not capable of servicing the rest of the assignment

    Sign Off - CANCELLED

    Remaining not serviced stops/journeys in the assignment will not be serviced (by the assigned vehicle).

    Sign Off - SHORTENING

    Same as CANCELLED

    Additional Sign Off codes used by RUTER

    • EXPIRED Given a successfull signOn, if the vehicle is not signed off before two hours after the last planned arrival. The vehicle will be automatically signed off with the code EXPIRED.

    Update

    Update - SHORTENING

    Operational change of a pre-existing assigned assignment for a vehicle.

    Failed attempts will not affect the assignment state for a vehicle.

    • serviceWindow is honoured as SignOn - PLANNED
    Example case for SHORTENING

    Given an assignment (vehicle plan) with two journeys:

    Journey 1
    Quay 1 dep 2023-04-27T10:00Z
    Quay 2 arr 2023-04-27T10:01Z, dep 2023-04-27T10:01Z
    Quay 3 arr 2023-04-27T10:02Z
    
    Journey 2
    Quay 3 dep 2023-04-27T10:03Z
    Quay 2 arr 2023-04-27T10:04Z, dep 2023-04-27T10:04Z
    Quay 1 arr 2023-04-27T10:05Z
    

    When SHORTENING

    {
        "eventTimestamp": "2023-04-27T12:40:12.631914Z",
        "traceId": "083b71c4-e417-11ed-b5ea-0242ac120004",
        "update":
        {
            "code": "SHORTENING",
            "serviceWindow":
            {
                "firstDepartureDateTime": "2023-04-27T10:02Z",
                "lastArrivalDateTime": "2023-04-27T10:03Z"
            }
        }
    }
    

    Then; both visits at Quay 3 will be removed from the assignment. The resulting assignment will be:

    Journey 1
    Quay 1 dep 2023-04-27T10:00Z
    Quay 2 arr 2023-04-27T10:01Z, dep 2023-04-27T10:01Z
    
    Journey 2
    Quay 2 arr 2023-04-27T10:04Z, dep 2023-04-27T10:04Z
    Quay 1 arr 2023-04-27T10:05Z
    

    Effectively, the vehicle should turn around at Journey 1 Quay 2 and continue servicing Journey 2 from Quay 2

    Accepts the following message:

    AssignmentAttemptRequest
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/operational/assignment/attempt/request/assignment-attempt-request.json

    Request to sign a vehicle on/off, or update an assigned assignment. The vehicle in question is provided in the mqtt topic name. Response will be sent to this vehicle via assignment attempt response.

    Examples

  • PUB operational/assignment/omit/request

    AssignmentOmitRequest Message

    Field Value
    Central Topic ruter/{operatorId}/back_office/adt/v3/operational/assignment/omit/request
    Schema assignment-omit-request.json
    Producer PTO
    Consumer Ruter Assignment
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    AssignmentOmitRequest Usage

    Follows the request/response pattern. When a request is made to this topic, a response will be available at the response topic once Ruter has finished processing.

    • All omit request will get an omit response under the response topic
    • Please provide all fields marked as required in the schema specifications.
    • Note that there are no vehicles involved in this exchange.

    Omit - NO_INTENTION

    Inform Ruter that the PTO has no intention of servicing the journeys and stops defined by the provided service window.

    • All omit attempts require the fields vehicleTaskId and serviceWindow.
      • vehicleTaskId: Can be found in the common file in the NeTEx export under this path VehicleScheduleFrame.blocks[].Block.PrivateCode
      • serviceWindow: Defines a time range for which calls or journeys the PTO has no intention of servicing. Times provided may belong to the same calendar date, or 2 consecutive dates Attempts not containing valid date times for firstDepartureDateTime and lastArrivalDateTimes will be rejected.

    Accepts the following message:

    AssignmentOmitRequest
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/operational/assignment/omit/request/assignment-omit-request.json

    Request to omit a specified service. Response will be sent to the back office via assignment attempt response.

    Examples

  • PUB pe/active_cab

    ActiveCab Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/active_cab
    Schema active-cab.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Accepts the following message:

    ActiveCab
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/active-cab/active-cab.json

    Used to keep track of what direction the train is driving

    Examples

  • PUB pe/door_lock

    DoorLock Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/door_lock
    Schema door-lock.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

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

    Frequency: on change

    Accepts the following message:

    DoorLock
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/door-lock/door-lock.json

    Door lock event

    Examples

  • PUB pe/doors_individually

    DoorsIndividually Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/doors_individually
    Schema doors-individually.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    This topic is used to track the individual status of doors. One use case is to improve the data quality of APC counts. See also topic sensors/door for status of anyDoorOpen/allDoorsClosed.

    Accepts the following message:

    DoorsIndividually
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/doors-individually/doors-individually.json

    This object is used to represent a door individually.

    Examples

  • PUB sensors/apc/{sensorId}

    Apc Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/apc/{sensorId}
    Schema apc.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.
    sensorId
    required
    string
    uid: sensorId

    The sensor / telemetry Id.

    Accepts the following message:

    Apc
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/apc/apc.json

    Raw-data from door-sensor for later evaluation.

    Examples

  • PUB sensors/door

    Door Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/door
    Schema door.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Frequency: on change

    Accepts the following message:

    Door
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/door/door.json

    Describes if any door is open (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","traceId":"2d826a9a-2474-11ed-861d-0242ac120002"}

    Examples

  • PUB sensors/location

    Location Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/location
    Schema location.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Describes the GNSS navigation receiver feedback in metric format.

    The GNSS type is expected to be GPS. The GNSS coordinate system is expected be “WGS84”. Negative values is used south of the equator and west of Greenwich.

    Frequency is expected to be at 1 message per second.

    Accepts the following message:

    Location
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/location/location.json

    Location sensor data

    Examples

  • PUB sensors/odometer

    Odometer Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/odometer
    Schema odometer.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Describes an odometer value in meters based on total vehicle distance or similar. Absolute value of less importance but should be increasing within the scope of a journey.

    Frequency is expected to be at 1 message per second.

    Accepts the following message:

    Odometer
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/odometer/odometer.json

    Odometer data

    Examples

  • PUB sensors/stop_button

    StopButton Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/stop_button
    Schema stop-button.json
    Producer PTO
    Consumer Ruter DPI
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    This message should be produced whenever the stop signal is turned on or off. Depending on whether the regular stop button is pressed or the blue accessebility button is pressed, a different signal should be produced.

    Whenever the vehicle has serviced a stop, the signal is to be reset.

    Frequency: on change

    Accepts the following message:

    StopButton
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/stop-button/stop-button.json

    Describes if passengers have requested that the bus should stop (stop button pressed).

    Examples

  • PUB sensors/telemetry/{sensorId}

    Telemetry Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/sensors/telemetry/{sensorId}
    Schema telemetry.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Several different kinds of sensor/telemetry data are available varying by vehicle type For traditional busses, FMS is the standard that defines what data about the vehicle is published on the FMS bus and further on by ITxPT FMStoIP service.In addition, vessels, trams and different bus types have proprietary data not captured by FMS.

    According to the data centric approach from ITxPT, several of these data types (door, location, stop button etc) have been assigned separate topics as being described in this document. However, data types required by Ruter that haven’t yet been described in the MQTT structure from ITxPT, will still be handled by the general Telemetry topic that was introduced by Ruter in 2019.

    All such data are defined by unique, 32 bit, identifiers. Data caught from the FMS bus retain their PGN numbers as the last 16 bits of the ID. Data not coming from the FMS bus follow a separate addressing scheme, with addresses allocated by Ruter on request. Please note that PTOs are free to decide if they want to use FMS or a non-FMS data source to provide the data.

    To utilize FMS data in Ruter’s architecture, Operators can either set up an FMS2IP service or use any other means to subscribe to the FMS bus data. Note that there must be one separate MQTT message per FMS PGN.

    The identifiers are constructed this way:

    Bytes Description
    1 Source identifier (0x00 FMS, 0x01 Non-FMS)
    2-4 Source-specific id, e.g. FMS PGNs

    Available Non-FMS standard data identifiers

    Optional unless stated explicitly in the main ADT document.

    ID Subid Name Value Recommended refresh interval Remarks
    0001FF25 Charger onChange
    10003 Wall charger connected boolean
    10004 Fast charger connected boolean
    10005 Charging active boolean
    01000002 Temperature indoor 6/min * Unit: Celcius
    * Resolution: <= 1 C
    tempavg Temperature indoor average float
    tempfront Temperature indoor front float
    tempmiddle Temperature indoor middle float
    temprear Temperature indoor rear float
    01000005 SOC float 1/min
    01000006 Transmission mode combustion/electric onChange Intended for hybrid vehicles
    01000007 Windscreen wiper active boolean onChange Taken to represent a measurement of the ground truth binary rainfall state, given that it is a better predictor of the binary rainfall state than radar- or gauge-based measurements
    01000008 Accelerometry 6/min * Bandwidth: >= 100 hz
    * Unit: g
    * Resolution: <= 0.01 g
    xmin Min x value last interval float
    xmax Max x value last interval float
    xavg Average x value last interval float
    ymin Min y value last interval float
    ymax Max y value last interval float
    yavg Average y value last interval float
    zmin Min z value last interval float
    zmax Max z value last interval float
    zavg Average z value last interval float
    01000009 Temperature outdoor float 1/min * Unit: Celcius
    * Resolution: <= 1 C
    * Measured at front of vehicle as near as possible to the ground
    0100000A Accumulated energy consumption float 1/min * Energy consumed
    * Including HVAC
    * Unit: kWh
    sensorId
    required
    string
    uid: sensorId

    The sensor / telemetry Id.

    Accepts the following message:

    Telemetry
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/telemetry/telemetry.json

    Examples

  • PUB di/override_attempt/destination_display

    Destination Display Override Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/di/override_attempt/destination_display
    Schema destination-display-override.json
    Producer PTO
    Consumer Ruter BO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Accepts the following message:

    DestinationDisplayOverride
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/di/override_attempt/destination_display/destination-display-override.json

    Describes a request from MADT or other GUI to manually override the information shown on the destination display. It is up to the presenting system to decide how and for how long the override will apply. A rule could be until next journey begins or a new override_attempt/destination_display is received. The topic could be blanked (provided with a zero-byte payload) to indicate that any overriding information is no longer valid and that the destination display can return to normal

    Examples

  • PUB pe/dpi/ack

    Acknowledge Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/dpi/ack
    Schema dpi-acknowledge.json
    Producer PTO, Ruter DPI
    Consumer Ruter DPI
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    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

    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

    Diagnostics Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/dpi/diagnostics
    Schema dpi-diagnostics.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    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:

    DpiDiagnostics
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/diagnostics/dpi-diagnostics.json

    Examples

  • PUB pe/sales/diagnostics

    RuterSalg diagnostics

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/sales/diagnostics
    Schema sales-diagnostics.json
    Producer RuterSalg
    Consumer RuterSalg
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Diagnostics message generated by RuterSalg.

    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:

    SalesDiagnostics
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/sales/diagnostics/sales-diagnostics.json

    Examples

  • PUB pe/cardreader_diagnostics/vix/{deviceRef}

    VIX Card Reader Diagnostics MQTT Message

    Field Value
    Central Topic ruter/{operatorId}/{vehicleId}/adt/v3/pe/cardreader_diagnostics/vix/{deviceRef}
    Schema vix-cardreader_diagnostics.json
    Producer VIX
    Consumer Ruter BackOffice
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Diagnostics message sent from any Vix-validator running Ruter-firmware in the vehicle. Can be used by both PTA and PTO to monitor the operational status of these units.

    deviceRef
    required
    string
    uid: deviceRef

    An unique ID of the unit.

    Accepts the following message:

    VixCardreaderDiagnostics
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/cardreader-diagnostics/vix/vix-cardreader_diagnostics.json

    Examples

  • SUB pe/sales/current_stop

    RuterSalg current_stop

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/sales/current_stop
    Schema sales-current_stop.json
    Producer RuterSalg
    Consumer RuterSalg
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Used to alert the RuterSalg app about the current stop. This message is triggered when the Progress entity determines that the bus is arriving at the quay, meaning it is maximum 35 meters from the quay, approaching it. Contains information about the zone the current stop belongs to.

    The message also contains information about the NEXT stop and its zone. This is used to determine if the bus is approaching a zone border. One use for this is whether or not to sell a "smart ticket" if the passenger has funds in their travel purse.

    Accepts the following message:

    SalesCurrentStop
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/sales/current_stop/sales-current_stop.json

    Examples

  • SUB operational/assignment/attempt/response

    AssignmentAttemptResponse Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/operational/assignment/attempt/response
    Schema assignment-attempt-response.json
    Producer Ruter Assignment
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    AssignmentAttemptResponse Usage

    When an AssignmentAttemptRequest is made, and Ruter has finished processing, the results are presented as AssignmentAttemptResponse. The response contains:

    • result to indicate if processing by Ruter has been successfully processed, or not. See the schema for possible codes.
    • state as a representation of the Assignment state as seen by Ruter after processing is completed.

    State

    Indicates what state the vehicle has in the RUTER systems. A vehicle can be either assigned or unassigned. In addition the state shows what code is applied

    Additional codes used by RUTER

    In addition to the codes supplied in the assignment attempts for signOn, signOff and update, RUTER can apply some codes.

    • REPLACED When a vehicle attempts a SignOn with the code REPLACED. Any other vehicle signed on to the same vehicle task and not marked as EXTRA will be automatically signed off with the code REPLACED.
    • EXPIRED Given a successfull signOn, if the vehicle is not signed off before two hours after the last planned arrival. The veicle will be automatically signed off with the code EXPIRED.

    Accepts the following message:

    AssignmentAttemptResponse
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/operational/assignment/attempt/response/assignment-attempt-response.json

    A response to an assignment attempt request

    Examples

  • SUB operational/assignment/status

    AssignmentStatus Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/operational/assignment/status
    Schema assignment-status.json
    Producer Ruter Assignment
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    AssignmentStatus Usage

    Current Assignment State for a vehicle as seen by Ruter. The topic is retained so the current status is persisted on the mqtt-broker. The topic is updated when an AssignmentAttemptRequest is made, processing is complete and/or the state has changed.

    Note that Ruter could, in case of operational deviations, or missing sign offs, update the assignment. This update will be reflected here.

    Accepts the following message:

    AssignmentStatus
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/operational/assignment/status/assignment-status.json

    Assignment status for the vehicle as recorded by Ruter

    Examples

  • SUB operational/assignment/omit/response

    AssignmentAttemptResponse Message

    Field Value
    Central Topic {operatorId}/ruter/back_office/adt/v3/operational/assignment/omit/response
    Schema assignment-omit-response.json
    Producer Ruter Assignment
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    AssignmentAttemptResponse Usage

    When an AssignmentAttemptRequest is made, and Ruter has finished processing, the results are presented as AssignmentAttemptResponse. The response contains:

    • result to indicate if processing by Ruter has been successfully processed, or not. See the schema for possible codes.

    Accepts the following message:

    AssignmentOmitResponse
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/operational/assignment/omit/response/assignment-omit-response.json

    A response to an assignment omit request

    Examples

  • SUB di/available_destination_displays

    Available Destination Displays Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/di/available_destination_displays
    Schema available-destination-displays.json
    Producer Ruter DPI
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Provides a list of available destination displays for a vehicle. The list should be used for external displays, in case the vehicle has lost connection to the backoffice.

    Accepts the following message:

    AvailableDestinationDisplays
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/di/available-destination-displays/available-destination-displays.json

    Examples

  • SUB di/operational_message_to_driver

    Operational Message to Driver Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/di/operational_message_to_driver
    Schema operational-message-to-driver.json
    Producer -
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    Provides an operational message directed to the driver onboard this vehicle. Direction: From back-office to driver.

    Accepts the following message:

    OperationalMessageToDriver
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/di/operational_message_to_driver/operational-message-to-driver.json

    Operational message to driver

    Examples

  • SUB pe/audio

    Audio Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/audio
    Schema audio.json
    Producer Ruter DPI
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    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.

    Multiple speaker groups may be the target of the same sound file.

    Accepts the following message:

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

    This topic provides an audio message intended for passengers onboard the vehicle that should be played on speaker(s) defined in the speaker property of the payload.

    Examples

  • SUB pe/dpi/journey

    Journey Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/journey
    Schema dpi-journey.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

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

    Accepts the following message:

    DpiJourney
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/journey/dpi-journey.json

    List of stops for current journey in block

    Examples

  • SUB pe/dpi/nextstop

    Nextstop Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/nextstop
    Schema dpi-nextstop.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Next stop on the buss route after leaving a stop.

    Accepts the following message:

    DpiNextstop
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/nextstop/dpi-nextstop.json

    Notification that vehicle has a new next stop

    Examples

  • SUB pe/dpi/eta

    Eta Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/eta
    Schema dpi-eta.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Estimated arrival at the remaining stops.

    Accepts the following message:

    DpiEta
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/eta/dpi-eta.json

    Estimated time of arrival for future stops on a journey

    Examples

  • SUB pe/dpi/externaldisplay

    Externaldisplay Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/externaldisplay
    Schema dpi-externaldisplay.json
    Producer Ruter DPI
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

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

    Accepts the following message:

    DpiExternaldisplay
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/externaldisplay/dpi-externaldisplay.json

    Notification that the external displays should show new destination information

    Examples

  • SUB pe/dpi/pa

    Pa Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/pa
    Schema dpi-pa.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

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

    Accepts the following message:

    DpiPa
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/pa/dpi-pa.json

    Examples

  • SUB pe/dpi/arriving

    Arriving Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/arriving
    Schema dpi-arriving.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    Notice to passengers that the bus is approaching a stop.

    Accepts the following message:

    DpiArriving
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/arriving/dpi-arriving.json

    For display of arriving information to passengers

    Examples

  • SUB pe/dpi/connections

    Connections Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/connections
    Schema dpi-connections.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

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

    Accepts the following message:

    DpiConnections
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/connections/dpi-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}/adt/v3/pe/dpi/key_stops
    Schema dpi-key_stops.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    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:

    DpiKeyStops
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/key_stops/dpi-key_stops.json

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

    Examples

  • SUB pe/dpi/command

    Command Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/dpi/command
    Schema dpi-command.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    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:

    DpiCommand
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/pe/dpi/command/dpi-command.json

    Message sent to bus to control DPI functions

    Examples

  • SUB pe/input/stop_button

    Remote Stop Button Message

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/input/stop_button
    Schema stop-button.json
    Producer Ruter DPI
    Consumer PTO
    Service Level ✅ External API. Restrictions apply. Only backward compatible changes may happen within the major version.

    This message should be interpreted as if the stop button, accessibility button or the stop was served by the vehicle.

    A corresponding message should be produced on /sensors/stop_button as normal, confirming that the stop signal lights was lit and the vehicle actually served the stop.

    Frequency: on change

    Accepts the following message:

    Stop Button Message
    object
    uid: https://schemas.ruter.no/adt/ota/api/v3.0/sensors/stop-button/stop-button.json

    Describes if passengers have requested that the bus should stop (stop button pressed).

    Examples

  • SUB pe/vehicle/api

    Vehicle API

    Field Value
    Central Topic {operatorId}/ruter/{vehicleId}/adt/v3/pe/vehicle/api
    Schema api.json
    Producer Ruter DPI
    Consumer Ruter DPI
    Service Level ⛔ Ruter internal API. No restrictions apply. Api may be removed or modified freely by Ruter within major version.

    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