INTRODUCTION

The ODEx (Onboard Data Exchange) protocol is a set of specifications for the exchange of real time vehicle data, including:

data concerning the physical vehicle (obtained from the vehicle CAN buses and vehicle signals and sensors)
data related to the PT services run by the vehicle and
data related to the ITS-PT equipment installed onboard.

This document describes ODEx core Concepts and its functional specification and topic structure.

Objectives

ODEx has the following objectives:

ITS-PT Interoperability

To enable interoperability among onboard ITS-PT equipment and applications (e.g. AVMS units, validators, ticket vending machines, driver terminals, passenger information systems, automatic passenger counting sensors) by standardizing data exchange mechanisms and data formats.
To enable BackOffice applications to interoperate with onboard ITS-PT equipment and applications using the same standardized data exchange mechanisms

Management of onboard ITS-PT equipment

To maintain an up-to-date inventory of all onboard ITS-PT equipment, including their operational status.
To get information about their firmware version and updates.
To get information about their configuration data and updates.

Management of onboard ITS-PT software applications

To maintain an inventory of onboard ITS-PT applications, including their operational status.
To get information about their software version and updates.
To get information about their configuration (e.g. parameters, white lists,…) data and updates.

Document logic

Section #2.2ODEX FUNCTIONSdescribes the functions required to fulfill the previous ODEx objectives, following a brief summary of key concepts introduced in Section #2.1. SUMMARY OF ODEX CONCEPTS
Section #2.3ODEX DATA presents the data involved in these functions.
Sections #2.4EQUIPMENT ITEM, #2.5APPLICATION, and #2.6PROVIDER describe the main ITS-PT components expected to implement these functions and exchange the associated data.
Section #2.7OPERATIONAL INTERFACE (OPI) defines the interfaces used to exchange operational data.
Section #2.8GUID (Global Unique Identifier) explains the global unique identifier (GUID) used in ODEx.
Section #3FUNCTIONAL SPECIFICATION AND TOPIC STRUCTURE describes the data exchange mechanism and topics structure

Alignment with the European Interoperability Framework (EIF)

ODEx is designed with the goals specified in section 5.2 of CEN/TS 13149-7:2020 System and Network Architecture and in accordance with the principles of the European Interoperability Framework (EIF). In particular, ODEx adopts:

Open standards and publicly available specifications, avoiding vendor-specific technologies and ensuring accessibility for all implementers. ODEx uses MQTT, JSON, J1939, SIRI and Transmodel concepts and topic structures and declaration mechanisms based on the ITxPT’s Active Inventory Specification and can be easily mapped with the ones used in these Specifications.
Technical and semantic interoperability, through the use of standardized communication protocols and well-defined data structures with consistent meaning across systems.
Modularity and replaceability, enabling different onboard equipment and backoffice systems, from any provider, to interoperate without proprietary dependencies.
Transparency and extensibility, ensuring that the ODEx specifications, catalogs and data models can be openly consulted, implemented, and extended by projects and vendors.

By following these EIF principles, ODEx promotes an open, interoperable, and vendor-neutral environment for ITS-PT systems onboard vehicles.

ODEx Documents

Table 1.- ODEx Documents
Document
ODEx-1. Concepts and Functional Architecture (This document)	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	Operational interfaces data definitions and topics
ODEx-5. Usage and Examples	Practical guidelines and implementation examples

CORE CONCEPTS

SUMMARY OF ODEX CONCEPTS

ODEx defines the framework for data exchange between ITS-PT components operating over the vehicle’s onboard IP (ITS-PT) network. These ITS-PT components can be:

ITS-PT physical elements (hardware), referred to as Equipment Items, and
ITS-PT software components, referred to as Applications, which include onboard software as well as BackOffice Applications that interact with onboard components.
Some Applications implement one or more Providers, which are software components that have any of the following functions:

It accepts commands from other ITS-PT components (e.g. device reset, validator lock, etc.) or
It publishes operational data: i.e. data related to the PT operation (vehicle network location, occupancy, ticket validations, etc.) and data related to the physical vehicle (e.g. vehicle diagnosis data, speed, energy consumption, physical/GNSS location, passenger area temperature etc.)

For example, a Validator Application implements a Validator Provider, which publishes information about validation transactions and accepts commands to change its operating mode. It also consumes information from other Providers to know its location in the network (Line, JourneyPattern, Stop) in order to determine the correct fare.
In a more complex example, a Ticket Vending Machine (TVM) will typically implement a Ticket Vending Provider, which publishes information about ticket vending transactions and accepts commands, a Validator Provider (if the TVM includes an integrated validator) and a Driver Interface Provider, which publishes driver inputs and accept commands with information for the driver.

ITS-PT components interact through interfaces, which define the data published or consumed by ITS-PT components.

An Operational Interface (OPI) is a set of inputs (commands, requests) and outputs (datasets) of a Provider for a specific operational function - such as ticket validation, network location, passenger counting, or any other logical grouping of inputs and outputs of a Provider that is useful for the purposes of operational information exchange.

For example, a Validator OPI defines the data provided by the validator (validation transactions, operating parameters), and the commands accepted by the validator (e.g. to lock the validator).

Providers can be seen as the sources of data while OPIs are a logical grouping of data. If there are two different sources of the same type of data (e.g. two Validators) there would be two Providers implementing the same type of OPI (e.g. Validator)

Figure 1.- ODEx ITS-PT components and their interfaces to declare themselves, provide information about their status and updates and publish operational data

ODEx requires all Providers to:

Declare themselves indicating their basic information, operational interfaces that they implement, the topics where they publish data and the topics where they are subscribed to receive commands (if any)
Provide information about their status (malfunctions, warnings, mode of operation, not running)

Equipment Items must declare all Applications they host and the Providers implemented by each Application, if any.

All Providers, Applications, Updates, and Equipment Items must be identified within ODEx using a globally unique identifier (GUID). This identifier is self-assigned by each component following RFC 9562, using the UUIDv4 format (e.g., bb6abc3b-0772-497e-8aa7-ad689c423c1d). The GUID is persistent and is used within the ODEx topic structure.

ODEX FUNCTIONS

The functions required to fulfill the previous ODEx objectives are the following:

Type	Equipment Items, Applications and Providers	Consumers
Inventory	Declaring Equipment Items and the operational applications they host, indicating the Providers implemented by each application.	Discovering Equipment items on the vehicle and the Applications and Providers they host
Inventory	Providing information about the status of Equipment Items and Providers	Obtaining information about the status of Equipment Items and Providers
Updates	Providing information related to current software and updates of Equipment Items and Applications	Obtaining information related to current software and updates of Equipment Items and Applications
Updates	Providing information related to data/configuration and updates of Equipment Items, Applications and Providers	Obtaining information related to data/configuration and updates of Equipment Items, Applications and Providers
Operation	Providing operational data Accepting Commands	Obtaining operational data Sending Commands

Figure 2.- Summary of ODEx functions implemented by an ITS-PT indicating which ones are done at startup and at runtime

For example, a Validator complying with ODEx will implement the following functions:

Connect to ODEx MQTT Broker using an MQTT client.
Declare itself as an Equipment Item (only if the validator is an independent hardware unit, not integrated into a ticket vending machine) and
Declare itself as a Provider
Provide information about its software and software updates
Provide information about its configuration, white lists or other data and their updates
Provide information about its status (malfunctions, mode of operation)
Publish data about each validation transaction, publish its operating parameters and accept commands according to a predefined OPI (Operational Interface)

The table in #Anexo A. ODEX summarizes all possible functions in ODEx.

ODEX DATA

In line with the functions described above, the data published in ODEx can be categorized as follows:

INVENTORY DATA

Information related to the declaration and identification of Equipment Items and Providers.
Status of Equipment Items and Providers
Data concerning the operational state of Equipment Items and Providers, including faults, warnings, and current mode.

INFORMATION ABOUT UPDATES OF SOFTWARE AND DATA

Details about the software versions and software updates of Equipment Items and Applications
Details about the configuration data and data updates. of Equipment Items and Applications

OPERATIONAL DATA AND COMMANDS, published by Providers. This includes:

Data related to public transport operations such as vehicle network location (line, journey pattern, previous and next stop, etc.), vehicle scheduling (service journey, calls, delays, deviations, etc.), vehicle occupancy levels, ticket validations, passenger information, messages to the driver, etc.
Data related to the physical vehicle such as diagnostic data, speed, energy consumption, GNSS location, accelerations, passenger area temperature, etc.
Commands accepted by Providers to request information or execute some action.

EQUIPMENT ITEM

An Equipment Item is any ITS-PT physical element (hardware) installed in the vehicle, particularly those with IP connectivity, an MQTT client and software implementing the ODEx functions for declaring, providing status information and eventually accepting commands (e.g. reset).

Equipment Items without IP connectivity or without ODEx software could still be declared and provide their status if they are connected or integrated into another Equipment Item with these capabilities.

Equipment Items that host any Provider or that accept commands must be declared and provide status information and information about their software and configuration, as well as any other Equipment Item if their status or other information needs to be made available in the system.

Diagrama, Tabla

El contenido generado por IA puede ser incorrecto. — Figure 3.- ODEx Equipment Items Categorization, with examples

(See #Anexo B. Catalog of Equipment)

APPLICATION

An Application is any ITS-PT software component installed on an onboard Equipment Item.

An Application shall be declared in ODEx if it has the following conditions:

It holds data that ODEx requires to be shared (including any data defined in ODEx DataGroups). In this case, the Application shall implement the corresponding OPI(s) and declare the Provider(s) implementing those OPI(s).

Any software component executed in the BackOffice that publishes ODEx data onboard or otherwise participates in ODEx exchanges within the vehicle shall also implement the corresponding OPI(s) and declare the Provider(s) implementing those OPI(s).

Its software version and SW update status or its Data update status (e.g., configuration, parameters, catalogs, operational datasets, lists) are required to be known, even if the Application does not implement any Provider or publish ODEx data.

PROVIDER

A Provider is a SW component that:

Publishes operational data and/or
Accepts commands

directly to/from the onboard broker or through a gateway application if the Provider is not directly connected to the onboard ITS network (e.g. in the case of a BackOffice application which publishes data onboard).

In addition to publishing operational information or accepting commands, all Providers must:

Declare themselves, providing the topics to which they publish or are subscribed to receive commands.

If capable, all onboard Providers shall:

Provide status information.
Provide information about their software and software updates.
Provide information about their configuration and data updates.

ODEx uses the concept of “Provider” to identify the source of the information published. A Provider could be an Equipment Item application (e.g. a Validator unit), a HW component application (e.g. a GNSS module), an application hosted in an Equipment item which also hosts other applications (e.g. an AVMS application hosted by an onboard computer) or a BackOffice application module.
Without the concept of “Provider”, two sources of the same type of information will have to publish it to the same topic, and the source of the information will have to be coded in the payload. This would be less convenient than the solution adopted in ODEx, where this information is published to two topics with the same name, each under its Provider, so that the data of both providers is retained instead of being substituted by the most recent publication from one of them.
For example, a Ticket Vending Machine (TVM) which includes a ticket vending application, an integrated validator, a driver display and a AVMS application, could have two sources for the same type of information such as the Line or the next Stop: the AVMS and the driver. Therefore, instead of defining the TVM as a Provider it is convenient to define its display and its AVMS application as different Providers. Its TVM application, and its integrated validator will also be TVM Providers.

OPERATIONAL INTERFACE (OPI)

An Operational Interface (OPI) is a set of inputs (commands, requests) and outputs (datasets) of a Provider for a specific operational function - such as ticket validation, GNSS positioning, passenger counting, or any other logical grouping of inputs and outputs of a Provider that is useful for the purposes of operational information exchange.

An Operational Interface can be considered as an instance of a Feature Set in ITxPT specifications.

By definition, a Provider either publishes operational data or accepts commands or both; therefore, each Provider must have at least one OPI that defines such data and commands.

Figure 4.- Functional Diagram of a Provider with Operational Interfaces and Dataflows

In ODEx, all operational information is organized by Provider (the source of the information), by OPI (a logical grouping of related information), and by DataGroups (which further structure the information published by an OPI).

Projects implementing ODEx shall define the OPI catalog and the Provider types they require. ODEx provides a reference OPI catalog and a set of enums for Provider types, both of which may be used as-is or extended with additional OPIs and Provider types to meet project-specific needs.

Operational Interfaces are defined in other document: ODEx-4. Operational Interfaces

GUID (Global Unique Identifier)

ODEx uses a Global Unique Identifier to univocally identify Providers, Applications, Equipment Items and Updates of software and data.

Table 2.- ODEx GUID specific names used in this specification
Concept	GUID specific name used in ODEx
Equipment Item	equip_GUID
Application	app_GUID
Provider	provider_GUID
Update of software or data	update_GUID

The GUID is self-assigned by each component following RFC 9562, using the UUIDv4 format. In the case of Updates and BackOffice Applications the GUID is generated in the BackOffice.

The GUID is persistent and is used within the ODEx topic structure. Example:

odex/inventory/equipment_items/bb6abc3b-0772-497e-8aa7-ad689c423c1d/

ITEM TYPE

Attribute used in …/infotopics which reside outside of the /operationstructure to indicate the type of item the payload refers to. It can have one of the following values and, depending on its value, it can have different additional information as shown in the table:

Table 3.- ODEx Item Types
ITEM TYPE	Additional information
Equipment Item	<Equipment type> (ej.HOST, SP-OBC, OBU, VAL, TVM, DT, APC…)
Provider	<Provider Type> and <Operational Interfaces> (ej. GNSS, NetworkLocation, DoorsStatus…)
SW Update	<SW Update Status> (ej. Current, Scheduled, Failed…)
Data Update	<Data Update Status> (ej. Current, Scheduled, Failed…)

FUNCTIONAL SPECIFICATION AND TOPIC STRUCTURE

TOP-LEVEL TOPIC STRUCTURE

/inventory: Holds the structured information about installed equipment items (inventory/equipment_items) and active providers (inventory/providers), including the /operation topic paths where they publish operational data or receive commands.
/sw_update_infoand /data_update_info: Used to publish information about software or data/configuration update attempts (e.g., versions, results, dates). They also hold the currently installed software or data versions.
/operation: Main topic branch for operational data exchange.
/general_info: Supplies contextual information about the ODEx environment, such as the current operating mode and broker configuration.

Useful generic subscriptions: (Each subsection lists additional topic-specific filters)

odex/ver1.0/+/+/+/info- Monitors every Equipment Item and Provider and any update they report.

odex/ver1.0/+/+/<GUID>/info- Monitors a single Equipment Item or Provider (identified by <GUID>) and all updates it reports.

GLOBAL TOPIC STRUCTURE

INVENTORY

The main purpose of the inventory is to enable plug-and-play installation of new ITS-PT components on the vehicle, by allowing:

New Equipment Items (and their hosted Applications and their Providers) or Providers to declare themselves, the data they provide and the commands they accept
New Equipment Items or Applications to discover the data provided and the commands accepted by otheronboard ITS-PT components

The inventory also supports maintenance, monitoring, and diagnostic tasks, enabling BackOffice applications to identify all Equipment Items and Applications installed on each vehicle and monitor their operational status.

Also, for security reasons, messages sent by Providers which are not registered in the Inventory may be ignored by all subscribers.

Accordingly, the following inventory Equipment item related information is published:

Table 4.- Inventory information about Equipment Items
Information aboutEQUIPMENT ITEMS	Description
Topic path where information is published: odex/ver1.0/inventory/equipment_items/<equip_GUID> Equipment Items should declare themselves each time they connect to the MQTT broker (e.g. at power on, due to a broker reset). (Notice that eBuses may have the 24V aux power always on. It is assumed that power control device will switch the rest of ITS off)
General information	When: Published at declaration Data in topics: /info Equipment type, name and short description. Heartbeat interval. If the Equipment Type is SP-OBC, its purpose (e.g. telemetry, avms…) should be declared here too.
Hardware description	When: Published at declaration and whenever hardware details change Data in topics: /hardware Model and manufacturer, serial number, list of ethernet interfaces (MACs, names)… /details Hardware components: e.g. an internal GNSS, an internal accelerometer, an external air quality sensor connected to this Equipment Item)
Current software/firmware	When: Published at declaration and when the base firmware or OS changes Data in topics: /softwareBase firmware version, operating system version, short note/description
Hosted applications	When: Together with the software information and whenever the hosted applications list changes Data in topics: /software For each hosted application: name, version, GUID and Providers it implements
Equipment status (heartbeat and status)	When: Heartbeat: periodically. Status: each time a condition is detected or when a detected condition changes Data in topics: /status Simple status, info/errors/warnings and definitions /heartbeat Heartbeat with next relative beat time

For Providers, the following related information is published:

Table 5.- Inventory information a bout Providers
Information about PROVIDERS	Description
Topic path where information is published: odex/ver1.0/inventory/providers/<provider_GUID> Providers should declare themselves each time their MQTT client connects to the MQTT broker.
General information	When: Published at declaration or when static data changes Data in topics: /info Provider name, type and short description. Heartbeat interval.
Operational Interfaces implemented	When: Together with the general information Data in topics: /info List of OPIs names implemented by the provider.
Topics declared	When: Published at declaration and whenever topics change Data in topics: /topics_declared Topics where the provider publishes operational data and topics where it accepts commands. The lowest-level topic name (i.e., the last segment of the topic path) must correspond to a predefined dataGroup in the ODEx or Project data dictionary. This allows subscribers to discover all /operation paths at startup and subscribe to the topics of their interest. If the Provider runs more than one OPI, topics should be organized by OPI (/topics_declared//data and /cmd) This discovery mechanism allows consumers to discover what predefined datagroups are being published but variables in datagroups may be optional and the consumer may need to subscribe to the corresponding topic to consume the datagroup in order to know which variables are actually available.
Provider status (heartbeat and status)	When: Heartbeat: periodically Status: when condition changes Data in topics: /status Simple status, info/errors/warnings and definitions /heartbeat Heartbeat with relative next beat time

Figure 7.- Topic Structure for declaration of Equipment Items and Providers (inventory information)

Common subscriptions:

odex/ver1.0/inventory/#- Detects any addition or update of information

odex/ver1.0/inventory/equipment_items/+/info- Basic info from every equipment item

odex/ver1.0/inventory/providers/+/topics_declared- Declared topics for each provider

INFORMATION ON SW AND DATA AND THEIR UPDATES

The purpose of ODEx Update functions is to provide a means to publish information about the software/firmware and Data of the following ITS-PT components:Equipment Items, Providers or other Applications.

Here, the concept of Data includes configuration parameters, catalogs, lists, AI model coefficients or any other data used by these ITS-PT components in operational functions.

The concept of Updates includes the downloading process and the actual update, whether it takes place immediately after downloading or later (e.g. at a specified date or after a particular event such as bus contact off) and includes complete updates as well as unsuccessful downloads or actual update attempts.

Notice that the purpose of ODEx Update functions is not to manage the actual downloading of SW and Data but to provide a place to publish and consume information about the current software and data of each Equipment Item,Provider or other Application and about their Updates.

These ITS-PT components must publish this information each time their MQTT client connects to the broker and after each update.

Each Update must have a unique UUID v4 (update_GUID), which could be assigned by the BackOffice application responsible for the Update or locally if it is not supplied by the BackOffice.

The update_GUIDs for SW and Data information published at power on should be the update_GUIDs corresponding to the downloading and actual Updates of these SW and Data, unless they have never been updated (e.g. factory SW or Data) in which case specific update_GUIDs should be created to publish this information. In this case the same updated_GUIDs should be used at each power on until an Update occurs.

Current software/firmare and Data information of these ITS-PT components and information on their updates must be published under a topic with the update_GUID and a topic under the ITS-PT component GUID:

<root>/sw_update_info/<update_GUID>/<GUID of equip, app, provider>/… (for SW Updates)

<root>/data_update_info/<update_GUID>/<GUID of equip, app, provider>/… (for Data Updates)

This allows publishing information about single updates affecting several ITS-PT components.

Each ITS-PT component will publish this information with retain flag under its own topic /info and /details ) allowing subscribers to monitor the life cycle of each update.

Table 6.- Topics used to publish information related to Updates
Topic	Purpose	Core fields
/info	Publish compact information about the update and the state of its life-cycle	Update type (data or software) Update status (current, scheduled, pending, downloading…) Description
/details	Full snapshot, overwritten on every change in the status	Package metadata: static basic information about the update Snapshot id: increments after a new state snapshot is published, replacing the previous one State snapshot: each snapshot showcases the details of the download or installation for an update, also including the actual status of an update for when the snapshot was published

Accordingly, the following information related to updates can be discovered:

Table 7.- Information related to Updates
Information	Description
Topic paths where information is published: Information on software updates: odex/ver1.0/sw_update_info/<update_guid>/<app_GUID or equip_GUID> Information on data updates: odex/ver1.0/data_update_info/<update_guid>/<app_GUID or equip_GUID>
Current Software Version Information	When: Published with retained flag at each connection to the MQTT broker Data in topics: /info Status of update= current.Type of update (data or software), description /details Static metadata of the package, status of the update in the last snapshot, download and installation information.
Pending Software Version Information	When: Published with retained flag at each connection to the MQTT broker Data in topics: /info Status of update = pending. Type of update (data or software), description /details Static metadata of the pending version, status of the update in the snapshot, scheduled application date = planned update date
Information on software downloads	When: Published with retained flag after a download is finished (whether it has been successful or not) Data in topics: /infoStatus of update = scheduled or downloading. Type of update (data or software), description /details Static metadata of the scheduled or downloading package, scheduled download date, download result (OK, NOK. e.g., download interrupted, signature mismatch), status of the update in the snapshot
Information on Updates	When: Published with retained flag after a software update is finished (whether it has been successful or not) Data in topics: /info Status of update (including results of update, check following list of states of an updates), type of update (data or software), description /details Static metadata of the package, update date, update result (e.g., rollback), information about the software version before the update (version, date, description), information about the software version after the update (version, date, description), status of the update in the snapshot

The different lifecycle states of an update in ODEx are defined in the following list:

scheduled: The package is planned but has not been downloaded yet.
downloading: Device is actively fetching the file.
pending: File fully downloaded, waiting for install window.
installing: Installer now running.
installed: Install step finished OK; version will become current after reboot/self-check.
current: Version that is in use. Only one can be current.
failed: Install attempt didn’t succeed.
rolled_back: Install succeeded but system later reverted to previous version.
old: previous version that was substituted by the current one.

These states, allow subscribers to monitor updates in all equipment items and applications, while also serve as a filter to identify the current and pending version, downloads and information on all updates.

Figure 8.- Topic Structure to publish information on software updates

Common subscriptions to know about software updates:

odex/ver1.0/sw_update_info/#- For general supervision, to monitor any software update attempt on the vehicle.

odex/ver1.0/sw_update_info/+/<app_GUID or equip_GUID>- For supervision of all software updates related to a specific equipment item or application/provider.

Figure 9.- Topic Structure to publish information on data/configuration updates

Common subscriptions to know about data/configuration updates:

odex/ver1.0/data_update_info/# - For general supervision, to monitor any data update attempt on the vehicle.

odex/ver1.0/data_update_info/+/<app_GUID or equip_GUID> - For supervision of all data updates related to a specific equipment item or application/provider.

OPERATION

The main purpose of the /operation topic branch is to structure the operational (business-related) data published by Providers and the topics where commands are accepted by Providers; therefore allowing:

Providers to publish the operational data they generate in the topics they previously declared in the inventory.
Other Applications or BackOffice systems to subscribe and consume this data in real time.
Providers to receive commands in the topics they previously declared in the inventory.
Authorized applications to send commands to Providers (e.g. reset device, change mode…).

Operational data in ODEx includes:

data concerning the physical vehicle (obtained from the vehicle CAN buses and vehicle signals and sensors), and
data related to the PT services provided by the vehicle

which is all the data considered in the Operational Interfaces (See ODEx-4)
Accordingly, the following operation-related information is published:

Table 8.- Topics used to publish Operational information
Information	Description
Topic path where information is published: odex/ver1.0/operation/<provider_GUID>/<OPI_name>
Provider operational data	When: As generated (periodic or event-driven) with the logic of the Operational Interface and at each connection with the MQTT broker. Data in topics: /dataUnder the /data branch, each OPI defines its own sub-topic hierarchy to organise the information it publishes. This sub-topic tree goes down to low level topics which correspond to datagroups predefined in ODEx or Project specific data dictionary extending ODEx’s
Provider command endpoints	When: Only when a command or response is exchanged. Data in topics: /cmd Under the /cmd branch, each OPI defines its own sub-topic hierarchy to organise the commands it can receive and the responses it may send. A command may be a request for information or a request for an action to be executed by the provider.

Figure 10.- Topic Structure to publish operational data

The /operationbranch follows a structure that makes it easy to route and filter every type of message:

odex/ver1.0/operation/<provider_GUID>/<OPI_name>/<OPI_version>/data/<path to datagroups>

Level 1 - Provider GUID (/<provider_GUID>)

The first path element after /operation is always the provider_GUID. This ties every publication or command to the Provider that owns it and matches the entry previously declared under /inventory/providers/<provider_GUID>.

Level 2 - Operational Interface (/<OPI_name>)

The second element is the Operational Interface name (network_location, validator, ticket_vending, …).

A Provider may publish several Operational Interfaces; each gets its own sub-tree so that consumers can selectively subscribe only to what they need.

Level 3 - Operational Interface Version (/<OPI_version>)

The third element is the Operational Interface Version (“v.X.X” e.g. “v1.0”).

This allows to have a version for each specific OPI, being able to update them unilaterally.

Level 4 - Leaf topics

/data: Continuous or event-driven operational data streams.
The provider will publish data using a topic structure under this topic. The lowest level topics in this topic structure must correspond to predefined datagroups in ODEx data dictionary or in a project-specific data dictionary.
/cmd: Commands (request for actions or requests for information) addressed to the Provider

To send a command to a Provider, the sender must publish on /operation/<provider_GUID>/<OPI_name>/cmd/<command_name>/<sender_GUID>
The <sender_GUID> uniquely identifies the issuer (e.g. an application GUID).
The Provider receiving the command will post its reply on the topic /operation/<provider_GUID>/<OPI_name>/cmd/<command_name>/<sender_GUID>/response

Common subscriptions:

odex/ver1.0/operation/+/+/data - To receive all published operational data from any provider and OPI type.

odex/ver1.0/operation/+/<OPI_name>/# - To receive all published operational data or commands from all versions from a specific OPI type.

odex/ver1.0/operation/<provider_GUID>/<OPI_name>/<OPI_version>/# - To receive all published operational data or commands from a specific OPI type.

odex/ver1.0/operation/<provider_GUID>/<OPI_name>/<OPI_version>/cmd/+/+ - To receive all commands (for the provider receiving the commands)

odex/ver1.0/operation/<provider_GUID>/<OPI_name>/<OPI_version>/cmd/+/<sender_GUID>/response - To receive the response to all commands sent (for the command sender)

GENERAL INFORMATION

The purpose of this topic is to provide the following information:

ODEx information

Version of the data dictionary
ODEx version

Router information

IP address of the onboard router
Hostname
Detail (4G, 5G, VPN used)

Broker information

IP address and ports
Hostname
MQTT versión
Details

Environment information

Vehicle ITS-PT operating mode (e.g., production, testing)
ITS-PT system startup state (e.g., normal, components starting not ready yet)

Vehicle identifier
Date and time
PTA
PTO

This information is published at each connection to the broker or whenever the information changes

Figure 11.- Topic Structure to publish general information

Common subscriptions:

odex/ver1.0/general_info/#- receives any context change

ANNEX A - ODEX Functions (Informative)

Functions marked with [P] are indicate that an Application implements a Provider.

Table 9.- ODEx Functions
	Equipment (HW) related functions	Applications (SW) related functions
Inventory	Declaring an Equipment Item: Generate GUID (persistent, used for topic names and included in the header of messages sent) Declaration: Name, equipment type, description… Manufacturer, Model, MAC Equipment Item HW versión List of Applications hosted Discovery of Equipment Items.	Declaring a Provider: Generate/use existing app GUID (persistent, for topic names and included in the header of messages sent) Declaration: Static metadata Information Provided and topics Commands accepted and topics Discovery of Providers and hosted applications.
Status info (inventory related)	Inform about the status of an Equipment Item: Equipment Item Heartbeat Equipment Item Errors and Warnings (e.g. no paper on printer) Equipment Item operating Mode (e.g. display switched off) Consumer of information about the status of Equipment Items	Inform about the status of a Provider: Provider Heartbeat Provider Errors and Warnings Provider operating Mode Consumer of information about the status of Providers
Updates info	Inform about FW updates of an Equipment Item: Generate/Use update GUID Equipment Item FW version and status: Active (date updated), Downloaded (date downloaded and date when it will be updated), Failed download (date), Failed update (date) Inform about Data updates of an Eq Item: Generate/Use update GUID Equipment Item data/configuration version and status: Active (date updated), Downloaded (date downloaded and date when it will be updated), Failed download (date), Failed update (date) Consumer of information about Software or Data updates of Equipment Items	Inform about FW updates of a Provider: Generate/Use update GUID Provider FW version and status: Active (date updated), Downloaded (date downloaded and date when it will be updated), Failed download (date), Failed update (date) Inform about Data updates of a Provider: Generate/Use update GUID Application version and status: Active (date updated), Downloaded (date downloaded and date when it will be updated), Failed download (date), Failed update (date) Consumer of information about Software or Data updates of Providers
Operation	Accept commands at Equipment Item level (e.g reset device, go to sleep mode) Send commands to an Equipment Item (Commands are sent only by authorized Providers).	[P] Provider of operational data (and also accepts requests for data which is published by request) Consumer of operational data [P] Accept commands Send commands (optional to register as a Provider if it only sends commands, this allows light clients)
Common	MQTT broker. Must be unique in the onboard ITS IP network. MQTT client. Each Equipment item must have at least one MQTT client. Separate clients can be used for specific providers, each with different access rights defined in the ACL. Inventory Management Service (IMS). Unique function in the onboard ITS IP network. Its purpose is to: Update the status of Equipment Items and Providers that are not available anymore in the inventory Publish general information (router’s IP address…)

ANNEX B - Catalog of Equipment Item Types

Equipment Item Type		Type ID	Description
M	General-purpose Onboard Computer (HOST computer)	HOST HOST	General Purpose OnBoard Computer which can host Applications from different suppliers.
M	Tablet	TABLET	A device that combines a HOST and a Driver Terminal
M	Special-purpose OBC	SP-OBC *(not in ITxPT)*	Device with one or more specialized functions, such as: AVMS/AVSM (automatic vehicle service monitoring) Telemetry OBC (CAN data and vehicle signals gateway) Multimedia (TTS audio and video output) Vehicle Data Hub ITS Power Control Unit Digital Video Recorder (DVR) Other
M	Onboard computer	OBU OBU	Onboard computer which does not implement any ODEx function other than Registering Device
M	Validator	VAL TICKETING	Ticket validator
M	Ticket vending Machine	TVM TICKETING	This device includes a printer, a driver terminal and possibly a validator and it may also be a general-purpose OBC hosting different ITS applications, such as an AVMS
M	Driver Terminal	DT TERMINAL	Device for driver interaction, displaying information to the driver and allowing the driver to input messages and commands.
M	Automatic Passenger Counter	APC *(not in ITxPT)*	Device which may be made of one APC central unit and several APC sensors (where only the central unit is connected to the ITS network) or where each sensor is connected to the ITS network.

OP	Information Display	SIGN SIGN	Display integrating a controller connected to the ITS network . A controller could have several displays connected.
OP	Digital Video Recorder	DVR
OP	Wireless Gateway/Router	ROUTER VCG
OP	Switch	SWITCH
OP	IP camera	IPCAM CAMERA
OP	Other	OTHR	Printer, GNSS, Sensor

		MULTIMEDIA	A device capable of both visual and audio output
		AUDIO	An audio device or separate PA system used for making announcements to passengers or crew.
		INTERCOM	An audio device capable of two-way audio communication
		MADT	A Multi-Application Driver Terminal device

M= These Equipment Items must register and provide status and update information (Mandatory)

OP= These Equipment Items may register and provide status and update information (Optional)

ITxPT equipment items in Green

Table 10.- Catalog of types of Equipment Items