deterix 0.1.4

Deterministic network emulator with microsecond timing precision
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# Deterix: Deterministic Network Emulator with Microsecond Timing Precision


Deterix is a lightweight network emulator written in Rust for building distributed applications that require precise timing control. It provides time-slotted communication with <1µs jitter on COTS hardware running Linux with PREEMPT_RT patch.

## Features


- Time-slotted communication (TDMA)
- Microsecond timing precision (<1µs jitter)
- No GC interruptions
- Zero-copy packet handling
- Distributed architecture

## Network Architecture


### Overview

The network operates on a Time Division Multiple Access (TDMA) protocol with Node 0 serving as the network orchestrator. Key architectural features include:
- Distributed time synchronization with <1µs precision
- Deterministic slot-based communication
- Dynamic network formation and management

### Slot Structure


```
|<------------------------ SLOTFRAME (8 slots) ------------------------>|
+--------+--------+--------+--------+--------+--------+--------+--------+
| Slot 0 | Slot 1 | Slot 2 | Slot 3 | Slot 4 | Slot 5 | Slot 6 | Slot 7 |
| IDLE   | DEDIC  | DEDIC  | DEDIC  | SHARED | SHARED | SHARED | SHARED |
| -/-    | 1/2    | 2/3    | 3/1    | */0    | */0    | 0/*    | */0    |
+--------+--------+--------+--------+--------+--------+--------+--------+


|<----------------------------- Single Slot ----------------------------->|
+-------+-----------------------------------+---------------------+-------+
| CLEAR |               TX/RX               |         ACK         | GUARD |
|  10%  |                50%                |         30%         |  10%  |
+-------+-----------------------------------+---------------------+-------+
```

Example transmission-slot chart showing two nodes join and synchronize with orchestrator and send 10 data packets in their dedicate slots.

![](./slot_chart/chart_1.png)

### Time Synchronization

- **Node 0 (Orchestrator)**
  - Provides network-wide time reference using system clock
  - Manages slot timing and synchronization
  - Broadcasts periodic sync messages

- **Other Nodes**
  - Maintain synchronized local clocks
  - Update timing based on sync messages
  - Calculate slot boundaries locally

## Network Operations


### Network Formation

1. **Initialization Phase**
   - Node 0 starts as orchestrator
   - Dedicated join slots are reserved in each slotframe
   - New nodes begin in unsynchronized state

2. **Join Process**
   ```
   New Node                  Node 0 (Orchestrator)
      |                              |
      |------ Join Request --------->| (in shared slot)
      |                              | - Records node and add schedule
      |                              | - Prepares timing info
      |<----- Join Response ---------|
      |                              |
      |- Synchronize local clock     |
      |- Start normal operation      |
   ```

### Communication Protocol

1. **Slot Assignment**
   - Deterministic sender/receiver pairs per slot
   - Scheduled transmission windows
   - Guard bands prevent overlap

2. **Transmission Process**
   - Reliable delivery with ACK mechanism
   - Automatic retransmission
   - Sequence number tracking

### Implementation Details

- **Core Components**
  - TX/RX Queue Management
  - Slot Ticker System
  - Zero-copy Packet Pool
  - RT Thread Scheduling

- **Performance Features**
  - Thread affinity optimization
  - RT scheduler prioritization
  - Efficient buffer management
  - Microsecond-precision timing


## LICENSE


GPL-3.0