@cheeko-ai/esp32-voice 2026.2.21

package/src/accounts.ts

@@ -0,0 +1,110 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+import type { Esp32VoiceAccountConfig, ResolvedEsp32VoiceAccount } from "./types.js";
+
+/**
+ * List all configured ESP32 Voice account IDs.
+ */
+export function listEsp32VoiceAccountIds(cfg: OpenClawConfig): string[] {
+  const section = cfg.channels?.esp32voice as Esp32VoiceAccountConfig & {
+    accounts?: Record<string, Esp32VoiceAccountConfig>;
+  };
+  if (!section) {
+    return [];
+  }
+
+  const ids = new Set<string>();
+
+  // Base-level config counts as the "default" account.
+  if (section.deviceToken || section.deviceId) {
+    ids.add(DEFAULT_ACCOUNT_ID);
+  }
+
+  // Named accounts.
+  if (section.accounts) {
+    for (const key of Object.keys(section.accounts)) {
+      ids.add(normalizeAccountId(key));
+    }
+  }
+
+  return [...ids];
+}
+
+/**
+ * Resolve the default account ID.
+ */
+export function resolveDefaultEsp32VoiceAccountId(cfg: OpenClawConfig): string {
+  const ids = listEsp32VoiceAccountIds(cfg);
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * Resolve a fully populated account config for a given account ID.
+ * Merges base-level config ← per-account overrides ← env vars.
+ */
+export function resolveEsp32VoiceAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string;
+}): ResolvedEsp32VoiceAccount {
+  const { cfg, accountId: rawAccountId } = params;
+  const accountId = normalizeAccountId(rawAccountId ?? DEFAULT_ACCOUNT_ID);
+
+  const section = cfg.channels?.esp32voice as Esp32VoiceAccountConfig & {
+    accounts?: Record<string, Esp32VoiceAccountConfig>;
+  };
+
+  const base: Esp32VoiceAccountConfig = section ?? {};
+  const perAccount = section?.accounts?.[accountId] ?? {};
+
+  // Per-account fields override base fields.
+  const merged: Esp32VoiceAccountConfig = { ...base, ...perAccount };
+
+  // ── Resolve device token ──
+  let deviceToken = merged.deviceToken?.trim() || undefined;
+  let deviceTokenSource: "config" | "env" | "none" = deviceToken ? "config" : "none";
+  if (!deviceToken) {
+    const envToken = process.env.ESP32_VOICE_DEVICE_TOKEN?.trim();
+    if (envToken) {
+      deviceToken = envToken;
+      deviceTokenSource = "env";
+    }
+  }
+
+  // ── Resolve STT API key ──
+  let sttApiKey = merged.sttApiKey?.trim() || undefined;
+  if (!sttApiKey) {
+    sttApiKey = process.env.DEEPGRAM_API_KEY?.trim() || undefined;
+  }
+
+  // ── Resolve TTS API key ──
+  let ttsApiKey = merged.ttsApiKey?.trim() || undefined;
+  if (!ttsApiKey) {
+    ttsApiKey = process.env.ELEVENLABS_API_KEY?.trim() || process.env.XI_API_KEY?.trim() || undefined;
+  }
+
+  // ── Resolve TTS voice ID ──
+  let ttsVoiceId = merged.ttsVoiceId?.trim() || undefined;
+  if (!ttsVoiceId) {
+    ttsVoiceId = process.env.ELEVENLABS_VOICE_ID?.trim() || undefined;
+  }
+
+  return {
+    accountId,
+    name: merged.name,
+    enabled: merged.enabled !== false,
+    deviceToken,
+    deviceTokenSource,
+    deviceId: merged.deviceId || accountId,
+    sttProvider: merged.sttProvider ?? "deepgram",
+    sttApiKey,
+    sttModel: merged.sttModel,
+    ttsProvider: merged.ttsProvider ?? "elevenlabs",
+    ttsApiKey,
+    ttsVoiceId,
+    ttsModel: merged.ttsModel,
+    maxResponseLength: merged.maxResponseLength ?? 500,
+    voiceOptimized: merged.voiceOptimized !== false,
+    language: merged.language ?? "en",
+    config: merged,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,270 @@
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  normalizeAccountId,
+  setAccountEnabledInConfigSection,
+  deleteAccountFromConfigSection,
+  applyAccountNameToChannelSection,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk";
+import { Esp32VoiceConfigSchema } from "./config-schema.js";
+import {
+  listEsp32VoiceAccountIds,
+  resolveDefaultEsp32VoiceAccountId,
+  resolveEsp32VoiceAccount,
+  type ResolvedEsp32VoiceAccount,
+} from "./accounts.js";
+import { monitorEsp32VoiceProvider } from "./monitor.js";
+import { getEsp32VoiceRuntime } from "./runtime.js";
+import { esp32VoiceOnboardingAdapter } from "./onboarding.js";
+
+const meta = {
+  id: "esp32voice",
+  label: "ESP32 Voice",
+  selectionLabel: "ESP32 Voice (plugin)",
+  detailLabel: "ESP32 Voice Device",
+  docsPath: "/channels/esp32-voice",
+  docsLabel: "esp32-voice",
+  blurb: "ESP32 IoT voice device — speech-to-text-to-speech via HTTP.",
+  systemImage: "waveform",
+  order: 90,
+  quickstartAllowFrom: false,
+} as const;
+
+export const esp32VoicePlugin: ChannelPlugin<ResolvedEsp32VoiceAccount> = {
+  id: "esp32voice",
+  meta: {
+    ...meta,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    reactions: false,
+    threads: false,
+    media: false,
+  },
+  reload: { configPrefixes: ["channels.esp32voice"] },
+  configSchema: buildChannelConfigSchema(Esp32VoiceConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listEsp32VoiceAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveEsp32VoiceAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultEsp32VoiceAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg,
+        sectionKey: "esp32voice",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg,
+        sectionKey: "esp32voice",
+        accountId,
+        clearBaseFields: ["deviceToken", "deviceId", "name"],
+      }),
+    isConfigured: (account) => Boolean(account.deviceToken),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.deviceToken),
+      deviceTokenSource: account.deviceTokenSource,
+      deviceId: account.deviceId,
+      language: account.language,
+      voiceOptimized: account.voiceOptimized,
+      maxResponseLength: account.maxResponseLength,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      resolveEsp32VoiceAccount({ cfg, accountId }).config.allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) => allowFrom.filter(Boolean),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(cfg.channels?.esp32voice?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath
+        ? `channels.esp32voice.accounts.${resolvedAccountId}.`
+        : "channels.esp32voice.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("esp32voice"),
+        normalizeEntry: (raw) => raw.trim().toLowerCase(),
+      };
+    },
+    collectWarnings: () => [],
+  },
+  pairing: {
+    idLabel: "esp32DeviceId",
+    normalizeAllowEntry: (entry) => entry.trim().toLowerCase(),
+    notifyApproval: async ({ id }) => {
+      console.log(`[esp32voice] Device ${id} approved for pairing`);
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getEsp32VoiceRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 500,
+    resolveTarget: ({ to }) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return {
+          ok: false,
+          error: new Error("Delivering to ESP32 Voice requires --to <deviceId>"),
+        };
+      }
+      return { ok: true, to: trimmed };
+    },
+    sendText: async ({ to, text }) => {
+      // Outbound to ESP32 is handled via the HTTP response (synchronous).
+      // This is for CLI `openclaw message send --channel esp32voice` support.
+      console.log(`[esp32voice] Outbound message to ${to}: ${text.slice(0, 100)}...`);
+      return {
+        channel: "esp32voice" as const,
+        ok: true,
+        messageId: `esp32-${Date.now()}`,
+      };
+    },
+  },
+  messaging: {
+    normalizeTarget: (target) => target.trim().toLowerCase(),
+    targetResolver: {
+      looksLikeId: (id) => /^esp32[a-z0-9_-]*$/i.test(id),
+      hint: "<deviceId>",
+    },
+  },
+  // Agent prompt: add voice-optimization context so the AI knows responses
+  // will be converted to speech on the device.
+  agentPrompt: {
+    systemPromptSuffix: () =>
+      [
+        "",
+        "## ESP32 Voice Channel Context",
+        "The user is communicating via an ESP32 IoT voice device.",
+        "Your responses will be converted to speech (TTS) and played through a speaker.",
+        "Keep responses concise, conversational, and natural for spoken delivery.",
+        "Avoid markdown formatting, code blocks, lists, and URLs — they don't translate well to speech.",
+        "Aim for 1-3 sentences unless the user asks for detail.",
+        "",
+      ].join("\n"),
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastDisconnect: null,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      deviceTokenSource: snapshot.deviceTokenSource ?? "none",
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      deviceId: snapshot.deviceId ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.deviceToken),
+      deviceTokenSource: account.deviceTokenSource,
+      deviceId: account.deviceId,
+      language: account.language,
+      running: runtime?.running ?? false,
+      connected: runtime?.connected ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "esp32voice",
+        accountId,
+        name,
+      }),
+    validateInput: () => {
+      // No token required — the WebSocket voice pipeline does not need a
+      // pre-configured device token. Devices authenticate via OTP pairing
+      // at runtime. The onboarding wizard handles full setup interactively.
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const token = input.botToken ?? input.token;
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "esp32voice",
+        accountId,
+        name: input.name,
+      });
+
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...namedConfig,
+          channels: {
+            ...namedConfig.channels,
+            esp32voice: {
+              ...namedConfig.channels?.esp32voice,
+              enabled: true,
+              ...(token ? { deviceToken: token } : {}),
+            },
+          },
+        };
+      }
+      return {
+        ...namedConfig,
+        channels: {
+          ...namedConfig.channels,
+          esp32voice: {
+            ...namedConfig.channels?.esp32voice,
+            enabled: true,
+            accounts: {
+              ...namedConfig.channels?.esp32voice?.accounts,
+              [accountId]: {
+                ...namedConfig.channels?.esp32voice?.accounts?.[accountId],
+                enabled: true,
+                ...(token ? { deviceToken: token } : {}),
+              },
+            },
+          },
+        },
+      };
+    },
+  },
+  onboarding: esp32VoiceOnboardingAdapter,
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        deviceId: account.deviceId,
+        deviceTokenSource: account.deviceTokenSource,
+      });
+      ctx.log?.info(`[${account.accountId}] starting ESP32 Voice channel`);
+      return monitorEsp32VoiceProvider({
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: getEsp32VoiceRuntime(),
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,37 @@
+import { DmPolicySchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const Esp32VoiceAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+
+    // Auth
+    deviceToken: z.string().optional(),
+    deviceId: z.string().optional(),
+
+    // Security
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.string()).optional(),
+
+    // STT
+    sttProvider: z.string().optional().default("deepgram"),
+    sttApiKey: z.string().optional(),
+    sttModel: z.string().optional(),
+
+    // TTS
+    ttsProvider: z.string().optional().default("elevenlabs"),
+    ttsApiKey: z.string().optional(),
+    ttsVoiceId: z.string().optional(),
+    ttsModel: z.string().optional(),
+
+    // Voice pipeline
+    maxResponseLength: z.number().int().positive().optional().default(500),
+    voiceOptimized: z.boolean().optional().default(true),
+    language: z.string().optional().default("en"),
+  })
+  .strict();
+
+export const Esp32VoiceConfigSchema = Esp32VoiceAccountSchemaBase.extend({
+  accounts: z.record(z.string(), Esp32VoiceAccountSchemaBase.optional()).optional(),
+});

package/src/device/device-otp.ts

@@ -0,0 +1,173 @@
+/**
+ * Device OTP (One-Time Password) pairing system.
+ *
+ * During onboarding, the user gets a 6-digit OTP code displayed in their terminal.
+ * The ESP32 device sends this OTP during its initial hello handshake to pair itself.
+ * Once verified, the device is added to the trusted devices list in config.
+ */
+
+import crypto from "node:crypto";
+
+interface PendingOtp {
+  code: string;
+  deviceId?: string;
+  createdAt: number;
+  expiresAt: number;
+}
+
+interface PairedDevice {
+  deviceId: string;
+  deviceToken: string;
+  pairedAt: string;
+  name?: string;
+}
+
+const OTP_LENGTH = 6;
+const OTP_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+
+class DeviceOtpManager {
+  /** Pending OTPs waiting for device activation. */
+  private pendingOtps = new Map<string, PendingOtp>();
+
+  /** Active paired devices (in-memory, synced to config). */
+  private pairedDevices = new Map<string, PairedDevice>();
+
+  /**
+   * Generate a new OTP for device pairing.
+   *
+   * @returns The OTP code to display to the user.
+   */
+  generateOtp(deviceId?: string): string {
+    // Generate a cryptographically secure 6-digit code
+    const code = crypto.randomInt(100000, 999999).toString();
+
+    const otp: PendingOtp = {
+      code,
+      deviceId,
+      createdAt: Date.now(),
+      expiresAt: Date.now() + OTP_EXPIRY_MS,
+    };
+
+    this.pendingOtps.set(code, otp);
+
+    // Clean up expired OTPs
+    this.cleanupExpired();
+
+    console.log(`[device-otp] Generated OTP: ${code} (expires in 5 minutes)`);
+    return code;
+  }
+
+  /**
+   * Verify an OTP from a device and complete pairing.
+   *
+   * @param code - The OTP code sent by the device.
+   * @param deviceId - The device's self-reported ID.
+   * @returns The device token to use for future authentication, or null if invalid.
+   */
+  verifyOtp(code: string, deviceId: string): { deviceToken: string; paired: PairedDevice } | null {
+    this.cleanupExpired();
+
+    const pending = this.pendingOtps.get(code);
+    if (!pending) {
+      console.warn(`[device-otp] Invalid OTP: ${code}`);
+      return null;
+    }
+
+    if (Date.now() > pending.expiresAt) {
+      this.pendingOtps.delete(code);
+      console.warn(`[device-otp] Expired OTP: ${code}`);
+      return null;
+    }
+
+    // OTP is valid — generate a permanent device token
+    const deviceToken = crypto.randomBytes(32).toString("hex");
+
+    const paired: PairedDevice = {
+      deviceId,
+      deviceToken,
+      pairedAt: new Date().toISOString(),
+    };
+
+    this.pairedDevices.set(deviceId, paired);
+    this.pendingOtps.delete(code);
+
+    console.log(`[device-otp] Device "${deviceId}" paired successfully`);
+    return { deviceToken, paired };
+  }
+
+  /**
+   * Check if a device is paired.
+   */
+  isPaired(deviceId: string): boolean {
+    return this.pairedDevices.has(deviceId);
+  }
+
+  /**
+   * Authenticate a device by its token.
+   *
+   * @returns The device ID if valid, null otherwise.
+   */
+  authenticateToken(token: string): string | null {
+    for (const [deviceId, paired] of this.pairedDevices) {
+      if (paired.deviceToken === token) {
+        return deviceId;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get all paired devices.
+   */
+  listPairedDevices(): PairedDevice[] {
+    return [...this.pairedDevices.values()];
+  }
+
+  /**
+   * Remove a paired device.
+   */
+  unpairDevice(deviceId: string): boolean {
+    return this.pairedDevices.delete(deviceId);
+  }
+
+  /**
+   * Load paired devices from config (call on startup).
+   */
+  loadFromConfig(devices: Record<string, { deviceToken: string; name?: string }>): void {
+    for (const [deviceId, config] of Object.entries(devices)) {
+      this.pairedDevices.set(deviceId, {
+        deviceId,
+        deviceToken: config.deviceToken,
+        pairedAt: "config",
+        name: config.name,
+      });
+    }
+    console.log(`[device-otp] Loaded ${this.pairedDevices.size} paired device(s) from config`);
+  }
+
+  /**
+   * Export paired devices for writing to config.
+   */
+  exportForConfig(): Record<string, { deviceToken: string; name?: string }> {
+    const result: Record<string, { deviceToken: string; name?: string }> = {};
+    for (const [deviceId, paired] of this.pairedDevices) {
+      result[deviceId] = {
+        deviceToken: paired.deviceToken,
+        ...(paired.name ? { name: paired.name } : {}),
+      };
+    }
+    return result;
+  }
+
+  private cleanupExpired(): void {
+    const now = Date.now();
+    for (const [code, otp] of this.pendingOtps) {
+      if (now > otp.expiresAt) {
+        this.pendingOtps.delete(code);
+      }
+    }
+  }
+}
+
+/** Global device OTP manager. */
+export const deviceOtpManager = new DeviceOtpManager();