@seeed-studio/meshtastic 0.1.1 → 0.2.1

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@seeed-studio/meshtastic",
-  "version": "0.1.1",
-  "description": "OpenClaw Meshtastic LoRa mesh channel plugin",
+  "version": "0.2.1",
+  "description": "MeshClaw — OpenClaw channel plugin for Meshtastic LoRa mesh networks",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Seeed-Solution/openclaw-meshtastic"
+    "url": "https://github.com/Seeed-Solution/MeshClaw"
   },
   "keywords": [
+    "meshclaw",
     "openclaw",
     "meshtastic",
     "lora",

package/src/channel.ts

@@ -10,7 +10,7 @@ import {
   resolveDefaultGroupPolicy,
   setAccountEnabledInConfigSection,
   type ChannelPlugin,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/irc";
 import {
   listMeshtasticAccountIds,
   resolveDefaultMeshtasticAccountId,
@@ -264,8 +264,8 @@ export const meshtasticPlugin: ChannelPlugin<ResolvedMeshtasticAccount, Meshtast
   },
   outbound: {
     deliveryMode: "direct",
-    chunker: (text, limit) => getMeshtasticRuntime().channel.text.chunkMarkdownText(text, limit),
-    chunkerMode: "markdown",
+    chunker: (text, limit) => getMeshtasticRuntime().channel.text.chunkText(text, limit),
+    chunkerMode: "text",
     textChunkLimit: 200,
     sendText: async ({ to, text, accountId }) => {
       const result = await sendMessageMeshtastic(to, text, {
@@ -291,25 +291,78 @@ export const meshtasticPlugin: ChannelPlugin<ResolvedMeshtasticAccount, Meshtast
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
     probeAccount: async ({ account }) => {
-      // Meshtastic probing is transport-dependent and may require
-      // active device connection. Return a basic status.
       if (!account.configured) {
         return {
           ok: false,
-          error: "not configured",
+          error: "Not configured. Run 'openclaw onboard' to configure.",
           transport: account.transport,
         } as MeshtasticProbe;
       }
-      return {
-        ok: true,
-        transport: account.transport,
-        address:
-          account.transport === "serial"
-            ? account.serialPort
-            : account.transport === "http"
-              ? account.httpAddress
-              : account.config.mqtt?.broker,
-      } as MeshtasticProbe;
+
+      const address =
+        account.transport === "serial"
+          ? account.serialPort
+          : account.transport === "http"
+            ? account.httpAddress
+            : account.config.mqtt?.broker;
+
+      // Lightweight transport-specific reachability check.
+      try {
+        if (account.transport === "serial") {
+          const { access } = await import("node:fs/promises");
+          await access(account.serialPort);
+        } else if (account.transport === "http") {
+          const prefix = account.httpTls ? "https" : "http";
+          const url = `${prefix}://${account.httpAddress}/api/v1/fromradio`;
+          const controller = new AbortController();
+          const timeout = setTimeout(() => controller.abort(), 5_000);
+          try {
+            await fetch(url, { signal: controller.signal });
+          } finally {
+            clearTimeout(timeout);
+          }
+        } else if (account.transport === "mqtt") {
+          const mqtt = await import("mqtt");
+          const mqttConfig = account.config.mqtt;
+          const protocol = mqttConfig?.tls ? "mqtts" : "mqtt";
+          const broker = mqttConfig?.broker ?? "mqtt.meshtastic.org";
+          const port = mqttConfig?.port ?? 1883;
+          await new Promise<void>((resolve, reject) => {
+            const timeout = setTimeout(() => {
+              client.end(true);
+              reject(new Error("MQTT connection timed out (5s)"));
+            }, 5_000);
+            const client = mqtt.default.connect(`${protocol}://${broker}:${port}`, {
+              username: mqttConfig?.username ?? "meshdev",
+              password: mqttConfig?.password ?? "large4cats",
+              clean: true,
+              connectTimeout: 5_000,
+            });
+            client.on("connect", () => {
+              clearTimeout(timeout);
+              client.end(true);
+              resolve();
+            });
+            client.on("error", (err) => {
+              clearTimeout(timeout);
+              client.end(true);
+              reject(err);
+            });
+          });
+        }
+        return {
+          ok: true,
+          transport: account.transport,
+          address,
+        } as MeshtasticProbe;
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          transport: account.transport,
+          address,
+        } as MeshtasticProbe;
+      }
     },
     buildAccountSnapshot: ({ account, runtime, probe }) => ({
       ...buildBaseAccountStatusSnapshot({ account, runtime, probe }),
@@ -324,7 +377,7 @@ export const meshtasticPlugin: ChannelPlugin<ResolvedMeshtasticAccount, Meshtast
       if (!account.configured) {
         throw new Error(
           `Meshtastic is not configured for account "${account.accountId}". ` +
-            `Set channels.meshtastic.transport and connection details.`,
+            `Run 'openclaw onboard' or set channels.meshtastic.transport and connection details in config.`,
         );
       }
       const transportDesc =

package/src/client.ts

@@ -2,6 +2,39 @@ import { MeshDevice } from "@meshtastic/core";
 import { nodeNumToHex } from "./normalize.js";
 import type { MeshtasticRegion } from "./types.js";
 
+/**
+ * Device status codes from @meshtastic/core DeviceStatusEnum.
+ * The SDK doesn't export these as named constants, so we define them here.
+ */
+export const DeviceStatus = {
+  Restarting: 1,
+  Disconnected: 2,
+  Connecting: 3,
+  Reconnecting: 4,
+  Connected: 5,
+  Configuring: 6,
+  Configured: 7,
+} as const;
+
+/**
+ * Thrown when setOwner() was called to update the device name.
+ * The device will reboot to persist the change; the caller should
+ * reconnect after a delay (~30 s).
+ */
+export class SetOwnerRebootError extends Error {
+  constructor(
+    public readonly newName: string,
+    public readonly previousName: string | undefined,
+  ) {
+    super(
+      `Device rebooting to apply name "${newName}"` +
+        (previousName ? ` (was "${previousName}")` : "") +
+        `. Auto-reconnect expected.`,
+    );
+    this.name = "SetOwnerRebootError";
+  }
+}
+
 export type MeshtasticTextEvent = {
   senderNodeNum: number;
   senderNodeId: string;
@@ -37,6 +70,7 @@ export type MeshtasticClient = {
     channelIndex?: number,
   ) => Promise<number>;
   getNodeName: (nodeNum: number) => string | undefined;
+  getMyNodeName: () => string | undefined;
   getChannelName: (index: number) => string | undefined;
   close: () => void;
 };
@@ -93,6 +127,22 @@ export async function connectMeshtasticClient(
 
   const device = new MeshDevice(transport);
 
+  // Expose serial port events for diagnostics — helps pinpoint why USB
+  // connections drop (power management, cable, firmware, etc.).
+  if (options.transport === "serial") {
+    const port = (transport as unknown as { port?: { on?: (...a: unknown[]) => void } }).port;
+    if (port?.on) {
+      port.on("error", (err: unknown) => {
+        options.onError?.(
+          err instanceof Error ? err : new Error(`serial port error: ${err}`),
+        );
+      });
+      port.on("close", () => {
+        options.onStatus?.("serial port closed by OS / device");
+      });
+    }
+  }
+
   // Node info cache for name resolution.
   const nodeNames = new Map<number, string>();
   const channelNames = new Map<number, string>();
@@ -106,10 +156,11 @@ export async function connectMeshtasticClient(
     }
   });
 
+  // NodeInfo is dispatched directly (not wrapped in { data: … }) during config.
   device.events.onNodeInfoPacket.subscribe(
-    (packet: { data?: { num?: number; user?: { longName?: string } } }) => {
-      if (packet.data?.user?.longName && packet.data.num) {
-        nodeNames.set(packet.data.num, packet.data.user.longName);
+    (packet: { num?: number; user?: { longName?: string } }) => {
+      if (packet.user?.longName && packet.num) {
+        nodeNames.set(packet.num, packet.user.longName);
       }
     },
   );
@@ -132,7 +183,16 @@ export async function connectMeshtasticClient(
   );
 
   device.events.onDeviceStatus.subscribe((status: number) => {
-    options.onStatus?.(`status=${status}`);
+    const label: Record<number, string> = {
+      [DeviceStatus.Restarting]: "Restarting",
+      [DeviceStatus.Disconnected]: "Disconnected",
+      [DeviceStatus.Connecting]: "Connecting",
+      [DeviceStatus.Reconnecting]: "Reconnecting",
+      [DeviceStatus.Connected]: "Connected",
+      [DeviceStatus.Configuring]: "Configuring",
+      [DeviceStatus.Configured]: "Configured",
+    };
+    options.onStatus?.(`status=${status} (${label[status] ?? "unknown"})`);
   });
 
   device.events.onMessagePacket.subscribe(
@@ -203,27 +263,31 @@ export async function connectMeshtasticClient(
     };
     const timeout = setTimeout(() => {
       cleanup();
-      reject(new Error("device configure timed out (45 s)"));
+      reject(new Error(
+        "Device configure timed out (45s). Check USB connection, try a different port, or power-cycle the device.",
+      ));
     }, 45_000);
     device.events.onDeviceStatus.subscribe((status: number) => {
-      if (status === 7 /* DeviceConfigured */) {
+      if (status === DeviceStatus.Configured) {
         cleanup();
         resolve();
-      } else if (status === 5 /* DeviceConnected */ && !configureRetried) {
+      } else if (status === DeviceStatus.Connected && !configureRetried) {
         // Transport is now connected — re-send the config request after a
         // short delay so the serial pipe is fully established.
         configureRetried = true;
         setTimeout(() => device.configure().catch(() => {}), 500);
-      } else if (status === 2 /* DeviceDisconnected */) {
+      } else if (status === DeviceStatus.Disconnected) {
         cleanup();
-        reject(new Error("device disconnected during configure"));
+        reject(new Error(
+          "Device disconnected during configure. Check cable connection and ensure no other program is using the serial port.",
+        ));
       }
     });
     // Poll as fallback — ste-core dispatch can miss late subscribers.
     poll = setInterval(() => {
       if (
         (device as unknown as { isConfigured: boolean }).isConfigured ||
-        (device as unknown as { deviceStatus: number }).deviceStatus === 7
+        (device as unknown as { deviceStatus: number }).deviceStatus === DeviceStatus.Configured
       ) {
         cleanup();
         resolve();
@@ -241,17 +305,43 @@ export async function connectMeshtasticClient(
     throw err;
   }
 
+  // Serial connections require periodic heartbeat pings to stay alive.
+  // Without this the device (or macOS USB stack) drops the connection after
+  // ~30 s of inactivity once configuration is complete.
+  if (options.transport === "serial") {
+    device.setHeartbeatInterval(15_000);
+  }
+
   // LoRa region: rely on NVS-persisted config set via `meshtastic --set lora.region`.
   // Sending a partial setConfig (region-only) zeroes out tx_enabled, tx_power, etc.
   // in the protobuf message, effectively disabling TX.  So we skip setConfig here.
 
-  // Set device display name if configured.  Fire-and-forget for the same reason.
-  if (options.nodeName?.trim()) {
-    const longName = options.nodeName.trim();
-    const shortName = longName.slice(0, 4);
-    device
-      .setOwner({ longName, shortName } as Parameters<typeof device.setOwner>[0])
-      .catch(() => {});
+  // Device display name — only call setOwner() when the configured name
+  // differs from what the device already reports.  setOwner() sends an admin
+  // packet that writes to NVS flash and reboots the device (~20-30 s later).
+  // By gating on a name mismatch we ensure the call happens at most once;
+  // after reboot the name matches and the guard passes, preventing an
+  // infinite reboot loop.
+  if (options.nodeName) {
+    const desiredName = options.nodeName.trim();
+    const currentName = nodeNames.get(myNodeNum);
+
+    if (desiredName && currentName !== desiredName) {
+      const shortName = desiredName.slice(0, 4);
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await device.setOwner({ longName: desiredName, shortName } as any);
+      } catch {
+        // Admin packet may fail on a flaky serial link; fall through and
+        // let the device keep its current name rather than crashing.
+      }
+      // Allow the firmware time to receive and process the admin packet
+      // before we tear down the serial connection.
+      options.onStatus?.("waiting 2s for firmware to process name change...");
+      await new Promise((r) => setTimeout(r, 2_000));
+      safeDisconnect();
+      throw new SetOwnerRebootError(desiredName, currentName);
+    }
   }
 
   // Catch unhandled promise rejections originating from @meshtastic/core's
@@ -283,6 +373,7 @@ export async function connectMeshtasticClient(
     sendText: (text, destination, wantAck = true, channelIndex) =>
       device.sendText(text, destination, wantAck, channelIndex),
     getNodeName: (nodeNum) => nodeNames.get(nodeNum),
+    getMyNodeName: () => nodeNames.get(myNodeNum),
     getChannelName: (index) => channelNames.get(index) || (index === 0 ? "LongFast" : undefined),
     close: () => {
       safeDisconnect();

package/src/config-schema.ts

@@ -5,7 +5,7 @@ import {
   ReplyRuntimeConfigSchemaShape,
   ToolPolicySchema,
   requireOpenAllowFrom,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/irc";
 import { z } from "zod";
 
 const MeshtasticGroupSchema = z
@@ -22,13 +22,14 @@ const MeshtasticGroupSchema = z
 
 const MeshtasticMqttSchema = z
   .object({
-    broker: z.string().optional(),
-    port: z.number().int().min(1).max(65535).optional(),
-    username: z.string().optional(),
-    password: z.string().optional(),
-    topic: z.string().optional(),
+    broker: z.string().optional().default("mqtt.meshtastic.org"),
+    port: z.number().int().min(1).max(65535).optional().default(1883),
+    username: z.string().optional().default("meshdev"),
+    password: z.string().optional().default("large4cats"),
+    topic: z.string().optional().default("msh/US/2/json/#"),
     publishTopic: z.string().optional(),
-    tls: z.boolean().optional(),
+    tls: z.boolean().optional().default(false),
+    myNodeId: z.string().optional(),
   })
   .strict();
 
@@ -77,11 +78,39 @@ export const MeshtasticAccountSchemaBase = z
     channels: z.record(z.string(), MeshtasticGroupSchema.optional()).optional(),
     mentionPatterns: z.array(z.string()).optional(),
     markdown: MarkdownConfigSchema,
+    textChunkLimit: z.number().int().min(50).max(500).optional(),
     ...ReplyRuntimeConfigSchemaShape,
   })
   .strict();
 
+/** Validates transport+connection coherence and open policy allowFrom. */
+function validateTransportConnection(value: z.output<typeof MeshtasticAccountSchemaBase>, ctx: z.RefinementCtx) {
+  const transport = value.transport ?? "serial";
+  if (transport === "serial" && !value.serialPort) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["serialPort"],
+      message: 'transport="serial" requires serialPort (e.g. "/dev/ttyUSB0" or "/dev/tty.usbmodem*")',
+    });
+  }
+  if (transport === "http" && !value.httpAddress) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["httpAddress"],
+      message: 'transport="http" requires httpAddress (e.g. "meshtastic.local" or "192.168.1.100")',
+    });
+  }
+  if (transport === "mqtt" && !value.mqtt?.broker) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["mqtt", "broker"],
+      message: 'transport="mqtt" requires mqtt.broker (e.g. "mqtt.meshtastic.org")',
+    });
+  }
+}
+
 export const MeshtasticAccountSchema = MeshtasticAccountSchemaBase.superRefine((value, ctx) => {
+  validateTransportConnection(value, ctx);
   requireOpenAllowFrom({
     policy: value.dmPolicy,
     allowFrom: value.allowFrom,
@@ -95,6 +124,7 @@ export const MeshtasticAccountSchema = MeshtasticAccountSchemaBase.superRefine((
 export const MeshtasticConfigSchema = MeshtasticAccountSchemaBase.extend({
   accounts: z.record(z.string(), MeshtasticAccountSchema.optional()).optional(),
 }).superRefine((value, ctx) => {
+  validateTransportConnection(value, ctx);
   requireOpenAllowFrom({
     policy: value.dmPolicy,
     allowFrom: value.allowFrom,

package/src/inbound.ts

@@ -1,7 +1,6 @@
 import {
   GROUP_POLICY_BLOCKED_LABEL,
   createNormalizedOutboundDeliverer,
-  createReplyPrefixOptions,
   formatTextWithAttachmentLinks,
   logInboundDrop,
   resolveControlCommandGate,
@@ -12,7 +11,8 @@ import {
   type OutboundReplyPayload,
   type OpenClawConfig,
   type RuntimeEnv,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/irc";
+import { createReplyPrefixOptions } from "openclaw/plugin-sdk/matrix";
 import type { ResolvedMeshtasticAccount } from "./accounts.js";
 import {
   normalizeMeshtasticAllowlist,
@@ -51,6 +51,14 @@ function resolveMeshtasticEffectiveAllowlists(params: {
 // so the firmware doesn't silently truncate them.
 const MESHTASTIC_CHUNK_LIMIT = 200;
 
+/** Channel-level system prompt hint for LoRa-constrained responses. */
+const LORA_SYSTEM_HINT =
+  "You are responding over a LoRa mesh radio (Meshtastic). " +
+  "Each message is limited to ~200 bytes. " +
+  "Keep responses extremely concise — plain text only, no markdown, no emoji, no bullet lists. " +
+  "Use short sentences. Omit filler words. Prioritize the most important information first.";
+
+
 function chunkText(text: string, limit: number): string[] {
   if (text.length <= limit) return [text];
   const chunks: string[] = [];
@@ -150,7 +158,13 @@ export async function handleMeshtasticInbound(params: {
   const storeAllowFrom =
     dmPolicy === "allowlist"
       ? []
-      : await core.channel.pairing.readAllowFromStore(CHANNEL_ID).catch(() => []);
+      : await core.channel.pairing.readAllowFromStore({
+          channel: CHANNEL_ID,
+          accountId: account.accountId,
+        }).catch((err: unknown) => {
+          runtime.log?.(`meshtastic: pairing allowFrom read failed: ${String(err)}`);
+          return [] as string[];
+        });
   const storeAllowList = normalizeMeshtasticAllowlist(storeAllowFrom);
 
   const channelLabel = message.channelName ?? `channel-${message.channelIndex}`;
@@ -227,6 +241,7 @@ export async function handleMeshtasticInbound(params: {
           const normalizedId = normalizeMeshtasticNodeId(message.senderNodeId);
           const { code, created } = await core.channel.pairing.upsertPairingRequest({
             channel: CHANNEL_ID,
+            accountId: account.accountId,
             id: normalizedId,
             meta: { name: message.senderName || undefined },
           });
@@ -336,7 +351,7 @@ export async function handleMeshtasticInbound(params: {
     SenderName: message.senderName || undefined,
     SenderId: message.senderNodeId,
     GroupSubject: message.isGroup ? channelLabel : undefined,
-    GroupSystemPrompt: message.isGroup ? groupSystemPrompt : undefined,
+    GroupSystemPrompt: [LORA_SYSTEM_HINT, groupSystemPrompt].filter(Boolean).join("\n\n"),
     Provider: CHANNEL_ID,
     Surface: CHANNEL_ID,
     WasMentioned: message.isGroup ? wasMentioned : undefined,