Summary of the AR3 Sketch
by Claude 4.5
AR3 (also referred to as TAR3 in this build) is an Arduino Uno R4 WiFi sketch that acts as the relay execution and autonomous control node of the ARMAC system. It sits at the intersection of three communication channels: the RS-485 link to AR1, the UDP WiFi link to AR2, and (on FireSys hardware) an I²C LCD display. Its responsibilities include executing relay commands received from AR1 in Remote mode, running a full autonomous sprinkler and shed-cooling programme based on live sensor data in Autonomous mode, forwarding sensor telemetry upstream to AR1 over RS-485, and driving a test facility that exercises the autonomous logic against scripted scenarios.
Hardware Variants: FireSys and TestSys
The same firmware runs on two distinct hardware configurations detected at boot. If pin D11 is strapped to ground (sampled with a majority vote over eight reads for robustness), the board is identified as a TestSys bench unit: LCD output is suppressed, the cooldown detection window is shortened from 5 minutes to 1 minute to make testing practical, and the FS_DISABLE_AUTONOMOUS build-time flag is overridden to always permit Autonomous mode regardless of how the field build was compiled. On FireSys (pin floating), the I²C LCD is initialised and all field timings apply. This single-pin detect allows the same compiled binary to behave correctly in both contexts without separate builds.
Pin Assignments and Outputs
Relay outputs use active-low logic: a pump latching contactor is driven by two coil pins (D2 for ON, D3 for OFF), each pulsed for 300 ms when a state change is commanded. Four peripheral relays occupy D4–D7 (P1 recirc valve, P2 shed cooling, P3 high-flow selector, P4 gel injection). All relay outputs are initialised HIGH (off) at boot. On TestSys, the coil pins are repurposed as LED indicators that hold their state after the pulse to show pump-on or pump-off status visually, mimicking the latch relay. An analogue test button on A3 is read with a long/short press distinction: a short press (under 1.2 seconds) starts the test sequence; a long press stops it.
RS-485 Communications with AR1
AR3 receives framed messages from AR1 via Serial1 at 9600 baud. Frames are delimited by < and > characters and carry an XOR-based hex checksum. The frame parser accumulates incoming bytes into a buffer, strips the checksum, and dispatches complete frames to a handler. Four frame types are recognised. HB: frames update the heartbeat timestamp that AR3 uses to determine whether Remote mode is live. STAT: frames carry the current relay state of P1–P4, the heartbeat flag, lock state, and HA auto-enable flags; in Remote mode AR3 mirrors the P1–P4 values directly to its relay outputs from these frames. CMD: frames carry an explicit relay command with a 4-bit sequence number and pump plus P1–P4 states; AR3 applies the pump edge and P1–P4 states and returns a sequenced ACK. CFG: frames deliver manual intermittent timing configuration (on/off minutes for P1) from AR1 for use in Remote mode manual cycling.
Telemetry is sent upstream to AR1 as a framed RS-485 message every 2 seconds, containing the full sensor snapshot (all temperatures, flow, water level, ember, phase, mode code, battery, pump state, P1–P4 states, oil pressure, and water pressure voltage) plus a READY:1 flag that AR1 uses to gate relay commands until AR3 is confirmed alive.
Pump Edge Control and Sequence ACK
All pump state changes go through a guarded edge function. The guard enforces a 400 ms silence window after any state change (during which further commands are dropped), a 400 ms minimum interval between same-direction repeated commands (which are ACKed immediately without pulsing), and a 400 ms hold-off between opposite-direction commands (to protect the contactor). Duplicate sequence numbers are ACKed without re-pulsing. The first command after boot is always applied unconditionally to establish an initial known pump state. When the Lock flag is active, pump-ON commands are silently converted to pump-OFF before the edge function is called.
A separate lock-kick mechanism in the main loop repeatedly sends pump-OFF commands every 500 ms for as long as the lock is active and the pump is still on, providing a safety backstop in case the initial OFF command was dropped.
Autonomous Mode and Mode Management
The mode manager (tickMode()) runs every loop pass and arbitrates between Remote and Autonomous operation. AR3 boots into Remote mode and requires a positive signal to enter Autonomous: either the HA_AUTO flag arriving in a STAT frame, or the heartbeat having been absent for 5 minutes (HB_ARM_MS). A boot-time guard prevents immediate Autonomous entry just because no heartbeat has been received yet. Exit from Autonomous back to Remote requires the heartbeat to be fresh and HA_AUTO cleared, and is only confirmed after the heartbeat has been stable for 60 seconds (HB_STABLE_MS) to avoid oscillation on a flapping link.
On entry to Autonomous mode all state is reset: phase reverts to WARMUP, the TRISE tracker and cooldown detection samples are cleared, all intermittent FSM timers are reset, and the shed thermostat latch is cleared. If a resume flag is set, the pump and relays are left in their current state rather than forced safe; otherwise they are set to all-off before autonomous logic takes over.
Autonomous Control Logic
The autonomous plan is computed each loop pass in fsComputeAutoPlan(), which builds an FsAutoOutputs structure describing the desired state of all five outputs (pump, P1 recirc, P2 shed, P3 high-flow, P4 gel), and then fsApplyAutoOutputs() translates that into actual relay changes and manages the intermittent cycle timers.
The plan is governed by a strict priority hierarchy. Water level is checked first. At or below 0.05 m (dry cutoff) all outputs are forced off. Between 0.05 and 0.30 m (gel priority band) the pump runs continuously and P4 (gel injection) is activated; P3 high-flow is suppressed. Between 0.30 and 0.50 m (recirc band) a conservative fixed sprinkler intermittent cycle of [3 on, 8 off] minutes is applied regardless of temperature, and any continuous pump request from the temperature logic is overridden to intermittent.
Above 0.50 m, temperature drives behaviour. The system tracks two phases: WARMUP and COOLDOWN. The transition from WARMUP to COOLDOWN is detected by monitoring a rolling window: if external temperature has dropped by at least 5°C and internal temperature by at least 2°C over the window period (5 minutes in the field, 1 minute on TestSys), phase switches to COOLDOWN and stays there for the remainder of the autonomous run.
In WARMUP, external temperature above 80°C activates continuous pump/sprinklers. Between 75 and 80°C an intermittent cycle of [5, 3] minutes is used. Between 60 and 75°C a [3, 7] minute cycle applies. Below 60°C no sprinkler activity occurs. In COOLDOWN the same external temperature thresholds drive reduced cycles: 70–80°C maps to [3, 5], 60–70°C to [3, 8], and below 60°C all sprinkler activity ceases.
For intermittent cycles, the driver (pump P0 or recirc valve P1) is selected by battery voltage and cycle timing: battery at or below 12.0 V always forces P1 (recirc) to protect the pump; above 12.0 V cycles with an off-time exceeding 15 minutes use P0 (pump), shorter cycles use P1. When P1 is selected the pump also runs during the on-phase to provide water pressure to the recirc circuit.
P3 (high-flow) is activated whenever external temperature exceeds 80°C, running concurrently with continuous pump operation.
Shed cooling (P2) is governed by a thermostat mode separate from the main sprinkler logic. When internal temperature reaches 47°C (after having cooled below 45°C), a 1-minute P2 pulse is started. If a subsequent trigger arrives within 2 minutes of the previous pulse start, the system escalates to continuous P2 ON, which latches until the next Autonomous entry. Internal temperature above 60°C forces immediate continuous P2 regardless of thermostat state. This logic mirrors the shed thermostat behaviour in AR1, ensuring consistent shed protection whether the system is in Remote or Autonomous mode.
LCD Display
On FireSys hardware, a 16×2 I²C LCD cycles through three pages every 2.5 seconds. Page 1 shows current water level and mode character (A/R), with a heartbeat freshness indicator and a "HB:WARN" notice if the heartbeat has been absent between 60 seconds and 5 minutes. Page 2 shows heartbeat state. Page 3 shows instantaneous relay states for pump, P1–P4. All LCD calls are skipped on TestSys.
Test Facility
AR3 includes a built-in test facility triggered by the physical button on A3. A short press sends SIMCTRL:SPEED and SIMCTRL:START commands over UDP to AR2, forcing a HB:0 on RS-485 to put AR3 into Autonomous mode for the duration of the test, suppressing any incoming heartbeat signals for the test run, and entering Autonomous with a clean state reset. AR3 then waits for the first UDP packet from AR2 before starting the autonomous tick, ensuring the scenario has time to initialise before control decisions are made. A long press sends SIMCTRL:STOP to AR2 and terminates the test. The test facility uses the same autonomous logic as production operation, providing a direct end-to-end validation of the control algorithms against realistic sensor scenarios without requiring actual fire conditions.
<< AR2 Arduino Sketch - Structure and Function | | >> |Table of Contents>