Tu placa en blanco, hablando con tu Muse.

Antes de empezar.

La placa llega con la demo de fábrica. Aquí instalarás Muse con tu propia cuenta y token SDK, para emparejar el gadget con tu Muse. El token es personal y lo mantienes bajo tu control.

Casi todo el trabajo lo hace un agente de código en tu computador. Tú sacas el token, conectas la placa, confirmas lo que el agente te propone y pruebas.

Paso 01

Saca tu token.

En gadgets.muse.ai, entra a Settings y luego SDK tokens, y crea uno. Empieza por mgst_.

No lo pegues en el chat de ninguna IA. Lo que escribes en el chat queda en el historial. Guárdalo en un archivo y que el agente lo lea de ahí sin mostrarlo:

1. Crea en tu carpeta personal un archivo llamado .muse.env.
2. Escribe adentro una sola línea: MUSE_SDK_TOKEN= y pega tu token después del igual.
3. Guarda. En Mac o Linux, pídele al agente que le deje permisos solo para tu usuario.

Si alguna vez se te filtra, lo revocas en la misma página y creas otro. El token es para uso personal y no comercial, en hasta 50 aparatos.

Paso 02

Conecta la placa.

Con el cable USB-C que viene en el kit, al computador. La placa tiene el USB abajo y el botón de arriba a la derecha: ese botón es el que vas a usar para emparejar y para hablar.

Si el computador no la ve, casi siempre es el cable. Muchos cables USB-C solo cargan y no pasan datos. Prueba con el del kit, directo al computador, sin hub.

Paso 03

Abre tu agente.

Ábrelo en una carpeta nueva, vacía. Lo primero es que confirme qué placa tienes. Al mío le pregunté y le leyó al chip la memoria: 32 MB de flash y 8 MB de PSRAM, que es la 1,75C.

Tengo una placa Waveshare ESP32-S3-Touch-AMOLED-1.75C conectada por USB.
1. Encuentra el puerto serie de la placa.
2. Instala esptool si no está, y léele al chip el modelo, la memoria flash y la PSRAM, sin escribir nada en la placa.
3. Confirma si cuadra con la 1.75C (ESP32-S3, 32 MB de flash, 8 MB de PSRAM).
No cargues ningún firmware todavía.

Vas bien si te responde con un ESP32-S3, 32 MB y 8 MB. Si no encuentra ningún puerto, vuelve al paso 2.

Paso 04

Compila y carga.

Aquí el agente baja el SDK, instala ESP-IDF (las herramientas de Espressif, la versión 6.0.1), compila el firmware de la 1,75C con tu token y lo carga en la placa. Es lo más largo: la instalación de ESP-IDF pesa varios gigas y la primera compilación tarda. Tú solo confirmas los comandos que te va proponiendo.

El repositorio trae un archivo esp32/AGENTS.md escrito para agentes de código. La 1,75C se compila “a mano” según esa guía, con sus dos archivos de configuración.

Clona github.com/facebookincubator/muse-gadget-sdk y lee esp32/AGENTS.md completo antes de hacer nada.
Quiero compilar y cargar el firmware de Muse en mi Waveshare ESP32-S3-Touch-AMOLED-1.75C, siguiendo la sección de placas con interfaz completa "by hand":
1. Instala ESP-IDF 6.0.1 solo para esp32s3, donde AGENTS.md lo espera.
2. Compila en build-muse-waveshare-s3-175c con los defaults sdkconfig.defaults, devices/sdkconfig.muse y devices/sdkconfig.muse-waveshare-s3-175c.
3. Mi token SDK está en ~/.muse.env, en la línea MUSE_SDK_TOKEN. Ponlo en CONFIG_GADGET_SDK_TOKEN dentro del sdkconfig de ese build (que Git ignora). Nunca lo imprimas, nunca lo muestres completo y nunca lo pongas en un archivo que se suba a Git.
4. Carga el firmware en la placa y muéstrame las líneas del arranque donde dice qué placa es y con qué nombre se anuncia por Bluetooth.
Antes de cada paso largo, dime qué vas a correr.

Vas bien si en el arranque aparece board: Waveshare ESP32-S3-Touch-AMOLED-1.75C y la placa se anuncia como MuseGadget- seguido de seis caracteres. La pantalla prende con el avatar.

Paso 05

Empareja con Muse.

En la app de Muse: Settings, Devices, activa Developer mode y luego Add Device. Aparece tu MuseGadget-…, lo eliges, y la placa te pide que presiones el botón para confirmar. Lo presionas una vez, corto.

Para confirmar basta un toque corto. No lo sostengas: sostenido, ese mismo botón es el de grabar y el de encendido.

Paso 06

Dale Wi-Fi.

Desde la misma app, durante el emparejamiento, eliges la red y pones la clave. Tiene que ser de 2,4 GHz. El chip no ve las de 5 GHz. Si no conecta, crea una red solo de 2,4 GHz desde la configuración del router.

Vas bien si en el registro de la placa aparece algo así: setup=done wifi=up ws=up. Eso es emparejada, con Wi-Fi y conectada a Muse.

Antes de probar con la voz, pruébala por texto. Así sabes que la conexión está bien sin depender del micrófono:

La placa ya está emparejada con Muse y con Wi-Fi. Mándale a Muse una pregunta de texto por USB con la herramienta de chat del repositorio (tools/muse, mira AGENTS.md) y muéstrame la respuesta y cuánto se demoró.
No dejes abierta ninguna otra captura del puerto serie mientras tanto: le roba las respuestas al chat.

A mí me contestó en unos 7 segundos.

Paso 07

Pídele texto y afina las notas de voz.

Cuando le hablas a Muse con una nota de voz, por defecto te contesta con audio, y los gadgets todavía no reciben esas respuestas en audio: solo las que traen texto. Por eso, antes de hablarle a la placa, pídele a tu Muse desde la app, con tus palabras, algo así:

Cuando te hable desde mi gadget, contéstame siempre en texto, nunca en audio. El gadget no puede reproducir tus respuestas de voz.

Desde ahí, al hablarle a la placa ves la respuesta escrita en la pantalla. Para hablarle mantienes el botón mientras hablas y lo sueltas al terminar.

Mejora: notas de hasta 13 segundos, con cuenta regresiva

Muse recibe notas de voz de hasta 15 segundos desde los gadgets. Y en la 1,75C el botón de hablar es también el de encendido: sostenido mucho rato, la placa se apaga. Entonces le pedí a mi agente que la nota se cierre sola a los 13 segundos, con una cuenta regresiva en pantalla y un pitido para soltar. Así cada nota llega completa y la placa nunca se apaga por hablar de más. Para preguntas largas, mejor dos notas.

En mi Waveshare 1.75C con el firmware de muse-gadget-sdk, el botón de hablar es la tecla de encendido del AXP2101, y Muse acepta notas de voz de hasta 15 s.
1. Desactiva el apagado por tecla sostenida que se controla por software (registro 22H, bit 1) y verifica leyendo el registro después del arranque.
2. El chip tiene además un apagado de hardware cerca de los 16 s, así que termina cada nota de voz a los 13 s: muestra en pantalla una cuenta regresiva para soltar en los últimos segundos, suena un pitido corto y envía la nota sola al llegar a 13.
Compila, carga y pruébalo con una nota de 15 s.

Vas bien si al grabar una nota larga ves la cuenta regresiva, suena el pitido y la respuesta llega. Para apagar la placa a propósito: Ajustes, Power off.

Paso 08 · opcional

Dale voz.

El firmware oficial no habla: tiene un hueco preparado para que cada quien le ponga su propia voz (la función start_tts), y la placa ya sabe reproducir MP3. Yo lo llené con ElevenLabs. Cada respuesta de Muse se manda a ElevenLabs y el audio suena mientras el texto pasa por la pantalla.

En la mía la voz empieza a sonar unos 7 segundos después de soltar el botón. Casi todo ese tiempo es Muse pensando: la voz en sí tarda alrededor de un segundo.

Necesitas una cuenta de ElevenLabs y una clave de API. Guárdala igual que el token, en ~/.elevenlabs.env con la línea ELEVENLABS_API_KEY=, y elige una voz en su biblioteca (copias el ID de la voz, no es secreto).

Quiero que mi gadget de Muse (Waveshare 1.75C, firmware de muse-gadget-sdk) lea en voz alta las respuestas de Muse con ElevenLabs.
Lee esp32/components/muse/muse_chat_session.cpp: start_tts es el lugar para un TTS propio y la placa ya decodifica MP3.
1. Agrega opciones de Kconfig para la clave de ElevenLabs, el ID de voz, el modelo y el idioma. La clave va solo en el sdkconfig del build (que Git ignora). Léela de ~/.elevenlabs.env sin imprimirla nunca.
2. En start_tts, manda el texto de cada respuesta al endpoint de streaming de ElevenLabs pidiendo MP3 de baja tasa (mp3_22050_32) y reprodúcelo mientras llega, en una tarea aparte para no trabar la pantalla.
3. Abre la conexión con ElevenLabs cuando presiono el botón (mientras hablo), para que el saludo TLS no sume tiempo.
4. CIERRA cada conexión cuando termina de llegar el audio. No reutilices conexiones guardadas: si quedan abiertas, la placa se queda sin sockets.
5. Si el certificado de ElevenLabs falla, activa CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY.
6. Agrega al registro, una vez por minuto, cuántos sockets hay abiertos.
Haz los cambios en una rama propia, compila, carga y mide cuántos segundos pasan entre soltar el botón y el primer sonido.

Vas bien si oyes la respuesta y el contador de sockets se queda quieto en 2 (las dos conexiones con Muse) aunque le hables muchas veces. Ese contador te confirma que la voz no se va a caer con el uso: si sube con cada pregunta, pídele al agente que revise qué conexión no se está cerrando.

El orden, en una lista.

1. Token en gadgets.muse.ai, guardado en ~/.muse.env. Nunca en el chat.
2. Placa al computador con el cable de datos del kit.
3. El agente confirma que es la 1,75C, sin escribir nada.
4. El agente instala ESP-IDF 6.0.1, compila con tu token y carga.
5. App de Muse: Settings, Devices, Developer mode, Add Device. Un toque al botón.
6. Wi-Fi de 2,4 GHz desde la app. Prueba por texto.
7. Le pides a tu Muse que al gadget le conteste en texto, y le pones notas de 13 s con cuenta regresiva.
8. Opcional: voz con ElevenLabs, cerrando cada conexión.

Rayo Charm no es un producto de Meta ni está respaldado por Meta. Muse y el SDK de gadgets son de Meta; el código del SDK es abierto con licencia Apache 2.0. Al usar tu token aceptas los términos del SDK.