Document

Contents

ODEx-1. Concepts and Functional Architecture

Core Concepts, functional specification and topic structure

ODEx-2. Network Requirements

Onboard IP Network requirements to support ODEx onboard communication

ODEx-3. Inventory and Updates Interfaces

Inventory, status and updates interfaces data definitions

ODEx-4. Operational Interfaces (This document)

Operational interfaces data definitions and topics

ODEx-5. Usage and Examples

Practical guidelines and implementation examples

Operational Data Domains

Content

Physical Vehicle

Vehicle Telemetry

Information related to the physical vehicle and its base (non ITS) equipment: vehicle static data (ID, vehicle specifications) CAN J1939 data, GNSS data, data from sensors (e.g. odometer, accelerometer, internal thermometers…) and data from signals (e.g. ignition, doors status).

Vehicle PT Operation

Ticketing

Validation and ticket sales transactions and other information related to ticketing

Vehicle Service Monitoring

Information related to the service run by the vehicle: network location, driver, vehicle journeys and calls observed, monitored and estimated, status with respect to planned and target services vehicle service assigmnet and driver messages.

Occupancy

Passenger counting, %occupancy, passenger density, occupancy status (e.g. vehicle full)

External information relevant to be published onboard

(Future)

Ambient Conditions

External ambient conditions: temperature, relative humidity, atmospheric pressure, meteorology conditions and predictions, air quality or others that can be published onboard and used by a passenger information system to inform passengers onboard or by other systems to log data with ambient conditions metadata.

Facilities monitoring

Incidents in public transport facilities (e.g. elevator not working) published onboard for passenger information.

Incidents and events

Incidents (e.g. cancelation of services, delays ) and events affecting other services which can be relevant for passenger information onboard

Topics for DG with “streamed” data

Content

/stream_info

The standard JSON is published to this topic, including static or slow changing information which is common to all data published to /stream_data, which includes at least the time reference for the timestamp of the data samples published in /stream_data.

/stream_data

The DG “streamed” data is published to this topic using a non-standard, more compact, JSON structure, consisting only of a list of data samples, each one consisting of an array of data elements. Fon instance, in the case of Accelerations, each sample will include the timestamp and the X, Y and Z accelerations.

ODEx data and command JSON Structure

<Common fields for every ODEx JSON data or command message>

<Specific ODEx DataGroup or Command fields>

Common Message Format Fields

+Structure

Description

timestamp

1:1

DateTime

Timestamp of the message (see DateTime in Data Types)

topicPath

1:1

String

Full MQTT topic path where this message is being published

messageId

(See description)

String

Message UUID. Mandatory in command topics but could also be needed in data topics.

<specific field>

<Specific ODEx DataGroup or Command fields>

<specific field>

Etc.

Common Response Fields

+Structure

Description

<Common fields for every JSON command message>**

commandResult

1:1

String (Enum)

Result of the request command. See the following possible enums: OK | NOK

rejectionCode

0:1

Integer

Rejection code only if result is "NOK". See next table of possible rejection codes.

rejectionDescription

0:1

String

Optional human-readable error message

details

0:1

String

Optional debug information or notes.

responseContent

-

anyType

In command responses where some fields are required to be returned, they will be in the responseContent field structure.

Code

Meaning

0

OK

1

FAILED

2

BUSY

3

PARAMETER_ERROR

4

NOT_SUPPORTED

5

FORMAT_ERROR

6

OPERATION_ALREADY_EXECUTED

7

TIMEOUT

8

CANCELLED

9

QUEUE_OVERFLOW

10

DENIED

11

NOT_CONFIGURED

12

COMMAND_EXPIRED

…

(Extensions)

Cardinality

Meaning

0:1

Optional field, zero or one occurrence. If included, supply exactly one non-array value. If not included, remove both, the tag and the value.

1:1

Mandatory field, exactly one occurrence. It must appear once and carry a single non-array value.

The 1:1 cardinatility of a field inside a structure only applies if the structure is published, as the structure may have 0:1 cardinality.

0:*

Optional array, zero or more elements. The array itself may be absent; if present it may be empty [] or have any length.

1:*

Mandatory array, at least one element. The field must be present and the array must contain ≥ 1 items.

Notation

Description

String

UTF-8 text

String (Enum)

UTF-8 text restricted to a predefined set of literal values

Integer

Whole number (positive or negative).

Use a wider range (e.g., 64-bit) only when the field explicitly requires it.

Float

Numbers with a decimal point (positive or negative).

Boolean

true / false

DateTime

ISO-8601 UTC E.g. 2025-05-27T11:28:15Z

Object

JSON object (unordered key-value map)

anyType

Freely defined extension field (must be valid JSON)

Concept

Naming notation

Examples

OPIs

OPIS are named using snake_case (lower case letters and underscore)

network_location

In tittles, OPIs are named using Title Case

OPI Network Location

DataGroups

DataGroups are named using UpperCamelCase

NetworkLocationAll

Commands

Commands are named using snake case (lower case letters and underscore)

lock_validation

Topics

Topics are named using snake_case (lower case letters and underscore)

/network_location

/lock_validation

Variables and enums

Variables and enumerations are named using lowerCamelCase

journeyPatternRef

Trigger type

Description

startup

Triggered immediately after the MQTT client used by the Provider is connected to the broker.
This occurs at power-on of the Equipment Item hosting the Provider, after a reset of the Equipment Item, or after a broker reset or reconnection.

periodic

Triggered periodically at fixed time intervals (e.g. GNSS data published every 1s). If no value is defined in ODEx, it should be defined in the project.

discrete change

Triggered when at least one discrete variable of a Datagroup (e.g. boolean, enumerated, string, identifier) changes value. The complete DataGroup must be published reflecting the new values.

threshold change

Triggered when both of the following conditions are met:

• The value of at least one continuous (numeric) variable within the DataGroup has changed by more than an optional, predefined change threshold with respect to the last published value. (If no change threshold is defined in ODEx, it can be established in the project if needed); and
• At least T = 100 ms have elapsed since the previous publication of the same DataGroup, ensuring that the publication rate of any DataGroup does not exceed 10 messages per second.

When this trigger occurs, the Provider shall publish the entire DataGroup, reflecting the updated values.

Variables whose values need to be sampled more frequently (for example, hvessCurrent, every 20 ms or raw PGNs) should be included in specific DataGroups that, although published at intervals of 100 ms or longer, contain in each publication all the required values of the variable, each timestamped and recorded at the desired sampling rate. For example, if a value is required every 20 ms, the DataGroup published every 100 ms will include 5 recorded samples.

request

When explicitly requested (i.e. Publication on demand)

other

E.g. Publication triggered by movement or distance

<DG1_name>

+Structure

Description

<Common fields for every JSON data message>**

<specific field>

Cardinality

Type

Description

<specific field>

Cardinality

Type

Description

Etc.

<DG2_name>

+Structure

Description

<Common fields for every JSON data message>**

<specific field>

Cardinality

Type

Description

<specific field>

Cardinality

Type

Description

Etc.

<command_1_name>

+Structure

Description

<Common fields for every JSON data message>**

<specific field>

Cardinality

Type

Description

<specific field>

Cardinality

Type

Description

Etc.

<command_2_name>

+Structure

Description

<Common fields for every JSON data message>**

<specific field>

Cardinality

Type

Description

<specific field>

Cardinality

Type

Description

Etc.

Topic under …/<OPI_name>/<OPI_version>/cmd

Specific Fields**

+Structure

Description

<Common fields for every JSON data message>

/<command_1_name>

<command_1_field_1_name>

Cardinality

Type

Field description

/<command_2_name>

<command_2_field_1_name>

Cardinality

Type

Field description

<command_2_field_2_name>

Cardinality

Type

Field description

<command_2_field_3_name>

Cardinality

Type

Field description

/<command_3_name>

<command_3_field_1_name>

Cardinality

Type

Field description

…

<command_2_name>

+Structure

Description

<Common fields for every JSON data message>

< command_2_field_1_name>

Cardinality

Type

Description

<command_2_field_2_name>

Cardinality

Type

Description

<command_2_field_3_name>

Cardinality

Type

Description

VehicleId

+Structure

Description

<Common fields for every JSON data message>

vehicleRef

1:1

String

ID of the vehicle unit. VIN for bus.

licensePlate

1:1

String

Registration plate.

ptoVehicleId

1:1

String

Operator (PTO) vehicle ID.

ptaVehicleId

1:1

String

Authority (PTA) vehicle ID.

fleetNumber

1:1

String

Internal fleet number.

vehicleType

0:1

String (Enum)

bus | coach | tram | other (TBD more types as needed)

additionalInfo

0:1

String

Free text notes.

VehicleSpecs

+Structure

Description

<Common fields for every JSON data message>

makeModel

0:1

Object

Make & model object

manufacturer

1:1

String

Vehicle manufacturer brand (e.g., “Iveco Bus”, “Irizar”)

model

1:1

String

Model family/commercial name (e.g., “Crossway LE”, “i4”). Do not include length here

variant

0:1

string

Commercial variant label; may include length and use-case (e.g., “LE City 12 m”, “LE Line 12 m”)

homologationStep

0:1

String

Emission stage or propulsion label (e.g., “Euro VI Step E”, “Hybrid”, “CNG”, “BEV”)

axleConfig

0:1

String

Axle/drive layout (e.g., “4×2”, “6×2”)

dimensionsWeight

0:1

Object

Dimensions and Weight information

length

1:1

Integer

Vehicle length (mm)

width

0:1

Integer

Vehicle width (mm)

height

0:1

Integer

Vehicle height (mm)

wheelbase

0:1

Integer

Wheelbase (mm)

curbWeight

0:1

Integer

Vehicle weight with all standard equipment, but no passengers or cargo (kg)

grossCombinationWeight

0:1

Integer

Gross Combination Weight (kg).

powerPlant

0:1

Object

Power-plant related information

propulsionType

1:1

String (Enum)

Primary propulsion type: diesel | cng | hybrid | batteryElectric | fuelCell | other

engineModel

0:1

String

Manufacturer/model of the prime mover (ICE engine or electric family, include variant if known).
Examples: Cummins ISB6.7 280, Volvo D13K-500

maxPower

0:1

String

Rated power of the ICE (Internal Combustion Engine) or traction motor for BEV/hybrid. Example: “265 kW (360 hp) @ 2000 rpm”

maxTorque

0:1

String

Rated torque for ICE or e-motor where given (units: Nm). Example: “1600 Nm @1200 rpm”

emissionClass

0:1

String

Regulatory emission standard of the combustion engine.
Examples: Euro VI, Euro V...

driveLayout

0:1

String

Driven-wheel configuration. Typical format AxleCount x DrivenWheels (e.g., 4x2, 6x2, 6x4)

displacement

0:1

String

Engine displacement (ICE only) (E.g.: “8.7 litres”

energySources

0:1

Object

Energy sources information

energySourceType

1:1

String

One source: dsl | lpg | cng | prop | elec | h2 |

Hybrid: dslElec | lpgElec | cngElec | propElec |

Bi-fuel: dslLpg | dslCng |

fuelCapacity

0:1

Integer

Diesel fuel tank capacity (L)

cngTank

0:*

Integer

Mandatory in CNG vehicles

cngTankCapacity

1:1

Integer

CNG tank capacity as mass (kg)

cngTankLocation

1:1

String

Location of CNG Tank

h2Tank

0:*

Object

Mandatory in H2 vehicles

h2TankCapacity

1:1

Integer

H2 tank capacity as mass (kg)

h2TankLocation

1:1

String

Location of H2 Tank

hvess

0:*

Object

Mandatory in electric vehicles

batteryCapacity

1:1

Integer

Battery nominal capacity (units: kWh)

batteryChemistry

1:1

String

Battery chemistry if disclosed (e.g., LFP, NMC)

batteryLocation

1:1

String

Location of battery and access method

passengerArea

0:1

Object

Passenger area section

seatedCapacity

1:1

Integer

Number of passenger seats for the reference layout of the chosen variant (count)

standingCapacity

1:1

Integer

Standing places (count).

wheelchairPositions

1:1

Integer

Wheelchair (PMR) spaces (count).

hasRamp

1:1

Integer

Number of doors equipped with wheelchair ramp

doorCount

1:1

Integer

Number of service doors (count).

doorDescription

0:1

String

Free-text door description field If the sheet provides per-door widths/heights (e.g., “Front & middle doors 1,200 mm” for LE City; “Front 800 mm, middle 1,200 mm” for LE Line)

hvac

0:1

Object

HVAC information.

acPresent

0:1

Boolean

Air conditioning present (true/false).

heatingType

0:1

String (Enum)

Passenger-area heating technology. Recommended enum: dieselHeater | heatPump | electricResistance | other

Otherwise map from the OEM wording (e.g., “Four heaters for the passenger compartment”

CanDataAvailable

+Structure

Description

<Common fields for every JSON data message>

pgnsDiscovered

0:*

Object

List of PGNs discovered

rawPgnHexString

1:*

String

Hex string with uppercase characters, without spaces, representing the 29bits CAN Identifier+1 byte Data Length Code+8 bytes of Data. Example “18FEEE17085A4B1027FFFFFFFF”

(For most PGNs (8 data bytes PGNs) a single string will be published but for larger PGNs more strings are needed: the first BAM string plus one or more sequence strings)

pgnPeriod

1:1

Integer

PGN occurrence period on the CAN bus, in ms

SignalsAvailable

+Structure

Description

<Common fields for every JSON data message>

signalList

0:*

Object

List of available signal descriptors. Each item has the following fields.

signalName

1:1

String

Signal name according to the catalog of signals (See OPI Raw Vehicle Signals).

signalInformation

0:1

String

Required if signal is not in the catalog (Other).

RawPGNMessage Stream Info

+Structure

Description

<Common fields for every JSON data message>

pgn

1:1

String

Hex string with uppercase characters, without spaces, representing the 2 bytes PGN, e.g. FEEE if the complete data were “18FEEE17085A4B1027FFFFFFFF”

pgnSource

0:1

String

Hex string with uppercase characters, without spaces, representing Source byte, e.g. 17

pgnStreamTimeRef

1:1

DateTime

Reference time for the Timestamps of the data. It is the date of the start of the vehicle session.

Adding the timestamp of a data element in the stream to this time will result in the absolute DateTime for this data element

RawPGNMessage Stream Data

+Structure

Description

Samples

1:*

Array

[0]

1:1

Integer

Timestamp in microseconds relative to pgnStreamTimeRef

[1]

1:1

String

Hex string with uppercase characters, without spaces, representing the 8 bytes PGN data, e.g. 5A4B1027FFFFFFFF

For most PGNs (8 data bytes PGNs) a single string will be published but for larger PGNs more strings are needed, the first BAM string plus one or more sequence strings.

[2…N]

0:*

String

Additional data represented as Hex string with uppercase characters, without spaces.

Only used in multi-packet PGNs.

request_pgn

+Structure

Description

<Common fields for every JSON cmd message>

pgn

1:1

String

Parameter Group Number (hex. Example FEEE)

stop_pgn

+Structure

Description

<Common fields for every JSON data message>

pgn

1:1

Integer

Parameter Group Number (hex. Example FEEE).

VehicleSignalName (for a specific Field Name)

+Structure

Description

<Common fields for every JSON data message>

<vehicleSignalFieldName>

1:1

String

high | low | unavailable | unknown

Vehicle Signals Catalog

Field Name

Leaf Topic Name

Field Name

Leaf Topic Name

manualSwitchStatus

manual_switch_status

ramp3Status

ramp_3_status

mainSwitchStatus

main_switch_status

door4Status

door_4_status

ignitionSwitchStatus

ignition_switch_status

door5Status

door_5_status

fullPowerAvailableStatus

full_power_available_status

door6Status

door_6_status

lowBatteryStatus

low_battery_status

stopRequestStatus

stop_request_status

doorsStatus

doors_status

rampRequestStatus

ramp_request_status

rampsStatus

ramps_status

motorRunningStatus

motor_running_status

door1Status

door_1_status

presenceHVStatus

presence_hv_status

ramp1Status

ramp_1_status

reverseStatus

reverse_status

door2 Status

door_2_status

silentAlarmRequestStatus

silent_alarm_request_status

ramp2Status

ramp_2_status

luggageCompartmentDoorStatus

luggage_compartment_door_status

door3Status

door_3_status

(other)

VehicleSignalName (ignitionSwitchStatus)

+Structure

Description

<Common fields for every JSON data message>

ignitionSwitchStatus

1:1

String

…

VehicleSignalName (ramp1Status)

+Structure

Description

<Common fields for every JSON data message>

ramp1Status

1:1

String

…

GnssLocation

+Structure

Description

<Common fields for every JSON data message>

gnssRawData

0:1

String

Raw data as defined in the relevant GNSS, for example GPS NMEA 0183 or 2000 frames. At most one occurrence of each frame type shall be provided.

rawDataType

0:1

String

Type of data specification used for raw data

latitude

1:1

Object

Latitude value

degree

1:1

Float

Coordinate in decimal degrees (DDDDD), WGS-84 [-90.00000, +90.00000]

Positive = Northern Hemisphere, negative = Southern Hemisphere.

heading

0:1

String (Enum)

Geographical direction (N or S)

longitude

0:1

Object

Longitude value

degree

1:1

Float

Coordinate in decimal degrees (DDDDD), WGS-84 [-180.00000, +180.000000]

Positive = Eastern Hemisphere, negative = Western Hemisphere.

heading

0:1

String (Enum)

Geographical direction (W or E)

altitude

1:1

Float

Altitude value (m)

time

1:1

String

UTC time value with following format hh:mm:ss

date

0:1

String

Date value with following format yyyy-mm-dd

speedOverGround

0:1

Float

GNSS based speed over ground (m/s)

signalQuality

0:1

String (Enum)

Signal quality value. Quality reference from GNSS coordinates based on system specification. See the following possible enums: aGPS | dGPS | estimated | gps | notValid | unknown

fix

0:1

String (Enum)

Status of GNSS fix. See the following possible enums: noFix | 2D | 3D | DR | 3D+DR

numberOfSatellites

0:1

Integer

Number of satellites which are used for the GNSS

horizontalDilutionOfPrecision

0:1

Float

Value of precision in horizontal dilution

verticalDilutionOfPrecision

0:1

Float

Value of precision in vertical dilution

trackDegreeTrue

0:1

Float

Value of the Track based at the real north pole

trackDegreeMagnetic

0:1

Float

Value of the Track based at the magnetic north pole

gnssType

1:1

String (Enum)

Information about the used GNSS System. Type of satellites receiver. MixedGNSSTypes is used for receivers using multiple satellite constellations. See the following possible enums: gps | glonass | galileo | beidou | irnss | deadReckoning | mixedGnssTypes | other

gnssCoordinateSystem

0:1

String (Enum)

Information about the coordinate system. data reference used by satellites coordinates. the default coordinate system is wgs84 (widely used), in case of empty field. see the following possible enums: ch1903 | etsr89 | itrs/itrf nad83 | wgs84 | pz90

deadReckoning

1:1

Boolean

DR assistance active (Y/N).

doubleFrequency

0:1

Boolean

Dual-frequency receiver (Y/N).

gnssDistance

0:1

Float

Distance travelled computed from GNSS (metres).

simulationMode

0:1

Boolean

true when GNSS is in simulation mode.

horizontalAccuracy

0:1

Float

1-σ horizontal accuracy (metres)

verticalAccuracy

0:1

Float

1-σ vertical accuracy (metres)

speedAccuracy

0:1

Float

1-σ speed accuracy (m s-¹).

headingAccuracy

0:1

Float

1-σ heading accuracy (degrees).

gnssFixOk

0:1

Boolean

true if solution meets DOP & accuracy masks.

RawAccelerations Stream Info

+Structure

Description

<Common fields for every JSON data message>

accellSamplingPeriod

1:1

Integer

Current sampling period (ms).

acelStreamTimeRef

1:1

DateTime

Reference time for the Timestamps of the data. It is the date of the start of the vehicle session.

Adding the timestamp of a data element in the stream to this time will result in the absolute DateTime for this data element

Raw Accelerations Stream Data

+Structure

Description

Samples

1:*

Array

[0]

1:1

Integer

Timestamp in microseconds relative to acelStreamTimeRef

[1]

1:1

Integer

Raw X acceleration from the sensor axes (mG). (1 mG = 0.0098 m/s²)

[2]

0:1

Integer

Raw Y acceleration from the sensor axes (mG). (1 mG = 0.0098 m/s²)

[3]

0:1

Integer

Raw Z acceleration from the sensor axes (mG). (1 mG = 0.0098 m/s²)

Vehicle Accelerations stream Info

+Structure

Description

<Common fields for every JSON data message>

accellSamplingPeriod

1:1

Integer

Current sampling period (ms).

accelSlope

0:1

Integer

Longitudinal acceleration measured last time the vehicle was stationary (mG).

acelStreamTimeRef

1:1

DateTime

Reference time for the Timestamps of the data. It is the date of the start of the vehicle session.

Adding the timestamp of a data element in the stream to this time will result in the absolute DateTime for this data element

Vehicle Accelerations stream

+Structure

Description

Samples

1:*

Array

[0]

1:1

Integer

Timestamp in microseconds relative to acelStreamTimeRef

[1]

1:1

Integer

Longitudinal, vehicle-aligned X acceleration (mG). (1 mG = 0.0098 m/s²)

[2]

0:1

Integer

Lateral, vehicle-aligned Y acceleration (mG). (1 mG = 0.0098 m/s²)

[3]

0:1

Integer

Vertical, vehicle-aligned Z acceleration (mG). (1 mG = 0.0098 m/s²)

calibrate_accel

+Structure

Description

<Common fields for every JSON command message>**

calibrateAccel

1:1

Boolean

true

OdometerAll

+Structure

Description

<Common fields for every JSON data message>

odoSpeed

1:1

Integer

Vehicle speed computed from odometer (Hm/h).

odoDistance

1:1

Integer

Distance travelled since last vehicle start (last contact on) (meters).

odoPulses

1:1

Integer

Accumulated odometer pulse count since last vehicle start (last contact on).

odoAcceleration

0:1

Integer

Vehicle instantaneous acceleration (mG) (1mG=(9,8m/s²)/1000)

ActiveTellTales

+Structure

Description

<Common fields for every JSON data message>

activeTellTales

1:*

Object

Tell Tales with Status= Info, Yellow or Red

tellTaleId

1:1

Integer

According to FMS (1~120)

tellTaleStatus

1:1

Integer

Info, Yellow or Red

ttsRedTime

0:1

Integer

Time in seconds with TTS Red

ttsRedDistance

0:1

Integer

Distance travelled in meters with TTS Red

ttsYellowTime

0:1

Integer

Time in seconds with TTS Yellow

ttsYellowDistance

0:1

Integer

Distance travelled in meters with TTS Yellow

DiagnosticMessagesAll

+Structure

Description

<Common fields for every JSON data message>

diagnosticMessages

1:*

Object

DM according to J1939 DM1

lampStatus

1:1

Integer

According to DM1. MIL(Malfunction Indicator), RSL(Red Stop), AWL(Amber Warning), PL(Protect Lamp)

dtc

1:*

Object

Diagnostic Trouble Codes

spn

1:1

Integer

J1939 parameter

failureModeId

1:1

Integer

Failure Mode Identifier

occurrenceCount

1:1

Integer

Occurrence Count

dtcTime

0:1

Integer

Time in seconds with DTC active

dtcDistance

0:1

Integer

Distance travelled in meters with DTC active

Contact

+Structure

Description

<Common fields for every JSON data message>

ignitionStatus

1:1

String (Enum)

on | off | noContact | unavailable | error

EngineStatus

+Structure

Description

<Common fields for every JSON data message>

engineStatus

1:1

String (Enum)

on | off | noContact | unavailable | error

ParkingBrakeStatus

+Structure

Description

<Common fields for every JSON data message>

parkingBrakeStatus

1:1

String (Enum)

on | off | unavailable | error

ChargingStatus

+Structure

Description

<Common fields for every JSON data message>

chargingStatus

1:1

String

Overall vehicle charging session status. ON, OFF, Unavailable, Error

chargingStartTime

1:1

DateTime

Timestamp when a charging session started (chargingStatus from OFF to ON)

energyCharged

0:1

Integer

Cumulated Energy charged (Wh)

hvessSoc

0:1

Integer

0% means no charge remaining, 100% means the system is fully charged in terms of physical limits of the energy storage system (%)

chargingEndTime

0:1

DateTime

Timestamp when a charging session ended (chargingStatus from ON to OFF, error)

DrivingMode

+Structure

Description

<Common fields for every JSON data message>

drivingMode

1:1

String

driving | standBy | charging

PowerMode

+Structure

Description

<Common fields for every JSON data message>

powerMode

1:1

String

24V auxiliaries power mode: ECO0, ECO1, ECO2 or SLEEP

timeToPowerOff

0:1

Integer

Time in seconds left until 24V power is set to Off (Contact Off)

DoorsStatus

+Structure

Description

<Common fields for every JSON data message>

anyDoorStatus

1:1

String (Enum)

open = if any door is open

closed = if all doors are closed

unknown = if status is “unknown”

malfunction = in case of malfunction

anyRampStatus

1:1

String (Enum)

noRamp = no ramp available in this bus

open = if any ramp has been deployed

closed = if no ramp has been deployed

unknown = if status is “unknown”

malfunction = in case of malfunction of any ramp

eachDoorStatus

0:*

Object

List of all doors and their status

doorLocationId

1:1

Integer

Door ID associated with its position in the bus (e.g. 1 = front door)

doorInfo

1:1

String

Free description of the door e.g. “low floor, rear door with ramp)

doorStatus

1:1

String (Enum)

open = if any door is open

closed = if all doors are closed

unknown = if status is “unknown”

malfunction = in case of malfunction

doorCondition

0:1

String (enum)

normal | locked | emergencyRelease

rampLiftPosition

1:1

String (Enum)

noRamp = no ramp available in this door

open = if ramp has been deployed

closed = if ramp has not been deployed

unknown = if status is “unknown”

malfunction = in case of malfunction

ramp7DaysWithoutUseStatus

0:1

String (Enum)

usedWithin7Days | notUsed7Days | unknown | malfunction

rampErrorStatus

0:1

Boolean

true | false

rampIsDirtyStatus

0:1

Boolean

true | false

totalCyclesRamp

0:1

Integer

Cumulative number of ramp cycles for this door since installation or last maintenance reset (rampCounterSince)

totalCyclesDoor

0:1

Integer

Cumulative number of door cycles (open/close) since installation or last maintenance reset

doorCounterSince

0:1

DateTime

Timestamp when the door cycle counter was last reset

rampCounterSince

0:1

DateTime

Timestamp when the ramp cycle counter was last reset

AmbientConditions

+Structure

Description

<Common fields for every JSON data message>

temperatureSensor

1:*

Object

Temperature sensors

temperatureSensorLocationId

1:1

Integer

ID associated with the position of the sensor within in the bus

temperatureSensorInfo

1:1

String

Free description of sensor features and , location

temperatureSensorValue

1:1

Integer

Value expressed in 0.1 °C units, unknown or malfunction

humiditySensor

0:*

Object

Humidity sensors

humiditySensorLocationId

1:1

Integer

ID associated with the position of the sensor within in the bus

humiditySensorInfo

1:1

String

Free description of sensor features and location

humiditySensorValue

1:1

Integer

Value expressed in % units, unknown or malfunction

co2Sensor

0:*

Object

CO2 sensors

co2SensorLocationId

1:1

Integer

ID associated with the position of the sensor within in the bus

co2SensorInfo

1:1

String

Free description of sensor features and location

co2SensorValue

1:1

Integer

Value expressed in ppm units, unknown or malfunction

euaqi

0:*

Object

European air quality index

euaqiSensorLocationId

0:1

Integer

ID associated with the position of the sensor within in the bus

euaqiSensorInfo

0:1

String

Free description of sensor features and location

euaqiSensorValue

0:1

Integer

EUAQI 1 to 5 air quality index value, unknown or malfunction

euaqiPassengersAreaValue

0:1

Integer

EUAQI 1 to 5 air quality index value in passengers Area

LuggageCompartmentStatus

+Structure

Description

<Common fields for every JSON data message>

luggageCompartment1Status

1:1

Boolean

Status of any luggage compartment: true = ANY OPEN, false = ALL CLOSED

luggageCompartment1Status

0:1

Boolean

Status of any luggage compartment1: true = OPEN, false = CLOSED

luggageCompartment2Status

0:1

Boolean

Status of any luggage compartment2: true = OPEN, false = CLOSED

luggageCompartment3Status

0:1

Boolean

Status of any luggage compartment3: true = OPEN, false = CLOSED

luggageCompartment4Status

0:1

Boolean

Status of any luggage compartment4: true = OPEN, false = CLOSED

StopRequestStatus

+Structure

Description

<Common fields for every JSON data message>

stopRequestStatus

1:1

Boolean

Status of the bus stop request signs.

true (if active/requested) | false (not requested)

They turn on whenever a stop request button is pushed by a passenger and turn off after the bus arrives at a stop.

stopRequestSource

0:1

String

Pushbutton, PMR_pushbutton or user_App

stopRequestButton1Status

0:1

Boolean

Status of stop request button 1 (front)

stopRequestButton2Status

0:1

Boolean

Status of stop request button 2 (middle)

stopRequestButton3Status

0:1

Boolean

Status of stop request button 3 (rear)

PassengersSeatbeltsStatus

+Structure

Description

<Common fields for every JSON data message>

passengersSeatbelts

1:N

Object

Status of passenger seatbelts

seatbeltLocationId

1:1

Integer

ID associated with the position of the sensor within in the bus

seatbeltInfo

1:1

String (Enum)

Seat or Wheelchair seatbelt. See the following possible enums: seat | wheelchair

seatbeltStatus

1:1

Integer

See the following possible enums: locked | unlocked | unknown | malfunction

HvessMain

+Structure

Description

<Common fields for every JSON data message>

hvessId

1:1

String

hvessSpecs

1:1

String

hvessVoltage

1:1

Integer

The voltage level of the High Voltage Energy Storage 1 pack (or system)

hvessCurrent

1:1

Integer

The current in or out of the High Voltage Energy Storage 1 pack (or system)

hvessTemperature

1:1

Integer

The temperature of High Voltage Energy Storage System (or Pack 1 in systems with only one pack)

hvessAvgCellTemp

1:1

Integer

The average temperature level of all cells in the High Voltage Energy Storage System (or Pack 1 in systems with only one pack)

hvessAvailablePower

0:1

Integer

The rate at which the High Voltage Energy Storage System (or Pack 1 in systems with only one pack) can currently provide energy for propulsion or other uses

hvessDischargeCurrentCapacity

0:1

Integer

The amount of stored electrical charge in the High Voltage Energy Storage System (or Pack 1 in systems with only one pack) that is available for use by the hybrid system

hvessDdischargePowerCapacity

0:1

Integer

The amount of stored electrical energy in High Voltage Energy Storage System (or Pack 1 in systems with only one pack) that is available for use by the hybrid system

hvessChargePower

0:1

Integer

The rate at which the High Voltage Energy Storage System (or Pack 1 in systems with only one pack) can currently receive energy from a regenerative or recharging system

hvessFastUpdateStateOfCharge

0:1

Integer

Indicates the High Voltage Energy Storage System (or Pack 1 in systems with only one pack) state of charge

HvessStatus

+Structure

Description

<Common fields for every JSON data message>

cellBalanceStatus

1:1

Integer

Indicates whether or not the cells in the High Voltage Energy Storage System (or Pack 1 in systems with only one pack) are balanced:

balanced | unbalanced | unavailable | error

cellTemperatureDifferential

0:1

Integer

Difference between highest and lowest HVESS cell temperature

cellVoltageDifferential

1:1

Integer

Difference between highest and lowest HVESS cell voltage

internalChargerStatus

0:1

Integer

indicative of AC Charging status

HvessCellTemp

+Structure

Description

<Common fields for every JSON data message>

hvessHighestCellTemp

1:1

Object

Highest temperature level reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack number containing the highest cell temperature

moduleNumber

0:1

Integer

Identifies the module containing the highest cell temperature

cellNumber

0:1

Integer

Identifies the cell with the highest temperature

temperature

1:1

Integer

The highest temperature level reported by any cell in the High Voltage Energy Storage System (ºC)

hvessLowestCellTemp

1:1

Object

The lowest temperature level reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack number containing the lowest cell temperature

moduleNumber

0:1

Integer

Identifies the module containing the lowest cell temperature

cellNumber

0:1

Integer

Identifies the cell with the lowest temperature

temperature

1:1

Integer

The lowest temperature level reported by any cell in the High Voltage Energy Storage System (ºC)

HvessCellVolt

+Structure

Description

<Common fields for every JSON data message>

hvessHighestCellVolt

1:1

Object

The highest voltage level reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack number containing the highest cell voltage

moduleNumber

0:1

Integer

Identifies the module containing the highest cell voltage

cellNumber

0:1

Integer

Identifies the cell with the highest voltage

voltage

1:1

Integer

The highest temperature level reported by any cell in the High Voltage Energy Storage System (V)

hvessLowestCellVolt

1:1

Object

The lowest voltage level reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack number containing the lowest cell voltage

moduleNumber

0:1

Integer

Identifies the module containing the lowest cell voltage

cellNumber

0:1

Integer

Identifies the cell with the lowest voltage

voltage

1:1

Integer

The lowest temperature level reported by any cell in the High Voltage Energy Storage System (V)

HvessCellSoc

+Structure

Description

<Common fields for every JSON data message>

hvessHighestCellSoc

1:1

Object

The highest state of charge (SoC) reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack containing the highest cell SoC

moduleNumber

0:1

Integer

Identifies the module containing the highest cell SoC

cellNumber

0:1

Integer

Identifies the cell with the highest SoC

stateOfCharge

1:1

Integer

Highest cell state of charge (%)

hvessLowestCellSoc

1:1

Object

The lowest state of charge (SoC) reported by any cell in the High Voltage Energy Storage System

packNumber

0:1

Integer

Identifies the pack containing the lowest cell SoC.

moduleNumber

0:1

Integer

Identifies the module containing the lowest cell SoC.

cellNumber

0:1

Integer

Identifies the cell with the lowest SoC.

stateOfCharge

1:1

Integer

Lowest cell state of charge (%).

HvessConfiguration

+Structure

Description

<Common fields for every JSON data message>

maximumOperatingVoltage

0:1

Integer

Maximum recommended voltage level for High Voltage Energy Storage System. Operating above this value may compromise HVES life.

minimumOperatingVoltage

0:1

Integer

Minimum recommended voltage level for High Voltage Energy Storage System. Operating below this value may compromise HVES life.

maximumOperatingTemperature

0:1

Integer

Recommended maximum temperature for High Voltage Energy Storage System

minimumOperatingTemperature

0:1

Integer

Recommended minimum temperature for High Voltage Energy Storage System

nominalRatedCapacity

0:1

Integer

Manufacturer's nominal rated capacity of the High Voltage Energy Storage System

nominalVoltage

0:1

Integer

Manufacturer’s nominal operating voltage of the High Voltage Energy Storage System

maximumStateOfCharge

0:1

Integer

Recommended maximum state of charge for High Voltage Energy Storage System

minimumStateOfCharge

0:1

Integer

Recommended minimum state of charge for High Voltage Energy Storage System

cellMaximumVoltageLimit

0:1

Integer

Recommended maximum cell voltage for High Voltage Energy Storage System

cellMinimumVoltageLimit

0:1

Integer

Minimum cell voltage for High Voltage Energy Storage System

HvessThermalManagement

+Structure

Description

<Common fields for every JSON data message>

heaterStatus

0:1

Integer

HVESS Thermal Management System Heater Status 

coolerStatus

0:1

Integer

HVESS Thermal Management System Cooler Status 

mode

0:1

Integer

HVESS Thermal Management System Mode (Cooler/Heater)

HvessHistory

+Structure

Description

<Common fields for every JSON data message>

contactorOpenUnderLoadCount

0:1

Integer

Number of times the contactors inside the High Voltage Energy Storage System have opened while current is flowing through them. The current level (that determines if an opening event will be counted) shall be defined by the HVES manufacturer, but in general should be a current level at which the contactor life may be reduced if repeated cycles occur.

totalLifetimeEnergyInput

0:1

Integer

The cumulative energy which has flowed into the High Voltage Energy Storage System over the lifetime of the battery system

hvessTotalEnergyThroughput

0:1

Integer

The total energy throughput which has flowed through High Voltage Energy Storage

hvessTotalLifetimeEnergyOutput

0:1

Integer

The cumulative energy which has flowed out of the High Voltage Energy Storage System over the lifetime of the battery system

hvessTotalAccumulatedCharge

0:1

Integer

The total accumulated amp hours which have flowed through High Voltage Energy Storage System

hvessStateOfHealth

1:1

Integer

Expected remaining “life” of the High Voltage Energy Storage System (%)

HvessPacks

+Structure

Description

<Common fields for every JSON data message>

hvessPack

1:*

Object

High Voltage Energy Storage packs voltage, temperature and energy

packNumber

1:1

Integer

Identifies the pack number

packVoltage

1:1

Integer

The voltage level of the High Voltage Energy Storage pack referenced

packTemperature

1:1

Integer

The temperature of the High Voltage Energy Storage pack referenced

packEnergy

0:1

Integer

The amount of stored electrical energy of the High Voltage Energy Storage pack referenced

ValidatorTransaction

+Structure

Description

<Common fields for every JSON data message>

validationDate

1:1

DateTime

Timestamp of the validation date

fareMediumSerialNumber

1:1

String

Unique serial of the physical/virtual medium presented

accessEventCounter

1:1

Integer

Value of event counter in the medium.

fareProductCode

1:1

String

Code of the Fare Product consumed/checked

farePurchasingDate

1:1

DateTime

Timestamp when the product was sold/loaded

fareFirstValidationDate

1:1

DateTime

Timestamp of the first use/first validation of the product

fareOwner

1:1

String

Identifier of the fare contract owner

fareMediumType

1:1

String (Enum)

Medium type used: contactlessCard | nfcPhone | bankcard | paperBarcode | phoneBarcode

fareSystemType

1:1

String (Enum)

ptaSystem | ptoSystem | emv | abt | tesc

customerProfile

1:1

String

Passenger profile applied (adult, student, senior…)

driverRef

1:1

String

Driver identifier linked to the operating session

ptoRef

1:1

String

Public Transport Operator identifier reference.

validationLocation

1:1

Object

Context of where the validation took place

equipmentGuid

1:1

String

ODEx equipment item GUID where the validation took place.

vehicleRef

1:1

String

ID of the vehicle unit. VIN for bus.

stopPointRef

0:1

String

Stop Point reference attributed to the event

lineRef

1:1

String

Identifier of operational Line that vehicle follows

directionRef

0:1

String (Enum)

Relative direction the vehicle is running along the line:

in = inbound | out = outbound | cw = clockwise | ccw = counterclockwise | other

servicePatternRef

0:1

String

Identifier of the Service Pattern

fareZoneId

0:1

String

Tariff/Fare Zone

blockRef

0:1

String

Reference (ID) of Block assigned

courseOfJourneyRef

0:1

String

Reference (ID) of Course of Journey assigned

serviceJourneyRef

0:1

String

Reference (ID) of Service Journey assigned

validationCount

1:1

Integer

Validator transaction counter

hotListsVersion

1:*

Object

List type and version of hot lists applied

type

1:1

String

Type of hot list applied (simple, ranged…)

version

1:1

String

Version of defined hot list.

validationResultCode

1:1

Integer

Project-specific validation result code. Consumers must interpret it using the project validation result code list.

E.g.: 1 = ok | 2 = cardRejected | 3 = cardBlocked | 4 = customerProfileChange…

ValidatorOpParameters

+Structure

Description

<Common fields for every JSON data message>

validatorOpStatus

Object

Current operational state of the validator application

opStatus

1:1

String (Enum)

Operating mode. See the following list of possible enums: ready | busy | locked | outOfOrder | maintenance | other

additionalInfo

0:1

String

Optional free-text

nlInfo

1:1

Object

Network-location context shared by the validator

servicePatternRef

0:1

String

Identifier of the Service Pattern

journeyPatternRef

0:1

String

Journey Pattern reference

vehicleJourneyRef

0:1

String

Reference to the specific service journey or dead run.

routeRef

0:1

String

Route identifier

lineRef

1:1

String

Identifier of operational Line that vehicle follows

directionRef

0:1

String (Enum)

Relative direction the vehicle is running along the line:

in = inbound | out = outbound | cw = clockwise | ccw = counterclockwise | other

externalLineRef

0:1

String

External/agency line reference (if applicable).

lastStopPointRef

0:1

String

Reference of the last passed stop

nextStopPointRef

0:1

String

Reference of the next scheduled stop

driver

1:1

Object

Current driver and duty context

driverRef

1:1

String

Driver identifier reference

driverName

0:1

String

Driver Name

driverDuty

0:1

String

Duty identifier reference (work to be performed by a driver on a particular day type)

locationInVehicle

1:1

Object

Validator shared info about its location in the vehicle

equipmentGuid

1:1

String

ODEx equipment item GUID

valPosition

1:1

Integer

(1-8) 1= front door

validationMode

1:1

String

Indicates whether the validator is configured for validations on boarding (entry) or on alighting (exit): boarding | alighting | both | onlyConsult

pmr

1:1

Boolean

true if configured as PMR entry point; otherwise, false

fareZoneInfo

0:*

Object

List of accepted tarrif and fare zones. Each entry ties a Fare Authority/Organisation to a Tariff/Fare Zone.

fareAuthorityId

1:1

String

Identifier of the fare authority/organisation that defines the zone.

fareZoneId

1:1

String

Identifier of the Tariff/Fare Zone.

farezoneTypeId

1:1

String

Index at the fare zone type

hotListsVersion

1:*

Object

List type and version of hot lists applied

type

1:1

String

Type of hot list applied (simple, ranged…)

version

1:1

String

Version of defined hot list.

ptaRef

1:1

String

Identifier of the Public Transport Authority.

ptoRef

1:1

String

Identifier of the Public Transport Operator.

vehicleId

1:1

String

ID of the vehicle unit. VIN for bus.

samSerialNumber

1:1

String

SAM serial number installed

MQTT topic under …/validator/<OPI_version>/cmd

Fields

+Structure

Description

<Common fields for every JSON command message>

/shutdown

reason

0:1

String

Switch off the validator app. Optional free-text reason

/reset

reason

0:1

String

Reset the validator app. With optional free-text reason.

/set_validation_mode

validationMode

1:1

String

Validation Mode (only entrance validation, consult…)

reason

0:1

String

Free-reason text

/lock_validation

durationSec

0:1

Integer

Lock duration time in seconds

reason

0:1

String

inspecction |driverOut …

/set_maintenance

active

1:1

Boolean

Enter/exit maintenance mode (true / false)

/set_demo

active

1:1

Boolean

Enter/exit demo mode (true / false) used for training

/request_config

-

-

-

Provider will return all config parameters in the details field structure (see Command Responses). Configuration parameters for the validator OPI and their data type must be specified (volumeLevel, screenBrightLevel, language…)

Structure of details field in response will be:

responseContent 0:* Object Config parameters

<configId1> - anyType1 Each parameter value

<configId2> - anyType2

…

/set_config

volumeLevel

0:1

anyType1

Integer

screenBrightLevel

0:1

anyType2

Integer

…

TicketVendingTransaction

+Structure

Description

<Common fields for every JSON data message>

saleDate

1:1

DateTime

Timestamp of the sale date.

ticketSerialNumber

1:1

String

Unique serial of the physical/virtual medium presented

fareProductCode

1:1

Integer

Code of the Fare Product consumed/checked

fareOwner

1:1

String

Identifier of the fare contract owner

customerProfile

1:1

String

Passenger profile applied (adult, student, senior…)

paymentType

1:1

String

cash | bankcard |

tariffAmount

1:1

Integer

Indicates the fare paid by the customer for the transaction (cents)

saleLocation

1:1

Object

Context of where the sale took place

equipmentGuid

1:1

String

ODEx equipment item GUID where the sale took place.

vehicleRef

1:1

String

ID of the vehicle unit. VIN for bus.

stopPointRef

0:1

String

Stop Point reference attributed to the event

lineRef

1:1

String

Identifier of operational Line that vehicle follows

directionRef

0:1

String (Enum)

Relative direction the vehicle is running along the line:

in = inbound | out = outbound | cw = clockwise | ccw = counterclockwise | other

servicePatternRef

0:1

String

Identifier of the Service Pattern

fareZoneId

0:1

String

Tariff/Fare Zone resolved

blockRef

0:1

String

Reference (ID) of Block assigned

courseOfJourneyRef

0:1

String

Reference (ID) of Course of Journey assigned

serviceJourneyRef

0:1

String

Reference (ID) of Service Journey assigned

driverRef

1:1

String

Driver identifier linked to the operating session

ptoRef

1:1

String

Public Transport Operator identifier reference.

samSerialNumber

1:1

String

SAM serial number installed

saleCount

1:1

Integer

Operation counter.

saleResultCode

1:1

Integer

Project-specific sale result code. Consumers must interpret it using the project sale result code list.

TicketVendingOpParameters

+Structure

Description

<Common fields for every JSON data message>

tvmOpMode

1:1

Object

Report of the operating mode and if manual or automatic

manualMode

1:1

Boolean

true if manual, false if automatic (farebox)

operatingMode

1:1

String (Enum)

ready | busy | locked | outOfOrder | maintenance | other

additionalInfo

0:1

String

Optional free-text

nlInfo

1:1

Object

Network location specific information shared.

servicePatternRef

0:1

String

Identifier of the Service Pattern

journeyPatternRef

0:1

String

Journey Pattern reference

vehicleJourneyRef

0:1

String

Reference to the specific service journey or dead run.

routeRef

0:1

String

Route identifier

lineRef

1:1

String

Identifier of operational Line that vehicle follows

directionRef

0:1

String

Relative direction the vehicle is running along the line (e.g. inbound, outbound, clockwise)

externalLineRef

0:1

String

External/agency line reference (if applicable).

lastStopPointRef

0:1

String

Reference of the last passed stop

nextStopPointRef

0:1

String

Reference of the next scheduled stop

driver

1:1

Object

Current driver

driverRef

1:1

String

Driver identifier reference

driverName

0:1

String

Driver Name

fareZoneInfo

0:*

Object

List of accepted tarrif and fare zones. Each entry ties a Fare Authority/Organisation to a Tariff/Fare Zone.

fareAuthorityId

1:1

String

Identifier of the fare authority/organisation that defines the zone.

fareZoneId

1:1

String

Identifier of the Tariff/Fare Zone.

farezoneTypeId

1:1

String

Index at the fare zone type

fareMatrixVersion

0:1

String

Version of Fare Matrix.

ptaRef

1:1

String

Identifier of the Public Transport Authority responsible for the services run by the vehicle

ptoRef

1:1

String

Identifier of the Public Transport Operator.

equipmentGuid

1:1

String

ODEx equipment item GUID.

vehicleRef

1:1

String

ID of the vehicle unit. VIN for bus.

DriverCashSettlement

+Structure

Description

<Common fields for every JSON data message>

sessionId

1:1

String

Sequential cash settlement identifier. New session id on new driver session.

sessionStartTime

1:1

DateTime

Start of session Timestamp.

sessionEndTime

1:1

DateTime

End of session Timestamp.

saleLocation

1:1

Object

Location context of the service during the settlement period.

vehicleRef

0:1

String

ID of the vehicle unit. VIN for bus.

equipmentGuid

0:1

String

ODEx equipment item GUID where the validation took place.

lineRef

1:*

String

Identifier of operational Line that vehicle followed

directionRef

0:1

String (Enum)

Relative direction the vehicle is running along the line:

in = inbound | out = outbound | cw = clockwise | ccw = counterclockwise | other

servicePatternRef

0:1

String

Identifier of the Service Pattern

fareOwner

0:1

String

Identifier of the fare contract owner

blockRef

0:1

String

Reference (ID) of Block assigned

courseOfJourneyRef

0:1

String

Reference (ID) of Course of Journey assigned

serviceJourneyRef

0:1

String

Reference (ID) of Service Journey assigned

salesByLine

1:*

Object