API v. 2.4

1         Overview

This API description covers Avtale om Digitale Tjenester v. 2.4. 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.

1.1        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.

Minor changes in the document are flagged either by color, or by specifying (NEW or UPD (updated) version x.y) in the heading.

  • Yellow represents changes in version 2.1 compared to 2.0.

  • Blue represents changes in version 2.2 compared to 2.0 or 2.1

  • Green represents changes in version 2.3 compared to 2.0, 2.1 or 2.2

  • Purple represents changes in version 2.4 compared to 2.0, 2.1, 2.2 og 2.3

 

Note: Corrections of unfortunate misspellings or other obvious flaws may occur - but are not considered as upgrades.

1.2        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.

1.3        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.

1.4        List of topics

The listed topics are topics that are to be produced in either the vehicle or in the Ruter Back Office.

All data must be JSON and UTF-8 encoded.

Topics are categorized by a thematic perspective, according to the topic structure proposed for ITxPT at the time of writing.

Category

Topic

Produced by

Consumed by

Sensor (sensor)

Stop Button

Vehicle

Ruter BO

Door

Vehicle

Ruter BO

Location

Vehicle

Ruter BO

Odometer

Vehicle

Ruter BO

Clock

Vehicle

Vehicle,
Ruter Sales

APC Sensors

Vehicle

Ruter BO

Telemetry

Vehicle

Ruter BO

Operational information (oi)

Unique Identifier

Vehicle

Ruter BO, Ruter Sales

Current Block State

Ruter BO

Ruter DPI

Current Vehicle Journey Status

Ruter BO

Ruter DPI,
Ruter Sales

Expected Call

Ruter BO

Ruter DPI,
Ruter Sales

Current Destination Display

Ruter BO

Ruter DPI

Extended information (ei)

Deviation Information

Ruter BO

Ruter DPI

Transfer Information

Ruter BO

Ruter DPI

Due Information

Ruter BO

Ruter DPI

Internal Audio Message

Ruter BO

Ruter DPI

External Audio Message

Ruter BO

Ruter DPI

Driver Audio Message

Ruter BO

Ruter DPI

Driver interaction (di)

Assignment Attempt

Vehicle

Ruter BO

Assignment Attempt Rejection

Ruter BO

Vehicle AVMS

Destination Display Override

Vehicle

Ruter DPI

Available Destination Displays

Ruter BO

Vehicle AVMS

Message to Driver

Ruter BO

Vehicle MADT

Proprietary Extensions (pe)

Sales Status

RuterSales

Ruter BO

Sales: Diagnostics

RuterSales

Ruter BO

Sales: Sale

RuterSales

Ruter BO

Sales: Validation

RuterSales

Ruter BO

DPI Extensions

Ruter DPI / Ruter BO

Ruter DPI / Ruter BO

DPI Command

Ruter DPI

Ruter BO

DPI Diagnostics

Ruter DPI

Ruter BO

DPI Acknowledge

Vehicle

Ruter BO

Doors Individually

Vehicle

Ruter BO

Door locks

Vehicle

Ruter BO, Vehicle DPI

Active Cab

Vehicle

Ruter BO, Vehicle DPI

Vehicle Direction

Vehicle

Ruter BO, Vehicle DPI

Boarding Status

Vehicle

Ruter BO, Vehicle DPI

Traffic Signal Priority

Ruter BO

Vehicle TSP

 

1.5        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.

2         Sensor Topics

2.1        Stop Button

Topic

ruter/{PTO}/{vehicleID}/sensors/stop_button

Retain

Yes

QoS

1

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

Fields

Name

Type

Description

stopPressed

boolean

True if stop request button pressed.

False if stop request signal is cleared.

atDateTime

string

ISO 8601. Reflects the UTC time when the state changed.

messageNumber

number

Sequence number, increased by one for each new message. Used to validate consistency in the data stream

The message number sequence is unique for each topic

Optional

 Example

{ "stopPressed": true, "atDateTime": "2021-11-30T23:45:52.006Z", "messageNumber": 999 }

 

2.2        Door

Topic

ruter/{PTO}/{vehicleID}/sensors/door

Retain

Yes

QoS

1

 

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.

Fields

Name

Type

Description

doorOpen

boolean

True if any door is open (door lock is released). False if door lock is activated

atDateTime

string

ISO 8601. Reflects the UTC time when the state changed.

 Example

 

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

 

2.3        Location

Topic

ruter/{PTO}/{vehicleID}/sensors/gnss/location

Retain

No

QoS

0

 

Describes the GNSS navigation receiver feedback in metric format. The periodicity of updates to be expected should be described as number of seconds in configValue01 for this topic under topic ruter/{PTO}/{vehicleID}/mi/provider_clients//provided_topics

The GNSS type should be described in configValue11. Information about the used GNSS System. MixedGNSSTypes is used for receivers using multiple satellite constellations. Possible values: “GPS”, ”Glonass”, ”Galileo”, ”Beidou”, ”IRNSS”, ”Other”, ”DeadReckoning”, ”MixedGNSSTypes”

The GNSS coordinate system should be described in configValue12, at least if other than “WGS84”. Possible values: “GPS”, ”Glonass”, ”Galileo”, ”Beidou”, ”IRNSS”, ”Other”, ”DeadReckoning”, ”MixedGNSSTypes”. “MixedGNSSTypes” is used for receivers using multiple satellite constellations.

Fields

Name

Type

Description

latitudeDegree

number

Latitude coordinate in decimal degrees

latitudeDirection

string

Optional. Latitude direction (“N” or “S”)

longitudeDegree

number

Longitude coordinate in decimal degrees

longitudeDirection

string

Optional. Longitude direction (“W” or “E”)

altitude

number

Altitude value (m) above mean sea level.

fixDateTime

string

ISO 8601. Reflects the UTC time provided by the GNSS equipment for position fix. This is the point in time the location applies to.

messageNumber

number

Sequence number, increased by one for each new message. Used to validate consistency in the data stream

The message number sequence is unique for each topic

Optional

speedOverGround

number

GNSS based speed over ground (m/s)

trackDegreeTrue

number

Direction of travel in relation to the geographical North Pole (0-360 degrees)

signalQuality

number

GPS quality indicator. Possible values:

  • 0 - Fix not available

  • 1 - GPS fix

  • 2 - Differential GPS fix

  • 3 = PPS fix

  • 4 = Real Time Kinematic

  • 5 = Float RTK

  • 6 = Estimated (dead reckoning)

  • 7 = Manual input mode

  • 8 = Simulation mode

numberOfSatellites

number

Number of satellites used

hdop

number

Value of precision in horizontal dilution

 

Example

 

{ "latitudeDegree": "59.251356", "longitudeDegree": "11.581231", "altitude": 124, "fixDateTime": "2017-11-30T23:45:52Z", "messageNumber": 12345, "speedOverGround": "15.3", "trackDegreeTrue": "324" "signalQuality": 1, "numberOfSatellites": 12, "hdop": 2.4 }

 

 

2.4        Odometer

Topic

ruter/{PTO}/{vehicleID}/sensors/odometer

Retain

No

QoS

0

 

Describes an odometer value in meters based on total vehicle distance or similar. Absolute value of less importance but should be increasing at least within the scope of a journey. Optionally the current speed according to the odometer could be included.

 

Fields

Name

Type

Description

distance

number

Describes absolute odometer value in metres.

atDateTime

string

ISO 8601. Reflects the UTC time when the information was provided.

messageNumber

number

Sequence number, increased by one for each new message. Used to validate consistency in the data stream

The message number sequence is unique for each topic

Optional

 

Example

 

2.5        Clock

Topic

sensors/clock

Retain

No

QoS

0

Fields

Name

Type

Description

localTimeZoneDate

string

Date formatted as YYYY-MM-DD where YYYY = year MM = month [01..12] DD = day [01..31]

localTimeZoneTime

string

Time formatted as hh:mm:ss where hh = hour [00..23] mm = minute [00..59] ss = seconds [00..59]

atDateTime

string

ISO 8601. Reflects the UTC time when the information was provided.

 

Example

 

 

2.6        APC sensors

Topic

ruter/{PTO}/{vehicleID}/sensors/apc_sensors

Retain

Yes

QoS

1

 

Raw-data from door-sensor for later evaluation.

Note: Each sensors accumulated count, shall be reset to zero (0) after successful delivery to BO.

Fields

Name

Type

Description

doorRef

string

Stable alfa-numeric reference that is unique within scope of vehicle (vehicle element/train set). Could be a door-number or a combination of coach number and door number.

alightingCount

number

Accumulated number of alighting passengers detected by this sensor since last reset.

boardingCount

number

Accumulated number of boarding passengers detected by this sensor since last reset.

atDateTime

string

ISO 8601. Reflects the current UTC time

messageNumber

number

Sequence number, increased by one for each new message. Used to validate consistency in the data stream

The message number sequence is unique for each topic

Optional

categoryActivities

Array of CategoryActivity

A list describing APC activity at each individual door divided per handled object category.

 

Fields of CategoryActivity

Name

Type

Description

categoryRef

string

Object class reference. I.e. “ADULT”, “CHILD”, “PRAM”, “BIKE”, “WHEELCHAIR” or “OTHER”

alightingCount

number

Accumulated number of alighting of this category detected by this sensor since last reset.

boardingCount

number

Accumulated number of boarding of this category detected by this sensor since last reset.

 Example

 

 

2.7        Telemetry

 

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

All FMS PGNs become "0000" + 4-digit hex PGN, i.e. “0000FE4E” for PGN FE4E.

Details of available non-FMS addresses are available in the resource section here

Telemetric data in the vehicle are often refreshed at a very high rate and are originally intended to be consumed directly in the vehicle. Ruter’s enterprise architecture requires the same data to be consumed by Ruter’s back office. This requirement, along with constrains related to mobile networks, doesn’t allow us to use the same refresh rates as are ideal onboard vehicles.

 

3         Operational Information Topics

3.1        Unique Identifier

Topic

oi/vehicle/unique_identifier

Retain

Yes

QoS

1

 

A primary and permanent unique identifier used to represent the physical vehicle. For road vehicles: Indicates the globally unique 17 characters long alphanumeric Vehicle Identification Number (VIN) permanently attached to the vehicle. For other modes: Indicates a globally unique number of some sort permanently attached to the vehicle or if this is not possible; to the on-board system. Could be a MAC-address or other GUID.

Fields

Name

Type

Description

value

string

Normally a 17 characters long alphanumeric Vehicle Identification Number (VIN) permanently attached to the vehicle by the vehicle manufacturer. For non-road vehicles where such a permanent identifier is not available or if the VIN is not known some other type of globally unique value could be used.

typeOfValue

string

«VIN”, “UUID”, “PIN”, “OTHER”

 Example

 

3.2        Current Block

Topic

{PTO}/ruter/{vehicleID}/oi/current_block/state

Retain

Yes

QoS

1

Normally this topic indicates which block this vehicle is currently signed on to according to the backoffice or that it only assigned but not yet signed on or that it is not even assigned. This is usually a result of what was proposed by the driver on-board (see ruter/{PTO}/{vehicleID}/di/assignment_attempt/block) and then confirmed as valid by the back-office. It could also be based on an overriding decision enforced by the operation control centre.

Note that if a ruter/{PTO}/{vehicleID}/di/assignment_attempt/block is not answered by the back-office within a configured duration it is assumed that contact is lost with the control centre and then the proposed block will be accepted and exposed on this topic.

Fields

Name

Type

Description

fromDateTime

string

Time from which the sign on or assignment applies. ISO 8601, UTC

state

string

Possible values: “SIGNED_ON”, “ASSIGNED”, “NOT_ASSIGNED”,

blockRef

string

Not provided if not assigned or not signed on, otherwise provided as a Block identifier.

operatingDay

string

Not provided if not assigned, otherwise provided as the scheduled date of the block on the format “YYYY-MM-DD” .Maybe different from calendar date

 

Example

 

 

3.3        Vehicle Journey Details

Topic

{PTO}/ruter/{vehicleID}/oi/current_vehicle_journey/details

Retain

Yes

QoS

1

 

This topic provides the details of the current (monitored) vehicle journey. If there is no ongoing vehicle journey, this topic will provide the details of the coming vehicle journey. The information should reflect the latest production plan including any applied control actions as known in the back-office. Note however that this does not include neither estimated nor observed times at the different stops. This information is instead provided on the topic ruter/{PTO}/{vehicleID}/oi/current_vehicle_journey/expected_call The topic should be blanked (provided as a retained message with a zero-byte payload) if the vehicle has left the last stop and the next vehicle journey is not known

Fields

Name

Type

Description

operatingDayDate

string

The scheduled date of the journey.

vehicleJourneyRef

string

A Vehicle Journey identifier.

journeyNumber

string

The journey number. May describe a part of the vehicleJourneyRef that should be interpreted in scope of a certain line or an operator.

journeyPatternRef

string

A unique identifier for the original journey pattern. E.g. 16-digit ID.

timedJourneyPatternRef

string

Optional. Identifier for a journey pattern with a unique timing pattern. Format to be agreed.

transportModeCode

string

The transport mode. “BUS”, “TRAM” etc.

transportAuthority

Organisation Info

Information about the transport authority that provides the journey. See xxx

contractor

Organisation Info

Optional. Information about the operator that is contracted to operate the journey.

plannedStartDateTime

string

The date and time when the journey is planned to start. ISO 8601, UTC.

plannedEndDateTime

string

The date and time when the journey is planned to end. ISO 8601, UTC

origin

Place

The place where the journey comes from.

line

Line Info

Optional. Only provided for service journeys. Information about the journey’s line

directionOfLine

Direction Of Line info

Optional. Only provided for service journeys. Information about the journey’s direction on the line

calls

Array of Point Call

Points that shall be called at during the journey. At least two items.

 

Fields of Line Info

Name

Type

Description

ref

string

Optional. Only provided for service journeys. Information about the journey’s line.

designation

string

The public line number displayed to passengers. Note: this value can be alphanumeric!

number

string

Technical line number.

name

string

Optional. Name of line

 

Fields of Direction of Line Info

Name

Type

Description

code

string

A value that is unique per direction. Usually “1” or “2”.

name

string

Optional. Name of direction.

Fields of Place

Name

Type

Description

name

string

Optional. Name of the origin

shortName

string

Optional. Short name of the origin.

Fields of Destination Display

Name

Type

Description

productName

string

Optional. Name of public transport product

symbolName

string

Optional. Controls any symbols in display.

lineDesignation

string

Displayed line number.

primaryDestination

string

Names of primary destination

secondaryDestination

string

Optional. Names of secondary destination.

displayKeys

Array of Key

Optional. Contains device specific information such as sign codes etcetera. See 5.6.20. A numeric sign code representing the combined destination display information could thus be provided in a contained key with appropriate parameterData. E.g. “Destination=659” It is possible to provide information for multiple display devices in parallel if there is a mixed fleet with different hardware by providing multiple Keys in parallel. E.g. one Key with "deviceName": "SIGN_X" and another Key with "deviceName": "SIGN_Y".

 

 

 

 

Fields of Primary Destination

Name

Type

Description

name

string

Name of the destination

shortName

string

Optional. Short name of the destination

Fields of Secondary Destination

Name

Type

Description

name

string

Optional. Name of the destination

shortName

string

Optional. Short name of the destination

secondaryDestinationType

string

Optional. The meaning of the secondary destination.

 

Fields of Point Call

Name

Type

Description

sequenceNumber

number

The order of the call on the vehicle journey. Increasing. Note that the numbering can start with a higher number than 1 and that there might be holes in the sequence numbering as not expected calls are excluded.

journeyPatternPoint

Journey Pattern Point info

The point to call. (May be updated in real time)

stopArea

Stop Area Info

Optional. The stop area of the call. (May be updated in real time).

stopPoint

Stop Point Info

Optional. The stop point of the call. (May be updated in real time).

arrival

Arrival

 

departure

Departure

 

destinationDisplay

Destination Display

Optional

isCancelledCall

boolean

Optional. Only provided if true. Boolean that indicates if this is call is cancelled without being replaced. In this case the call to the above-mentioned stop should be presented as cancelled.

replacedJourneyPatternPoint

Journey Pattern Point info

Optional. Only provided if the original Journey Pattern Point is replaced. Describes the replaced point. Represents the original (planned) information

replacedStopArea

Stop Area Info

Optional. Only present if the original StopArea is replaced. Describes the replaced stop area. Represents the original (planned) information

replacedStopPoint

Stop Point Info

Optional. Only present if the original StopPoint is replaced. Describes the replaced stop point. Represents the original (planned) information

fetcherConnections

Array of connection Info

Optional. Planned fetcher (distributor) protected connections. A list of vehicle journeys that must wait for passengers from this vehicle journey at this stop even if it is delayed. Relevant for passenger information

feederConnections

Array of connection Info

Optional. Planned feeder protected connections. A list of vehicle journeys that this vehicle journey should await passengers from at this stop even if the feeding journeys are delayed. Relevant for driver information.

Fields of Journey Pattern Point Info

Name

Type

Description

ref

string

Id of journey pattern point.

isTimingPoint

boolean

Boolean that indicates if this is a point where the driver should respect the departure time.

location

Position

Optional. The position of the point in Latitude/Longitude.

distanceFromPrevious

number

Optional. Meters from previous point. The first call has the value zero

tariffZones

Array of Tariff Zone info

Optional. Tariff Zones valid for this point.

Fields of Position

Name

Type

Description

latitude

number

The latitude in decimal degrees.

longitude

number

The longitude in decimal degrees.

Fields of Stop Area Info

Name

Type

Description

ref

string

Id of the Stop Area

name

string

Full name. Max 50 characters.

shortName

string

Optional. Shortened name. Max 16 characters.

Fields of Stop Point Info

Name

Type

Description

ref

string

Id of the Stop Area

name

string

Full name. Max 50 characters.

shortName

string

Optional. Shortened name. Max 16 characters.

designation

string

Optional. Track, gate, stop etc. as shown to the public. This is for local orientation within a stop area, bus terminal or station.

localNumber

number

The display order of stops within a stop area.

length

number

Optional. The stops capacity in meters.

stopPointKeys

Array of Key

Optional. Array with point specific information

Fields of Arrival

Name

Type

Description

latestDateTime

string

The latest arrival time expected according to original plan. Arrival after this time is LATE. ISO 8601, UTC

arrivalType

string

Usage of the arrival according to original plan. NoStop and StopNoBoarding means that the departure should NOT be presented public

Fields of Departure

Name

Type

Description

earliestDateTime

string

The earliest permitted departure time according to original plan. Departure before this time is EARLY. ISO 8601, UTC

departureType

string

Usage of the departure according to original plan. NoStop and StopNoAlighting means that the arrival should NOT be presented public.

 Fields of Organisation Info

Name

Type

Description

ref

string

A unique identifier

code

string

Short abbreviation.

name

string

Full name

number

string

The number of the object that the organisation info refers to. Transport Authority number or Contractor Number.

Fields of Key

Name

Type

Description

deviceName

string

Name of devices for which this key applies.

typeCode

string

Name of data type.

parameterData

string

The data formatted in an agreed (that could be customer specific) format for the specified DeviceName and TypeCode.

Fields of Tariff Zone info

Name

Type

Description

ref

string

A unique identifier.

number

string

The number of the tariff zone unique within the transport authority.

code

string

Optional. Short abbreviation.

name

string

Optional. Full name.

Fields of Connection info

Name

Type

Description

connectionRef

string

Identifier used for matching with real-time data in later stage. Is unique in scope of current vehicle journey and call sequenceNumber. Typically has the value of the connecting journeys directionOfLineRef.

transportModeCode

string

The transport mode. “BUS”, “TRAM” etc.

lineAuthorityCode

string

Short abbreviation for the organisation providing the connecting journey. “SJ”, “ÖTåg”, “SL” etc

lineDesignation

string

The public line number displayed to passengers for the connecting journey. Observe that this value can be alphanumeric!

directionName

string

Optional. Name of direction for connecting journey.

stopAreaName

string

Optional. Name of stop for the connecting journey. Only included if different stop than the stop this vehicle stops at.

stopPointDesignation

string

Optional. Platform/track/gate number or letter as shown to the public for the stop of the connecting journey. This is for local orientation within a stop area, bus terminal or station.

minChangeDurationSeconds

number

The minimum number of seconds needed to transfer (walk) between the involved vehicles. May need to be multiplied by some factors depending on different passenger abilities.

maxWaitingUntilTime

string

Optional. The date and time when the connection guarantee ends. The fetcher vehicle may leave at this time even if feeder vehicle has not yet arrived. ISO 8601, UTC

 

Example

 

 

3.4        Expected Call

 

Topic

{PTO}/ruter/vehicleID}/oi/current_vehicle_journey/expected_call

 

Retain

Yes

 

QoS

1

 

The topic should provide a consistent set of current information describing the vehicle’s current, previous and next stop(s) including estimated times, observed times and additional information helping the driver to adhere to the operation control centre’s current plan for this vehicle. The topic is focused on the stop that the vehicle is standing at or will arrive to next in the case that the vehicle is between stops. The topic should be blanked (provided as a retained message with a zero-byte payload) if the vehicle has left the last stop and if it is not known what the next vehicle journey will be.

Fields                                                                  

Name

Type

Description

updatedAtDateTime

string

Time when last updated. ISO 8601, UTC

vehicleJourneyRef

string

A Vehicle Journey identifier.

callSequenceNumber

number

Order number of stop in journey pattern.

pointRef

string

A stop identifier.

tariffZone

TariffZone

Optional. The tariff zone of the stop

atStop

Boolean

True if vehicle is standing at (has arrived to) the stop. False when between stops.

estimatedTimeOfArrival

string

Optional. Only provided if the vehicle has not arrived at this stop. ISO 8601, UTC

observedTimeOfArrival

string

Optional. Only provided if the vehicle has arrived at this stop. ISO 8601, UTC

estimatedTimeOfDeparture

string

Optional. Usually not provided for the last call of the journey. ISO 8601, UTC

serviceDeviation

number

Value related to timetable or regularity depending on operation mode. A negative value indicates the number of seconds the vehicle journey is behind optimal time and a positive value indicates the number of seconds it is ahead of optimal time.

holdReason

string

Optional. Only provided if vehicle should hold. Describes the reason why the driver should hold at this stop. Possible values: “CONNECTION_PROTECTION”, “TIMING_POINT”, “DRIVER_CHANGE”

holdUntil

string

Optional. Only provided if vehicle should hold. Time of earliest permitted departure. ISO 8601, UTC

restriction

string

Optional. Only provided if boarding or alighting restriction applies based on a combination of planned restrictions and partial journey cancellations. Possible values: “NO_BOARDING”, “NO_ALIGHTING”, “NO_STOP”.

previousCall

Call

l Optional. Describes the call to the stop immediately preceding the expected call. Only provided if there is at least one call in the journey before the expected call.

laterCalls

Array of Calls

Optional. Only provided if there are any calls in the journey after the expected call. Describes a configured number of calls that follow in sequence after the expected call. Note that the first item in the list represents the “next stop” only when the vehicle is standing at a stop. If the vehicle is between stops then the first item represents the first stop after the next stop. The configured max number of later Calls to be expected should be provided in configValue01 for this topic under topic tobs/mi/provider_clients//provided_topics.

 

Fields of Call                                                                     

Name

Type

Description

callSequenceNumber

number

Order number of stop in journey pattern. (One-based list)

pointRef

string

A stop identifier.

estimatedTimeOfArrival

string

Optional. Only provided if the vehicle has not arrived at this stop. ISO 8601, UTC

observedTimeOfArrival

string

Optional. Only provided if the vehicle has arrived at this stop. ISO 8601, UTC

estimatedTimeOfDeparture

string

Optional. Usually not provided for the last call of the journey. ISO 8601, UTC

observedTimeOfDeparture

string

Optional. Only provided if the vehicle has departed from this stop. ISO 8601, UTC

restriction

string

Optional. Only provided if boarding or alighting restriction applies based on a combination of planned restrictions and partial journey cancellations. Possible values: “NO_BOARDING”, “NO_ALIGHTING”, “NO_STOP”.

 Fields of Tariff Zone info

Name

Type

Description

ref

string

A unique identifier.

number

string

The number of the tariff zone unique within the transport authority.

code

string

Optional. Short abbreviation.

name

string

Optional. Full name.

 

Example

3.5        Current Destination Display

Topic

{PTO}/ruter/{vehicleID}/oi/current_destination_display/text

Retain

Yes

QoS

1

 

Fields                                                                  

Name

Type

Description

number

number

Optional. Numeric value representing the destination display text.

name

string

The name of the (primary) destination or a free text. Shall be placed on line one of the display, if alternativeText is also present

alternativeText

string

Optional. The name of the secondary destination or an alternative (free) text.

Shall be placed on the second line of the display if present.

lineDesignation

string

Optional. Displayed public line number or line code.

typeOfAlternativeText

string

Optional. The purpose of the alternative text. E.g. “COUNT_DOWN_TO_DEPARTURE”, “MESSAGE”, “VIA”, “END_STATION”, “TRANSFER_AT_THIS_STOP, “CONTINUE_TO”.

 

Example

4         Extended Information Topics

These topics are intended for announcements of adapted passenger information. It is possible to provide multiple topics in parallel with information in different languages

4.1        Deviation Information

Topic

{PTO}/ruter/{vehicleID}/ei/deviation_information/

Retain

Yes

QoS

1

This topic provides an adapted selection of deviation and incident information that is relevant for passengers onboard this vehicle in scope of what the vehicle is currently doing and where it is on the current vehicle journey. The information is provided in the form of a list of situation messages. This topic should be blanked (provided with empty content) if there are no relevant situation messages. As an added precaution an expiry timestamp is included to assure that outdated information is not presented.

Fields

Name

Type

Description

expiryDateTime

string

Do not present this information after this time. ISO 8601, UTC

heading

string

Optional. The heading to be displayed. E.g.: “Deviation information”

displayDurationSeconds

number

Optional. The recommended number of seconds the deviation information shall be presented. This value depends on the number of items and content type, reflecting the time it takes for a passenger to read it.

message

string

Optional. Text to be presented instead of situation messages when no deviation information is available due to technical problems or similar. E.g.: “Due to technical problems, deviation information cannot be displayed at the moment.”

situationMessages

Array of Situation Message

A list of situation messages that are currently relevant to the passengers onboard the vehicle at this point in the vehicle journey.

Fields of Situation Message

Name

Type

Description

heading

string

The message heading text

body

string

The message body text

 

Example

4.2        Transfer Information

Topic

{PTO}/ruter/{vehicleID}/ei/transfer_information

(was {PTO}/ruter/{vehicleID}/ei/expected_call/transfer_information )

Retain

Yes

QoS

1

 

This topic provides an adapted selection of real time information describing connecting lines at the current or the coming stop that passengers onboard this vehicle could transfer to. The information is provided in the form of a list of possible transfer options at the next stop.

This topic should be blanked (provided with empty content) when there is no relevant information to display.

As an added precaution an expiry timestamp is included to assure that outdated information is not presented.

Fields

Name

Type

Description

expiryDateTime

string

Do not present this information after this time. ISO 8601, UTC

heading

string

Optional. The heading to be displayed. E.g.: “Next departures from City Centre”

displayDurationSeconds

number

Optional. The recommended number of seconds the transfer options shall be presented. This value depends on the number of items and content type, reflecting the time it takes for a passenger to read it.

message

string

Optional. Text to be presented when no transfer option information is available for a stop where transfer options usually are presented. Example 1: “No departures from City Centre within the next 20 minutes”. Example 2: “Due to technical problems, departures cannot be displayed at the moment.”

transferOptions

Array of Transfer Option

A list of Transfer Options that are currently relevant to the passengers onboard the vehicle at this point in the vehicle journey.

 

Fields Transfer Option

Name

Type

Description

transportMode

string

Mode of transport: BUS, TRAIN, FERRY, METRO etc.

lineDesignation

string

The line designation to display. This is often a number but can also be alphanumeric. Normally 1- 4 characters.

destinationDisplayName

string

The name of the destination of the vehicle. This can be of any length but practically seldom over 30 characters.

directionOfLineName

string

Optional. The text denoting the direction of the vehicle. This can be of any length but practically seldom over 30 characters. E.g. “Towards City Centre”.

stopPointDesignation

string

Optional. The designation of the stop from where departure will occur. Typically, a single or double letter or a digit that distinguish this stop point from other stop points within the stop area.

presentedDepartureTimes

Array of Presented Departure Times

A list of adapted departure times to present.

Fields Presented Departure Time

Name

Type

Description

presentedDepartureTime

string

A text describing remaining time to departure. E.g. “4 min” or “Now”.

 

Example

 

4.3        Due Information

Topic

{PTO}/ruter/{vehicleID}/ei/due_information

(was {PTO}/ruter/{vehicleID}/ei/expected_call/due_information)

Retain

No

QoS

0

This topic provides an adapted text indicating that the vehicle is about to arrive at a stop according to what the coordinating application has concluded.

This could optionally be based on information provided in real-time from a back-office AVMS. However, if contact is lost with the back-office for more than a configured duration the information should be based on local information.

Fields

Name

Type

Description

expiryDateTime

string

Do not present this information after this time. ISO 8601, UTC

heading

string

Optional. The heading to be displayed. E.g.: “Arriving at”

body

string

The stop that the bus is approaching. E.g. “Broparken”

displayDurationSeconds

number

Optional. The recommended number of seconds the due information shall be presented. This value depends on the number of items and content type, reflecting the time it takes for a passenger to read it.

 Example

 

4.4        Audio Messages

Topic

{PTO}/ruter/{vehicleID}/ei/audio_message

Retain

No

QoS

0

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.

Fields

Name

Type

Description

eventDateTime

string

ISO 8601, UTC

expiryDateTime

string

Do not present this information after this time. ISO 8601, UTC

preferredStartDateTime

string

ISO 8601, UTC

ref

object

 

audio

Array of Audio

 

 

Fields of Audio

Name

Type

Description

encoding

string

«OPUS», or «MP3»

content

string

Optional. BASE64 encoded binary data. Do not use if contentURL is defined

contentURL

string

Optional. Location of content. Do not use if content is defined.

speaker

string

“INTERNAL”, “EXTERNAL” or “DRIVER”

volume

number

Volume in dB

 

Example

 

5         Driver Interaction Topics

5.1        Assignment Attempt

Topic

ruter/{PTO}/{vehicleID}/di/assignment_attempt/block

Retain

Yes

QoS

1

 

Describes an attempt to sign on or off a block from MADT, another GUI or from the PTO backoffice. The result of this request will be confirmed by the PTA backoffice and the results presented either on the topic ruter/{PTO}/{vehicleID}/oi/current_ block/state or the topic ruter/{PTO}/{vehicleID}/di/assignment_attempt_rejection/block.

Fields

Name

Type

Description

fromDateTime

string

Time, according to scheduled departure, from which the sign on/off applies. ISO 8601, UTC.

Eg. departure time of block, journey (partial servicing of block) or call on Journey (partial servicing of journey)

vehicleRef

string

ID of the vehicle/vessel.

blockRef

string

Optional. Not provided for sign off. Otherwise the Block identifier to be signed on.

apiVersion

string

“v2” for ADT v2.x.

Attribute in use by Ruter only. Not part of ITxPT specification.

assignmentType

string

“SIGNON” or “SIGNOFF”

Attribute in use by Ruter only. Not part of ITxPT specification.

assignmentCode

string

“PLANNED”, “EXTRA”, “SHORTENING”, “CANCELLED”, “BREAKDOWN”, “FINISHED” or “REPLACEMENT”

Attribute in use by Ruter only. Not part of ITxPT specification.

 5.1.1        Valid combinations of assignmentType and assignmentCode (NEW version 2.2)

assignmentType

assignmentCode

Usecase

assignmentType

assignmentCode

Usecase

SIGNON

PLANNED

Used when signing on to planned block. Vehicle is flagged as the main vehicle on the task

SIGNON

EXTRA

Used when signing an additional vehicle to a single journey within a block. Vehicle is flagged as extra, and will coexist on the same journey as the main vehicle

Each additional extra journey requires a new sign on.

Sign off with SIGNOFF - FINISHED

SIGNON

REPLACEMENT

Used when replacing a vehicle on a block with another vehicle. The main vehicle currently signed on to the block, will be signed off from the block. Any extravehicles will remain on their assigment

SIGNOFF

FINISHED

Used when signing off after a completed block.

SIGNOFF

SHORTENING

Used when signing off after a partly completed block

SIGNOFF

BREAKDOWN

Used to flag a SHORTENING due to vehicle malfunction.

SIGNOFF

CANCELLED

Used when signing off a block if parts, or the whole remainder of a previously signed on block is cancelled.

Any vehicle assigned to operate the cancelled blocks should sign on with SIGNON - REPLACEMENT

Other combinations of assignmentType and assignmentCode are not accepted.

 

Example

5.2        Assignment Attempt Rejection (upd 2.2)

Topic

{PTO}/ruter/{vehicleID}/di/assignment_attempt_rejection/block

Retain

No

QoS

0

Describes a negative result from the back-office of an attempt to sign on or off a block from MADT or another GUI.

Fields

Name

Type

Description

fromDateTime

string

Time from which the sign on/off was supposed to apply. ISO 8601, UTC

blockRef

string

Optional. Not provided for sign off. Otherwise the Block identifier.

result

string

Possible values: “INTERNAL_ERROR”, “TIMEOUT”, “SERVICE_CLOSED”, “NOT_SUCCEEDED”, “NOT_GRANTED”, “NOT_SUPPORTED”, “NOT_UNDERSTOOD”

errorText

string

Optional. Only provided if there is an error text.

Note; Corrected mistyped values in result. 

Example

 

5.3        Destination Display Override (upd 2.4)

Topic

ruter/{PTO}/{vehicleID}/di/override_attempt/destination_display

Retain

No

QoS

0

 

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

Fields

Name

Type

Description

number

number

Numeric value representing the destination sign information displayed. See 5.4

For destinations not in the predefined list, this value shall be null

atDateTime

string

ISO 8601, UTC. The time of the Override attempt

optional

name

string

The name of the (primary) destination or a free text.

optional

alternativeText

string

The name of the secondary destination or an alternative (free) text.

Optional

lineDesignation

string

Displayed public line number or line code.

Optional.

 

Example

 

 

 

5.4        Available Destination Displays (upd 2.2)

Topic

{PTO}/ruter/{vehicleID}/di/available_destination_displays

Retain

Yes

QoS

1

Fields

Name

Type

Description

atDateTime

string

ISO 8601, UTC. The time of the Display Text generation.

optional

availableDestinationDisplays

Array of DestinationDisplays

A list of destination display texts that can be manually selected.

 

Fields of Destination Display:

Name

Type

Description

number

number

Numeric value representing a destination display text.

name

string

The name of the (primary) destination or a free text. Shall be placed on line one of the display, if alternativeText is also present

alternativeText

string

The name of the secondary destination or an alternative (free) text.

Shall be placed on the second line of the display if present.

Optional

lineDesignation

string

Displayed public line number or line code.

Optional.

 Example

 

5.5        Operational Message To Driver

Topic

{PTO}/ruter/{vehicleID}/di/operational_message_to_driver

Retain

No

QoS

1

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

Fields

Name

Type

Description

heading

string

 

body

string

 

senderRef

string

 

atDateTime

string

 ISO 8601

 

Example

 

6. Proprietary Extensions

These are topics that do not exist in the ITxPT topic structure, but have been defined by Ruter. They are used for communication between Ruters backoffice and onboard systems (RuterSales and DPI).

6.1. Sales and Validation

Topic

ruter/{PTO}/{vehicleID}/pe/sales_validation

Retain

No

QoS

1

Note:

This topic will be deprecated from future versions, it is recommended to use sales, validation and Sales: Diagnostics described further down this document

Submits status of RuterSales application in the vehicle. The status can be submitted both at a periodic interval and when a ticket is sold or validated.

Fields

Name

Type

Description

status

string

  “OK”, or “ERROR”

validationOk

string

True if validation is positive

validationText

string

Text result from NOD

validationColor

string

Color result from NOD

validationSound

string

Sound result from NOD

nfcReaderConnected

string

True if NFC reader is connected

printerConnected

string

True if last connection attempt/print was successful

printerStatus

string

Latest status from printer if printerConnected is false

nodAvailable

string

True if app is able to reach NOD

sapiAvailable

string

True if app is able to reach NOD

loggedIn

string

True if a user currently is logged in

atDateTime

string

When the ticket is sold/validated or the timestamp for periodic reporting e.g. 1/min.

 

6.2 Sales: Diagnostics (new version 2.1)

Topic

ruter/{PTO}/{vehicleID}/pe/sales/diagnostics

Retain

No

QoS

1


Health status for the Sales application "RuterSalg" and its peripheral connections. Diagnostics are performed and results are sent every minute.

Name

Type

Description

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC. The time of this diagnostics message generation

nfcReaderConnected

boolean

True if the NFC reader is discovered and connected by the app

printerConnected

boolean

True if the printer is discovered and connected, and if the previous communication with the printer was a print operation the print was a success

printerStatus

string

Optional. If printerConnected is false, printerStatus might contain last errorMessage from printer if available, or error message from the sales device if unavailable

nodAvailable

boolean

True if the app can contact the NOD backend

sapiAvailable

boolean

True if the app can contact the SAPI backend

loggedIn

boolean

True if a user is logged into the app

journeyRef

string

Last received journeyRef. Obtained from last received Journey message.

stopPlaceId

string

Last received stopPlaceId. Obtained from last received NextStop message with a valid Ruter zone

Mistyped in v. 2.1

appVersion

string

Version of the client application on Semantic Versioning format

Example

6.3 Sales: Sale (new version 2.1)

Topic

ruter/{PTO}/{vehicleID}/pe/sales/saleresult

Retain

No

QoS

1


Sale result message generated by RuterSalg after each ticket order. This topic is intended as a live view of sales for health monitoring performance insight purposes. Must not be used for accounting, settlement or other financial calculations.

Fields

Root level

Name

Type

Description

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC. The time of this sale result message generation

paymentMethod

integer

Payment method used for sale. 45 = CASH, 46 = CARD, 50 = TPURSE

mediaType

integer

Media used for sale. 1 = DESFIRE ("reisekort"), 3 = ULTRALIGHT ("impuls"), 4 = PAPER

vendorId

string

User who sold the ticket

tickets

Ticket[]

Array of tickets in this sale



Ticket

Name

Type

Description

Name

Type

Description

numberOfZonesToPay

integer

Number of zones to pay for

passengers

Passenger[]

Passengers in this ticket

price

integer

price of ticket (in øre)

startDate

string

ISO 8601, UTC

zoneFrom

string

Start zone name

zoneTo

string

Destination zone  name

zoneVia

string

Via zone name

externalId

string

Ruter Sales Client reference to ticket

productTemplateId

long

Type of ticket

selectedZones

string[]

Array of zones of underlying ticket (for additional tickets only)



Passenger

Name

Type

Description

Name

Type

Description

numberOfPassengers

integer

Quantity of this passenger

productId

integer

Product ID of this passenger

profileId

integer

Profile ID of this passenger

Example 1 - Single ticket paper

Example 2 - travel card ticket paid with prepaid travel card money

 

6.4 Sales: Validation (new version 2.1)

Topic

ruter/{PTO}/{vehicleID}/pe/sales/validationresult

Retain

No

QoS

1


Validation result message generated by RuterSalg after validation of Travel card ticket. This topic is intended as a live view of validation count and results. 

Fields

Root level

Name

Type

Description

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC. The time of this diagnostics message generation

buzzerCommand

BuzzerCommand

Buzzer sound result of validation

inspectionResult

InspectionResult

Validation result details

ledCommand

LedCommand

Color result of validation

BuzzerCommand

Name

Type

Description

Name

Type

Description

duration

integer

Duration of each buzz in ms

frequency

integer

Frequency to be used for buzzes

pause

integer

Pause between each buzz in ms

repeat

integer

The number of times the buzz should be repeated

InspectionResult

Name

Type

Description

Name

Type

Description

code

integer

Validity code returned by NOD

message

string

Message to be displayed to user

validity

string

Can be either VALID or INVALID, might change in the future (by for example adding an UNKNOWN for students/seniors)

LedCommand

Name

Type

Description

Name

Type

Description

color

string

Color to be displayed ("red" and "green" are the possible values as of now)

duration

integer

Duration in ms the color should be displayed

pause

integer

How long the pause should be between each time the color is displayed

repeat

integer

The number of times the color should be displayed

Example

 

6.5 DPI Command

Topic

{PTO}/ruter/{vehicleID}/pe/dpi_command

Retain

No

QoS

1

The c2 channels are 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 of Trigger display of campaign The payload is defined as an object with no structure to provide flexibility.

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601

type

string

 

payload

object

 

 

Example

 6.6 DPI extensions (new version 2.1)

Topic

{PTO}/ruter/{vehicleID}/pe/dpi/#

Retain

As published in message

QoS

As published in message

Topic

ruter/{PTO}/{vehicleID}/pe/dpi/#

Retain

As published in message

QoS

As published in message

It is in Ruters interest to provide a rich and dynamic personal user experience onboard our vehicles. To provide flexibility these two topics and corresponding subtopics must be bridged between Ruter BO and the vehicle. Data will be produced and consumed only by Ruters systems.

No payload structure is defined.

6.7 DPI Diagnostics

Topic

ruter/{PTO}/{vehicleID}/pe/dpi_diagnostics

Retain

No

QoS

1

It is expected that the DPI application itself will produce diagnostic messages. The payload is defined as an object with no structure to provide flexibility.

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601

screenId

string

 

type

string

“STATUS” or “HEARTBEAT”

payload

dictionary of any

 

 

Example

 

 6.8 DPI Acknowledge (updated v. 2.2)

Topic

ruter/{PTO}/{vehicleID}/pe/dpi_ack

Retain

No

QoS

1

The DPI Ack topic is used to inform the Ruter BO about the content presented on the PTO’s own systems for Dynamic Passenger Information in the vehicle. Usually, this is destination displays. The rest of DPI is presented by Ruter’s own DPI system, and does not need this kind of acknowledgement message.

For API versions ≤ 2.2 does not require production of dpi_ack on topics beside CURRENT DESTINATION DISPLAY.

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601

type

string

“AUDIO” or “DESTINATION”

payload

object

Destination text strings

 

Example

 

 6.9 Doors Individually

Topic

ruter/{PTO}/{vehicleID}/pe/doors_individually

Retain

No

QoS

1

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.

Fields

Name

Type

Description

doorRef

string

Has to be the same reference as is used in the topic sensors/apc_sensors.

isOpen

boolean

True if the door is open.

atDateTime

string

Timestamp when isOpen has changed, ISO 8601

 

Example

 

6.10 Door lock (tram only)

Topic

ruter/{PTO}/{vehicleID}/pe/doorlock

Retain

No

QoS

1

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

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC

locked

boolean

true or false

Example

 

6.11 Active cab (tram only)

Topic

ruter/{PTO}/{vehicleID}/pe/activecab

Retain

Yes

QoS

1

Used to keep track of what direction the train is driving

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC

activeCab

string

“c1”, ”c2” or “inactive”

Example

6.12 Vehicle direction (bidirectional vehicles only)

Topic

ruter/{PTO}/{vehicleID}/pe/vehicledirection

Retain

Yes

QoS

1

Alternative to 6.11, allowing to keep track of the direction of other bidirectional vehiclesF

ields

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC

vehicleDirection

string

“A” or ”B”

Example

 

6.13 Boarding status (boat only)

Topic

ruter/{PTO}/{vehicleID}/pe/bordingstatus

Retain

No

QoS

1

Topic used to notify about boarding possibilities.

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC

embarkationAllowed

Boolean

 

disembarkationAllowed

Boolean

 

Topic used to notify about boarding possibilities.

Example

 

6.14 Traffic Signal Priority

Topic

{PTO}/ruter/{vehicleID}/pe/tsp

Retain

No

QoS

0

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.

Fields

Name

Type

Description

eventTimestamp

string

ISO 8601, UTC

message

string

The 7 byte telegram, HEX encoded

 

Example