Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (70 loc) · 3.94 KB

AGENTS.md

File metadata and controls

89 lines (70 loc) · 3.94 KB

AGENTS.md – ModernJVS Coding Agent Guide

This file provides technical guidance for AI coding agents working in this repository.

Quick Reference

Task Command
Development build mkdir -p build && cd build && cmake .. && make
Clean build make clean (removes build/) then rebuild
Install (DEB) sudo make install
Install without WebUI sudo make install-no-webui
Check build output build/modernjvs (binary)

Environment Setup

Install build dependencies before building:

sudo apt install -y build-essential cmake git file libgpiod-dev pkg-config

Python 3 is required for the WebUI but is included in Raspberry Pi OS Lite and DietPi by default.

Build Validation

There is no automated test suite. Validate changes by:

  1. Running mkdir -p build && cd build && cmake .. && make — it must compile with zero warnings (-Wall -Wextra -Wpedantic).
  2. Confirming the resulting build/modernjvs binary exists.
  3. For WebUI changes, confirming Python syntax with python3 -m py_compile src/webui/modernjvs-webui.py.

Making Changes

C Source Files (src/**/*.c, src/**/*.h)

  • Standard: C99.
  • Logging: always use debug(level, fmt, ...), never bare printf.
  • New public functions: add a Doxygen /** */ comment.
  • After editing, rebuild and fix all warnings before committing.

WebUI (src/webui/)

  • Python 3, PEP 8 style.
  • No new pip dependencies.
  • All request handlers must enforce the private-IP allowlist.

Configuration Files (docs/modernjvs/)

  • Game profiles: docs/modernjvs/games/<game-name> – button mapping format.
  • Device profiles: docs/modernjvs/devices/<device-name> – axis/button-to-action mapping.
  • IO board definitions: docs/modernjvs/ios/<io-name> – capability declarations.
  • These files are installed to /etc/modernjvs/ by cmake --install / sudo make install.

Version Bumps

  • Version is set in CMakeLists.txt: project(modernjvs VERSION "X.Y.Z").
  • Pushing a version change on master automatically triggers the GitHub release workflow.

Critical Implementation Details

Topic Detail
JVS sense line pulse LOW 200 ms → FLOAT 100 ms stabilization
Serial buffer flush tcflush() then usleep(100000) (100 ms) before read after reset
Wiimote pairing Bluetooth only — no USB Wiimotes exist; always use proximity-based merge
Hot-plug checksum errors Expected during reinitialization; log shows this.
Namco 246/256 re-enum Reactive sense line pulse on wrong-address packet detection
libgpiod version CMake auto-detects; GPIOD_API_V2 defined for v2+
GPIO interface Use libgpiod exclusively — sysfs GPIO is not supported

Repository Structure (at a glance)

src/modernjvs.c        – entry point & main loop
src/console/           – CLI args, config parser, debug, watchdog
src/controller/        – input device enumeration, per-controller threads
src/hardware/          – RS485 serial device abstraction
src/jvs/               – JVS packet protocol, sense line, IO board emulation
src/ffb/               – force-feedback output
src/webui/             – Python WebUI server
docs/modernjvs/        – runtime config templates (installed to /etc/modernjvs/)
.github/workflows/     – CI release workflow
CMakeLists.txt         – build system (version, sources, install, CPack DEB)
Makefile               – developer convenience wrapper

Common Pitfalls

  • Don't use printf directly – always use debug().
  • Don't use sysfs GPIO – use libgpiod.
  • Don't assume USB Wiimotes – Wiimote/Nunchuk merge is always Bluetooth proximity-based.
  • Don't skip tcflush + sleep after serial reset – this causes data corruption.
  • Don't change install paths in CMakeLists.txt without updating the dpkg postrm script in debian/postrm.
  • The build/version.h file is generated by CMake from src/version.h.in – do not edit it directly.