Ubiqua Sniffer API
Describes the communication protocol between sniffer adapters and the host running Ubiqua Protocol Analyzer. The API defined in this document applies to Ubiqua versions 2.4 and above.
Interfaces
The Ubiqua Sniffer API specification makes possible the usage of different interfaces.
UART Interface
UART interface configuration
| Attribute | Value |
|---|---|
| Baud rate | 230400 |
| Data bits | 8 |
| Parity | none |
| Stop bits | 1 |
| Flow control | none |
Frame structure
The structure of the frame is presented below, fields with multiple octets and a defined data type (uint16, uint32, etc.), the byte-ordering to use MUST be little-endian.
| Octets | Description |
|---|---|
| 2 | Start of Frame. MUST contain 0x02 0x50 |
| 1 | The command ID |
| 2 | The payload length in octets |
| n | The payload data (0 - 65535) |
| 1 | The checksum, the result of the XOR operation applied to the serial frame excluding the first octet (0x02), ( 0x50 XOR command_id XOR paylen XOR payload) |
There are three message types: Requests, Responses and Indications.
- Requests are messages coming from the host requesting action in the adapter. Requests can also be used to configure the adapter according to the settings supported by the adapter.
- Requests can be sent by the host at any time and with no specific order (stateless behavior). The same request can be sent multiple times, the action should be executed successfully returning the respective status.
- Responses are messages from the adapter to the host providing feedback to previous requests executed by the host. Responses are expected by the host within 20ms. Each Request has its own Response message.
- Response messages payload will be structured as follows: 1 byte Status, n bytes (0 - 65534) context data.
- Indications are asynchronous messages sent by the adapter to inform the host about events that happened on the adapter.
The two most significant bits of a command ID describe the type of the command, as shown in Table 2 below:
| Bit 7 | Bit 6 | Message type |
|---|---|---|
| LOW | LOW | Request |
| HIGH | LOW | Response |
| LOW | HIGH | Indication |
All responses have a status field to indicate if the request has been processed successfully or the reason for the failure, the following is a list of values to use:
| Status | Value |
|---|---|
| Success | 0x00 |
| Failed | 0x01 |
| Unsupported command | 0x02 |
| Invalid index | 0x03 |
The Failed status is how the adapter implementation indicates a failure condition that is not described by any of the other possible status listed in Table 3, that is the case of internal issues in the adapter implementation due to memory errors, hardware failures, etc. This Failed status when returned by the adapter will make it unavailable to the host until it is restarted (unplugged and plugged in again).
The Unsupported command status is used when the adapter receives an unknown or Unsupported command, for which it must respond using the same command ID but with the response prefix bits, a payload length of 1 and status 0x02 Unsupported command.
Values not defined in Table 3 are reserved and must not be used.
Mandatory Adapter Commands
Ping Request
This command is used by the host to verify that the communication with the adapter has been established correctly, it may also be used at any time by the host to ensure the adapter is still connected and responsive.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Ping Request [0x01] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0000] |
Pong Response
Sends a response back to the host to acknowledge that the communication with the adapter is still working correctly.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Pong Response [0x81] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0001] |
| Status | 1 | uint8 | Status of the response. If the adapter is operational [Success = 0x00], if the adapter has run into internal problems (such as run out of memory) that prevent it from functioning as this specification requires [Failed = 0x01]. |
Get Version Request
Queries the API version implemented in the adapter.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Version Request [0x02] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0000] |
Get Version Response
Provides the host with the API version implemented in the adapter.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Version Response [0x82] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0004] |
| Status | 1 | uint8 | Status of the response [Success = 0x00] |
| Major | 1 | uint8 | Major version number. 1 for this specification. |
| Minor | 1 | uint8 | Minor version number. 0 for this specification. |
| Patch | 1 | uint8 | Patch version number. 0 for this specification. |
Get Supported Requests List Request
Queries the list of the commands supported by the adapter. Only request messages are expected by the host.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Supported Commands Request [0x03] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0000] |
Get Supported Requests List Response
Provides the host a list of the commands that the adapter can receive and process. The command Ids can be provided in any order.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Supported Commands Response [0x83] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0008-0x0009] |
| Status | 1 | uint8 | Status of the response [Success = 0x00] |
| Command list | n | uint8[] | List of supported request commands |
Get Radio Configurations Count Request
Queries the number of different configurations supported by the adapter. A configuration is a combination of Modulation, Data Rate, Band and Frequency settings. The configurations supported by the adapter can be manufacturer specific.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Radio Configurations Count Request [0x04] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0000] |
Get Radio Configurations Count Response
Indicates to the host the number of configurations supported by the adapter.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Radio Configurations Count Response [0x84] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0003] |
| Status | 1 | uint8 | Status of the response [Success = 0x00] |
| Count | 2 | uint16 | The number of supported configurations |
Get Radio Configuration Description Request
After an adapter has responded with the number of radio configurations supported, the host will query the adapter to get the description of each supported configuration. The response from each configuration allows the host to display useful information regarding the configurations supported by an adapter.
This command will be sent for each configuration supported by the adapter starting at index 0 (zero). The configurations must be indexed in ascending order without skipping any index id, e.g. Configuration count = 3, then index must be 0, 1, 2.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Radio Configuration Description Request [0x05] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0002] |
| Configuration index | 2 | uint16 | The configuration index (from 0 to number of supported configurations-1) |
Get Radio Configuration Description Response
Provides the host with Modulation, rate, band, frequency, fractional frequency, and identifier supported per index. This information is used to display the available configurations in the adapter.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Get Radio Configuration Description Response [0x85] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x000E] |
| Status | 1 | uint8 | Status of the response. If valid index is queried [Success = 0x00], if invalid index is queried [Invalid index = 0x0A] |
| Modulation | 1 | enum8 | The channel modulation as defined in Table 4 |
| Rate | 4 | uint32 | The data rate of the communication channel. Units are in kbps. |
| Band | 2 | uint16 | Frequency band in which the adapter will be operating. Units are in MHz. |
| Frequency | 2 | uint16 | Integer part of the communication channel frequency. Units are in MHz. |
| Fractional frequency | 2 | uint16 | Fractional part of the communication channel frequency. Units in 1/65536 MHz |
| Identifier | 2 | uint16 | Channel identifier |
Table 4. Modulations enumeration
| Enum | Modulation |
|---|---|
| 0 | O-QPSK |
| 1 | GFSK |
| 2 - 251 | Reserved |
| 252 | Manufacturer specific 1 |
| 253 | Manufacturer specific 2 |
| 254 | Manufacturer specific 3 |
The Manufacturer specific modulation enums are available for the user to describe their own modulation type in case it is not defined already.
Start Sniffing Request
Indicates the adapter to initiate the sniffing operation with the radio configuration of the index provided.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Start Sniffing Request [0x06] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0002] |
| Configuration index | 2 | uint16 | The radio configuration index |
Start Sniffing Response
Indicates to the host the result of processing the Start Sniffing Request. After a successful response, the host is expecting to receive Sniffer Frame Indication messages from the adapter of the OverTheAir traffic on the channel that corresponds to the requested configuration.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Start Sniffing Response [0x86] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0001] |
| Status | 1 | uint8 | Status of the response. If valid index is queried [Success = 0x00], if invalid index is queried [Invalid index = 0x03] |
Stop Sniffing Request
Request the adapter to finish the sniffing operation. After a successful response, it is expected that none Sniffer Frame Indications will be sent by the adapter, if any are sent, those will be discarded by the host.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Stop Sniffing Request [0x07] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0000] |
Stop Sniffing Response
Indicates to the host that the request was received and the adapter has stopped the sniff operation
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Stop Sniffing Response [0x87] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0009] |
| Status | 1 | uint8 | Status of the response [Success = 0x00] |
| Reserved | 4 | uint32 | 0xFFFFFFFF |
| Reserved | 4 | uint32 | 0xFFFFFFFF |
Sniffer Frame Indication
Frame indications are generated when the adapter gets a frame. This is sent by the adapter to the host only if the adapter has started the sniff operation. There is no confirmation from the host on this message and the adapter must assume that the frame was processed correctly, then it can release the memory of those messages.
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Sniffer Frame Indication [0x48] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0007-0xFFFE] |
| Timestamp | 4 | uin32 | Timestamp is in ticks, each tick is 1 microsecond. |
| RSSI | 1 | int8 | Received Signal Strength Indicator. If not supported then [0x7F] shall be returned. |
| LQI | 1 | uint8 | Link Quality Indicator. If not supported then [0xFF] shall be returned |
| OTA payload | 0-128 | uint8[] | PHR + PHY PAYLOAD as defined in 802.15.4 spec (2015) |
Optional Adapter Commands
Start Sniffing w/Beacon Request
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Start Sniffing with Beacon Request [0x09] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0002] |
| Configuration index | 2 | uint16 | The radio configuration index |
Start Sniffing w/Beacon Response
| Field name | Octets | Type | Value |
|---|---|---|---|
| Command ID | 1 | uint8 | Start Sniffing with Beacon Response [0x89] |
| Payload length | 2 | uint16 | The length of the payload in octets [0x0001] |
| Status | 1 | uint8 | Status as defined in Table 2 |