01. Operational Architecture

The APC-S3 Pro utilizes a True Dual-Core RTOS architecture. Core 1 is isolated for real-time safety critical tasks (Sensor Polling, Motor Control, Solenoid Venting), while Core 0 handles the Network Stack (WiFi, MQTT, Local Web Server). This ensures the pump never fails even during heavy network congestion.

02. First-Time Setup (AP Mode)

Provisioning the Device

Before the system can connect to your router, it starts in Access Point (AP) mode. Connect your smartphone to the device directly to provide your WiFi credentials.

03. Engineering Pin-Mapping

Official GPIO assignments for the ESP32-S3 WROOM interface. Do not modify the hardware traces without consulting the factory manual.

Component	Pin (GPIO)	Protocol	Direction
LCD SDA / SCL	GPIO 1 / 2	I2C	Output/Input
Voltage Sensor (ZMPT)	GPIO 4	Analog (ADC)	Input
Ultrasonic TRIG / ECHO	GPIO 5 / 6	Pulse Digital	Out/In
Main Motor Relay	GPIO 8	High/Low	Output
Manual Reset / Override	GPIO 9	Digital In (Pull)	Input
Pressure Solenoid	GPIO 10	High/Low	Output
Flow Pulse Sensor	GPIO 18	Digital Interrupt	Input
Status RGB (NeoPixel)	GPIO 48	1-Wire	Output

04. RGB LED Logic Matrix

05. LCD Visual Interface

Smart Status Label Dictionary

Refer to these codes that appear on the right side of the screen for real-time diagnostics.

LCD Label	Type	Meaning / Logic
PUMP ON	Motor	Relay is active. Pump/Compressor is running.
PUMP OFF	Motor	System standby. Motor is powered down.
FLOW OK	Flow	Active flow pulses detected via pipe/tank. Normal operation.
FLOW CHK	Flow	Start-up grace period. System waiting for water pressure.
ONLINE	Cloud	WiFi Connected & HiveMQ Cloud connection established.
WAITING	Cloud	WiFi OK. Attempting to bridge to MQTT Cloud servers.
NO WIFI	Cloud	Not connected to any router. Cloud disconnected.
NORMAL	Power	Voltage is within the stable 170V - 250V window.
OVER	Power	High Voltage Alert! Motor cut-off for protection.
UNDER	Power	Low Voltage Alert! Motor cut-off for protection.
SNR ERR	Health	Ultrasonic sensor failure. Check wiring/eye cleanliness.
DRY ALRM	Safety	No water flow detected. Motor stopped to prevent damage.
LOCKED	Safety	System is waiting for the Auto-Retry countdown to finish.
PUMP REST	Safety	1-Hour limit reached. Motor is cooling down.
VENTING	Valve	Compressor mode active. Releasing head-pressure.
DELAY	Power	Voltage just stabilized. 10-second safety countdown active.

06. 💧 Water Level Logic

The system polls the Ultrasonic sensor every 4 seconds and uses a 20-sample Median Filter to ignore water turbulence. Auto-Start: Below 20%. Auto-Stop: At 100%.

07. 🌙 Smart Scheduling (DND)

To prevent motor noise during sleeping hours, the system includes a Do Not Disturb (DND) timer. When active, a Moon Badge appears on the dashboard, and the pump will not auto-start even if the water is low.
Note: You can still force-start the pump via the Manual Button or Cloud during DND.

08. ⚡ Voltage Security Engine

Operating Window: 170V - 250V. The ZMPT sensor samples RMS voltage continuously. If outside the range, the motor cuts off in < 100ms. A 10-second wait is required after power stabilization before the motor restarts.

09. 🌊 Dry-Run & Auto-Retry

1. Dry-Run Safety & Auto-Retry

When the motor starts, the system enters a 60-second Grace Period. If no flow is detected for > 60 seconds, the "DRY ALRM" is triggered and the motor is stopped.

Instead of staying off forever, the system enters a "LOCKED" state and initiates an Auto-Retry Countdown (30 or 60 mins). Once the timer hits zero, it will automatically attempt to restart the pump to see if water has returned to the city pipes.

2. Manual Toggle Override

The physical button on **GPIO 9** provides industrial **Manual Toggle Control**. A single press allows you to start or stop the pump manually at any time, bypassing automatic level thresholds while maintaining safety protections.

10. ❄️ Thermal Cool-Down Protection

If the motor runs continuously for 1 Hour without stopping, the system will force a thermal cut-off and enter "PUMP REST" mode for 5 to 15 minutes (configurable). Once cooled down, it will automatically resume pumping if the tank is not yet full.

11. 💨 Compressor Mode Logic

In this mode, the Solenoid Valve executes Head-Pressure Venting. The Valve opens for 5s - 15s (selectable) before the motor starts (Pre-Vent) and after it stops (Post-Vent).

12. 📏 Calibration & Tuning

The system supports tanks from 1.0 ft to 7.0 ft height. When configuring, set the exact distance from the **sensor face** to the **tank bottom**. The system calculates a 6-inch buffer automatically.

13. 🏠 Wi-Fi & Offline Fallback

1. Local Network Access

Once connected to your home router, you can access the dashboard from any smartphone on the **same Wi-Fi network**. Use the **Device IP Address** shown on the Control Page (Dashboard).

2. True Offline Fallback (No Internet Needed)

If your home router loses internet connection, the system will not freeze or reboot. It will silently broadcast the Auto-Pump-Config network. You can connect your phone to this network and control your pump locally while the internet is down. Once your internet is fixed, the system automatically hides this network and reconnects to the Cloud.

14. ☁️ MQTT Cloud API

Bridge: HiveMQ Enterprise Cloud. Topic Format: smartpump/[DEVICE_ID]/status. All commands require your unique **6-Digit PIN** (Default: 123456) for secure validation.

15. 🔑 License & Subscriptions

If your license expires, the Cloud Control Web Page will be inaccessible for remote use. However, Automatic Features and Local Web Access (via smartpump.local) remain 100% active.

16. 🛠️ Troubleshooting Matrix

LCD Error	Indicator	Root Cause & Manual Solution
SNR ERR	Red Flash	Sensor Failure: Eye is dirty, wiring is loose, or tank is deeper than 7ft. Clean the sensor eye and reset.
FLOW CHK	Amber ON	Priming Issue: Motor is on but water is not reaching the sensor. Check for source emptiness. Reset via button.
OVER / UNDER	Red Flash	Grid Volatility: Voltage is outside 170V-250V. System will auto-reset in 10s after stabilization.
NO WIFI	Blue Pulse	Network Loss: Router is off or password changed. Re-configure via Auto-Pump-Config AP.
WAITING	Cyan Solid	Cloud Link: Local WiFi is OK, but HiveMQ Cloud is unreachable. Check internet connection.
DRY ALRM	Red Flash	Safety Lock: Dry-run detected for >60s. **Must press physical Button (GPIO 9)** to acknowledge and reset.

17. 🔩 Technical Specifications

18. ❓ Frequently Asked Questions