@seeed-studio/meshtastic 0.1.1 → 0.2.1

package/README.md

@@ -1,136 +1,257 @@
-# openclaw-meshtastic
+<p align="center">
+  <img src="media/GoMeshClaw.png" width="700" alt="Meshtastic LoRa hardware" />
+</p>
 
-OpenClaw channel plugin for [Meshtastic](https://meshtastic.org/) LoRa mesh networks.
+# MeshClaw: OpenClaw Meshtastic Channel Plugin
 
-Lets your OpenClaw gateway send and receive messages over Meshtastic devices — via USB serial, HTTP (WiFi), or MQTT broker.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="npm version" src="https://img.shields.io/npm/v/@seeed-studio/meshtastic.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="license" src="https://img.shields.io/npm/l/@seeed-studio/meshtastic.svg" />
+  </a>
+  <a href="https://github.com/openclaw/openclaw">
+    <img alt="openclaw compat" src="https://img.shields.io/badge/OpenClaw-2026.3.x-blue" />
+  </a>
+</p>
 
+<!-- LANG_SWITCHER_START -->
 <p align="center">
-  <img src="media/hardware.jpg" width="400" alt="Meshtastic LoRa hardware with Seeed WM1302 module" />
+  <b>English</b> | <a href="README.zh-CN.md">中文</a> | <a href="README.ja.md">日本語</a> | <a href="README.fr.md">Français</a> | <a href="README.pt.md">Português</a> | <a href="README.es.md">Español</a>
 </p>
+<!-- LANG_SWITCHER_END -->
+
+**MeshClaw** is an OpenClaw channel plugin that lets your AI gateway send and receive messages over Meshtastic — no internet, no cell towers, just radio waves. Talk to your AI assistant from the mountains, the ocean, or anywhere the grid doesn't reach.
+
+⭐ Star us on GitHub — it motivates us a lot!
+
+> [!IMPORTANT]
+> This is a **channel plugin** for the [OpenClaw](https://github.com/openclaw/openclaw) AI gateway — not a standalone application. You need a running OpenClaw instance (Node.js 22+) to use it.
+
+[Documentation][docs] · [Hardware Guide](#recommended-hardware) · [Report Bug][issues] · [Request Feature][issues]
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Recommended Hardware](#recommended-hardware)
+- [Features](#features)
+- [Capabilities & Roadmap](#capabilities--roadmap)
+- [Demo](#demo)
+- [Quick Start](#quick-start)
+- [Setup Wizard](#setup-wizard)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph mesh ["📻 LoRa Mesh Network"]
+        N["Meshtastic Nodes"]
+    end
+    subgraph gw ["⚙️ OpenClaw Gateway"]
+        P["Meshtastic Plugin"]
+        AI["AI Agent"]
+    end
+    N -- "Serial (USB)" --> P
+    N -- "HTTP (WiFi)" --> P
+    N -. "MQTT (Broker)" .-> P
+    P <--> AI
+```
 
-## Demo
+The plugin bridges Meshtastic LoRa devices and the OpenClaw AI agent. It supports three transport modes:
+
+- **Serial** — direct USB connection to a local Meshtastic device
+- **HTTP** — connects to a device over WiFi / local network
+- **MQTT** — subscribes to a Meshtastic MQTT broker, no local hardware needed
 
-https://github.com/user-attachments/assets/demo.mp4
+Inbound messages go through access control (DM policy, group policy, mention gating) before reaching the AI. Outbound replies are stripped of markdown formatting (LoRa devices can't render it) and chunked to fit radio packet size limits.
 
-> The video above shows OpenClaw communicating over a Meshtastic LoRa mesh network. If it doesn't load, see [media/demo.mp4](media/demo.mp4).
+## Recommended Hardware
+
+<p align="center">
+  <img src="media/XIAOclaw.png" width="760" alt="Meshtastic device with Seeed XIAO module" />
+</p>
+
+| Device                        | Best for                | Link               |
+| ----------------------------- | ----------------------- | ------------------ |
+| XIAO ESP32S3 + Wio-SX1262 kit | Entry-level development | [Buy][hw-xiao]     |
+| Wio Tracker L1 Pro            | Portable field gateway    | [Buy][hw-wio]      |
+| SenseCAP Card Tracker T1000-E | Compact tracker         | [Buy][hw-sensecap] |
+
+No hardware? MQTT transport connects via broker — no local device required.
+
+Any Meshtastic-compatible device works.
 
 ## Features
 
-- **Three transport modes**
-  - **Serial** — connect a Meshtastic device via USB (e.g. `/dev/ttyUSB0`)
-  - **HTTP** — connect over WiFi to a device's HTTP API (e.g. `meshtastic.local`)
-  - **MQTT** — connect through an MQTT broker (e.g. `mqtt.meshtastic.org`), no local hardware needed
-- **Direct messages and group channels** — supports both DM and mesh channel conversations
-- **Access control** — DM policy (open / pairing / allowlist), per-channel allowlists, mention-gating for group channels
-- **Multi-account** — run multiple Meshtastic connections with independent configs
-- **LoRa region selection** — configure device region on connect (US, EU_868, CN, JP, etc.)
-- **Device display name** — set node longName, also used as @mention trigger in channels
-- **Interactive onboarding** — guided setup wizard via `openclaw setup`
-- **Auto-reconnect** — resilient connection handling with configurable retry
+- **AI Agent Integration** — Bridges OpenClaw AI agents with Meshtastic LoRa mesh networks. Enables intelligent communication without cloud dependency.
+
+- **Three Transport Modes** — Serial (USB), HTTP (WiFi), and MQTT support
+
+- **DM & Group Channels with Access Control** — Supports both conversation modes with DM allowlists, channel response rules, and mention-gating
+
+- **Multi-Account Support** — Run multiple independent connections simultaneously
+
+- **Resilient Mesh Communication** — Auto-reconnect with configurable retries. Handles connection drops gracefully.
 
-## Requirements
+## Capabilities & Roadmap
 
-- [OpenClaw](https://github.com/openclaw/openclaw) installed and running
-- Node.js 22+
-- For serial transport: a Meshtastic device connected via USB
-- For HTTP transport: a Meshtastic device on the same network
-- For MQTT transport: access to an MQTT broker (public `mqtt.meshtastic.org` works out of the box)
+The plugin treats Meshtastic as a first-class channel — just like Telegram or Discord — enabling AI conversations and skill invocation entirely over LoRa radio, without internet dependency.
 
-## Install
+| Query Information Offline                                    | Cross-Channel Bridge: Send from off-grid, receive anywhere | 🔜 What's next:                                               |
+| ------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------ |
+| <img src="media/image1.png" alt="Query Information Offline" /> | <img src="media/image2.png" alt="Cross-Channel Bridge" />  | We plan to ingest real-time node data (GPS location, environmental sensors, device status) into OpenClaw's context, enabling the AI to monitor mesh network health and broadcast proactive alerts without waiting for user queries. |
+
+## Demo
+
+<div align="center">
+
+https://github.com/user-attachments/assets/837062d9-a5bb-4e0a-b7cf-298e4bdf2f7c
+
+</div>
+
+Fallback: [media/demo.mp4](media/demo.mp4)
+
+## Quick Start
 
 ```bash
+# 1. Install plugin
 openclaw plugins install @seeed-studio/meshtastic
-```
 
-Or install from a local directory during development:
+# 2. Guided setup — walks you through transport, region, and access policy
+openclaw onboard
 
-```bash
-git clone https://github.com/Seeed-Solution/openclaw-meshtastic.git
-openclaw plugins install -l ./openclaw-meshtastic
+# 3. Verify
+openclaw channels status --probe
 ```
 
-## Configuration
+<p align="center">
+  <img src="media/setup-screenshot.png" width="700" alt="OpenClaw setup wizard" />
+</p>
 
-### Interactive setup
+## Setup Wizard
 
-```bash
-openclaw setup
-# Select "Meshtastic" when prompted for channel
-```
+Running `openclaw onboard` launches an interactive wizard that walks you through each configuration step. Below is what each step means and how to choose.
+
+### 1. Transport
 
-The wizard walks you through transport selection, connection details, region, access policy, and channel config.
+How the gateway connects to the Meshtastic mesh:
+
+| Option            | Description                                                  | Requires                                         |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------ |
+| **Serial** (USB)  | Direct USB connection to a local device. Auto-detects available ports. | Meshtastic device plugged in via USB             |
+| **HTTP** (WiFi)   | Connects to a device over the local network.                 | Device IP or hostname (e.g. `meshtastic.local`)  |
+| **MQTT** (broker) | Connects to the mesh via an MQTT broker — no local hardware needed. | Broker address, credentials, and subscribe topic |
+
+### 2. LoRa Region
+
+> Serial and HTTP only. MQTT derives the region from the subscribe topic.
+
+Sets the radio frequency region on the device. Must match your local regulations and other nodes on the mesh. Common choices:
+
+| Region   | Frequency           |
+| -------- | ------------------- |
+| `US`     | 902–928 MHz         |
+| `EU_868` | 869 MHz             |
+| `CN`     | 470–510 MHz         |
+| `JP`     | 920 MHz             |
+| `UNSET`  | Keep device default |
+
+See [Meshtastic region docs](https://meshtastic.org/docs/getting-started/initial-config/#lora) for the full list.
+
+### 3. Node Name
+
+The device's display name on the mesh. Also used as the **@mention trigger** in group channels — other users send `@OpenClaw` to talk to your bot.
+
+- **Serial / HTTP**: optional — auto-detects from the connected device if left empty.
+- **MQTT**: required — there is no physical device to read the name from.
+
+### 4. Channel Access (`groupPolicy`)
+
+Controls whether and how the bot responds in **mesh group channels** (e.g. LongFast, Emergency):
+
+| Policy               | Behavior                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `disabled` (default) | Ignores all group channel messages. Only DMs are processed.  |
+| `open`               | Responds in **every** channel on the mesh.                   |
+| `allowlist`          | Responds only in **listed** channels. You will be prompted to enter channel names (comma-separated, e.g. `LongFast, Emergency`). Use `*` as a wildcard to match all. |
+
+### 5. Require Mention
+
+> Only appears when channel access is enabled (not `disabled`).
+
+When enabled (default: **yes**), the bot only responds in group channels when someone mentions its node name (e.g. `@OpenClaw how's the weather?`). This prevents the bot from replying to every single message in the channel.
+
+When disabled, the bot responds to **all** messages in allowed channels.
+
+### 6. DM Access Policy (`dmPolicy`)
+
+Controls who can send **direct messages** to the bot:
+
+| Policy              | Behavior                                                     |
+| ------------------- | ------------------------------------------------------------ |
+| `pairing` (default) | New senders trigger a pairing request that must be approved before they can chat. |
+| `open`              | Anyone on the mesh can DM the bot freely.                    |
+| `allowlist`         | Only nodes listed in `allowFrom` can DM. All others are ignored. |
+
+### 7. DM Allowlist (`allowFrom`)
+
+> Only appears when `dmPolicy` is `allowlist`, or when the wizard determines one is needed.
+
+A list of Meshtastic User IDs allowed to send direct messages. Format: `!aabbccdd` (hex User ID). Multiple entries are comma-separated.
 
 <p align="center">
-  <img src="media/setup-screenshot.png" width="600" alt="OpenClaw setup wizard with Meshtastic channel configured" />
+  <img src="media/image3.jpg" width="400" />
 </p>
 
-### Manual configuration
+### 8. Account Display Names
+
+> Only appears for multi-account setups. Optional.
+
+Assigns human-readable display names to your accounts. For example, an account with ID `home` could be displayed as "Home Station". If skipped, the raw account ID is used as-is. This is purely cosmetic and does not affect functionality.
 
-Add to your OpenClaw config (`openclaw config edit`):
+## Configuration
+
+The guided setup (`openclaw onboard`) covers everything below. See [Setup Wizard](#setup-wizard) for a step-by-step walkthrough. For manual config, edit with `openclaw config edit`.
 
-**Serial (USB device):**
+### Serial (USB)
 
 ```yaml
 channels:
   meshtastic:
-    enabled: true
     transport: serial
     serialPort: /dev/ttyUSB0
     nodeName: OpenClaw
-    dmPolicy: pairing
 ```
 
-**HTTP (WiFi device):**
+### HTTP (WiFi)
 
 ```yaml
 channels:
   meshtastic:
-    enabled: true
     transport: http
     httpAddress: meshtastic.local
-    httpTls: false
     nodeName: OpenClaw
-    dmPolicy: pairing
 ```
 
-**MQTT (broker):**
+### MQTT (broker)
 
 ```yaml
 channels:
   meshtastic:
-    enabled: true
     transport: mqtt
+    nodeName: OpenClaw
     mqtt:
       broker: mqtt.meshtastic.org
-      port: 1883
       username: meshdev
       password: large4cats
       topic: "msh/US/2/json/#"
-      tls: false
-    dmPolicy: pairing
 ```
 
-### Configuration reference
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `transport` | `serial` \| `http` \| `mqtt` | `serial` | Connection method |
-| `serialPort` | string | — | Serial device path |
-| `httpAddress` | string | `meshtastic.local` | Device IP or hostname |
-| `httpTls` | boolean | `false` | Use HTTPS for HTTP transport |
-| `mqtt.broker` | string | `mqtt.meshtastic.org` | MQTT broker hostname |
-| `mqtt.port` | number | `1883` | MQTT broker port |
-| `mqtt.username` | string | `meshdev` | MQTT username |
-| `mqtt.password` | string | `large4cats` | MQTT password |
-| `mqtt.topic` | string | `msh/US/2/json/#` | MQTT subscribe topic |
-| `mqtt.tls` | boolean | `false` | Use TLS for MQTT |
-| `region` | string | `UNSET` | LoRa region (serial/HTTP only) |
-| `nodeName` | string | — | Device display name and @mention trigger |
-| `dmPolicy` | `open` \| `pairing` \| `allowlist` | `pairing` | DM access policy |
-| `allowFrom` | string[] | — | Allowed node IDs (e.g. `["!aabbccdd"]`) |
-| `groupPolicy` | `open` \| `allowlist` \| `disabled` | `disabled` | Group channel policy |
-| `channels` | object | — | Per-channel config (requireMention, tools, allowFrom) |
-
 ### Multi-account
 
 ```yaml
@@ -144,27 +265,80 @@ channels:
         transport: mqtt
         mqtt:
           broker: mqtt.meshtastic.org
+          topic: "msh/US/2/json/#"
 ```
 
-## Verify
+<details>
+<summary><b>All Options Reference</b></summary>
+
+| Key                 | Type                            | Default               | Notes                                                        |
+| ------------------- | ------------------------------- | --------------------- | ------------------------------------------------------------ |
+| `transport`         | `serial \| http \| mqtt`        | `serial`              |                                                              |
+| `serialPort`        | `string`                        | —                     | Required for serial                                          |
+| `httpAddress`       | `string`                        | `meshtastic.local`    | Required for HTTP                                            |
+| `httpTls`           | `boolean`                       | `false`               |                                                              |
+| `mqtt.broker`       | `string`                        | `mqtt.meshtastic.org` |                                                              |
+| `mqtt.port`         | `number`                        | `1883`                |                                                              |
+| `mqtt.username`     | `string`                        | `meshdev`             |                                                              |
+| `mqtt.password`     | `string`                        | `large4cats`          |                                                              |
+| `mqtt.topic`        | `string`                        | `msh/US/2/json/#`     | Subscribe topic                                              |
+| `mqtt.publishTopic` | `string`                        | derived               |                                                              |
+| `mqtt.tls`          | `boolean`                       | `false`               |                                                              |
+| `region`            | enum                            | `UNSET`               | `US`, `EU_868`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU`, `IN`, `NZ_865`, `TH`, `EU_433`, `UA_433`, `UA_868`, `MY_433`, `MY_919`, `SG_923`, `LORA_24`. Serial/HTTP only. |
+| `nodeName`          | `string`                        | auto-detect           | Display name and @mention trigger. Required for MQTT.        |
+| `dmPolicy`          | `open \| pairing \| allowlist`  | `pairing`             | Who can send direct messages. See [DM Access Policy](#6-dm-access-policy-dmpolicy). |
+| `allowFrom`         | `string[]`                      | —                     | Node IDs for DM allowlist, e.g. `["!aabbccdd"]`              |
+| `groupPolicy`       | `open \| allowlist \| disabled` | `disabled`            | Group channel response policy. See [Channel Access](#4-channel-access-grouppolicy). |
+| `channels`          | `Record<string, object>`        | —                     | Per-channel overrides: `requireMention`, `allowFrom`, `tools` |
+
+</details>
+
+<details>
+<summary><b>Environment Variable Overrides</b></summary>
+
+These override the default account's config (YAML takes precedence for named accounts):
+
+| Variable                  | Equivalent config key |
+| ------------------------- | --------------------- |
+| `MESHTASTIC_TRANSPORT`    | `transport`           |
+| `MESHTASTIC_SERIAL_PORT`  | `serialPort`          |
+| `MESHTASTIC_HTTP_ADDRESS` | `httpAddress`         |
+| `MESHTASTIC_MQTT_BROKER`  | `mqtt.broker`         |
+| `MESHTASTIC_MQTT_TOPIC`   | `mqtt.topic`          |
+
+</details>
+
+## Troubleshooting
+
+| Symptom               | Check                                                        |
+| --------------------- | ------------------------------------------------------------ |
+| Serial won't connect  | Device path correct? Host has permission?                    |
+| HTTP won't connect    | `httpAddress` reachable? `httpTls` matches device?           |
+| MQTT receives nothing | Region in `mqtt.topic` correct? Broker credentials valid?    |
+| No DM responses       | `dmPolicy` and `allowFrom` configured? See [DM Access Policy](#6-dm-access-policy-dmpolicy). |
+| No group replies      | `groupPolicy` enabled? Channel in allowlist? Mention required? See [Channel Access](#4-channel-access-grouppolicy). |
+
+Found a bug? [Open an issue][issues] with transport type, config (redact secrets), and `openclaw channels status --probe` output.
+
+## Development
 
 ```bash
-openclaw channels status --probe
+git clone https://github.com/Seeed-Solution/MeshClaw.git
+cd MeshClaw
+npm install
+openclaw plugins install -l ./MeshClaw
 ```
 
-## Environment variables
-
-These can be used as alternatives to config file settings:
-
-- `MESHTASTIC_TRANSPORT` — `serial`, `http`, or `mqtt`
-- `MESHTASTIC_SERIAL_PORT` — serial device path
-- `MESHTASTIC_HTTP_ADDRESS` — device IP or hostname
-- `MESHTASTIC_MQTT_BROKER` — MQTT broker hostname
-
-## Supported LoRa regions
+No build step — OpenClaw loads TypeScript source directly. Use `openclaw channels status --probe` to verify.
 
-US, EU_433, EU_868, CN, JP, ANZ, KR, TW, RU, IN, NZ_865, TH, UA_433, UA_868, MY_433, MY_919, SG_923, LORA_24
+## Contributing
 
-## License
+- [Open an issue][issues] for bugs or feature requests
+- Pull requests welcome — keep code aligned with existing TypeScript conventions
 
-MIT
+<!-- Reference-style links -->
+[docs]: https://meshtastic.org/docs/
+[issues]: https://github.com/Seeed-Solution/MeshClaw/issues
+[hw-xiao]: https://www.seeedstudio.com/Wio-SX1262-with-XIAO-ESP32S3-p-5982.html
+[hw-wio]: https://www.seeedstudio.com/Wio-Tracker-L1-Pro-p-6454.html
+[hw-sensecap]: https://www.seeedstudio.com/SenseCAP-Card-Tracker-T1000-E-for-Meshtastic-p-5913.html