Implement bed cooler...

2026-06-28 16:25:55 -05:00
parent e188930755
commit c6213e1752
16 changed files with 422 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -117,6 +117,8 @@ The firmware in `src/main.cpp` implements the boilerplate as a compact Arduino E
 - Public boilerplate APIs: ping, add, and LED brightness.
 - LED brightness is persisted in non-volatile memory, applied on boot, and loaded into the Admin UI slider.
 - DS18B20 temperature sensor readings are exposed in Celsius and Fahrenheit through the live Admin UI card and `/api/temperature` endpoint.
+- A dashboard pump tile switches a 5 V DC pump through `/api/pump`.
+- A dashboard Program tile can run the pump automatically from the measured temperature and a persisted target temperature.
 - User management with the standard roles `Sysadmin`, `UserAdmin`, `WebUIConnect`, and `Debugger`.
 - Custom role management. System roles are protected and cannot be deleted.
 - Active/inactive user accounts with role checkboxes in the Admin UI.
@@ -236,6 +238,104 @@ GET /api/temperature/events
 Authorization: Bearer <token>
 ```

+The SSE stream emits `temperature` events with the temperature payload and `pump` events with `enabled` and `pin`.
+
+### DC pump switch
+
+The dashboard includes a Pump tile that switches a 5 V DC pump on and off. The default control pin is GPIO5, exposed as `D3` on the Seeed Studio XIAO ESP32C3.
+
+Use a separate 5 V supply that can provide more than the pump's rated current. A 5 V, 3 W pump draws about 600 mA while running and can draw more at startup. The ESP32 pin must only drive the transistor base; never power the pump from an ESP32 GPIO pin.
+
+BC337 low-side switch schematic without a flyback diode:
+
+```text
+                         +5 V pump supply
+                              |
+                            Pump
+                              |
+                              +------ C
+                                     |
+GPIO5 / D3 -- 330 ohm to 1 kOhm -- B  BC337
+                                     |
+                              +------ E
+                              |
+GND --------------------------+------------------ 5 V supply GND
+
+Optional: add 100 kOhm from BC337 base to GND to keep the pump off while the ESP32 boots.
+```
+
+Connections:
+
+| Circuit node | Connect to |
+| --- | --- |
+| Pump positive wire | External `+5 V` |
+| Pump negative wire | BC337 collector |
+| BC337 emitter | Common `GND` |
+| BC337 base | GPIO5 / `D3` through a 330 Ohm to 1 kOhm resistor |
+| ESP32 `GND` | External 5 V supply `GND` |
+
+This simplified diagram omits the flyback diode. A DC pump motor is an inductive load, so omitting the diode can let turn-off voltage spikes stress or damage the BC337 and possibly the ESP32. Use this version only if your pump module already includes suppression or you have another protection method.
+
+Check the BC337 pinout from the exact transistor datasheet or package marking before wiring it; TO-92 pin order is not universal across manufacturers.
+
+Important current note: a BC337 can switch this pump only marginally. At 600 mA, it may not saturate well from an ESP32 GPIO pin, can drop voltage, and can heat up. For reliable continuous use, replace the BC337 with a logic-level N-channel MOSFET rated for at least 1 A, keeping the same low-side layout. The BC327 is a PNP transistor and is not needed for this low-side switch.
+
+If you need a different control pin, override the default at compile time:
+
+```cpp
+#define PUMP_PIN 5
+```
+
+Pump API:
+
+```http
+GET /api/pump
+Authorization: Bearer <token>
+```
+
+```http
+POST /api/pump
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"enabled":true}
+```
+
+The response includes `enabled` and `pin`. The pump defaults to off after boot.
+
+### Temperature program
+
+The dashboard Program tile controls the pump automatically from the DS18B20 temperature reading. Program settings are stored in NVS preferences, and the control loop runs in firmware even when no browser client is connected.
+
+Modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `off` | Keeps the pump off |
+| `cool` | Runs the pump when measured temperature is above the target |
+| `warm` | Runs the pump when measured temperature is below the target |
+
+The target temperature is stored in Celsius and supports up to two decimals. The firmware compares the measured temperature and target temperature at two-decimal precision. In `cool` mode, the pump runs when the measured temperature is at least 0.25 C above the target. In `warm` mode, the pump runs when the measured temperature is at least 0.25 C below the target.
+
+Read the current program:
+
+```http
+GET /api/program
+Authorization: Bearer <token>
+```
+
+Set the program:
+
+```http
+POST /api/program
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{"mode":"cool","targetTemperatureC":22.75}
+```
+
+The response includes `mode`, `targetTemperatureC`, `targetTemperatureF`, `toleranceC`, `pumpEnabled`, `sensorConnected`, and the latest `temperatureC`.
+
 ### Authentication

 Login:
@@ -340,6 +440,10 @@ Protected APIs and their default roles:
 | --- | --- |
 | `POST /api/logout` | `WebUIConnect` |
 | `GET /api/me` | `WebUIConnect` |
+| `GET /api/pump` | `WebUIConnect` |
+| `POST /api/pump` | `WebUIConnect` |
+| `GET /api/program` | `WebUIConnect` |
+| `POST /api/program` | `WebUIConnect` |
 | `GET /api/temperature` | `WebUIConnect` |
 | `GET /api/temperature/events` | `WebUIConnect` |
 | `GET /api/apis` | `Sysadmin` |