| name | vibe-robotics-coding |
| description | Use when writing or modifying embedded robotics firmware for the IITA soccer robots (Teensy 4.1 + OpenMV cameras + custom Zircon PCB + BNO055 IMU + IR sensors + motors). AI-accelerated coding with hard verification gates: compiles, fits in MCU, hardware-tested, no regressions on working subsystems. Specialised for the C++/Arduino-Teensy stack and MicroPython OpenMV stack. |
Vibe Robotics Coding — Firmware Embedded Acelerado con IA
Status: outline only — content pending iteration.
When to use
- Modificar código del robot en
software/robot-arquero/, software/robot-delantero/, software/libraries/.
- Escribir código de visión OpenMV en
software/vision/.
- Implementar protocolos de comunicación (UART OpenMV↔Teensy, ESP-NOW inter-robot, módulo árbitro).
- Agregar features (Kalman filter ball, FSM states, kicker control, dribbler PWM).
When NOT to use
- Cambios de hardware sin firmware — usar
vibe-mechanical-design o vibe-pcb-design.
- Cambios sólo a docs / playbooks — edición directa.
- Refactor cosmético sin justificación funcional.
Verification gates (no negociable)
Toda modificación de firmware debe pasar:
- Compila sin warnings (o con warnings explicados en el commit message).
- Cabe en el MCU — flash/RAM usage check para Teensy 4.1 (1MB RAM, 8MB flash).
- Loop time check — main loop sigue dentro del budget (objetivo: < 10ms para 100Hz, < 5ms si hay visión).
- No rompe subsistemas vecinos — regression test sobre módulos que tocaba antes (motores, IMU, comm).
- Test en hardware real documentado en
journal/:
- Setup (qué robot, qué condiciones, qué firmware version).
- Criterio de aceptación medible (no "anda bien" — "el robot se posiciona behind-the-ball en menos de 2s desde STR_APPROACH").
- Resultado observado.
- Antes/después (video, log, foto cuando aplica).
- Atribución de IA en commit (ver
AI-INSTRUCTIONS.md sección 1).
Pipeline esperado (planned content)
[TODO: desarrollar con el código real del robot]
- Intent capture — qué tiene que hacer el código, en qué condiciones, qué interactúa.
- Search existing code — el robot ya hace cosas; antes de generar nuevo, leer qué hay (incluye
playbooks//skills/ para el patrón mental).
- Generación incremental — IA propone diff pequeño, no rewrite. Excepción: cuando el código existente está fundamentalmente roto (raro).
- Static checks — compilación, sintaxis, headers correctos, linker.
- Mental simulation — paso a paso por cada estado de la FSM, valores límite (ball_dist = 0, ball_visible = false, partner_alive = false).
- Hardware test plan — antes de flashear, plan concreto de validación.
- Hardware test execution — alumno corre el plan, captura resultados con video/log.
- Journal entry — qué se cambió, qué se midió, qué se aprendió, qué quedó pendiente.
Stack actual
- MCU principal: Teensy 4.1 (ARM Cortex-M7, 600MHz, 1MB RAM, 8MB flash).
- Visión: OpenMV H7 / H7 Plus (MicroPython, ~30 FPS golf ball detection).
- IMU: BNO055 (deshabilitado en 2025; integración pendiente — ver Fase 2).
- Sensores línea: IR analógicos (3 sensores, A11 / A12 / A13).
- Sensores pelota IR: array IR pasivo para fallback (8 sensores, pines 14-23) — útil si la cámara pierde la pelota.
- Comunicación:
- UART OpenMV↔Teensy (pines 0/1).
- ESP-NOW inter-robot (a través de ESP32 externo).
- Módulo árbitro RCJ obligatorio (UART, ver communication-module-integration playbook).
- Actuadores:
- 3 motores TT con drivers H-bridge en placa Zircon (pinout depende de robot — ver journal del 2026-03-20).
- Dribbler.
- Solenoide kicker (solo delantero).
Anti-patterns (qué NO hacer)
- ❌ Magic numbers sin explicación. Si ves
if (ball_dist < 250), agregá comentario o constante (#define BALL_APPROACH_THRESHOLD_MM 250).
- ❌ Cambios que tocan motores sin verificar que el robot no se va contra una pared.
- ❌ Asumir que un playbook describe el comportamiento actual sin verificar contra el código.
- ❌ Subir código sin compilar localmente primero.
- ❌ Test plan que dice "probar en cancha" sin criterio de aceptación.
- ❌ Refactor + feature en el mismo commit (separar siempre).
Bugs conocidos a tener presente
[TODO: poblar a medida que se auditen los playbooks en Fase 1]
striker-strategy.md (playbook) — behind-the-ball asume goal_y = FIELD_LENGTH fijo; no maneja polaridad de campo según qué arco defendemos.multi-camera-world-model.md (playbook) — correct_position_from_goal() tiene álgebra incorrecta.- BNO055 — no funcionaba en 2025; revisar I2C + initialization sequence + magnetic interference.
References
software/libraries/zirconLib/ — librería custom de la placa.software/robot-arquero/definitivo-arquero_6-9-2026/ — código arquero actual.software/robot-delantero/definitivo-delantero/ — código delantero actual.journal/2026-03-20-diferencias-pines-motores-arquero-delantero.md — gotcha conocido del pinout.legacy/2025-season/ — código histórico (NO modificar; sólo lectura).
