# smart_enclosure_firmware

**Repository Path**: seaoftranquility/smart_enclosure_firmware

## Basic Information

- **Project Name**: smart_enclosure_firmware
- **Description**: Smart regulator firmware, based off ESP32 S3 CAM model GOOUU board, with peripherals, components and drivers. streams live video over the internet to client side miniprogram via server.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Firmware — Smart Enclosure Regulator

Arduino firmware for an GOOUUU ESP32-S3-CAM enclosure controller.

## Current status

Implemented:

- SoftAP captive-portal WiFi provisioning and NVS persistence
- saved-WiFi boot monitoring with automatic SoftAP fallback after 20 seconds
- non-destructive force-provision gesture on GPIO41 during boot
- permanent private device credential plus rotating five-minute pairing OTP
- TLS MQTT client on port 8883 with per-device authentication
- DHT11, DS18B20, and HSS20P sensor drivers
- active-low relays, visible LED PWM, RGB strip, and fan PWM drivers
- GPIO42 addressable RGB ring; GPIO48 is intentionally unused
- telemetry, status/LWT, command handling, pairing-complete, and unbind handling
- explicit manual mode plus firmware-timed mister/fan overrides with telemetry countdowns
- validated raw config-topic setpoints applied in RAM
- OV5640 JPEG capture with authenticated server upload and viewer leases
- PID utility and a safety-disabled automatic-regulation reference

Not complete:

- automatic outputs are intentionally disabled pending real hardware validation
- config values are not yet persisted to NVS or acknowledged with a version
- the camera pin map still requires a physical frame-capture smoke test on the exact board revision

## Hardware target

- Board: GOOUUU ESP32-S3-CAM (Arduino target: ESP32S3 Dev Module)
- Camera: OV5640 through the board FPC connector
- Flash/PSRAM: N16R8 profile (16 MB flash, 8 MB OPI PSRAM)
- Serial: 115200 baud

See [hardware README](../hardware/README.md) for the pin map and safety requirements.

## Secure MQTT setup

Before flashing a device that must connect to production:

1. Deploy the server and download its public `ca.crt` and `server.crt`.
2. Run `python firmware/tools/import_mqtt_ca.py --ca ca.crt --server-cert server.crt --broker <host>` from the repository root. The tool verifies the chain and IP/DNS identity before updating `code/include/config.h`.
3. Compile and flash the firmware, then compare the serial `固件信任 CA SHA-256` line with the deployment fingerprint.
4. Keep `MQTT_PORT` at 8883.

Firmware refuses MQTT connections when the CA is empty. Do not replace verification with `setInsecure()`.
The firmware synchronizes its clock before attempting TLS. It retries regional SNTP servers and falls back to the server's plaintext development `/api/time` endpoint when mobile networks block UDP/123; certificate validation cannot work with the ESP32's post-boot epoch time. The fallback uses the configured server IPv4 address, so it does not depend on hotspot DNS. STA auto-reconnect is enabled and Wi-Fi power saving is disabled to avoid camera/WebSocket stalls on phone hotspots and cellular routers.

Supported access points include iPhone and Android hotspots, 4G/5G modem routers, and ordinary home/office routers when they provide 2.4 GHz Wi-Fi, DHCP, and outbound IPv4 access. ESP32-S3 does not support 5 GHz Wi-Fi. Configure hotspots for 2.4 GHz (or iPhone "Maximize Compatibility") and WPA2/WPA2-WPA3 mixed mode. Captive-login, WPA-Enterprise, IPv6-only without NAT64/CLAT, and networks blocking the configured MQTT port require additional network or server-side support.

## Pairing

The device stores two distinct values:

- a private 32-hex credential for MQTT/device authentication
- a visible `XXXX-XXXX` OTP for user binding

Each server OTP is valid for five minutes; firmware rotates it 30 seconds early to avoid an expired-code gap and updates the open portal live. Factory reset clears WiFi, the OTP, settings, and calibration while preserving the private device identity. Account ownership is changed only by the authenticated unbind workflow, preventing a reset device from being orphaned by a new secret.

## SoftAP boot behavior

Flashing normally preserves ESP32 NVS. If saved WiFi still works, firmware reconnects without opening the portal. If saved WiFi cannot connect for 20 seconds, firmware automatically opens `SmartReg-XXXX` while keeping the old credentials so they can be corrected.

To open provisioning on demand, connect GPIO41 to GND before power-on, release it after roughly one second and before three seconds, then connect to `SmartReg-XXXX` with password `12345678`. Holding GPIO41 for three seconds performs a local factory reset instead. Android, iOS, and Windows probe paths serve the portal directly; if an OS suppresses its captive assistant, browse to `http://192.168.4.1/`. The phone must support/connect to 2.4 GHz WiFi.

## Automatic control

`src/control_loop.cpp` contains a reference controller for heating, humidity, lighting, UVB limits, and ventilation. Its call remains commented out and auto mode forces outputs off.

Only enable it after low-voltage dummy-load tests, an independent thermal cutoff, low-water protection, and non-living enclosure trials.

## Client control

- Full manual mode accepts direct top-level actuator fields only after `set_mode` selects `manual`.
- Bounded overrides work in either mode: mister 1-10 seconds and fan 1-120 seconds.
- Firmware owns expiry; mister also enforces a 30-second cooldown.
- Manual writes to the same actuator cancel its active timed override.
- Auto regulation remains commented out; bounded overrides do not enable the automatic controller.

## Build

Required libraries:

- DHT sensor library
- OneWire
- DallasTemperature
- FastLED
- PubSubClient
- WebSockets (Links2004, provides `WebSocketsClient.h`)

Install the WebSockets dependency before compiling:

```powershell
arduino-cli lib install WebSockets
```

Compile:

```powershell
arduino-cli compile --fqbn esp32:esp32:esp32s3 `
  --board-options FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,PSRAM=opi,USBMode=hwcdc,CDCOnBoot=cdc `
  --warnings all firmware\code
```

The camera-enabled build requires more than the default 1.2 MB application partition. Hardware CDC with CDC-on-boot is required for native-USB serial diagnostics. The validated N16R8 build uses about 42% of the 3 MB application partition and 19% RAM.

## LLM guide

See [firmware/.ai/README.md](.ai/README.md) and the root [.ai knowledge base](../.ai/README.md).