# Edge Transportation Exchange - MQTT API 1.1.0 documentation The Edge Transportation Exchange (ETX) MQTT API provides a message exchange for all V2X communications. It allows clients to participate in the V2X ecosystem to build better and safer transportation. This documentation describes how the MQTT connections can be used for V2X communication in the ETX system. ## How to connect to the ETX message exchange 1. Call the ETX Registration services `registration` endpoint to request a device ID and certificate package. This ID and certificate will be needed to connect to the ETX message exchange through MQTT. - **Note:** This step is only needed for the very first connection attempt, if the client already has a device ID and a valid certificate, the `registration` endpoint doesn't have to be invoked. 2. Call the ETX Registration services `connection` endpoint to request the MQTT URL for the ETX message exchange. This request will provide the right MQTT endpoint based on client location and network connection type. 3. Use the credentials to create an MQTT connection to the received URL and start using the message exchange. ## MQTT Connections details * The ETX system uses MQTT 3.1.1 protocol (v4 in most of the client SDKs). * **The MQTT connection can only be established over TLS 1.2+ using the certificate provided by the ETX Registration service.** * **The MQTT connection requires that the device ID used as the MQTT client ID. The Device ID is provided by the ETX Registration service.** * The ETX system supports QoS 0 and QoS 1 messages, but QoS 0 is preferred for most of the messages. * Please restrict yourself to publish QoS 1 message for messages that are not repeated and has to be delivered only once. * The ETX system does not support QoS 2 messages. * Only clean sessions connections are accepted, so QoS 1 messages sent to the client after it disconnected will not be collected and will not be delivered upon reconnection. * Retained messages are only supported for the `RegionalStatic` namespace and the client is responsible for clearing the retained messages. * Once the MQTT connection is accepted a Session ID is assigned to the client, which can be used to send targeted messages to the client. The Session ID is a 64-bit number that is unique for each client. * **The Session ID is only valid for one MQTT session, so when the same client creates a new connection new Session ID will be assigned.** ## Security MQTT connections to the ETX system are secured with TLS 1.2. The client needs to provide a valid certificate and private key to connect to the system. The certificate and private key are provided by the ETX Registration service. The ETX system has an Access Control List (ACL) that defines which clients can publish and subscribe to which topics. The ACL is based on mostly the `VendorId`, but the `ClientType` and `ClientSubtype` parameters can also be considered. * The ACL rules are determined by the agreement between the Vendor and Verizon. * **If a client tries to publish to a topic that it is not authorized to do so, its connection will be terminated.** This is according to the MQTT V3.1.1 protocol. * If a client tries to subscribe to a topic that it is not authorized to do, the subscription request will be denied and the client will receive a `SUBACK` message with a return code of 128 (0x80). This is according to the MQTT V3.1.1 standard. It is important to implement proper error handling on the client side as that is the fastest way to learn about ACL related issues. * If you ran into ACL related issues and you think that it is not compliant with the agreement or you'd like to extend access to the system. Please contact customer support. ## Servers ### `Message Exchange` Server * URL: `mqtt://imp-{area}{zone}.{environment}-{region}.thingspace.verizon.com:8883/` * Protocol: `mqtt` Endpoint for the V2X message exchange in the Edge Transportation Exchange. V2X clients should connect to this endpoint to send or receive V2X messages. **Note:** Clients have to call the ETX Registration Service's `connection` API to receive the exact URL that they need to use for their connection. As the region and zone variables are determined by the client's geolocation. The call also triggers the authorization of the client's device ID and certificate to the location. Without proper authorization the client will not be able to connect to the message exchange. #### URL Variables | Name | Description | Default value | Allowed values | |---|---|---|---| | environment | The environment where the client needs to connect. It can be one of the following options: - development (dev) - quality assurance (qa) - staging - production (prod) | `prod` | `dev`, `qa`, `staging`, `prod` | | area | The area where the client needs to connect based on its geolocation. These are geographical areas within the U.S. (e.g 'bos' - Boston, MA) where the ETX processing nodes are deployed. | _None_ | `bos`, `atl`, `was`, `nyc`, `mia`, `dfw`, `iah`, `chi`, `clt`, `dtw`, `msp`, `tpa`, `bna`, `dal`, `sfo`, `las`, `den`, `sea`, `phx`, `lax` | | zone | Defines if the connection is to a Edge zone or to a Cloud zone. The Edge zones are signified as "-wl1". For Cloud zones this parameter remains empty. | _None_ | `-wl1`, | | region | The AWS region where the client needs to connect. It should be one of the following options: - US East (us-east-1) - US West (us-west-2) These regions are where the different ETX processing nodes are connected to. | _None_ | `us-east-1`, `us-west-2` | ## Operations ### SEND `vzimp/1/GeoRelevance/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *Publish location based messages to all the clients within a targeted geohash regions.* * Operation ID: `publishGeoRelevanceData` The GeoRelevance topic allows a road user to publish their own location based data (location, speed, status, etc.) and retrieve similar data from all clients in the neighboring geohashes. The GeoRelevance area is defined as a 3-by-3 grid of 7-digit geohashes around the client's geohash covering about a 450m by 450m (1500ft) area. The GeoRelevance channel should be the main communication channel for most road users in the ETX system. Only stationary clients (e.g. traffic lights, road sensors) should use the Regional channel. **All messages that are sent to this channel has to be in the GeoRoutedMsg protocol buffer format.** The message should contain the original message in raw binary format, the timestamp when the message was created, and the GPS position where the message should be routed to. **Publishing** to the `GeoRelevance` namespace is used by the road users (e.g. vehicles, mobile phone user, etc.) to share their current location, status or other information they detected with the rest of the ecosystem. For example: - a vehicle publishes a BSM message every 100ms to notify applications in the system about their current location and status, so they can provide alerts to the driver - a cyclist publishes a PSM message every second to notify applications about their current location and status, so they can provide alerts to the cyclist. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Geo Routed Message `geoRoutedMsg` *A message wrapped in GeoRoutedMsg protocol buffer package.* * Message ID: `geoRoutedMsg` * Content type: [protobuf](https://www.iana.org/assignments/media-types/protobuf) The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section. ```protobuf syntax = "proto3"; import "google/protobuf/timestamp.proto"; \ package georoutedmsg; option go_package = "./proto-gen/georoutedmsg;georoutedmsg"; message Position { \ double latitude = 1; \ double longitude = 2; \ } message GeoRoutedMsg { bytes msgBytes = 1; \ google.protobuf.Timestamp time = 2; \ optional Position position = 3; \ } ``` ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | time | string | The timestamp when the message was created. | - | format (`date-time`) | **required** | | msgBytes | string | The original J2735 ASN.1 type message in raw binary format. | - | format (`binary`) | **required** | | position | object | The GPS position where the message should be routed to. | - | - | **additional properties are NOT allowed** | | position.latitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -90 .. 90 ] | - | | position.longitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -180 .. 180 ] | - | > Examples of payload _(generated)_ ```json { "time": "2019-08-24T14:15:22Z", "msgBytes": "string", "position": { "latitude": -90, "longitude": -180 } } ``` ### RECEIVE `vzimp/1/GeoRelevance/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *Subscribe to receive location based messages from the system based on the geohash regions.* * Operation ID: `subscribeGeoRelevanceData` The GeoRelevance topic allows a road user to publish their own location based data (location, speed, status, etc.) and retrieve similar data from all clients in the neighboring geohashes. The GeoRelevance area is defined as a 3-by-3 grid of 7-digit geohashes around the client's geohash covering about a 450m by 450m (1500ft) area. The GeoRelevance channel should be the main communication channel for most road users in the ETX system. Only stationary clients (e.g. traffic lights, road sensors) should use the Regional channel. **All messages that are sent to this channel has to be in the GeoRoutedMsg protocol buffer format.** The message should contain the original message in raw binary format, the timestamp when the message was created, and the GPS position where the message should be routed to. **Subscribing** to the `GeoRelevance` namespace is used by road users (e.g. vehicles, mobile phone users, etc.) to receive location based messages from other road users and backend applications. For example: - a traffic light controller is subscribed to the GeoRelevance topic to receive SRM messages from the vehicles in the vicinity, so it can adjust the signal timing to avoid congestion. - a vehicle is subscribed to GeoRelevance topic to receive RSA or TIM messages about the dangers on the road ahead, so it can adjust its speed or route. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Geo Routed Message `geoRoutedMsg` *A message wrapped in GeoRoutedMsg protocol buffer package.* * Message ID: `geoRoutedMsg` * Content type: [protobuf](https://www.iana.org/assignments/media-types/protobuf) The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section. ```protobuf syntax = "proto3"; import "google/protobuf/timestamp.proto"; \ package georoutedmsg; option go_package = "./proto-gen/georoutedmsg;georoutedmsg"; message Position { \ double latitude = 1; \ double longitude = 2; \ } message GeoRoutedMsg { bytes msgBytes = 1; \ google.protobuf.Timestamp time = 2; \ optional Position position = 3; \ } ``` ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | time | string | The timestamp when the message was created. | - | format (`date-time`) | **required** | | msgBytes | string | The original J2735 ASN.1 type message in raw binary format. | - | format (`binary`) | **required** | | position | object | The GPS position where the message should be routed to. | - | - | **additional properties are NOT allowed** | | position.latitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -90 .. 90 ] | - | | position.longitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -180 .. 180 ] | - | > Examples of payload _(generated)_ ```json { "time": "2019-08-24T14:15:22Z", "msgBytes": "string", "position": { "latitude": -90, "longitude": -180 } } ``` ### SEND `vzimp/1/GeoRelevance/Small/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *Publish location based messages to all the clients within a targeted geohash regions.* * Operation ID: `publishGeoRelevanceSmallData` The GeoRelevance/Small topic is exactly the same as the GeoRelevance topic, but it provides a smaller coverage area by providing 3-by-3 grid of 8-digit geohashes around the client's geohash covering about a 115m by 57m (380ft by 187ft) area. Slow moving road user like pedestrians, cyclists, and scooters can use this channel to reduce the number of messages they receive. **Publishing** to the `GeoRelevance/Small` namespace is used by the road users (e.g. pedestrians, cyclists, scooter riders, etc.) to share their current location, status or other information they detected with the rest of the ecosystem. For example: - a pedestrian publishes a PSM message every second to notify applications in the system about their current location and status, so they can provide alerts to the pedestrian. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Geo Routed Message `geoRoutedMsg` *A message wrapped in GeoRoutedMsg protocol buffer package.* * Message ID: `geoRoutedMsg` * Content type: [protobuf](https://www.iana.org/assignments/media-types/protobuf) The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section. ```protobuf syntax = "proto3"; import "google/protobuf/timestamp.proto"; \ package georoutedmsg; option go_package = "./proto-gen/georoutedmsg;georoutedmsg"; message Position { \ double latitude = 1; \ double longitude = 2; \ } message GeoRoutedMsg { bytes msgBytes = 1; \ google.protobuf.Timestamp time = 2; \ optional Position position = 3; \ } ``` ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | time | string | The timestamp when the message was created. | - | format (`date-time`) | **required** | | msgBytes | string | The original J2735 ASN.1 type message in raw binary format. | - | format (`binary`) | **required** | | position | object | The GPS position where the message should be routed to. | - | - | **additional properties are NOT allowed** | | position.latitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -90 .. 90 ] | - | | position.longitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -180 .. 180 ] | - | > Examples of payload _(generated)_ ```json { "time": "2019-08-24T14:15:22Z", "msgBytes": "string", "position": { "latitude": -90, "longitude": -180 } } ``` ### RECEIVE `vzimp/1/GeoRelevance/Small/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *Subscribe to receive location based messages from the system based on the geohash regions.* * Operation ID: `subscribeGeoRelevanceSmallData` The GeoRelevance/Small topic is exactly the same as the GeoRelevance topic, but it provides a smaller coverage area by providing 3-by-3 grid of 8-digit geohashes around the client's geohash covering about a 115m by 57m (380ft by 187ft) area. Slow moving road user like pedestrians, cyclists, and scooters can use this channel to reduce the number of messages they receive. **Subscribing** to the `GeoRelevance/Small` namespace is used by road users (e.g. pedestrians, cyclists, scooter riders, etc.) to receive location based messages from other road users and backend applications. For example: - a pedestrian is subscribed to GeoRelevance/Small topic to receive RSA or TIM messages about the dangers on the road ahead, so it can adjust its speed or route. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Geo Routed Message `geoRoutedMsg` *A message wrapped in GeoRoutedMsg protocol buffer package.* * Message ID: `geoRoutedMsg` * Content type: [protobuf](https://www.iana.org/assignments/media-types/protobuf) The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section. ```protobuf syntax = "proto3"; import "google/protobuf/timestamp.proto"; \ package georoutedmsg; option go_package = "./proto-gen/georoutedmsg;georoutedmsg"; message Position { \ double latitude = 1; \ double longitude = 2; \ } message GeoRoutedMsg { bytes msgBytes = 1; \ google.protobuf.Timestamp time = 2; \ optional Position position = 3; \ } ``` ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | time | string | The timestamp when the message was created. | - | format (`date-time`) | **required** | | msgBytes | string | The original J2735 ASN.1 type message in raw binary format. | - | format (`binary`) | **required** | | position | object | The GPS position where the message should be routed to. | - | - | **additional properties are NOT allowed** | | position.latitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -90 .. 90 ] | - | | position.longitude | number | The latitude of the position used for geo routing | - | format (`double`), [ -180 .. 180 ] | - | > Examples of payload _(generated)_ ```json { "time": "2019-08-24T14:15:22Z", "msgBytes": "string", "position": { "latitude": -90, "longitude": -180 } } ``` ### SEND `vzimp/1/Private/{receiverSessionID}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *⚠️ [DEPRECATED] Send personalized messages to a specific client. Use publishDirectData instead.* * Operation ID: `publishPrivateData` ⚠️ **Deprecated.** Use the `Direct` topic instead. The `Private` namespace has been replaced by the `Direct` namespace, which provides identical functionality with a clearer name. New integrations should use the `Direct` topic. The `Private` namespace is a dedicated one way channel of communication between two registered ETX clients. It is used for sending targeted messages to specific clients that do not need to be broadcasted. It is mainly intended for downstream communication (e.g. from backend software to roadside clients). The messages that are sent to this channel are only delivered to the client that is specified in the topic parameter. ⚠️ **Deprecated.** Use the `publishDirectData` operation and the `Direct` topic instead. The `Direct` topic provides identical functionality and is the preferred channel for all new integrations. **Publishing** to the `Private` namespace is used by backend services to send personalized alerts to road users. For example: - a collision avoidance application is subscribed to a Regional topic when it discovers an accident is about to occur, so it sends an emergency message through the private channel to the vehicles involved. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | receiverSessionID | string | The session ID of the receiving party. The receiver's session ID can be acquired from a subscription topic. For example subscribe to "vzimp/1/GeoRelevance/+/+/+/j2735_gr/BSM/+" and the session ID will be the last part of the topic. If you want to send a message to your own client please use the ClientInfo topic subscription. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Channel extensions | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | x-deprecated | - | - | `"true"` | - | - | #### Operation extensions | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | x-deprecated | - | - | `"true"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### RECEIVE `vzimp/1/Private/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *⚠️ [DEPRECATED] Subscribe to receive personalized messages from a specific client. Use subscribeDirectData instead.* * Operation ID: `subscribePrivateData` ⚠️ **Deprecated.** Use the `Direct` topic instead. The `Private` namespace has been replaced by the `Direct` namespace, which provides identical functionality with a clearer name. New integrations should use the `Direct` topic. The `Private` namespace is a dedicated one way channel of communication between two registered ETX clients. It is used for sending targeted messages to specific clients that do not need to be broadcasted. It is mainly intended for downstream communication (e.g. from backend software to roadside clients). The messages that are sent to this channel are only delivered to the client that is specified in the topic parameter. ⚠️ **Deprecated.** Use the `subscribeDirectData` operation and the `Direct` topic instead. The `Direct` topic provides identical functionality and is the preferred channel for all new integrations. **Subscribing** to the `Private` namespace is used by the ETX clients to receive personalized messages from the backend services. For example: - a vehicle is subscribed to the private topic when it receives a message from the collision avoidance application that a collision might occur if you follow the current trajectory. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Channel extensions | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | x-deprecated | - | - | `"true"` | - | - | #### Operation extensions | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | x-deprecated | - | - | `"true"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### SEND `vzimp/1/Direct/{receiverSessionID}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *Send targeted messages directly to a specific client.* * Operation ID: `publishDirectData` The `Direct` namespace is the preferred channel for sending targeted messages to a specific ETX client. It replaces the deprecated `Private` namespace and provides the same functionality with a clearer name. The `Direct` namespace is a dedicated one way channel of communication between two registered ETX clients. It is used for sending targeted messages to specific clients that do not need to be broadcasted. It is mainly intended for downstream communication (e.g. from backend software to roadside clients). The messages that are sent to this channel are only delivered to the client that is specified in the topic parameter. **Publishing** to the `Direct` namespace is used by backend services to send targeted messages to a specific road user. This is the preferred channel for all new integrations, replacing the deprecated `Private` topic. The `Direct` topic works by addressing the receiver's session ID in the topic, ensuring the message is delivered only to that specific client. For example: - a collision avoidance application discovers an imminent accident and sends an emergency alert directly to the vehicles involved via their session IDs. - a backend application sends a route update or personalized instruction to a specific vehicle without broadcasting to all clients in a region. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | receiverSessionID | string | The session ID of the receiving party. The receiver's session ID can be acquired from a subscription topic. For example subscribe to "vzimp/1/GeoRelevance/+/+/+/j2735_gr/BSM/+" and the session ID will be the last part of the topic. If you want to send a message to your own client please use the ClientInfo topic subscription. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### RECEIVE `vzimp/1/Direct/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *Subscribe to receive targeted messages sent directly to this client.* * Operation ID: `subscribeDirectData` The `Direct` namespace is the preferred channel for receiving targeted messages sent to this client. It replaces the deprecated `Private` namespace and provides the same functionality with a clearer name. The `Direct` namespace is a dedicated one way channel of communication between two registered ETX clients. It is used for sending targeted messages to specific clients that do not need to be broadcasted. It is mainly intended for downstream communication (e.g. from backend software to roadside clients). The messages that are sent to this channel are only delivered to the client that is specified in the topic parameter. **Subscribing** to the `Direct` namespace is used by ETX clients to receive targeted messages sent specifically to them by backend services. This is the preferred channel for all new integrations, replacing the deprecated `Private` topic. A client's session ID is included in the publish topic by the sender to address a message to that specific client. For example: - a vehicle subscribes to the `Direct` topic to receive emergency alerts from a collision avoidance application when a collision risk is detected. - a roadside unit subscribes to the `Direct` topic to receive configuration updates or instructions from a backend management service. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### RECEIVE `vzimp/1/ClientInfo` Operation *Subscribe to receive the session ID of the client.* * Operation ID: `subscribeClientInfo` The `ClientInfo` namespace is a dedicated one way channel for clients to receive their session ID after their connection has been established. The session ID is a 64-bit number that is unique for each client and each MQTT session, so it is different every time a client creates a connection. **Note:** The session ID can help to debug any connection or message related issues. So it is recommended to implement the session ID retrieval in the your client code. **Subscribing** to the `ClientInfo` namespace is used by the clients to receive their session ID. Upon subscription the client will receive a JSON message containing the session ID. The message is not repeated, so after it was received the subscription can be closed. #### Message Client Info Message `ClientInfoMessage` *The message that contains the session ID of the client.* * Message ID: `ClientInfoMessage` * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) This message contains a JSON object with a single key-value pair containing the session ID of the client. ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | sessionID | integer | - | - | format (`int64`) | **required** | > Examples of payload _(generated)_ ```json { "sessionID": 0 } ``` ### SEND `vzimp/1/Regional/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *Publish real time location based messages to all the clients within a targeted geohash regions.* * Operation ID: `publishRegionalData` The `Regional` namespace is a communal topic where all the location based, real-time messages from clients get shared in the ecosystem. The messages here are partitioned into a rectangular grid based on [Geohashes](https://en.wikipedia.org/wiki/Geohash). The `Regional` namespace allows clients to send any type of messages to any Geohash, which can be specified in the topic parameter. These messages will be routed to all of the subscribers in that region. **Publishing** to the `Regional` namespace is commonly used for infrastructure services to send messages that need to be broadcasted to a region. For example: - a traffic light service might want to send a SPAT message to all the cars within a Geohash region that surrounds an intersection; - a local road authority might want to send RSA messages to all the cars to notify them of an evolving roadside situation (e.g. congestion, accidents). **Note:** The message sent through the `Regional` namespace should be in QoS 0 or QoS 1 and should not be retained. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### RECEIVE `vzimp/1/Regional/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *Subscribe to receive real time data from the system based on the geohash regions.* * Operation ID: `subscribeRegionalData` The `Regional` namespace is a communal topic where all the location based, real-time messages from clients get shared in the ecosystem. The messages here are partitioned into a rectangular grid based on [Geohashes](https://en.wikipedia.org/wiki/Geohash). The `Regional` namespace allows clients to send any type of messages to any Geohash, which can be specified in the topic parameter. These messages will be routed to all of the subscribers in that region. **Subscribing** to the `Regional` namespace is commonly used for backend services to perform real-time analysis of all the messages within a region. For example: - a collision avoidance application might want to analyze all the messages coming into an intersection to calculate the likelihood of an accident occurring in real-time. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### SEND `vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VehicleDensity` Operation *Write real time vehicle density messages to all the clients within a targeted geohash regions.* * Operation ID: `publishVehicleDensityData` This is a subtopic within the Regional namespace where the vehicle density messages are published. The vehicle density messages are in JSON format containing the number of vehicles (the number of BSM providers) in the given geohash. The vehicle density messages are generated for 6, 7, and 8-digit geohashes, where vehicles are present in the ETX system (BSM messages are published within the geohash). If there are no vehicle in a given geohash, **0 count message will not be sent out**. The `VehicleDensity` topic is used by the Density application to publish the vehicle density messages. These messages contain the number of vehicles (the number of BSM providers) in a given geohash. **Writing to the topic is only allowed for the Density application.** #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Vehicle Density Message `vehicleDensityMessage` *The vehicle density message. It contains the number of BSM providers (vehicles) within a geohash.* * Message ID: `vehicleDensityMessage` * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | GeoHash | string | - | - | pattern (`^\w{6,8}$`) | **required** | | VehicleCount | integer | - | - | format (`int32`), [ 1 .. 100000 ] | **required** | > Examples of payload _(generated)_ ```json { "GeoHash": "string", "VehicleCount": 1 } ``` ### RECEIVE `vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VehicleDensity/{sessionID}` Operation *Receive real time vehicle density data from clients based on subscribed geohash regions.* * Operation ID: `subscribeVehicleDensityData` This is a subtopic within the Regional namespace where the vehicle density messages are published. The vehicle density messages are in JSON format containing the number of vehicles (the number of BSM providers) in the given geohash. The vehicle density messages are generated for 6, 7, and 8-digit geohashes, where vehicles are present in the ETX system (BSM messages are published within the geohash). If there are no vehicle in a given geohash, **0 count message will not be sent out**. **Subscribing** to the `VehicleDensity` topic is used by the ETX clients to receive the vehicle density messages. These messages contain the number of vehicles (the number of BSM providers) in the given geohash. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message Vehicle Density Message `vehicleDensityMessage` *The vehicle density message. It contains the number of BSM providers (vehicles) within a geohash.* * Message ID: `vehicleDensityMessage` * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | GeoHash | string | - | - | pattern (`^\w{6,8}$`) | **required** | | VehicleCount | integer | - | - | format (`int32`), [ 1 .. 100000 ] | **required** | > Examples of payload _(generated)_ ```json { "GeoHash": "string", "VehicleCount": 1 } ``` ### SEND `vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VruDensity` Operation *Write real time VRU density messages to all the clients within a targeted geohash regions.* * Operation ID: `publishVRUDensityData` This is a subtopic within the Regional topic group where the vulnerable road user (VRU) density messages are published. The VRU density messages are JSON messages containing the number of VRUs (the number of PSM providers) in the given geohash. The VRU density messages are generated for 6, 7, and 8-digit geohashes, where vehicles are present in the ETX system (PSM messages are published within the geohash). If there are no VRUs in a given geohash, **0 count message will not be sent out**. The `VRUDensity` topic is used by the Density application to publish the VRU density messages. These messages contain the number of VRUs (the number of PSM providers) in a given geohash. **Writing to the topic is only allowed for the Density application.** #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message VRU Density Message `vruDensityMessage` *The vulnerable road user (VRU) density message. It contains the number of PSM providers (VRU) within a geohash.* * Message ID: `vruDensityMessage` * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | GeoHash | string | - | - | pattern (`^\w{6,8}$`) | **required** | | VruCount | integer | - | - | format (`int32`), [ 1 .. 100000 ] | **required** | > Examples of payload _(generated)_ ```json { "GeoHash": "string", "VruCount": 1 } ``` ### RECEIVE `vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VruDensity/{sessionID}` Operation *Receive real time VRU density data from clients based on subscribed geohash regions.* * Operation ID: `subscribeVRUDensityData` This is a subtopic within the Regional topic group where the vulnerable road user (VRU) density messages are published. The VRU density messages are JSON messages containing the number of VRUs (the number of PSM providers) in the given geohash. The VRU density messages are generated for 6, 7, and 8-digit geohashes, where vehicles are present in the ETX system (PSM messages are published within the geohash). If there are no VRUs in a given geohash, **0 count message will not be sent out**. **Subscribing** to the `VRUDensity` topic is used by the ETX clients to receive the VRU density messages. These messages contain the number of VRUs (the number of PSM providers) in the given geohash. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | sessionID | string | The session ID associated with the sender of the message. **Note:** Please use '+' for this parameter. Since the session ID can change frequently it is not recommended to use a specific session ID in a subscription topic. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"0"` | - | - | | retain | - | - | `"false"` | - | - | #### Message VRU Density Message `vruDensityMessage` *The vulnerable road user (VRU) density message. It contains the number of PSM providers (VRU) within a geohash.* * Message ID: `vruDensityMessage` * Content type: [application/json](https://www.iana.org/assignments/media-types/application/json) ##### Payload | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | (root) | object | - | - | - | **additional properties are NOT allowed** | | GeoHash | string | - | - | pattern (`^\w{6,8}$`) | **required** | | VruCount | integer | - | - | format (`int32`), [ 1 .. 100000 ] | **required** | > Examples of payload _(generated)_ ```json { "GeoHash": "string", "VruCount": 1 } ``` ### SEND `vzimp/1/RegionalStatic/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}` Operation *Publish persistent messages to all the clients within a targeted geohash regions.* * Operation ID: `publishRegionalStaticData` The `RegionalStatic` namespace is a communal topic used to share persistent messages in the ecosystem. Persistence here refers to the MQTT retain feature where messages will be stored on a topic permanently, so that subscribers to the topic can retrieve the message at any point of time. The `RegionalStatic` namespace allows clients to publish any type of messages to any Geohash, which can be specified in the topic parameter. These messages will be routed to all the subscribers in that region. **Publishing** to the `RegionalStatic` namespace is commonly used for backend services to broadcast messages that are relevant for a longer period of time. For example: - a map vendor service might want to send lane level MAP messages to all the cars to notify them how to maneuver; - a local road authority might want to send RSA messages to alert them of a scheduled road maintenance. **The publisher must also track of the retain messages it has published as the message is kept in the system forever if no further action is taken. A publisher to the `RegionalStatic` namespace can remove the message from the topic by sending an empty message to the topic where the message resides.** **Note:** When publishing to the `RegionalStatic` namespace, the session ID segment of the topic is automatically set to `0` by the ETX system, regardless of the sender's actual session ID. This ensures retained messages are not duplicated when the publisher reconnects with a new session ID and stops clients from trying to reach publishers that are no longer connected to the system. Retained messages allow publishers to disconnect because the system persists their messages. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type. ### RECEIVE `vzimp/1/RegionalStatic/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID}` Operation *Subscribe to receive persistent data from the system based on the geohash regions.* * Operation ID: `subscribeRegionalStaticData` The `RegionalStatic` namespace is a communal topic used to share persistent messages in the ecosystem. Persistence here refers to the MQTT retain feature where messages will be stored on a topic permanently, so that subscribers to the topic can retrieve the message at any point of time. The `RegionalStatic` namespace allows clients to publish any type of messages to any Geohash, which can be specified in the topic parameter. These messages will be routed to all the subscribers in that region. **Note:** For `RegionalStatic` topics, the session ID in the topic is fixed to `0` instead of the sender's actual session ID. This prevents duplicate retained entries from being created when the sender's session ID changes between connections and stops clients from trying to reach publishers that are no longer connected to the system. Retained messages allow the publishers to disconnect because the system persists their messages. **Subscribing** to the `RegionalStatic` namespace is commonly used for backend services to receive messages that are relevant for a longer period of time. For example: - a map vendor service might want to receive lane level MAP messages to all the cars to notify them how to maneuver; - a local road authority might want to receive RSA messages to alert them of a scheduled road maintenance. #### Parameters | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | geohash | string | The [Geohashes](https://en.wikipedia.org/wiki/Geohash) that the message is associated with. This is a slash delimited topic string with 8 geohash characters (e.g. 1/2/3/4/5/6/7/8). **Wildcard subscriptions** are supported on the 7- and 8-digit geohash level, so a client can subscribe to all 32 8-digit geohashes within a 7-digit geohash by using the standard MQTT '+' wildcard: 1/2/3/4/5/6/7/+. This can also be done for the 6-digit geohash and subscribe to all 1024 geohashes: 1/2/3/4/5/6/+/+. These type of subscriptions also include the wide area messages (see the definition below). **Note** that wildcard publishing is not supported. **Wide area publishing or subscription** are supported on the 6- and 7-digit geohash level. This function allows the client to send or receive messages at a specific geohash level. For this the client needs to use the dash '-' character in the geohash. For example, messages published with 1/2/3/4/5/6/7/- geohash will only be available with subscriptions to 1/2/3/4/5/6/7/+ or 1/2/3/4/5/6/7/-. The same can be done for 6-digit geohash messages: 1/2/3/4/5/6/-/-. **Note** the wide area publishing and subscription is hierarchical. If a dash '-' is included in the geohash description all further geohash levels are need to be dash as well. So, publishing or subscribing to **1/2/3/4/5/6/-/8** it not supported. | - | - | **required** | | clientType | string | The type of the client that is to be registered. This is one of the major traffic participant groups considered in V2X communication. The system uses this value to define which topics the client will be able to publish and subscribe to. Values: - **Vehicle** - Vehicle with an enclosure around the passengers. (Subtypes: PassengerCar, Truck, Bus, EmergencyVehicle, SchoolBus, MaintenanceVehicle) - **VulnerableRoadUser** - Traffic participants without a protecting enclosure. (Subtypes: Motorcycle, Bicycle, Pedestrian, Scooter) - **TrafficLightController** - A Traffic light controller system. (Subtypes: NA) - **InfrastructureSensor** - Sensors that are deployed in the infrastructure. (Subtypes: RoadSideUnit, Camera, Lidar, Radar, InductiveLoop, MagneticSensor) - **OnboardSensor** - Sensors that are onboard on a vehicle(Subtypes: Camera, Lidar, Radar) - **Software** - A software system or application. (Subtypes: Platform, Application, NA) | allowed (`"Vehicle"`, `"VulnerableRoadUser"`, `"TrafficLightController"`, `"InfrastructureSensor"`, `"OnboardSensor"`, `"Software"`) | - | **required** | | clientSubtype | string | The subtype or subgroup of the client type. This further specifies the client type. For example it will specify if the client is a passenger car or a truck. See the ClientType description for the supported Subtypes for each client type. | allowed (`"PassengerCar"`, `"Truck"`, `"Bus"`, `"EmergencyVehicle"`, `"SchoolBus"`, `"MaintenanceVehicle"`, `"Pedestrian"`, `"Bicycle"`, `"Scooter"`, `"Motorcycle"`, `"RoadSideUnit"`, `"Camera"`, `"Lidar"`, `"Radar"`, `"InductiveLoop"`, `"MagneticSensor"`, `"Platform"`, `"Application"`, `"NA"`) | - | **required** | | vendorId | string | The vendor ID that the client belongs to or "Public". E.g. Verizon, GM, Ford, etc. The "Public" vendor ID should be used for messages that are meant to be available for all clients in the system. This is used for messages that are not specific to a vendor and typically carry safety information such as BSM, PSM, RSA, or TIM messages. PLease note that this is the typical usage, but there is no restriction on what message types can be published under the "Public" vendor, so other messages like SPAT and MAP messages can also be delivered under the "Public" vendor ID. **All clients that are part of the ETX ecosystem can Publish and Subscribe to the "Public" vendor ID messages.** | - | - | **required** | | messageFormat | string | The encoding of the message (e.g. j2735, protobuf, json, Avro, etc.). If the message is encapsulated within a GeoRoutedMsg protocol buffer wrapper, append _gr to the message format (e.g. j2735 => j2735_gr). **Note:** ETX prefers the j2735_gr encoding and only vendor specific message types are allowed to be published in different message formats. | - | - | **required** | | messageType | string | The type of message. This can be any of the standard V2X messages specified in the SAE J2735 standard (e.g. BSM, PSM, RSA, TIM, MAP, SPAT, etc.), or it can be a vendor specific message type that is not defined by the standard. | - | - | **required** | | sessionID | string | For `RegionalStatic` topics, the session ID is fixed to `0` instead of the sender's actual session ID. This prevents duplicate retained entries from being created when the sender's session ID changes between connections and stops clients from trying to reach publishers that are no longer connected to the system. Retained messages allow publishers to disconnect because the system persists their messages. **Note:** Please use '+' or '0' for this parameter when subscribing to `RegionalStatic` topics. | - | - | **required** | #### `mqtt` Operation specific information | Name | Type | Description | Value | Constraints | Notes | |---|---|---|---|---|---| | qos | - | - | `"1"` | - | - | | retain | - | - | `"true"` | - | - | #### Message V2X Message `V2xMessage` *The V2X message that is transferred through the ETX system. It is encoded in the format specified in the {messageFormat} topic parameter.* Most V2X standards uses ASN.1 encoding, but the ETX system can support any other encoding type that the sender and receiver are agreed upon. The message can be a standard V2X message for example: - BSM, PSM, RSA, SPAT, etc. from the SAE standard - CAM, DENM from the ETSI standard These should be in ASN.1 formatted required by the standard. However, the message can also be a vendor specific message type.