MQTT API

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 exchangeCopy Anchor Link

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 detailsCopy Anchor Link

• 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.

SecurityCopy Anchor Link

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.

ServersCopy Anchor Link

Message Exchange ServerCopy Anchor Link

• 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 VariablesCopy Anchor Link

• 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 |

OperationsCopy Anchor Link

SEND vzimp/1/GeoRelevance/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Geo Routed Message geoRoutedMsgCopy Anchor Link

A message wrapped in GeoRoutedMsg protocol buffer package.

• Message ID: geoRoutedMsg
• Content type: protobuf

The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section.

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; \
}

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "time": "2019-08-24T14:15:22Z",
  "msgBytes": "string",
  "position": {
    "latitude": -90,
    "longitude": -180
  }
}

RECEIVE vzimp/1/GeoRelevance/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Geo Routed Message geoRoutedMsgCopy Anchor Link

A message wrapped in GeoRoutedMsg protocol buffer package.

• Message ID: geoRoutedMsg
• Content type: protobuf

The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section.

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; \
}

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "time": "2019-08-24T14:15:22Z",
  "msgBytes": "string",
  "position": {
    "latitude": -90,
    "longitude": -180
  }
}

SEND vzimp/1/GeoRelevance/Small/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Geo Routed Message geoRoutedMsgCopy Anchor Link

A message wrapped in GeoRoutedMsg protocol buffer package.

• Message ID: geoRoutedMsg
• Content type: protobuf

The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section.

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; \
}

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "time": "2019-08-24T14:15:22Z",
  "msgBytes": "string",
  "position": {
    "latitude": -90,
    "longitude": -180
  }
}

RECEIVE vzimp/1/GeoRelevance/Small/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType}/{sessionID} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Geo Routed Message geoRoutedMsgCopy Anchor Link

A message wrapped in GeoRoutedMsg protocol buffer package.

• Message ID: geoRoutedMsg
• Content type: protobuf

The Geo Routed Messages should be packaged in the following protocol buffer schema. The descriptions of the fields are in the payload section.

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; \
}

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "time": "2019-08-24T14:15:22Z",
  "msgBytes": "string",
  "position": {
    "latitude": -90,
    "longitude": -180
  }
}

SEND vzimp/1/Private/{receiverSessionID}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType} OperationCopy Anchor Link

⚠️ [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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Channel extensionsCopy Anchor Link

Operation extensionsCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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} OperationCopy Anchor Link

⚠️ [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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Channel extensionsCopy Anchor Link

Operation extensionsCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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 OperationCopy Anchor Link

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 ClientInfoMessageCopy Anchor Link

The message that contains the session ID of the client.

• Message ID: ClientInfoMessage
• Content type: application/json

This message contains a JSON object with a single key-value pair containing the session ID of the client.

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "sessionID": 0
}

SEND vzimp/1/Regional/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType} OperationCopy Anchor Link

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.

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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} OperationCopy Anchor Link

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.

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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 OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Vehicle Density Message vehicleDensityMessageCopy Anchor Link

The vehicle density message. It contains the number of BSM providers (vehicles) within a geohash.

• Message ID: vehicleDensityMessage
• Content type: application/json

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "GeoHash": "string",
  "VehicleCount": 1
}

RECEIVE vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VehicleDensity/{sessionID} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message Vehicle Density Message vehicleDensityMessageCopy Anchor Link

The vehicle density message. It contains the number of BSM providers (vehicles) within a geohash.

• Message ID: vehicleDensityMessage
• Content type: application/json

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "GeoHash": "string",
  "VehicleCount": 1
}

SEND vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VruDensity OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message VRU Density Message vruDensityMessageCopy Anchor Link

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

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "GeoHash": "string",
  "VruCount": 1
}

RECEIVE vzimp/1/Regional/{geohash}/Software/Application/Public/JSON/VruDensity/{sessionID} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message VRU Density Message vruDensityMessageCopy Anchor Link

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

PayloadCopy Anchor Link

Examples of payload (generated)

{
  "GeoHash": "string",
  "VruCount": 1
}

SEND vzimp/1/RegionalStatic/{geohash}/{clientType}/{clientSubtype}/{vendorId}/{messageFormat}/{messageType} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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} OperationCopy Anchor Link

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.

ParametersCopy Anchor Link

mqtt Operation specific informationCopy Anchor Link

Message V2X Message V2xMessageCopy Anchor Link

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.