docs: Add BLE and UART protocol specification
This commit is contained in:
Jannik Beyerstedt
parent
58e5d5ec75
commit
29a5d86e43
4 changed files with 196 additions and 1 deletions
|
|
@ -1,4 +1,4 @@
|
|||
# ESP32-C5 C-ITS Visualizer
|
||||
# ESP32-C5 C-ITS Companion/ Visualizer
|
||||
|
||||
Displays different C-ITS receive-only use cases for cheap.
|
||||
|
||||
|
|
|
|||
53
docs/ble-protocol.md
Normal file
53
docs/ble-protocol.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# Bluetooth LE Protocol
|
||||
|
||||
Some data is made available via BLE so that a smartphone app can be used to display it in other use cases.
|
||||
|
||||
## General
|
||||
|
||||
The BLE protocol contains some standardized services, but can also transport custom services.
|
||||
Each service is compromised of a set of characteristics which can be read or clients can even subscribe for changes.
|
||||
|
||||
Sadly we can't use any of the standardized service/ profiles to transmit V2X data.
|
||||
Even notifications about DENMs can't be transmitted since the Alert Notification Profile is only meant for the companion device to query notifications from the phone, but not the other way around.
|
||||
|
||||
So we will only use the Device Information Service to announce ourselves and use a custom service for everything else.
|
||||
|
||||
## V2X BLE Service
|
||||
|
||||
V2X data is exposed via the service UUID `c0b70000-d4f4-4000-ada8-f99a02ee315c` (randomly generated UUID, with byte 3 and 4 set to zero) using the following characteristics:
|
||||
|
||||
UUID | Type | Description
|
||||
------------------------------------- | --------------- | -----------
|
||||
c0b70001-d4f4-4001-ada8-f99a02ee315c | `PositionState` | Set position from external source
|
||||
c0b70001-d4f4-4001-ada8-f99a02ee315c | `RawMsgRx` | Raw CAM message (de-duplicated/ rate-limited)
|
||||
c0b70001-d4f4-4002-ada8-f99a02ee315c | `CamEvent` | Latest received CAM
|
||||
c0b70001-d4f4-4003-ada8-f99a02ee315c | `RawMsgRx` | Raw DENM message (de-duplicated/ rate-limited)
|
||||
c0b70001-d4f4-4004-ada8-f99a02ee315c | `DenmEvent` | Latest received DENM
|
||||
c0b70001-d4f4-4005-ada8-f99a02ee315c | `RawMsgRx` | Raw MAPEM message (de-duplicated/ rate-limited)
|
||||
c0b70001-d4f4-4006-ada8-f99a02ee315c | `RawMsgRx` | Raw SPATEM message (de-duplicated/ rate-limited)
|
||||
|
||||
## Message Format
|
||||
|
||||
Messages are encoded according to the [Protocol Buffers](https://protobuf.dev/) specification since it provides decent binary size and has parser libraries for many programming languages.
|
||||
All data types are defined in one `.proto` file: [c_its-messages.proto](./c_its-messages.proto).
|
||||
|
||||
### Position State Input
|
||||
|
||||
When there's no GNSS receiver connected to the ESP, position, heading and speed information can be set using a `PositionState` message (see [c_its-messages.proto](./c_its-messages.proto)).
|
||||
|
||||
### DENM Event
|
||||
|
||||
Each received DENM will be "published" as a `DenmEvent` message (see [c_its-messages.proto](./c_its-messages.proto)).
|
||||
Repetitions of the same message (e.g. no changes to the validity timeframe and location) may be dropped by the BLE server.
|
||||
|
||||
### CAM Event
|
||||
|
||||
Each received (low-frequency) CAM will be "published" as a `CamEvent` message (see [c_its-messages.proto](./c_its-messages.proto)).
|
||||
|
||||
### Raw Received Message
|
||||
|
||||
Received V2X messages will be "published" as a `RawMsgRx` message (see [c_its-messages.proto](./c_its-messages.proto)).
|
||||
Repetitions of the same message should be dropped by the BLE server.
|
||||
Consecutive messages with no relevant changes may be dropped by the BLE server while keeping some minimal publishing rate, e.g.:
|
||||
- only publish MAPEMs every 10 seconds (since content doesn't change, but client may be restarted after first MAPEM from an intersection was received)
|
||||
- drop high-frequency CAMs (only publish "full" CAMs which include the low-frequency container)
|
||||
122
docs/c_its-messages.proto
Normal file
122
docs/c_its-messages.proto
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
syntax = "proto2";
|
||||
|
||||
package c_its_io;
|
||||
|
||||
// ------------------------------
|
||||
// Data Types
|
||||
// ------------------------------
|
||||
|
||||
message Position {
|
||||
required float latitude_deg = 1;
|
||||
required float longitude_deg = 2;
|
||||
}
|
||||
|
||||
enum TrafficDir {
|
||||
// for all directions of traffic
|
||||
ALL_DIRECTIONS = 0;
|
||||
// for the direction of traffic according to the reference direction, and the portion of traffic upstream of the reference position
|
||||
UPSTREAM = 1;
|
||||
// for the direction of traffic according to the reference direction, and the portion of traffic downstream of the reference position
|
||||
DOWNSTREAM = 2;
|
||||
// for the direction of traffic opposite to the reference direction
|
||||
OPPOSITE = 3;
|
||||
}
|
||||
|
||||
message VehicleContainer {
|
||||
optional uint32 heading_deg = 1; // vehicle heading in degrees, if not "unavailable"
|
||||
optional uint32 speed = 2; // vehicle speed in 1/100 m/s, if not "unavailable"
|
||||
optional uint32 vehicle_length_dm = 3; // vehicle length in 1/10 m, if not "unavailable"
|
||||
optional uint32 vehicle_width_dm = 4; // vehicle width in 1/10 m, if not "unavailable"
|
||||
}
|
||||
|
||||
|
||||
// GeoNetworking Destination Area Shape
|
||||
enum GNAreaShape {
|
||||
ETSI_AREASHAPE_CIRCLE = 0;
|
||||
ETSI_AREASHAPE_RECTANGLE = 1;
|
||||
ETSI_AREASHAPE_ELLIPSIS = 2;
|
||||
ETSI_AREASHAPE_UNKNOWN = 15;
|
||||
}
|
||||
|
||||
// GeoNetworking Destination Area/ Source Position
|
||||
message ITSPosition {
|
||||
optional int32 latitude = 1; // Latitude in 1/10th of micro degrees
|
||||
optional int32 longitude = 2; // Longitude in 1/10th of micro degrees
|
||||
}
|
||||
|
||||
// GeoNetworking Destination Area
|
||||
message GNArea {
|
||||
optional GNAreaShape area = 1 [default = ETSI_AREASHAPE_UNKNOWN];
|
||||
optional ITSPosition position = 2;
|
||||
optional int32 distA = 3; // Distance A of the geometric shape in meters
|
||||
optional int32 distB = 4; // Distance B of the geometric shape in meters, mandatory for rectangle and ellipsis
|
||||
optional int32 angle = 5; // Angle of the geometric shape in degrees, mandatory for rectangle and ellipsis
|
||||
}
|
||||
|
||||
// GeoNetworking Transport
|
||||
enum GNTransport {
|
||||
GN_TRANSPORT_DEFAULT = 0;
|
||||
GN_TRANSPORT_GUC = 2; // GeoUnicast
|
||||
GN_TRANSPORT_GAC = 3; // Geographically-Scoped Anycast
|
||||
GN_TRANSPORT_GBC = 4; // Geographically-Scoped broadcast
|
||||
GN_TRANSPORT_TSB = 5; // Topologically-scoped broadcast
|
||||
GN_TRANSPORT_SHB = 7; // Single hop broadcast
|
||||
}
|
||||
|
||||
message RawMsgTx {
|
||||
required bytes payload = 1; // as UPER
|
||||
required uint32 message_type = 2; // ITS `MessageId` integer value
|
||||
|
||||
required GNTransport gnTransport = 3;
|
||||
required GNArea gnArea = 4;
|
||||
required uint32 hopLimit = 5;
|
||||
}
|
||||
|
||||
// ------------------------------
|
||||
// Messages
|
||||
// ------------------------------
|
||||
|
||||
message PositionState {
|
||||
required Position position = 1;
|
||||
optional uint32 heading_deg = 2;
|
||||
optional uint32 speed = 3; // speed in 1/100 m/s
|
||||
}
|
||||
|
||||
message DenmEvent {
|
||||
required fixed64 timestamp = 1; // DENM reference time as UNIX time
|
||||
required fixed64 validity_end_ts = 2; // UNIX time when event validity ends (from denm.management.validityDuration)
|
||||
required fixed32 station_id = 3; // unique ID of the event when combined with `seq_num`
|
||||
required uint32 seq_num = 4; // unique ID of the event when combined with `station_id`
|
||||
optional Position event_position = 5; // event location (from denm.management.eventPosition)
|
||||
optional uint32 event_heading_deg = 6; // event heading (from denm.location.eventPositionHeading)
|
||||
optional TrafficDir direction = 7; // relevance traffic direction (from denm.management.trafficDirection)
|
||||
optional uint32 cause_code = 8;
|
||||
optional uint32 sub_cause_code = 9;
|
||||
}
|
||||
|
||||
message CamEvent {
|
||||
required fixed32 station_id = 1; // Station ID of the vehicle
|
||||
required uint32 station_type = 2; // ITS `StationType`
|
||||
required Position position = 3; // vehicle position
|
||||
optional uint32 vehicle_role = 4; // ITS `VehicleRole`
|
||||
optional VehicleContainer vehicle_data = 5; // speed, etc unless CAM contains an RSU container
|
||||
}
|
||||
|
||||
message RawMsgRx {
|
||||
required uint32 msg_type = 1; // ITS message type (`MessageId` from PDU header)
|
||||
required bytes payload = 2; // UPER message with Geonetworking and BTP headers
|
||||
}
|
||||
|
||||
message SerialOutputMsg {
|
||||
oneof payload {
|
||||
DenmEvent denm = 1;
|
||||
RawMsgRx rx_msg = 2;
|
||||
}
|
||||
}
|
||||
|
||||
message SerialInputMsg {
|
||||
oneof payload {
|
||||
PositionState position = 1;
|
||||
RawMsgTx tx_msg = 2;
|
||||
}
|
||||
}
|
||||
20
docs/uart-protocol.md
Normal file
20
docs/uart-protocol.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# UART Protocol
|
||||
|
||||
If enabled using the `TODO` feature flag, all received messages are transmitted on UART using the protocol described in this document.
|
||||
The serial communication can also be used to send V2X data.
|
||||
|
||||
## Message Format
|
||||
|
||||
The UART communication is using a custom framing protocol to encapsulate binary messages.
|
||||
The payload is:
|
||||
|
||||
- a `SerialOutputMsg` for transmissions from the ESP to the host or
|
||||
- a `SerialInputMsg` for transmissions from the host to the ESP
|
||||
|
||||
in binary [Proto](https://protobuf.dev/) serialization according to the [c_its-messages.proto](./c_its-messages.proto) definition.
|
||||
|
||||
Each transmission:
|
||||
- starts with a Start of Frame (SOF) sequence: `0x56, 0x32, 0x58, 0x2B` ("V2X+")
|
||||
- followed by a 16-bit big-endian length field
|
||||
- followed by the payload
|
||||
- followed by an End of Frame (EOF) sequence `0x0d, 0x0a`
|
||||
Loading…
Add table
Add a link
Reference in a new issue