@seeed-studio/meshtastic 0.1.0

package/README.md

@@ -0,0 +1,170 @@
+# openclaw-meshtastic
+
+OpenClaw channel plugin for [Meshtastic](https://meshtastic.org/) LoRa mesh networks.
+
+Lets your OpenClaw gateway send and receive messages over Meshtastic devices — via USB serial, HTTP (WiFi), or MQTT broker.
+
+<p align="center">
+  <img src="media/hardware.jpg" width="400" alt="Meshtastic LoRa hardware with Seeed WM1302 module" />
+</p>
+
+## Demo
+
+https://github.com/user-attachments/assets/demo.mp4
+
+> The video above shows OpenClaw communicating over a Meshtastic LoRa mesh network. If it doesn't load, see [media/demo.mp4](media/demo.mp4).
+
+## 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
+
+## Requirements
+
+- [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)
+
+## Install
+
+```bash
+openclaw plugins install @seeed-studio/openclaw-meshtastic
+```
+
+Or install from a local directory during development:
+
+```bash
+git clone https://github.com/suharvest/openclaw-meshtastic.git
+openclaw plugins install -l ./openclaw-meshtastic
+```
+
+## Configuration
+
+### Interactive setup
+
+```bash
+openclaw setup
+# Select "Meshtastic" when prompted for channel
+```
+
+The wizard walks you through transport selection, connection details, region, access policy, and channel config.
+
+<p align="center">
+  <img src="media/setup-screenshot.png" width="600" alt="OpenClaw setup wizard with Meshtastic channel configured" />
+</p>
+
+### Manual configuration
+
+Add to your OpenClaw config (`openclaw config edit`):
+
+**Serial (USB device):**
+
+```yaml
+channels:
+  meshtastic:
+    enabled: true
+    transport: serial
+    serialPort: /dev/ttyUSB0
+    nodeName: OpenClaw
+    dmPolicy: pairing
+```
+
+**HTTP (WiFi device):**
+
+```yaml
+channels:
+  meshtastic:
+    enabled: true
+    transport: http
+    httpAddress: meshtastic.local
+    httpTls: false
+    nodeName: OpenClaw
+    dmPolicy: pairing
+```
+
+**MQTT (broker):**
+
+```yaml
+channels:
+  meshtastic:
+    enabled: true
+    transport: mqtt
+    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
+channels:
+  meshtastic:
+    accounts:
+      home:
+        transport: serial
+        serialPort: /dev/ttyUSB0
+      remote:
+        transport: mqtt
+        mqtt:
+          broker: mqtt.meshtastic.org
+```
+
+## Verify
+
+```bash
+openclaw channels status --probe
+```
+
+## 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
+
+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
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,17 @@
+import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { meshtasticPlugin } from "./src/channel.js";
+import { setMeshtasticRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "meshtastic",
+  name: "Meshtastic",
+  description: "Meshtastic LoRa mesh channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setMeshtasticRuntime(api.runtime);
+    api.registerChannel({ plugin: meshtasticPlugin as ChannelPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "meshtastic",
+  "channels": ["meshtastic"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@seeed-studio/meshtastic",
+  "version": "0.1.0",
+  "description": "OpenClaw Meshtastic LoRa mesh channel plugin",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Seeed-Solution/openclaw-meshtastic"
+  },
+  "keywords": [
+    "openclaw",
+    "meshtastic",
+    "lora",
+    "mesh",
+    "iot"
+  ],
+  "dependencies": {
+    "@meshtastic/core": "^2.6.7",
+    "@meshtastic/transport-http": "^0.2.5",
+    "@meshtastic/transport-node-serial": "^0.0.2",
+    "mqtt": "^5.10.0",
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,196 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { CoreConfig, MeshtasticAccountConfig, MeshtasticTransport } from "./types.js";
+
+export type ResolvedMeshtasticAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  configured: boolean;
+  transport: MeshtasticTransport;
+  serialPort: string;
+  httpAddress: string;
+  httpTls: boolean;
+  config: MeshtasticAccountConfig;
+};
+
+function listConfiguredAccountIds(cfg: CoreConfig): string[] {
+  const accounts = cfg.channels?.meshtastic?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return [];
+  }
+  const ids = new Set<string>();
+  for (const key of Object.keys(accounts)) {
+    if (key.trim()) {
+      ids.add(normalizeAccountId(key));
+    }
+  }
+  return [...ids];
+}
+
+function resolveAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+): MeshtasticAccountConfig | undefined {
+  const accounts = cfg.channels?.meshtastic?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return undefined;
+  }
+  const direct = accounts[accountId] as MeshtasticAccountConfig | undefined;
+  if (direct) {
+    return direct;
+  }
+  const normalized = normalizeAccountId(accountId);
+  const matchKey = Object.keys(accounts).find((key) => normalizeAccountId(key) === normalized);
+  return matchKey ? (accounts[matchKey] as MeshtasticAccountConfig | undefined) : undefined;
+}
+
+function mergeMeshtasticAccountConfig(cfg: CoreConfig, accountId: string): MeshtasticAccountConfig {
+  const { accounts: _ignored, ...base } = (cfg.channels?.meshtastic ??
+    {}) as MeshtasticAccountConfig & {
+    accounts?: unknown;
+  };
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  const merged: MeshtasticAccountConfig = { ...base, ...account };
+  if (base.mqtt || account.mqtt) {
+    merged.mqtt = {
+      ...base.mqtt,
+      ...account.mqtt,
+    };
+  }
+  return merged;
+}
+
+export function listMeshtasticAccountIds(cfg: CoreConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+  return ids.toSorted((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultMeshtasticAccountId(cfg: CoreConfig): string {
+  const ids = listMeshtasticAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveMeshtasticAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): ResolvedMeshtasticAccount {
+  const hasExplicitAccountId = Boolean(params.accountId?.trim());
+  const baseEnabled = params.cfg.channels?.meshtastic?.enabled !== false;
+
+  const resolve = (accountId: string) => {
+    const merged = mergeMeshtasticAccountConfig(params.cfg, accountId);
+    const accountEnabled = merged.enabled !== false;
+    const enabled = baseEnabled && accountEnabled;
+
+    const envTransport =
+      accountId === DEFAULT_ACCOUNT_ID
+        ? (process.env.MESHTASTIC_TRANSPORT?.trim() as MeshtasticTransport | undefined)
+        : undefined;
+    const transport: MeshtasticTransport = merged.transport ?? envTransport ?? "serial";
+
+    const envSerialPort =
+      accountId === DEFAULT_ACCOUNT_ID ? process.env.MESHTASTIC_SERIAL_PORT?.trim() : undefined;
+    const serialPort = merged.serialPort?.trim() || envSerialPort || "";
+
+    const envHttpAddress =
+      accountId === DEFAULT_ACCOUNT_ID ? process.env.MESHTASTIC_HTTP_ADDRESS?.trim() : undefined;
+    const httpAddress = merged.httpAddress?.trim() || envHttpAddress || "";
+
+    const httpTls = merged.httpTls ?? false;
+
+    // Apply env vars to MQTT config
+    if (accountId === DEFAULT_ACCOUNT_ID && merged.mqtt) {
+      const envBroker = process.env.MESHTASTIC_MQTT_BROKER?.trim();
+      const envTopic = process.env.MESHTASTIC_MQTT_TOPIC?.trim();
+      if (envBroker && !merged.mqtt.broker) {
+        merged.mqtt.broker = envBroker;
+      }
+      if (envTopic && !merged.mqtt.topic) {
+        merged.mqtt.topic = envTopic;
+      }
+    }
+
+    // For MQTT transport, also check env vars even without mqtt config block
+    if (transport === "mqtt" && !merged.mqtt && accountId === DEFAULT_ACCOUNT_ID) {
+      const envBroker = process.env.MESHTASTIC_MQTT_BROKER?.trim();
+      const envTopic = process.env.MESHTASTIC_MQTT_TOPIC?.trim();
+      if (envBroker || envTopic) {
+        merged.mqtt = {
+          broker: envBroker,
+          topic: envTopic,
+        };
+      }
+    }
+
+    const configured = resolveIsConfigured(transport, serialPort, httpAddress, merged);
+
+    const config: MeshtasticAccountConfig = {
+      ...merged,
+      transport,
+      serialPort: serialPort || undefined,
+      httpAddress: httpAddress || undefined,
+      httpTls,
+    };
+
+    return {
+      accountId,
+      enabled,
+      name: merged.name?.trim() || undefined,
+      configured,
+      transport,
+      serialPort,
+      httpAddress,
+      httpTls,
+      config,
+    } satisfies ResolvedMeshtasticAccount;
+  };
+
+  const normalized = normalizeAccountId(params.accountId);
+  const primary = resolve(normalized);
+  if (hasExplicitAccountId) {
+    return primary;
+  }
+  if (primary.configured) {
+    return primary;
+  }
+
+  const fallbackId = resolveDefaultMeshtasticAccountId(params.cfg);
+  if (fallbackId === primary.accountId) {
+    return primary;
+  }
+  const fallback = resolve(fallbackId);
+  if (!fallback.configured) {
+    return primary;
+  }
+  return fallback;
+}
+
+function resolveIsConfigured(
+  transport: MeshtasticTransport,
+  serialPort: string,
+  httpAddress: string,
+  config: MeshtasticAccountConfig,
+): boolean {
+  switch (transport) {
+    case "serial":
+      return Boolean(serialPort);
+    case "http":
+      return Boolean(httpAddress);
+    case "mqtt":
+      return Boolean(config.mqtt?.broker);
+    default:
+      return false;
+  }
+}
+
+export function listEnabledMeshtasticAccounts(cfg: CoreConfig): ResolvedMeshtasticAccount[] {
+  return listMeshtasticAccountIds(cfg)
+    .map((accountId) => resolveMeshtasticAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}