ESP32-32S-OV3660-cam

Part of CommandAGI: connecting agents to real computers, robots and physical environments. This repository can be cloned independently of the private platform code.

git clone https://github.com/CommandAGI/commandagi-firmware-ESP32-32S-OV3660-cam.git
cd commandagi-firmware-ESP32-32S-OV3660-cam

Hardware status

The repository name identifies the requested hardware target. The checked-in PlatformIO default currently uses the AI-Thinker esp32cam board with OV2640 wiring; an ESP32-32S/OV3660 build has not been verified in this cleanup. Review platformio.ini and src/config.h against your exact board before flashing.

Turn a ~$6 AI-Thinker ESP32-CAM into a camera that streams into your CommandAGI dashboard. You pair it from the CommandAGI mobile app over Bluetooth — no hardcoded Wi-Fi, no re-flashing to change networks, no cloud account baked into the binary.

power on ──► advertises over BLE ──► app finds it ("My cameras → Pair")
        ──► app sends Wi-Fi creds + a per-device account key over BLE
        ──► camera joins Wi-Fi, registers a machine session under your account
        ──► streams sealed JPEG frames ──► shows up live in the dashboard

It remembers everything in flash (NVS), so after a power cycle it reconnects and resumes streaming on its own. See the hardware notes for the board and security design.

Hardware

• AI-Thinker ESP32-CAM (ESP32 + OV2640, 4 MB flash, PSRAM) — the default.
• CommandAGI-Cam-001 (-DCAM_BOARD_CAGI_CAM001): an ESP32-S3-WROOM-1-N8R2 and an M5Stack Stamp-AddOn Cam3660 (OV3660) on one base board, flashed over its USB-C (native USB). Its env is in hardware/CommandAGI-Cam-001/firmware/platformio.ini of CommandAGI.
• A USB-UART adapter (FTDI/CP2102) for the first flash, or an ESP32-CAM-MB programmer board.
• Other boards (e.g. ESP32-S3 cams) work by editing the pin map in src/config.h and adding -DCAM_BOARD_ESP32S3 to build_flags.
• Every build signs its own frames with a key made on the device (§ Sealed stream). It is the camera's only frame path.

Flashing

Uses PlatformIO. The AI-Thinker board has no auto-reset, so for the first flash tie GPIO0 → GND, power-cycle, then upload; remove the jumper and reset to run.

cd .
pio run                 # build
pio run -t upload       # flash over USB-UART
pio device monitor      # watch the serial log (115200 baud)

Re-flashable forever. This firmware deliberately does not enable Secure Boot or Flash Encryption, and never burns the download-disable eFuse. The partition table keeps two OTA app slots (partitions.csv) so you can always re-flash over USB and push OTA updates later. A factory-reset wipes only the stored credentials (the cagi NVS namespace), never the app.

The one exception is deliberate and is not in this repository: CommandAGI-Cam-002's production envs (CommandAGI's hardware/CommandAGI-Cam-002/firmware) lock a unit for good at the factory, so that its sealing key cannot be copied (§ Sealed stream). A locked unit is not covered by this guarantee. Every env here stays open.

Why it can ALWAYS be re-flashed (the guarantee)

The ESP32's serial download mode lives in mask ROM and runs before the application on every reset where GPIO0 is held low — so no firmware can ever block re-flashing. The only thing that can permanently lock a board is burning an eFuse (Secure Boot, Flash Encryption, or the download-disable bit), and this firmware does none of that:

• No eFuse is written anywhere in src/. The only esp_efuse_*, esp_secure_boot_* and esp_flash_encrypt* calls are reads in src/chip_lock.cpp (esp_efuse_read_field_bit(), esp_secure_boot_enabled(), esp_flash_encryption_enabled(), esp_get_flash_encryption_mode()): a sealing build reports them in its seals; they change nothing.
• No Secure Boot / Flash Encryption build flags — platformio.ini produces a plain, unencrypted image.
• The partition table's Flags column is empty (no encrypted partitions).
• factory-reset calls Preferences.clear() on just the cagi NVS namespace — never nvs_flash_erase() or a partition wipe, and never the app.

Recovery (even a "bricked" board): tie GPIO0 → GND, press reset (or power-cycle), and run pio run -t upload (or esptool.py write_flash). Because download mode is ROM-based, this works no matter what state the app is in — a boot loop, a bad OTA, or garbage in flash. Remove the jumper and reset to run again. esptool.py erase_flash then a fresh pio run -t upload is the full clean slate.

How pairing works (BLE GATT)

The device advertises service c0a1d61c-0001-… as "CommandAGI Cam XXXX" (XXXX = MAC suffix). The contract is shared with the apps in packages/domain/core/src/esp32cam.ts (platform-internal reference) — keep the UUIDs in src/config.h in sync with it.

Characteristic	UUID suffix	Props	Payload
INFO	…0002	read	{ kind, model, fw, hwid, name, provisioned, mic, spk?, secure, salt?, sealKey? }
STATUS	…0003	read + notify	{ state, ip?, sessionId?, deviceId?, error?, link?, operator?, rssi?, rsrp?, battery?, ir? }
PROVISION	…0004	write	PIN-sealed { ssid, psk, apiBaseUrl, apiKey, deviceName?, apn?, simPin? } (see Security)
COMMAND	…0005	write	identify | reboot | factory-reset

This is the beginning of the README. Read the rest at the original. Read the full README ↗