Skip to content

Commit 0e2bfb2

Browse files
committed
Audit docs: strict verification + security enforcement
1 parent 3d0bf0f commit 0e2bfb2

19 files changed

Lines changed: 505 additions & 596 deletions

‎.gitignore‎

355 Bytes
Binary file not shown.

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Contributing
2+
3+
This repository currently focuses on correctness and verifiable documentation.
4+
5+
## Before opening a PR
6+
7+
- Keep technical claims evidence-based. If you add performance/power/range claims, include reproducible measurement artifacts and link them.
8+
- Prefer small, reviewable changes (one logical change per PR).
9+
- If you modify behavior, add or update a host-test under `tests/` when possible.
10+
11+
## Local build + tests (POSIX port)
12+
13+
The repository supports a host-testable POSIX port via CMake.
14+
15+
Example (Windows/MSVC):
16+
- `cmake -S . -B build -DUMESH_PORT=posix -DUMESH_BUILD_TESTS=ON`
17+
- `cmake --build build --config Release --parallel`
18+
- `ctest --test-dir build -C Release --output-on-failure`

‎README.md‎

Lines changed: 38 additions & 273 deletions
Original file line numberDiff line numberDiff line change
@@ -1,292 +1,57 @@
1-
# µMesh
1+
# µMesh (uMesh)
22

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.
54

6-
[![Language: C99](https://img.shields.io/badge/language-C99-blue.svg)](#)
7-
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#)
8-
[![Platform](https://img.shields.io/badge/platform-ESP32%20%7C%20S2%20%7C%20S3%20%7C%20C3%20%7C%20C6-lightgrey.svg)](#)
9-
[![Status: v1.4.0](https://img.shields.io/badge/status-v1.4.0-brightgreen.svg)](#)
10-
[![Actions](https://github.com/Vanderhell/uMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Vanderhell/uMesh/actions/workflows/ci.yml)
5+
## Status (this run)
116

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`
1311

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.
1515

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)
1717

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)
1924

20-
---
25+
## Verification and evidence
2126

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)
2331

24-
ESP-NOW is a great idea — but it has fundamental limitations:
32+
## Version consistency
2533

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).
3636

37-
---
37+
## Getting started (API)
3838

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`).
4040

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)
4742

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.
5444

55-
---
45+
## Documentation index
5646

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`
27554

27655
## License
27756

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

Comments
 (0)