# Security Mesh Node — Architecture & Development Guide

## Project Structure

```
security-new/
├── platformio.ini              # PlatformIO config (targets, libs, flags)
├── src/
│   ├── main.cpp                # Main firmware — SecurityMesh class + loop
│   ├── target.h                # Pin mappings, radio params, platform defs
│   └── variants/
│       └── promicro/           # ProMicro-specific files
├── boards/                     # Custom linker scripts
├── scripts/                    # Build helper scripts
├── .pio/                       # Build output (ignored)
```

All MeshCore library lives at `../MeshCore/`.

---

## How Radio Mesh Works

### Low-level Layer (RadioLib)
- `radio_module` (SX1262) — raw LoRa send/receive.
- `radio_driver` (CustomSX1262Wrapper) — RadioLib wrapper. Provides `getCurrentRSSI()`, `setParams()`, `setTxPower()`.

### Mesh Layer (MeshCore)
- `mesh::Mesh` — main class that manages flooding, routing, encryption, channel storage.
- `mesh::Dispatcher` — base of Mesh (packet scheduling, radio control).
- `mesh::GroupChannel` — channel with `hash[1]` and `secret[32]`.
- `mesh::Packet` — a mesh packet. Obtained from `PacketManager` (pool of 16 slots).

### Lifecycle

```
1. radio_module.begin()          — init SX1262
2. radio_driver.setParams(...)   — freq, BW, SF, CR
3. Mesh.begin()                  — starts listening
4. Mesh.loop() loop()            — pumps radio ISR, processes incoming
5. onGroupDataRecv() callback    — called when encrypted group msg arrives
```

---

## SecurityMesh Class

### Channel Derivation (`setup_channel()`)

```
SHA256("1234") → 32 bytes key
mesh_channel.secret = key[0..15]   (first 16 bytes)
mesh_channel.hash  = SHA256(secret)[0..0]  (first 1 byte, PATH_HASH_SIZE=1)
```

### Critical Virtual Overrides

#### `searchChannelsByHash()`
**WHY IT'S NEEDED:** `Mesh::loop()` calls `searchChannelsByHash()` to match incoming packet hashes against stored channels. The base implementation returns 0 (no matches). Without this override, **every incoming group message is silently dropped** and `onGroupDataRecv` is never called.

```cpp
int searchChannelsByHash(const uint8_t* hash, mesh::GroupChannel channels[], int max_matches) override {
    if (max_matches > 0 && channel_ready
        && memcmp(hash, mesh_channel.hash, sizeof(mesh_channel.hash)) == 0) {
        channels[0] = mesh_channel;
        return 1;  // found 1 match
    }
    return 0;
}
```

`sizeof(mesh_channel.hash)` = `PATH_HASH_SIZE` = 1 byte.

#### `onGroupDataRecv()`
Called for each decrypted group message that matched a channel. Format: `[4 bytes ts][1 byte type][text]`. Type byte must be 0 for text.

### Sending (`send_text()`)

```cpp
void send_text(const char* text) {
    uint8_t buf[256];
    buf[0..3] = timestamp (4 bytes)
    buf[4]    = 0 (type: text)
    buf[5..]  = text
    Packet* pkt = createGroupDatagram(PAYLOAD_TYPE_GRP_TXT, mesh_channel, buf, 5 + text_len);
    sendFlood(pkt, 0, 1);  // 1 hop
}
```

`sendFlood` with `path_hash_size=1` means 0-hop (immediate neighbors only). Increase to flood across the mesh.

---

## Command Processing

All commands are processed in `onGroupDataRecv()`:

### Preprocessing
1. **Trim trailing spaces** — `"status "` → `"status"`
2. **Lowercase** — `"Status"` → `"status"`
3. **Strip prefix** — `"Security: status"` → `"status"` (anything before `": "`)
4. **Trim leading spaces**

### Command Table

| Command | Action | Response |
|---------|--------|----------|
| `help` | list commands | `help:...` |
| `ohrana on` | arm, relay1 ON | `ohrana on ok` |
| `ohrana off` | disarm, relay1 OFF | `ohrana off ok` |
| `relay1 on` | relay1 ON (direct) | `relay1 on ok` |
| `relay1 off` | relay1 OFF (direct) | `relay1 off ok` |
| `relay2 on` | relay2 ON | `relay2 on ok` |
| `relay2 off` | relay2 OFF | `relay2 off ok` |
| `status` | report state | `status:armed/off temp:±X.XC hall:trig/ok motion:trig/ok` |
| `ver` | build date | `build:Mon DD YYYY HH:MM:SS` |
| `scan` | noise floor | `noise:-XXXdBm` |
| `security_conf <name>` | change channel | `channel:<name>` |

### Auto-Sent Messages
- **Startup:** `poweron Mon DD YYYY HH:MM:SS` — sent 10s after boot.
- **Hall alert:** `alert:hall` — when armed and reed opens.
- **Motion alert:** `alert:motion` — when armed and PIR triggers.

Cooldown: 10 minutes between alerts (ALERT_COOLDOWN_MS).

---

## Hardware

| Pin (nRF52) | Pin (ProMicro) | Function |
|-------------|----------------|----------|
| 30 | 13 | NSS (LoRa SPI CS) |
| 29 | 12 | SCK |
| 31 | 14 | MOSI |
| 2 | 15 | MISO |
| 7 | 11 | DIO1 (LoRa IRQ) |
| 6 | 10 | RST |
| 10 | 16 | BUSY |
| — | 21 | POWER_EN (ProMicro only) |
| 12 | 0 | REED (hall sensor) |
| 11 | 1 | PIR (motion) |
| 3 | 2 | DS18B20 (temp) |
| 4 | 3 | RELAY_1 |
| 5 | 4 | RELAY_2 |
| 13 | 22 | LED_STATUS |

**Reference:** `target.h` lines 25–114.

---

## Radio Config

| Param | Value |
|-------|-------|
| Frequency | 868.731018 MHz |
| Bandwidth | 62.5 kHz |
| Spreading Factor | 7 |
| Coding Rate | 7 (4/7) |
| TX Power | 22 dBm |
| TCXO voltage | 1.8V |
| Current limit | 140 mA |
| RX Boosted Gain | on |
| DIO2 as RF switch | on |

`PATH_HASH_MODE=0` → `PATH_HASH_SIZE=1` (minimal hash, maximum throughput).

---

## Build & Upload

```bash
# Build
pio run -e promicro_security

# Upload (via nrfutil)
pio run -e promicro_security -t upload

# Monitor
pio device monitor -b 115200
```

Current resource usage: RAM 8%, Flash 36.5%.

---

## Common Pitfalls & Debugging

### `onGroupDataRecv` not called despite LED blink
The LED blink (3 fast flashes) is the first thing in `onGroupDataRecv`. If LED doesn't blink:
- Check `searchChannelsByHash()` override — it's required.
- Check hash match: both sides must derive the same `secret` and `hash` from passphrase.
- Check radio config matches (freq, BW, SF, CR).

### No response despite LED blinking
- Command was received (LED blinked) but processing or send failed.
- **Test with simple response** — if `send_text("ok")` fails but `send_text("relay2 on ok")` works, check response length/SNPRINTF.
- `sendFlood` with `path_hash_size=1` sends only to neighbors. If response doesn't arrive at the remote app, check app's mesh routing or increase path_hash_size.

### `send_text()` doesn't actually send
- `createGroupDatagram` may return NULL if packet pool is full (16 slots).
- `rtc_clock.getCurrentTime()` returning bogus data (VolatileRTCClock starts from 0, fine).

### Adding a new command
1. Add `else if` block in `onGroupDataRecv()` after line 168.
2. Use `strcmp(cmd, "command") == 0` for exact match.
3. Call `send_text("response")` to reply.
4. Update the `help` string.

### Config persistent storage
- `InternalFS` (LittleFS) on nRF52 internal flash.
- `SecurityConfig`: armed + relay2 state saved as binary struct.
- File: `/security.cfg`, magic `0x53454355`.

---

## Key Files in MeshCore Library

| File | What it provides |
|------|-----------------|
| `MeshCore/src/Mesh.h` | `Mesh`, `GroupChannel`, virtual methods |
| `MeshCore/src/MeshCore.h` | Constants (`PUB_KEY_SIZE`, `PATH_HASH_SIZE`, etc.) |
| `MeshCore/src/Dispatcher.h` | `Dispatcher`, packet scheduling |
| `MeshCore/src/helpers/SimpleMeshTables.h` | Duplicate packet detection |
| `MeshCore/src/helpers/StaticPoolPacketManager.h` | Packet memory pool |
| `MeshCore/src/helpers/ChannelDetails.h` | Channel helper structs |
| `MeshCore/src/helpers/NRF52Board.h` | nRF52 board abstraction |

---

## Things That Won't Work

- **BLE** — not included. No `BLESerialInterface`, no `BaseChatMesh`.
- **`BaseChatMesh`** — not used. SecurityMesh inherits directly from `mesh::Mesh`.
- **Serial commands** — not processed. Serial is for debug output only.
- **`onPeerDataRecv`** — not used. Group messaging only, no direct peer messages.