ULS-DeCoNet Protocol Documentation

• 1: ULS Blitz Types and Description
• 2: ULS-DeCoNet Protocol Interface Control Document
• 3: ULS-DeCoNet Quick Reference Guide
• 4: ULS-DeCoNet Blitz Messages Specification
• 5: ULS-DeCoNet CAN Transport Specification
• 6: ULS-DeCoNet UART Transport Specification

1 - ULS Blitz Types and Description

ULSDC-PBDS031025 · version 1.0.1 · issued November 3, 2025
The numbered PDF is the controlled copy: download it from the portal.

Overview

The protocol used by devices for configuration is proprietary and is described in other documents. However, the protocol implements the possibility of transmitting messages (Blitz messages) that can be used by the user to control the device and obtain information. These messages are universal, and the format describes the data that is transmitted by various devices in our system connected to a single network.

Use CMD=6 to send Blitz messages.

In this document, the CAN protocol is specified. RS485 is used to implement custom protocols that can be defined in the future.

ULS-DECONET CAN Bus Protocol Frame Format

flowchart LR
  A[Sender Device] --> B[GLOBAL]
  B --> C[CMD = 6]
  C --> D[ID]
  D --> E[dsn_lid]
  E --> F[msg_id]
  F --> G[Blitz Payload data <= 8 bytes]
  G --> H[Receiver Device]

The CAN protocol uses the following frame structure:

Table: CAN Protocol Frame Fields

Status Bit Definitions

Most messages include a status byte with the following bit definitions:

Table: Status Bit Definitions

Message list by device

Message Types

XCG1 Raw Measurement (0x0010)

Message ID: ULS_BLITZ_MSG_ID_XCG1_RX_RAW_MEASURMENT (0x0010)

Structure: __uls_blitz_xcg1_rx_raw_measurmet

Table: XCG1 Raw Measurement Message Structure Usage: Legacy raw measurement data. Message generated by receiver each time it decode signal from transmitter. Client can capture this frame to get receivers raw data. Do not send this type of message to Bus.

Senders list (this message are generated by):

• ULSDV-XC-RX-G1 - ULS-XCopter receiver (generation 1).
• ULSDV-XC-RX-G2 - ULS-XCopter-G2 receiver (generation 2).
• ULSDV-XS-RXM - ULS-XSpot master receiver.
• ULSDV-XS-RXS - ULS-XSpot slave receiver.
• ULSDV-HL-RXM - ULS-Heli master receiver.
• ULSDV-HL-RXS - ULS-Heli slave receiver.
• ULSDV-PC-RX - ULS-ProCopter receiver.

Receivers list (this message is consumed by):

• Ground control stations (for monitoring)
• Debug/diagnostic tools
• Data logging systems

Raw Measurement (0x0011)

Message ID: ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT (0x0011)

Structure: __uls_blitz_msg_rx_raw_measurmet

Table: Raw Measurement Message Structure Angular Conversion Formula:

degrees = (value_int16 * 180.0f) / 32767.0f

Usage: Measurement data generated by receiver each time when signal from transmitter decoded.

Senders list (this message are generated by):

• ULSDV-XC-RX-G1 - ULS-XCopter receiver (generation 1).
• ULSDV-XC-RX-G2 - ULS-XCopter-G2 receiver (generation 2).
• ULSDV-XS-RXM - ULS-XSpot master receiver.
• ULSDV-XS-RXS - ULS-XSpot slave receiver.
• ULSDV-HL-RXM - ULS-Heli master receiver.
• ULSDV-HL-RXS - ULS-Heli slave receiver.
• ULSDV-PC-RX - ULS-ProCopter receiver.

Receivers list (this message is consumed by):

• Autopilot systems (Ardupilot, PX4)
• Ground control stations
• External navigation computers
• Data logging systems

Position in TX Frame (0x0012)

Message ID: ULS_BLITZ_MSG_ID_RX_POS_IN_TX_FRAME (0x0012)

Structure: __uls_blitz_msg_rx_pos_in_tx_frame

Table: Position in TX Frame Message Structure Usage: 3D position data relative to the transmitter coordinate system. Generated by receiver after calculating position from raw measurements.

Senders list (this message is generated by):

• ULSDV-XC-RX-G1 - ULS-XCopter receiver (generation 1).
• ULSDV-XC-RX-G2 - ULS-XCopter-G2 receiver (generation 2).
• ULSDV-XS-RXM - ULS-XSpot master receiver.
• ULSDV-XS-RXS - ULS-XSpot slave receiver.
• ULSDV-HL-RXM - ULS-Heli master receiver.
• ULSDV-HL-RXS - ULS-Heli slave receiver.
• ULSDV-PC-RX - ULS-ProCopter receiver.

Receivers list (this message is consumed by):

• Autopilot systems (Ardupilot, PX4)
• Ground control stations
• External navigation computers

MRX Information (0x0013)

Message ID: ULS_BLITZ_MSG_ID_RX_MRX (0x0013)

Structure: __uls_blitz_msg_rx_mrx

Table: MRX Information Message Structure Usage: Multi-receiver (MRX) information for secondary receiver data. Generated when multiple receivers calculate relative orientation.

Senders list (this message is generated by):

• ULSDV-XS-RXM - ULS-XSpot master receiver (when paired with slaves).
• ULSDV-HL-RXM - ULS-Heli master receiver (when paired with slaves).

Receivers list (this message is consumed by):

• Autopilot systems (for yaw correction)
• External navigation computers
• Ground control stations

DACS Information (0x0014)

Message ID: ULS_BLITZ_MSG_ID_RX_DACS (0x0014)

Structure: __uls_blitz_msg_rx_dacs

Table: DACS Information Message Structure Usage: DACS (Directional Angle Calculation System) data with continuous yaw tracking. Advanced multi-receiver mode with unwrapped yaw angle.

Senders list (this message is generated by):

• ULSDV-XS-RXM - ULS-XSpot master receiver (DACS mode).
• ULSDV-HL-RXM - ULS-Heli master receiver (DACS mode).

Receivers list (this message is consumed by):

• Autopilot systems (for continuous yaw tracking)
• External navigation computers
• Ground control stations

Ground IMU Measurement (0x0020)

Message ID: ULS_BLITZ_MSG_ID_GIMU_MEASUREMENT (0x0020)

Structure: __uls_blitz_msg_gimu_data

Table: Ground IMU Measurement Message Structure Angular Conversion Formula:

degrees = (value_int16 * 180.0f) / 32767.0f

Usage: Ground unit IMU (Inertial Measurement Unit) orientation data. Provides transmitter orientation for coordinate system transformation.

Senders list (this message is generated by):

• ULSDV-XC-TX-G1 - ULS-XCopter transmitter (generation 1).
• ULSDV-XC-TX-G2 - ULS-XCopter-G2 transmitter (generation 2).
• ULSDV-XS-TX - ULS-XSpot transmitter.
• ULSDV-HL-TX - ULS-Heli transmitter.
• ULSDV-PC-TX - ULS-ProCopter transmitter.

Receivers list (this message is consumed by):

• Ground control stations (for transmitter monitoring)

IMU Override (0x0030)

Message ID: ULS_BLITZ_MSG_ID_XX_TXC_IMU_OVERRIDE (0x0030)

Structure: __uls_blitz_msg_xx_txc_imu_override

Table: IMU Override Message Structure Control Bits:

Table: IMU Override Control Bits Angular Conversion Formula:

degrees = (value_int16 * 180.0f) / 32767.0f

Usage: Override IMU data on ground unit for external orientation control. Allows external IMU/compass to replace internal sensors.

Senders list (this message is sent by):

• External control PC/computer
• Autopilot systems (for transmitter orientation override)
• Ground control stations

Receivers list (this message is consumed by):

• ULSDV-XC-TX-G2 - ULS-XCopter-G2 transmitter (generation 2).
• ULSDV-XS-TX - ULS-XSpot transmitter.
• ULSDV-HL-TX - ULS-Heli transmitter.
• ULSDV-PC-TX - ULS-ProCopter transmitter.

Magnetometer Override (0x0031)

Message ID: ULS_BLITZ_MSG_ID_XX_TXC_MAG_OVERRIDE (0x0031)

Structure: __uls_blitz_msg_xx_txc_mag_override

Table: Magnetometer Override Message Structure Control Bits:

Table: Magnetometer Override Control Bits Magnetic Field Conversion Formula:

mag_value = (value_int16 * 1.0f) / 32767.0f

Usage: Override magnetometer data on ground unit for external compass control. Allows external magnetometer to replace internal compass.

Senders list (this message is sent by):

• External control PC/computer
• Autopilot systems (for compass override)
• Ground control stations
• External magnetometer systems

Receivers list (this message is consumed by):

• ULSDV-XC-TX-G2 - ULS-XCopter-G2 transmitter (generation 2).
• ULSDV-XS-TX - ULS-XSpot transmitter.
• ULSDV-HL-TX - ULS-Heli transmitter.
• ULSDV-PC-TX - ULS-ProCopter transmitter.

Implementation Notes

1. Packed Structures: All structures use __attribute__((packed)) to ensure no padding bytes are added by the compiler.

2. Endianness: The protocol assumes little-endian byte order for multi-byte fields.

3. Message Counters: Most messages include a counter field for packet ordering and loss detection.

4. Angular Precision: Angular measurements use 16-bit signed integers with specific scaling factors for different ranges.

5. Distance Units: Distance measurements may use different units (cm, 10cm increments) depending on the message type.

2 - ULS-DeCoNet Protocol Interface Control Document

ULSDC-PBICD011125 · version 1.0.5 · issued November 13, 2025
The numbered PDF is the controlled copy: download it from the portal.

Introduction

Purpose

The ULS-DeCoNet (ULS Devices Connection Network) protocol is a comprehensive communication protocol designed for Ultra-precise Location Systems (ULS). It provides a robust, hierarchical network architecture for connecting ULS devices across multiple transport mediums including UART and CAN bus.

Scope

This protocol defines:

• Device discovery and network management
• Object-oriented data exchange
• System control and configuration
• Firmware update mechanisms
• Multi-hop routing capabilities
• Blitz sensor data transmission

Key Features

• Multi-transport Support: UART (with various framing modes) and CAN bus
• Automatic Device Discovery: Dynamic network topology with automatic ID allocation
• Hierarchical Addressing: Support for up to 63 local devices per interface
• Multi-hop Routing: Packet forwarding through intermediate nodes
• Object-based Data Model: Structured access to device parameters and data
• Permission System: Read/write/protected access control for objects
• Firmware Update: Secure bootloader mode with signature verification
• Low Overhead: Optimized for embedded systems with limited resources

Terminology

Protocol Architecture

Protocol Stack

block-beta
  columns 1
  A["Application Layer\n(Device Objects, Blitz Messages, Config)"]
  B["Connection Layer (CN)\n(Object Access, System Commands, Routing)"]
  C["Interface Layer (IF)\n(Network Management, Device Discovery)"]
  D["Framing Layer\n(UART: ESC/COBS, CAN: Multi-frame)"]
  E["Physical Layer\n(UART, CAN/FDCAN)"]

Design Principles

1. Layered Architecture: Clear separation of concerns between protocol layers
2. Transport Agnostic: Core protocol independent of physical medium
3. Efficient Framing: Multiple framing modes optimized for different scenarios
4. Scalable Addressing: Support for hierarchical and flat addressing schemes
5. Robust Error Handling: CRC protection and timeout-based error recovery
6. Plug-and-Play: Automatic device discovery and ID allocation

OSI Layer Model Mapping

The ULS-DeCoNet protocol maps to the OSI reference model as follows:

Layer Interactions

Application Data (Objects/Blitz)
        ↓
    [CN Layer]
    - Add routing information
    - Add command type
        ↓
    [IF Layer]
    - Add source LID
    - Add command flags
    - Network management
        ↓
    [Framing Layer]
    - Add frame delimiters
    - Add CRC
    - Escape special characters (UART)
    - Multi-frame splitting (CAN)
        ↓
    [Physical Layer]
    - Transmit bytes/frames

Physical Layer

UART Physical Layer

Specifications:

• Data Format: 8-N-1 (8 data bits, no parity, 1 stop bit)
• Baud Rates: Configurable (typically 115200, 230400, 460800, 921600 bps)
• Voltage Levels: Device-dependent (typically 3.3V or 5V TTL/RS232)
• Flow Control: Optional hardware (RTS/CTS) or software (XON/XOFF)

Advantages:

• Simple two-wire interface
• Widely supported
• Point-to-point or multi-drop with appropriate hardware

Limitations:

• Distance limitations without level shifters
• No built-in arbitration for multi-device scenarios

CAN Physical Layer

Specifications:

• CAN Version: Classical CAN and CAN-FD (FDCAN) supported
• Bit Rates:
  • Classical CAN: Up to 1 Mbps
  • CAN-FD: Up to 5 Mbps (data phase)
• Bus Topology: Multi-drop differential bus
• Termination: 120Ω termination resistors required at both ends
• Max Devices: Theoretically unlimited (practical limit ~32-64)
• Max Distance: Up to 40m @ 1Mbps, longer at lower speeds

Advantages:

• Multi-master capability with arbitration
• Built-in error detection and signaling
• Robust in electrically noisy environments
• Supports broadcast and multicast

CAN Identifiers:

• Standard 11-bit identifiers used
• Identifier structure defined by implementation

Data Link Layer

The Data Link Layer provides reliable frame transmission with error detection. Different framing modes are supported for UART, while CAN has its own native framing.

UART Framing Modes

The protocol supports four UART framing modes:

RAW Mode (SERIAL_MODE_RAW)

Description: No framing - direct byte transmission

Use Case: Binary data transfer when frame boundaries are managed at higher layers

Structure:

[DATA BYTES...]

Characteristics:

• No overhead
• No frame delimiting
• No error detection at this layer
• Highest throughput
• Requires higher layer to manage message boundaries

ESC Mode (SERIAL_MODE_ESC)

Description: Frame delimiting with byte stuffing and CRC-16

Frame Structure:

packet-beta
title "ESC Mode Frame Structure"
0-7: "SOF 0x55 (1 byte)"
8-15: "START_TYPE 0x01 (1 byte)"
16-23: "PAYLOAD (variable, ~1 byte)"
24-31: "CRC_LOW (1 byte)"
32-39: "CRC_HIGH (1 byte)"
40-47: "EOF 0x55 (1 byte)"
48-55: "END_TYPE 0x03 (1 byte)"

Byte Stuffing:

• If data byte == 0x55, insert 0x02 after it
• Delimiter 0x55 is escaped when it appears in payload or CRC

CRC Calculation:

• Algorithm: CRC-16 (polynomial 0x8005, init 0xFFFF)
• Applied to payload only
• 2 bytes transmitted (low byte, high byte)

Example:

Original payload: [0x12, 0x55, 0x34]
CRC: 0xABCD

Transmitted frame:
0x55 0x01 0x12 0x55 0x02 0x34 0xCD 0xAB 0x55 0x03

Characteristics:

• Frame boundaries clearly defined
• Error detection with CRC-16
• Variable overhead (depends on data content)
• Average overhead: ~15-25%

ESC Simple CRC Mode (SERIAL_MODE_ESC_SIMPLE_CRC)

Description: Similar to ESC mode but with simpler 8-bit checksum

Frame Structure:

packet-beta
title "ESC Simple Mode Frame Structure (8-bit Checksum)"
0-7: "SOF 0x55 (1 byte)"
8-15: "START_TYPE 0x01 (1 byte)"
16-23: "PAYLOAD (variable, ~1 byte)"
24-31: "CHECKSUM (1 byte)"
32-39: "EOF 0x55 (1 byte)"
40-47: "END_TYPE 0x03 (1 byte)"

Checksum:

• Simple byte summation: checksum = Σ(data_bytes) & 0xFF
• 1 byte transmitted

Characteristics:

• Faster than CRC-16
• Lower error detection capability
• Less overhead than full ESC mode
• Suitable for low-error-rate environments

COBS Mode (SERIAL_MODE_COBS)

Description: Consistent Overhead Byte Stuffing with CRC-16

Advantages:

• Predictable framing overhead
• Zero byte (0x00) used as frame delimiter
• No data expansion for most byte values
• Very efficient for binary data

Frame Structure:

packet-beta
title "COBS Mode Frame Structure"
0-7: "SOF 0x00 (1 byte)"
8-15: "COBS CODE (1 byte)"
16-79: "ENCODED DATA (variable, ~8 bytes)"
80-87: "CRC_LOW (1 byte)"
88-95: "CRC_HIGH (1 byte)"
96-103: "EOF 0x00 (1 byte)"

COBS Encoding Algorithm:

1. Packet is divided into blocks separated by zero bytes
2. Each block is preceded by a code byte:
   • Code byte = number of non-zero bytes following + 1
   • Maximum block size = 254 bytes
   • Code byte 0xFF means 254 non-zero bytes follow

Example:

Original data: [0x45, 0x00, 0x00, 0x2C, 0x4C]

COBS encoded: [0x02, 0x45, 0x01, 0x03, 0x2C, 0x4C]
              ^^^^^ ^^^^  ^^^^  ^^^^^ ^^^^^^^^^^
              code  data  code  code  data data

With frame delimiters:
0x00 0x02 0x45 0x01 0x03 0x2C 0x4C [CRC_L] [CRC_H] 0x00

COBS Characteristics:

• Overhead: +1 byte per 254 bytes + frame delimiters
• Maximum overhead: ~0.4% + fixed overhead
• Excellent for binary protocols
• No byte escaping needed
• Efficient zero-crossing detection

CRC Calculation in COBS:

• CRC-16 calculated on original unencoded data
• CRC bytes are COBS encoded with the data

CAN Framing

CAN bus has built-in framing at the hardware level, but ULS-DeCoNet adds an additional application-level framing layer for large messages.

Single-Frame CAN Messages

Structure:

packet-beta
title "Single-Frame CAN Message (8-byte data field)"
0-7: "CMD (1 byte)"
8-15: "SRC (1 byte)"
16-23: "(varies) (1 byte)"
24-87: "PAYLOAD (variable, ~8 bytes)"

Field Description:

• Byte 0 (CMD): Command type (IF layer command)
• Byte 1 (SRC): Source device ID (bits 0-5), connection ID (bits 6-7)
• Bytes 2+: Command-specific payload

Used for:

• Network management messages (HB, REQUEST_ID, SET_ID)
• Blitz messages (up to 10 bytes payload)
• Short system commands

Multi-Frame CAN Messages

For messages larger than can fit in a single CAN frame, multi-frame protocol is used.

Frame Structure:

packet-beta
title "Multi-Frame CAN Message"
0-7: "CMD (1 byte)"
8-15: "DID (1 byte)"
16-23: "FRMCTL (1 byte)"
24-95: "PAYLOAD (variable, ~9 bytes)"

FRMCTL byte: Bit 7 = End-of-message flag (1 = last frame); Bits 6-0 = Frame sequence number (0–127)

Multi-Frame Protocol:

1. Frame Sequence: Frames numbered 0, 1, 2, … N
2. Last Frame Marker: Frame N has bit 7 set (value = N | 0x80)
3. Payload per Frame: 9 bytes (DLC = 11, minus 3 header bytes)
4. Frame Pool: Receiver maintains a pool of 256 frame buffers
5. Timeout: Device timeout of 128 frames worth of time

Transmission Algorithm:

total_frames = ceil(message_len / 9)
for frame_num in 0..total_frames-1:
    can_frame.data[0] = CMD
    can_frame.data[1] = SRC_DID
    can_frame.data[2] = frame_num
    if frame_num == total_frames-1:
        can_frame.data[2] |= 0x80  // Mark last frame
    copy up to 9 bytes to can_frame.data[3..11]
    send_can_frame()

Reception Algorithm:

On receiving CAN frame:
    1. Store frame in pool indexed by (DID, frame_num)
    2. Set device timeout
    3. If last_frame_flag:
        a. Verify all frames 0..N received
        b. Reconstruct message from frames
        c. If complete: process message
        d. If incomplete: log missing frames, discard
        e. Free pool entries for this DID

Frame Pool Management:

• Pool Size: 256 frame slots
• Device Table: 64 device entries with timeouts
• Timeout Value: CN_CAN_DEV_TIMEOUT = 128 frames
• Cleanup: On timeout, all frames from device are freed

Example Multi-Frame Message:

Message length: 25 bytes
Frames needed: 3 (9+9+7)

Frame 0: [CMD][DID][0x00][data 0-8]
Frame 1: [CMD][DID][0x01][data 9-17]
Frame 2: [CMD][DID][0x82][data 18-24][pad]
                    ^^^^
                    0x80 | 0x02 = last frame, number 2

Error Handling:

• Missing frame detection by sequence number gaps
• Device timeout triggers cleanup
• Duplicate frames overwrite previous (allows retransmission)
• Pool full triggers emergency cleanup of timed-out devices

CRC-16 Algorithm

Polynomial: 0x8005 (CRC-16-IBM/ANSI)
Initial Value: 0xFFFF
Table-based implementation for efficiency

uint16_t crc = 0xFFFF;
for each byte in data:
    crc = (crc >> 8) ^ crc16_table[(crc ^ byte) & 0xFF]

Validation:

• Receiver calculates CRC over received data
• Valid frame: calculated CRC == 0x0000 (after including received CRC bytes)

Network Layer

The Network Layer (IF Layer) manages device addressing, discovery, and basic packet routing.

Addressing Scheme

Device ID (DID/LID)

Range: 0-63 (6 bits)

Special IDs:

• ID 0: Reserved for the master device (typically the main controller or coordinator)
• ID 63: Used by devices before ID assignment and for broadcast messages

Connection ID (CID)

Range: 0-3 (2 bits)

Identifies which physical connection a device uses when a node has multiple network interfaces.

Combined Routing ID (CNRID):

CNRID = (CID << 6) | DID
       = [CID(2)][DID(6)]

Bits: 7 6 5 4 3 2 1 0
      └─┘ └─────────┘
      CID     DID

Network Management (NM) Protocol

The NM protocol handles device discovery and ID allocation.

Device States

stateDiagram-v2
  [*] --> UNINITIALIZED: Power On (DID=63)
  UNINITIALIZED --> WaitingSetID: Send REQUEST_ID
  WaitingSetID --> OK: Receive SET_ID (DID assigned)
  OK --> OK: Send HB / Timeout

NM Messages

IF_CMD_NM_HB (0x01) - Heartbeat

Purpose: Keep-alive message to announce presence

Structure:

packet-beta
title "IF_CMD_NM_HB (0x01) Heartbeat"
0-7: "CMD 0x01 (1 byte)"
8-15: "SRC (DID) (1 byte)"
16-47: "UID0 (4 bytes)"

Fields:

• CMD: 0x01
• SRC: Source device ID
• UID0: Device unique ID (first 32 bits)

Timing:

• Send Interval: Every 1000ms (IF_NM_PING_HB_TIMEOUT)
• Receive Timeout: 3000ms (IF_NM_DVICE_HB_TIMEOUT)
• Device considered disconnected if no HB received within timeout

Behavior:

• All devices with assigned ID send periodic HB
• Master and slaves both participate
• Timeout detection triggers disconnection callback

IF_CMD_NM_REQUEST_ID (0x03) - Request ID Allocation

Purpose: Device requests ID assignment from master

Structure:

packet-beta
title "IF_CMD_NM_REQUEST_ID (0x03)"
0-7: "CMD 0x03 (1 byte)"
8-15: "SRC 63 (1 byte)"
16-47: "KEY (4 bytes)"

Fields:

• CMD: 0x03
• SRC: 63 (uninitialized)
• KEY: Random 32-bit key derived from device UID

Key Generation:

key = DEVICE_KEY ^ key_counter
where DEVICE_KEY = UID0 ^ UID1 ^ UID2 ^ UID3

Timing:

• Sent every 100ms + random offset
• Up to 5 attempts
• If no master responds, device self-assigns random free ID

IF_CMD_NM_SET_ID (0x04) - ID Assignment

Purpose: Master assigns ID to requesting device

Structure:

packet-beta
title "IF_CMD_NM_SET_ID (0x04)"
0-7: "CMD 0x04 (1 byte)"
8-15: "SRC 0 (1 byte)"
16-23: "NEW_ID (1 byte)"
24-55: "KEY (4 bytes)"

Fields:

• CMD: 0x04
• SRC: 0 (master device)
• NEW_ID: Assigned device ID (1-62)
• KEY: The key from REQUEST_ID message

ID Allocation Algorithm (Master):

1. Maintain table of active devices (timeout-based)
2. On REQUEST_ID received:
   a. Scan table for first free ID (timeout == 0)
   b. Assign that ID
   c. Send SET_ID with matching KEY
   d. Set timeout for new device

Reception (Requesting Device):

1. Receive SET_ID
2. Verify KEY matches own key
3. If match:
   a. Set DID = NEW_ID
   b. Change state to OK
   c. Send immediate HB
4. If no match:
   Ignore (not for us)

IF_CMD_NM_RESET_ID (0x05) - Reset Device ID

Purpose: Force device to return to uninitialized state

Structure:

packet-beta
title "IF_CMD_NM_RESET_ID (0x05)"
0-7: "CMD 0x05 (1 byte)"
8-15: "SRC 0 (1 byte)"
16-23: "DST_DID (1 byte)"

Note: Defined but not fully implemented in current version

Static ID Assignment

Method: ifSetStaticDID(uint8_t static_did)

Devices can be configured with static IDs (1-62) that bypass the dynamic allocation process.

Usage:

• Configuration storage in device
• Fixed topology networks
• Deterministic addressing requirements

Behavior:

• Device uses static ID immediately
• Still sends HB for presence indication
• Bypasses REQUEST_ID mechanism

Network Topology

The IF layer supports various network topologies:

Star Topology

flowchart TB
  Master["Master (ID=0)"] --> N1["Node (1)"]
  Master --> N2["Node (2)"]
  Master --> N3["Node (3)"]

Characteristics:

• Single master (ID=0)
• All slaves connect directly to master
• Master performs ID allocation
• Common for UART bus configurations

Multi-Master (CAN)

flowchart LR
  N0["(0)"] --- N1["(1)"] --- N2["(2)"] --- N3["(3)"]
  N0 --- N4["(4)"]
  N3 --- N5["(5)"]
  N4~~~N5

CAN BUS (shared medium)

Characteristics:

• Any device can be master (first ID=0 or all peer)
• Peer-to-peer communication possible
• ID allocation can be distributed
• Typical for CAN bus configurations

Packet Structure (IF Layer)

packet-beta
title "IF Layer Packet Structure"
0-7: "CMD (1 byte)"
8-15: "SRC_LID (1 byte)"
16-79: "PAYLOAD (variable, ~8 bytes)"

CMD Field (1 byte):

• Bit 4: Frame type flag
  • 0x00-0x0F: Network management / System commands
  • 0x10-0x1F: Higher layer protocols (CN layer)
• Bits 3-0: Command code

IF Layer Commands:

Transport Layer

The Transport Layer (CN - Connection Layer) provides routing, object access, and system management.

CN Protocol Overview

The Connection layer adds:

• Multi-hop routing
• Object-oriented data access
• System configuration and firmware update
• Reliable request-response patterns

Routing Mechanism

Route Table

Routes are stored as arrays of routing IDs (CNRID):

Route = [hop0, hop1, hop2, ..., hopN]

Each hop contains:
  - Bits 7-6: CID (Connection ID)
  - Bits 5-0: DID (Device ID)

Route Direction:

• Forward Route (command): hop0 = source, hopN = destination
• Reverse Route (response): route is reversed

CN Packet Structure

packet-beta
title "CN Packet Structure"
0-7: "CMD (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-143: "PAYLOAD (variable, ~8 bytes)"

HOP byte: Bits 7-4 = current hop index; Bits 3-0 = route size

Packet Fields:

• CMD: CN command type
• SRC_DID: Original source device ID
• HOP: Hop counter (high nibble) and route size (low nibble)
• ROUTE: Array of CNRID values defining path
• PAYLOAD: Command-specific data

Routing Example

Scenario: Device A (DID=1, CID=0) sends message to Device C (DID=3, CID=2) through Device B (DID=2, CID=1)

Forward Packet (A→B→C):

At A:
  CMD = CN_CMD_GETOBJ
  SRC_DID = 1
  HOP = 0x03 (hop=0, route_size=3)
  ROUTE = [0x01, 0x42, 0x83]
          ^^^^  ^^^^  ^^^^
          A     B     C
          CID=0 CID=1 CID=2
          DID=1 DID=2 DID=3

At B (forwarding):
  - Increment hop: HOP = 0x13 (hop=1, route_size=3)
  - Next destination = ROUTE[1] = 0x42 (DID=2)
  - Forward to CID=1

At C (final destination):
  - hop == route_size-1, packet is for us
  - Process CN_CMD_GETOBJ

Response Packet (C→B→A):

At C:
  CMD = CN_ACK_GETOBJ
  SRC_DID = 3
  HOP = 0x03 (hop=0, route_size=3)
  ROUTE = [0x83, 0x42, 0x01]  // Reversed!
          ^^^^  ^^^^  ^^^^
          C     B     A

Routing process same as forward

Route Discovery

Routes are built dynamically through Explorer messages:

1. Master sends CN_CMD_EXPLORER with empty route
2. Each device:
   • Adds its CNRID to route
   • Forwards to all connections
   • Responds with CN_ACK_EXPLORER containing reverse route
3. Master builds topology map from responses

CN Commands

Command Types

Explorer Protocol

CN_CMD_EXPLORER (0x10)

Purpose: Discover network topology

Structure:

packet-beta
title "CN_CMD_EXPLORER (0x10)"
0-7: "0x10 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-87: "ROUTE (variable, ~8 bytes)"

Transmission:

1. Master sends with HOP=0x00, empty route
2. Each device receives:
   a. Append own CNRID to route
   b. If HOP < 15:
      - Increment HOP
      - Forward to all other connections
   c. Send CN_ACK_EXPLORER with reverse route

CN_ACK_EXPLORER (0x11)

Purpose: Respond to explorer with device info

Structure:

packet-beta
title "CN_ACK_EXPLORER (0x11)"
0-7: "0x11 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-111: "TYPE (4 bytes)"
112-239: "NAME (16 bytes)"

Fields:

• TYPE: Device type code (uint32_t)
• NAME: Device name (null-terminated string, max 16 chars)

Object Access

CN_CMD_GETOBJ (0x14) - Read Object

Purpose: Read data from device object

Request Structure:

packet-beta
title "CN_CMD_GETOBJ (0x14) Request"
0-7: "0x14 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-95: "OBJ_ADDR (2 bytes)"

Fields:

• OBJ_ADDR: Object address/ID (uint16_t)

Response (CN_ACK_GETOBJ):

packet-beta
title "CN_ACK_GETOBJ (0x15) Response"
0-7: "0x15 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-95: "OBJ_ADDR (2 bytes)"
96-159: "OBJ_DATA (variable, ~8 bytes)"

Process:

1. Request routed to target device
2. Device looks up object by OBJ_ADDR
3. Check read permission
4. If OK: respond with object data
5. If error: no response or error code

CN_CMD_SETOBJ (0x16) - Write Object

Purpose: Write data to device object

Request Structure:

packet-beta
title "CN_CMD_SETOBJ (0x16) Request"
0-7: "0x16 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-95: "OBJ_ADDR (2 bytes)"
96-159: "OBJ_DATA (variable, ~8 bytes)"

Response (CN_ACK_SETOBJ):

packet-beta
title "CN_ACK_SETOBJ (0x17) Response"
0-7: "0x17 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-95: "OBJ_ADDR (2 bytes)"

Process:

1. Request routed to target device
2. Device looks up object by OBJ_ADDR
3. Check write permission
4. If OK: write data, respond with ACK
5. If error: no response or error code

System Commands

CN_CMD_SYS (0x12) - System Operations

Purpose: Device configuration and firmware update

Structure:

packet-beta
title "CN_CMD_SYS (0x12)"
0-7: "0x12 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-87: "SYSCMD (1 byte)"
88-151: "SYS_PAYLOAD (variable, ~8 bytes)"

System Sub-Commands:

PING (0x00)

Request:

packet-beta
title "SYS PING (0x00) Request"
0-7: "SYSCMD 0x00 (1 byte)"
8-23: "DEVTYPE (2 bytes)"

Response: Operation result (CN_ACK_SYS)

SETMODE (0x01)

Purpose: Switch between application and bootloader mode

Request:

┌─────────┬──────┐
│ SYSCMD  │ MODE │
│  0x01   │(1 b) │
└─────────┴──────┘

MODE values:
  0 = CN_SYS_MODE_APP (application)
  1 = CN_SYS_MODE_LOADER (bootloader)

Usage:

• Switch to loader mode for firmware update
• Requires device reset after mode change

ERASE (0x02)

Purpose: Erase flash memory region

Request:

packet-beta
title "SYS ERASE (0x02)"
0-7: "SYSCMD 0x02 (1 byte)"
8-39: "KEY (4 bytes)"
40-71: "START (4 bytes)"
72-103: "LEN (4 bytes)"

Fields:

• KEY: Operation authorization key
• START: Start address in flash
• LEN: Length to erase (bytes)

Response: Operation result with status code

WRITE (0x03)

Purpose: Write data to flash memory

Request:

packet-beta
title "SYS WRITE (0x03)"
0-7: "SYSCMD 0x03 (1 byte)"
8-39: "KEY (4 bytes)"
40-71: "START (4 bytes)"
72-103: "LEN (4 bytes)"
104-135: "DATA (up to 512 bytes)"

Fields:

• KEY: Operation authorization key
• START: Start address in flash
• LEN: Length to write (bytes)
• DATA: Data to write

Response: Operation result with status code

SETSIGNATURE (0x04)

Purpose: Set firmware signature information

Request:

packet-beta
title "SYS SETSIGNATURE (0x04)"
0-7: "SYSCMD 0x04 (1 byte)"
8-39: "KEY (4 bytes)"
40-295: "FW version (32 bytes)"
296-551: "LDR version (32 bytes)"
552-583: "FWTIME (4 bytes)"
584-615: "PROGSIZE (4 bytes)"
616-647: "PROGCRC (4 bytes)"

Fields:

• KEY: Operation authorization key
• FW: Firmware version string (32 chars)
• LDR: Loader version string (32 chars)
• FWTIME: Firmware flashing timestamp
• PROGSIZE: Program size in bytes
• PROGCRC: Program CRC32 checksum

Purpose: Store metadata after firmware update completion

SAVECFG (0x05)

Purpose: Save current configuration to non-volatile memory

Request:

packet-beta
title "SYS SAVECFG (0x05)"
0-7: "SYSCMD 0x05 (1 byte)"
8-39: "KEY (4 bytes)"

CN_ACK_SYS (0x13) - System Command Response

Structure:

packet-beta
title "CN_ACK_SYS (0x13)"
0-7: "0x13 (1 byte)"
8-15: "SRC_DID (1 byte)"
16-23: "HOP (1 byte)"
24-79: "ROUTE (variable, ~8 bytes)"
80-87: "RESULT (1 byte)"

Result Codes:

Operation Keys

Purpose: Prevent unauthorized firmware modifications

Key Generation:

#define _ULS_OPERATION_KEY 0x24041982

#define DEVICE_KEY (UID0 ^ UID1 ^ UID2 ^ UID3)

uint32_t operation_key = _ULS_OPERATION_KEY;
// Or device-specific key for some operations

Usage:

• ERASE, WRITE, SETSIGNATURE, SAVECFG require valid key
• Key validation prevents accidental or malicious operations
• Each device can have unique key derived from UID

Application Layer

The Application Layer defines device-specific data structures and high-level protocols.

Object Model

Object Architecture

Objects provide structured access to device parameters, configuration, and data.

Object Base Class:

class ULSObjectBase {
    uint16_t id;                      // Object address
    uint16_t size;                    // Size of single element
    uint16_t len;                     // Array length (1 for scalar)
    uint8_t *data;                    // Pointer to data
    const char *name;                 // Object name
    const char *description;          // Object description
    _ulsbus_obj_permissions permission; // Access permission
}

Object Permissions

*Note: Protected/Config/Admin levels require additional authorization mechanisms (implementation-specific)

Standard Objects

System Signature Object (0x0001)

Purpose: Device identification and firmware information

Structure:

struct ULSObjectSignature {
    char fw[32];                  // Firmware version
    char ldr[32];                 // Loader/bootloader version
    uint32_t serial[4];           // Device serial number (UID)
    uint32_t progflashingtime;    // Firmware flash timestamp
    uint32_t progsize;            // Program size
    uint32_t progcrc;             // Program CRC32
    uint32_t type;                // Device type code
}; // Total: 128 bytes

Permission: READONLY

Usage:

• Device identification
• Firmware version tracking
• Update verification

Device Base Class

class ULSDBase {
    const char *devname;          // Device name
    const char *typeName;         // Type name string
    uint16_t typeCode;            // Numeric type code
    ULSList<ULSObjectBase> objects; // List of objects
    
    ULSObjectBase* getObject(uint16_t obj_id);
    void setData(uint16_t obj_id, uint8_t *buf);
};

Purpose: Base class for all ULS devices providing:

• Object management
• Device identification
• Configuration storage

Blitz Protocol

The Blitz protocol provides high-frequency sensor data transmission with minimal overhead.

Blitz Packet Structure (IF Layer)

packet-beta
title "Blitz Packet (IF Layer)"
0-7: "CMD 0x06 (1 byte)"
8-15: "SRC_LID (1 byte)"
16-31: "MSG_ID (2 bytes)"
32-95: "DATA (8 bytes)"

Fields:

• CMD: 0x06 (IF_CMD_BLITZ)
• SRC_LID: Source device ID
• MSG_ID: Blitz message type identifier
• DATA: Message-specific payload (max 8 bytes)

Blitz Message Types

See separate document: ULS-DeCoNet_Blitz_Messages.md for complete message definitions.

Summary of Message Types:

Blitz Data Flow

Sensor → Measurement → Blitz Packet → IF Layer → Framing → Physical Layer
  ↓
[Status Bits]
[Counter]
[Sensor Data]

Status Bits (common to most Blitz messages):

Blitz Usage Pattern

Transmitter:

// Construct Blitz message
__uls_blitz_msg_rx_raw_measurmet msg;
msg.status = calculate_status();
msg.counter = counter++;
msg.aX = angle_x_scaled;
msg.aY = angle_y_scaled;
msg.distance = distance_cm;

// Send via IF layer
interface->ifSendBLITZ(
    ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT,
    (uint8_t*)&msg,
    sizeof(msg)
);

Receiver:

// Set callback
interface->ifclbkBlitzReceived = &onBlitzReceived;

void onBlitzReceived(ULSBusInterface *iface) {
    uint16_t msg_id = iface->ifRxPacket->blitz.msg_id;
    uint8_t *data = iface->ifRxPacket->blitz.data;
    
    switch(msg_id) {
        case ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT:
            process_raw_measurement(data);
            break;
        // ... handle other message types
    }
}

Application Examples

Read Configuration Object

Scenario: Read object 0x0100 from device at DID=5

// Prepare route (direct connection)
uint8_t route[] = {0x05}; // DID=5, CID=0

// Send GET request
connection->cnSendGetObject(
    route,              // Route array
    1,                  // Route size (hops)
    0x0100             // Object address
);

// Response handled in callback
connection->cnclbkObjReceived = &onObjectReceived;

void onObjectReceived(ULSBusConnection *cn) {
    uint16_t obj_addr = *((uint16_t*)&cn->cnRxPacket->pld[cn->cnRxPacket->hop & 0xF]);
    uint8_t *obj_data = &cn->cnRxPacket->pld[(cn->cnRxPacket->hop & 0xF) + 2];
    
    // Process object data
    process_config(obj_addr, obj_data);
}

Firmware Update Procedure

1. Switch to Loader Mode:
   cnSendSysSetMode(route, hops, CN_SYS_MODE_LOADER)
   → Device resets into bootloader

2. Erase Flash:
   cnSendSysErase(route, hops, key, start_addr, length)
   → Wait for CN_ACK_SYS with OK result

3. Write Firmware (in blocks):
   for each 512-byte block:
       cnSendSysWrite(route, hops, key, addr, 512, data)
       → Wait for CN_ACK_SYS with OK result
       addr += 512

4. Set Signature:
   cnSendSysSetSignature(route, hops, key, fw_ver, ldr_ver, 
                         timestamp, size, crc)
   → Device validates and stores metadata

5. Save Configuration:
   cnSendSysSaveConfig(route, hops, key)
   → Device commits changes

6. Switch to Application Mode:
   cnSendSysSetMode(route, hops, CN_SYS_MODE_APP)
   → Device resets into new firmware

Security Considerations

Authentication

Operation Keys:

• System operations require 32-bit keys
• Key validation prevents unauthorized firmware modification
• Keys can be device-specific (derived from UID)

Recommendations:

• Change default _ULS_OPERATION_KEY for production
• Implement challenge-response for critical operations
• Consider encryption for sensitive data

Access Control

Object Permissions:

• Enforce read/write restrictions
• Protected objects require authorization
• Validate permissions before object access

Firmware Integrity

CRC Validation:

• Firmware CRC32 stored in signature
• Bootloader verifies before execution
• Prevents corrupted firmware execution

Signature Verification:

• Firmware version and timestamp tracking
• Size validation
• Metadata consistency checks

Network Security

ID Allocation:

• Master controls ID assignment
• Duplicate ID detection
• Timeout-based cleanup

Routing:

• Route validation
• Hop count limits prevent loops
• Source verification

Best Practices

1. Use static IDs for critical devices
2. Implement authentication for system commands
3. Validate all inputs at object level
4. Use CRC checking on all transports
5. Implement timeouts for all operations
6. Log security events for audit trails
7. Encrypt sensitive data if required by application
8. Protect operation keys in device storage

References

• ULS-DeCoNet Source Code: ULSOpenLib/
• ULSDC-PBDS021125 - ULS-DeCoNet CAN Transport Specification
• ULSDC-PBDS031125 - ULS-DeCoNet UART Transport Specification
• ULSDC-PBDS041125 - ULS-DeCoNet Quick Reference Guide
• ULSDC-PBDS051125 - ULS-DeCoNet Blitz Messages Specification

Copyright © 2020-2026 UAVLAS <www.uavlas.com>
License: GNU Lesser General Public License v3.0+
Project: ULS Devices Connection Network (ULS-DeCoNet)

3 - ULS-DeCoNet Quick Reference Guide

ULSDC-PBDS041125 · version 1.0.0 · issued November 13, 2025
The numbered PDF is the controlled copy: download it from the portal.

Protocol Stack

Application Layer    │ Objects, Blitz Messages, Device Data
Connection Layer     │ Routing, Object Access, System Commands
Interface Layer      │ Network Management, Device Discovery
Framing Layer        │ UART: ESC/COBS  |  CAN: Multi-frame
Physical Layer       │ UART 115200+    |  CAN 1Mbps

Addressing

Special Addresses:

• 0: Master device
• 63: Broadcast / Uninitialized
• 1-62: Regular devices

UART Framing Modes

Frame Examples

ESC Mode:

[0x55][0x01][DATA...][CRC_L][CRC_H][0x55][0x03]

COBS Mode:

[0x00][CODE][DATA...][CRC_L][CRC_H][0x00]

CAN Frame Structure

Single-Frame (≤10 bytes payload)

[CMD][DID][PAYLOAD(6 bytes)]

Multi-Frame (>10 bytes)

Frame N:   [CMD][DID][FRMCTL][PAYLOAD(5 bytes)]
Last Frame: FRMCTL = 0x80 | frame_number

Frame Control (FRMCTL):

• Bit 7: End flag (1 = last frame)
• Bits 6-0: Frame number (0-127)

IF Layer Commands

Packet Structure:

[CMD][SRC_LID][PAYLOAD]

CN Layer Commands

Packet Structure:

[CMD][SRC_DID][HOP][ROUTE...][PAYLOAD]

HOP byte:
  Bits 7-4: Current hop index
  Bits 3-0: Route size

System Sub-Commands

Result Codes:

• 0: UNDEFINED
• 1: OK
• 2: ERROR
• 3: WRONGKEY

Blitz Messages

Message Types

Status Bits

Data Encoding

Angles (±180°):

int16_t = (degrees / 180.0) * 32767.0
degrees = (int16_t / 32767.0) * 180.0

Position/Distance (cm):

value_cm = int16_t or uint16_t
value_m = value_cm * 0.01

Object Permissions

*Requires authorization

Network States

Device States

UNINITIALIZED (DID=63)
    ↓ Send REQUEST_ID
    ↓ Receive SET_ID
OK (DID assigned)
    ↓ Send HB every 1000ms
    ↓ Timeout 3000ms
ERROR

Common Operations

Device Discovery

1. Master sends CN_CMD_EXPLORER
2. Devices forward and respond with ACK_EXPLORER
3. Master builds topology map

Read Object

1. Send CN_CMD_GETOBJ with object ID
2. Receive CN_ACK_GETOBJ with data

Write Object

1. Send CN_CMD_SETOBJ with object ID and data
2. Receive CN_ACK_SETOBJ confirmation

Firmware Update

1. SETMODE → LOADER
2. ERASE flash region
3. WRITE firmware blocks (512 bytes each)
4. SETSIGNATURE with metadata
5. SAVECFG
6. SETMODE → APP

Timing Parameters

Performance Metrics

UART @ 115200 bps

CAN @ 1 Mbps

Error Handling

UART

• CRC errors → discard frame, increment counter
• Framing errors → resync to next delimiter
• Buffer overflow → flush and restart

CAN

• Missing frames → timeout and cleanup
• Pool overflow → emergency cleanup
• Bus-Off → automatic recovery

Code Examples

Initialize Connection (UART)

ULSSerial serial(&rxFifo, &txFifo);
serial.mode(SERIAL_MODE_COBS);
ULSBusInterface interface("UART1", static_did);
interface.open();

Initialize Connection (CAN)

ULSBusConnectionCAN can(&hfdcan1, &device, 
                        &connections, "CAN1", 
                        static_did, cid);
can.setSpeed(1000000);
can.open();

Send Blitz Message

__uls_blitz_msg_rx_raw_measurmet msg;
msg.status = calc_status();
msg.counter = counter++;
msg.aX = (angle_x / 180.0) * 32767;
msg.aY = (angle_y / 180.0) * 32767;
msg.distance = distance_m * 100;

interface->ifSendBLITZ(
    ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT,
    (uint8_t*)&msg, sizeof(msg)
);

Receive Blitz Message

interface->ifclbkBlitzReceived = &onBlitz;

void onBlitz(ULSBusInterface *iface) {
    uint16_t msg_id = iface->ifRxPacket->blitz.msg_id;
    uint8_t *data = iface->ifRxPacket->blitz.data;
    
    switch(msg_id) {
        case ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT:
            process_measurement(data);
            break;
    }
}

Read Object

uint8_t route[] = {0x05};  // DID=5
connection->cnSendGetObject(route, 1, 0x0100);

// In callback
connection->cnclbkObjReceived = &onObjReceived;

System Command

uint8_t route[] = {0x05};
uint32_t key = _ULS_OPERATION_KEY;
connection->cnSendSysSetMode(route, 1, 
                            CN_SYS_MODE_LOADER);

Troubleshooting

Key Definitions

// Operation Key
#define _ULS_OPERATION_KEY 0x24041982

// Buffer Sizes
#define IF_PACKET_SIZE 1324
#define CN_CAN_POOL_SIZE 256
#define CN_CAN_DEV_SIZE 64

// Timeouts
#define IF_NM_DVICE_HB_TIMEOUT 3000
#define IF_NM_PING_HB_TIMEOUT 1000
#define IF_NM_REQUESTID_TIMEOUT 100

Document References

• Overview: ULS-DeCoNet_Protocol_Overview.md
• UART: ULS-DeCoNet_UART_Protocol.md
• CAN: ULS-DeCoNet_CAN_Protocol.md
• Blitz: ULS-DeCoNet_Blitz_Messages.md

Copyright © 2020-2026 UAVLAS
License: LGPL-3.0+
Version: 1.0

Copyright © 2020-2026 UAVLAS <www.uavlas.com>
License: GNU Lesser General Public License v3.0+

4 - ULS-DeCoNet Blitz Messages Specification

ULSDC-PBDS051125 · version 1.0.4 · issued November 13, 2025
The numbered PDF is the controlled copy: download it from the portal.

Introduction

Purpose

The Blitz protocol is a specialized messaging subsystem within ULS-DeCoNet designed for high-frequency transmission of sensor measurement data from ULS positioning systems.

Key Characteristics

• Low Overhead: Fixed 11-byte messages (3-byte header + 8-byte payload)
• High Frequency: Optimized for 100+ Hz update rates
• Real-time: Minimal latency from sensor to network
• Type-safe: Strongly typed message definitions
• Compact: Efficient packing of measurement data

Blitz Protocol Overview

Protocol Stack Position

block-beta
  columns 1
  A["Application Layer\n(Blitz Message Handling)"]
  B["IF Protocol\n(IF_CMD_BLITZ = 0x06)"]
  C["Framing Layer"]

Message Flow

flowchart LR
  Sensor --> Measurement --> BlitzEncode["Blitz Encode"] --> IFLayer["IF Layer"] --> Transport --> Receiver
  BlitzEncode --> MsgId["MSG_ID + Data"] --> BlitzCmd["IF_CMD_BLITZ"] --> Frame["UART/CAN Frame"]

Message Format

IF Layer Packet Structure

packet-beta
title "Blitz IF Layer Packet"
0-7: "CMD 0x06 (1 byte)"
8-15: "SRC_LID (1 byte)"
16-31: "MSG_ID (2 bytes)"
32-95: "DATA (8 bytes)"

Total Size: 11 bytes

Fields:

• CMD: Always 0x06 (IF_CMD_BLITZ)
• SRC_LID: Source device ID
• MSG_ID: Blitz message type identifier (uint16_t, little-endian)
• DATA: Message-specific payload (8 bytes maximum)

Common Data Structure

typedef struct {
    uint8_t src_lid;         // Source logical ID
    uint16_t msg_id;         // Message type ID
    union {
        uint8_t data[8];     // Raw data access
        // Specific message structures
        __uls_blitz_xcg1_rx_raw_measurmet xcg1_rx_raw_measurmet;
        __uls_blitz_msg_rx_raw_measurmet rx_raw_measurmet;
        __uls_blitz_msg_rx_pos_in_tx_frame rx_pos_in_tx_frame;
        __uls_blitz_msg_rx_mrx rx_mrx;
        __uls_blitz_msg_rx_dacs rx_dacs;
    };
} __blitz_common_data_struct;

Message Types

Message Type Summary

XCG1 Raw Measurement (0x0010)

Legacy message for XCopter Generation 1 systems

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;    // Status bits
    uint8_t d;         // Distance in 10 cm increments
    int16_t aX;        // Angle X: [-30000 = -30°, +30000 = +30°]
    int16_t aY;        // Angle Y: [-30000 = -30°, +30000 = +30°]
    int8_t oF;         // Sensor offset Forward (cm)
    int8_t oR;         // Sensor offset Right (cm)
} __uls_blitz_xcg1_rx_raw_measurmet;

Total Size: 8 bytes

Field Descriptions

Angular Conversion

float angle_x_deg = (aX * 30.0f) / 30000.0f;
float angle_y_deg = (aY * 30.0f) / 30000.0f;

Distance Conversion

float distance_m = d * 0.1f;  // d in 10 cm steps

Raw Measurement (0x0011)

Standard raw measurement with full angular range

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;      // Status bits
    uint8_t counter;     // Message counter
    int16_t aX;          // Angle X: [-180° to +180°]
    int16_t aY;          // Angle Y: [-180° to +180°]
    uint16_t distance;   // Distance measurement
} __uls_blitz_msg_rx_raw_measurmet;

Total Size: 8 bytes

Field Descriptions

Angular Conversion

float angle_x_deg = (aX * 180.0f) / 32767.0f;
float angle_y_deg = (aY * 180.0f) / 32767.0f;

Precision: ~0.0055° per LSB

Distance Conversion

float distance_m = distance * 0.01f;  // distance in cm

Position in TX Frame (0x0012)

3D position vector in transmitter coordinate frame

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;    // Status bits
    uint8_t counter;   // Message counter
    int16_t posX;      // X position (cm)
    int16_t posY;      // Y position (cm)
    int16_t posZ;      // Z position (cm)
} __uls_blitz_msg_rx_pos_in_tx_frame;

Total Size: 8 bytes

Field Descriptions

Coordinate System

Transmitter Frame:
         +Z (up)
          |
          |
          +------- +X (forward)
         /
        /
      +Y (right)

Position Conversion

float pos_x_m = posX * 0.01f;  // cm to m
float pos_y_m = posY * 0.01f;
float pos_z_m = posZ * 0.01f;

Range: ±327.68 meters
Resolution: 1 cm

MRX Information (0x0013)

Multi-Receiver Extension data

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;      // Status bits
    uint8_t counter;     // Message counter
    int16_t yaw;         // Yaw angle [-180° to +180°]
    uint16_t distance;   // Distance in cm
} __uls_blitz_msg_rx_mrx;

Total Size: 6 bytes (2 bytes unused in 8-byte payload)

Field Descriptions

Angular Conversion

float yaw_deg = (yaw * 180.0f) / 32767.0f;

Usage

MRX data is calculated from measurements of a secondary receiver, providing:

• Relative yaw orientation
• Distance between receivers
• Enhanced positioning accuracy

DACS Information (0x0014)

Directional Angle Calculation System with continuous yaw tracking

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;         // Status bits
    uint8_t counter;        // Message counter
    int16_t yaw;            // Yaw angle [-180° to +180°]
    uint16_t distance;      // Distance in cm
    int16_t yawContinuous;  // Continuous yaw (±32768°)
} __uls_blitz_msg_rx_dacs;

Total Size: 8 bytes

Field Descriptions

Angular Conversion

Wrapped Yaw:

float yaw_deg = (yaw * 180.0f) / 32767.0f;  // -180 to +180°

Continuous Yaw:

float yaw_continuous_deg = yawContinuous;  // Direct degree value

Usage

DACS provides:

• Standard wrapped yaw for heading
• Continuous yaw for counting full rotations
• Useful for applications requiring rotation tracking beyond ±180°

Example:

Rotation: 450° clockwise
yaw = 90° (wrapped to ±180° range)
yawContinuous = 450°

Ground IMU Measurement (0x0020)

Inertial Measurement Unit data from ground transmitter

Structure

typedef struct __attribute__((packed)) {
    uint8_t status;    // Status bits
    uint8_t counter;   // Message counter
    int16_t roll;      // Roll angle [-180° to +180°]
    int16_t pitch;     // Pitch angle [-180° to +180°]
    int16_t yaw;       // Yaw angle [-180° to +180°]
} __uls_blitz_msg_gimu_data;

Total Size: 8 bytes

Field Descriptions

Angular Conversion

float roll_deg = (roll * 180.0f) / 32767.0f;
float pitch_deg = (pitch * 180.0f) / 32767.0f;
float yaw_deg = (yaw * 180.0f) / 32767.0f;

Precision: ~0.0055° per LSB

Orientation Convention

Euler Angles (Tait-Bryan convention):
  Roll:  Rotation about X-axis (forward)
  Pitch: Rotation about Y-axis (right)
  Yaw:   Rotation about Z-axis (up)

IMU Override (0x0030)

Override IMU data on ground transmitter

Structure

typedef struct __attribute__((packed)) {
    uint8_t control;   // Control bits
    uint8_t counter;   // Message counter
    int16_t roll;      // Override roll [-180° to +180°]
    int16_t pitch;     // Override pitch [-180° to +180°]
    int16_t yaw;       // Override yaw [-180° to +180°]
} __uls_blitz_msg_xx_txc_imu_override;

Total Size: 8 bytes

Field Descriptions

Control Bits

Usage

// Override only yaw
msg.control = (1 << 2);  // SET_YAW
msg.yaw = (45.0f * 32767.0f) / 180.0f;  // 45 degrees
msg.roll = 0;    // Ignored (SET_ROLL not set)
msg.pitch = 0;   // Ignored (SET_PITCH not set)

Purpose:

• External orientation source (e.g., motion capture, GNSS heading)
• Calibration and testing
• Compass-less operation

Magnetometer Override (0x0031)

Override magnetometer data on ground transmitter

Structure

typedef struct __attribute__((packed)) {
    uint8_t control;   // Control bits
    uint8_t counter;   // Message counter
    int16_t mx;        // Magnetic field X component
    int16_t my;        // Magnetic field Y component
    int16_t mz;        // Magnetic field Z component
} __uls_blitz_msg_xx_txc_mag_override;

Total Size: 8 bytes

Field Descriptions

Control Bits

Magnetic Field Conversion

float mx_norm = (mx * 1.0f) / 32767.0f;  // Normalized [-1.0, +1.0]
float my_norm = (my * 1.0f) / 32767.0f;
float mz_norm = (mz * 1.0f) / 32767.0f;

Purpose:

• External magnetometer source
• Magnetic interference compensation
• Indoor operation with external compass

Status Bits

Common Status Flags

Most Blitz messages include a status byte with these flags:

Status Checking

bool check_measurement_valid(uint8_t status) {
    // Check minimum required flags
    if (!(status & (1 << 0))) return false;  // No carrier
    if (!(status & (1 << 1))) return false;  // Poor signal quality
    if (!(status & (1 << 2))) return false;  // No position
    return true;
}

bool has_velocity(uint8_t status) {
    return (status & (1 << 3)) != 0;
}

bool has_mrx_data(uint8_t status) {
    return ((status & (1 << 5)) != 0) && ((status & (1 << 6)) != 0);
}

Data Encoding

Integer Scaling

Angular Data (±180° range):

int16_t_value = (angle_degrees / 180.0) * 32767.0
angle_degrees = (int16_t_value / 32767.0) * 180.0

Position Data (cm):

int16_t_value = position_cm
position_m = int16_t_value * 0.01

Distance Data (cm):

uint16_t_value = distance_cm
distance_m = uint16_t_value * 0.01

Byte Order

All multi-byte fields use little-endian byte order

Example (int16_t = 0x1234):

Memory layout: [0x34, 0x12]
                 LSB   MSB

Packing

All structures use __attribute__((packed)) to ensure:

• No padding bytes inserted by compiler
• Exact memory layout as defined
• Network transmission compatibility

Usage Examples

Sending Blitz Message

// Prepare raw measurement
__uls_blitz_msg_rx_raw_measurmet msg;

msg.status = calculate_status_bits();
msg.counter = packet_counter++;
msg.aX = (int16_t)((angle_x_deg / 180.0f) * 32767.0f);
msg.aY = (int16_t)((angle_y_deg / 180.0f) * 32767.0f);
msg.distance = (uint16_t)(distance_m * 100.0f);  // m to cm

// Send via interface
interface->ifSendBLITZ(
    ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT,
    (uint8_t*)&msg,
    sizeof(msg)
);

Receiving Blitz Message

// Set callback
interface->ifclbkBlitzReceived = &onBlitzReceived;

void onBlitzReceived(ULSBusInterface *iface) {
    uint16_t msg_id = iface->ifRxPacket->blitz.msg_id;
    uint8_t *data = iface->ifRxPacket->blitz.data;
    
    switch(msg_id) {
        case ULS_BLITZ_MSG_ID_RX_RAW_MEASURMENT: {
            __uls_blitz_msg_rx_raw_measurmet *msg =
                (__uls_blitz_msg_rx_raw_measurmet*)data;
            
            // Check status
            if (!(msg->status & 0x07)) break;  // Check flags 0,1,2
            
            // Extract data
            float ax = (msg->aX / 32767.0f) * 180.0f;
            float ay = (msg->aY / 32767.0f) * 180.0f;
            float dist = msg->distance * 0.01f;
            
            // Process measurement
            process_measurement(ax, ay, dist);
            break;
        }
        
        case ULS_BLITZ_MSG_ID_GIMU_MEASUREMENT: {
            __uls_blitz_msg_gimu_data *msg =
                (__uls_blitz_msg_gimu_data*)data;
            
            float roll = (msg->roll / 32767.0f) * 180.0f;
            float pitch = (msg->pitch / 32767.0f) * 180.0f;
            float yaw = (msg->yaw / 32767.0f) * 180.0f;
            
            update_orientation(roll, pitch, yaw);
            break;
        }
        
        // Handle other message types...
    }
}

IMU Override Example

// Override yaw angle from external source
void send_yaw_override(float yaw_deg) {
    __uls_blitz_msg_xx_txc_imu_override msg;
    
    msg.control = (1 << 2);  // Enable yaw override only
    msg.counter = counter++;
    msg.roll = 0;
    msg.pitch = 0;
    msg.yaw = (int16_t)((yaw_deg / 180.0f) * 32767.0f);
    
    interface->ifSendBLITZ(
        ULS_BLITZ_MSG_ID_XX_TXC_IMU_OVERRIDE,
        (uint8_t*)&msg,
        sizeof(msg)
    );
}

Performance Considerations

Update Rates

Typical Rates:

• Raw measurements: 100-200 Hz
• Position data: 100 Hz
• IMU data: 100-200 Hz
• MRX data: 50-100 Hz

Bandwidth Usage

Per Message:

• UART (COBS mode): ~13 bytes (11 data + 2 overhead)
• CAN: 1 frame (11 bytes in 8-byte frame + header)

Example Load (100 Hz, UART @ 115200 bps):

Bandwidth = 100 Hz × 13 bytes × 8 bits = 10.4 kbps
Utilization = 10.4 / 115.2 = 9%

Latency

End-to-end latency:

• Sensor → Encoding: <1 ms
• Transmission: 0.1-1 ms (depends on transport)
• Reception → Callback: <1 ms
• Total: 1-3 ms typical

Copyright © 2020-2026 UAVLAS <www.uavlas.com>
License: GNU Lesser General Public License v3.0+

5 - ULS-DeCoNet CAN Transport Specification

ULSDC-PBDS021125 · version 1.0.5 · issued November 13, 2025
The numbered PDF is the controlled copy: download it from the portal.

Introduction

Purpose

This document specifies how ULS-DeCoNet protocol messages are transmitted over CAN bus, including frame structure, multi-frame messaging, and error handling specific to the CAN transport.

CAN Bus Advantages

Why CAN for ULS-DeCoNet:

• Multi-master: Any device can initiate communication
• Robust: Built-in error detection and retry
• Priority-based: Critical messages transmitted first
• Collision-free: Hardware arbitration prevents collisions
• Long-distance: Up to 40m @ 1Mbps, longer at lower speeds
• Industrial proven: Widely used in automotive and industrial applications

Scope

This specification covers:

• CAN physical layer configuration
• Application-level frame structure
• Multi-frame message segmentation and reassembly
• Frame pool management
• Priority schemes
• Error recovery mechanisms

Physical Layer

CAN Standards Support

Classical CAN:

• Standard identifiers (11-bit)
• Data payload: 0-8 bytes
• Bit rates: Up to 1 Mbps
• Fully supported

CAN-FD (Flexible Data-rate):

• Standard identifiers (11-bit)
• Extended data payload: Up to 64 bytes
• Arbitration phase: Up to 1 Mbps
• Data phase: Up to 5 Mbps
• Supported via FDCAN peripheral

ULS-DeCoNet Implementation:

• Uses standard 11-bit identifiers
• Classical CAN: 8-byte payload maximum
• CAN-FD: Can utilize extended payload for efficiency
• Current implementation optimized for 8-byte frames

Physical Specifications

Bus Configuration:

Device 1 -----+
              |
Device 2 -----+---- CAN_H -------- 120Ω
              |    CAN_L
Device 3 -----+
              |
Device N -----+
              |
             120Ω

Electrical Specifications:

• Differential voltage: 2V typical
• Termination: 120Ω at both ends
• Max stub length: 30 cm recommended
• Common mode range: -2V to +7V
• Max nodes: Typically 30-64 (driver dependent)

Recommended Bit Rates:

CAN Identifier Structure

Standard 11-bit Identifier:

packet-beta
title "CAN 11-bit Identifier"
0-10: "Message ID (11 bits)"

ULS-DeCoNet Usage:

• Identifiers determined by implementation
• Lower identifiers = higher priority
• Can use identifier for addressing or priority

Example Identifier Scheme:

Bits [10:8] - Message priority (0=highest)
Bits [7:0]  - Source device address

CAN Frame Structure

Hardware CAN Frame

Standard CAN Frame:

packet-beta
title "Standard CAN Frame"
0-0: "SOF"
1-11: "ID (11b)"
12-12: "RTR"
13-13: "IDE"
14-17: "DLC (4b)"
18-81: "DATA (0-8 bytes)"
82-97: "CRC (16b)"
98-99: "ACK (2b)"

• Hardware handles SOF, CRC, ACK automatically
• Application specifies ID, DLC, DATA
• RTR and IDE typically 0 for ULS-DeCoNet

ULS-DeCoNet Application Frame

Single-Frame Structure

For messages that fit in one CAN frame (≤10 bytes payload):

packet-beta
title "Single-Frame CAN Data Field (8 bytes)"
0-7: "CMD (Byte 0)"
8-15: "DID (Byte 1)"
16-63: "PAYLOAD (Bytes 2-7)"

Fields:

• Byte 0 (CMD): Command code from IF or CN layer
• Byte 1 (DID): Source Device ID
  • Bits 5-0: Device ID (0-63)
  • Bits 7-6: Connection ID (0-3)
• Bytes 2-7: Command-specific payload (up to 6 bytes)

Characteristics:

• Total overhead: 2 bytes
• Usable payload: 6 bytes per frame
• Transmitted as single atomic CAN frame

Multi-Frame Structure

For messages >10 bytes:

packet-beta
title "Multi-Frame CAN Data Field (8 bytes)"
0-7: "CMD (Byte 0)"
8-15: "DID (Byte 1)"
16-23: "FRMCTL (Byte 2)"
24-63: "PAYLOAD 5 bytes (Bytes 3-7)"

packet-beta
title "FRMCTL Byte"
0-0: "END"
1-7: "FRAME NUMBER 0-127 (bits 6-0)"

• CMD: Command code (same across all frames)
• DID: Source Device ID (same across all frames)
• FRMCTL: Frame control byte
  • Bit 7: End-of-message flag
  • Bits 6-0: Frame sequence number (0-127)
• PAYLOAD: Data segment (5 bytes per frame)

Frame Numbering:

Frame 0:  FRMCTL = 0x00, payload bytes 0-4
Frame 1:  FRMCTL = 0x01, payload bytes 5-9
Frame 2:  FRMCTL = 0x02, payload bytes 10-14
...
Frame N:  FRMCTL = 0x80 | N, last payload bytes

Single-Frame Messages

Network Management Messages

Heartbeat (HB)

packet-beta
title "Heartbeat (CMD=0x01)"
0-7: "CMD 0x01"
8-15: "DID"
16-47: "UID0 (4 bytes)"

Usage: Periodic presence announcement
Payload: Device unique ID (32 bits)
Frequency: Every 1000ms

Request ID

packet-beta
title "Request ID (CMD=0x03)"
0-7: "CMD 0x03"
8-15: "DID 0x3F"
16-47: "KEY (4 bytes)"

Usage: Request ID assignment
Payload: Random key for identification
Sent by: Uninitialized devices (DID=63)

Set ID

packet-beta
title "Set ID (CMD=0x04)"
0-7: "CMD 0x04"
8-15: "DID 0x00 (Master)"
16-23: "NEWID (1 byte)"
24-55: "KEY (4 bytes)"

Usage: Master assigns ID to device
Sent by: Master device (DID=0)
Payload: New ID + matching key

Blitz Messages

packet-beta
title "Blitz Message (CMD=0x06)"
0-7: "CMD 0x06"
8-15: "DID"
16-31: "MSG_ID (2 bytes)"
32-63: "DATA (4 bytes)"

Usage: High-frequency sensor data
Payload:

• MSG_ID (2 bytes): Blitz message type
• DATA (4 bytes): Message-specific data

Note: Blitz messages use DLC=7 or 8 depending on data size

Multi-Frame Protocol

Overview

When Multi-Frame is Used:

• Messages >10 bytes total length
• CN protocol commands (routing, object access)
• System commands with large payloads
• Firmware update data

Key Concept:

• Large message split into multiple CAN frames
• Each frame carries 5 bytes of payload (with 3-byte header)
• Frames can arrive out of order
• Receiver assembles from frame pool

Transmission Algorithm

_io_op_result sendPacket() {
    uint8_t framecntr = 0;
    uint8_t *pxPld = ifTxPacket->pld;
    
    // Check if single-frame message
    if (ifTxPacket->cmd < 16) {
        if (ifTxLen > 12) return IO_ERROR;
        
        // Single-frame transmission
        _can_mail mail;
        mail.packet.raw.data[0] = ifTxPacket->cmd;
        mail.packet.raw.data[1] = ifTxPacket->src_lid;
        memcpy(&mail.packet.raw.data[2], ifTxPacket->pld, ifTxLen - 2);
        mail.len = (ifTxLen < 4) ? 0 : ifTxLen - 4;
        
        send_can_frame(&mail, CAN_PRIORITY_HIGH);
        return IO_OK;
    }
    
    // Multi-frame transmission
    ifTxLen -= 2;  // Subtract CMD and DID
    
    while (ifTxLen > 0) {
        _can_mail mail;
        mail.packet.raw.data[0] = ifTxPacket->cmd;
        mail.packet.raw.data[1] = ifTxPacket->src_lid;
        mail.packet.raw.data[2] = framecntr++;
        
        // Copy up to 5 bytes payload
        uint32_t len = (ifTxLen > 5) ? 5 : ifTxLen;
        for (uint32_t i = 0; i < len; i++) {
            mail.packet.raw.data[3 + i] = *pxPld++;
            ifTxLen--;
        }
        
        // Mark last frame
        if (ifTxLen == 0) {
            mail.packet.raw.data[2] |= 0x80;
        }
        
        mail.len = len + 2;  // Data length code
        
        if (!send_can_frame(&mail, CAN_PRIORITY_NORMAL)) {
            return IO_BUFFER_FULL;
        }
    }
    
    return IO_OK;
}

Reception Algorithm

_io_op_result receivePacket() {
    _can_mail mail;
    
    while (read_can_frame(&mail)) {
        uint8_t did = mail.packet.raw.data[1] & 0x3F;
        uint8_t cmd = mail.packet.raw.data[0];
        
        // Update device timeout
        _devs[did].timeout = CN_CAN_DEV_TIMEOUT;
        
        // Single-frame message
        if (cmd < 16) {
            ifRxPacket->cmd = cmd;
            ifRxPacket->src_lid = did;
            memcpy(ifRxPacket->pld, &mail.packet.raw.data[2], mail.len + 2);
            ifRxLen = 4 + mail.len;
            return IO_OK;
        }
        
        // Multi-frame message
        uint8_t frame_num = mail.packet.raw.data[2] & 0x7F;
        bool is_last = (mail.packet.raw.data[2] & 0x80) != 0;
        
        // Store frame in pool
        store_frame_in_pool(did, frame_num, &mail);
        
        if (is_last) {
            // Attempt to assemble message
            return assemble_message(did, frame_num);
        }
    }
    
    return IO_NO_DATA;
}

Message Assembly

_io_op_result assemble_message(uint8_t did, uint8_t last_frame) {
    ifRxPacket->cmd = get_cmd_from_pool(did);
    ifRxPacket->src_lid = did;
    
    uint32_t expected_frames = last_frame + 1;
    uint32_t expected_len = last_frame * 5 + get_last_frame_len(did);
    
    ifRxLen = 2;  // CMD + DID
    
    // Verify all frames present
    for (uint32_t frame = 0; frame <= last_frame; frame++) {
        if (!frame_exists_in_pool(did, frame)) {
            // Missing frame
            log_missing_frames(did, expected_frames);
            clean_pool(did);
            return IO_ERROR;
        }
        
        // Copy frame payload
        copy_frame_payload(did, frame, &ifRxPacket->pld[frame * 5]);
        ifRxLen += get_frame_payload_len(did, frame);
    }
    
    // Verify length
    if (ifRxLen != expected_len + 2) {
        clean_pool(did);
        return IO_ERROR;
    }
    
    // Success - clean up pool
    clean_pool(did);
    return IO_OK;
}

Multi-Frame Example

Scenario: Send 22-byte message from device ID=5

Calculation:

Payload: 22 bytes
Frames needed: ceil(22 / 5) = 5 frames

Frame 0: bytes 0-4   (5 bytes)
Frame 1: bytes 5-9   (5 bytes)
Frame 2: bytes 10-14 (5 bytes)
Frame 3: bytes 15-19 (5 bytes)
Frame 4: bytes 20-21 (2 bytes, last frame)

CAN Frames Transmitted:

Frame 0:
[CMD][0x05][0x00][data[0]][data[1]][data[2]][data[3]][data[4]]

Frame 1:
[CMD][0x05][0x01][data[5]][data[6]][data[7]][data[8]][data[9]]

Frame 2:
[CMD][0x05][0x02][data[10]][data[11]][data[12]][data[13]][data[14]]

Frame 3:
[CMD][0x05][0x03][data[15]][data[16]][data[17]][data[18]][data[19]]

Frame 4:
[CMD][0x05][0x84][data[20]][data[21]][PAD][PAD][PAD]
          ^^^^
          0x80 | 0x04 = Last frame, number 4

Frame Pool Management

Pool Architecture

Purpose: Store received frames until complete message assembled

Pool Structure:

#define CN_CAN_POOL_SIZE 256  // Frame storage slots
#define CN_CAN_DEV_SIZE 64    // Device tracking entries

typedef struct {
    uint32_t timeout;
    uint32_t start;
    uint32_t size;
    uint32_t len;
} _cn_can_dev;

_can_mail _pool[CN_CAN_POOL_SIZE];
_cn_can_dev _devs[CN_CAN_DEV_SIZE];

Pool Operations

Frame Storage

bool store_frame_in_pool(uint8_t did, uint8_t frame_num, _can_mail *mail) {
    // Find free slot
    uint32_t slot = allocate_pool_slot();
    if (slot == INVALID_SLOT) {
        // Pool full - trigger cleanup
        clean_expired_frames();
        slot = allocate_pool_slot();
        if (slot == INVALID_SLOT) {
            return false;  // Still full
        }
    }
    
    // Store frame
    memcpy(&_pool[slot], mail, sizeof(_can_mail));
    
    // Mark slot as used
    _pool[slot].packet.raw.data[0] = mail->packet.raw.data[0];
    
    return true;
}

Slot Allocation

uint32_t allocate_pool_slot() {
    for (uint32_t i = 0; i < CN_CAN_POOL_SIZE; i++) {
        _iempty++;
        if (_iempty >= CN_CAN_POOL_SIZE) {
            _iempty = 0;
        }
        
        // Check if slot is empty (marked with 0xFF)
        if (_pool[_iempty].packet.raw.data[0] == 0xFF) {
            return _iempty;
        }
    }
    return INVALID_SLOT;
}

Timeout Management

Device Timeout:

#define CN_CAN_DEV_TIMEOUT (CN_CAN_POOL_SIZE / 2)  // 128 frame times

Timeout Process:

void task(uint32_t dtms) {
    // Decrement all device timeouts
    for (uint32_t i = 0; i < CN_CAN_DEV_SIZE; i++) {
        if (_devs[i].timeout > 0) {
            _devs[i].timeout--;
        }
    }
    
    // On device timeout, clean its frames
    for (uint32_t i = 0; i < CN_CAN_DEV_SIZE; i++) {
        if (_devs[i].timeout == 0 && _devs[i].size > 0) {
            clean_device_frames(i);
        }
    }
}

Pool Cleanup

Clean Expired Frames

void clean_expired_frames() {
    for (uint32_t i = 0; i < CN_CAN_POOL_SIZE; i++) {
        if (_pool[i].packet.raw.data[0] == 0xFF) {
            continue;  // Already free
        }
        
        uint8_t did = _pool[i].packet.raw.data[1] & 0x3F;
        
        if (_devs[did].timeout == 0) {
            // Device timed out - free frame
            _pool[i].packet.raw.data[0] = 0xFF;
        }
    }
}

Clean Device Frames

uint32_t clean_device_frames(uint8_t did) {
    uint32_t count = 0;
    
    for (uint32_t i = 0; i < CN_CAN_POOL_SIZE; i++) {
        if (_pool[i].packet.raw.data[0] == 0xFF) {
            continue;
        }
        
        uint8_t frame_did = _pool[i].packet.raw.data[1] & 0x3F;
        
        if (frame_did == did) {
            _pool[i].packet.raw.data[0] = 0xFF;
            count++;
        }
    }
    
    return count;
}

Pool Monitoring

uint32_t get_pool_free_count() {
    uint32_t count = 0;
    for (uint32_t i = 0; i < CN_CAN_POOL_SIZE; i++) {
        if (_pool[i].packet.raw.data[0] == 0xFF) {
            count++;
        }
    }
    return count;
}

void check_pool_health() {
    uint32_t free = get_pool_free_count();
    
    if (free < CN_CAN_POOL_SIZE / 4) {
        // Less than 25% free - warning
        log_warning("CAN pool low: %d free", free);
    }
    
    if (free == 0) {
        // Pool exhausted - critical
        log_error("CAN pool exhausted!");
        emergency_cleanup();
    }
}

Priority and Arbitration

CAN Arbitration

Hardware Arbitration:

• Lower CAN ID wins arbitration
• Non-destructive (losing node automatically retries)
• Deterministic priority

Message Priority Levels:

typedef enum {
    _CAN_MAIL_PRIORITY_HI = 0,      // Critical messages
    _CAN_MAIL_PRIORITY_NORMAL = 1,   // Regular data
    _CAN_MAIL_PRIORITY_LOW = 2       // Background tasks
} _can_mail_priority;

Priority Assignment

High Priority:

• Network management messages (HB, REQUEST_ID, SET_ID)
• Safety-critical commands
• Single-frame short messages

Normal Priority:

• Multi-frame data transfers
• Object access commands
• System commands

Low Priority:

• Diagnostic data
• Non-critical telemetry
• Bulk data transfers

Identifier Allocation Strategy

Option 1: Source Address Based:

CAN ID = Source Device ID
  - Simple
  - Natural priority (lower DID = higher priority)
  - Master (DID=0) always highest priority

Option 2: Priority + Source:

CAN ID[10:8] = Priority (0=high, 7=low)
CAN ID[7:0]  = Source Device ID

Example:
  0x000-0x0FF: Highest priority messages
  0x100-0x1FF: Normal priority
  0x200-0x7FF: Lower priorities

Performance Characteristics

Throughput Analysis

Single-Frame Messages:

CAN @ 1 Mbps:
  Frame overhead: ~44 bits
  Data: 8 bytes = 64 bits
  Total: 108 bits
  Time per frame: 108 µs
  Max throughput: ~9260 frames/sec

Multi-Frame Messages:

Payload per frame: 5 bytes
Effective data rate: 5/8 = 62.5% efficiency
Net throughput @ 1 Mbps: ~625 kbps for data

Example Transfer Rates:

Latency Analysis

Best Case (single frame, no contention):

Latency = CAN_frame_time
        = 108 µs @ 1 Mbps

Typical Case (multi-frame, some contention):

Latency = (N_frames × CAN_frame_time) + queuing_delay
        ≈ (N_frames × 108 µs) + (0-500 µs)

Worst Case (high bus load):

Latency = (N_frames × CAN_frame_time) + max_retry_delay
        Can be significantly higher during bus saturation

Bus Utilization

Recommended Maximum Load: 70-80%
Critical Threshold: 90%

Load Calculation:

Load = (Messages_per_second × Bits_per_message) / Bus_bitrate

Example:
  100 msgs/sec × 108 bits/msg = 10,800 bps
  Load @ 1 Mbps = 1.08%

Error Handling

CAN Hardware Errors

CAN Controller Error States:

stateDiagram-v2
  [*] --> ErrorActive
  ErrorActive: Error Active\n(Normal operation)
  ErrorPassive: Error Passive\n(Reduced priority)
  BusOff: Bus Off\n(Disconnected)

  ErrorActive --> ErrorPassive: TEC/REC > 127
  ErrorPassive --> BusOff: TEC > 255
  BusOff --> ErrorActive: Recovery (128 × 11 recessive bits)

• Automatic retransmission
• Error frames generation
• Automatic recovery from Bus Off (implementation-dependent)

Application-Level Errors

Missing Frames

Detection:

// Check for missing frames in sequence
for (uint32_t i = 0; i <= last_frame; i++) {
    if (!frame_exists(did, i)) {
        log_error("Missing frame %d from device %d", i, did);
        _missedFrames[i] = 1;
    }
}

Recovery:

• Discard incomplete message
• Clean pool entries
• Higher layer handles timeout/retransmission

Pool Overflow

Detection:

if (allocate_pool_slot() == INVALID_SLOT) {
    log_error("CAN pool exhausted!");
    return IO_BUFFER_FULL;
}

Recovery:

1. Trigger emergency cleanup
2. Remove oldest/timed-out frames
3. If still full, reject new frames
4. Report error to higher layer

Timeout Errors

Device Timeout:

void handle_device_timeout(uint8_t did) {
    log_warning("Device %d timeout", did);
    
    // Clean all frames from device
    uint32_t cleaned = clean_device_frames(did);
    log_info("Cleaned %d frames from device %d", cleaned, did);
    
    // Notify higher layer
    notify_device_disconnected(did);
}

Error Statistics

typedef struct {
    uint32_t tx_ok;
    uint32_t tx_errors;
    uint32_t rx_ok;
    uint32_t rx_errors;
    uint32_t missing_frames;
    uint32_t pool_overflows;
    uint32_t device_timeouts;
} can_stats_t;

Implementation Details

ULSBusConnectionCAN Class

class ULSBusConnectionCAN : public ULSBusConnection, DrvCAN {
public:
    ULSBusConnectionCAN(_drvcan_handle_td* handler, 
                       ULSDBase* dev,
                       ULSBusConnectionsList* connections, 
                       const char* name, 
                       uint8_t id, 
                       uint8_t cid);
    
    // Configuration
    bool open() override;
    void setSpeed(uint32_t speed);
    
    // Task processing
    void task(uint32_t dtms) override;
    
    // Frame I/O
    _io_op_result sendPacket() override;
    _io_op_result receivePacket() override;
    
    // Statistics
    uint32_t poolSize();
    
private:
    _can_mail _pool[CN_CAN_POOL_SIZE];
    _cn_can_dev _devs[CN_CAN_DEV_SIZE];
    uint32_t _iempty;
    uint32_t _missedFrames[128];
    
    bool allocate();
    void clean();
    uint32_t clean(uint8_t id);
    void setTimeouts();
};