¿Qué pasa si la calabaza de Halloween de la entrada no solo se ilumina, sino que te mira, te saluda, comenta tu disfraz y decide si mereces dulces? Este proyecto lo resuelve con dos calabazas impresas en 3D y una sola Raspberry Pi 5: Jack conversa con quien se acerca y Jill, su amiga tímida, guarda los dulces detrás de una puerta motorizada que solo se abre cuando corresponde.

Al terminar vas a entender cómo se reparte el trabajo entre una cámara que detecta personas, un arreglo de micrófonos USB con parlante, dos servos de bus serial y dos tiras LED direccionables, y cómo un modelo de lenguaje decide cuándo abrir la puerta llamando a una "herramienta" en vez de mover el servo por su cuenta. Es un proyecto de temporada, pero la arquitectura sirve para cualquier dispensador interactivo: una fiesta de cumpleaños, un stand en una feria o una mesa dulce para Fiestas Patrias.

La idea: dos personajes, un solo cerebro

La gracia del montaje es que los personajes se ven separados, pero la lógica no. Jack lleva la cámara, el parlante, el servo de la mandíbula y los LED de los ojos. Jill lleva solo el servo de la puerta y su propia tira LED: no tiene computador propio. Todo cuelga de la misma Raspberry Pi 5 por USB, CSI y SPI.

Raspberry Pi utilizada para controlar las dos calabazas

Las reglas de la visita son simples y conviene tenerlas claras antes de cablear, porque explican varias decisiones de hardware:

  • Una persona que se acerca recibe un saludo en voz alta, sin tener que hablar primero.
  • Un "hola" por sí solo no abre la puerta. Hay que pedir dulces (o decir "dulce o truco").
  • La puerta se abre una vez por visita. Si el servo falla al moverse, ese intento no cuenta.
  • Mientras la persona sigue frente a la cámara, la puerta queda abierta; cuando se va, se cierra sola.
  • La cámara describe la ropa para que Jack haga un chiste del disfraz, pero no reconoce caras ni identifica a nadie.

El hardware, bloque por bloque

Audio: reSpeaker XVF3800 por USB

El reSpeaker Flex XVF3800 Linear-4 se conecta a la Pi por USB y aparece como una sola tarjeta de sonido: por ahí entra lo que dice el visitante y sale la voz de Jack. El chip XMOS XVF3800 hace cancelación de eco y supresión de ruido en el propio módulo, algo que agradeces en la puerta de una casa con niños gritando: la Pi recibe un audio ya limpio y no tiene que filtrar nada.

Arreglo de micrófonos Seeed reSpeaker Flex XVF3800 lineal

El parlante va a la salida de amplificador con conector JST. Ojo con un detalle que confunde a muchos: si enchufas algo al jack de 3,5 mm, el sonido se desvía a ese jack y el parlante JST queda mudo. Usa un solo parlante de 4 Ω y deja el jack vacío.

Parlante de 4 Ω para la salida de amplificador del reSpeaker

La plaquita soldada sobre el reSpeaker es parte del micrófono; no se usa para mover servos ni LED.

Visión: Pi Camera Module 3 y un detector local

La Camera Module 3 va al conector CSI. El flujo tiene dos etapas, y entenderlas te ahorra plata en la API:

  1. Detección local: un modelo ONNX de MediaPipe corre en la propia Pi y solo responde "¿hay una persona y qué tan grande se ve?". Esto es gratis y rápido.
  2. Descripción remota: solo cuando alguien está cerca se manda una foto a Gemini para obtener una frase corta sobre la ropa. Ese texto, no la imagen, es lo que recibe Jack.

Módulo de cámara de Raspberry Pi

El disparo usa una métrica muy práctica: la persona tiene que ocupar al menos el 22 % de la altura de la imagen durante unos 0,8 segundos. Medir altura relativa en vez de distancia real evita calibrar nada: alguien lejos se ve chico y no dispara; alguien en la puerta se ve grande y sí. Después de eso Jack mira cerca de un segundo más y recién habla.

Movimiento: servos de bus serial STS3215

La mandíbula de Jack y la puerta de Jill usan servos Feetech STS3215. No son servos de hobby con PWM: reciben comandos por un bus serial, informan su posición real y entregan bastante más torque. Por eso la aplicación puede saber si la puerta realmente se movió y no contar un intento fallido como apertura.

Servo de bus serial Feetech STS3215

Cada servo va en su propia placa Seeed Bus Servo Driver con su propio cable USB a la Pi. Como cada uno vive en un bus separado, los dos pueden tener el ID 1 sin chocar. La placa recibe los 7,4 V de los servos desde una fuente aparte; la Pi la alimenta por USB solo para la lógica. Nunca saques la potencia de los servos de los pines de 5 V de la Pi: un STS3215 bloqueado consume más de lo que el riel de la Pi aguanta y provoca reinicios difíciles de diagnosticar.

Placa Seeed Bus Servo Driver para XIAO

Posiciones que usó el autor (son de su mecánica, tú vas a medir las tuyas):

Servo Cerrado Abierto
Mandíbula de Jack 40° (cuenta 455) 85° (cuenta 967)
Puerta de Jill 330° (cuenta 3755) 230° (cuenta 2617)

La relación es directa: el STS3215 tiene 4096 cuentas por vuelta, así que cada grado son unas 11,4 cuentas.

Luz: dos tiras WS2813 por SPI

Cada calabaza tiene una tira de 20 LED WS2813. Los ojos de Jack descansan en naranjo y, mientras habla, pasan por amarillo, rojo, morado y verde; la tira de Jill cambia lento con la puerta cerrada y rápido mientras se mueve o está abierta.

Tira LED WS2813 de 20 LED

Aquí hay un truco técnico que vale la pena entender: en la Pi 5 los LED direccionables se manejan por SPI y no con el clásico PWM o DMA de modelos anteriores, porque el chip RP1 cambió el acceso a esos periféricos. El bus SPI genera el tren de pulsos con una temporización estable sin que Linux interfiera. La WS2813, además, tiene línea de respaldo de datos: si un LED muere, el resto de la tira sigue funcionando.

Conexiones

Diagrama general del sistema de las calabazas Jack y Jill

La cámara va al conector CSI. Por USB entran tres dispositivos: el reSpeaker, la placa del servo de Jack y la de Jill.

Diagrama de conexiones del proyecto

Tira de los ojos de Jack

Tira LED Pin físico Pi GPIO / función
Entrada de datos (DIN) 19 GPIO 10, SPI0 MOSI
GND 20 GND
5 V 2 o 4 5 V

Deja libre el pin físico 21.

Tira de Jill

Tira LED Pin físico Pi GPIO / función
Entrada de datos (DIN) 38 GPIO 20, SPI1 MOSI
GND 39 GND
5 V 2 o 4 5 V

Para que existan /dev/spidev0.0 (Jack) y /dev/spidev1.0 (Jill), el archivo /boot/firmware/config.txt necesita estas dos líneas (la segunda la agrega el script scripts/enable-spi1.sh del proyecto):

Ini
dtparam=spi=on
dtoverlay=spi1-1cs

Los servos se conectan con el conector de 3 pines con guía (tierra, alimentación del servo y señal) directamente en su placa. Los 7,4 V van a la placa del driver, jamás a un GPIO.

Las carcasas impresas

Las dos calabazas vienen como archivos STEP dentro del ZIP del proyecto (3d/jack-talking-pumpkin.stp y 3d/jill-candy-pumpkin.stp). Si tu laminador pide malla, expórtalas a STL o 3MF desde tu programa CAD.

Carcasas impresas con las aberturas de la cara y el mecanismo de la mandíbula de Jack a la vista

El software

El programa no es un script corto: es un paquete Python (halloween) con módulos separados para conversación, cámara, audio, servos, LED, configuración, despliegue y pruebas. Se descarga completo como halloween-ai-pumpkin.zip desde el artículo original (enlace en Recursos).

Instalación paso a paso

Descomprime el proyecto en la carpeta de tu usuario:

Bash
sudo apt update
sudo apt install -y unzip curl
mkdir -p ~/halloween-ai-dispenser
unzip ~/halloween-ai-pumpkin.zip -d ~/halloween-ai-dispenser
cd ~/halloween-ai-dispenser

Instala los paquetes del sistema y crea el entorno virtual. El --system-site-packages es clave: deja que el entorno vea Picamera2, OpenCV y spidev instalados con apt, que son difíciles de compilar con pip en la Pi.

Bash
sudo apt install -y python3-venv python3-pip python3-picamera2 python3-opencv \
  python3-numpy python3-spidev alsa-utils ffmpeg
python3 -m venv .venv --system-site-packages
source .venv/bin/activate
pip install -r requirements.txt websockets

Da permisos de hardware a tu usuario y luego cierra sesión y vuelve a entrar:

Bash
sudo usermod -aG dialout,gpio,spi,video,audio,render "$USER"

Llaves de API

Crea el archivo .env a partir del ejemplo y no lo subas nunca a un repositorio:

Bash
cd ~/halloween-ai-dispenser
[ -f .env ] || cp .env.example .env
nano .env
Ini
GEMINI_API_KEY=
ELEVENLABS_API_KEY=
ELEVENLABS_VOICE_ID=

Gemini convierte la foto en una descripción corta de la ropa; ElevenLabs le pone la voz a Jack (el VOICE_ID es la voz que elijas en tu cuenta).

Modelo de detección de personas

Este archivo no viene en el ZIP y debe quedar con este nombre exacto:

Bash
mkdir -p models
curl -fL -o models/person_detection_mediapipe_2023mar.onnx \
  https://github.com/opencv/opencv_zoo/raw/main/models/person_detection_mediapipe/person_detection_mediapipe_2023mar.onnx

La personalidad de Jack

El archivo config/character.yaml es el "prompt" del personaje. Fíjate en cómo está escrito: no le da al modelo control directo de la puerta, sino una herramienta (ask_jill_to_open) y reglas estrictas para no afirmar que la puerta se abrió si la herramienta no lo confirma. Ese patrón (el modelo pide, el código decide y responde con el resultado real) es lo que evita que la IA "alucine" una acción física.

YAML
name: Jack
title: The Haunted Candy Guardian
instructions: |
  You are Jack, a magical talking Halloween pumpkin, and the only one who talks. Your friend Jill is the other pumpkin. She is too shy to speak much, so she stays quiet and guards the candy. You cannot open her lock yourself. When someone should have candy, call ask_jill_to_open. The door moves only if that tool says Jill opened the lock.
  You know Jill well. If someone asks who she is, why she is quiet, who guards the candy, or why there are two pumpkins, tell that story in a sentence or two. Do not recite it unless it comes up.
  You are warm, playful, and easy to please. A Halloween costume is welcome, and you do not quiz anyone about it. If the camera says they are in ordinary clothes or no costume, tell one short kid-safe Halloween joke before any candy. After they have heard that joke, they can ask for candy. Do not send them away to find a costume, and do not demand a second joke.
  You like jokes. When a camera observation says what they are wearing, mention it out loud. A costume gets one short kid-safe joke about that costume. Ordinary clothes get one short kid-safe Halloween joke, not a joke that pretends they have a costume. Use only details from that observation. Do not invent a costume, a cape, or a prop that the observation does not mention. Through the visit, keep the jokes light, one at a time.
  When the visit starts, greet them out loud yourself in one or two sentences. Do not wait for them to speak first. If they are in a costume, put that comment and a joke in the greeting. If they are not, tell the Halloween joke in the greeting. Do not mention opening the lock in that greeting.
  A hello by itself is not a reason to open. If they are not in a costume, ask Jill only after they have heard the Halloween joke and then ask for candy. If they are in a costume, ask Jill only after they ask for candy, say trick-or-treat, tell a joke, or ask again. Then say one short line that you are asking her, and call the tool in that same turn. After the tool result, say whether the door actually opened. Once it is open, it stays open while they are still there and closes after they leave. Do not rush them.
  Keep most replies to one or two short sentences. Speak in a clear, normal voice. Never whisper, and never use a whisper tag or a quiet voice. You can pretend to be scary, but never genuinely frighten children. Keep the interaction appropriate for children.
  You cannot see anything unless the local application provides a camera observation. If that note says ordinary clothes, one Halloween joke comes before candy. Do not invent details. Do not identify who they are.
  Never say the door opened, or that candy was given, unless the tool result says Jill opened the lock. If the lock sticks, admit it lightly. If Jill already opened it this visit, be kind and do not pretend it is opening again.

Puedes traducir las instrucciones al español para que Jack converse en castellano; lo importante es mantener las reglas de cuándo llamar a la herramienta.

Ajustes del hardware

Este es un extracto de config/settings.yaml. Edita estos valores en el archivo completo del ZIP y deja intactas las demás secciones (system, safety, ai, dispenser, servos.dispenser):

YAML
camera:
  enabled: false
  detection_width: 640
  detection_height: 360
  confidence_threshold: 0.0
  close_height_fraction: 0.22
  presence_confirmation_seconds: 0.8
  visitor_cooldown_seconds: 90
  jpeg_quality: 60
  session_seconds: 45
  frame_interval_seconds: 1.0
  reply_delay_seconds: 1
  recording_gap_frames: 20
audio:
  input_device: auto
  output_device: auto
  name_hints:
    - respeaker
    - xvf3800
  sample_rate_hz: 16000
  channels: 2
  sample_format: S16_LE
  record_seconds: 5
  jaw_sync_enabled: true
  playback_ceiling: 60
  playback_step: 3
servos:
  port: /dev/ttyACM0
  bus_baud: 1000000
  jaw:
    id: 1
    enabled: true
    closed_position: 455
    open_position: 967
    speed: 3000
    acceleration: 200
    update_rate_hz: 20
  door:
    port: /dev/serial/by-id/usb-1a86_USB_Single_Serial_5C85050232-if00
    id: 1
    enabled: true
    open_position: 2617
    closed_position: 3755
    speed: 350
    acceleration: 30
leds:
  enabled: true
  count: 20
  idle_brightness: 0.4
  speak_brightness: 1.0
  red: 255
  green: 80
  blue: 0
dashboard:
  enabled: false
  host: 127.0.0.1
  port: 8080

playback_ceiling: 60 equivale a 0 dB en el mezclador del reSpeaker. Las rutas de puertos USB son las del montaje original: tienes que poner las tuyas.

Habilitar SPI e identificar las placas

Revisa que dtparam=spi=on esté activo en el archivo de arranque:

Bash
sudo nano /boot/firmware/config.txt

Luego activa SPI1 con el script del proyecto y reinicia:

Bash
sudo sh scripts/enable-spi1.sh
sudo reboot

Para saber qué puerto corresponde a cada placa de servo, lista los dispositivos, desconecta una placa y vuelve a listar: la ruta que desaparece es la de esa placa.

Bash
ls -l /dev/serial/by-id/

Usa la ruta de /dev/serial/by-id/ y no /dev/ttyACM0: los nombres numerados cambian cuando reconectas dispositivos USB, y terminarías moviendo la mandíbula cuando querías abrir la puerta. La de Jack va en servos.port y la de Jill en servos.door.port.

Calibración y pruebas

Antes de mover nada, pon enabled: false en el bloque servos > door. Así la aplicación no toma el control del servo de Jill mientras defines los ángulos.

Bash
cd ~/halloween-ai-dispenser
source .venv/bin/activate
python scripts/talk.py --watch

La terminal muestra la dirección de la página de control con la IP de la Pi en la red local y el puerto 8080; ábrela desde un navegador en la misma red (no sirve 127.0.0.1). En esa página:

  1. Revisa la vista previa de la cámara y confirma que el visitante queda dentro del cuadro.
  2. Escribe el ángulo de apertura y de cierre en grados y presiona Save. Guardar no mueve el servo.
  3. Detén la aplicación con Ctrl+C, vuelve a poner enabled: true en servos > door y reiníciala.
  4. Prueba con Door open y Door close que los límites calcen con tu bisagra.
  5. Recién ahí enciende el interruptor de ElevenLabs: es el modo que activa el saludo automático y la puerta controlada por la conversación.

Un comportamiento a tener en cuenta: con el controlador de la puerta activo, si no se detecta a nadie por unos 8 segundos y la puerta no está cerrada, la aplicación la cierra sola, incluso si la conversación está detenida.

Las visitas quedan grabadas en la carpeta recordings de la Pi con nombres como visitor-YYYYMMDD-HHMMSS-N.mp4. El proyecto trae además deploy/jack-watch.service para arrancar todo al encender; instálalo solo después de calibrar y probar a mano, ajustando usuario, grupo y rutas.

Problemas comunes

  • Jack no se escucha: revisa que no haya nada enchufado al jack de 3,5 mm del reSpeaker.
  • La Pi se reinicia cuando se mueve la puerta: los servos están sacando corriente del lado equivocado. Revisa que la fuente de 7,4 V llegue a la placa del driver.
  • Jack nunca saluda: la persona no alcanza el 22 % de la altura de la imagen. Acerca la cámara o baja close_height_fraction.
  • Se mueve el servo equivocado: estás usando /dev/ttyACM0; cambia a las rutas by-id.

Variantes y mejoras

  • Mesa dulce para Fiestas Patrias o un cumpleaños: cambia el personaje en character.yaml (un huaso que pide un chiste o una adivinanza antes de entregar el dulce) y reemplaza la calabaza por cualquier caja con tapa. La lógica de "pedir, verificar, abrir una vez" queda igual.
  • Versión con servo PWM común: si no consigues servos de bus serial, puedes usar un servo estándar de alto torque como el MG996R con un controlador PCA9685 por I2C. Pierdes la lectura de posición real, así que conviene agregar un microinterruptor de fin de carrera para confirmar que la puerta abrió.
  • Micrófono USB y parlante de PC: para una primera prueba, un micrófono USB común y unos parlantes con su propio amplificador alcanzan. Vas a perder la cancelación de eco del XVF3800, así que Jack se escuchará a sí mismo si el volumen está alto; baja playback_ceiling o separa físicamente micrófono y parlante.
  • Contador de dulces: agrega una celda de carga HX711 bajo el compartimento de Jill y haz que Jack avise cuando quedan pocos dulces.

Personalización para Chile

En Chile consigues en MechatronicStore el corazón del proyecto:

  • Raspberry Pi 5 8gb Ram (SKU N-351): el único computador del montaje; corre la detección, el audio, los servos y los LED de las dos calabazas.
  • Array 4 Micrófonos XMOS XVF3800 SeeedStudio (SKU K-309): usa el mismo chip XVF3800 que el reSpeaker Flex lineal del original, en formato circular. Se conecta igual por USB y ofrece la misma cancelación de eco; solo cambia la forma de la placa, así que ajusta el hueco en la carcasa de Jack.
  • Cinta led WS2812B 5 V 5050 RGB 162 Tira de luz LED 60/PCB negro 5M IP65 (SKU G-599): reemplaza a las Grove RGB LED Stick WS2813. Corta dos tramos de 20 LED. La WS2812B usa el mismo protocolo de datos, así que el código SPI funciona igual; lo que pierdes es la línea de respaldo de la WS2813.

Los servos STS3215, sus placas driver, la Camera Module 3, el parlante de 4 Ω y la fuente de 7,4 V no están hoy en el catálogo; el artículo original enlaza a sus fabricantes.

Recursos

Versión chilena inspirada en el proyecto original, con componentes en stock local en MechatronicStore.