# ULS-DeCoNet Quick Reference Guide

> Reference for developers and integrators of ULS-DeCoNet — the ULS Devices Connection Network protocol for UART and CAN.

---

Site [llms.txt](/llms.txt)

---

> **ULSDC-PBDS041125** · version 1.0.0 · issued November 13, 2025  
> The numbered PDF is the controlled copy: [download it from the portal](https://downloads.uavlas.com).

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

| Component | Size | Range | Description |
|-----------|------|-------|-------------|
| Device ID (DID) | 6 bits | 0-63 | Local device address |
| Connection ID (CID) | 2 bits | 0-3 | Interface identifier |
| CNRID | 8 bits | 0-255 | Combined routing ID: `(CID<<6)\|DID` |

**Special Addresses**:
- **0**: Master device
- **63**: Broadcast / Uninitialized
- **1-62**: Regular devices

---

## UART Framing Modes

| Mode | Delimiter | CRC | Overhead | Best For |
|------|-----------|-----|----------|----------|
| RAW | None | None | 0% | Custom protocols |
| ESC | 0x55 0x01/0x03 | CRC-16 | ~15-25% | General purpose |
| ESC_SIMPLE | 0x55 0x01/0x03 | 8-bit sum | ~12-20% | Low-power |
| COBS | 0x00 | CRC-16 | ~0.4-2% | Binary data |

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

| Code | Name | Description |
|------|------|-------------|
| 0x00 | SYS | System command |
| 0x01 | NM_HB | Heartbeat (1000ms interval) |
| 0x02 | NM_GET_STATUS | Get device status |
| 0x03 | NM_REQUEST_ID | Request ID allocation |
| 0x04 | NM_SET_ID | Assign device ID |
| 0x05 | NM_RESET_ID | Reset device ID |
| 0x06 | BLITZ | Sensor data message |

**Packet Structure**:
```
[CMD][SRC_LID][PAYLOAD]
```

---

## CN Layer Commands

| Code | Name | Description |
|------|------|-------------|
| 0x10 | EXPLORER | Network discovery |
| 0x11 | ACK_EXPLORER | Discovery response |
| 0x12 | SYS | System operation |
| 0x13 | ACK_SYS | System response |
| 0x14 | GETOBJ | Read object |
| 0x15 | ACK_GETOBJ | Object data response |
| 0x16 | SETOBJ | Write object |
| 0x17 | ACK_SETOBJ | Write acknowledgment |

**Packet Structure**:
```
[CMD][SRC_DID][HOP][ROUTE...][PAYLOAD]

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

---

## System Sub-Commands

| Code | Name | Description |
|------|------|-------------|
| 0 | PING | Device ping |
| 1 | SETMODE | Set APP/LOADER mode |
| 2 | ERASE | Erase flash memory |
| 3 | WRITE | Write flash memory |
| 4 | SETSIGNATURE | Set firmware signature |
| 5 | SAVECFG | Save configuration |

**Result Codes**:
- 0: UNDEFINED
- 1: OK
- 2: ERROR
- 3: WRONGKEY

---

## Blitz Messages

### Message Types

| ID | Name | Size | Description |
|----|------|------|-------------|
| 0x0010 | XCG1_RAW | 8B | Legacy ±30° measurement |
| 0x0011 | RAW_MEASURMENT | 8B | ±180° measurement |
| 0x0012 | POS_TX_FRAME | 8B | 3D position (cm) |
| 0x0013 | MRX | 6B | Multi-receiver data |
| 0x0014 | DACS | 8B | Continuous yaw |
| 0x0020 | GIMU | 8B | Ground IMU data |
| 0x0030 | IMU_OVERRIDE | 8B | Override IMU |
| 0x0031 | MAG_OVERRIDE | 8B | Override magnetometer |

### Status Bits

| Bit | Flag | Description |
|-----|------|-------------|
| 0 | CARRIER_OK | IR signal present |
| 1 | SQ_OK | Signal quality OK |
| 2 | POS_OK | Position valid |
| 3 | VEL_OK | Velocity valid |
| 4 | GU_IMU_OK | Ground IMU OK |
| 5 | MRX_OK | MRX received |
| 6 | MRXDATA_OK | MRX data valid |

### Data Encoding

**Angles (±180°)**:
```c
int16_t = (degrees / 180.0) * 32767.0
degrees = (int16_t / 32767.0) * 180.0
```

**Position/Distance (cm)**:
```c
value_cm = int16_t or uint16_t
value_m = value_cm * 0.01
```

---

## Object Permissions

| Value | Name | Read | Write |
|-------|------|------|-------|
| 0 | READONLY | ✓ | ✗ |
| 1 | WRITEONLY | ✗ | ✓ |
| 2 | READWRITE | ✓ | ✓ |
| 3 | PROTECTED | ✓ | ✓* |
| 4 | CONFIG | ✓ | ✓* |
| 5 | SYSCONFIG | ✓ | ✓* |
| 6 | ADMIN | ✓ | ✓* |

*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

| Parameter | Value | Description |
|-----------|-------|-------------|
| HB_INTERVAL | 1000 ms | Heartbeat send interval |
| DEVICE_TIMEOUT | 3000 ms | Device disconnection timeout |
| REQUEST_ID_INTERVAL | 100 ms | ID request interval |
| REQUEST_ID_RETRIES | 5 | Max ID request attempts |
| CAN_DEV_TIMEOUT | 128 frames | CAN multi-frame timeout |
| CAN_POOL_SIZE | 256 slots | CAN frame buffer pool |

---

## Performance Metrics

### UART @ 115200 bps

| Mode | Throughput | Latency |
|------|------------|---------|
| RAW | 11.5 KB/s | ~0 ms |
| ESC | 9.6 KB/s | ~0.17 ms |
| COBS | 11.3 KB/s | ~0.09 ms |

### CAN @ 1 Mbps

| Message | Frames | Time | Throughput |
|---------|--------|------|------------|
| 10 bytes | 1 | 108 µs | 92.6 KB/s |
| 256 bytes | 52 | 5.6 ms | 45.6 KB/s |

---

## 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)
```cpp
ULSSerial serial(&rxFifo, &txFifo);
serial.mode(SERIAL_MODE_COBS);
ULSBusInterface interface("UART1", static_did);
interface.open();
```

### Initialize Connection (CAN)
```cpp
ULSBusConnectionCAN can(&hfdcan1, &device, 
                        &connections, "CAN1", 
                        static_did, cid);
can.setSpeed(1000000);
can.open();
```

### Send Blitz Message
```cpp
__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
```cpp
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
```cpp
uint8_t route[] = {0x05};  // DID=5
connection->cnSendGetObject(route, 1, 0x0100);

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

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

---

## Troubleshooting

| Issue | Check | Solution |
|-------|-------|----------|
| No communication | Baud rate, wiring | Match settings, check connections |
| CRC errors | Noise, cable quality | Add shielding, lower baud rate |
| Device timeout | HB interval | Check network connectivity |
| Pool overflow | Traffic load | Increase pool size, reduce rate |
| Missing frames | Bus load | Reduce message rate |

---

## Key Definitions

```cpp
// 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+

---