Camera Settings Control writes out-of-range values on the new K1 camera hardware, producing a black

[vshortt73]

Camera Settings Control writes out-of-range values on the new K1 camera hardware, producing a black image
Summary

Camera Settings Control hardcodes control values on a generic UVC scale (brightness −64…64, contrast 0…64). The camera in current K1 hardware reports a different range — min=50, max=160 — so every "neutral" value the startup block sends falls below the minimum and is clamped by the driver to the floor.

The result is minimum brightness, minimum contrast, and hue shifted well off neutral: a near-black image in Fluidd, Mainsail and Creality Print alike.

Environment
Printer: Creality K1 Max
Firmware:
Camera: CCX2F3299, firmware 250422, /dev/video4, 1280x720 @ 15 fps
Helper Script: Camera Settings Control installed
Symptom

Stream works. Frames are live and updating (?action=snapshot returns changing JPEGs). The picture is almost entirely black regardless of chamber lighting, and shining a light directly into the lens barely registers.

Root cause

v4l2-ctl -d /dev/video4 -l on this hardware reports only five controls, with these ranges:

brightness : min=50 max=160 step=1 value=50
contrast : min=50 max=160 step=1 value=50
saturation : min=50 max=160 step=1 value=56
hue : min=50 max=160 step=1 value=50
white_balance_temperature_auto (bool) : value=1

The LOAD_CAM_SETTINGS block in camera-settings.cfg sends:

CAM_BRIGHTNESS BRIGHTNESS=0 # below min=50 -> clamped to 50
CAM_CONTRAST CONTRAST=32 # below min=50 -> clamped to 50
CAM_HUE HUE=0 # below min=50 -> clamped to 50
CAM_SATURATION SATURATION=56 # in range, applied

Three of the four land at the bottom of their range. Because this runs from a delayed_gcode with initial_duration: 2, it is reapplied at every Klipper start, so the camera is darkened on every boot.

Secondary issue: macros for controls that don't exist

These target controls the hardware does not expose, and are silent no-ops:

gain, gamma, exposure_auto, exposure_auto_priority, sharpness, backlight_compensation, power_line_frequency

The description: fields on those macros advertise ranges that don't apply, which sends anyone troubleshooting a dark image chasing exposure and gain settings that aren't there.

Reproduction
Install Camera Settings Control on a K1 with the new camera hardware
Restart Klipper so LOAD_CAM_SETTINGS fires
Open the stream — image is black
Run CAM_SETTINGS and observe brightness and contrast sitting at 50, their minimum
Suggested fix

Query the device rather than assuming a scale. At install time, or in the macros themselves:

sh
v4l2-ctl -d /dev/video4 -l

Then either:

Generate LOAD_CAM_SETTINGS from the reported min/max, defaulting each control to its midpoint, or
Clamp submitted values into the reported range before applying, or
At minimum, skip controls absent from v4l2-ctl -l and correct the description: strings so they reflect the hardware actually present

Option one seems most robust, since it also keeps working if Creality changes the ranges again.

Workaround for affected users

Check your own ranges first — they may differ by model:

CAM_SETTINGS

Then edit /usr/data/printer_data/config/Helper-Script/camera-settings.cfg:

ini
[delayed_gcode LOAD_CAM_SETTINGS]
initial_duration: 2
gcode:
CAM_BRIGHTNESS BRIGHTNESS=105
CAM_CONTRAST CONTRAST=105
CAM_SATURATION SATURATION=105
CAM_HUE HUE=105
CAM_WHITE_BALANCE_TEMPERATURE_AUTO WHITE_BALANCE_TEMPERATURE_AUTO=1

105 is the midpoint of 50–160. If the settings don't survive a reboot, cam_app is still initialising and overwriting them — raise initial_duration to 30.

Related

Users on firmware 1.3.5.22 need the S59mjpg_streamer workaround to get any stream at all (the firmware ships no such service, and input_uvc.so no longer works — input_memfd.so is required). At least one user in that thread reported the black-image symptom after applying it and received no answer:

https://forum.creality.com/t/solved-k1c-firmware-1-3-5-22-internal-camera-working-again-in-mainsail-fluidd/52668

Thanks for maintaining this — the Helper Script is the only reason these machines are usable.

[nerdoc]

Possibly related to the same hardware revision: files/services/S50usb_camera-single
guards against Creality cameras with

CREALITY_CAMS=$(v4l2-ctl --list-devices | grep -E 'CREALITY|CCX2F3298' | wc -l)

My internal camera reports as CCX2F3299, so it slips past that filter. I haven't
tested what it breaks in practice, but the guard clearly predates this revision.