Skip to content

Commit 0972a35

Browse files
jknoxdevjknoxdev
committed
docs(readme): update repo structure with links and highlights table
1 parent 3d2faa9 commit 0972a35

1 file changed

Lines changed: 76 additions & 51 deletions

File tree

‎README.md‎

Lines changed: 76 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -47,12 +47,13 @@ Security goals:
4747
---
4848
## Project Status
4949

50-
✔ FSM pipeline validated
51-
✔ CryptoCell ECDSA signing working
52-
✔ BLE advertisement verified
50+
✔ FSM pipeline validated
51+
✔ CryptoCell ECDSA-P256 signing + AES-256-GCM encryption working
52+
✔ BLE extended advertisement verified
53+
✔ Gateway: BLE scanner + MQTT + SQLite audit log + ntfy.sh notifications
54+
✔ Client: native Rust TUI with live AES-256-GCM decryption
5355

54-
Current phase:
55-
Gateway receiver + MQTT + SQLite audit log
56+
Current phase: hardware power management + KiCad schematic
5657

5758
---
5859
## Architecture
@@ -74,25 +75,27 @@ Gateway receiver + MQTT + SQLite audit log
7475

7576
**Two independent threat models, one pipeline:**
7677

77-
| Trigger | Use Case | Sensor |
78-
|---|---|---|
78+
| Trigger | Use Case | Sensor |
79+
| -------------------| ----------------------------------------------------| -------------------|
7980
| `PRESSURE_BREACH` | Cabinet puncture, enclosure door open, seal broken | BME280 barometric |
80-
| `MOTION_DETECTED` | Vehicle tow, rack movement, vibration attack | MPU6050 IMU |
81-
| `DUAL_BREACH` | Full physical intrusion — moved AND breached | Both |
81+
| `MOTION_DETECTED` | Vehicle tow, rack movement, vibration attack | MPU6050 IMU |
82+
| `DUAL_BREACH` | Full physical intrusion — moved AND breached | Both |
8283

8384
Each fires independently. An attacker must defeat both sensors simultaneously to avoid detection.
8485

8586
---
8687

8788
## Hardware
8889

89-
| Component | Part | Role |
90-
| ------------| --------------------------------| ------------------------------|
91-
| Edge Node | Nordic nRF52840 MDK USB Dongle | Sensor + crypto + BLE |
92-
| IMU | MPU6050 | Motion / vibration detection |
93-
| Barometric | BME280 | Pressure delta detection |
94-
| Crypto | CryptoCell-310 (on-die) | ECDSA-P256 hardware signing |
95-
| Gateway | Raspberry Pi Zero | BLE scanner + MQTT broker |
90+
| Component | Part | Role |
91+
| -------------| -------------------------------| -------------------------------|
92+
| Edge Node | Nordic nRF52840-DK (PCA10056) | Sensor + crypto + BLE |
93+
| IMU | MPU6050 | Motion / vibration detection |
94+
| Barometric | BME280 | Pressure delta detection |
95+
| RTC | DS3231 | Battery-backed wall clock |
96+
| Crypto | CryptoCell-310 (on-die) | ECDSA-P256 + AES-256-GCM |
97+
| Gateway | Raspberry Pi 5 | BLE scanner + MQTT broker |
98+
| BLE Adapter | ASUS BT500 (Realtek, hci1) | BLE 5.0 extended adv receiver |
9699

97100
---
98101

@@ -174,44 +177,66 @@ west flash
174177

175178
```
176179
lima-node/
177-
├── .github/
178-
│ └── workflows/ # CI (PlantUML render, etc.)
179-
├── artifacts/ # Bench captures / exports
180-
├── docs/
181-
│ ├── analysis/ # Design notes / analysis
182-
│ ├── architecture/ # PlantUML sources + rendered diagrams
183-
│ │ ├── adr/ # Architecture Decision Records
184-
│ │ ├── context.puml|svg|png
185-
│ │ ├── component.puml|svg|png
186-
│ │ ├── sequence.puml|svg|png
187-
│ │ ├── state.puml|svg|png
188-
│ │ └── overview.puml|svg|png
189-
│ ├── build/ # Build / flash / dev setup
190-
│ │ ├── FLASHING.md
191-
│ │ ├── DEV_SETUP.md
192-
│ │ └── quickref.md
193-
│ └── dev/ # Session context + dev notes
194-
│ └── context.md
195-
│ ├── logs/ # Test logs / traces
196-
│ ├── media/ # Images used in docs/README
197-
│ ├── resources/ # Reference material
198-
│ └── verification/ # Validation notes + results
199-
├── firmware/ # Zephyr firmware (nRF52840)
200-
│ ├── boards/
180+
├── firmware/ # nRF52840 Zephyr firmware
201181
│ ├── src/
202-
│ │ ├── main.c
203-
│ │ ├── fsm.c
204-
│ │ ├── fsm.h
205-
│ │ └── events.h
206-
│ ├── CMakeLists.txt
207-
│ ├── Kconfig
208-
│ └── prj.conf
209-
├── LICENSE
210-
├── README.md
211-
├── SECURITY.md
212-
└── west.yml # NCS workspace manifest
182+
│ │ ├── main.c # Application entry, sensor poll loop, FSM wiring
183+
│ │ ├── fsm.c / fsm.h # Full state machine — BOOT → ARMED → SIGNING → TX
184+
│ │ ├── crypto.c / crypto.h # AES-256-GCM + ECDSA-P256 via CryptoCell-310
185+
│ │ ├── ble.c / ble.h # BLE 5.0 extended advertising
186+
│ │ ├── rtc.c / rtc.h # DS3231 RTC — wall clock, tamper detection, wakeup
187+
│ │ └── events.h # Event type definitions
188+
│ ├── boards/ # Board overlays (nRF52840-DK + MDK USB Dongle)
189+
│ ├── tests/sensor_wire/ # I2C sensor validation test
190+
│ ├── tools/provision.py # PSK + ECDSA key provisioning tool
191+
│ ├── Kconfig # LIMA-specific Kconfig symbols
192+
│ └── prj.conf # Project configuration
193+
│
194+
├── gateway/ # Rust gateway workspace (Raspberry Pi 5)
195+
│ └── crates/
196+
│ ├── gateway/src/main.rs # BLE scanner, sig verify, SQLite, MQTT, TUI
197+
│ ├── lima-types/src/lib.rs # Wire format constants — single source of truth
198+
│ └── crypto-test/ # Standalone crypto verification utility
199+
│
200+
├── client/ # Native Rust decrypt client
201+
│ └── src/
202+
│ ├── main.rs # PSK prompt, DB poll loop, TUI event loop
203+
│ ├── crypto.rs # AES-256-GCM decrypt pipeline + test suite
204+
│ ├── db.rs # SQLite read, ack, delete
205+
│ └── display.rs # ratatui TUI — decrypted LER display
206+
│
207+
├── docs/
208+
│ ├── architecture/
209+
│ │ ├── adr/ # Architecture Decision Records (ADR-001 → 006)
210+
│ │ ├── frame-record-spec.md # LER + LF wire format specification
211+
│ │ ├── *.puml # PlantUML source — auto-rendered on push
212+
│ │ └── *.png / *.svg # Rendered diagrams
213+
│ ├── analysis/threat_model.md # Threat model
214+
│ ├── verification/ # FSM, I2C, RF, signal integrity validation notes
215+
│ └── dev/
216+
│ ├── context/ # Session context files (cross-session handoff)
217+
│ ├── lima-ler-lf-spec.md # LER/LF spec (dev reference)
218+
│ └── quickref.md # Build + flash quick reference
219+
│
220+
├── CONTRIBUTING.md # How to contribute + graduation terminology 🎓
221+
├── SECURITY.md # Vulnerability disclosure policy
222+
├── COMMERCIAL_LICENSE.md # Commercial licensing terms
223+
└── west.yml # NCS workspace manifest
213224
```
214225

226+
227+
### Highlights
228+
229+
| What | Where |
230+
| ------------------------------| --------------------------------------------------------------------------------------------------------------|
231+
| Wire format spec (LER + LF) | [`docs/architecture/frame-record-spec.md`](docs/architecture/frame-record-spec.md) |
232+
| Encrypt-then-Sign pipeline | [`firmware/src/crypto.c`](firmware/src/crypto.c) |
233+
| Wire format constants (Rust) | [`gateway/crates/lima-types/src/lib.rs`](gateway/crates/lima-types/src/lib.rs) |
234+
| Gateway BLE → MQTT pipeline | [`gateway/crates/gateway/src/main.rs`](gateway/crates/gateway/src/main.rs) |
235+
| Client AES-256-GCM decrypt | [`client/src/crypto.rs`](client/src/crypto.rs) |
236+
| FSM state machine | [`firmware/src/fsm.c`](firmware/src/fsm.c) |
237+
| ADR-005: Encrypt everything | [`docs/architecture/adr/ADR-005-encrypt-everything.md`](docs/architecture/adr/ADR-005-encrypt-everything.md) |
238+
| Provisioning tool | [`firmware/tools/provision.py`](firmware/tools/provision.py) |
239+
215240
---
216241

217242
## Architecture Decision Records

0 commit comments

Comments
 (0)