Contributing to HAPTIC.SKIN

Thanks for your interest. This document covers the workflow for team members and external contributors.

Workflow

1. Pick an issue on the project board or create one. Assign it to yourself.
2. Create a branch from main: git checkout -b feat/<scope>-<short-title>. Scopes: firmware, daemon, client, hardware, patterns, docs, website.
3. Commit using conventional commits:
   • feat(client): homing-compass navigator
   • fix(firmware): debounce serial command parser
   • docs(science): Pacinian threshold citation
4. Open a PR against main. Link the issue. Fill the PR template.
5. CI must pass and one reviewer must approve before merge.
6. Branch is auto-deleted after merge.

Local dev setup

Daemon / client (Python)

cd daemon/  # or client/
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .

Firmware (Arduino C++ on Arduino Mega 2560)

1. Install the toolchain (pick one):

   # Arduino CLI
   arduino-cli core install arduino:avr
   # or use the Arduino IDE with the AVR boards package
   

2. Build and flash (board FQBN arduino:avr:mega):

   cd firmware/
   arduino-cli compile --fqbn arduino:avr:mega .
   arduino-cli upload --fqbn arduino:avr:mega -p /dev/ttyACM0 .
   

3. A serial simulator lives in tests/serial_sim.py for daemon dev without hardware.

Hardware (wiring)

• 8 QYF-740 motor modules wired to 8 PWM pins on the Mega 2560.
• Wiring diagram and BOM live under hardware/.

Website

The public site at haptic.skin. No build step for now — just edit files in website/public/ and push to main. GitHub Actions deploys automatically via rsync.

# Preview locally
open website/public/index.html

Code style

• Python: ruff (configured in pyproject.toml), type hints encouraged, docstrings on public API.
• Firmware (Arduino C++): keep loop() non-blocking (no delay() in the control path) — use millis()-based timing. Avoid dynamic allocation (String, malloc) in hot loops. Keep PWM writes batched per serial command.
• Commits: Conventional commits lite (see above).
• No secrets in commits — use .env (gitignored) for API keys.

Reviewing

Reviews should be lightweight. One approval is enough. Reviewers are auto-assigned via .github/CODEOWNERS. Cross-area reviews are encouraged — it helps everyone understand the whole system before the final defense.

Filing issues

• Bug: use the bug template, include repro steps and hardware state.
• Feature: use the feature template, link it to a milestone if applicable.
• Tag with one zone label (firmware, daemon, …) and one priority label (P0-blocking to P3-nice-to-have).

Licenses

By contributing, you agree your contributions are licensed under:

• MIT for code
• CERN-OHL-P v2 for hardware files
• CC-BY-SA 4.0 for documentation

See LICENSE, LICENSE-HARDWARE, LICENSE-DOCS.

Code of conduct

Be kind. See CODE_OF_CONDUCT.md.