@seeed-studio/meshtastic 0.1.0

package/src/channel.ts

@@ -0,0 +1,347 @@
+import {
+  buildBaseAccountStatusSnapshot,
+  buildBaseChannelStatusSummary,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  PAIRING_APPROVED_MESSAGE,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  setAccountEnabledInConfigSection,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk";
+import {
+  listMeshtasticAccountIds,
+  resolveDefaultMeshtasticAccountId,
+  resolveMeshtasticAccount,
+  type ResolvedMeshtasticAccount,
+} from "./accounts.js";
+import { MeshtasticConfigSchema } from "./config-schema.js";
+import { monitorMeshtasticProvider } from "./monitor.js";
+import {
+  normalizeMeshtasticMessagingTarget,
+  looksLikeMeshtasticNodeId,
+  normalizeMeshtasticAllowEntry,
+  normalizeMeshtasticNodeId,
+} from "./normalize.js";
+import { meshtasticOnboardingAdapter } from "./onboarding.js";
+import { resolveMeshtasticGroupMatch, resolveMeshtasticRequireMention } from "./policy.js";
+import { getMeshtasticRuntime } from "./runtime.js";
+import { sendMessageMeshtastic } from "./send.js";
+import type { CoreConfig, MeshtasticProbe } from "./types.js";
+
+const meta = {
+  id: "meshtastic",
+  label: "Meshtastic",
+  selectionLabel: "Meshtastic (plugin)",
+  docsPath: "/channels/meshtastic",
+  docsLabel: "meshtastic",
+  blurb: "LoRa mesh network; configure serial, HTTP, or MQTT transport.",
+  order: 80,
+  quickstartAllowFrom: true,
+};
+
+export const meshtasticPlugin: ChannelPlugin<ResolvedMeshtasticAccount, MeshtasticProbe> = {
+  id: "meshtastic",
+  meta: {
+    ...meta,
+    quickstartAllowFrom: true,
+  },
+  onboarding: meshtasticOnboardingAdapter,
+  pairing: {
+    idLabel: "meshtasticNode",
+    normalizeAllowEntry: (entry) => normalizeMeshtasticAllowEntry(entry),
+    notifyApproval: async ({ id }) => {
+      const normalized = normalizeMeshtasticNodeId(id);
+      if (!normalized) {
+        throw new Error(`invalid Meshtastic pairing id: ${id}`);
+      }
+      await sendMessageMeshtastic(normalized, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.meshtastic"] },
+  configSchema: buildChannelConfigSchema(MeshtasticConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listMeshtasticAccountIds(cfg as CoreConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultMeshtasticAccountId(cfg as CoreConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "meshtastic",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "meshtastic",
+        accountId,
+        clearBaseFields: ["name", "transport", "serialPort", "httpAddress", "httpTls", "mqtt"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      transport: account.transport,
+      serialPort: account.serialPort || undefined,
+      httpAddress: account.httpAddress || undefined,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId }).config.allowFrom ?? []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom.map((entry) => normalizeMeshtasticAllowEntry(String(entry))).filter(Boolean),
+    resolveDefaultTo: ({ cfg, accountId }) =>
+      resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId }).config.defaultTo?.trim() ||
+      undefined,
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.meshtastic?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.meshtastic.accounts.${resolvedAccountId}.`
+        : "channels.meshtastic.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: `${basePath}allowFrom`,
+        approveHint: formatPairingApproveHint("meshtastic"),
+        normalizeEntry: (raw) => normalizeMeshtasticAllowEntry(raw),
+      };
+    },
+    collectWarnings: ({ account, cfg }) => {
+      const warnings: string[] = [];
+      const defaultGroupPolicy = resolveDefaultGroupPolicy(cfg);
+      const { groupPolicy } = resolveAllowlistProviderRuntimeGroupPolicy({
+        providerConfigPresent: cfg.channels?.meshtastic !== undefined,
+        groupPolicy: account.config.groupPolicy,
+        defaultGroupPolicy,
+      });
+      if (groupPolicy === "open") {
+        warnings.push(
+          '- Meshtastic channels: groupPolicy="open" allows all channels and senders (mention-gated). Prefer channels.meshtastic.groupPolicy="allowlist" with channels.meshtastic.channels.',
+        );
+      }
+      if (account.transport === "mqtt" && !account.config.mqtt?.tls) {
+        warnings.push("- Meshtastic MQTT TLS is disabled; credentials are sent in plaintext.");
+      }
+      return warnings;
+    },
+  },
+  groups: {
+    resolveRequireMention: ({ cfg, accountId, groupId }) => {
+      const account = resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId });
+      if (!groupId) {
+        return true;
+      }
+      const match = resolveMeshtasticGroupMatch({
+        groups: account.config.channels,
+        target: groupId,
+      });
+      return resolveMeshtasticRequireMention({
+        groupConfig: match.groupConfig,
+        wildcardConfig: match.wildcardConfig,
+      });
+    },
+    resolveToolPolicy: ({ cfg, accountId, groupId }) => {
+      const account = resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId });
+      if (!groupId) {
+        return undefined;
+      }
+      const match = resolveMeshtasticGroupMatch({
+        groups: account.config.channels,
+        target: groupId,
+      });
+      return match.groupConfig?.tools ?? match.wildcardConfig?.tools;
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeMeshtasticMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeMeshtasticNodeId,
+      hint: "<!nodeId>",
+    },
+  },
+  resolver: {
+    resolveTargets: async ({ inputs, kind }) => {
+      return inputs.map((input) => {
+        const normalized = normalizeMeshtasticMessagingTarget(input);
+        if (!normalized) {
+          return {
+            input,
+            resolved: false,
+            note: "invalid Meshtastic target",
+          };
+        }
+        if (kind === "group") {
+          return {
+            input,
+            resolved: true,
+            id: normalized,
+            name: normalized,
+          };
+        }
+        if (!looksLikeMeshtasticNodeId(normalized)) {
+          return {
+            input,
+            resolved: false,
+            note: "expected node ID target",
+          };
+        }
+        return {
+          input,
+          resolved: true,
+          id: normalized,
+          name: normalized,
+        };
+      });
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() ?? "";
+      const ids = new Set<string>();
+
+      for (const entry of account.config.allowFrom ?? []) {
+        const normalized = normalizeMeshtasticAllowEntry(entry);
+        if (normalized && normalized !== "*") {
+          ids.add(normalized);
+        }
+      }
+      for (const entry of account.config.groupAllowFrom ?? []) {
+        const normalized = normalizeMeshtasticAllowEntry(entry);
+        if (normalized && normalized !== "*") {
+          ids.add(normalized);
+        }
+      }
+      for (const ch of Object.values(account.config.channels ?? {})) {
+        for (const entry of ch.allowFrom ?? []) {
+          const normalized = normalizeMeshtasticAllowEntry(entry);
+          if (normalized && normalized !== "*") {
+            ids.add(normalized);
+          }
+        }
+      }
+
+      return Array.from(ids)
+        .filter((id) => (q ? id.includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "user", id }));
+    },
+    listGroups: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMeshtasticAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() ?? "";
+      const groupIds = new Set<string>();
+
+      for (const group of Object.keys(account.config.channels ?? {})) {
+        if (group === "*") {
+          continue;
+        }
+        groupIds.add(group);
+      }
+
+      return Array.from(groupIds)
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "group", id, name: id }));
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getMeshtasticRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 200,
+    sendText: async ({ to, text, accountId }) => {
+      const result = await sendMessageMeshtastic(to, text, {
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "meshtastic", ...result };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ account, snapshot }) => ({
+      ...buildBaseChannelStatusSummary(snapshot),
+      transport: account.transport,
+      serialPort: account.serialPort || undefined,
+      httpAddress: account.httpAddress || undefined,
+      probe: snapshot.probe,
+      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",
+          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;
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      ...buildBaseAccountStatusSnapshot({ account, runtime, probe }),
+      transport: account.transport,
+      serialPort: account.serialPort || undefined,
+      httpAddress: account.httpAddress || undefined,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.configured) {
+        throw new Error(
+          `Meshtastic is not configured for account "${account.accountId}". ` +
+            `Set channels.meshtastic.transport and connection details.`,
+        );
+      }
+      const transportDesc =
+        account.transport === "serial"
+          ? `serial (${account.serialPort})`
+          : account.transport === "http"
+            ? `http (${account.httpAddress}${account.httpTls ? " tls" : ""})`
+            : `mqtt (${account.config.mqtt?.broker ?? "?"})`;
+      ctx.log?.info(`[${account.accountId}] starting Meshtastic provider (${transportDesc})`);
+      const { stop } = await monitorMeshtasticProvider({
+        accountId: account.accountId,
+        config: ctx.cfg as CoreConfig,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+      });
+      return { stop };
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,296 @@
+import { MeshDevice } from "@meshtastic/core";
+import { nodeNumToHex } from "./normalize.js";
+import type { MeshtasticRegion } from "./types.js";
+
+export type MeshtasticTextEvent = {
+  senderNodeNum: number;
+  senderNodeId: string;
+  senderName?: string;
+  text: string;
+  channelIndex: number;
+  isDirect: boolean;
+  rxTime: number;
+};
+
+export type MeshtasticClientOptions = {
+  transport: "serial" | "http";
+  serialPort?: string;
+  httpAddress?: string;
+  httpTls?: boolean;
+  /** LoRa region to set on the device after connection. */
+  region?: MeshtasticRegion;
+  /** Device display name — sets the node's longName on connect. */
+  nodeName?: string;
+  abortSignal?: AbortSignal;
+  onText?: (event: MeshtasticTextEvent) => void | Promise<void>;
+  onStatus?: (status: string) => void;
+  onError?: (error: Error) => void;
+};
+
+export type MeshtasticClient = {
+  device: MeshDevice;
+  myNodeNum: number;
+  sendText: (
+    text: string,
+    destination?: number,
+    wantAck?: boolean,
+    channelIndex?: number,
+  ) => Promise<number>;
+  getNodeName: (nodeNum: number) => string | undefined;
+  getChannelName: (index: number) => string | undefined;
+  close: () => void;
+};
+
+/**
+ * Patch SerialPort.prototype.close to not throw when the port is already
+ * closed.  The @meshtastic/transport-node-serial `create()` factory has an
+ * `onError` handler that calls `port.close()` on a port that may never have
+ * opened (e.g. "Resource temporarily unavailable / Cannot lock port").  The
+ * synchronous throw from the native close() becomes an uncaught exception.
+ */
+async function patchSerialPortClose(): Promise<void> {
+  try {
+    const { SerialPort } = (await import("serialport")) as {
+      SerialPort: { prototype: { close: ((...a: unknown[]) => unknown) & { __patched?: boolean } } };
+    };
+    const proto = SerialPort.prototype;
+    if (proto.close && !proto.close.__patched) {
+      const origClose = proto.close;
+      const patched = function patchedClose(this: { isOpen?: boolean }, ...args: unknown[]) {
+        if (!this.isOpen) {
+          // Port already closed — invoke callback (if any) with the error
+          // instead of throwing synchronously.
+          const cb = typeof args[args.length - 1] === "function" ? args[args.length - 1] : undefined;
+          if (cb) (cb as (e: Error) => void)(new Error("Port is not open"));
+          return;
+        }
+        return origClose.apply(this, args);
+      };
+      patched.__patched = true;
+      proto.close = patched as typeof proto.close;
+    }
+  } catch {
+    // Best-effort; serialport may not be installed (HTTP transport).
+  }
+}
+
+/** Connect to a Meshtastic device via serial or HTTP transport. */
+export async function connectMeshtasticClient(
+  options: MeshtasticClientOptions,
+): Promise<MeshtasticClient> {
+  let transport;
+  if (options.transport === "serial") {
+    // Patch before create() so the factory's onError handler won't throw.
+    await patchSerialPortClose();
+    const { TransportNodeSerial } = await import("@meshtastic/transport-node-serial");
+    transport = await TransportNodeSerial.create(options.serialPort ?? "");
+  } else {
+    const { TransportHTTP } = await import("@meshtastic/transport-http");
+    const address = options.httpAddress ?? "meshtastic.local";
+    const prefix = options.httpTls ? "https" : "http";
+    transport = await TransportHTTP.create(`${prefix}://${address}`);
+  }
+
+  const device = new MeshDevice(transport);
+
+  // Node info cache for name resolution.
+  const nodeNames = new Map<number, string>();
+  const channelNames = new Map<number, string>();
+  let myNodeNum = 0;
+
+  // Subscribe to device events before configuring.
+  // Event types from @meshtastic/core are complex generics; use explicit shapes.
+  device.events.onMyNodeInfo.subscribe((info: { myNodeNum?: number }) => {
+    if (info.myNodeNum) {
+      myNodeNum = info.myNodeNum;
+    }
+  });
+
+  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);
+      }
+    },
+  );
+
+  device.events.onConfigPacket.subscribe(
+    (packet: {
+      data?: {
+        payloadVariantCase?: string;
+        payloadVariant?: { value?: { index?: number; settings?: { name?: string } } };
+      };
+    }) => {
+      // Capture channel config for name resolution.
+      if (packet.data?.payloadVariantCase === "channels") {
+        const ch = packet.data.payloadVariant?.value;
+        if (ch && typeof ch.index === "number" && ch.settings?.name) {
+          channelNames.set(ch.index, ch.settings.name);
+        }
+      }
+    },
+  );
+
+  device.events.onDeviceStatus.subscribe((status: number) => {
+    options.onStatus?.(`status=${status}`);
+  });
+
+  device.events.onMessagePacket.subscribe(
+    async (packet: { from?: number; to?: number; channel?: number; data?: unknown }) => {
+      if (!options.onText) {
+        return;
+      }
+      const from = packet.from;
+      if (!from || from === myNodeNum) {
+        return;
+      }
+      const text =
+        typeof packet.data === "string" ? packet.data : (packet.data as { text?: string })?.text;
+      if (!text) {
+        return;
+      }
+
+      const senderNodeId = nodeNumToHex(from);
+      const channelIndex = packet.channel ?? 0;
+      // Direct message: packet.to equals our node number.
+      const isDirect = packet.to === myNodeNum;
+
+      const event: MeshtasticTextEvent = {
+        senderNodeNum: from,
+        senderNodeId,
+        senderName: nodeNames.get(from),
+        text: typeof text === "string" ? text : String(text),
+        channelIndex,
+        isDirect,
+        rxTime: Date.now(),
+      };
+
+      try {
+        await options.onText(event);
+      } catch (err) {
+        options.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    },
+  );
+
+  // device.disconnect() may reject asynchronously (WritableStream already
+  // closed by the transport layer after a USB disconnect).  A plain try/catch
+  // only catches synchronous throws, so we must also swallow the returned
+  // promise's rejection.
+  const safeDisconnect = () => {
+    try {
+      const result = device.disconnect();
+      if (result && typeof (result as Promise<unknown>).catch === "function") {
+        (result as Promise<unknown>).catch(() => {});
+      }
+    } catch {
+      // Best-effort cleanup.
+    }
+  };
+
+  // Configure the device (loads channels, nodes, config).
+  // The SDK's configure() sends `wantConfigId` via sendRaw(), which also
+  // triggers the serial transport to start connecting.  Because the first
+  // sendRaw call happens before the transport is connected, the `wantConfigId`
+  // packet is often lost.  We re-call configure() once DeviceConnected is
+  // reached so the device actually receives the config request.
+  let configureRetried = false;
+  const configured = new Promise<void>((resolve, reject) => {
+    let poll: ReturnType<typeof setInterval> | undefined;
+    const cleanup = () => {
+      clearInterval(poll);
+      clearTimeout(timeout);
+    };
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error("device configure timed out (45 s)"));
+    }, 45_000);
+    device.events.onDeviceStatus.subscribe((status: number) => {
+      if (status === 7 /* DeviceConfigured */) {
+        cleanup();
+        resolve();
+      } else if (status === 5 /* DeviceConnected */ && !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 */) {
+        cleanup();
+        reject(new Error("device disconnected during configure"));
+      }
+    });
+    // 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
+      ) {
+        cleanup();
+        resolve();
+      }
+    }, 2_000);
+  });
+  // First configure() call kicks off the transport connection.
+  device.configure().catch(() => {});
+  try {
+    await configured;
+  } catch (err) {
+    // Configuration failed — disconnect the device to release the serial port
+    // so retries can reopen it.
+    safeDisconnect();
+    throw err;
+  }
+
+  // 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(() => {});
+  }
+
+  // Catch unhandled promise rejections originating from @meshtastic/core's
+  // internal transport (e.g. WritableStream.close() on a broken serial port).
+  // Without this the process crashes with exit code 1.
+  let disposed = false;
+  const rejectionGuard = (reason: unknown) => {
+    const msg = reason instanceof Error ? reason.message : String(reason ?? "");
+    if (/WritableStream|Invalid state/i.test(msg)) {
+      // Suppress — handled.  Return without rethrowing so the process
+      // doesn't crash.
+      return;
+    }
+    // Non-transport rejections: let the default handler deal with them.
+    // We can't rethrow here (would crash), so just log.
+    console.error("[meshtastic] unhandled rejection:", reason);
+  };
+  process.on("unhandledRejection", rejectionGuard);
+
+  if (options.abortSignal) {
+    options.abortSignal.addEventListener("abort", () => safeDisconnect(), { once: true });
+  }
+
+  return {
+    device,
+    get myNodeNum() {
+      return myNodeNum;
+    },
+    sendText: (text, destination, wantAck = true, channelIndex) =>
+      device.sendText(text, destination, wantAck, channelIndex),
+    getNodeName: (nodeNum) => nodeNames.get(nodeNum),
+    getChannelName: (index) => channelNames.get(index) || (index === 0 ? "LongFast" : undefined),
+    close: () => {
+      safeDisconnect();
+      // Remove rejection guard — no longer needed after disconnect.
+      if (!disposed) {
+        disposed = true;
+        process.off("unhandledRejection", rejectionGuard);
+      }
+    },
+  };
+}