Hermes

Wiki técnica de Hermes

Hermes es el robot humanoide educativo de Creabot (Guatemala), el primero de la red Hermes. Ve con una cámara, escucha y responde en español, gesticula con brazos y manos de cinco dedos, imita movimientos y se desplaza sobre una base con tracción diferencial.

Esta wiki tiene el detalle técnico: pines, pulsos, protocolos, consumo y cómo operarlo. Cualquier persona del equipo puede editarla desde GitHub (botón del lápiz en cada página).

Páginas

Ficha

GDL = 2 × (1 + 1 + 1 + 5) + 2 = 18. Cada dedo es 1 GDL porque lo mueve un solo SG90. La base tiene 4 motores pero solo 2 señales (un pulso por lado): controla velocidad lineal v y de giro ω. La cabeza no tiene motores: los ojos se animan en pantalla.

Dónde está cada cosa en el repo

Cabeza

Los ojos de Hermes. Una Raspberry Pi 3 B+ dibuja ojos animados en dos pantallas redondas con el Adafruit Animated Snake Eyes Bonnet. Funciona sola: no se comunica con la Jetson.

Archivos en el repo: cabeza/ (copia sacada por SSH el 2026-10-13; ver su README).

Hardware

Raspberry Pi 3 Model B+

Snake Eyes Bonnet (Adafruit 3356)

Se monta sobre los 40 pines y maneja dos pantallas. Soporta OLED 1.5″ 128×128, TFT 1.44″ 128×128 e IPS 1.54″ 240×240. Tiene 4 entradas analógicas (joystick, luz), hoy libres. Las pantallas van por cable plano soldado.

Pantallas IPS 1.54″ 240×240 (Adafruit 3787) × 2

ST7789 por SPI de 4 hilos, 240 × 240, color de 16 bits, panel IPS, 3.3 o 5 V. Modelo marcado como probable.

Software: Snake Eyes

Instalado a partir de la guía de Adafruit, pero adaptado a trixie con un instalador propio.

Cómo arranca

pi-eyes.service espera la red y 20 s, abre X con xinit corriendo eyes.py --radius 240 y, 5 s después, lanza fbx2 -i -b 12000000, que copia la imagen de X a las dos pantallas por SPI. Se reinicia siempre (máximo 5 intentos cada 120 s). Variables en /etc/pi-eyes/env: PYTHON, PI_EYES_DIR, RADIUS=240.

sudo systemctl status pi-eyes.service        # estado
sudo systemctl restart pi-eyes.service       # reiniciar los ojos
journalctl -u pi-eyes.service -f             # registro en vivo
sudo systemctl disable --now pi-eyes.service # apagar el arranque automático

Cambios respecto del repo de Adafruit

Solo dos archivos de /opt/Pi_Eyes difieren de adafruit/Pi_Eyes (diff en cabeza/Pi_Eyes/cambios.diff):

• eyes.py: eyeRadius = 240 fijo (el original es 128).
• Makefile: versión vieja con -lbcm_host (dispmanx). No compila en trixie; el instalador compila

fbx2 con gcc -O2 -o fbx2 fbx2.c -lpthread -lm -lX11 -lXext sin usarlo.

Problemas encontrados

• pi-eyes-fbx2.service se reinicia en bucle. Lanza un segundo fbx2 -t (modo TFT) mientras

pi-eyes.service ya corre fbx2 -i. Arreglo propuesto: sudo systemctl disable --now pi-eyes-fbx2.service.

• Dos resoluciones. config.txt pide 1280×720 y cmdline.txt 640×480. Con KMS manda cmdline.txt;

conviene dejar una sola.

• SPI a 12 MHz en lugar de 96 MHz: más lento pero más estable con cables largos. Sin medir cuadros por segundo.

Planes

Ver Planes: cámara CSI que transmita a la Jetson y ojos que sigan la cara.

Torso

El cerebro de Hermes: una Jetson Orin Nano que ve, escucha, conversa y manda la pose a los brazos. También tiene la webcam con micrófono, la pantalla del pecho y el parlante Bluetooth.

Archivos en el repo: jetson/.

Hardware

Jetson Orin Nano Developer Kit

Si es un kit original (no Super): 40 TOPS, CPU a 1.5 GHz y 68 GB/s. Por confirmar cuál es.

Antes de correr la visión (en cada arranque): sudo nvpmodel -m 0 (modo MAXN) y sudo jetson_clocks.

Programas

Uno a la vez: hermes_vision, hermes_mirror y hermes_manual abren el puerto 5005. Los tres usan hermes_net para hablar con los brazos.

hermes_vision.py

Ve con la cámara (MediaPipe: manos y pose), escucha, piensa con un modelo de lenguaje y habla.

• STT: Groq whisper-large-v3-turbo · LLM: openai/gpt-oss-120b · visión: qwen/qwen3.6-27b.
• TTS: Piper por aplay (ALSA default) al parlante Bluetooth. Una frase a la vez (Popen + wait).
• Teclas: Z graba, X detiene y procesa (las agrega parche_gestos.py). Siempre activas.
• Contiene los movimientos pre-hechos (según el equipo, por confirmar).
• Necesita la API key de Groq (no subirla al repo).
• El aviso landmark_projection_calculator.cc de MediaPipe no es un error.

hermes_gesture.py

Hilo a 40 Hz que observa el estado de vision (tts_playing, recording, chat_status) y escribe una onda viajera en los 5 dedos de cada mano con net.set_fingers(). No toca los codos.

• Onda: pct_i = 100 − A · (1 − cos(θ − i·π/5)) / 2, con θ integrada (θ += 2π·dt/T) para que cambiar de

periodo no dé saltos. La mano derecha usa el índice invertido: la onda corre en sentido opuesto.

• Solo se suaviza la amplitud (τ = 0.3 s), nunca la salida.
• Neutro = 100 % (dedos extendidos). Si se corta el enlace, las manos se cierran (posición segura 0 %).
• Por ser observador, si vision vuelve a quieto por cualquier motivo (incluida una excepción), la mano

vuelve sola al neutro.

parche_gestos.py

Parche idempotente sobre hermes_vision.py (deja hermes_vision.py.bak; marca # [PARCHE-GESTOS]): importa hermes_net y hermes_gesture, arranca la red y los gestos, agrega las teclas Z/X, los detiene al cerrar y cambia el texto de ayuda a «Abierta/Z=grabar Puño/X=enviar».

python3 parche_gestos.py            # parchea ./hermes_vision.py

Pendiente: confirmar que el hermes_vision.py de la Jetson ya está parcheado.

hermes_mirror.py

Hermes copia con los codos y los dedos lo que hace la persona frente a la cámara.

• MediaPipe Pose (codos, sobre pose_world_landmarks, métricos) y Hands (dedos) en dos hilos que procesan

siempre el cuadro más nuevo. Entrada a MediaPipe de 320 px de ancho con el aspecto real de la cámara.

• Suavizado EMA con constante de tiempo fija: α = 1 − e^(−Δt/τ), τ = 0.12 s. Zona muerta 6–94 % aplicada

solo a la salida.

• Calibración separada por mano. Resultados de más de 250 ms se descartan.
• Cámara USB por V4L2 (MJPG 1024×768 a 30 fps); opción CSI por GStreamer (USE_CSI).
• Telemetría de la Jetson (GPU, temperatura, potencia) con jtop.

Problema conocido: se cae en el modo espejo. Ver Planes.

hermes_manual.py

Banco de pruebas: página web en http://<ip-jetson>:8080 con un deslizador por dedo y codo, y un botón que barre 0–100–0. Usa el mismo hermes_net, así que prueba el camino real.

hermes_net.py

El cartero. Ver Protocolo.

• Escucha en :5005 (HELLO y telemetría) y envía a :5006 a 50 Hz desde un hilo propio con reloj absoluto.
• API: start(), stop(), set_codos(izq, der), set_fingers(lado, [5]), pause(), resume(),

is_paused(), ramp_to_zero_blocking(), link_ok(rol), stats().

• Rampa a cero de 0.8 s al pausar o apagar. Un peer se da por caído tras 5 s sin noticias.

Deuda técnica

• hermes_net.py: ROLES incluye CODOS → dejar ("LEFT", "RIGHT").
• hermes_manual.py: links() busca CODOS y MANOS.
• hermes_mirror.py: el HUD muestra el rol CODOS; sin try/finally, una excepción salta la rampa a cero.

Brazos

Cada brazo tiene un ESP32-C3 SuperMini que recibe la pose de la Jetson por WiFi y mueve el codo, el hombro, la muñeca y los cinco dedos. Los dos brazos corren el mismo firmware; solo cambia una línea.

Archivos en el repo: firmware/arms/hermes_v4_fixed.c.

Mapa de pines

Orden de los dedos en CH0–CH4: pulgar, índice, medio, anular, meñique.

GPIO18/19 del C3 son el USB: no usarlos. Pines de arranque (strapping): GPIO2, 8 y 9. GPIO10 se eligió para el hombro porque no tiene función de arranque.

Componentes

ESP32-C3 SuperMini × 2

RISC-V de un núcleo a 160 MHz, 400 KB SRAM, WiFi 2.4 GHz y Bluetooth 5 LE, 6 canales LEDC. Corriente RF: RX 84 mA, TX hasta 335 mA. LED en GPIO8, BOOT en GPIO9, UART en GPIO20/21.

PCA9685 × 2

Generador de PWM de 16 canales y 12 bits por I2C. En Hermes: 50 Hz, I2C a 400 kHz, dirección 0x40, oscilador calibrado a 27 MHz (PCA_OSC_HZ; el típico es 25 MHz). VCC desde el 3V3 del ESP32, V+ desde el 5 V del brazo. A 50 Hz cada paso es 20 ms / 4096 ≈ 4.9 µs.

Servo Docyke 18 V × 4 (hombros y codos)

16–24 V (18 V nominal), 0.24 s por 60°, pulso RC estándar (no duty-cycle crudo: usar ESP32Servo). Modelo exacto de los brazos por confirmar. El fabricante no publica corrientes: ver Alimentación.

SG90 × 10 (dedos)

4.8–6 V, 1.7 kg·cm, 0.12 s por 60°. Hermes usa 600–2400 µs. 10 mA en reposo, 100–250 mA moviéndose, 360 mA bloqueado.

MG995 × 2 (muñecas)

4.8–7.2 V, 9.4–11 kg·cm, 0.5–2.5 ms. 10 mA en reposo, 170–400 mA moviéndose, 1.3–1.5 A bloqueado.

Firmware hermes_v4

• Core Arduino-ESP32 v3.x. Librerías: Adafruit PWM Servo Driver, ESP32Servo.
• Por placa: cambiar ROLE_ID (ROLE_LEFT / ROLE_RIGHT). Para Arduino IDE, renombrar a .ino.
• La clave WiFi va solo en tu copia local: el repo guarda WIFI_PASS = "********".
• Cálculo a 200 Hz, escritura a 50 Hz, limitador de velocidad por canal, watchdog de dos niveles, tarea

FreeRTOS que imprime [MON] cada segundo. WiFi.setSleep(false) para evitar 100 ms de latencia.

• Al arrancar, todos los canales van a la posición segura (0 %).

Canales

Si un canal gira al revés, intercambiar us_min y us_max.

Tope del codo: el tope vigente es 1300 µs (≈60°), pero esta copia del firmware usa 900–2100 µs. Verificar contra lo flasheado antes de flashear de nuevo. Los límites de seguridad van en el firmware (en µs), no en Python.

Watchdog

El movimiento "solo" que se ve al cortar el enlace es el watchdog HARD, no un fallo.

Siguiente versión (v5)

Hombro (GPIO10) y muñeca (CH5) en firmware: 4 campos más en el paquete y N_CH = 8.

Base

La base móvil: cuatro Docyke 550 kg en modo rueda, en configuración 2×2 con tracción diferencial, controlados por un ESP32 desde una página web en el teléfono. Está separada del resto por seguridad: la Jetson no la controla.

Archivos en el repo: firmware/base/hermes_base.c.

Hardware

Tracción diferencial: v = (v_der + v_izq) / 2, ω = (v_der − v_izq) / b. Lado de GPIO18/19 por confirmar (hoy: 18 = izquierda).

Firmware hermes_base

• Core Arduino-ESP32 v3.x. Librerías: ESP32Servo, ESPAsyncWebServer y AsyncTCP (ESP32Async).
• Red: HackerspaceX_EXT (no la misma que los brazos). La clave está retirada en esta copia.
• Página de control en http://<ip>/: flechas, STOP, velocidad y el pulso de cada lado.
• Protocolo WebSocket: ver Protocolo.

velocidad (−100…100 %) → map(−100, 100, 500, 2500). Girar a la izquierda = lado izquierdo en reversa y derecho adelante (y al revés).

Notas

• Sin rampa de aceleración. Pasa de parado a la velocidad elegida, o de un sentido al otro al girar, de

golpe. Puede contribuir a que la base se tambalee (sin probar). Ver Planes.

• Se queda esperando la red. Si no encuentra el WiFi, setup() no termina y la página no se sirve; los

motores quedan parados.

• El ESP32 se puede reiniciar al acelerar porque toma 5 V de las salidas de los motores. Instalar el

XL4005 dedicado.

• Falta paro de emergencia. Pico estimado de la base ≈ 28 A.

Protocolo

Jetson ↔ brazos (UDP)

Texto plano separado por comas, sobre WiFi. Lo implementan jetson/hermes_net.py y el firmware de los brazos.

<ROL> es LEFT o RIGHT. Los valores de control van de 0 a 100 %.

Paquete de control

Un solo datagrama con la pose completa va a los dos brazos. Cada ESP32 toma solo sus índices (pkt_idx): el izquierdo lee 1 y 3–7, el derecho 2 y 8–12.

Ancho de banda ≈ 45 B × 50 Hz × 2 destinos ≈ 4.5 KB/s.

Cada paquete lleva el estado completo, nunca diferencias: perder uno no importa porque el siguiente llega 20 ms después. Por eso UDP y no WebSocket: TCP retransmite, y el brazo se congela y luego salta.

Estados del enlace en el ESP32

INIT (anunciándose) → LIVE (recibe control) → SOFT (250 ms sin paquetes: congela) → HARD (1500 ms: rampa a 0 % a 60 %/s). Ver Brazos.

Lado de la Jetson

• Un peer se da por caído tras 5 s sin noticias.
• Pausa y apagado: rampa a cero de 0.8 s.
• Solo un programa a la vez puede abrir :5005 (hermes_vision, hermes_mirror o hermes_manual).

Base (WebSocket)

El ESP32 de la base sirve su página en http://<ip>/ y escucha en ws://<ip>/ws. Un carácter por mensaje:

• La página reenvía el comando activo (o S) cada 80 ms.
• Watchdog: sin mensajes durante 300 ms con los motores en marcha → STOP.
• Al desconectarse un cliente o haber un error → STOP.

La base no pasa por la Jetson. A futuro: un rol BASE en hermes_net.

Alimentación

Estimado a partir de las hojas de datos; falta medirlo en el robot. Reposo: servos quietos. Típico: gesticulando. Pico: todos los servos forzados a la vez (peor caso, no simultáneo en la práctica).

Fuentes de energía

Consumo por riel

La fila de la cabeza se calculó para una Raspberry Pi 4; la cabeza tiene una Pi 3 B+ (≈500 mA típico sin periféricos). Recalcular o medir.

5 V de cada brazo (un XL4005 por brazo)

I_18V = V_out · I_out / (V_in · η) = 5 · 1.27 / (18 · 0.9) ≈ 0.39 A por XL4005 (típico), 1.13 A (pico).

El típico de 1.27 A está dentro de los 2–3 A continuos recomendados para el XL4005; el pico de 3.66 A solo es aceptable como transitorio y con disipador.

XL4005

Entrada 5–32 V, salida ajustable (5 V en Hermes), 5 A nominal con disipador y 2–3 A continuo recomendado, 300 kHz, eficiencia hasta 96 %. Protección térmica; sin protección de sobretensión.

Docyke a 18 V

El fabricante no publica corrientes. Estimado desde el par nominal (180 kg·cm = 17.65 N·m) y la velocidad (0.24 s por 60°), con eficiencia supuesta de 60 %:

• ω = (π/3) / 0.24 s = 4.36 rad/s · P_mec = τ·ω = 17.65 · 4.36 ≈ 77 W
• I ≈ P_mec / (η · V) = 77 / (0.6 · 18) ≈ 7.1 A por servo a par nominal (pico) · típico ≈ 15 % → 1.1 A

Coherente con el fabricante, que pide una fuente de al menos 25 A. Su puerto de señal entrega 5 V / 1 A.

Autonomía

• Baterías: t [h] = C [Ah] · 0.8 / I_típica
• Powerbank: t [h] = E [Wh] · 0.85 / P

Brazos ≈ 9 min por cada Ah (16 min/Ah con solo los codos), base ≈ 11 min por Ah, cabeza ≈ 10.6 min por Wh. Falta la capacidad real de las baterías.

Cableado

• 18 AWG, rojo (+) y negro (GND) en todas las líneas de 18 V y 5 V. GND común en todo el sistema de brazos.
• 18 AWG: 1.02 mm, 0.0209 Ω/m, hasta 16 A en cableado de chasis. Un Docyke a 7.1 A con 1 m de cable (2 m ida

y vuelta) pierde ΔV = 7.1 · 0.042 ≈ 0.3 V (1.7 %): aceptable.

• Revisar el tronco común: si los 4 Docyke de los brazos van por un solo par de 18 AWG, el pico (≈31 A)

supera los 16 A. Opciones: un par por servo desde un punto de distribución, o un tronco de mayor calibre; en ambos casos, un fusible cerca de la batería.

• Falta: conectores, longitudes y recorrido de cada cable.

Operación

Uso

Correr un solo programa de la Jetson a la vez: vision, mirror y manual abren el puerto 5005.

Pendiente: secuencia de encendido y apagado.

Calibración de servos

1. Quitar las piezas acopladas a cada servo (brazos, cuernos y tendones de los dedos) para que el eje gire libre.
2. Encender la placa con su firmware: al arrancar lleva todos los canales a la posición segura (0 %):

codo a 900 µs y dedos a 600 µs, o 2400 µs en los invertidos.

1. Montar las piezas con el servo ya en esa posición, en la pose de reposo del robot.
2. Verificar con hermes_manual: barrido 0–100–0 de cada canal sin choques. Si un canal gira al revés,

intercambiar us_min y us_max.

1. Confirmar el tope del codo (1300 µs ≈ 60°) antes de conectar la visión.

Diagnóstico

Acceso por SSH

Las contraseñas no van en el repo: están en acceso.env (ignorado por git) en la computadora del equipo.

Seguridad

• El tope del codo y los watchdog están en el firmware, en µs. Los límites no van en Python.
• Al cortarse el enlace o cerrar un programa, las manos se cierran (0 %): es la posición segura.
• Falta: paro de emergencia, fusible por batería, distribución de 18 V y manejo de baterías Li-ion.

Materiales

La lista de materiales completa está en docs/BOM.csv: GitHub la muestra como tabla y se puede abrir en una hoja de cálculo. Esa es la fuente; si cambia un componente, editarlo ahí.

Falta en la lista: proveedor, número de parte, costo y longitudes de cable.

Resumen por robot

Sin hoja de datos todavía (modelo por confirmar): webcam, pantalla del pecho, parlante, router, powerbank y baterías de 18 V.

Piezas impresas en 3D

Identificadas en la foto como probables piezas impresas (FDM). Material y archivos por confirmar.

Pendiente: archivos CAD/STL, planos, parámetros de impresión y guía de ensamble.

Planes y pendientes

Marcar con [x] lo que se termine.

Planes Universidad San Pablo

Cabeza

• [ ] Cámara de la cabeza a la Jetson. Conectar la cámara CSI a la Raspberry de la cabeza y transmitir

el video por WiFi a la Jetson.

• [ ] Los ojos siguen la cara. Modificar eyes.py para que los ojos miren hacia donde se detecta una cara.

Jetson

• [ ] Se cae en el modo espejo. La Jetson se desconecta y el programa se cierra mientras está en

hermes_mirror.py. Encontrar la causa y corregirla. Pistas al leer el código (sin probar): no hay try/finally, así que cualquier excepción cierra el programa sin la rampa a cero; si un hilo de MediaPipe lanza una excepción muere sin aviso y la pose deja de actualizarse; la ventana de OpenCV depende de la sesión gráfica, y si se cae el VNC el programa se cierra.

• [ ] El micrófono se oye a sí mismo. El micrófono capta el audio mientras Hermes habla. Opciones:

bloquear el micrófono durante la reproducción, o permitir interrumpir el audio con otro comando.

Base

• [ ] Base más estable. Que no se tambalee: modificar la base para hacerla más estable.

Pista del firmware (sin probar): no tiene rampa de aceleración; arranca, frena y cambia de sentido de golpe.

Seguridad y firmware

• [ ] Confirmar que el firmware flasheado tiene el tope del codo en 1300 µs (la copia del repo usa 900–2100).
• [ ] Hombro (GPIO10) y muñeca (PCA CH5) en firmware; paquete v5 con 4 campos y N_CH = 8.
• [ ] Quitar CODOS/MANOS de hermes_net.py, hermes_manual.py y el HUD de hermes_mirror.py.
• [ ] Clave WiFi a secrets.h (ignorado por git).
• [ ] XL4005 dedicado para el ESP32 de la base.
• [ ] Fusible por batería, paro de emergencia, distribución de 18 V (pico ≈31 A > 16 A de un par 18 AWG).
• [ ] Cabeza: desactivar pi-eyes-fbx2.service (se reinicia en bucle) y dejar una sola resolución.
• [ ] A futuro: rol BASE en hermes_net.

Código por copiar

• [ ] hermes_vision.py (Jetson).
• [ ] Confirmar que el hermes_vision.py de la Jetson tiene el parche de gestos (marca # [PARCHE-GESTOS]).
• [ ] Confirmar si hermes_presenta.py sigue en uso.
• [ ] Revisar ~/hermesJetson y el escritorio de la Jetson.

Datos por confirmar

• [ ] Altura y peso · capacidad de las baterías (Ah) · modelo exacto de los Docyke de los brazos.
• [ ] Jetson Orin Nano: kit Super u original · modelo de la pantalla del pecho, webcam y powerbank.
• [ ] Lado de GPIO18/19 en la base (hoy: 18 = izquierda) · pantallas de los ojos IPS 240×240 (probable).
• [ ] Red WiFi real de la Jetson y la Raspberry (hiveBot o HackerspaceX2).
• [ ] Esquema KiCad: cambiar la Raspberry Pi 4 por la Pi 3 B+.
• [ ] Recalcular o medir el consumo de la cabeza con la Pi 3 B+.

Estado de la documentación

Fuentes

De dónde sale cada dato técnico de esta wiki. Lo que no aparece aquí viene del propio proyecto (firmware, programas, esquema y respuestas del equipo).

1. NVIDIA · Jetson Orin Nano Super Developer Kit — TOPS, GPU, CPU, memoria, potencia
2. NVIDIA · Orin Nano Dev Kit User Guide, hardware layout — puertos
3. Foro NVIDIA · consumo del Orin Nano Dev Kit — modos de 7, 15 y 25 W
4. Raspberry Pi · Pi 3 Model B+ — SoC, memoria, puertos
5. Raspberry Pi · documentación, fuente de alimentación — fuente de 2.5 A, ≈500 mA típico
6. Adafruit · Animated Snake Eyes Bonnet (3356) — función del bonnet, pantallas compatibles
7. Adafruit Learn · Snake Eyes software installation — instalador, opción IPS, bitrates
8. adafruit/Pi_Eyes — código original de los ojos (comparado contra 8553deb)
9. Adafruit · 1.54″ 240×240 IPS TFT (3787) — resolución, ST7789, SPI, voltaje
10. Espressif · ESP32-C3 datasheet — núcleo, memoria, radio, corrientes RF
11. Last Minute Engineers · ESP32-C3 Super Mini pinout — strapping, LED, BOOT, UART
12. Espressif · ESP32 datasheet — núcleos, memoria, radio, LEDC
13. NXP · PCA9685 datasheet — canales, resolución, I2C, salidas
14. Toytooth · DOCYKE 550 kg High Torque Servo — voltaje, par, velocidad, modos, salida 5 V/1 A
15. Protosupplies · SG90 — par, velocidad, pulsos, corrientes medidas
16. Components101 · MG995 — par, velocidad, peso, pulsos
17. Protosupplies · MG995 — corrientes medidas
18. done.land · XL4005 — rangos, corriente práctica, frecuencia
19. XLSEMI · XL4005 datasheet — hoja de datos del regulador
20. HyperPhysics · Common wire gauges — resistencia y corriente de 18 AWG
21. anatomy (kit de figuras isométricas, MIT) — figura del sitio visual