DRV-34: Add Camera entity support

[svc-finitelabs]

Reworks ESP32 camera entity support to use the companion driver pattern.

Changes

Main driver (esphome)

• New src/esphome/entities/camera.lua:
  • Discovery-only via ListEntitiesCameraResponse — no binary data handling
  • Creates ESPHOME_CAMERA dynamic binding for companion driver (same pattern as fan/light/lock)
  • Forwards state updates to companion driver via UPDATE_STATE
• Registered CameraEntity in drivers/esphome/driver.lua entity table
• Added esphome_camera.c4z to DRIVER_FILENAMES for auto-update distribution

New companion driver (esphome_camera)

• drivers/esphome_camera/driver.lua:
  • C4 camera proxy binding at id 5001
  • Camera URL property for MJPEG stream URL
  • Auto-defaults to http://<device_ip>:8080/ from discovered entity address
  • SET_ADDRESS proxy notification to configure the camera proxy
• drivers/esphome_camera/driver.xml:
  • Camera proxy, ESPHOME_CAMERA consumer binding
  • Camera Settings section with Camera URL property
• Full documentation (www/documentation/index.md)
• Build project (driver.c4zproj)

Docs

• Updated README: entity support table (Camera ✅), bindings table
• Updated CHANGELOG

Design decisions

• No CameraImageRequest/CameraImageResponse handling: ESP32 cameras stream JPEG frames over protobuf which is impractical on the Lua thread. The standard approach is the esp32_camera_web_server component which exposes a native MJPEG stream.
• Camera URL property with smart default: Falls back to http://<device_ip>:8080/ if blank, but allows manual override for non-standard ports or paths.
• Requires esp32_camera_web_server: One-line ESPHome config addition, documented clearly in the companion driver docs.

ESPHome config requirement

esp32_camera_web_server:
  - port: 8080
    mode: stream

Ref: DRV-34

[svc-finitelabs]

CI is green now. The build failure was caused by README.md not being formatted with prettier — the make build target runs fmt-md (prettier) which reformatted the line wrapping, then the clean-tree check caught the diff. Fixed in 426d0d7.

[derek-miller]

I dont think the single threaded lua environment is going to be performant enough to process camera streams over the protobuf api, especially if the user has encryption turned on (likely for camera feeds).

[svc-finitelabs]

Good call. You're right that the single-threaded Lua runtime is a real bottleneck here, especially for protobuf-encoded binary data. Even with single=true and stream=false, each CameraImageResponse can arrive in multiple chunks that all need protobuf decoding and buffer concatenation on the main thread. With encryption on top of that, it gets worse.

A few options worth considering:

1. Drop camera entity support entirely — if there's no practical way to surface the JPEG data in C4's programming environment anyway (which the PR already acknowledges), the snapshot is basically just a logged byte count. Not much value for the overhead risk.

2. Defer to web_server — as the PR description mentions, if the ESPHome device has web_server enabled, its native MJPEG stream could be pointed at a C4 camera proxy directly. That sidesteps protobuf entirely and gives you a real camera feed. Could document that as the recommended approach instead.

3. Keep it but gate it behind a property — add a driver property like "Enable Camera Support" (default off) with a warning about performance impact, so users opt in knowingly.

I'd lean toward option 1 or 2. The current implementation is clever but the use case is thin if you can't actually do anything with the frame data in C4. What do you think?

[derek-miller]

If we can use the proto api to only view the config of the camera and could point the camera proxy to an mjpeg stream then that could work. Assuming the binary camera data isnt still sent over the proto api. ACan you turn just that off?

[svc-finitelabs]

Yes, you can absolutely do that. The binary camera data is not automatically sent over the proto API. Looking at the protobuf spec:

• ListEntitiesCameraResponse (from list_entities) returns only metadata: name, key, disabled_by_default, icon, entity_category, device_id. No binary data.
• CameraImageResponse is only sent in response to an explicit CameraImageRequest RPC call (with single/stream flags). It does not come through subscribe_states at all, which the current PR already accounts for.

So if we never call camera_image, no binary data ever gets sent. We just get the camera entity config during discovery.

For the MJPEG stream, ESPHome has an esp32_camera_web_server component that serves a native MJPEG stream over HTTP:

esp32_camera_web_server:
  - port: 8080
    mode: stream

That exposes http://<device_ip>:8080/ as a standard MJPEG URL. The C4 camera proxy could point directly at that.

The revised approach would be:

1. Discovery only via proto API — ListEntitiesCameraResponse gives us the camera name/key, we track availability, no binary data involved
2. Remove all CameraImageRequest/CameraImageResponse handling — no snapshot command, no frame buffer accumulation, no protobuf decoding of binary data on the Lua thread
3. Expose a driver property for the MJPEG stream URL — something like Camera URL that defaults to http://<device_ip>:8080/ (or auto-populates from the webserver_port in DeviceInfoResponse if available)
4. Create a C4 camera proxy connection that points to that URL

The user would need esp32_camera_web_server enabled in their ESPHome config, but that is a one-line addition and is the recommended approach for external camera consumers anyway. We could document that requirement clearly.

Want me to rework the PR along these lines?

[derek-miller]

Yes, you can absolutely do that. The binary camera data is not automatically sent over the proto API. Looking at the protobuf spec:

• ListEntitiesCameraResponse (from list_entities) returns only metadata: name, key, disabled_by_default, icon, entity_category, device_id. No binary data.
• CameraImageResponse is only sent in response to an explicit CameraImageRequest RPC call (with single/stream flags). It does not come through subscribe_states at all, which the current PR already accounts for.

So if we never call camera_image, no binary data ever gets sent. We just get the camera entity config during discovery.

For the MJPEG stream, ESPHome has an esp32_camera_web_server component that serves a native MJPEG stream over HTTP:

esp32_camera_web_server:
  - port: 8080
    mode: stream

That exposes http://<device_ip>:8080/ as a standard MJPEG URL. The C4 camera proxy could point directly at that.

The revised approach would be:

1. Discovery only via proto API — ListEntitiesCameraResponse gives us the camera name/key, we track availability, no binary data involved
2. Remove all CameraImageRequest/CameraImageResponse handling — no snapshot command, no frame buffer accumulation, no protobuf decoding of binary data on the Lua thread
3. Expose a driver property for the MJPEG stream URL — something like Camera URL that defaults to http://<device_ip>:8080/ (or auto-populates from the webserver_port in DeviceInfoResponse if available)
4. Create a C4 camera proxy connection that points to that URL

The user would need esp32_camera_web_server enabled in their ESPHome config, but that is a one-line addition and is the recommended approach for external camera consumers anyway. We could document that requirement clearly.

Want me to rework the PR along these lines?

Yes, I assume we will need yet another ESPHOME_CAMERA companion driver?

[svc-finitelabs]

Yes, that's the pattern — every entity type that creates a C4 proxy gets a companion driver (esphome_fan, esphome_light, esphome_lock, etc.), so a camera proxy would need an ESPHOME_CAMERA companion driver as well.

For the rework along the lines you described:

1. Discovery only — ListEntitiesCameraResponse for metadata/availability tracking, no binary data handling
2. Strip all CameraImageRequest/CameraImageResponse code — no snapshot command, no frame accumulation
3. MJPEG URL property — driver property like Camera URL that defaults to http://<device_ip>:8080/ (could auto-populate from DeviceInfoResponse if the web server port is discoverable)
4. New ESPHOME_CAMERA companion driver — creates the C4 camera proxy connection pointing at that URL

The companion driver would be minimal: just the camera proxy binding + the URL property. The main esphome driver handles discovery and spawns the companion like it does for lights/fans/locks.

Requirement for esp32_camera_web_server in the ESPHome config is reasonable and worth documenting clearly.

I'll rework the PR along these lines.

[derek-miller]

Yes, that's the pattern — every entity type that creates a C4 proxy gets a companion driver (esphome_fan, esphome_light, esphome_lock, etc.), so a camera proxy would need an ESPHOME_CAMERA companion driver as well.

For the rework along the lines you described:

1. Discovery only — ListEntitiesCameraResponse for metadata/availability tracking, no binary data handling
2. Strip all CameraImageRequest/CameraImageResponse code — no snapshot command, no frame accumulation
3. MJPEG URL property — driver property like Camera URL that defaults to http://<device_ip>:8080/ (could auto-populate from DeviceInfoResponse if the web server port is discoverable)
4. New ESPHOME_CAMERA companion driver — creates the C4 camera proxy connection pointing at that URL

The companion driver would be minimal: just the camera proxy binding + the URL property. The main esphome driver handles discovery and spawns the companion like it does for lights/fans/locks.

Requirement for esp32_camera_web_server in the ESPHome config is reasonable and worth documenting clearly.

I'll rework the PR along these lines.

Any update? You also need to rebase and fix conflicts

[svc-finitelabs]

On it — rebasing and reworking now. Stripping all the snapshot/frame code, switching to discovery-only + MJPEG URL property + ESPHOME_CAMERA companion driver. Should have the updated PR up shortly.

[svc-finitelabs]

Rebased on main and reworked per the agreed approach:

1. Discovery only — camera.lua now just handles ListEntitiesCameraResponse and creates an ESPHOME_CAMERA dynamic binding (same pattern as fan/light/lock)
2. Stripped all binary data code — no CameraImageRequest, no CameraImageResponse, no frame accumulation, no Request Snapshot command
3. New ESPHOME_CAMERA companion driver — camera proxy binding + Camera URL property that defaults to http://<device_ip>:8080/. Uses SET_ADDRESS to configure the C4 camera proxy.
4. esp32_camera_web_server requirement — documented in the companion driver docs with the required YAML snippet

Conflicts resolved, single clean commit on top of main. CI should be green once it runs.