OTA Messages

Introduction

This page is an update of an outdated OTA Messages wiki page that was based on version 1.0 of the requirements. Version 1.1 of the requirements introduced some changes and after the development process began, new needs were identified as documented here, partly for use in formulating a change order for the operators selected for routes in Romerike and the electric bus contract.

Ruter has agreed with the operators to use only JSON in MQTT messages and not support Protobuf. The contents of the messages will therefore be defined by JSON schemas and these will be made available to the operators.

Summary

The summary refers to topics on board the buses. See below for mapping of the local topic to the bridged topic.

Changes noted in status are based on a comparison with v. 1.1 of the OTA Messages document. Direction is in/out of the bus.

Topics

signon/json 

JSON example

{
  "eventTimestamp": "2017-10-31T12:45:50Z",
  "vehicleNumber": "12345",
  "blockId": "1234:34",
  "vehicleJourneyId": "35:ABC"
}

Fields

Vehicle journey is required and helps track cases where blocks are interrupted and replacement vehicles take over.

signoff/json

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

avl/json

JSON example

{
  "eventTimestamp": "2017-10-31T12:45:50Z",
  "seqNumber": 0,
  "latitude": 60.25255,
  "longitude": 11.0567,
  "heading": 0.5,
  "speedOverGround": 34.5,
  "signalQuality": "AGPS_QUALITY",
  "numberOfSatellites": 4,
  "gnssType": "GPS",
  "gnssCoordinateSystem": "WGS84",
  "deadReckoning": false,
  "positionIsSimulated": false
}

Fields

Enum SignalQuality

Enum GNSSType

Enum GNSSCoordinateSystem

apc/+/json

JSON example

{
  "eventTimestamp": "2017-10-31T12:45:50Z",
  "doorId": 1,
  "passengerCounting": [{
    "objectClass": "ADULT",
    "doorPassengerIn": 1,
    "doorPassengerOut": 1
  }, {
    "objectClass": "CHILD",
    "doorPassengerIn": 0,
    "doorPassengerOut": 0
  }, {
    "objectClass": "PRAM",
    "doorPassengerIn": 0,
    "doorPassengerOut": 0
  }, {
    "objectClass": "WHEELCHAIR",
    "doorPassengerIn": 0,
    "doorPassengerOut": 0
  }],
  "doorCountQuality": "REGULAR"
}

Fields

APC

PassengerCount

Enum ObjectClass

Enum CountQuality

stopsignal/json

JSON example

{
  "eventTimestamp": "2017-10-31T12:45:50Z",
  "stopSignalled": true
}

Fields

telemetry/+/json

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

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

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

Source identifiers will be:

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

FMS

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

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

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

FMS Parameter Group Number (PGN)

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

ITxPT

These PGNs must be subscribed to when the buses are started (unless the subscription is persistent) through the AddPGN call:

<PGNReq>FE4E</PGNReq>
<PGNReq>FDA5</PGNReq>
<PGNReq>FEC1</PGNReq>

A service must be implemented by the operator's vendor that listens the UDP messages and converts them to MQTT messages.

XML format (source)

The message for all subscribed PGNs is sent to UDP as XML.

<FMStoIPDelivery>
    <FMStoIP FMSVersion="03">
        <frame Status="OK">
            <PGN>FEF1</PGN>
            <data>F35237C403501FFF</data>
            <relativetime>5000</relativetime>
            <SPN id="84">
                <name>Wheel-Based Vehicle Speed</name>
                <unit>km/h</unit>
                <value>55.3</value>
            </SPN>
            <SPN id="597">
                <name>Brake Switch</name>
                <value>released</value>
            </SPN>
        </frame>
        <frame Status="OK">
            <PGN>F004</PGN>
            <data>F35237C403501FFF</data>
            <relativetime>5000</relativetime>
            <SPN id="190">
                <name>Engine Speed</name>
                <unit>rpm</unit>
                <value>854</value>
            </SPN>
        </frame>
    </FMStoIP>
</FMStoIPDelivery>

PGN FEF1 og F004 shown here are the examples found in the ITxPT spec.

JSON format (MQTT)

The message containing several PGNs is split up into several MQTT messages. SPNs are mapped as subids.

telemetry/0000fef1/json

{
    "eventTimestamp": "2017-10-31T12:45:50Z",
    "id": "0000FEF1",
    "payloads": [
        {
            "subid": 84,
            "name": "Wheel-Based Vehicle Speed",
            "unit": "km/h",
            "value": 55.3
        },
        {
            "subid": 597,
            "name": "Wheel-Based Vehicle Speed",
            "value": "released"
        }
    ]
}

telemetry/0000f004/json

{
    "eventTimestamp": "2017-10-31T12:45:50Z",
    "id": "0000F004",
    "payloads": [
        {
            "subid": 190,
            "name": "Engine Speed",
            "unit": "rpm",
            "value": 854
        }
    ]
}

Fields

Telemetry

Payload

tsp/json

This message is generated by Ruter when approaching an intersection or, when a stop is just before an intersection, after the doors have closed.

JSON example

{
    "eventTimestamp": "2017-10-31T08:38:02.749Z",
    "message": ""
}

Fields

madt/notification/json

Notice: Documentation of this message can be found here: ruterno.github.io

infohub/dpi/journey/json

The coordinates of the stop have been added to facilitate backup calculations for stop announcements and possibly other messages.

JSON example

{
  "eventTimestamp": "2017-10-31T08:38:02.749Z",
  "route": {
    "id": "RUT:Route:31-1041",
    "name": "Fornebu vest-Tonsenhagen",
    "line": {
      "id": "RUT:Line:31",
      "name": "Snarøya - Fornebu - Tonsenhagen - Grorud",
      "publicCode": "31"
    },
    "stopPlaces": [
      {
        "id": "RUT:StopPlace:02190017",
        "name": "Fornebu vest",
        "connections": [],
        "location": {
            "latitude": 12.33345,
            "longitude": 12.33345
        }
      },
      {
        "id": "RUT:StopPlace:03010013",
        "name": "Jernbanetorget",
        "connections": [
          {
            "line": {
              "id": "RUT:Line:30",
              "name": "Bygdøy via Bygdøynes",
              "publicCode": "30"
           },
           "type": "BUS",
           "color": "e60000"
         },
         {
           "line": {
             "id": "RUT:Line:12",
             "name": "Majorstuen",
             "publicCode": "12"
           },
           "type": "TRAM",
           "color": "0b91ef"
          }
        ],
        "location": {
            "latitude": 12.33345,
            "longitude": 12.33345
        }
      }
    ]
  }
}

Fields

Journey

Route

Line

StopPlace

Connection

Location

Enum TransportType

infohub/dpi/nextstop/json

StopPointRef was replaced by StopPlaceId in v. 1.1.

JSON example

{
    "eventTimestamp": "2017-10-31T08:38:02.749Z",
    "stopPlaceId": "RUT:StopPlace:03012453"
}

Fields

infohub/dpi/eta/json

StopPointRef was replaced by StopPlaceId in v. 1.1. The field "text" was added to send the desired display text for the arrival time.

JSON example

{
	"eventTimestamp": "2017-10-31T08:38:02.749Z",
	"estimatedCalls": [
		{
			"eta": "2017-10-13T12:27:04Z",
			"stopPlaceId": "RUT:StopPlace:03010510",
			"text": "Nå"
    	},
		{
			"eta": "2017-10-13T12:27:04Z",
			"stopPlaceId": "RUT:StopPlace:03010511",
			"text": "5 min"
    	}
  	]
}

Fields

EstimatedCall

infohub/dpi/externaldisplay/json

JSON example

{
  "eventTimestamp": "2017-10-31T08:38:02.749Z",
  "publicCode": "31",
  "destination": "Lorem ipsum",
  "alternativeMessage": "Duis aute irure dolor"
}

Fields

infohub/dpi/arriving/json

StopPointRef was replaced by StopPlaceId in v. 1.1. The field createTimestamp was removed in v. 1.1. Multi-lingual suoport added in v.1.2

The field expiryTimestamp has been added to to prevent delayed messages from being played after a certain amount of time.

JSON example

{
  "eventTimestamp": "2017-10-31T08:38:02.749Z",
  "expiryTimestamp": "2017-10-31T08:38:47.749Z",
  "ref": "RUT:StopPlace:03012453",
  "zoneId": "2b-vest",
  "message": {
    "no": {
      "title": "Ankommer"
      "text": "Oslo sentralstasjon"
    },
    "en": {
      "title": "Arriving at"
      "text": "Oslo Central Station"
    }
  }
}

Fields

MultilingualMessage

infohub/dpi/deviation/json

The ref field has been added to specify the scope of the deviation. This should be an NSR ID (where the type is included in the ID) such as StopPlaceId, QuayId, LineId, RouteId, JourneyId, OperatorId or AuthorityId. It is possible additional identifiers may be included.

JSON example

{
    "eventTimestamp": "2017-10-31T08:38:02.749Z",
    "expiryTimestamp": "2017-10-31T08:38:47.749Z",
    "ref": [
        "NSR:StopPlace:2561",
		"NSR:StopPlace:2562"
    ],
    "message": {
        "no": {
            "title": "afsdf",
            "text": "Lorem ipsum dolor sit amet"
        },
        "en": {
            "title": "afsdf",
            "text": "Lorem ipsum dolor sit amet"
        }
    }
}

Fields

Responsibility for the use of the ref field lies entirely with the DPI application. When it has matching ids it can tailor the information display accordingly. An example of this is stopPlaceId deviations.

MultilingualMessage

infohub/dpi/announcement/json

Message contains a reference to the scope of the message, if applicable. Typically NSR stopplaceid / lineId or similar. 

JSON example

{
    "eventTimestamp": "2017-10-31T08:38:02.749Z",
    "expiryTimestamp": "2017-10-31T08:38:47.749Z",
	"type": "INFO",
    "ref": [
        "NSR:StopPlace:2561",
		"NSR:StopPlace:2562"
    ],
    "message": {
        "no": {
            "title": "afsdf",
            "text": "Lorem ipsum dolor sit amet"
        },
        "en": {
            "title": "afsdf",
            "text": "Lorem ipsum dolor sit amet"
        }
    }
}

Fields

MultilingualMessage

infohub/dpi/audio/json

Notice: Documentation of this message can be found here: ruterno.github.io

infohub/dpi/c2/json

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

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

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

JSON example - DEBUG

{
    "eventTimestamp": "2018-10-31T12:45:50Z",
    "type": "DEBUG",
    "payload": {
		"command": "LOG_TRANSFER",
		"arg": {
			"level": "ERROR",
			"limit": 10,
			"page": 0
		}
    }
}

JSON example - SET_ITEM

{
    "eventTimestamp": "2018-10-31T12:45:50Z",
    "type": "WORKER_JOB",
    "payload": {
		"command": "SET_ITEM",
		"arg": {
			"name": "enableFeatureX",
			"value": true
		}
    }
}

Fields

infohub/dpi/diagnostics/json

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. 

The types illustrated below are example of possible messages. The types are under discussion but will be generated entirely by the DPI application and consumed by the PTA BO.

JSON example - STATUS

{
    "eventTimestamp": "2018-10-31T12:45:50Z",
    "screenId": "ad71dba8-c881-11e8-a8d5-f2801f1b9fd1",
    "type": "STATUS",
    "payload": {
        "version": {
            "application": "2018-10-03T12:45:50Z",
            "media": "2018-10-05T12:45:50Z",
        },
        "display": {
            "type": "1",
            "res": {
                "height": 360,
                "width": 1080
            }
        },
        "stats": {
            "logEntries": {
                "error": 0,
                "warning": 14,
                "info": 123
            },
            "lastLoaded": "2018-10-31T12:45:45Z",
			"pingFreq": 3600
            "usedStorage": "124kb"
        }
    }
}

JSON example - HEARTBEAT

{
    "eventTimestamp": "2018-10-31T12:45:50Z",
    "type": "HEARTBEAT",
    "screenId": "ad71dba8-c881-11e8-a8d5-f2801f1b9fd1",
}

Fields

Enum DiagnosticType

Other types of messages may be defined later.

Planned Topics

infohub/dpi/connections/json

This message is intended to be sent before the bus comes to the next stop. It is possible that it is sent only once, but it may also be updated if the view changes.

infohub/dpi/digitalsignage/json

When we begin to deliver packages of media to the buses, for example, in connection with campaigns, we must be able to trigger playlists as needed, for example at a stop, a time, etc.

Summary of Changes