alro65
a2f3e82f17
Integration tests (64 new tests, 462 total): - test_integration_cascade: full cascade closed-loop simulation -- outer PID → inner PID → rudder dynamics → vessel heading; verifies convergence across small/90°/180° turns, wrap-around, and low speed - test_integration_ekf_pid: EKF-smoothed heading feeding outer PID; confirms EKF reduces rudder total-variation vs raw noisy heading - test_integration_alarm_audit: alarm engine → audit log hash-chain; verify, tamper detection, cross-session reload, multi-alarm logging - test_modbus_utils: 38 tests for scale/raw conversion, bounds checking, heading/rudder helpers, signed int16 two's-complement round-trip Hardening: - heading_ekf: guard NaN/inf in update_heading() and update_rot() -- skip bad measurements silently rather than corrupting filter state - adaptive_tuner: guard NaN/inf in step() -- ignore corrupt error samples - modbus_utils.py: new shared module with scale_to_raw, scale_to_raw_signed, raw_signed_to_scaled, clamp_uint16, validate_holding_write, heading_deg_to_raw, rudder_deg_to_raw_signed Documentation: - docs/operator_manual.md: 15-section operator manual covering safety, installation, all operating modes, alarm reference, commissioning, fault-finding, Modbus register summary, and activation/audit log procedure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
280 lines
12 KiB
Markdown
280 lines
12 KiB
Markdown
# AR-Autopilot — Operator Manual
|
||
|
||
**Document status:** Sprint 9 (production-ready baseline)
|
||
**Firmware version:** 1.0.0 and later
|
||
**Applies to:** AR-Autopilot display unit + ESP32 controller
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Safety Instructions](#1-safety-instructions)
|
||
2. [System Overview](#2-system-overview)
|
||
3. [Installation Checklist](#3-installation-checklist)
|
||
4. [Controls and Indicators](#4-controls-and-indicators)
|
||
5. [Operating Modes](#5-operating-modes)
|
||
6. [Engaging and Disengaging](#6-engaging-and-disengaging)
|
||
7. [Heading Hold (HH)](#7-heading-hold-hh)
|
||
8. [True Course (TC)](#8-true-course-tc)
|
||
9. [Track Keeping (TK)](#9-track-keeping-tk)
|
||
10. [Dodge Mode](#10-dodge-mode)
|
||
11. [Alarm Reference](#11-alarm-reference)
|
||
12. [Commissioning](#12-commissioning)
|
||
13. [Fault-Finding](#13-fault-finding)
|
||
14. [Modbus Register Reference](#14-modbus-register-reference)
|
||
15. [Certification and Licensing](#15-certification-and-licensing)
|
||
|
||
---
|
||
|
||
## 1. Safety Instructions
|
||
|
||
**Read all instructions before operating the autopilot.**
|
||
|
||
- The AR-Autopilot is a navigational aid only. **A qualified watch-keeper must remain on the bridge at all times** while the autopilot is engaged. The operator is always responsible for collision avoidance.
|
||
- **Always disengage before entering port, anchoring, or navigating restricted waters.**
|
||
- Test all manual override and disengage functions before each voyage.
|
||
- If any alarm sounds, acknowledge it and investigate the cause before continuing.
|
||
- Do not attempt to override or silence a HEADING SENSOR LOST or OFF-COURSE SEVERE alarm — these indicate loss of situational awareness.
|
||
- Ensure the NMEA 2000 network is correctly terminated (two 120 Ω resistors, one at each bus end) before commissioning.
|
||
- The controller draws up to 30 A peak. Fuse the supply with an appropriately rated marine-grade fuse at the switchboard.
|
||
|
||
---
|
||
|
||
## 2. System Overview
|
||
|
||
```
|
||
[NMEA 2000 backbone] ──► [ESP32 controller] ──► [H-bridge / hydraulic valve]
|
||
│ │
|
||
[RS-485] [rudder feedback pot]
|
||
│
|
||
[Display PC / tablet]
|
||
```
|
||
|
||
The ESP32 controller:
|
||
- Receives heading (PGN 127250), ROT (PGN 127251), COG/SOG (PGN 129026), and XTE/waypoint (PGN 129284) from the NMEA 2000 backbone.
|
||
- Drives the rudder actuator via PWM.
|
||
- Reads rudder position via ADC (feedback potentiometer).
|
||
- Publishes autopilot state back to the NMEA 2000 bus (PGN 127245 rudder, PGN 127237 heading track control).
|
||
- Exposes all telemetry and command registers over Modbus RTU RS-485.
|
||
|
||
The Studio software (PC/tablet) communicates via Modbus and provides the operator interface, alarm display, and audit log.
|
||
|
||
---
|
||
|
||
## 3. Installation Checklist
|
||
|
||
Before first power-on:
|
||
|
||
- [ ] Controller securely mounted, protected from bilge water.
|
||
- [ ] NMEA 2000 backbone correctly terminated.
|
||
- [ ] Controller connected as a NMEA 2000 device (T-piece, correct PGN subscriptions active on MFD).
|
||
- [ ] RS-485 cable wired A/B correctly to display unit; max cable length 1 200 m at 38 400 baud.
|
||
- [ ] Actuator wired with correct polarity (positive terminal drives starboard, negative drives port).
|
||
- [ ] Rudder feedback potentiometer wiper connected to ADC input; verify resistance changes smoothly through full travel.
|
||
- [ ] Port and starboard limit switches wired to DI2 and DI3 respectively.
|
||
- [ ] Disengage push-button wired to DI1.
|
||
- [ ] External alarm input (VMS/genset) wired to DI4 if fitted.
|
||
- [ ] Supply fused and connected (12/24 V DC depending on variant).
|
||
- [ ] Commissioning wizard completed (see section 12).
|
||
|
||
---
|
||
|
||
## 4. Controls and Indicators
|
||
|
||
### Physical controls
|
||
|
||
| Control | Function |
|
||
|---|---|
|
||
| Engage/Disengage button | Rising edge requests engage; while engaged, press to disengage immediately |
|
||
| Heading knob (optional) | After arming via Studio, each click adjusts setpoint by 1°; auto-disarms after 5 s |
|
||
| Manual confirm switch | Emergency override — allows engage while limit switch or minor alarm is active |
|
||
|
||
### Display (Studio)
|
||
|
||
| Indicator | Meaning |
|
||
|---|---|
|
||
| Mode badge (green) | Pilot engaged in the shown mode |
|
||
| Mode badge (grey) | STANDBY — manual steering |
|
||
| Red alarm banner | One or more alarms active |
|
||
| Amber alarm banner | One or more LOW alarms active; no auto-disengage risk |
|
||
| Heading tape | Current heading vs setpoint |
|
||
| Rudder bar | Commanded rudder position |
|
||
|
||
---
|
||
|
||
## 5. Operating Modes
|
||
|
||
| Mode | Code | Description |
|
||
|---|---|---|
|
||
| STANDBY | 0 | Manual steering. Actuator power off. All PIDs idle. |
|
||
| Heading Hold | 1 (HH) | Maintains the compass heading set at the time of engagement. |
|
||
| True Course | 2 (TC) | Maintains the COG setpoint (corrects for leeway and current). Requires PGN 129026. |
|
||
| Track Keeping | 3 (TK) | Corrects cross-track error to a route waypoint. Requires PGN 129284. |
|
||
| Dodge | 4 | Temporarily offsets the heading by a fixed amount (±1 to ±30°) to pass an obstacle. |
|
||
|
||
---
|
||
|
||
## 6. Engaging and Disengaging
|
||
|
||
### To engage
|
||
|
||
1. Confirm the vessel is on the desired heading (or set the desired COG/XTE in TC/TK mode).
|
||
2. Press **Engage** on the Studio or the physical button.
|
||
3. The controller checks interlocks: no limit switches active, heading sensor fresh (<5 s), battery voltage ≥ 10.5 V.
|
||
4. On success, the mode badge turns green and the rudder begins driving.
|
||
|
||
### To disengage
|
||
|
||
- Press the **Disengage** button (physical or on-screen) at any time.
|
||
- Any EMERGENCY alarm also triggers automatic disengage.
|
||
- Power loss automatically disengages (fail-safe to manual steering).
|
||
|
||
---
|
||
|
||
## 7. Heading Hold (HH)
|
||
|
||
Heading Hold captures the current compass heading the moment the pilot engages. The outer PID corrects any subsequent deviation. Rate-of-turn feed-forward reduces overshoot during turns.
|
||
|
||
**To change the setpoint while engaged:**
|
||
- Use the heading increment/decrement arrows on the Studio (+/– 1° per press).
|
||
- Or arm the physical knob (CMD_KNOB_ARM coil) and rotate.
|
||
|
||
**Gain scheduling:** Gains reduce at low speed and increase at high speed. The active gains are visible in the PID telemetry panel.
|
||
|
||
---
|
||
|
||
## 8. True Course (TC)
|
||
|
||
True Course maintains a desired Course Over Ground (COG) rather than a compass heading. The controller reads COG from PGN 129026 and adjusts the heading setpoint to correct for current and leeway.
|
||
|
||
**Requirements:** An NMEA 2000 GPS/chartplotter transmitting PGN 129026 at ≥ 1 Hz.
|
||
|
||
**COG age alarm:** If COG is not updated within 5 s, the alarm HEADING SENSOR LOST fires and the pilot auto-disengages.
|
||
|
||
---
|
||
|
||
## 9. Track Keeping (TK)
|
||
|
||
Track Keeping adds cross-track error (XTE) correction on top of True Course. If the vessel drifts off the planned route, the heading setpoint is offset to steer back.
|
||
|
||
**Requirements:** An NMEA 2000 chartplotter transmitting PGN 129284 (Navigation Data) at ≥ 1 Hz.
|
||
|
||
**XTE limit:** The heading correction from XTE is clamped to ±20° by default (configurable via `XTE_MAX_CORRECTION_X100`). If the vessel is more than the XTE correction limit off track, the track error alarm fires.
|
||
|
||
---
|
||
|
||
## 10. Dodge Mode
|
||
|
||
Dodge mode adds a temporary heading offset to avoid an obstacle without disengaging.
|
||
|
||
1. The operator sets `DODGE_OFFSET_DEG_X100` (holding register 8) to the desired offset (positive = starboard, negative = port).
|
||
2. Select MODE_REQUEST = 4 (DODGE).
|
||
3. The new heading setpoint = locked HH heading ± offset.
|
||
4. To return to the original course, select MODE_REQUEST = 1 (HH) and the offset is discarded.
|
||
|
||
---
|
||
|
||
## 11. Alarm Reference
|
||
|
||
| Alarm | Severity | Auto-disengage | Cause | Action |
|
||
|---|---|---|---|---|
|
||
| OFF_COURSE | LOW | No | Heading deviates > 10° from setpoint | Verify sea state; adjust ROT feed-forward if persistent |
|
||
| OFF_COURSE_SEVERE | EMERGENCY | Yes | Heading deviates > 30° for > 5 s | Check rudder feedback and actuator power |
|
||
| RUDDER_NOT_RESPONDING | EMERGENCY | Yes | Rudder setpoint sent but no motion for 3 s | Check actuator power relay, limit switches, hydraulic pressure |
|
||
| HEADING_SENSOR_LOST | EMERGENCY | Yes | PGN 127250 not received for > 5 s | Check NMEA 2000 termination; check compass power |
|
||
| ACTUATOR_OVERCURRENT | HIGH | Yes | Actuator current > threshold | Check for rudder jam, hydraulic fault |
|
||
| VOLTAGE_LOW | HIGH | Yes | Supply < 10.5 V | Check battery and alternator |
|
||
| LIMIT_SWITCH_REACHED | LOW | No | Rudder at mechanical end-stop | Steer vessel to reduce commanded angle; check rudder travel |
|
||
| WATCHDOG_TRIPPED | EMERGENCY | Yes | Firmware watchdog fired (MCU reset) | Report to Alvaro Rodríguez Marine; check for power glitch |
|
||
| VMS_CRITICAL | EMERGENCY | Yes | VMS reported blackout or overload | Check VMS display; cut non-essential loads |
|
||
|
||
---
|
||
|
||
## 12. Commissioning
|
||
|
||
The commissioning wizard is run once during installation via the AR-Autopilot Studio.
|
||
|
||
### Phase 1 — Rudder limits
|
||
|
||
The wizard drives the rudder to port and starboard limits and records the ADC calibration values. Ensure the vessel has sea room and the limit switches are installed.
|
||
|
||
### Phase 2 — Sensor calibration
|
||
|
||
Verify the ADC reading changes correctly across the rudder travel. If the port and starboard readings are inverted, the wiring polarity is reversed — the wizard corrects this in software.
|
||
|
||
### Phase 3 — Auto-tuning
|
||
|
||
The wizard performs a relay feedback test (Åström-Hägglund method) to estimate the ultimate gain and ultimate period of the plant. The ZN formulas are used to calculate initial PID gains. This step requires approximately 5 minutes of clear water at cruising speed.
|
||
|
||
### Phase 4 — Confirmation
|
||
|
||
The commissioning data (ADC bounds, PID gains) is stored in non-volatile storage (NVS) on the ESP32 and applied automatically at every subsequent power-on.
|
||
|
||
---
|
||
|
||
## 13. Fault-Finding
|
||
|
||
| Symptom | Likely cause | Check |
|
||
|---|---|---|
|
||
| Pilot will not engage | Interlock active | Check alarm banner for root cause; check limit switches |
|
||
| Rudder drives to one side and does not return | Actuator power issue / limit switch wired backwards | Swap DI2/DI3 wiring |
|
||
| Excessive overshoot on heading changes | ROT feed-forward too low or Kd too low | Increase `rot_ff_gain` or Kd in Studio tuning panel |
|
||
| Hunting / oscillation | Kp too high | Run auto-tuner from commissioning wizard to re-tune |
|
||
| Heading deviates in cross-wind | Ki too low | Increase Ki slightly; avoid excessive Ki (causes windup) |
|
||
| NMEA 2000 alarms intermittent | Bus termination | Verify exactly two 120 Ω resistors; check backbone cable |
|
||
| Heading sensor lost alarm at speed | GPS/chartplotter update rate < 1 Hz | Increase source device update rate |
|
||
|
||
---
|
||
|
||
## 14. Modbus Register Reference
|
||
|
||
Communication: RS-485, 38 400 baud, 8N1, Modbus RTU, slave address 1.
|
||
|
||
### Key holding registers (read/write)
|
||
|
||
| Address (40001+) | Name | Unit | Scale | Range |
|
||
|---|---|---|---|---|
|
||
| 40001 | MODE_REQUEST | — | 1 | 0–4 |
|
||
| 40002 | HEADING_SETPOINT_X100 | deg | 0.01 | 0–35999 |
|
||
| 40003 | BRIGHTNESS_PCT | % | 1 | 0–100 |
|
||
| 40009 | DODGE_OFFSET_DEG_X100 | deg | 0.01 | signed ±9000 |
|
||
|
||
### Key input registers (read-only telemetry)
|
||
|
||
| Address (30001+) | Name | Unit | Scale |
|
||
|---|---|---|---|
|
||
| 30001–30003 | FW_VERSION_MAJOR/MINOR/PATCH | — | 1 |
|
||
| 30007 | CURRENT_MODE | — | 1 |
|
||
| 30010 | HWID_MAC_01 | — | 1 |
|
||
| 30011 | HWID_MAC_23 | — | 1 |
|
||
| 30012 | HWID_MAC_45 | — | 1 |
|
||
| 30017 | RUDDER_ANGLE_DEG_X100 | deg | 0.01 |
|
||
| 30025 | HEADING_DEG_X100 | deg | 0.01 |
|
||
| 30026 | ROT_DPS_X100 | deg/s | 0.01 |
|
||
| 30033 | BATTERY_VOLTAGE_X100 | V | 0.01 |
|
||
|
||
The full register map is in `firmware/ar_autopilot_v1/modbus_registers.yaml`.
|
||
|
||
---
|
||
|
||
## 15. Certification and Licensing
|
||
|
||
The AR-Autopilot uses hardware-binding activation. Each controller has a unique 6-byte hardware ID (HWID) derived from the ESP32 eFuse MAC address. The installer must obtain an activation token from the factory using the HWID and enter it in the Studio before the autopilot can be used in production.
|
||
|
||
### Activating a unit
|
||
|
||
1. Connect to the controller via Modbus.
|
||
2. In the Studio, navigate to **Settings → Activation**.
|
||
3. The HWID is displayed in `AA:BB:CC:DD:EE:FF` format (read from input registers 9/10/11).
|
||
4. Contact Alvaro Rodríguez Marine with the HWID to obtain the activation token.
|
||
5. Enter the token in the Studio. The token is verified locally using HMAC-SHA256.
|
||
|
||
### Audit log
|
||
|
||
Every significant event (engage, disengage, mode change, alarm, alarm acknowledge, commissioning) is written to an immutable SHA-256 hash-chained audit log stored on the display computer. The log can be exported from **Settings → Audit Log** for inspection by port authorities or warranty service.
|
||
|
||
---
|
||
|
||
*© Alvaro Rodríguez Marine — All rights reserved.*
|
||
*For technical support contact the installation company or email support@arautopilot.com.*
|