GTAC Logo

INTRODUCTION

TheODEx (Onboard Data Exchange)protocol is a set of specifications for the exchange of real time vehicle data, which can be categorized either as 1) Inventory and Status Data, 2) Information about the Software and Configuration or other Data of Equipment Items and Applications and their Updates, and 3) Operational Data, which includes data concerning the physical vehicle (obtained from the vehicle CAN buses and vehicle signals and sensors) and data related to the PT services run by the vehicle (Network Location, Driver Log on, passenger counting, ticketing data…).

The object of this document, ODEx-3. Inventory & Updates Interfaces, is the data of the fisrt two categories: Inventory and Updates, defining the MQTT topics and JSON payloads used by an onboard ITS-PT component to:

  • Declare itself in the inventory
  • Publish information about its firmware and firmware updates
  • Publish information about its configuration data and data updates
  • Publish liveness and diagnostic status (heartbeat, simple status plus detailed status reports)

Additionally, ODEx-3 also defines MQTT topics and JSON payloads used to advertise system context (environment, broker, router) and other general information

The corresponding functions are described in equivalent sections (INVENTORY, INFORMATION ON SW AND DATA AND THEIR UPDATES and GENERAL INFORMATION) in ODEx-1. Concepts and Functional Architecture, needed to understand the purpose and working of the payloads described here.

ODEx Documents

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 (This document)
  • Inventory, status and updates interfaces data definitions

ODEx-4. Operational Interfaces
  • Operational interfaces data definitions and topics

ODEx-5. Usage and Examples
  • Practical guidelines and implementation examples

Table 1.- ODEx Documents

DATA TYPES AND CARDINALITY NOTATION

Cardinality notation used for the JSON fields

Cardinality

Meaning

0:1

Optional field, zero or one occurrence. You may omit it; if you include it, supply exactly one non-array 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. Thefield must be present and the array must contain ≥ 1 items.

Table 2.- Cardinality notation used for the JSON fields.

The concept of mandatory and optional fields indicates whether a piece of data must always be included in the JSON or not. An optional JSON field (0:1) means that the field may or may not appear in the message structure. However, this does not necessarily mean that the information is optional for the project. For example, the field ramp_statusis mandatory for buses equipped with a ramp (it must be present in those vehicles), but it will be absent from the JSON messages of vehicles that do not have a ramp.

Data Types used for JSON fields

All JSON samples in this document

  • use lower camel-case field names in a single-level structure (no header / payload nesting)
  • include optional elements only when they add value

Notation

Description

String

UTF-8 text

Integer

Whole number (positive or negative).

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

Boolean

true / false

DateTime

ISO-8601 UTC

Object

JSON object (unordered key-value map)

anyType

Freely defined extension field (must be valid JSON)

Table 3.- Data types used for JSON fields

INVENTORY: Equipment Items

/info (Equipment Item general information)

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/info

1

1

Equipment item

Table 4.- Equipment Item General Information topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message, corresponding to the Equipment Item declared

itemType

1:1

String

Item Type as defined in Section #2.9 Item Type from ODEx-1 Specification: “Equipment Item”

equipmentType

1:1

String (Enum)

Equipment type (see Section #4.3 ANNEX 3 – CATALOG OF EQUIPMENT ITEM TYPES from ODEx-1 Specification)

description

1:1

String

Short human-readable description of the equipment

configTopics

(inventory topics)

0:*

String

Equipment Item inventory topics under the declared /< Equipment Item GUID>/

(e.g. /info, /hardware, /software, /details/aa, /details/bb)

currentUpdates

0:*

String

MQTT topic paths to the information about current software/data installed

heartbeatAvailable

1:1

Boolean

Indicates whether this Equipment Item publishes a /heartbeat topic (true/false)

usageHints

0:*

Object

Used for additional information related to the publisher or item. E.g. MQTT ClientId

Table 5.- Equipment item /info message structure

JSON example for a HOST equipment item: 

 { 
  "timestamp" : "2025-05-27T10:20:30Z", 
  "topicPath" : <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/info, 
  "itemType" : "Equipment Item", 
  "equipmentType" : "HOST", 
  "description" : "Main onboard computer", 
  "heartbeatAvailable" : true, 
  "configTopics" : [ 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/info, 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/hardware, 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/software
  ], 
  "usageHints" : [ { 
    "clientId" : "cli-189a1ab0-bff0-46d7"
   } ] 
}

JSON example for an SP-OBC Equipment Item with 3 HW components: 

{ 
  "timestamp": "2025-05-27T10:20:30Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/info, 
  "itemType": "Equipment Item", 
  "equipmentType": "SP-OBC", 
  "description": "Telemetry OBC", 
  "heartbeatAvailable": true, 
  "configTopics": [ 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/info, 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/hardware, 
    <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/software, 
    …/equipment_items/550e84.../details/hw_components/internal_gnss, 
    …/equipment_items/550e84.../details/hw_components/internal_accelerometer, 
    …/equipment_items/550e84.../details/hw_components/external_thermometer
  ], 
  "usageHints": [ { 
    "clientId": "cli-189a1ab0-bff0-46d7"
   } ] 
}

/hardware (Equipment Item HW description)

Topic

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/hardware

1

1

Equipment item

Table 6.- Equipment Item Hardware topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

manufacturer

1:1

String

Company or entity that designed, produced, and assembled the equipment

itsEquipmentModel

1:1

String

Model name of the equipment

serialNumber

0:1

String

Serial number of the equipment

bridgeGuid

0:1

String

GUID of bridge device if the equipment item is not directly connected to the ITS network and it is declared through a bridge device

hardwareVersion

1:1

String

Manufacturer’s hardware-revision identifier for the unit. E.g. Rev-B, V3.1…

dateOfManufacture

1:1

Datetime (ISO-8601)

Build date.

ethernetPhys

0:*

Object

List of on-board Ethernet interfaces. Each object contains the attributes below.

name

1:1

String

macAddress

1:1

String

any

0:1

anyType

Optional additional fields freely defined by the MQTT client.

Table 7.- Equipment item /hardware message structure

JSON example: 

{ 
  "timestamp": "2025-05-27T10:20:30Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/hardware, 
  "manufacturer": "Tekia Systems", 
  "itsEquipmentModel": "PC-X5", 
  "serialNumber": "HOST-2025-00042", 
  "hardwareVersion": "Rev-B", 
  "dateOfManufacture": "2025-01-15T00:00:00Z", 
  "ethernetPhys": [ { 
    "name": "eth0", 
    "macAddress": "00:1A:2B:3C:4D:5E"
   } ] 
}

/software (Equipment Item base SW/FW and hosted Applications)

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/software

1

1

Equipment item

Table 8.- Equipment Item Software Topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

baseVersion

1:1

String

Version of the main software or firmware running on the device

OSVersion

1:1

String

Version of the operating system used.

hostedApps

1:*

Object

List of applications hosted on the equipment item

appName

1:1

String

Human-readable name of the application

appGuid

1:1

String

Globally unique identifier (UUID) of the application

appVersion

1:1

String

Version of the application

description

0:1

String

Short description of the application

providers

0:*

Object

List of different providers the application has.

providerGuid

1:1

String

If the application only has one provider, the same GUID of the application can be used in the provider GUID.

providerType

1:1

String (Enum)

Information about the source of the OPIs they are implementing, useful in cases where the Equipment Item and its Application are not enough to know the source of the provided OPIs. See enumeration in section #3.2.1 /Info

description

0:1

String

Short human-readable description of the equipment

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 9.- Equipment item /software message structure

JSON example: 

{ 
  "timestamp": "2025-05-27T10:20:30Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/software, 
  "baseVersion": "3.0.2", 
  "OSVersion": "Ubuntu 24.04.2 LTS", 
  "hostedApps": [ { 
    "appName": "insulation", 
    "appGuid": "c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1", 
    "appVersion": "2.1.0", 
    "description": "GNSS position provider", 
    "providers": [ { 
      "providerGuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", 
      "providerType": "MAIN", 
      "description": "TVM main application provider"
     }, { 
      "providerGuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", 
      "providerType": "VALIDATOR", 
      "description": "Validator1 provider"
     }, { 
      "providerGuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", 
      "providerType": "VALIDATOR", 
      "description": "Validator2 provider"
     } ] 
   } ] 
}

/details (Equipment Item HW details)

The topic < root>/inventory/equipment_items/< equip_GUID>/detailsis an optional topicreserved for any extra information about the Equipment Item that does not fit under /info, /hardwareor/software.

A common use case is to declare hardware sub-components, such as an internal GNSS or an external Air Quality sensor connected to the Equipment Item, etc.. This does not replace the declaration of a full ODEx Equipment Item when applicable, but rather offers a lightweight alternative for internal or secondary HW components.

To accommodate these cases, information about hardware sub-components mustbe published under:

<root>/inventory/equipment_items/<equip_GUID>/details/hw_components/<componentId>

Where < componentId> is a locally unique descriptive identifier created by the Equipment Item inventory application (the application responsible for declaring the Equipment Item).

Use of a component GUID is not required, but recommendedif global traceability is desired.

The payload at each of these sub-paths is intentionally flexible and can be as minimal as: 

{ 
  "topicPath": …/equipment_items/<SP-OBC_GUID>/details/hw_components/internal_gnss, 
  "componentId": "internal_gnss", 
  "model": "u-blox NEO-M9N", 
  "description": "Multi constellation DR GNSS receiver"
}

Directly published under each < componentId> topic… or it may partially mirror /info, /hardware, /software sub-topics previously defined in Sections#3.1.1 /info, #3.1.2 /hardware, #3.1.3 /software.

NOTE:As seen in Section 2.1.1 /info, any of these additional /details topics must be declared in the configTopics field from the belonging Equipment Item /info declaration. This way, a subscriber can correctly discover all published topics under that Equipment Item GUID path.

Topic path example for an SP-OBC with different HW components:

…/equipment_items/<SP-OBC_GUID>/details/hw_components/internal_gnss

…/equipment_items/<SP-OBC_GUID>/details/hw_components/internal_accelerometer

…/equipment_items/<SP-OBC_GUID>/details/hw_components/external_thermometer

INVENTORY: Providers

/info (Provider general information)

Topic (s)

QoS

Retain

Published by

< root>/inventory/providers/< provider_GUID>/info

1

1

Provider

Table 10.- Provider General Information topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

itemType

1:1

String

Equipment Item, Provider, SW Update or Data Update as defined in Section #2.9 Item Type from ODEx-1 Specification: “Provider”

providerType

1:1

String (Enum)

Information about the source of the OPIs they are implementing, useful in cases where the Equipment Item and its Application are not enough to know the source of the provided OPIs. See enumeration and note below.1

opInterfaces

1:*

Object

List of implemented Operation Interfaces (OPI_name) (from the Catalog of OPIs included in ODEx-4) along with their version.

opiName

1:1

String

OPI_name as defined in the Catalog of OPIs included in ODEx-4

opiVersion

1:1

String

OPI_version used as defined in the Catalog of OPIs included in ODEx-4

description

0:1

String

Short human-readable description of the provider (e.g. External Validator NFC, EMV, QR)

configTopics

0:*

String

Provider inventory topics under the declared /< Provider GUID>/

(e.g. /info, /topics_declared, /details/aa, /details/bb)

heartbeatAvailable

0:1

Boolean

Indicates whether this Provider publishes a /heartbeat topic (true/false)

usageHints

0:*

String

Used for additional information related to the publisher or item. E.g. ConnID (Connection ID/User), ClientID, etc.

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 11.- Provider /info message structure

providerType enums1

validator

gnss

ticketVending

canGateway

avms

vehicleSignalsInterface

driverInterface

powerControl

passengerDisplay

Others as needed2

1Note: The purpose of providerType is to offer subscribers information about the source of the OPI they are using, specially in cases where the Equipment Item and its Application(s) are not enough to know the source of an OPI because the same OPI is provided by different Providers in the same Application (e.g. a ticket vending machine, TVM, may publish network location data (line, next stop) introduced by the driver or automatically obtained by an AVMS function included in the TVM. In the first case the providerType will be “driverInterfaces” and in the second case “avms”. Without providerType the consumer of this information will not be able to know its origin).

2Note: Specific projects must use ODEx providerType enums while they are adequate but may define their own providerType if needed.

JSON example: 

{ 
  "timestamp": "2025-05-27T11:05:00Z", 
  "topicPath": <root>/inventory/providers/c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1/info, 
  "itemType": "Provider", 
  "providerType": "gnss", 
  "opInterfaces": [ { 
    "opiName": "gnss", 
    "opiVersion": "v1.0"
   }, { 
    "opiName": <OPI_name>, 
    "opiVersion": <OPI_name>
   } ], 
  "description": "GNSS provider application", 
  "configTopics": [ 
    <root>/inventory/providers/c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1/info, 
    <root>/inventory/providers/c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1/topics_declared
   ], 
  "heartbeatAvailable": true
}

/topics_declared (Operational Interfaces implemented by the Provider)

Topic (s)

QoS

Retain

Published by

< root>/inventory/providers/< provider_GUID>/topics_declared

1

1

Provider

Table 12.- Provider topics_declared topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

topicsProvided

0:*

String

Topic paths where the provider publishes data. Each full path where a /operation topic is published must be included, see ODEx-4 document to see the different DataGroups.

controlOffered

0:*

String

Topic paths where the provider is subscribed and accepts commands.

any

0:1

anyType

Optional additional fields freely defined by the MQTT client.

Table 13.- Provider /topics_declared message structure

JSON example: 

{ 
  "timestamp": "2025-05-27T11:05:01Z", 
  "topicPath": <root>/inventory/providers/c2a1d3f4-8e7b-4d90-b312-34fe7e2f5b1/topics_declared, 
  "topicsProvided": [ 
    <root>/operation/c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1/gnss/v1.0/data/gnss_data
   ], 
  "controlsOffered": [ 
    <root>/operation/c2a1d3f4-8e7b-4d90-b312-a34fe7e2f5b1/gnss/v1.0/cmd/reset_distance
   ] 
}

/details (Additional information about the Provider)

The topic < root>/inventory/providers/< provider_GUID>/detailsis an optional topicreserved for any extra information about the Provider that does not fit under /info or /topics_declared.

INFORMATION ON SW AND DATA AND THEIR UPDATES

(See section # 3.4 INFORMATION ON SW AND DATA AND THEIR UPDATES in ODEx-1 specifications)

/info (Basic information about SW and Data of ITS-PT components and their Updates)

Topic (s)

QoS

Retain

Published by

< root>/sw_update_info/< update_GUID>/< GUID of equip, app, provider>/info

< root>/data_update_info/< update_GUID>/< GUID of equip, app, provider>/info

1

1

Provider

Table 14.- SW and Data Updates General Information topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

itemType

1:1

String

Item Type as defined in Section #2.9 Item Type from ODEx 01 Specification: “Data Update” or “SW Update”

updateStatus

1:1

String

"current", "scheduled", "pending", "downloading", "installing", "installed", "failed", "rolled_back"(see states of an update enum in Section #3.4 INFORMATION ON UPDATES from ODEx 01 Specification)

description

0:1

String

Short human-readable description of what the update contains, e.g.

“Configuration parameters”, “White list”, “CAN template”, “AI model”

configTopics

0:*

String

All self-published topics (/info, /details, /details/logs, etc)

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 15.- SW & Data /info message structure

JSON example (SW Update): 

{ 
  "timestamp": "2025-06-01T19:45:00Z", 
  "topicPath": <root>/sw_update_info/f48a7d.../550e84.../info, 
  "itemType": "SW Update", 
  "updateStatus": "downloading", 
  "description": "Firmware 3.1.0 for validator devices", 
  "configTopics": [ 
    <root>/sw_update_info/f48a7d.../550e84.../info, 
    <root>/sw_update_info/f48a7d.../550e84.../details, 
    <root>/sw_update_info/f48a7d.../550e84.../details/logs
   ] 
}

/details (Detailed information about SW and Data of ITS-PT components and their Updates)

Topic (s)

QoS

Retain

Published by

< root>/sw_update_info/< update_GUID>/< GUID of equip, app, provider>/details

< root>/data_update_info/< update_GUID>/< GUID of equip, app, provider>/details

1

1

Provider

Table 16.- SW and Data Updates Details topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

packageMetadata

1:1

Object

Static metadata about the update

guidValue

1:1

String (UUIDv4)

Update GUID of new version

version

1:1

String

Package version

releaseDate

1:1

Datetime (ISO-8601)

Date of official release

fileSignature

0:1

String

Digital signature of the update file

fileSource

0:1

String

Source of the package

snapshotID

1:1

Integer

Snapshot identifier/counter (since every new snapshot retained message is overwritten)

stateSnapshot

1:1

Object

Live status of the update process

updateStatus

1:1

String

Current update state. Allowed values:

"current", "scheduled", "pending", "downloading", "installing", "installed", "failed", "rolled_back", “old”

scheduledApplyDate

0:1

Datetime (ISO-8601)

Planned time to apply/install the update

lastDownload

0:1

Object

Information about the last download attempt

version

1:1

String

Version downloaded

date

1:1

String

When the download occurred

result

1:1

String

Result of the download ("OK", "NOK", "rollback")

description

0:1

String

Additional explanation or debug notes

lastInstall

0:1

Object

Information about the last installation attempt

date

1:1

String

When the installation occurred

result

1:1

String

Installation result ("OK", "NOK")

description

0:1

String

Additional explanation or debug notes

previousVersion

0:1

Object

Version information before update

version

1:1

String

Previous package version

date

1:1

Datetime (ISO-8601)

Date of previous version deployment

newVersion

0:1

Object

Version information after update

version

1:1

String

Newly installed version

date

1:1

Datetime (ISO-8601)

Date of new version activation

extraLogs

0:*

String

Extra topic paths under /details with more information about the snapshot state. Can be structured as desired, such as having a path for each snapshot id. E.g. [“.../details/logs/snapshot_id/< 1…N>/…”]

any

0:1

anyType

Optional additional fields freely defined by the MQTT client.

Table 17.- SW & Data /details message structure

Example A: Package scheduledfor tonight (no download yet)

{ 
  "timestamp": "2025-06-30T20:00:00Z", 
  "topicPath": <root>/data_update_info/f48a7d.../550e84.../details, 

  "packageMetadata": { 
    "guidValue": "f48a7d18-cf3f-4c6e-91a3-daa1705fa987", 
    "version": "cfg-1.3", 
    "releaseDate": "2025-06-01"
   }, 

  "snapshotId": 1, 

  "stateSnapshot": { 
    "updateStatus": "scheduled", 
    "scheduledApplyDate": "2025-07-01T03:00:00Z"
   } 
}

Example B: Download OK, waiting for install (pending)

{ 
  "timestamp": "2025-06-30T23:16:00Z", 
  "topicPath": <root>/data_update_info/f48a7d.../550e84.../details, 

  "packageMetadata": { 
    "guidValue": "f48a7d18-cf3f-4c6e-91a3-daa1705fa987", 
    "version": "cfg-1.3", 
    "releaseDate": "2025-06-01"
   }, 

  "snapshotId": 2, 

  "stateSnapshot": { 
    "updateStatus": "pending", 
    "scheduledApplyDate": "2025-07-01T03:00:00Z", 

    "lastDownload": { 
      "version": "cfg-1.3", 
      "date": "2025-06-30T23:15:00Z", 
      "result": "OK", 
      "description": "Download successful"
     } 
   } 
}

Example C: Install succeeded, package current

{ 
  "timestamp": "2025-07-01T03:07:30Z", 
  "topicPath": <root>/data_update_info/f48a7d.../550e84.../details, 

  "packageMetadata": { 
    "guidValue": "f48a7d18-cf3f-4c6e-91a3-daa1705fa987", 
    "version": "cfg-1.3", 
    "releaseDate": "2025-06-01"
   }, 

  "snapshotId": 3, 

  "stateSnapshot": { 

    "updateStatus": "current", 

    "lastDownload": { 
      "version": "cfg-1.3", 
      "date": "2025-06-30T23:15:00Z", 
      "result": "OK"
     }, 

    "lastInstall": { 
      "date": "2025-07-01T03:07:00Z", 
      "result": "OK", 
      "description": "Installed successfully during scheduled window", 

      "previousVersion": { 
        "version": "cfg-1.2", 
        "date": "2025-05-01"
       }, 

      "newVersion": { 
        "version": "cfg-1.3", 
        "date": "2025-06-01"
       } 

     } 

   }, 

  "extraLogs": [ 
    <root>/data_update_info/f48a7d.../550e84.../details/logs/snapshot_id/3
   ] 

}

Managing Updates (informative)

ODEx requires Equipment Items and applications to inform about their software and data and their updates status as specified in the previous sections but does not provide a solution to manage such updates, which can be specific for each product. A possible solution is to add a /cmdtopic under the corresponding Equipment Item, Application or Provider topic for these components to accept commands to download new software or data:

- <root>/sw_update_info

- <update_GUID>

- <GUID of equip, app, provider>

- /info

- /details

- /cmd

The commands could be coded as an ODEx JSON including the following information:

  • Element to download: Software, Data, (Specific data such as white lists)
  • Type of command: Download, Cancel
  • Download site: e.g and sFTP server IP
  • Download token: the Update_GUID can be used for the server to provide the correct file to download
  • Download start conditions: Immediately, at next vehicle contact ON or contact OFF or at a specified date and time
  • Update conditions: Immediately, at next vehicle contact ON or contact OFF or at a specified date and time

The component to be updated will only accept commands from the specific application in the BackOffice authorised to update the component, which will be in the access control list, ACL, of the onboard MQTT broker. Additionally, all update files will be signed with a key known only by the component and the authorised Application. Commands could be also signed. For additional security all signature keys will be diversified with the Update GUID.

STATUS & HEARTBEAT

Every ODEx Equipment Item and Providershall publish:

Purpose

Topic pattern

Heartbeat (liveness)

< root>/inventory/< equipment_items>/< GUID>/heartbeat

< root>/inventory/< providers>/< GUID>/heartbeat

Simple Status (global OK / NOK flag)

< root>/inventory/< equipment_items>/< GUID>/status

< root>/inventory/< providers>/< GUID>/status

Detailed Status Report (active problems)

< root>/inventory/< equipment_items>/< GUID>/status/report

< root>/inventory/< providers>/< GUID>/report

Status Definitions (dictionary of codes)

(OPTIONAL)

< root>/inventory/< equipment_items>/< GUID>/status/definitions

< root>/inventory/< providers>/< GUID>/status/definitions

Table 18.- Status & Heartbeat MQTT topics summary

/heartbeat

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/heartbeat

< root>/inventory/providers/< provider_GUID>/heartbeat

1

1

Equipment item

Provider

Table 19.- Heartbeat topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

heartbeatIntervalSecs

1:1

Integer

Integer indicating the expected heartbeat interval in seconds (10–300). If exceeded, IMS and other subscribers may count missed heartbeats. After 3 consecutive misses, IMS marks the application as inactive.

seq

0:1

Integer

Optional, for MQTT 3.1/3.1.1 users. See Note below

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 20.- /heartbeat message structure

Note:To facilitate missed‐beat detection, publishers shouldinclude an incrementing integer in the MQTT User Property named seq, as defined in MQTT 53.3.2.3.7 User Property (MQTT 5.0 exclusive). Subscribers can detect gaps in the sequence to identify lost heartbeats. If using an older version, this field can be included in the payload.

JSON example: 

{ 
  "timestamp": "2025-06-06T10:15:00Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/heartbeat, 
  "heartbeatIntervalSecs": 20, 
  "seq": 185
}

/status (Basic Status)

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/status

< root>/inventory/providers/< provider_GUID>/status

1

1

Equipment item

Provider

Table 21.- Simple status topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

statusCode

1:1

Integer

0=OK, non-zero=condition present

description

0:1

String

Optional human-readable text

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 22.- Simple /status message structure

JSON example: 

{ 
  "timestamp": "2025-06-06T10:15:05Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/status, 
  "statusCode": 0
}

/status/reports (Detailed Status Report)

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/status/reports

< root>/inventory/providers/< provider_GUID>/status/reports

1

1

Equipment item

Provider

Table 23.- Status Reports topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicpath

1:1

String

Exact MQTT topic path for this message

statusItems

1:1

Object

One entry per active condition

conditionId

1:1

Integer

Numeric code (1-99 reserved ODEx, 100+ custom).

severity

1:1

String (Enum)

See Severity Enum below

description

0:1

String

Human-readable text

detectedAt

1:1

DateTime (ISO8601)

When the condition was (last) detected

componentId

0:1

String

ID of the affected item: Equipment Item or HW components of the Eq. Item, Provider or SW component of the Provider:

  • use a GUID if the sub-unit (or equipment) is declared in ODEx
  • otherwise, a short alias can be used (e.g. eth0, printer, display…).

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 24.- Status /reports message structure

The different severity fields to use defined in ODEX are the following:

Severity Enum

When to use it

"noError"

Publish this value when a condition that was previously reported has disappeared or returned to normal.

"information"

Informational events that do not represent any malfunction.

"warning"

An abnormal situation that might degrade service if it persists.

"malfunction"

A fault that already degrades functionality (reduced performance, fallback mode).

"notRunning"

Component or application is unable to run or has crashed irrecoverably.

any

Optional additional Severity fields freely defined by the MQTT client.

JSON example: 

{ 
  "timestamp": "2025-06-06T10:16:50Z", 
  "topicPath": <root>/inventory/equipment_items/550e8400-e29b-41d4-a716-446655440000/status/reports, 
  "statusItems": [ { 
    "conditionId": 21, 
    "severity": "warning", 
    "description": "Ethernet link unstable", 
    "detectedAt": "2025-06-06T10:16:45Z"
   }, { 
    "conditionId": 42, 
    "severity": "malfunction", 
    "description": "LIDAR sensor not responding", 
    "detectedAt": "2025-06-06T10:16:20Z", 
    "componentId": "lidar0"
   } ] 
}

/status/definitions (Status Definitions, OPTIONAL)

Topic (s)

QoS

Retain

Published by

< root>/inventory/equipment_items/< equip_GUID>/status/definitions

< root>/inventory/providers/< provider_GUID>/status/definitions

1

1

Equipment item

Provider

Table 25.- Status Definitions topic summary

The objective of this optional topic is for the equipment or provider to publish all “conditionId”defined for that specific Equipment Item or provider.

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

statusItems

1:1

Object

One entry per each defined condition

conditionId

1:1

Integer

Numeric code (1-99 reserved ODEx, 100+ custom)

severity

1:1

String (Enum)

See Severity Enum in previous section

description

0:1

String

Human-readable text

any

0:1

anyType

Optional additional fields freely defined by the MQTT client

Table 26.- Status /definitions message structure

JSON example: 

{ 
  "timestamp": "2025-06-06T09:00:00Z", 
  "topicPath": <root>/inventory/equipment_items/550e84.../status/definitions, 
  "statusItems": [ { 
    "conditionId": 100, 
    "severity": "warning", 
    "description": "Ethernet link unstable"
   }, { 
    "conditionId": 101, 
    "severity": "malfunction", 
    "description": "Sensor not responding"
   } ] 
}

GENERAL INFO

/odex_info

Topic (s)

QoS

Retain

Published by

< root>/general_info/odex_info

1

1

IMS (Inventory Management Service)

Table 27.- General Info odex_info topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

protocolVersion

1:1

String

Version of the ODEx protocol

boPath

0:1

String

MQTT topic path used to communicate with the BackOffice

startupState

0:1

String

Startup status (e.g., "normal", "starting_components")

supportedOpInterfaces

0:*

String

Informative list of supported Operational Interfaces (OPI_name) (e.g., ["gnss", "validator"])

Table 28.- General Info /odex_info message structure

/router_info

Topic (s)

QoS

Retain

Published by

< root>/general_info/router_info

1

1

IMS (Inventory Management Service)

Table 29.- General Info router_info topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

ip

0:*

String

List of IP addresses assigned to the router

hostname

0:1

String

Router hostname, if known

macAddress

0:1

String

MAC address of the primary interface

interfaceName

0:1

String

Interface name used by the router

lastBoot

0:1

Datetime (ISO-8601)

Timestamp of the last system boot

Table 30.- General Info /router_info message structure

/broker_info

Topic (s)

QoS

Retain

Published by

< root>/general_info/broker_info

1

1

IMS (Inventory Management Service)

Table 31.- General Info broker_info topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

brokerHostname

0:1

String

hostname of module hosting the broker

brokerIp

0:1

String

IP address of module hosting the broker

brokerEndpoints

0:*

Object

List of MQTT connection endpoints exposed by the broker

ports

1:*

Integer

TCP port used by the broker (e.g., 1883, 8883, 443)

tls

1:*

Boolean

Whether the connection on such port requires TLS

mqttVersion

1:1

String

MQTT protocol version used (e.g., "3.1.1" or "5.0")

aclVersion

1:1

String

Version identifier of the Access Control List, if applicable

maxQosSupported

1:1

Integer

Maximum Quality of Service level supported (0, 1 or 2)

persistentSessions

0:1

Boolean

Whether persistent sessions are supported

lastRestartDatetime

0:1

DateTime (ISO8601)

Timestamp of the last broker restart

Table 32.- General Info /broker_info message structure

/environment

Topic (s)

QoS

Retain

Published by

< root>/general_info/environment

1

1

IMS (Inventory Management Service)

Table 33.- General Info Environment topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

appliedAt

1:1

DateTime (ISO8601)

The date and time at which the setting was registered

validUntil

0:1

DateTime (ISO8601)

The date and time at which the setting is expected to become invalid

operatingState

1:1

String

Active operating mode: "DEVELOPMENT", "INTEGRATION", "TESTING", "PRE-PRODUCTION", "PRODUCTION", "TECH-SUPPORT"

Table 34.- General Info /environment message structure

/vehicle_id

Topic (s)

QoS

Retain

Published by

< root>/general_info/vehicle_id

1

1

IMS (Inventory Management Service)

Table 35.- General Info vehicle_id topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

vehicleId

1:1

String

Identifier of the vehicle where the system is installed. VIN for bus.

Table 36.- General Info /vehicle_id message structure

/date_time

Topic (s)

QoS

Retain

Published by

< root>/general_info/date_time

1

1

IMS (Inventory Management Service)

Table 37.- General Info date_time topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

dateTimeSource

1:1

String

Identifier of the source of the date and time information

Table 38.- General Info /date_time message structure

/pto

Topic (s)

QoS

Retain

Published by

< root>/general_info/pto

1

1

IMS (Inventory Management Service)

Table 39.- General Info pto topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

ptoRef

1:1

String

Identifier of the Public Transport Operator operating the vehicle

Table 40.- General Info /pto message structure

/pta

Topic (s)

QoS

Retain

Published by

< root>/general_info/pta

1

1

IMS (Inventory Management Service)

Table 41.- General Info pta topic summary

Payload structure:

JSON fields

+Structure

Description

timestamp

0:1

DateTime (ISO8601)

UTC timestamp of the message, ISO 8601 (UTC)

topicPath

1:1

String

Exact MQTT topic path for this message

ptaRef

1:1

String

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

Table 42.- General Info /pta message structure

    Anexo A – Summary of Inventory and Updates information associated to Equipment Items and Providers

Equipment Item

- Equipment Item GUID

- Info: Equipment type, name and short description. Heartbeat interval. Purpose (e.g. APC, Validator…)

- Hardware: Model and manufacturer, serial number, list of ethernet interfaces (MACs, names)…

- Software: Base firmware version, operating system version, short note/description

- Hosted applications: Name, version

- Providers implemented: Provider GUID, providerType, providerDescription

- Details: Hardware components: e.g. an internal GNSS, an internal accelerometer, an external air quality sensor connected to this Equipment Item

- Status: OK/NOK, or fault code, warning or error text

- Heartbeat

- Current SW, SW downloads and Updates

- Current Data, Data downloads and Updates


Provider

- Provider GUID

- Provider Type

- Equipment Item where it is hosted onboard (unless it is a BackOffice Provider publishing data onboard)

- Info: List of OPIs implemented by the Provider

- OPIs: Topics where DataGroups are published and Commands are accepted for each OPI

- Details: Additional information about the Provider, if any

- Status: OK/NOK or fault code, warning or error text

- Heartbeat

- Current SW, SW downloads and Updates

- Current Data, Data downloads and Updates