AR-Autopilot/docs/operator_manual.md

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
2. System Overview
3. Installation Checklist
4. Controls and Indicators
5. Operating Modes
6. Engaging and Disengaging
7. Heading Hold (HH)
8. True Course (TC)
9. Track Keeping (TK)
10. Dodge Mode
11. Alarm Reference
12. Commissioning
13. Fault-Finding
14. Modbus Register Reference
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.