@seeed-studio/meshtastic 0.1.0

package/src/monitor.ts

@@ -0,0 +1,300 @@
+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 { handleMeshtasticInbound } from "./inbound.js";
+import { connectMeshtasticMqtt, type MeshtasticMqttClient } from "./mqtt-client.js";
+import { nodeNumToHex } from "./normalize.js";
+import { getMeshtasticRuntime } from "./runtime.js";
+import { setActiveSerialSend, setActiveMqttSend } from "./send.js";
+import type { CoreConfig, MeshtasticInboundMessage } from "./types.js";
+
+export type MeshtasticMonitorOptions = {
+  accountId?: string;
+  config?: CoreConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export async function monitorMeshtasticProvider(
+  opts: MeshtasticMonitorOptions,
+): Promise<{ stop: () => void }> {
+  const core = getMeshtasticRuntime();
+  const cfg = opts.config ?? (core.config.loadConfig() as CoreConfig);
+  const account = resolveMeshtasticAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+
+  const runtime: RuntimeEnv =
+    opts.runtime ??
+    createLoggerBackedRuntime({
+      logger: core.logging.getChildLogger(),
+      exitError: () => new Error("Runtime exit not available"),
+    });
+
+  if (!account.configured) {
+    throw new Error(
+      `Meshtastic is not configured for account "${account.accountId}". ` +
+        `Set channels.meshtastic.transport and connection details.`,
+    );
+  }
+
+  const logger = core.logging.getChildLogger({
+    channel: "meshtastic",
+    accountId: account.accountId,
+  });
+
+  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") {
+    return monitorMqtt({ account, cfg: effectiveCfg, runtime, logger, opts });
+  }
+  return monitorDevice({ account, cfg: effectiveCfg, runtime, logger, opts, transport });
+}
+
+async function monitorDevice(params: {
+  account: ReturnType<typeof resolveMeshtasticAccount>;
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  logger: ReturnType<ReturnType<typeof getMeshtasticRuntime>["logging"]["getChildLogger"]>;
+  opts: MeshtasticMonitorOptions;
+  transport: "serial" | "http";
+}): Promise<{ stop: () => void }> {
+  const { account, cfg, runtime, logger, opts, transport } = params;
+  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,
+      };
+
+      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(() => {});
+          } 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,
+      });
+    },
+  });
+
+  // Register active send function for `openclaw message send`.
+  setActiveSerialSend((text, destination, channelIndex) =>
+    client ? client.sendText(text, destination, true, channelIndex) : Promise.resolve(0),
+  );
+
+  const address =
+    transport === "serial"
+      ? account.serialPort
+      : `${account.httpAddress}${account.httpTls ? " (tls)" : ""}`;
+  logger.info(
+    `[${account.accountId}] connected via ${transport} (${address}), node ${nodeNumToHex(client.myNodeNum)}`,
+  );
+
+  // Block until the gateway aborts or the device disconnects.
+  // Returning from startAccount signals "channel exited" to the framework,
+  // which triggers auto-restart.  We must stay alive so the serial port
+  // remains open and isn't double-locked on reconnect.
+  await new Promise<void>((resolve) => {
+    if (opts.abortSignal) {
+      opts.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    }
+    client!.device.events.onDeviceStatus.subscribe((status: number) => {
+      if (status === 2 /* DeviceDisconnected */) {
+        logger.info(`[${account.accountId}] device disconnected, exiting monitor`);
+        resolve();
+      }
+    });
+  });
+
+  // Cleanup: release the serial port so the next start can open it.
+  setActiveSerialSend(null);
+  client?.close();
+  client = null;
+
+  // Give the OS time to release the serial port lock before the framework
+  // restarts the channel (which would immediately try to reopen it).
+  await new Promise<void>((r) => setTimeout(r, 3_000));
+
+  return { stop: () => {} };
+}
+
+async function monitorMqtt(params: {
+  account: ReturnType<typeof resolveMeshtasticAccount>;
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  logger: ReturnType<ReturnType<typeof getMeshtasticRuntime>["logging"]["getChildLogger"]>;
+  opts: MeshtasticMonitorOptions;
+}): Promise<{ stop: () => void }> {
+  const { account, cfg, runtime, logger, opts } = params;
+  const core = getMeshtasticRuntime();
+  const mqttConfig = account.config.mqtt;
+
+  if (!mqttConfig?.broker) {
+    throw new Error("MQTT broker not configured");
+  }
+
+  let mqttClient: MeshtasticMqttClient | null = null;
+
+  mqttClient = await connectMeshtasticMqtt({
+    mqtt: mqttConfig,
+    abortSignal: opts.abortSignal,
+    onStatus: (status) => {
+      logger.info(`[${account.accountId}] mqtt: ${status}`);
+    },
+    onError: (error) => {
+      logger.error(`[${account.accountId}] mqtt error: ${error.message}`);
+    },
+    onText: async (event) => {
+      const message: MeshtasticInboundMessage = {
+        messageId: randomUUID(),
+        senderNodeId: event.senderNodeId,
+        senderName: event.senderName,
+        channelIndex: event.channelIndex,
+        channelName: event.channelName ?? `channel-${event.channelIndex}`,
+        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 (!mqttClient) {
+            return;
+          }
+          const channelName = message.isGroup ? message.channelName : undefined;
+          await mqttClient.sendText(text, message.isGroup ? undefined : target, channelName);
+          opts.statusSink?.({ lastOutboundAt: Date.now() });
+          core.channel.activity.record({
+            channel: "meshtastic",
+            accountId: account.accountId,
+            direction: "outbound",
+          });
+        },
+        statusSink: opts.statusSink,
+      });
+    },
+  });
+
+  // Register active send function for `openclaw message send`.
+  setActiveMqttSend((text, destination, channelName) =>
+    mqttClient ? mqttClient.sendText(text, destination, channelName) : Promise.resolve(),
+  );
+
+  logger.info(
+    `[${account.accountId}] connected via mqtt (${mqttConfig.broker}:${mqttConfig.port ?? 1883})`,
+  );
+
+  // Block until the gateway aborts.  Same pattern as monitorDevice.
+  await new Promise<void>((resolve) => {
+    if (opts.abortSignal) {
+      opts.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    }
+  });
+
+  setActiveMqttSend(null);
+  mqttClient?.close();
+  mqttClient = null;
+
+  return { stop: () => {} };
+}

package/src/mqtt-client.ts

@@ -0,0 +1,162 @@
+import mqtt from "mqtt";
+import { nodeNumToHex } from "./normalize.js";
+import type { MeshtasticMqttConfig } from "./types.js";
+
+export type MeshtasticMqttTextEvent = {
+  senderNodeId: string;
+  senderName?: string;
+  text: string;
+  channelIndex: number;
+  channelName?: string;
+  isDirect: boolean;
+  rxTime: number;
+};
+
+export type MeshtasticMqttClientOptions = {
+  mqtt: MeshtasticMqttConfig;
+  myNodeId?: string;
+  abortSignal?: AbortSignal;
+  onText?: (event: MeshtasticMqttTextEvent) => void | Promise<void>;
+  onStatus?: (status: string) => void;
+  onError?: (error: Error) => void;
+};
+
+export type MeshtasticMqttClient = {
+  sendText: (text: string, destination?: string, channelName?: string) => Promise<void>;
+  close: () => void;
+};
+
+/**
+ * Meshtastic MQTT JSON message format.
+ * Messages on the JSON topic contain: sender, from, type, payload, channel.
+ */
+type MqttJsonMessage = {
+  sender?: string;
+  from?: number;
+  to?: number;
+  type?: string;
+  payload?: { text?: string };
+  channel?: number;
+  channel_name?: string;
+};
+
+/** Connect to a Meshtastic mesh via MQTT broker. */
+export async function connectMeshtasticMqtt(
+  options: MeshtasticMqttClientOptions,
+): Promise<MeshtasticMqttClient> {
+  const mqttConfig = options.mqtt;
+  const broker = mqttConfig.broker ?? "mqtt.meshtastic.org";
+  const port = mqttConfig.port ?? 1883;
+  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 protocol = mqttConfig.tls ? "mqtts" : "mqtt";
+  const myNodeId = options.myNodeId?.toLowerCase();
+
+  const client = mqtt.connect(`${protocol}://${broker}:${port}`, {
+    username,
+    password,
+    clean: true,
+    reconnectPeriod: 5000,
+  });
+
+  client.on("connect", () => {
+    options.onStatus?.("connected");
+    client.subscribe(topic, (err) => {
+      if (err) {
+        options.onError?.(new Error(`MQTT subscribe failed: ${err.message}`));
+      } else {
+        options.onStatus?.(`subscribed to ${topic}`);
+      }
+    });
+  });
+
+  client.on("error", (err) => {
+    options.onError?.(err);
+  });
+
+  client.on("reconnect", () => {
+    options.onStatus?.("reconnecting");
+  });
+
+  client.on("message", async (_topic, payload) => {
+    if (!options.onText) {
+      return;
+    }
+
+    let msg: MqttJsonMessage;
+    try {
+      msg = JSON.parse(payload.toString()) as MqttJsonMessage;
+    } catch {
+      return;
+    }
+
+    // Only handle text messages.
+    if (msg.type !== "sendtext" || !msg.payload?.text) {
+      return;
+    }
+
+    // Skip own messages.
+    const senderNodeId = msg.sender
+      ? msg.sender.toLowerCase()
+      : msg.from
+        ? nodeNumToHex(msg.from)
+        : undefined;
+    if (!senderNodeId) {
+      return;
+    }
+    if (myNodeId && senderNodeId === myNodeId) {
+      return;
+    }
+
+    // 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;
+
+    const event: MeshtasticMqttTextEvent = {
+      senderNodeId: senderNodeId.startsWith("!") ? senderNodeId : `!${senderNodeId}`,
+      text: msg.payload.text,
+      channelIndex: msg.channel ?? 0,
+      channelName: msg.channel_name,
+      isDirect,
+      rxTime: Date.now(),
+    };
+
+    try {
+      await options.onText(event);
+    } catch (err) {
+      options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  });
+
+  if (options.abortSignal) {
+    options.abortSignal.addEventListener(
+      "abort",
+      () => {
+        client.end(true);
+      },
+      { once: true },
+    );
+  }
+
+  return {
+    sendText: async (text, destination, channelName) => {
+      const outboundTopic = channelName
+        ? publishTopic.replace(/\/[^/]*$/, `/${channelName}`)
+        : publishTopic;
+      const message: MqttJsonMessage = {
+        sender: myNodeId ?? options.myNodeId,
+        type: "sendtext",
+        payload: { text },
+        ...(destination ? { to: Number.parseInt(destination.replace("!", ""), 16) } : {}),
+      };
+      client.publish(outboundTopic, JSON.stringify(message));
+    },
+    close: () => {
+      client.end(true);
+    },
+  };
+}

package/src/normalize.ts

@@ -0,0 +1,112 @@
+import type { MeshtasticInboundMessage } from "./types.js";
+
+/** Convert numeric node ID to !hex format (e.g. 2882400001 -> "!abcd0001"). */
+export function nodeNumToHex(nodeNum: number): string {
+  return `!${nodeNum.toString(16).padStart(8, "0")}`;
+}
+
+/** Convert !hex node ID to numeric (e.g. "!abcd0001" -> 2882400001). */
+export function hexToNodeNum(hex: string): number {
+  const cleaned = hex.startsWith("!") ? hex.slice(1) : hex;
+  const parsed = Number.parseInt(cleaned, 16);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`Invalid Meshtastic node ID: ${hex}`);
+  }
+  return parsed;
+}
+
+/** Normalize a node ID to !hex format. Accepts !hex or numeric string. */
+export function normalizeMeshtasticNodeId(raw: string): string {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed.startsWith("!")) {
+    const hex = trimmed.slice(1);
+    if (/^[0-9a-f]{1,8}$/i.test(hex)) {
+      return `!${hex.padStart(8, "0")}`;
+    }
+    return trimmed;
+  }
+  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();
+  if (!trimmed) {
+    return false;
+  }
+  if (trimmed.startsWith("!") && /^![0-9a-f]{1,8}$/i.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();
+  if (!trimmed) {
+    return undefined;
+  }
+  let target = trimmed;
+  if (target.toLowerCase().startsWith("meshtastic:")) {
+    target = target.slice("meshtastic:".length).trim();
+  }
+  if (target.toLowerCase().startsWith("channel:")) {
+    return target.slice("channel:".length).trim() || undefined;
+  }
+  if (target.toLowerCase().startsWith("user:")) {
+    target = target.slice("user:".length).trim();
+  }
+  if (!target) {
+    return undefined;
+  }
+  if (looksLikeMeshtasticNodeId(target)) {
+    return normalizeMeshtasticNodeId(target);
+  }
+  return target;
+}
+
+/** Normalize an allowlist entry (lowercase, strip meshtastic: prefix). */
+export function normalizeMeshtasticAllowEntry(raw: string): string {
+  let value = raw.trim().toLowerCase();
+  if (!value) {
+    return "";
+  }
+  if (value.startsWith("meshtastic:")) {
+    value = value.slice("meshtastic:".length);
+  }
+  if (value.startsWith("user:")) {
+    value = value.slice("user:".length);
+  }
+  return normalizeMeshtasticNodeId(value.trim());
+}
+
+/** Normalize a list of allowlist entries. */
+export function normalizeMeshtasticAllowlist(entries?: string[]): string[] {
+  return (entries ?? []).map((entry) => normalizeMeshtasticAllowEntry(entry)).filter(Boolean);
+}
+
+/** Check if sender matches an allowlist. */
+export function resolveMeshtasticAllowlistMatch(params: {
+  allowFrom: string[];
+  message: MeshtasticInboundMessage;
+}): { allowed: boolean; source?: string } {
+  const allowFrom = new Set(
+    params.allowFrom.map((entry) => entry.trim().toLowerCase()).filter(Boolean),
+  );
+  if (allowFrom.has("*")) {
+    return { allowed: true, source: "wildcard" };
+  }
+  const nodeId = normalizeMeshtasticNodeId(params.message.senderNodeId).toLowerCase();
+  if (nodeId && allowFrom.has(nodeId)) {
+    return { allowed: true, source: nodeId };
+  }
+  return { allowed: false };
+}