|
1 | | -# µMesh |
| 1 | +# µMesh (uMesh) |
2 | 2 |
|
3 | | -> **Lightweight open mesh protocol over raw 802.11 for ESP32.** |
4 | | -> No router. No infrastructure. No proprietary dependencies. |
| 3 | +Strict documentation policy: every important claim is either verified by repository contents and/or commands executed in this run, explicitly marked **NOT VERIFIED**, or removed. |
5 | 4 |
|
6 | | -[](#) |
7 | | -[](#) |
8 | | -[](#) |
9 | | -[](#) |
10 | | -[](https://github.com/Vanderhell/uMesh/actions/workflows/ci.yml) |
| 5 | +## Status (this run) |
11 | 6 |
|
12 | | ---- |
| 7 | +**Verified by test execution (Windows / MSVC / CMake, POSIX port):** |
| 8 | +- CMake configure/build succeeded for `-DUMESH_PORT=posix -DUMESH_BUILD_TESTS=ON` |
| 9 | +- `ctest` ran **13 tests** and reported **100% pass (13/13)** |
| 10 | + Evidence: `VERIFICATION.md` |
13 | 11 |
|
14 | | -## What is µMesh? |
| 12 | +**CI (configuration only):** |
| 13 | +- GitHub Actions workflow exists for Ubuntu + Windows POSIX builds: `.github/workflows/ci.yml` |
| 14 | + NOT VERIFIED: whether CI is currently passing on GitHub. |
15 | 15 |
|
16 | | -µMesh is a complete **network protocol stack** built on top of raw IEEE 802.11 frames on ESP32. It uses the WiFi hardware — antenna, radio chip — but **bypasses the entire WiFi protocol stack.** No router, no association, no infrastructure. |
| 16 | +## What is implemented (code-visible) |
17 | 17 |
|
18 | | -Result: peer-to-peer and mesh communication between ESP32 devices anywhere, instantly, without any network configuration. |
| 18 | +µMesh is a C99 library that implements a small mesh-style protocol on top of a “raw 802.11 frame” PHY abstraction with separate modules for: |
| 19 | +- PHY abstraction: `src/phy/` (+ ESP32 and POSIX ports in `port/`) |
| 20 | +- MAC: `src/mac/` (send path includes CSMA/CA/backoff + ACK/retry logic) |
| 21 | +- Network: `src/net/` (discovery + routing modes) |
| 22 | +- Security: `src/sec/` (AES-128-CTR + HMAC-SHA256 truncated MIC + replay window) |
| 23 | +- Optional power-management module: `src/power/` (compile-time gated) |
19 | 24 |
|
20 | | ---- |
| 25 | +## Verification and evidence |
21 | 26 |
|
22 | | -## Why not ESP-NOW? |
| 27 | +See: |
| 28 | +- `VERIFICATION.md` (commands run, results, and what was NOT run) |
| 29 | +- `docs/DIAGRAMS.md` (Mermaid diagrams derived from the code paths) |
| 30 | +- `SECURITY.md` (threat model + limitations; no “strong security” claims without proof) |
23 | 31 |
|
24 | | -ESP-NOW is a great idea — but it has fundamental limitations: |
| 32 | +## Version consistency |
25 | 33 |
|
26 | | -| | ESP-NOW | **µMesh** | |
27 | | -|---|---|---| |
28 | | -| Open protocol | ✗ Proprietary | **✓ MIT license** | |
29 | | -| Mesh routing | ✗ 1 hop only | **✓ Multi-hop** | |
30 | | -| Addressing | ✗ MAC only | **✓ NET_ID + NODE_ID** | |
31 | | -| Discovery | ✗ Manual | **✓ Automatic** | |
32 | | -| Security | ~ Basic | **✓ AES-128 + HMAC** | |
33 | | -| Command layer | ✗ None | **✓ Opcode table** | |
34 | | -| Portability | ✗ Espressif only | **✓ Abstracted PHY** | |
35 | | -| Dependencies | Espressif SDK | **✓ Zero extra** | |
| 34 | +**Implemented version in code:** `1.4.0` (`src/common/defs.h` defines `UMESH_VERSION_MAJOR/MINOR/PATCH`). |
| 35 | +NOT VERIFIED: Git tags / GitHub releases in this run (no network access). |
36 | 36 |
|
37 | | ---- |
| 37 | +## Getting started (API) |
38 | 38 |
|
39 | | -## Why not Zigbee / Thread? |
| 39 | +The public header is `include/umesh.h`. For configuration fields and defaults, see `docs/API_REFERENCE.md` (defaults are derived from code in `src/umesh.c` and constants in `src/common/defs.h`). |
40 | 40 |
|
41 | | -``` |
42 | | -Zigbee / Thread: |
43 | | - ✗ Require a special radio chip (802.15.4) |
44 | | - ✗ Complex — hundreds of KB of code |
45 | | - ✗ Difficult integration |
46 | | - ✗ Certification required |
| 41 | +## What is NOT VERIFIED (intentionally not claimed here) |
47 | 42 |
|
48 | | -µMesh: |
49 | | - ✓ Runs on the ESP32 you already have |
50 | | - ✓ Lightweight — tens of KB |
51 | | - ✓ #include and go |
52 | | - ✓ MIT license |
53 | | -``` |
| 43 | +This repository (and this run) does not provide measured evidence for radio range, throughput, latency, or current consumption. Any such numbers must be backed by reproducible measurement artifacts (hardware, antenna, channel, TX power, environment) and linked from documentation. |
54 | 44 |
|
55 | | ---- |
| 45 | +## Documentation index |
56 | 46 |
|
57 | | -## How it works |
58 | | - |
59 | | -µMesh sends its own packets directly through the WiFi hardware using `esp_wifi_80211_tx()` — no association, no AP, no DHCP. It receives through promiscuous mode. The WiFi antenna becomes a **general-purpose radio transmitter** for the protocol. |
60 | | - |
61 | | -``` |
62 | | -Standard ESP32 WiFi stack: |
63 | | - Application -> lwIP -> WiFi stack -> 802.11 -> Antenna |
64 | | -
|
65 | | -µMesh: |
66 | | - Application -> µMesh stack -> raw 802.11 frame -> Antenna |
67 | | - (bypasses entire WiFi stack) |
68 | | -``` |
69 | | - |
70 | | ---- |
71 | | - |
72 | | -## Quick Start |
73 | | - |
74 | | -```c |
75 | | -#include "umesh.h" |
76 | | - |
77 | | -static const uint8_t KEY[16] = { 0x2B, 0x7E, ... }; |
78 | | - |
79 | | -umesh_cfg_t cfg = { |
80 | | - .net_id = 0x01, |
81 | | - .node_id = UMESH_ADDR_UNASSIGNED, /* auto-assign */ |
82 | | - .master_key = KEY, |
83 | | - .role = UMESH_ROLE_END_NODE, |
84 | | - .security = UMESH_SEC_FULL, |
85 | | - .channel = 6, |
86 | | -}; |
87 | | - |
88 | | -void on_temp(umesh_pkt_t *pkt) { |
89 | | - float t = *(float *)pkt->payload; |
90 | | - printf("Temperature: %.1f C\n", t); |
91 | | -} |
92 | | - |
93 | | -void app_main(void) { |
94 | | - umesh_init(&cfg); |
95 | | - umesh_start(); |
96 | | - umesh_on_cmd(UMESH_CMD_SENSOR_TEMP, on_temp); |
97 | | - |
98 | | - float temp = 23.5f; |
99 | | - umesh_send(0x02, UMESH_CMD_SENSOR_TEMP, |
100 | | - &temp, sizeof(temp), UMESH_FLAG_ACK_REQ); |
101 | | -} |
102 | | -``` |
103 | | -
|
104 | | ---- |
105 | | -
|
106 | | -## Sensor Networks (Gradient Routing) |
107 | | -
|
108 | | -For many-to-one sensor collection (for example 30 sensors -> 1 coordinator), |
109 | | -enable gradient mode: |
110 | | -
|
111 | | -```c |
112 | | -umesh_cfg_t cfg = { |
113 | | - .net_id = 0x01, |
114 | | - .node_id = UMESH_ADDR_UNASSIGNED, |
115 | | - .master_key = KEY, |
116 | | - .role = UMESH_ROLE_AUTO, |
117 | | - .security = UMESH_SEC_FULL, |
118 | | - .channel = 6, |
119 | | - .routing = UMESH_ROUTING_GRADIENT, |
120 | | - .on_gradient_ready = on_ready, |
121 | | -}; |
122 | | -``` |
123 | | - |
124 | | -In this mode each node tracks distance-to-coordinator and forwards packets |
125 | | -uphill through neighbors with lower distance. |
126 | | - |
127 | | ---- |
128 | | - |
129 | | -## Architecture |
130 | | - |
131 | | -``` |
132 | | -+---------------------------------------------+ |
133 | | -| APPLICATION LAYER | |
134 | | -| umesh_send / receive | |
135 | | -+---------------------------------------------+ |
136 | | -| NETWORK LAYER | |
137 | | -| addressing, routing, multi-hop | |
138 | | -+---------------------------------------------+ |
139 | | -| MAC LAYER | |
140 | | -| CSMA/CA, ACK, backoff | |
141 | | -+------------------+--------------------------+ |
142 | | -| SECURITY LAYER | FEC LAYER | |
143 | | -| AES-128 CTR | Hamming(7,4) | |
144 | | -| HMAC-SHA256 | | |
145 | | -+------------------+--------------------------+ |
146 | | -| PHYSICAL LAYER | |
147 | | -| Raw IEEE 802.11 frames / ESP32 WiFi | |
148 | | -| esp_wifi_80211_tx / Promiscuous mode | |
149 | | -+---------------------------------------------+ |
150 | | -``` |
151 | | - |
152 | | ---- |
153 | | - |
154 | | -## Performance |
155 | | - |
156 | | -``` |
157 | | -Range: ~200 m (direct link) |
158 | | - ~500 m+ (multi-hop, 3 hops) |
159 | | -Latency: ~1-5 ms (1 hop) |
160 | | -Data rate: tens of kbps (raw 802.11) |
161 | | -Max nodes: 16 per network |
162 | | -Max hops: 15 |
163 | | -TX current: ~80 mA @ 3.3V |
164 | | -RX current: ~60 mA @ 3.3V |
165 | | -``` |
166 | | - |
167 | | ---- |
168 | | - |
169 | | -## Comparison |
170 | | - |
171 | | -| | µMesh | ESP-NOW | Zigbee | BLE Mesh | LoRa | |
172 | | -|---|---|---|---|---|---| |
173 | | -| Range | 200m+ | 200m | 100m | 30m | 10km | |
174 | | -| Multi-hop | ✓ | ✗ | ✓ | ✓ | ✗ | |
175 | | -| Extra HW | ✗ | ✗ | ✓ | ✗ | ✓ | |
176 | | -| Open source | ✓ | ✗ | ~ | ~ | ✓ | |
177 | | -| C99 embedded | ✓ | ✗ | ✗ | ✗ | ~ | |
178 | | -| Zero deps | ✓ | ✗ | ✗ | ✗ | ✗ | |
179 | | -| Mesh routing | ✓ | ✗ | ✓ | ✓ | ✗ | |
180 | | - |
181 | | ---- |
182 | | - |
183 | | -## Hardware |
184 | | - |
185 | | -µMesh runs on **any ESP32** you already have: |
186 | | - |
187 | | -| Chip | Support | Notes | |
188 | | -|---|---|---| |
189 | | -| ESP32 (classic) | ✓ | Full support | |
190 | | -| ESP32-S3 | ✓ | Recommended | |
191 | | -| ESP32-C3 | ✓ | Cheapest (~EUR 3) | |
192 | | -| ESP32-S2 | ✓ | Single-core | |
193 | | - |
194 | | -**No extra hardware.** Just ESP32 + power supply. |
195 | | - |
196 | | -## Supported Hardware |
197 | | - |
198 | | -| Chip | Support | Reason | |
199 | | -|------|---------|--------| |
200 | | -| ESP32 | ✓ Full | Classic, fully tested | |
201 | | -| ESP32-S2 | ✓ Full | No BT, otherwise identical | |
202 | | -| ESP32-S3 | ✓ Full | Recommended, dual-core | |
203 | | -| ESP32-C3 | ✓ Full | Budget option, RISC-V | |
204 | | -| ESP32-C6 | ✓ Full | WiFi 6, best power mgmt | |
205 | | -| ESP32-H2 | ✗ Not supported | No WiFi (802.15.4 only) | |
206 | | -| ESP32-C2 | ✗ Not supported | Insufficient RAM | |
207 | | -| ESP8266 | ✗ Not supported | No raw 802.11 TX API | |
208 | | -| ESP8285 | ✗ Not supported | Same as ESP8266 | |
209 | | - |
210 | | -> **Why ESP8266 is not supported:** |
211 | | -> ESP8266 lacks `esp_wifi_80211_tx()` - the API required |
212 | | -> to send raw 802.11 frames. Only promiscuous RX is |
213 | | -> available, making it impossible to be an active mesh node. |
214 | | -> |
215 | | -> **Why ESP32-H2 is not supported:** |
216 | | -> ESP32-H2 uses 802.15.4 radio (Zigbee/Thread) instead |
217 | | -> of WiFi. µMesh requires WiFi hardware. |
218 | | -> |
219 | | -> **Why ESP32-C2 is not supported:** |
220 | | -> ESP32-C2 has insufficient RAM (272KB) for the full |
221 | | -> µMesh stack. |
222 | | -
|
223 | | ---- |
224 | | - |
225 | | -## Documentation |
226 | | - |
227 | | -| Document | Content | |
228 | | -|---|---| |
229 | | -| [DESIGN.md](docs/DESIGN.md) | Architectural decisions and rationale | |
230 | | -| [API_REFERENCE.md](docs/API_REFERENCE.md) | Public API, cfg fields and callbacks | |
231 | | -| [PHYSICAL_LAYER.md](docs/PHYSICAL_LAYER.md) | Raw 802.11, promiscuous mode, ESP32 WiFi API | |
232 | | -| [MAC_LAYER.md](docs/MAC_LAYER.md) | CSMA/CA, ACK, backoff, collisions | |
233 | | -| [NETWORK_LAYER.md](docs/NETWORK_LAYER.md) | Routing, discovery, multi-hop | |
234 | | -| [SECURITY_LAYER.md](docs/SECURITY_LAYER.md) | AES-128 CTR, HMAC, replay protection | |
235 | | -| [IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | C99 structure, project layout | |
236 | | -| [KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) | Known issues and limitations | |
237 | | -| [POWER_MANAGEMENT.md](docs/POWER_MANAGEMENT.md) | ACTIVE/LIGHT/DEEP power profiles | |
238 | | - |
239 | | ---- |
240 | | - |
241 | | -## micro-toolkit Integration |
242 | | - |
243 | | -µMesh uses **microcrypt** for cryptographic primitives (AES-128, HMAC-SHA256). |
244 | | -Other micro-toolkit libraries are optional and can be integrated if needed: |
245 | | - |
246 | | -| Library | Role in µMesh | |
247 | | -|---|---| |
248 | | -| `microcrypt` | AES-128, HMAC-SHA256 — **used** | |
249 | | -| `microfsm` | Network layer FSM (optional) | |
250 | | -| `microlog` | Structured packet/RSSI logging (optional) | |
251 | | -| `iotspool` | Store-and-forward over µMesh (optional) | |
252 | | -| `microwdt` | Watchdog for protocol stack task (optional) | |
253 | | -| `microtest` | Unit test framework (optional) | |
254 | | - |
255 | | ---- |
256 | | - |
257 | | -## Project Status |
258 | | - |
259 | | -``` |
260 | | -+ Protocol designed |
261 | | -+ Documentation |
262 | | -+ PHY layer (raw 802.11) |
263 | | -+ MAC layer (CSMA/CA, ACK, backoff) |
264 | | -+ Network layer (routing, discovery, FSM) |
265 | | -+ Security layer (AES-128 CTR, HMAC-SHA256) |
266 | | -+ Auto-mesh coordinator election |
267 | | -+ Gradient routing mode for sensor networks |
268 | | -+ Broad ESP32 capability detection (S2/S3/C3/C6) |
269 | | -+ ESP32 port |
270 | | -+ Examples |
271 | | -+ Unit tests (13/13 passing) |
272 | | -``` |
273 | | - |
274 | | ---- |
| 47 | +- `docs/API_REFERENCE.md` |
| 48 | +- `docs/SECURITY_LAYER.md` |
| 49 | +- `docs/PHYSICAL_LAYER.md` |
| 50 | +- `docs/MAC_LAYER.md` |
| 51 | +- `docs/NETWORK_LAYER.md` |
| 52 | +- `docs/POWER_MANAGEMENT.md` |
| 53 | +- `docs/KNOWN_ISSUES.md` |
275 | 54 |
|
276 | 55 | ## License |
277 | 56 |
|
278 | | -MIT — free for commercial and personal use. |
279 | | - |
280 | | ---- |
281 | | - |
282 | | -## Power Consumption |
283 | | - |
284 | | -| Mode | Role | Avg Current | Use Case | |
285 | | -|------|------|-------------|----------| |
286 | | -| ACTIVE | Any | ~60-80 mA | Development, always-on | |
287 | | -| LIGHT | END_NODE | ~8 mA | Battery sensors, periodic check-in | |
288 | | -| DEEP | END_NODE | ~1-5 mA | Long interval telemetry (30s+) | |
289 | | -| ACTIVE | ROUTER | ~60 mA | Must stay awake to route packets | |
290 | | - |
291 | | -Deep sleep is intended for gradient routing deployments. |
292 | | -Routers should use ACTIVE mode in production meshes. |
| 57 | +MIT (see `LICENSE`). |
0 commit comments