ESP32-S3 Security Cam

Firmware for a small, local-first security-camera prototype built with the Seeed Studio XIAO ESP32S3 Sense, its OV2640 camera, and a microSD card. It captures short MJPEG recordings and uploads them to a local MQTT broker.

Prototype status. This is working experimental firmware, not a finished security product. It has no authentication UI, OTA update path, NTP setup, encryption configuration, or motion-triggered recording enabled. Keep the camera and broker on a trusted local network.

The current firmware has been used successfully on Windows with the XIAO ESP32S3 Sense. Its public release is being organized and documented; it has not been independently rebuilt or hardware-verified in this repository's CI yet.

What it does

• Captures 15-second VGA/JPEG recordings at a target of 15 fps.
• Writes the concatenated JPEG frames as .mjpeg files to the microSD card.
• Keeps recordings for 30 days, based on the device clock.
• Uploads a finished file to MQTT in 4 KiB binary messages when the SD writer is idle, followed by a JSON completion message.

The current trigger is a timer: a recording begins every 60 seconds. PIR motion-sensor support is present only as commented-out scaffolding.

Current state and roadmap

Read project status and roadmap for the exact prototype state, known limitations, and prioritized remaining work. See the architecture overview for the task pipeline, responsibilities, and library list.

Documentation

• Hardware reference and pin mapping
• Software architecture and dependencies
• MQTT upload protocol
• Current state and roadmap
• Datasheets and schematics

Hardware

• Seeed Studio XIAO ESP32S3 Sense with its camera/sense expansion board
• OV2640 camera (included with the Sense kit)
• FAT32-formatted microSD card
• USB-C data cable
• 2.4 GHz Wi-Fi network and a reachable local MQTT broker

See the hardware reference for the exact camera and SD pin mappings.

Requirements

• ESP-IDF v5.5.1 (the project is constrained to the 5.5 release line)
• Python and the ESP-IDF tools installed by Espressif's installer
• A serial port accessible to your user account

The devcontainer is an optional containerized ESP-IDF 5.5.1 environment.

Build and flash

1. Install ESP-IDF v5.5.1 using the official getting-started guide. In each shell, load its environment, for example:

   . "$IDF_PATH/export.sh"

2. Clone this repository and enter it.

   git clone https://github.com/YOUR_GITHUB_USER/esp32-s3-security-cam.git
   cd esp32-s3-security-cam

3. Select the chip and configure your private network values. sdkconfig is intentionally ignored, so this keeps secrets out of Git.

   idf.py set-target esp32s3
   idf.py menuconfig

   Open Security camera configuration and set at least:

   • Wi-Fi SSID and password
   • MQTT broker URI, such as mqtt://192.168.1.10:1883
   • MQTT username/password when your broker requires them

   DHCP is the default. Enable Use a static IPv4 address only when your network requires it, then set the IP, gateway, netmask, and DNS values.

4. Build, flash, and monitor. Replace the example port with your device.

   idf.py build
   idf.py -p /dev/ttyACM0 flash monitor

   On Windows, the port is normally COMx; on macOS it is commonly /dev/cu.usbmodem*. Exit the monitor with Ctrl-].

The first build downloads the pinned espressif/esp32-camera component into managed_components/. That generated directory is not committed.

MQTT protocol

Each recording is published as ordered 4 KiB binary chunks to camera/frames by default. The final QoS 1 message on camera/upload_complete is JSON:

{"filename":"YYYY-MM-DD-HHMMSS-capture.mjpeg","size":123456,"timestamp":0}

Consumers must subscribe to both topics, preserve the received chunk order, and use the completion message as the end-of-file marker. See the MQTT protocol notes before integrating a receiver.

Verification checklist

After flashing, check the serial monitor for:

• [init] PSRAM found
• a successful SD-card mount
• Wi-Fi connection and [wifi] MQTT connected
• [sd] File complete after a recording
• [mqtt] Upload complete after the SD writer drains

Known limitations

• The device does not currently synchronize time, so filenames and retention may be incorrect after boot until SNTP support is added.
• SD write and Wi-Fi throughput can cause dropped frames. The included settings are tuned for the XIAO's SPI SD interface but need real hardware validation for each card and network.
• MQTT traffic is unencrypted with a normal mqtt:// URI. Do not use this firmware across the public internet or with sensitive video until TLS and certificate provisioning are implemented.
• Recordings remain on the microSD card after upload.

Project layout

main/                 Application firmware and project Kconfig options
docs/                 Hardware, MQTT, architecture, and project-status notes
sdkconfig.defaults    Non-secret defaults for the XIAO ESP32S3 Sense
idf_component.yml     Pinned ESP-IDF component dependencies

License

This project is released under the MIT License. The camera driver is obtained separately from Espressif through the Component Manager and is licensed by its upstream project.