In a PiKVM environment built on a Raspberry Pi 3 Model B, we introduced a CSI-connected camera module to externally monitor the server’s front LED indicators and physical operational status. For the video streaming daemon, we adopted the lightweight and low-latency ustreamer (service name: ustreamer-csi), configured to stream MJPEG via port 8081.<\/p>\n
During the initial setup, \/dev\/video0 was specified directly in the configuration file, and we confirmed that the video could be previewed smoothly via a web browser without any issues.<\/p>\n
However, after rebooting the system, checking uStreamer’s streaming status revealed that while the web server itself responded, the video stream had stopped.<\/p>\n
Upon checking the API endpoint (\/state), we found “online”: false and “captured_fps”: 0 as shown below, indicating that not a single frame was being acquired from the device.<\/p>\n
\n{\n"ok": true,\n"result": {\n"source": {\n"resolution": {\n"width": 640,\n"height": 480\n},\n"online": false,\n"desired_fps": 0,\n"captured_fps": 0\n},\n"stream": {\n"queued_fps": 0,\n"clients": 0\n}\n}\n}\n<\/pre>\nLogging in via SSH after every reboot to check the device number and manually reconfigure the service is not practical. We needed to implement a mechanism that would automatically and reliably recognize the camera device and resume streaming even after an OS reboot, without human intervention.<\/p>\n
Dynamic Allocation of \/dev\/video Numbers and Raspberry Pi-Specific Device Structures<\/h2>\n
To identify the cause of the issue, we checked the kernel logs.<\/p>\n
dmesg | grep video<\/pre>\nPart of the output was as follows:<\/p>\n
\nbcm2835-isp bcm2835-isp: Device node output[0] registered as \/dev\/video13\nbcm2835-codec bcm2835-codec: Device registered as \/dev\/video10\nbcm2835_v4l2-0: V4L2 device registered as video2 - stills mode > 1280x720\nbcm2835-codec bcm2835-codec: Device registered as \/dev\/video18\n<\/pre>\nDue to the kernel initialization order, the bcm2835-v4l2 device for the CSI camera was registered as \/dev\/video2. Because the service definition hardcoded \/dev\/video0, a mismatch occurred, causing the open operation to fail.<\/p>\n
The challenge here is the large number of V4L2 devices unique to the Raspberry Pi. Since the SoC’s internal hardware codec (bcm2835-codec) and Image Signal Processor (bcm2835-isp) generate numerous nodes (video10 to video23, etc.), simply specifying an “available video node” cannot accurately pinpoint the correct camera device.<\/p>\n
Also, it is important to note that conditions like ATTR{name}==”mmal service 16.1″ found in older documentation do not match current environments, and on actual hardware, it is identified as camera0.<\/p>\n
Generating a Fixed Symbolic Link (\/dev\/csi-camera) via udev Rules<\/h2>\n
Rather than trying to fix the device number itself, we use udev rules to automatically generate a unique symbolic link, \/dev\/csi-camera, that always points to the CSI camera.<\/p>\n
Checking Actual Device Attributes<\/h3>\n
First, we extracted attributes available for udev conditions from the device currently recognized as the camera.<\/p>\n
udevadm info --attribute-walk --name=\/dev\/video2<\/pre>\nThe key attributes extracted were as follows:<\/p>\n
\nlooking at device '\/devices\/platform\/soc\/3f00b840.mailbox\/bcm2835-camera\/video4linux\/video2':\nKERNEL=="video2"\nSUBSYSTEM=="video4linux"\nATTR{index}"0"\nATTR{name}"camera0"\n\nlooking at parent device '\/devices\/platform\/soc\/3f00b840.mailbox\/bcm2835-camera':\nKERNELS=="bcm2835-camera"\nSUBSYSTEMS=="vchiq-bus"\nDRIVERS=="bcm2835-camera"\n<\/pre>\nTo avoid confusing it with other device nodes, we ensured uniqueness by combining ATTR{name}==”camera0″ with the parent device’s KERNELS==”bcm2835-camera” and DRIVERS==”bcm2835-camera”.<\/p>\n
Creating and Applying udev Rules<\/h3>\n
Make the PiKVM file system writable and create the rule file.<\/p>\n
rwnano \/etc\/udev\/rules.d\/99-csi-camera.rules<\/pre>\nWrite the following single line into the file \/etc\/udev\/rules.d\/99-csi-camera.rules.<\/p>\n
\nSUBSYSTEM=="video4linux", ATTR{name}"camera0", KERNELS"bcm2835-camera", DRIVERS=="bcm2835-camera", ATTR{index}=="0", SYMLINK+="csi-camera", TAG+="systemd", ENV{SYSTEMD_ALIAS}="\/dev\/csi-camera"\n<\/pre>\nBy adding TAG+=”systemd” and ENV{SYSTEMD_ALIAS}=”\/dev\/csi-camera”, the udev-generated link is recognized as a systemd device unit (dev-csi\\x2dcamera.device). After setting this up, reload the rules to apply them.<\/p>\n
\nudevadm control --reload-rules\nudevadm trigger --subsystem-match=video4linux\nudevadm settle\nro\n<\/pre>\nVerifying the Symbolic Link<\/h3>\n
Check if the link is generated normally.<\/p>\n
\nls -l \/dev\/csi-camera\nreadlink -f \/dev\/csi-camera\n<\/pre>\nIf it points to the actual device like \/dev\/csi-camera -> video2, it is successful.<\/p>\n
Configuring Stable Systemd Service Startup Using the Fixed Device<\/h2>\n
We utilize the generated \/dev\/csi-camera from the uStreamer service. In addition to simply changing the path, configuring systemd’s startup order control (waiting for the device) prevents races where the service starts up before the camera device is recognized and fails.<\/p>\n
Checking the Systemd Device Unit Name<\/h3>\n
Check the escaped device unit name handled by systemd.<\/p>\n
systemd-escape --path --suffix=device \/dev\/csi-camera<\/pre>\nOutput result:<\/p>\n
dev-csi\\x2dcamera.device<\/pre>\nUpdating the Service Definition Edit the service configuration file to specify the fixed path and add dependencies.<\/p>\n
rwnano \/etc\/systemd\/system\/ustreamer-csi.service<\/pre>\nThe contents of the configuration file \/etc\/systemd\/system\/ustreamer-csi.service are as follows:<\/p>\n
\n[Unit]\nDescription=uStreamer for CSI Camera\nRequires=dev-csi\\x2dcamera.device\nAfter=network.target dev-csi\\x2dcamera.device\n\n[Service]\nExecStart=\/usr\/bin\/ustreamer --device=\/dev\/csi-camera --host=0.0.0.0 --port=8081\nRestart=always\nRestartSec=3\nUser=root\n\n[Install]\nWantedBy=multi-user.target\n<\/pre>\nBy specifying dev-csi\\x2dcamera.device in Requires and After, the service is guaranteed to start at the timing when udev completes the device link generation. Apply the settings, restart the service, and return the file system to read-only.<\/p>\n
\nsystemctl daemon-reload\nsystemctl restart ustreamer-csi\nro\n<\/pre>\nEnsuring Reliable Streaming via \/dev\/csi-camera and Applicability to Other Devices After completing the configuration, we checked uStreamer’s streaming status again.<\/p>\n
curl -s http:\/\/127.0.0.1:8081\/state<\/pre>\nIn the output, “online”: true was displayed, frame rates were counted normally, and we confirmed that the stream video was displayed seamlessly from the browser as well. After running multiple OS reboot tests, we verified that even if the CSI camera’s physical number fluctuated to video0 or video2, the service started 100% reliably via \/dev\/csi-camera. This approach of “generating a fixed symbolic link from unique conditions using udev, and controlling service startup order with TAG+=”systemd”” is applicable not only to cameras but to any devices prone to number fluctuations on Linux, such as USB-serial converters (\/dev\/ttyUSB*) or external storage.<\/p>\n