1 Overview

This API description covers Ruter’s ADT agreement v2.1. 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) in the heading.

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

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 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. E.g. “ADULT”, “CHILD”, “PRAM”, “BIKE”, “WHEELCHAIR”
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

(edit 06-2021: mistyped example)

2.7 Telemetry

Topic	ruter/{PTO}/{vehicleID}/sensors/telemetry
Retain	No
QoS	0

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.

Available Non-FMS standard data identifiers

Optional unless stated explicitly in the main ADT document.

ID	Subid	Name	Value	Recommended refresh interval	Remarks
0001FF25	10003	Wall Charger connected		onChange
0001FF25	10004	Fast Charger connected		onChange
0001FF25	10005	Charging Active		onChange
01000002		Temperature inside average	float	1/min
01000005		SOC	float	1/min
01000006		Transmission mode	combustion/electric	onChange	Intended for hybrid vehicles
01000007		Windscreen wiper active	True/false	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		1/min	· Bandwidth >= 100 hz · Resolution <= 0.01 g
	xmin	Min x value last minute	g
	xmax	Max x value last minute	g
	xavg	Average x value last minute	g
	ymin	Min y value last minute	g
	ymax	Max y value last minute	g
	yavg	Average y value last minute	g
	zmin	Min z value last minute	g
	zmax	Max z value last minute	g
	zavg	Average z value last minute	g
01000009		Outdoor temperature	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

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.

Fields

Name	Type	Description
eventTimestamp	string	ISO 8601, UTC
id	string	Eight digit hex as defined above
messageNumber	number	Sequence number, increased by one for each new message. Used to validate consistency in the data stream Unique for each sensor ID Optional
payloads	Array of Payload	If FMS data or accelerometry, one payload per SPN. Else, one payload

Fields of Payload

Name	Type	Description
subid	string	Optional. Only to be used for SPN
name	string	Optional
unit	string	Optional
value	any

Examples

Accelerometry:

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.
alternativeText	string	Optional. The name of the secondary destination or an alternative (free) text.
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 sheduled 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.

Example

5.2 Assignment Attempt Rejection

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_SUCCEDED”, “NOT_GRANTED”, “NOT_SUPPORTED”, “NOT_UNDERSTOOD”
errorText	string	Optional. Only provided if there is an error text.

Example

5.3 Destination Display Override

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 to display

Example

5.4 Available Destination Displays

Topic	{PTO}/ruter/{vehicleID}/di/available_destination_displays
Retain	Yes
QoS	1

Fields

Name	Type	Description
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	A destination display text

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)

Topic	ruter/{PTO}/{vehicleID}/pe/sales/diagnostics
Retain	No
QoS	1

Health status for the Sales application "Ruter Salg" and it peripheral connections. Diagnostics performed and reuslts sent before every stop.

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	boolean string	Last received stopPlaceId. Obtained from last received NextStop message with a valid Ruter zone Note: Mistyped in this version.

Example

6.3 Sales: Sale (new)

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)

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)

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

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.

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

API v. 2.1

1 Overview

1.1 Upgrades to the API

1.2 Consumer Client Requirements

1.3 Quality of Service, Retained Flag and Persistence

1.4 List of topics

1.5 Translation of topic names

2 Sensor Topics

2.1 Stop Button

2.2 Door

2.3 Location

2.4 Odometer

2.5 Clock

2.6 APC sensors

2.7 Telemetry

Available Non-FMS standard data identifiers

3 Operational Information Topics

3.1 Unique Identifier

3.2 Current Block

3.3 Vehicle Journey Details

3.4 Expected Call

3.5 Current Destination Display

4 Extended Information Topics

4.1 Deviation Information

4.2 Transfer Information

4.3 Due Information

4.4 Audio Messages

5 Driver Interaction Topics

5.1 Assignment Attempt

5.2 Assignment Attempt Rejection

5.3 Destination Display Override

5.4 Available Destination Displays

5.5 Operational Message To Driver

6. Proprietary Extensions

6.1. Sales and Validation

6.2 Sales: Diagnostics (new)

Example

6.3 Sales: Sale (new)

Fields

Example 1 - Single ticket paper

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

6.4 Sales: Validation (new)

Fields

Example

6.5 DPI Command

6.6 DPI extensions (new)

6.7 DPI Diagnostics

6.8 DPI Acknowledge

6.9 Doors Individually

6.10 Door lock (tram only)

6.11 Active cab (tram only)

6.12 Traffic Signal Priority