diff --git a/README.md b/README.md index fdd9456..3d9ce11 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,94 @@ -# RatDeck +
-**v1.5.2** | [Ratspeak.org](https://ratspeak.org) +# ratdeck -Standalone [Reticulum](https://reticulum.network/) mesh node + [LXMF](https://github.com/markqvist/LXMF) encrypted messenger for the [LilyGo T-Deck Plus](https://www.lilygo.cc/products/t-deck-plus). +**Encrypted mesh messenger for the LilyGo T-Deck Plus** -Not an RNode. Not a gateway. A fully self-contained Reticulum instance with a keyboard, trackball, and screen — no host computer required. + + + +
RatDeck booting up, showing the Ratspeak splash screenRatDeck running, showing the home screen with tabs
-``` -+----------------------------------------------+ -| [|||] Ratspeak [87%] | -+----------------------------------------------+ -| | -| CONTENT AREA | -| 320x240, LVGL v8.4 | -+----------------------------------------------+ -| Home Friends Msgs Peers Setup | -+----------------------------------------------+ -``` +A standalone Reticulum node with a keyboard, trackball, and screen — no computer required. -## Features +
-- **Encrypted LoRa messaging** — LXMF protocol, Ed25519 signatures, per-conversation storage -- **Mesh networking** — Reticulum endpoint or transport node, automatic path discovery -- **Node discovery** — See who's online, save contacts, manage friends -- **WiFi bridging** — TCP client to remote Reticulum nodes, or AP mode to bridge your desktop to LoRa -- **BLE transport** — Not yet available -- **Identity management** — Easily swap and manage different identities -- **Dual storage** — LittleFS flash + SD card with atomic writes and automatic backup -- **OTA-ready** — Check for firmware updates directly from the device +--- -Built on [microReticulum](https://github.com/attermann/microReticulum) with a register-level SX1262 driver and LVGL v8.4. +RatDeck turns a [LilyGo T-Deck Plus](https://www.lilygo.cc/products/t-deck-plus) into a fully self-contained [Reticulum](https://reticulum.network/) mesh node. It's not an RNode and it's not a gateway — it's a complete encrypted communicator you carry with you. -## Hardware +End-to-end encrypted [LXMF](https://github.com/markqvist/LXMF) messaging over LoRa, WiFi bridging to the wider Reticulum network, node discovery, multiple identities, transport relay mode, and a configurable SX1262 radio — all through an LVGL touchscreen UI with a physical QWERTY keyboard and trackball. -| Component | Part | Notes | -|-----------|------|-------| -| **Board** | LilyGo T-Deck Plus | ESP32-S3, 16MB flash, 8MB PSRAM, 320x240 IPS, QWERTY keyboard, trackball | -| **Radio** | Integrated SX1262 | 915 MHz ISM, TCXO 1.8V, DIO2 RF switch | -| **Storage** | microSD card | Optional but recommended. FAT32, any size | +## Get one -## Quick Start +1. Buy a **LilyGo T-Deck Plus** (~$55 — [LilyGo](https://www.lilygo.cc/), [AliExpress](https://aliexpress.com), or Amazon) +2. Attach a **915 MHz antenna** (SMA, usually included) +3. Flash the firmware + +### Flash it + +The easiest way is the **[web flasher](https://ratspeak.org/download.html)** — plug in USB, click flash, done. + +To build from source: ```bash -git clone https://github.com/ratspeak/ratdeck.git -cd Ratdeck -python3 -m platformio run # build -python3 -m platformio run --target upload # flash +git clone https://github.com/ratspeak/ratdeck +cd ratdeck +pip install platformio +python3 -m platformio run --target upload ``` -First build pulls the ESP32-S3 toolchain and all dependencies automatically. +First build takes a couple minutes while PlatformIO pulls the toolchain. After that it's fast. -### Web Flash +## Using it -No build tools? Visit **[ratspeak.org/download](https://ratspeak.org/download.html)** to flash from your browser. +On first boot, RatDeck generates a Reticulum identity and shows a name input screen. Your LXMF address (32-character hex string) is what you share with contacts. -## First Boot +**Tabs:** Home, Friends, Msgs, Peers, Setup — navigate with the trackball or `,` / `/` keys. -1. Boot animation with progress bar -2. SX1262 radio initializes (915 MHz, Balanced preset) -3. SD card checked, `/ratputer/` directories auto-created -4. Reticulum identity generated (Ed25519 keypair, triple-redundant backup) -5. Name input screen (optional — auto-generates if skipped) -6. Home screen — you're on the mesh +**Sending a message:** Find someone in Peers, click with the trackball to open chat, type your message, hit Enter. Status goes yellow (sending) → green (delivered). -## Usage +**Radio presets** (Setup → Radio): +- **Long Range** — SF12, 62.5 kHz, 22 dBm. Maximum distance, very slow. +- **Balanced** — SF9, 125 kHz, 17 dBm. Good default. +- **Fast** — SF7, 250 kHz, 14 dBm. Short range, quick transfers. -### Navigation +All radio parameters are individually tunable. Changes apply immediately, no reboot. -| Input | Action | -|-------|--------| -| Trackball up/down | Scroll lists | -| Trackball left/right | Cycle tabs | -| Trackball click | Select / confirm | -| Long-press (1.2s) | Context menu | -| `,` / `/` | Previous / next tab | -| Enter | Select / send | -| Esc / Backspace | Back / cancel | -| Ctrl+H | Hotkey help overlay | +### WiFi bridging -### Tabs +RatDeck can bridge your laptop to the LoRa mesh: -| Tab | What It Shows | -|-----|---------------| -| **Home** | Name, LXMF address, connection status, online nodes | -| **Friends** | Saved contacts with display names | -| **Msgs** | Conversations — sorted by most recent, preview, unread dots | -| **Peers** | All discovered nodes with RSSI/SNR | -| **Setup** | Device, Display, Radio, Network, Audio, Info, System | +1. Set WiFi to **AP mode** in Setup → Network (creates `ratdeck-XXXX`, password: `ratspeak`) +2. Connect your laptop to that network +3. Add to your Reticulum config: -### Sending a Message +```ini +[[ratdeck]] + type = TCPClientInterface + target_host = 192.168.4.1 + target_port = 4242 +``` -1. Another node appears in **Peers** (or connect via WiFi) -2. Select the node, press Enter to open chat -3. Type your message, press Enter to send -4. Status: yellow (sending) → green (delivered) → red (failed) +Your desktop Reticulum instance now reaches the LoRa mesh through RatDeck's radio. -## LoRa Radio +Or use **STA mode** to connect to existing WiFi and reach remote nodes like `rns.ratspeak.org:4242`. -Three presets in Settings → Radio: +### Transport mode -| Preset | SF | BW | CR | TX | Use Case | -|--------|----|----|----|----|----------| -| **Balanced** | 9 | 125 kHz | 4/5 | 17 dBm | General use | -| Long Range | 12 | 62.5 kHz | 4/8 | 22 dBm | Maximum range | -| Fast | 7 | 250 kHz | 4/5 | 14 dBm | Short range, fast | +Enable in Setup → Network to turn your RatDeck into a mesh relay — it'll forward packets and maintain routing tables for other nodes. Best for fixed, elevated positions with good radio coverage. -All parameters individually configurable. Changes apply immediately. +## Docs -## WiFi & Networking +The detailed stuff lives in [`docs/`](docs/): -| Mode | Description | -|------|-------------| -| **STA** (default) | Connect to your WiFi, TCP client to remote Reticulum nodes | -| **AP** | Creates `ratdeck-XXXX` hotspot, TCP server on port 4242 | -| **OFF** | LoRa only, saves power | - -**Connect to the mesh over WiFi:** Settings → Network → enter WiFi creds → add TCP endpoint (e.g., `rns.ratspeak.org:4242`). - -**Bridge your desktop to LoRa:** Set AP mode → connect laptop to `ratdeck-XXXX` (password: `ratspeak`) → add `TCPClientInterface` to `~/.reticulum/config` pointing at `192.168.4.1:4242`. - -## Transport Mode - -Default: **endpoint** (handles own traffic). Enable **Transport Node** in Settings → Network to relay packets and maintain routing tables for the mesh. - -## Status - -| Subsystem | Status | -|-----------|--------| -| LoRa (SX1262) | Working — async TX/RX, configurable presets | -| LXMF messaging | Working — send/receive/store, Ed25519, delivery tracking | -| LVGL UI | Working — 5 tabs, chat bubbles, settings, contacts | -| WiFi STA + TCP | Working — auto-reconnect, live server switching | -| WiFi AP | Working — TCP server, HDLC framing, desktop bridge | -| BLE Sideband | Not yet available | -| Node discovery | Working — announces, friend management | -| SD + Flash storage | Working — dual-backend, atomic writes | -| Identity management | Working — multi-slot, triple-redundant | -| Transport mode | Working — endpoint or relay | -| Touchscreen | Disabled — GT911 needs calibration | -| GPS | Pins defined — not yet implemented | - -## Documentation - -| Doc | Contents | -|-----|----------| -| **[Quick Start](docs/QUICKSTART.md)** | Build, flash, first boot, first message | -| [Building](docs/BUILDING.md) | Build flags, flashing, CI/CD, partition table | -| [Architecture](docs/ARCHITECTURE.md) | Layer diagram, data flow, design decisions | -| [Development](docs/DEVELOPMENT.md) | Adding screens, settings, transports, debugging | -| [Pin Map](docs/PINMAP.md) | Full T-Deck Plus GPIO assignments | -| [Hotkeys](docs/HOTKEYS.md) | Keyboard shortcuts and navigation | -| [Troubleshooting](docs/TROUBLESHOOTING.md) | Radio, build, boot, storage issues | +- **[Quick Start](docs/QUICKSTART.md)** — build, flash, first boot, first message +- [Building](docs/BUILDING.md) — build flags, flashing, CI, partition table +- [Architecture](docs/ARCHITECTURE.md) — layer diagram, data flow, design decisions +- [Development](docs/DEVELOPMENT.md) — adding screens, settings, transports +- [Hotkeys](docs/HOTKEYS.md) — keyboard shortcuts and navigation +- [Pin Map](docs/PINMAP.md) — full T-Deck Plus GPIO assignments +- [Troubleshooting](docs/TROUBLESHOOTING.md) — radio, build, boot, storage ## License diff --git a/assets/card3.JPG b/assets/card3.JPG new file mode 100644 index 0000000..68bc3ba Binary files /dev/null and b/assets/card3.JPG differ diff --git a/assets/card4.JPG b/assets/card4.JPG new file mode 100644 index 0000000..5394873 Binary files /dev/null and b/assets/card4.JPG differ