Skip to content

Commit 3d0bf0f

Browse files
VanderhellVanderhell
committed
docs: add wiki pages to .github/wiki/
1 parent 7bf64c3 commit 3d0bf0f

File tree

9 files changed

+377
-0
lines changed

9 files changed

+377
-0
lines changed

‎.github/wiki/Configuration.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Configuration
2+
3+
`umesh_cfg_t` controls network identity, role behavior, routing, power profile, and callbacks.
4+
5+
## Core fields
6+
7+
| Field | Type | Meaning | Typical value / default |
8+
|---|---|---|---|
9+
| `net_id` | `uint8_t` | Logical network ID. Nodes join only matching networks. | `0x01` |
10+
| `node_id` | `uint8_t` | Node address. Use unassigned for auto assignment. | `UMESH_ADDR_UNASSIGNED (0xFE)` |
11+
| `master_key` | `const uint8_t*` | 16-byte key for AUTH/FULL security. | Required for secure mesh |
12+
| `role` | `umesh_role_t` | Startup role mode. | `UMESH_ROLE_AUTO` recommended |
13+
| `security` | `umesh_security_t` | Security level (`NONE`, `AUTH`, `FULL`). | `UMESH_SEC_FULL` |
14+
| `channel` | `uint8_t` | WiFi channel used for raw frames. | default `6` when `0` |
15+
| `tx_power` | `uint8_t` | PHY TX power setting. | default `60` when `0` |
16+
17+
## Routing and auto-mesh fields
18+
19+
| Field | Type | Meaning | Default when `0` |
20+
|---|---|---|---|
21+
| `routing` | `umesh_routing_mode_t` | `DISTANCE_VECTOR` or `GRADIENT`. | `DISTANCE_VECTOR` |
22+
| `scan_ms` | `uint32_t` | Auto-role scan window before election. | `2000` |
23+
| `election_ms` | `uint32_t` | Auto-role election timeout. | `1000` |
24+
| `gradient_beacon_ms` | `uint32_t` | Coordinator gradient beacon period. | `30000` |
25+
| `gradient_jitter_max_ms` | `uint32_t` | Randomized beacon jitter cap. | `200` |
26+
27+
## Power fields
28+
29+
| Field | Type | Meaning | Default when `0` |
30+
|---|---|---|---|
31+
| `power_mode` | `umesh_power_mode_t` | `ACTIVE`, `LIGHT`, or `DEEP`. | `ACTIVE` |
32+
| `light_sleep_interval_ms` | `uint32_t` | Sleep interval for LIGHT mode. | `1000` |
33+
| `light_listen_window_ms` | `uint32_t` | RX listen window for LIGHT mode. | `100` |
34+
| `deep_sleep_tx_interval_ms` | `uint32_t` | Wake/send interval in DEEP mode. | `30000` |
35+
36+
## Callback fields
37+
38+
| Field | Signature | Trigger |
39+
|---|---|---|
40+
| `on_joined` | `void (*)(uint8_t node_id)` | Node gets valid ID and joins network |
41+
| `on_role_elected` | `void (*)(umesh_role_t role)` | Auto election chooses role |
42+
| `on_node_joined` | `void (*)(uint8_t node_id)` | Peer joined notification |
43+
| `on_node_left` | `void (*)(uint8_t node_id)` | Peer timeout/leave notification |
44+
| `on_gradient_ready` | `void (*)(uint8_t distance)` | First valid gradient distance available |
45+
| `on_sleep` | `void (*)(void)` | Power subsystem enters sleep |
46+
| `on_wake` | `void (*)(void)` | Power subsystem wakes |
47+
| `on_error` | `void (*)(umesh_result_t err)` | Internal error callback |
48+
49+
## Minimal recommended config
50+
51+
```c
52+
umesh_cfg_t cfg = {
53+
.net_id = 0x01,
54+
.node_id = UMESH_ADDR_UNASSIGNED,
55+
.master_key = KEY,
56+
.role = UMESH_ROLE_AUTO,
57+
.security = UMESH_SEC_FULL,
58+
.channel = 6,
59+
.routing = UMESH_ROUTING_GRADIENT,
60+
};
61+
```

‎.github/wiki/Contributing.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Contributing
2+
3+
Thanks for helping improve µMesh.
4+
5+
## Ways to contribute
6+
7+
- Report bugs with logs and reproducible steps
8+
- Propose features with clear use case
9+
- Improve docs, examples, and tests
10+
- Submit fixes for portability, reliability, or performance
11+
12+
## Development workflow
13+
14+
1. Fork and create a feature branch.
15+
2. Keep changes focused and small.
16+
3. Add or update tests when behavior changes.
17+
4. Run local build/tests before opening PR.
18+
5. Open a Pull Request with clear summary and rationale.
19+
20+
## Local build and test
21+
22+
```bash
23+
git submodule update --init --recursive
24+
cmake -S . -B build -DUMESH_PORT=posix -DUMESH_BUILD_TESTS=ON
25+
cmake --build build -j
26+
ctest --test-dir build --output-on-failure
27+
```
28+
29+
## Coding expectations
30+
31+
- Keep C99 style consistent with existing code
32+
- Avoid breaking public API without discussion
33+
- Prefer explicit error handling and clear return codes
34+
- Document non-obvious behavior in `docs/`
35+
36+
## Pull request checklist
37+
38+
- [ ] Compiles on your target configuration
39+
- [ ] Tests pass or failures are explained
40+
- [ ] Docs updated (README/docs/wiki) if needed
41+
- [ ] Backward compatibility impact described

‎.github/wiki/FAQ.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# FAQ
2+
3+
## Does it work with ESP8266?
4+
5+
No. ESP8266 lacks `esp_wifi_80211_tx()`.
6+
7+
## Can I use it without a coordinator?
8+
9+
Yes. Use `UMESH_ROLE_AUTO`. Nodes elect a coordinator automatically.
10+
11+
## How many nodes can the network support?
12+
13+
Up to 16 nodes per network (`NET_ID`). Multiple networks can coexist on the same channel.
14+
15+
## Does it interfere with normal WiFi?
16+
17+
It shares the 2.4GHz band. Use channel 1, 6, or 11. CSMA/CA handles collisions.
18+
19+
## What is the maximum range?
20+
21+
About 200m line-of-sight with standard ESP32. Range extends with multi-hop routing.

‎.github/wiki/Getting-Started.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Getting Started
2+
3+
This guide gets you from source checkout to a working 3-node mesh test.
4+
5+
## Step 1: Clone and build
6+
7+
```bash
8+
git clone https://github.com/Vanderhell/uMesh
9+
cd uMesh
10+
git submodule update --init --recursive
11+
cmake -S . -B build -DUMESH_PORT=posix
12+
cmake --build build -j
13+
```
14+
15+
## Step 2: Flash to ESP32
16+
17+
Use the auto-role firmware:
18+
19+
- `tests/hardware/firmware/auto_mesh_node/auto_mesh_node.ino`
20+
21+
Arduino IDE checklist per chip:
22+
23+
- Select the correct board (ESP32 / S2 / S3 / C3 / C6)
24+
- Select correct USB/COM port
25+
- Keep CPU/flash defaults unless your board vendor says otherwise
26+
- Set `USB CDC On Boot` to `Enabled` (important for serial test tooling)
27+
28+
Flash one device as coordinator candidate, one as router candidate, one as end-node candidate.
29+
30+
## Step 3: Run test runner
31+
32+
```bash
33+
pip install -r tests/hardware/runner/requirements.txt
34+
python tests/hardware/runner/test_runner.py \
35+
-c COM_COORDINATOR -r COM_ROUTER -e COM_ENDNODE
36+
```
37+
38+
Expected result:
39+
40+
- `7/7 PASS`

‎.github/wiki/Hardware-Support.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Hardware Support
2+
3+
µMesh support matrix for ESP family:
4+
5+
| Chip | Support | Reason |
6+
|------|---------|--------|
7+
| ESP32 | ✓ Full | Classic, fully tested |
8+
| ESP32-S2 | ✓ Full | No BT, otherwise identical |
9+
| ESP32-S3 | ✓ Full | Recommended, dual-core |
10+
| ESP32-C3 | ✓ Full | Budget option, RISC-V |
11+
| ESP32-C6 | ✓ Full | WiFi 6, best power mgmt |
12+
| ESP32-H2 | ✗ Not supported | No WiFi (802.15.4 only) |
13+
| ESP32-C2 | ✗ Not supported | Insufficient RAM |
14+
| ESP8266 | ✗ Not supported | No raw 802.11 TX API |
15+
| ESP8285 | ✗ Not supported | Same as ESP8266 |
16+
17+
## Why ESP8266 is not supported
18+
19+
ESP8266 does not provide `esp_wifi_80211_tx()`, which µMesh requires to send raw 802.11 frames. Promiscuous RX alone is not enough for active mesh participation.
20+
21+
## Why ESP32-H2 is not supported
22+
23+
ESP32-H2 is an 802.15.4 (Zigbee/Thread) target, not a WiFi target. µMesh depends on WiFi PHY capability.
24+
25+
## Why ESP32-C2 is not supported
26+
27+
ESP32-C2 RAM is too constrained for the full µMesh stack and expected routing/security workloads.

‎.github/wiki/Home.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# µMesh Wiki
2+
3+
µMesh is a lightweight open mesh protocol stack that runs over raw IEEE 802.11 frames on ESP chips. It bypasses normal WiFi networking (association, DHCP, TCP/IP) and enables direct multi-hop device-to-device communication with routing, discovery, and security.
4+
5+
## Pages
6+
7+
- [Getting Started](Getting-Started)
8+
- [Configuration](Configuration)
9+
- [Routing Modes](Routing-Modes)
10+
- [Power Management](Power-Management)
11+
- [Hardware Support](Hardware-Support)
12+
- [Troubleshooting](Troubleshooting)
13+
- [FAQ](FAQ)
14+
- [Contributing](Contributing)
15+
16+
## Repository
17+
18+
- [uMesh on GitHub](https://github.com/Vanderhell/uMesh)

‎.github/wiki/Power-Management.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Power Management
2+
3+
µMesh provides runtime power profiles via `umesh_set_power_mode(...)`.
4+
5+
## Modes
6+
7+
## ACTIVE
8+
9+
- Radio stays fully available
10+
- Lowest latency
11+
- Highest current draw
12+
- Best for coordinators and latency-sensitive routers
13+
14+
## LIGHT
15+
16+
- Periodic sleep with short listen windows
17+
- Balanced power vs responsiveness
18+
- Tuned by:
19+
- `light_sleep_interval_ms`
20+
- `light_listen_window_ms`
21+
22+
## DEEP
23+
24+
- Aggressive sleep intervals with periodic wake/send cycles
25+
- Lowest average power
26+
- Highest latency
27+
- Tuned by:
28+
- `deep_sleep_tx_interval_ms`
29+
30+
## API
31+
32+
- `umesh_set_power_mode(UMESH_POWER_ACTIVE | UMESH_POWER_LIGHT | UMESH_POWER_DEEP)`
33+
- `umesh_get_power_mode()`
34+
- `umesh_deep_sleep_cycle()`
35+
- `umesh_estimate_current_ma()`
36+
- `umesh_get_power_stats()`
37+
38+
## Practical guidance
39+
40+
- Coordinator: keep `ACTIVE`.
41+
- Routers: use `ACTIVE` or carefully tuned `LIGHT`.
42+
- End nodes: `LIGHT` or `DEEP` depending on reporting interval.
43+
- Validate packet delivery and retries after changing power profile.

‎.github/wiki/Routing-Modes.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Routing Modes
2+
3+
µMesh supports two routing modes configured by `umesh_cfg_t.routing`.
4+
5+
## 1) Distance Vector (`UMESH_ROUTING_DISTANCE_VECTOR`)
6+
7+
How it works:
8+
9+
- Nodes exchange route updates periodically
10+
- Each node keeps best next-hop route to known destinations
11+
- Metric combines hop cost and link quality
12+
13+
Best for:
14+
15+
- General mesh traffic
16+
- Mixed source/destination patterns
17+
- Stable small-to-medium topologies
18+
19+
Pros:
20+
21+
- Mature default mode
22+
- Handles arbitrary destination routing
23+
24+
Tradeoffs:
25+
26+
- Convergence depends on route update intervals
27+
28+
## 2) Gradient (`UMESH_ROUTING_GRADIENT`)
29+
30+
How it works:
31+
32+
- Coordinator emits gradient beacons
33+
- Each node computes distance-to-coordinator
34+
- Uplink traffic forwards to neighbor with lower distance
35+
36+
Best for:
37+
38+
- Sensor networks (many nodes -> one coordinator)
39+
- Telemetry collection and low-complexity uplink
40+
41+
Pros:
42+
43+
- Very simple forwarding logic for upstream traffic
44+
- Good fit for periodic sensor payloads
45+
46+
Tradeoffs:
47+
48+
- Optimized for coordinator-destined traffic
49+
- Needs beacon convergence before routing is ready
50+
51+
## Which one should I choose?
52+
53+
- Choose **Distance Vector** for general-purpose mesh communication.
54+
- Choose **Gradient** for sensor aggregation to one coordinator.
55+
56+
## Related settings
57+
58+
- `gradient_beacon_ms`
59+
- `gradient_jitter_max_ms`
60+
- `umesh_gradient_distance()`
61+
- `umesh_gradient_refresh()`

‎.github/wiki/Troubleshooting.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Troubleshooting
2+
3+
Common issues and quick fixes.
4+
5+
## Node not joining
6+
7+
Symptoms:
8+
9+
- Node remains unassigned or disconnected
10+
11+
Checks:
12+
13+
- `net_id` must match on all nodes
14+
- `master_key` must match exactly on all nodes
15+
- `channel` must match
16+
- Ensure role setup is valid (`UMESH_ROLE_AUTO` is easiest)
17+
18+
## `NOT_ROUTABLE` error
19+
20+
Symptoms:
21+
22+
- `umesh_send(...)` fails with `NOT_ROUTABLE`
23+
24+
Checks:
25+
26+
- In gradient mode, wait until gradient is established (`on_gradient_ready`)
27+
- Verify coordinator is online and sending beacons
28+
- Reduce distance or obstructions while converging
29+
30+
## High retry count
31+
32+
Symptoms:
33+
34+
- Elevated `retry_count`, delayed delivery
35+
36+
Checks:
37+
38+
- Reduce node spacing
39+
- Remove obstacles/metal shielding
40+
- Prefer channels 1, 6, or 11
41+
- Lower congestion from nearby AP traffic
42+
43+
## USB CDC not working on ESP32-C3
44+
45+
Symptoms:
46+
47+
- No serial output in test runner
48+
49+
Fix:
50+
51+
- In Arduino IDE, set `USB CDC On Boot` to `Enabled`
52+
- Reflash and reconnect serial monitor
53+
54+
## Tests failing at distance
55+
56+
Symptoms:
57+
58+
- Intermittent packet loss in hardware test runner
59+
60+
Checks:
61+
62+
- Mini modules often have weaker antennas
63+
- Start with shorter spacing, then increase gradually
64+
- Keep antennas vertical and clear of cables/enclosures
65+
- Increase relay density (more routers) for long paths

0 commit comments

Comments
 (0)