Skip to content

Commit 72b91c2

Browse files
jurgelenasjurgelenas
committed
split development docs out of README into docs/development.md
Move the Architecture table and CRSF Simulator section out of the user-facing README and into a new docs/development.md. Add a Make targets reference covering setup, quality checks, and deployment.
1 parent 4bd6a69 commit 72b91c2

2 files changed

Lines changed: 72 additions & 37 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -62,17 +62,6 @@ The main tool (`SCRIPTS/TOOLS/ExpressLRS/`) lets you configure your ExpressLRS t
6262

6363
<img src="screenshots/tool_main.png" width="472" alt="ExpressLRS Configuration Tool">
6464

65-
### Architecture
66-
67-
| Module | Purpose |
68-
|--------|---------|
69-
| `main.lua` | Entry point and run-loop orchestrator |
70-
| `protocol.lua` | CRSF frame parsing, device discovery, parameter read/write |
71-
| `navigation.lua` | Folder and device navigation stack |
72-
| `shim.lua` | Polyfills for BW radios missing standard Lua functions |
73-
| `ui/lvgl.lua` | Color LCD interface (LVGL dialogs, command pages, warnings) |
74-
| `ui/lcd.lua` | BW LCD interface (text cursor, popups) |
75-
7665
## Widgets
7766

7867
Both widgets running side-by-side on the home screen:
@@ -91,33 +80,9 @@ The VTX Administrator widget (`WIDGETS/ELRSVTXAdmin/`) provides control over you
9180

9281
<img src="screenshots/widget_vtxadmin_fullscreen.png" width="472" alt="VTX Administrator Widget">
9382

94-
## CRSF Simulator (Testing)
95-
96-
The `src/SCRIPTS/CRSFSimulator/` library provides a CRSF protocol simulator for development and testing without real hardware. It is declared as a dev-only library in `edgetx.yml` (`dev: true`), so it is included by `edgetx-cli dev sync` but skipped by `edgetx-cli pkg install`.
97-
98-
**File:** `src/SCRIPTS/CRSFSimulator/csrfsimulator.lua`
99-
100-
The simulator provides a packet-level mock of `crossfireTelemetryPop` and `crossfireTelemetryPush`, allowing the ELRS tool to exercise the full communication flow (device discovery, parameter loading, value writes, ELRS status) inside the EdgeTX simulator. Multiple scenarios are available to simulate different states such as normal operation, disconnected links, model mismatch, and more.
101-
102-
### How it works
103-
104-
When the tool detects it is running in the EdgeTX simulator (version string ends with `-simu`), `main.lua` automatically loads the simulator module from `/SCRIPTS/CRSFSimulator/csrfsimulator.lua` and patches the protocol's `pop`, `push`, and `hasCrsfModule` functions with the mock implementations.
105-
106-
Run `make sync` (which runs `edgetx-cli dev sync`) to copy the sources -- including the dev-only `CRSFSimulator` library -- onto the simulator SD card. `edgetx-cli pkg install` omits the library automatically, so the simulator is never shipped to real hardware.
107-
108-
### Scenarios
109-
110-
The simulator supports multiple test scenarios, configurable via the `config.scenario` variable at the top of the file:
83+
## Development
11184

112-
| Scenario | Description |
113-
|----------|-------------|
114-
| `normal` | TX + RX connected. Happy path with full telemetry and all parameters. |
115-
| `no_telemetry` | TX present but no RX telemetry. Shows "No telemetry" state. |
116-
| `reconnect` | Starts disconnected, transitions to connected after ~5 seconds. |
117-
| `model_mismatch` | TX + RX connected with Model ID mismatch flag. Triggers warning dialog. |
118-
| `armed` | TX + RX connected with "is Armed" warning flag. |
119-
| `slow_loading` | Parameter reads delayed by ~2 seconds each. Tests loading UI states. |
120-
| `no_module` | No CRSF module found. Triggers "No Module Found" error dialog. |
85+
See [docs/development.md](docs/development.md) for the tool's internal architecture and the CRSF simulator used for testing inside the EdgeTX simulator.
12186

12287
## Compatibility
12388

‎docs/development.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Development
2+
3+
This document covers the internal architecture of the ExpressLRS configuration tool and the CRSF simulator used for testing inside the EdgeTX simulator without real hardware.
4+
5+
## Make targets
6+
7+
Run `make help` to list all targets. The Makefile groups them into three categories:
8+
9+
### Setup
10+
11+
| Target | Purpose |
12+
|--------|---------|
13+
| `install-tools` | Install both `stylua` and `lua-language-server` |
14+
| `install-stylua` | Install [stylua](https://github.com/JohnnyMorganz/StyLua) via `cargo` (requires Rust toolchain). Built with the `lua53` feature for EdgeTX compatibility. |
15+
| `install-luals` | Download [lua-language-server](https://github.com/LuaLS/lua-language-server) `3.17.1` to `bin/lua-language-server/` |
16+
17+
### Quality checks
18+
19+
| Target | Purpose |
20+
|--------|---------|
21+
| `format` | Format all Lua sources in `src/` with `stylua` (config: `.stylua.toml`) |
22+
| `format-check` | Verify formatting without modifying files. Used in CI. |
23+
| `typecheck` | Run `lua-language-server --check .` against the project (config: `.luarc.json`) |
24+
| `check` | Convenience target: runs `format-check` then `typecheck` |
25+
26+
### Deployment
27+
28+
| Target | Purpose |
29+
|--------|---------|
30+
| `sync` | Copy sources to the EdgeTX simulator SD card at `../edgetx-sdcard` via `edgetx-cli dev sync`. Includes dev-only libraries like the CRSF simulator. |
31+
| `push` | Install the package to a connected EdgeTX radio via `edgetx-cli pkg install . --eject`. Excludes dev-only libraries. |
32+
33+
## Architecture
34+
35+
| Module | Purpose |
36+
|--------|---------|
37+
| `main.lua` | Entry point and run-loop orchestrator |
38+
| `protocol.lua` | CRSF frame parsing, device discovery, parameter read/write |
39+
| `navigation.lua` | Folder and device navigation stack |
40+
| `shim.lua` | Polyfills for BW radios missing standard Lua functions |
41+
| `ui/lvgl.lua` | Color LCD interface (LVGL dialogs, command pages, warnings) |
42+
| `ui/lcd.lua` | BW LCD interface (text cursor, popups) |
43+
44+
## CRSF Simulator
45+
46+
The `src/SCRIPTS/CRSFSimulator/` library provides a CRSF protocol simulator for development and testing without real hardware. It is declared as a dev-only library in `edgetx.yml` (`dev: true`), so it is included by `edgetx-cli dev sync` but skipped by `edgetx-cli pkg install`.
47+
48+
**File:** `src/SCRIPTS/CRSFSimulator/csrfsimulator.lua`
49+
50+
The simulator provides a packet-level mock of `crossfireTelemetryPop` and `crossfireTelemetryPush`, allowing the ELRS tool to exercise the full communication flow (device discovery, parameter loading, value writes, ELRS status) inside the EdgeTX simulator. Multiple scenarios are available to simulate different states such as normal operation, disconnected links, model mismatch, and more.
51+
52+
### How it works
53+
54+
When the tool detects it is running in the EdgeTX simulator (version string ends with `-simu`), `main.lua` automatically loads the simulator module from `/SCRIPTS/CRSFSimulator/csrfsimulator.lua` and patches the protocol's `pop`, `push`, and `hasCrsfModule` functions with the mock implementations.
55+
56+
Run `make sync` (which runs `edgetx-cli dev sync`) to copy the sources -- including the dev-only `CRSFSimulator` library -- onto the simulator SD card. `edgetx-cli pkg install` omits the library automatically, so the simulator is never shipped to real hardware.
57+
58+
### Scenarios
59+
60+
The simulator supports multiple test scenarios, configurable via the `config.scenario` variable at the top of the file:
61+
62+
| Scenario | Description |
63+
|----------|-------------|
64+
| `normal` | TX + RX connected. Happy path with full telemetry and all parameters. |
65+
| `no_telemetry` | TX present but no RX telemetry. Shows "No telemetry" state. |
66+
| `reconnect` | Starts disconnected, transitions to connected after ~5 seconds. |
67+
| `model_mismatch` | TX + RX connected with Model ID mismatch flag. Triggers warning dialog. |
68+
| `armed` | TX + RX connected with "is Armed" warning flag. |
69+
| `slow_loading` | Parameter reads delayed by ~2 seconds each. Tests loading UI states. |
70+
| `no_module` | No CRSF module found. Triggers "No Module Found" error dialog. |

0 commit comments

Comments
 (0)