@seeed-studio/meshtastic 0.1.0 → 0.2.0

package/src/config-schema.ts

@@ -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

@@ -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,

package/src/monitor.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { createLoggerBackedRuntime, type RuntimeEnv } from "openclaw/plugin-sdk";
 import { resolveMeshtasticAccount } from "./accounts.js";
-import { connectMeshtasticClient, type MeshtasticClient } from "./client.js";
+import { connectMeshtasticClient, DeviceStatus, SetOwnerRebootError, type MeshtasticClient } from "./client.js";
 import { handleMeshtasticInbound } from "./inbound.js";
 import { connectMeshtasticMqtt, type MeshtasticMqttClient } from "./mqtt-client.js";
 import { nodeNumToHex } from "./normalize.js";
@@ -9,6 +9,28 @@ import { getMeshtasticRuntime } from "./runtime.js";
 import { setActiveSerialSend, setActiveMqttSend } from "./send.js";
 import type { CoreConfig, MeshtasticInboundMessage } from "./types.js";
 
+/** Inject a mention pattern (e.g. "@bard2") into the config so group messages
+ *  containing the pattern are recognized as mentions. */
+function injectMentionPattern(cfg: CoreConfig, name: string | undefined): CoreConfig {
+  if (!name) return cfg;
+  const mentionPattern = `@${name}`;
+  const existingPatterns =
+    (cfg as Record<string, unknown> & { messages?: { groupChat?: { mentionPatterns?: string[] } } })
+      .messages?.groupChat?.mentionPatterns ?? [];
+  if (existingPatterns.includes(mentionPattern)) return cfg;
+  return {
+    ...cfg,
+    messages: {
+      ...(cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined,
+      groupChat: {
+        ...((cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined)
+          ?.groupChat as Record<string, unknown> | undefined,
+        mentionPatterns: [...existingPatterns, mentionPattern],
+      },
+    },
+  };
+}
+
 export type MeshtasticMonitorOptions = {
   accountId?: string;
   config?: CoreConfig;
@@ -37,7 +59,7 @@ export async function monitorMeshtasticProvider(
   if (!account.configured) {
     throw new Error(
       `Meshtastic is not configured for account "${account.accountId}". ` +
-        `Set channels.meshtastic.transport and connection details.`,
+        `Run 'openclaw setup' or set channels.meshtastic.transport and connection details in config.`,
     );
   }
 
@@ -48,33 +70,14 @@ export async function monitorMeshtasticProvider(
 
   const transport = account.transport;
 
-  // Auto-inject nodeName into mentionPatterns so "@NodeName" triggers replies.
-  // buildMentionRegexes reads from cfg.messages.groupChat.mentionPatterns, so
-  // we merge nodeName there (not in channel-specific config).
-  const nodeName = account.config.nodeName?.trim();
-  const mentionPattern = nodeName ? `@${nodeName}` : undefined;
-  const existingPatterns =
-    (cfg as Record<string, unknown> & { messages?: { groupChat?: { mentionPatterns?: string[] } } })
-      .messages?.groupChat?.mentionPatterns ?? [];
-  const effectiveCfg =
-    mentionPattern && !existingPatterns.includes(mentionPattern)
-      ? {
-          ...cfg,
-          messages: {
-            ...(cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined,
-            groupChat: {
-              ...((cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined)
-                ?.groupChat as Record<string, unknown> | undefined,
-              mentionPatterns: [...existingPatterns, mentionPattern],
-            },
-          },
-        }
-      : cfg;
-
   if (transport === "mqtt") {
+    // MQTT: use config nodeName for mention pattern (no device to read from).
+    const effectiveCfg = injectMentionPattern(cfg, account.config.nodeName?.trim());
     return monitorMqtt({ account, cfg: effectiveCfg, runtime, logger, opts });
   }
-  return monitorDevice({ account, cfg: effectiveCfg, runtime, logger, opts, transport });
+  // Serial/HTTP: mention pattern is injected after connection so the device's
+  // actual name can be used as fallback when nodeName is not configured.
+  return monitorDevice({ account, cfg, runtime, logger, opts, transport });
 }
 
 async function monitorDevice(params: {
@@ -85,87 +88,110 @@ async function monitorDevice(params: {
   opts: MeshtasticMonitorOptions;
   transport: "serial" | "http";
 }): Promise<{ stop: () => void }> {
-  const { account, cfg, runtime, logger, opts, transport } = params;
+  const { account, runtime, logger, opts, transport } = params;
+  let cfg = params.cfg;
   const core = getMeshtasticRuntime();
 
   let client: MeshtasticClient | null = null;
 
-  client = await connectMeshtasticClient({
-    transport,
-    serialPort: account.serialPort,
-    httpAddress: account.httpAddress,
-    httpTls: account.httpTls,
-    region: account.config.region,
-    nodeName: account.config.nodeName,
-    abortSignal: opts.abortSignal,
-    onStatus: (status) => {
-      logger.info(`[${account.accountId}] device ${status}`);
-    },
-    onError: (error) => {
-      logger.error(`[${account.accountId}] error: ${error.message}`);
-    },
-    onText: async (event) => {
-      if (!client) {
-        return;
-      }
-
-      const channelName =
-        client.getChannelName(event.channelIndex) ?? `channel-${event.channelIndex}`;
-
-      const message: MeshtasticInboundMessage = {
-        messageId: randomUUID(),
-        senderNodeId: event.senderNodeId,
-        senderName: event.senderName ?? client.getNodeName(event.senderNodeNum),
-        channelIndex: event.channelIndex,
-        channelName,
-        text: event.text,
-        timestamp: event.rxTime,
-        isGroup: !event.isDirect,
-      };
+  try {
+    client = await connectMeshtasticClient({
+      transport,
+      serialPort: account.serialPort,
+      httpAddress: account.httpAddress,
+      httpTls: account.httpTls,
+      region: account.config.region,
+      nodeName: account.config.nodeName,
+      abortSignal: opts.abortSignal,
+      onStatus: (status) => {
+        logger.info(`[${account.accountId}] device ${status}`);
+      },
+      onError: (error) => {
+        logger.error(`[${account.accountId}] error: ${error.message}`);
+      },
+      onText: async (event) => {
+        if (!client) {
+          return;
+        }
 
-      core.channel.activity.record({
-        channel: "meshtastic",
-        accountId: account.accountId,
-        direction: "inbound",
-        at: message.timestamp,
-      });
+        const channelName =
+          client.getChannelName(event.channelIndex) ?? `channel-${event.channelIndex}`;
+
+        const message: MeshtasticInboundMessage = {
+          messageId: randomUUID(),
+          senderNodeId: event.senderNodeId,
+          senderName: event.senderName ?? client.getNodeName(event.senderNodeNum),
+          channelIndex: event.channelIndex,
+          channelName,
+          text: event.text,
+          timestamp: event.rxTime,
+          isGroup: !event.isDirect,
+        };
+
+        core.channel.activity.record({
+          channel: "meshtastic",
+          accountId: account.accountId,
+          direction: "inbound",
+          at: message.timestamp,
+        });
+
+        await handleMeshtasticInbound({
+          message,
+          account,
+          config: cfg,
+          runtime,
+          sendReply: async (target, text) => {
+            if (!client) {
+              return;
+            }
+            // For DM replies, resolve node number from hex ID.
+            // For group replies, broadcast to the same channel.
+            if (message.isGroup) {
+              // Broadcast: fire-and-forget.  The SDK's sendText promise waits
+              // for internal queue confirmation which may time out for broadcasts.
+              // The radio sends the packet regardless, so we don't await.
+              client.sendText(text, undefined, false, message.channelIndex).catch((err) => {
+                logger.warn(`[${account.accountId}] broadcast send failed: ${err instanceof Error ? err.message : String(err)}`);
+              });
+            } else {
+              // DM: fire-and-forget.  The SDK's sendText awaits ACK from the
+              // target node; if ACK times out the promise rejects, but the radio
+              // has already transmitted the packet.  Awaiting would block
+              // subsequent reply chunks.
+              const { hexToNodeNum } = await import("./normalize.js");
+              const destNum = hexToNodeNum(target);
+              client.sendText(text, destNum, true).catch((err) => {
+                logger.warn(`[${account.accountId}] DM send failed to ${target}: ${err instanceof Error ? err.message : String(err)}`);
+              });
+            }
+            opts.statusSink?.({ lastOutboundAt: Date.now() });
+            core.channel.activity.record({
+              channel: "meshtastic",
+              accountId: account.accountId,
+              direction: "outbound",
+            });
+          },
+          statusSink: opts.statusSink,
+        });
+      },
+    });
+  } catch (err) {
+    if (err instanceof SetOwnerRebootError) {
+      logger.info(`[${account.accountId}] ${err.message}`);
+      // Wait for the device to finish rebooting before the framework retries.
+      logger.info(`[${account.accountId}] waiting 30s for device reboot...`);
+      await new Promise((r) => setTimeout(r, 30_000));
+    }
+    throw err;
+  }
 
-      await handleMeshtasticInbound({
-        message,
-        account,
-        config: cfg,
-        runtime,
-        sendReply: async (target, text) => {
-          if (!client) {
-            return;
-          }
-          // For DM replies, resolve node number from hex ID.
-          // For group replies, broadcast to the same channel.
-          if (message.isGroup) {
-            // Broadcast: fire-and-forget.  The SDK's sendText promise waits
-            // for internal queue confirmation which may time out for broadcasts.
-            // The radio sends the packet regardless, so we don't await.
-            client.sendText(text, undefined, false, message.channelIndex).catch(() => {});
-          } else {
-            // DM: fire-and-forget.  The SDK's sendText awaits ACK from the
-            // target node; if ACK times out the promise rejects, but the radio
-            // has already transmitted the packet.  Awaiting would block
-            // subsequent reply chunks.
-            const { hexToNodeNum } = await import("./normalize.js");
-            const destNum = hexToNodeNum(target);
-            client.sendText(text, destNum, true).catch(() => {});
-          }
-          opts.statusSink?.({ lastOutboundAt: Date.now() });
-          core.channel.activity.record({
-            channel: "meshtastic",
-            accountId: account.accountId,
-            direction: "outbound",
-          });
-        },
-        statusSink: opts.statusSink,
-      });
-    },
-  });
+  // Determine the effective device name for @mention matching.
+  // If nodeName is configured, use it.  Otherwise read the device's actual name.
+  const effectiveName = account.config.nodeName?.trim() || client.getMyNodeName();
+  cfg = injectMentionPattern(cfg, effectiveName);
+  if (effectiveName) {
+    logger.info(`[${account.accountId}] mention trigger: @${effectiveName}`);
+  }
 
   // Register active send function for `openclaw message send`.
   setActiveSerialSend((text, destination, channelIndex) =>
@@ -189,7 +215,7 @@ async function monitorDevice(params: {
       opts.abortSignal.addEventListener("abort", () => resolve(), { once: true });
     }
     client!.device.events.onDeviceStatus.subscribe((status: number) => {
-      if (status === 2 /* DeviceDisconnected */) {
+      if (status === DeviceStatus.Disconnected) {
         logger.info(`[${account.accountId}] device disconnected, exiting monitor`);
         resolve();
       }
@@ -203,6 +229,7 @@ async function monitorDevice(params: {
 
   // Give the OS time to release the serial port lock before the framework
   // restarts the channel (which would immediately try to reopen it).
+  logger.info(`[${account.accountId}] releasing serial port (3s delay)...`);
   await new Promise<void>((r) => setTimeout(r, 3_000));
 
   return { stop: () => {} };
@@ -220,7 +247,7 @@ async function monitorMqtt(params: {
   const mqttConfig = account.config.mqtt;
 
   if (!mqttConfig?.broker) {
-    throw new Error("MQTT broker not configured");
+    throw new Error("MQTT broker not configured. Set channels.meshtastic.mqtt.broker or run 'openclaw setup'.");
   }
 
   let mqttClient: MeshtasticMqttClient | null = null;

package/src/mqtt-client.ts

@@ -2,6 +2,16 @@ import mqtt from "mqtt";
 import { nodeNumToHex } from "./normalize.js";
 import type { MeshtasticMqttConfig } from "./types.js";
 
+/** Derive a publish topic from a subscribe topic.
+ *  Standard pattern: "msh/REGION/NUM/json/#" → "msh/REGION/NUM/json/mqtt".
+ *  If the topic has no wildcard suffix, appends "/mqtt" as the publish leaf. */
+function derivePublishTopic(subscribeTopic: string): string {
+  if (subscribeTopic.endsWith("/#")) {
+    return subscribeTopic.slice(0, -2) + "/mqtt";
+  }
+  return subscribeTopic + "/mqtt";
+}
+
 export type MeshtasticMqttTextEvent = {
   senderNodeId: string;
   senderName?: string;
@@ -50,9 +60,16 @@ export async function connectMeshtasticMqtt(
   const username = mqttConfig.username ?? "meshdev";
   const password = mqttConfig.password ?? "large4cats";
   const topic = mqttConfig.topic ?? "msh/US/2/json/#";
-  const publishTopic = mqttConfig.publishTopic ?? topic.replace("/#", "/mqtt");
+  const publishTopic = mqttConfig.publishTopic ?? derivePublishTopic(topic);
   const protocol = mqttConfig.tls ? "mqtts" : "mqtt";
-  const myNodeId = options.myNodeId?.toLowerCase();
+  const myNodeId = (mqttConfig.myNodeId ?? options.myNodeId)?.toLowerCase();
+
+  if (!myNodeId) {
+    options.onStatus?.(
+      "warning: myNodeId not set — all messages will be treated as group. " +
+        "Set channels.meshtastic.mqtt.myNodeId for DM support.",
+    );
+  }
 
   const client = mqtt.connect(`${protocol}://${broker}:${port}`, {
     username,
@@ -111,13 +128,19 @@ export async function connectMeshtasticMqtt(
     }
 
     // Determine DM vs broadcast.
-    // MQTT JSON doesn't clearly distinguish DM; if `to` is a specific node and matches our ID, it's direct.
-    const isDirect = myNodeId
-      ? msg.to !== undefined && nodeNumToHex(msg.to).toLowerCase() === myNodeId
-      : false;
+    // MQTT JSON: if `to` matches our node ID, it's a direct message.
+    const isDirect = myNodeId !== undefined
+      && msg.to !== undefined
+      && msg.to !== 0xffffffff
+      && nodeNumToHex(msg.to).toLowerCase() === myNodeId;
+
+    const senderName = msg.sender && msg.sender !== senderNodeId
+      ? msg.sender
+      : undefined;
 
     const event: MeshtasticMqttTextEvent = {
       senderNodeId: senderNodeId.startsWith("!") ? senderNodeId : `!${senderNodeId}`,
+      senderName,
       text: msg.payload.text,
       channelIndex: msg.channel ?? 0,
       channelName: msg.channel_name,
@@ -152,6 +175,7 @@ export async function connectMeshtasticMqtt(
         type: "sendtext",
         payload: { text },
         ...(destination ? { to: Number.parseInt(destination.replace("!", ""), 16) } : {}),
+        ...(channelName ? { channel_name: channelName } : {}),
       };
       client.publish(outboundTopic, JSON.stringify(message));
     },

package/src/normalize.ts

@@ -28,13 +28,16 @@ export function normalizeMeshtasticNodeId(raw: string): string {
     }
     return trimmed;
   }
+  // Bare hex string (contains at least one a-f character to disambiguate from decimal).
+  if (/^[0-9a-f]{1,8}$/i.test(trimmed) && !/^\d+$/.test(trimmed)) {
+    return `!${trimmed.padStart(8, "0")}`;
+  }
   const num = Number.parseInt(trimmed, 10);
   if (Number.isFinite(num) && num >= 0) {
     return nodeNumToHex(num);
   }
   return trimmed;
 }
-
 /** Check if a string looks like a Meshtastic node ID (!hex or numeric). */
 export function looksLikeMeshtasticNodeId(raw: string): boolean {
   const trimmed = raw.trim();
@@ -44,10 +47,13 @@ export function looksLikeMeshtasticNodeId(raw: string): boolean {
   if (trimmed.startsWith("!") && /^![0-9a-f]{1,8}$/i.test(trimmed)) {
     return true;
   }
+  // Bare hex string (contains at least one a-f to disambiguate from decimal).
+  if (/^[0-9a-f]{1,8}$/i.test(trimmed) && !/^\d+$/.test(trimmed)) {
+    return true;
+  }
   const num = Number.parseInt(trimmed, 10);
   return Number.isFinite(num) && num >= 0 && String(num) === trimmed;
 }
-
 /** Normalize a messaging target. Strips "meshtastic:" prefix, resolves channel: prefix. */
 export function normalizeMeshtasticMessagingTarget(raw: string): string | undefined {
   const trimmed = raw.trim();
@@ -89,8 +95,10 @@ export function normalizeMeshtasticAllowEntry(raw: string): string {
 }
 
 /** Normalize a list of allowlist entries. */
-export function normalizeMeshtasticAllowlist(entries?: string[]): string[] {
-  return (entries ?? []).map((entry) => normalizeMeshtasticAllowEntry(entry)).filter(Boolean);
+export function normalizeMeshtasticAllowlist(entries?: unknown[]): string[] {
+  return (entries ?? [])
+    .map((entry) => (typeof entry === "string" ? normalizeMeshtasticAllowEntry(entry) : ""))
+    .filter(Boolean);
 }
 
 /** Check if sender matches an allowlist. */