{"id":23069058,"url":"https://github.com/gretel/rns-if-espnow","last_synced_at":"2025-07-09T01:40:36.831Z","repository":{"id":267059201,"uuid":"900130404","full_name":"gretel/rns-if-espnow","owner":"gretel","description":"ESP-NOW interface for Reticulum Network Stack","archived":false,"fork":false,"pushed_at":"2024-12-28T03:27:19.000Z","size":49,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T23:17:08.284Z","etag":null,"topics":["38c8","asyncio","esp-now","esp32","espnow","hdlc","micropython","micropython-esp32","reticulum"],"latest_commit_sha":null,"homepage":"https://www.espressif.com/en/solutions/low-power-solutions/esp-now","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gretel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-08T00:00:36.000Z","updated_at":"2025-01-19T20:00:30.000Z","dependencies_parsed_at":"2024-12-08T03:19:01.447Z","dependency_job_id":"25a9e841-c89a-4bd5-933f-8b314a0a44f7","html_url":"https://github.com/gretel/rns-if-espnow","commit_stats":null,"previous_names":["gretel/rns-if-espnow"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gretel%2Frns-if-espnow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gretel%2Frns-if-espnow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gretel%2Frns-if-espnow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gretel%2Frns-if-espnow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gretel","download_url":"https://codeload.github.com/gretel/rns-if-espnow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246981151,"owners_count":20863825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["38c8","asyncio","esp-now","esp32","espnow","hdlc","micropython","micropython-esp32","reticulum"],"created_at":"2024-12-16T06:12:47.220Z","updated_at":"2025-04-03T09:44:33.086Z","avatar_url":"https://github.com/gretel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📡 RNS Interface ESP-NOW \n\nESP32-based wireless interface for [Reticulum Network Stack](https://github.com/markqvist/Reticulum) using ESP-NOW.\n\n## ⚠️ Current Status\n\nThis code is functional and ready for testing. Core features are implemented:\n\n- 🎯 HDLC framing of serial data\n- 📻 ESP-NOW transport with packet fragmentation and reassembly\n- 🔧 Configuration via `AT` commands\n- 💾 Persistent configuration storage\n\n## 🤔 Why?\n\n[ESP-NOW](https://github.com/espressif/esp-now) provides a hardware interface for Reticulum networks:\n\n- 🏗️ No infrastructure required - direct peer-to-peer\n- 🚀 High bandwidth (up to 1Mbps) \n- ⚡ Low latency (\u003c4ms)\n- 💰 Built into most ESP32 (~$5)\n- 🧩 Works with `SerialInterface`\n\n## 🐍 Why MicroPython?\n\nMicroPython provides ideal characteristics for RNS ESP-NOW interface development:\n\n- Interactive REPL and runtime execution enables fast prototyping and testing\n- Directly aligns with Reticulum's Python codebase, allowing shared patterns\n- AsyncIO enables efficient concurrent I/O handling\n- Clear, readable code structure\n\n### 📸 Flashing\n\nFirst steps first:\n\n* MicroPython needs to be [flashed](https://docs.micropython.org/en/latest/esp32/tutorial/intro.html) to the ESP32\n* The [mpremote](https://github.com/micropython/micropython/tree/master/tools/mpremote) tool is recommended for device management and file operations.\n\n## 🌐 System Design\n\nThe system utilizes an event-driven architecture with components communicating through a lightweight event bus.\n\n### 📍 Core Components\n\n```mermaid\nclassDiagram\n    class EventBus {\n        -dict listeners\n        +add_listener(event: str, listener: func)\n        +remove_listener(event: str, listener: func) \n        +emit(event: str, data: any)\n    }\n\n    class RNSNOW {\n        -Config config\n        -Logger log\n        -HDLCProcessor hdlc\n        -Fragmentor fragmentor\n        -Hardware hw\n        -UART uart\n        -EventBus event_bus\n        -ATCommands at\n        +process_uart()\n        +process_espnow()\n    }\n\n    class HDLCProcessor {\n        -Logger log\n        -bytearray rx_buffer\n        -bool in_frame\n        -bool escape\n        +frame_data(data: bytes)\n        +process_byte(byte: int)\n    }\n\n    class Fragmentor {\n        -Logger log\n        -dict _reassembly\n        +fragment_data(data: bytes)\n        +process_fragment(fragment: bytes)\n    }\n\n    class Hardware {\n        -Pin led\n        -Pin btn1\n        -EventBus event_bus\n        +blink_led(times: int)\n        +check_buttons()\n    }\n\n    class ATCommands {\n        -Config config\n        -EventBus event_bus\n        -UART uart\n        +process_byte(byte: int)\n        +process_command(cmd: str)\n    }\n\n    RNSNOW --\u003e EventBus\n    RNSNOW --\u003e HDLCProcessor\n    RNSNOW --\u003e Fragmentor\n    RNSNOW --\u003e Hardware\n    RNSNOW --\u003e ATCommands\n    Hardware --\u003e EventBus\n    ATCommands --\u003e EventBus\n```\n\n### 🎬 Events\n\nThe system responds to several core events:\n\n- **Control Events**: Channel changes (`ch_ch`), baudrate changes (`ch_bd`)\n- **Hardware Events**: Button presses, LED signals\n- **Network Events**: ESP-NOW transmission/reception, ping requests/responses\n- **Configuration Events**: Settings changes via AT commands\n\n### 🔌 UART Processing\n\n- Single UART interface for both data and AT commands\n- Configurable pins and baud rate\n- `AT` command set for configuration\n- HDLC frame processing for RNS packets\n\n### 📻 ESP-NOW Transport \n\n- WiFi station mode (no AP needed)\n- Group broadcast approach\n- Long range mode support\n- Packet fragmentation for RNS MTU compliance\n\n## 🔄 Data Flow\n\n```mermaid\nsequenceDiagram\n    participant RNS as RNS Daemon\n    participant UART as UART Handler\n    participant HDLC as HDLC Processor\n    participant FRAG as Fragmentor\n    participant NOW as ESP-NOW\n    \n    RNS-\u003e\u003eUART: Serial Data\n    UART-\u003e\u003eHDLC: Process Bytes\n    HDLC-\u003e\u003eFRAG: Complete Frame\n    FRAG-\u003e\u003eNOW: Fragments\n    NOW--\u003e\u003eFRAG: Fragments\n    FRAG--\u003e\u003eHDLC: Complete Frame\n    HDLC--\u003e\u003eUART: Frame Data\n    UART--\u003e\u003eRNS: Serial Data\n```\n\n## 👾 Hardware\n\nThe interface uses a minimal hardware configuration:\n\n```mermaid\ngraph TD\n    subgraph \"ESP32 Development Board\"\n        CPU[ESP32 MCU]\n        \n        subgraph \"Peripherals\"\n            LED[LED - Pin 10]\n            BTN1[Button1 - Pin 37]\n        end\n        \n        subgraph \"Communications\"\n            UART[UART1 - Data + AT]\n            WIFI[WiFi/ESP-NOW]\n        end\n    end\n    \n    subgraph \"Connections\"\n        RNS[RNS Daemon]\n        AIR[Wireless Medium]\n    end\n    \n    CPU --\u003e LED\n    BTN1 --\u003e CPU\n    CPU \u003c--\u003e UART\n    CPU \u003c--\u003e WIFI\n    \n    UART \u003c--\u003e RNS\n    WIFI \u003c--\u003e AIR\n    \n    classDef peripheral fill:#f9f,stroke:#333\n    classDef comm fill:#bbf,stroke:#333\n    class LED,BTN1 peripheral\n    class UART,WIFI comm\n```\n\n## 📡 Configuration\n\nThe device can be configured via AT commands:\n\n- `AT` - Test command\n- `ATI` - Show device info  \n- `AT\u0026F` - Factory reset\n- `AT\u0026V` - View config\n- `AT\u0026W` - Write config\n- `AT+DESC=text` - Set description\n- `AT+BAUD=rate` - Set baudrate\n- `AT+CHAN=n` - Set WiFi channel (1-14)\n- `AT+MAC=xxxxxxxxxxxx` - Set target MAC\n- `AT+LOG=n` - Set log level (0-4)\n- `AT+PROTO=type` - Set protocol (default/lr)\n- `AT+PINS=name,val - Configure pin (name: led/button1/button2/tx/rx, val: pin number or NONE)`\n- `AT+RESET` - Reset device\n\nSettings are stored in `config.json` and persist across reboots.\n\n## 🎯 Development Target\n\nWhile this interface should work on any ESP32-based platform, current development and testing is being done exclusively on ESP32-S3 based boards. Development is ongoing and testing with other ESP32 platforms will follow as the project matures.\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n- 🐛 Report bugs\n- 💡 Suggest features  \n- 🔧 Submit pull requests\n- 📢 Share your experiences\n\n## 🎫 Sponsor\n\nThis work is supported by the [Critical Decentralisation Cluster (CDC)](https://decentral.community/) - thank you very much!\n\n## 📄 License\n\nMIT License - See LICENSE file for full details.\n\n## 🖇 References\n\n- https://github.com/espressif/esp-now\n- https://docs.espressif.com/projects/esp-faq/en/latest/application-solution/esp-now.html\n- https://github.com/espressif/esp-now/blob/master/User_Guide.md\n- https://docs.micropython.org/en/latest/library/espnow.html\n- https://github.com/micropython/micropython-lib/blob/master/micropython/aioespnow/aioespnow.py","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgretel%2Frns-if-espnow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgretel%2Frns-if-espnow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgretel%2Frns-if-espnow/lists"}