Define el protocolo completo de la tarjeta concentrador NMEA2000-USB:
- Sentencias NMEA 0183 estandar emitidas por el ESP32 hacia los puertos OUT
- Sentencias propietarias $PARP para comandos del autopilot
- Protocolo de transferencia de mando entre estaciones (puente, cockpit, flybridge)
- Mapeo completo NMEA 0183 <-> NMEA 2000 PGNs
- Seguridad: validacion de checksum, permisos por estacion, alarmas
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1_buck_chain.cir:
- RL1 creaba nodo flotante V5V_AFTER_L sin retorno
- Reemplazado por parametro Rser=0.051 en L1 (soporte nativo LTspice)
2_output_stage.cir:
- Gcoll con VALUE={} no es sintaxis valida para G-source en LTspice
→ convertido a B-source: Bcoll GATE_Q1 EMITTER I={MAX(0, 1.0*I(Dled))}
- .net V(out1) VLOAD → directiva invalida en este contexto, eliminada
- .meas V(out1) → nodo inexistente, corregido a V(drain_q1)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All analog ports (IN-BAT, IN-WATER, IN-OILP, IN-RPM) now use R_high=100K,
R_low=27K — unified design confirmed in schematic. Updated .param values,
voltage divider netlist, verification comments, and design notes.
Vout @ 14.4V (alternator) = 3.06V — just at the ADC limit, correct.
Vout @ 15.5V = 3.30V — absolute maximum safe input voltage.
Filter fc = 747 Hz with 100K||27K and 10nF.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Simulates the full RS-485 half-duplex channel on the ESP32+CAN+RS485 board:
- SN65HVD1781 behavioral driver/receiver (3.3V native, 32 unit loads)
- Half-duplex direction control via DE/RE GPIO4
- 560Ω bias resistors keeping bus HIGH during idle (NMEA 0183 failsafe)
- 120Ω termination at both ends of a 10m T-line model (Zo=120, Td=50ns)
- Transmits ASCII 'G' (0x47) at 4800 bps — one complete NMEA character
- Second node as passive 12kΩ unit-load receiver
- .meas directives verify Vdiff > ±200mV (RS-485 spec) in both polarities
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Four .cir behavioral simulations ready to open in LTspice via File→Open:
1_buck_chain.cir — dual MP2338 12V→5V→3.3V, verifies Rfb math + soft-start
2_output_stage.cir — PC817 + IRLML6344 isolated output (inverted logic confirmed)
3_analog_input.cir — analog input conditioning; flags ADC overvoltage on IN-BAT/WATER/OILP
4_nmea2000_can.cir — MCP2562T CAN transceiver, two-node NMEA2000 bus, T-line model
CRITICAL finding in 3_analog_input.cir: R_high=10K + R_low=15K gives 4.3V
at ESP32 ADC when measuring a 12V battery — exceeds 3.3V limit. Fix: use
R_high=100K (same as IN-RPM, which is correctly designed at 3.06V @ 14.4V).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary of the autonomous overnight session covering Sprints 0-3 + 2.5
plus polish + dev scripts. Includes:
- Per-sprint commit/tag table
- "What you can do right now" checklist (verify, launch Studio, run
cascade simulation, flash hardware)
- Demo PINs for the 4 RBAC roles
- Architectural decisions taken without asking (rationale + how to
reverse if needed)
- Environment limitations (no host C++ compiler, no ESP32 hardware
available during the session)
- Repository structure overview
- Test count per suite (258 total)
- Next sprints (4-10+) with rough effort estimates
- Open questions for the next session (Flutter SDK, WiX, EKF timing,
knob hardware model)
End-to-end implementation per docs/sprint-3-plan.md.
Closes the cascade: outer loop (heading control, 10 Hz on Core 1) drives
the inner loop (rudder position control, 50 Hz from Sprint 2). First real
mode other than STANDBY is now activable: HEADING_HOLD.
Builds: pio run -e esp32-dev SUCCESS, RAM 6.8%, Flash 27.1% (355 KB).
Tests: pytest 258/258 green (231 Sprint 2.5 + 27 Sprint 3 new).
Python (arautopilot/studio/simulator/):
- vessel_heading.py: first-order yaw model. ROT responds to
rudder*speed; damping returns ROT to zero when rudder is centred.
Defaults tuned so 5 deg rudder @ 10 kn -> ~3 dps steady-state ROT.
Includes heading_error_deg() shortest-arc helper.
- pid_outer.py: pure-Python outer heading PID. Anti-windup via back-
calculation, gain scheduling by SOG, deadband, derivative LPF,
output saturation, ROT feed-forward (brief sec. 6 -- the term that
distinguishes a premium autopilot from a basic one), rate limit on
produced rudder setpoint, shortest-arc heading wrap-around.
Firmware (firmware/ar_autopilot_v1/src/pid/):
- pid_outer.h: header-only C++17 port. Same algorithm, same variables,
same numerics. Fixed-capacity gain schedule (up to 8 points).
- pid_outer_task.{h,cpp}: 10 Hz FreeRTOS task on Core 1. Subscribes to
TWDT. Reads heading + ROT from the NMEA 2000 snapshot. Uses
operator-configurable SOG (default 15 kn until PGN 129026 wiring in
Sprint 5). Pushes rudder setpoint into the inner loop only when
current_mode == HEADING_HOLD.
Modes (firmware/ar_autopilot_v1/src/modes/standby.cpp):
- HEADING_HOLD activable via request_mode(). Pre-conditions:
* NMEA 2000 heading sensor valid (fresh PGN 127250)
* Rudder sensor valid (median filter filled)
On success, captures current heading as initial setpoint so the
operator doesn't get a sudden swing toward an old setpoint.
Modbus (regenerated from YAML):
- 7 new INPUTs (50-56): outer heading setpoint, produced rudder
setpoint, error, current SOG, live kp/ki/kd.
- 5 new HOLDINGs (24-28): writable heading setpoint, SOG override,
outer base gains. Writing any of kp/ki/kd disables the built-in
3-point gain schedule (operator override).
Tests:
- test_vessel_heading_simulator.py: 6 dynamics tests + 9 parameterised
heading_error_deg edge cases (wrap-around).
- test_pid_outer_python.py: 12 tests covering gain interpolation,
per-tick PID behaviour (deadband, sign, ROT feed-forward,
saturation, rate limit, allowed=false), and three end-to-end cascade
tests (positive step, negative step, wrap-around 360->10).
Cascade verification: outer + inner + rudder dynamics + vessel-heading
simulator settles a 30 deg step within +-2 deg in 60 s.
NOT in Sprint 3 (intentional):
- True Course / Track Keeping / Dodge -- Sprint 5
- Off-course alarms + auto-disengage on sensor loss -- Sprint 6
- COG / SOG / Position via N2K PGN 129025/9/6 -- Sprint 5
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
End-to-end implementation per docs/sprint-2.5-plan.md.
New requirement added by user mid-sprint: 4-role RBAC (Super Admin /
Engineer / Owner / User) with dual-auth for Engineer flashing firmware,
plus a "mini Arduino IDE" inside the Studio.
Tests: pytest 231/231 green (129 Sprint 2 + 102 Sprint 2.5 new).
RBAC core (arautopilot/core/):
- rbac.py: 4 roles, 12 capabilities, immutable capability matrix,
has() / capabilities_of() / require() / requires_dual_auth() helpers.
Engineer flashing firmware needs SA approval; everything else is
single-factor.
- user.py: User model with PBKDF2-HMAC-SHA256 PIN hashing (200k iters,
16-byte salt, self-describing hash format for future migrations).
4-8 digit numeric PINs enforced.
- user_store.py: JSON-backed user database. seed_demo_users() for
first-run UX.
- audit.py: append-only JSONL audit log. AuditEvent with timestamp,
user_id, role, action, target, outcome, reason, secondary_user_id
for dual-auth, optional extra payload. Crypto signing of lines
deferred to Sprint 8.
Studio GUI (arautopilot/studio/):
- app.py: real entry point (replaces Sprint 0 stub). --seed-demo
populates demo users without launching GUI; --data-dir overrides the
~/.ar-autopilot/studio/ default.
- session.py: Session + SessionHolder. check() always audits the
decision; verify_super_admin_pin() + log_dual_auth_grant() for
dual-auth flows.
- login_window.py: modal login dialog with user picker + PIN field.
Audits login attempts (success and bad-PIN denials).
- main_window.py: top-level window with sidebar (user + role + caps)
and tab area (Overview, Flash Console, Project placeholder,
Telemetry placeholder).
- flash_console.py: the "mini Arduino IDE". Lists serial ports via
pyserial; picks firmware variant (esp32-dev / esp32-debug); compiles
via 'pio run'; flashes via 'pio run -t upload --upload-port <port>';
streams pio output to a dark-themed read-only console; supports
cancel. For Engineer flashes, asks the Super Admin for their PIN
inline before invoking pio. Records dual-auth grant + pio exit code
in the audit log.
Dependencies:
- New [project.optional-dependencies] group 'studio': PySide6>=6.6,
pyserial>=3.5, platformio>=6.1. Kept optional so the core can be
installed in lean / CI environments.
Tests (arautopilot/tests/):
- test_rbac.py: 32 tests for capability matrix, dual-auth policy,
no-privilege-escalation invariants, partial overlap between roles.
- test_user.py: 11 tests for PIN hashing, verification, salting,
serialisation, field validators.
- test_audit.py: 9 tests for JSONL append, immutability, round-trip,
corrupt-line detection, dual-auth event shape, blank-line tolerance.
- test_user_store.py: 10 tests for CRUD, persistence, role filtering,
demo seed idempotency.
- test_session.py: 9 tests for capability checks + audit side effects,
SA PIN verification, dual-auth recording, SessionHolder lifecycle.
- test_studio_smoke.py: 5 headless tests verifying Studio modules
import without a display server, --seed-demo works, helpers safe to
call without hardware.
NOT in Sprint 2.5 (intentional):
- Crypto signing of audit log lines (hash-chain) -- Sprint 8
- HWID binding of the user store -- Sprint 8
- Project configurator + .appack compiler -- Sprint 4
- Flutter bridge display -- Sprint 4
- Telemetry dashboard tab -- Sprint 4
- Serial monitor as a separate tab -- future enhancement
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
End-to-end implementation of Sprint 1 per docs/sprint-1-plan.md.
Builds: pio run -e esp32-dev SUCCESS, RAM 6.7%, Flash 26.5% (347 KB).
Tests: pytest 110/110 green; pio test -e native deferred (needs host
C++ compiler -- none on this Windows machine).
Firmware (firmware/ar_autopilot_v1/):
- platformio.ini: 4 envs (esp32-dev release, esp32-debug, native unity
tests, check static analysis). NMEA2000-library@4.22, NMEA2000_esp32@
1.0, eModbus@1.7.4 pinned.
- main.cpp: boot in STANDBY, FreeRTOS task spawn, returns to scheduler.
- system/: ar_log.h facade, task_config.h (priorities/stacks/cores
central table), heartbeat (1 Hz LED + uptime).
- modes/: STANDBY-only state machine; non-STANDBY rejected.
- hal/: di_do.cpp (5 DI + 10 DO with debounce + last-state cache),
rudder_sensor.cpp (100 Hz ADC + 5-sample median filter, Core 1),
rudder_actuator.cpp (DO1/DO2/DO3 with three safety interlocks:
power-off, STANDBY mode, limit switch).
- safety/: TWDT @ 2 s panic-on-expire; 50 Hz safety task on Core 1
enforcing DI1 physical disengage button, DI4 external alarm,
both-limit-switch interlock.
- protocols/modbus_slave.cpp: eModbus RTU server on UART2 @ 38400 8N1,
slave ID 1. 17 inputs + 19 discretes + 5 holdings + 4 coils. Reads
pull live telemetry; writes validate range and route to handlers.
- protocols/nmea2000_consumer.cpp: stack open with CAN TX=GPIO3
RX=GPIO1, subscribed to PGN 127250 (Heading) + PGN 127251 (Rate of
Turn). 5 s staleness flag built in for Sprint 6 alarm wiring.
- filters/median.h: templated MedianFilter<T,N> (host testable).
Cross-cutting:
- modbus_registers.yaml: single source of truth for the Modbus register
map. 45 entries.
- tools/gen_modbus_registers.py: YAML -> C++ header + Python module
generator with --check for drift detection.
- arautopilot/shared/modbus_register_map.py: generated Python mirror,
imported by Studio + tools.
- arautopilot/tests/test_modbus_register_map.py: 30 tests covering
schema, address uniqueness, range, spot-checks, and drift detection
(fails if YAML edited without regenerating).
- firmware/ar_autopilot_v1/tools/modbus_client_test.py: manual Modbus
client for poking the slave from a PC with USB-RS485 dongle.
- firmware/ar_autopilot_v1/test/test_median_filter/test_median.cpp:
8 Unity tests of the median filter (host-side, no Arduino dependency).
- docs/firmware.md: full operator + integrator guide (toolchain, build,
flash, expected boot log, troubleshooting, Sprint 1 capability matrix).
Architecture note: opted for Arduino-on-ESP32 only instead of the
proposed dual Arduino-as-ESP-IDF-component setup. Rationale documented
in CHANGELOG and docs/firmware.md -- Arduino-on-ESP32 already provides
the FreeRTOS primitives we need; dual framework adds fragility without
benefit at Sprint 1 scope. Reconsider in Sprint 8 (OTA + secure boot).
NOT in Sprint 1 (intentional per brief sec. 12):
- PID loops (inner/outer)
- True Course / Track Keeping
- Full alarm catalogue beyond DI1/DI4
- Knob driver
- Studio GUI / dedicated display
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new documents to drive the Sprint 1 approval cycle when the user
reviews in the morning. NO firmware code touched -- this is planning
material only, per brief rule #1 "Antes de cada sprint, me presentas
plan detallado y esperas mi OK. No improvises features."
docs/sprint-1-plan.md
- Sprint 1 objective (firmware boot + STANDBY + Modbus slave +
NMEA 2000 consume of PGN 127250/127251 + watchdog).
- 4 explicit technical decisions awaiting the user's go/no-go:
2.1 Framework: Arduino-as-ESP-IDF-component (recommended)
2.2 New libraries: NMEA2000-library, NMEA2000_esp32, eModbus
(asked per brief rule #4 "No agregues dependencias sin
preguntarme")
2.3 FreeRTOS core/priority mapping (PID isolated on Core 1)
2.4 Logging: ESP_LOG via UART0
- 7-phase breakdown over 3-4 weeks (mirrors brief's Sprint 1 scope).
- Acceptance criteria, risks, and the inputs needed from the user
before kickoff (hardware availability, schematic, NMEA 2000 bus).
docs/firmware-libraries-research.md
- Detailed rationale for each library choice with comparison tables.
- Pinout / hardware references aligned with the existing
firmware/ar_autopilot_v1/src/hal/pinout.h.
- Draft platformio.ini outline (NOT yet written to the firmware
directory -- needs user OK first).
- All external sources cited for traceability.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wrap the most common day-to-day commands so we stop typing
.venv/Scripts/python.exe -m ... by hand. Mirrors the same tasks on both
shells; binaries always resolved from the project's .venv so the host
machine's globally-installed Python doesn't leak in.
Tasks (both shells):
install create .venv, install arautopilot[dev] in editable mode
test run pytest (extra args forwarded: e.g. test -k roundtrip)
test-cov pytest with branch coverage + HTML report
lint ruff check (read-only)
fix ruff check --fix + ruff format
format ruff format
typecheck mypy --strict over core/library/shared
check full quality gate: lint + typecheck + test
demo run examples/sprint0_demo.py
clean remove build/cache artefacts + examples/output
Usage:
.\scripts\dev.ps1 check (Windows PowerShell)
bash scripts/dev.sh check (Git Bash / WSL / Linux)
Verification: `bash scripts/dev.sh check` runs lint + typecheck + 80 tests
all green in ~0.5s on this machine.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Run the dev linters over Sprint 0's core/library/shared modules and
address every finding. Behaviour unchanged; tests still 80/80 green.
Changes:
- Replace `class Foo(str, Enum)` with `class Foo(StrEnum)` (PEP 663
/ Python 3.11+) in 7 enum classes: ActuatorType, AlarmSeverity,
AlarmType, KnobMode, KnobFunction, AutopilotMode, AccessLevel,
VesselType. Pydantic v2 serialises StrEnum the same way, so YAML/JSON
round-trips are byte-identical.
- Use `datetime.UTC` alias in place of `datetime.timezone.utc`
(UP017) across alarms.py, knob_state.py, project_config.py, and
test_knob_state.py.
- Remove now-unnecessary forward-reference quotes from method return
type annotations (UP037) — `from __future__ import annotations` is
already in scope everywhere.
- Tighten `_read_json_resource` / `_read_yaml_resource` in the library
loader: validate that the deserialised payload is actually a dict
before returning, instead of leaking `Any` from json.loads /
yaml.safe_load. Fixes the only two `mypy --strict` findings.
- Add `.claude/settings.local.json` to .gitignore (personal
Claude Code overrides are not committed).
Verification:
ruff check arautopilot/ -> All checks passed
mypy arautopilot/core library shared -> Success, 0 issues, 12 files
pytest -> 80 passed in 0.25s
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Initial commit. Delivers what the brief calls 'Sprint 0 - Foundations'
(see docs/AR_Autopilot_brief.md section 12):
- Complete repository structure (arautopilot package + firmware, display,
installer, tools placeholders + docs).
- Core data model (Pydantic v2): modes, alarms, actuator config, PID
config + gain scheduling, vessel config, knob state machine, project
config with YAML/JSON serialisation.
- Seed library: 2 actuator profiles (hydraulic & electric DC reversible)
and 2 default tunings (yacht motor planeo 30 m and 40 m). Conservative
literature values, NOT the integrator's production tuning IP.
- Firmware skeleton: only src/hal/pinout.h with the 21 I/O contract for
the AR-NMEA-IO v1.0 board. No drivers, no main loop.
- Studio stubs (real PySide6 app starts in Sprint 4).
- pytest suite (80 tests, all green): modes, alarms, actuator, PID
(incl. gain interpolation and the +/-50% adaptive bound from brief
section 6), vessel, knob state, project config, library loader,
end-to-end roundtrip.
- examples/sprint0_demo.py - the acceptance demo from the brief.
Acceptance criteria met:
- pytest green (80/80)
- demo creates, saves (YAML + JSON), reloads, and verifies a full
ProjectConfig using the seed library
- repository ready for tag `sprint-0-approved`
See CHANGELOG.md for the detailed scope.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
alro65