Avtale om digitale tjenester - ADT 3.0.3

AssignmentAttemptRequest Message

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

AssignmentAttemptRequest Usage

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

An AssignmentAttemptRequest can be made for:

Action	Description
SignOn	Creating an Assignment for a vehicle. Signing a vehicle on to a set of planned journeys/stops
SignOff	Signing a vehicle off from an assigned assignment
Update	Altering an existing assigned assignment

• The message is composed of three operations (signOn, signOff, update). Only one operation will be processed per message received by Ruter. This gives that each message should only contain one operation. If the message contains more than one operation, the order of precedence is the following:
  1. signOn
  2. signOff
  3. update
• Attempt request will get an attempt response under the response topic
• Any request leading to a change of existing assignment state is reflected under the status topic
  • This topic will also be updated when Ruter has initiated any change to the existing assignment
• Please provide all fields marked as reqired in the schema specifications.

Definitions

• A block contains a set of journeys.
• A vehicleTask is a set of one or more blocks that can be served by one vehicle during one operating day. In the example below, the vehicle task with vehicleTaskId=59001 consists of the 2 Blocks with <PrivateCode>59001</PrivateCode>.

Example of NeTEx definition of a vehicle task with 2 blocks

<VehicleScheduleFrame version="20220908125021" id="RUT:VehicleScheduleFrame:1">
  <blocks>
    <Block version="20220908125021" id="RUT:Block:168197-59001mut-202209081312000">
      <PrivateCode>59001</PrivateCode>
      <StartTime>11:12:00</StartTime>
      <EndTime>14:41:00</EndTime>
      <dayTypes>
        <DayTypeRef ref="RUT:DayType:2022-09-08"/>
      </dayTypes>
      <StartPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
      <EndPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
      <journeys>
        <DeadRunRef ref="RUT:DeadRun:006723-008020-131200"/>
        <VehicleJourneyRef ref="RUT:ServiceJourney:003565-004003-131500"/>
        ...
      </journeys>
    </Block>
    <Block version="20220908125021" id="RUT:Block:168197-59001muwt-202209080359000">
      <PrivateCode>59001</PrivateCode>
      <StartTime>01:59:00</StartTime>
      <EndTime>06:16:00</EndTime>
      <dayTypes>
        <DayTypeRef ref="RUT:DayType:2022-09-08"/>
      </dayTypes>
      <StartPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
      <EndPointRef ref="RUT:ScheduledStopPoint:Fg" version="20220908125021"/>
      <journeys>
      <DeadRunRef ref="RUT:DeadRun:006713-008006-035900"/>
      <VehicleJourneyRef ref="RUT:ServiceJourney:002521-002932-041700"/>
      ...
      </journeys>
    </Block>
  </blocks>
</VehicleScheduleFrame>

Sign On

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

Sign On - PLANNED

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

Sign On - EXTRA

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

Sign On - REPLACEMENT

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

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

Sign Off

Sign Off - FINISHED

The vehicle has serviced all journeys in the assignment

Sign Off - BREAKDOWN

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

Sign Off - CANCELLED

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

Sign Off - SHORTENING

Same as CANCELLED

Additional Sign Off codes used by RUTER

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

Update

Update - SHORTENING

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

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

• serviceWindow is honoured as SignOn - PLANNED

Example case for SHORTENING

Given an assignment (vehicle plan) with two journeys:

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

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

When SHORTENING

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

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

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

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

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

AssignmentOmitRequest Message

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

AssignmentOmitRequest Usage

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

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

Omit - NO_INTENTION

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

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

ActiveCab Message

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

DoorLock Message

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

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

Frequency: on change

DoorsIndividually Message

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

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

Apc Message

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

Door Message

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

Frequency: on change

Location Message

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

Describes the GNSS navigation receiver feedback in metric format.

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

Frequency is expected to be at 1 message per second.

Odometer Message

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

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

Frequency is expected to be at 1 message per second.

StopButton Message

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

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

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

Frequency: on change

Telemetry Message

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

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

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

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

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

The identifiers are constructed this way:

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

Available Non-FMS standard data identifiers

Optional unless stated explicitly in the main ADT document.

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

Destination Display Override Message

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

Acknowledge Message

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

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

Ruter shall receive an acknowledgment message for the following topics:

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

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

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

Diagnostics Message

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

Report to PTA BO about a screen.

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

RuterSalg diagnostics

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

Diagnostics message generated by RuterSalg.

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

VIX Card Reader Diagnostics MQTT Message

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

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

RuterSalg current_stop

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

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

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

AssignmentAttemptResponse Message

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

AssignmentAttemptResponse Usage

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

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

State

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

Additional codes used by RUTER

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

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

AssignmentStatus Message

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

AssignmentStatus Usage

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

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

AssignmentAttemptResponse Message

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

AssignmentAttemptResponse Usage

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

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

Available Destination Displays Message

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

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

Operational Message to Driver Message

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

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

Audio Message

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

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

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

Journey Message

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

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

Nextstop Message

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

Next stop on the buss route after leaving a stop.

Eta Message

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

Estimated arrival at the remaining stops.

Externaldisplay Message

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

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