Summary of the AR1 Sketch
by Claude 4.5
AR1 is an Arduino Uno R4 WiFi sketch that acts as the primary controller and communications hub for the ARMAC bushfire defence system. It sits between Home Assistant (HA) on the local network and AR3, the autonomous relay controller, connected via RS-485. AR1 handles MQTT communications, translates HA commands into RS-485 relay commands, manages two local peripheral modes (sprinkler cycling and shed cooling), and arbitrates between Remote (HA-controlled) and Autonomous (AR3-controlled) operating modes.
Hardware and Pin Assignments
AR1 drives six relay outputs on pins 2–7: a latching pump contactor (separate ON/OFF coils on pins 2 and 3) and four peripheral relays (P1–P4 on pins 4–7). Additional outputs are a direct pump start pin (11) and the heartbeat signal pin (8), which signals to AR3 whether Remote mode is active. Analogue inputs read oil pressure (A1), water pressure (A2), tank level (A0), and an ember/flame detector (A4). Temperature sensors on pins 9 and 10 are proxies that return values received from AR3 over RS-485 rather than local readings. RS-485 uses the Gravity DFR0845 transceiver on Serial1 (9600 baud) with automatic direction control.
EEPROM Persistence
Relay states (pump, P1–P4) and peripheral timing configurations (P1 and P2 on/off durations in minutes) are persisted to EEPROM addresses 0–8. Address 9 stores the last-known heartbeat (Remote/Autonomous) mode; address 10 stores a Development/Production boot flag. In Production mode, all states are restored from EEPROM on reboot. In Development mode, relay and timer states are cleared to safe defaults (all off, timings zero) on every reboot, which avoids inadvertent activation during firmware iteration. The dev/prod flag is toggled from HA via MQTT and persists independently of the state-clearing.
Network and MQTT
AR1 holds a table of known WiFi networks and on boot iterates through them until one connects, selecting the corresponding MQTT broker address automatically. This allows the same firmware to run on-site or at a test bench without modification. The MQTT client ID is derived from the board's MAC address for uniqueness. On connection, AR1 publishes its online status and subscribes to topics covering pump control, four peripheral set/timing topics, lock control, heartbeat commands, flame acknowledgement, and the dev mode toggle. A watchdog timer (8 second interval) is refreshed each loop pass; failure to refresh (e.g. from a hung loop) triggers a hardware reset.
If MQTT connectivity is lost for more than five minutes, AR1 automatically drops the heartbeat signal, which causes AR3 to enter Autonomous mode. When MQTT is restored, the heartbeat resumes and Remote mode reactivates.
Remote vs Autonomous Mode (Heartbeat)
The heartbeat signal on pin 8 is the mode-arbitration mechanism between AR1 and AR3. When the heartbeat is HIGH (active), AR3 defers relay control to AR1 commands (Remote mode). When LOW, AR3 runs its own autonomous sprinkler cycle logic independently of AR1. AR1 forces itself into Remote mode on every boot to ensure a known starting state.
Heartbeat control arrives from HA via the heartbeat/cmd MQTT topic (preferred) or the legacy heartbeat/control topic. A 12-second boot-window guard ignores retained ON/OFF messages on the legacy topic at startup, preventing stale HA state from overriding the boot-time Remote default. The current mode is published retained to heartbeat/control/state, where payload "OFF" means Autonomous is active (an intentionally inverted convention to align with HA switch semantics).
When transitioning from Autonomous back to Remote (heartbeat START), AR1 reads the last-known AR3 relay state cache (populated from recent RS-485 telemetry) and, if it is fresh (within 10 seconds), adopts that state for its own relay tracking. This ensures a smooth handover with no relay glitch when HA reasserts control.
RS-485 Command and Telemetry Protocol
All relay commands to AR3 are sent as CMD: frames containing a 4-bit sequence number plus pump and P1–P4 states as a single atomic packet: e.g. CMD:SEQ:3|LOCK:0|PUMP:1|P1:0|P2:1|P3:0|P4:0. AR3 acknowledges with an ACK:SEQ:<n>|PUMP:<0/1> frame. AR1 implements a fast-retry mechanism: if no matching ACK is received within 120 ms, the command is resent up to four more times before giving up. This provides robustness against RS-485 noise without blocking the main loop.
Separate STAT: frames carry status snapshots (heartbeat mode, P1–P4 coil states, lock state) without a pump field, so AR3 can update its mirrors without interpreting them as pump commands. Timing configuration for P1 intermittent cycling is forwarded to AR3 via CFG:INT frames whenever HA updates the on/off dial values.
AR3 telemetry frames carry pipe-delimited key:value fields including INT_TEMP, EXT_TEMP, WATER_LEVEL, FLOW, EMBER, PUMP, P1–P4, OIL_OK, WATER_PV, BAT, PHASE, and MODE. AR1 parses these on receipt, updates its volatile sensor cache, and republishes all values to MQTT for HA consumption. Relay states from AR3 telemetry are only republished to MQTT when in Autonomous mode (heartbeat inactive), so HA always sees the authoritative current state regardless of which unit is in control. A "ready" flag (ar3Ready) gates all outgoing relay commands until at least one valid telemetry frame has been received from AR3, preventing commands being issued to an unresponsive downstream unit.
All RS-485 frames are wrapped in <...> delimiters and carry an 8-bit byte-sum checksum appended after a | separator. Frames failing checksum validation are dropped, with a fallback that accepts any frame containing a : field separator in case the checksum calculation diverges between firmware versions.
Lock Mechanism
A software lock (lockState), controllable from HA via home/lock/control, forces the pump and P1/P3/P4 off and blocks any MQTT command that would re-enable them while active. P2 (shed cooling) is explicitly exempted from the lock, as cooling the pump shed is considered a safety requirement independent of fire-defence operational state. The lock state is included in every CMD frame sent to AR3, so it is enforced at both ends of the RS-485 link. AR1 always boots with the lock engaged.
Peripheral Control
P1 – Sprinkler/Recirc (Valve): P1 controls a valve that switches the sprinkler circuit between recirculation and pass-through. Two driver modes are available: RECIRC mode, where AR1 cycles the valve on a configurable on/off timer; and PUMP mode, where the valve is held open and the pump itself is cycled instead. PUMP mode is subject to a battery voltage gate (minimum 12.25 V) and a minimum cycle duration constraint (both on and off phases must exceed 10 minutes) to protect the pump from short-cycling. If PUMP mode is requested but the safety conditions are not met, the driver is silently downgraded to RECIRC and HA is notified. TimeON and TimeOFF parameters (in minutes, up to 240) are set from HA via MQTT, stored in EEPROM, and forwarded to AR3 via CFG frames.
P2 – Shed Cooling: P2 drives a shed cooling device and supports four sub-modes determined by the TimeON2/TimeOFF2 configuration: both zero activates thermostat mode; TimeON2 > 0 with TimeOFF2 = 0 forces continuous ON; TimeON2 = 0 with TimeOFF2 > 0 forces continuous OFF; both > 0 runs a timed intermittent cycle. In thermostat mode, AR1 uses the internal temperature received from AR3: it triggers 1-minute cooling pulses when the internal temperature reaches 47°C (with a re-arm threshold of 45°C after cooling), and escalates to continuous ON if two pulses occur less than 2 minutes apart. If the internal temperature reading is absent (NaN), P2 defaults to continuous ON as a safe fallback.
Autonomous Mode Telemetry Pass-Through
When the heartbeat is inactive (Autonomous mode active), AR1 continues to receive and parse AR3 telemetry and republishes relay states (PUMP, P1–P4) directly to their respective MQTT topics with the retained flag set. This means HA always displays the current physical relay state driven by AR3's autonomous logic, even though AR1 is not generating the commands.
<< Backing up and Restoring the Raspberry Pi | | AR2 Arduino Sketch - Structure and Function >> |Table of Contents>