@seeed-studio/meshtastic 0.1.0 → 0.2.0

package/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: NPM_KEY
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm install
+
+      - run: npm publish --provenance --access public

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Seeed Solution
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,136 +1,219 @@
-# openclaw-meshtastic
+# OpenClaw Meshtastic Plugin
 
-OpenClaw channel plugin for [Meshtastic](https://meshtastic.org/) LoRa mesh networks.
+[![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)
 
-Lets your OpenClaw gateway send and receive messages over Meshtastic devices — via USB serial, HTTP (WiFi), or MQTT broker.
+**[English](README.md)** | [中文](README.zh-CN.md)
 
-<p align="center">
-  <img src="media/hardware.jpg" width="400" alt="Meshtastic LoRa hardware with Seeed WM1302 module" />
-</p>
+[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.
 
-## Demo
+> [!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.
 
-https://github.com/user-attachments/assets/demo.mp4
+[Documentation][docs] · [Hardware Guide](#recommended-hardware) · [Report Bug][issues] · [Request Feature][issues]
 
-> The video above shows OpenClaw communicating over a Meshtastic LoRa mesh network. If it doesn't load, see [media/demo.mp4](media/demo.mp4).
+<p align="center">
+  <img src="media/hardware.jpg" width="420" alt="Meshtastic LoRa hardware" />
+</p>
 
-## Features
+## Table of Contents
 
-- **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
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Recommended Hardware](#recommended-hardware)
+- [Demo](#demo)
+- [Features](#features)
+- [Setup Wizard](#setup-wizard)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Contributing](#contributing)
 
-## Requirements
+## Quick Start
 
-- [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)
+```bash
+# 1. Install plugin
+openclaw plugins install @seeed-studio/meshtastic
 
-## Install
+# 2. Guided setup — walks you through transport, region, and access policy
+openclaw setup
 
-```bash
-openclaw plugins install @seeed-studio/openclaw-meshtastic
+# 3. Verify
+openclaw channels status --probe
 ```
 
-Or install from a local directory during development:
+<p align="center">
+  <img src="media/setup-screenshot.png" width="700" alt="OpenClaw setup wizard" />
+</p>
 
-```bash
-git clone https://github.com/suharvest/openclaw-meshtastic.git
-openclaw plugins install -l ./openclaw-meshtastic
+## 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
 ```
 
-## Configuration
+The plugin bridges Meshtastic LoRa devices and the OpenClaw AI agent. It supports three transport modes:
 
-### Interactive setup
+- **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
 
-```bash
-openclaw setup
-# Select "Meshtastic" when prompted for channel
-```
+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 wizard walks you through transport selection, connection details, region, access policy, and channel config.
+## Recommended Hardware
 
 <p align="center">
-  <img src="media/setup-screenshot.png" width="600" alt="OpenClaw setup wizard with Meshtastic channel configured" />
+  <img src="media/XIAOclaw.png" width="760" alt="Meshtastic device with Seeed XIAO module" />
 </p>
 
-### Manual configuration
+| 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] |
+
+Any Meshtastic-compatible device works. Serial and HTTP transports connect directly; MQTT requires no local hardware at all.
+
+## Demo
+
+https://github.com/user-attachments/assets/a3e46e9d-cf5a-4743-9830-f671a1998ca0
+
+Fallback: [media/demo.mp4](media/demo.mp4)
+
+## Features
+
+- **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
+
+## 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.
+
+### 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`) |
+| **MQTT** (broker) | Connects to the mesh via an MQTT broker — no local hardware needed. | Broker address, credentials, and subscribe topic |
+
+### 2. LoRa Region
 
-Add to your OpenClaw config (`openclaw config edit`):
+> Serial and HTTP only. MQTT derives the region from the subscribe topic.
 
-**Serial (USB device):**
+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 node IDs allowed to send direct messages. Format: `!aabbccdd` (hex node ID). Multiple entries are comma-separated.
+
+### 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.
+
+## 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`.
+
+### 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 +227,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/openclaw-meshtastic.git
+cd openclaw-meshtastic
+npm install
+openclaw plugins install -l ./openclaw-meshtastic
 ```
 
-## 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/openclaw-meshtastic/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