@seeed-studio/meshtastic 0.2.0 → 0.2.1

package/README.md

@@ -1,51 +1,50 @@
-# OpenClaw Meshtastic Plugin
+<p align="center">
+  <img src="media/GoMeshClaw.png" width="700" alt="Meshtastic LoRa hardware" />
+</p>
+
+# MeshClaw: OpenClaw Meshtastic Channel Plugin
+
+<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>
 
-[![npm version](https://img.shields.io/npm/v/@seeed-studio/meshtastic.svg)](https://www.npmjs.com/package/@seeed-studio/meshtastic)
-[![license](https://img.shields.io/npm/l/@seeed-studio/meshtastic.svg)](https://www.npmjs.com/package/@seeed-studio/meshtastic)
+<!-- LANG_SWITCHER_START -->
+<p align="center">
+  <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 -->
 
-**[English](README.md)** | [中文](README.zh-CN.md)
+**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.
 
-[OpenClaw](https://github.com/openclaw/openclaw) channel plugin for [Meshtastic](https://meshtastic.org/) LoRa mesh networks. Connect your AI gateway to the mesh over USB serial, HTTP, or MQTT — no cloud required.
+⭐ 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]
 
-<p align="center">
-  <img src="media/hardware.jpg" width="420" alt="Meshtastic LoRa hardware" />
-</p>
-
 ## Table of Contents
 
-- [Quick Start](#quick-start)
 - [How It Works](#how-it-works)
 - [Recommended Hardware](#recommended-hardware)
-- [Demo](#demo)
 - [Features](#features)
+- [Capabilities & Roadmap](#capabilities--roadmap)
+- [Demo](#demo)
+- [Quick Start](#quick-start)
 - [Setup Wizard](#setup-wizard)
 - [Configuration](#configuration)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [Contributing](#contributing)
 
-## Quick Start
-
-```bash
-# 1. Install plugin
-openclaw plugins install @seeed-studio/meshtastic
-
-# 2. Guided setup — walks you through transport, region, and access policy
-openclaw setup
-
-# 3. Verify
-openclaw channels status --probe
-```
-
-<p align="center">
-  <img src="media/setup-screenshot.png" width="700" alt="OpenClaw setup wizard" />
-</p>
-
 ## How It Works
 
 ```mermaid
@@ -77,40 +76,75 @@ Inbound messages go through access control (DM policy, group policy, mention gat
   <img src="media/XIAOclaw.png" width="760" alt="Meshtastic device with Seeed XIAO module" />
 </p>
 
-| Device | Best for | Link |
-|---|---|---|
-| XIAO ESP32S3 + Wio-SX1262 kit | Budget off-grid node | [Buy][hw-xiao] |
-| Wio Tracker L1 Pro | Ready-to-deploy gateway | [Buy][hw-wio] |
-| SenseCAP Card Tracker T1000-E | Compact field tracker | [Buy][hw-sensecap] |
+| 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] |
 
-Any Meshtastic-compatible device works. Serial and HTTP transports connect directly; MQTT requires no local hardware at all.
+No hardware? MQTT transport connects via broker — no local device required.
+
+Any Meshtastic-compatible device works.
+
+## Features
+
+- **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.
+
+## Capabilities & Roadmap
+
+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.
+
+| 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
 
-https://github.com/user-attachments/assets/a3e46e9d-cf5a-4743-9830-f671a1998ca0
+<div align="center">
+
+https://github.com/user-attachments/assets/837062d9-a5bb-4e0a-b7cf-298e4bdf2f7c
+
+</div>
 
 Fallback: [media/demo.mp4](media/demo.mp4)
 
-## Features
+## Quick Start
 
-- **Direct messages and mesh channels** with per-channel rules
-- **Access control** — DM policy (`open` / `pairing` / `allowlist`), group policy (`open` / `allowlist` / `disabled`), mention-gating, per-channel allowlists
-- **Multi-account** — run independent serial, HTTP, and MQTT connections side by side
-- **Region-aware** — sets device region on connect and derives MQTT topic defaults
-- **Auto-reconnect** with resilient retry handling
+```bash
+# 1. Install plugin
+openclaw plugins install @seeed-studio/meshtastic
+
+# 2. Guided setup — walks you through transport, region, and access policy
+openclaw onboard
+
+# 3. Verify
+openclaw channels status --probe
+```
+
+<p align="center">
+  <img src="media/setup-screenshot.png" width="700" alt="OpenClaw setup wizard" />
+</p>
 
 ## Setup Wizard
 
-Running `openclaw setup` launches an interactive wizard that walks you through each configuration step. Below is what each step means and how to choose.
+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
 
 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`) |
+| 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
@@ -119,13 +153,13 @@ How the gateway connects to the Meshtastic mesh:
 
 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 |
+| 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.
 
@@ -140,11 +174,11 @@ The device's display name on the mesh. Also used as the **@mention trigger** in
 
 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. |
+| 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
 
@@ -158,17 +192,21 @@ When disabled, the bot responds to **all** messages in allowed channels.
 
 Controls who can send **direct messages** to the bot:
 
-| Policy | Behavior |
-|---|---|
+| 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. |
+| `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 node IDs allowed to send direct messages. Format: `!aabbccdd` (hex node ID). Multiple entries are comma-separated.
+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/image3.jpg" width="400" />
+</p>
 
 ### 8. Account Display Names
 
@@ -178,7 +216,7 @@ Assigns human-readable display names to your accounts. For example, an account w
 
 ## Configuration
 
-The guided setup (`openclaw setup`) covers everything below. See [Setup Wizard](#setup-wizard) for a step-by-step walkthrough. For manual config, edit with `openclaw config edit`.
+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)
 
@@ -233,25 +271,25 @@ channels:
 <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` |
+| 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>
 
@@ -260,35 +298,35 @@ channels:
 
 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` |
+| 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). |
+| 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
-git clone https://github.com/Seeed-Solution/openclaw-meshtastic.git
-cd openclaw-meshtastic
+git clone https://github.com/Seeed-Solution/MeshClaw.git
+cd MeshClaw
 npm install
-openclaw plugins install -l ./openclaw-meshtastic
+openclaw plugins install -l ./MeshClaw
 ```
 
 No build step — OpenClaw loads TypeScript source directly. Use `openclaw channels status --probe` to verify.
@@ -300,7 +338,7 @@ No build step — OpenClaw loads TypeScript source directly. Use `openclaw chann
 
 <!-- Reference-style links -->
 [docs]: https://meshtastic.org/docs/
-[issues]: https://github.com/Seeed-Solution/openclaw-meshtastic/issues
+[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