1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
gst1-rtsp-launch installs the gst-rtsp procd service and /etc/config/gst-rtsp.
Install capture, ISP, processing and encoder plugins appropriate to the hardware.
Discovery
The discovery instance handles video4linux and media hotplug events. A scan
starts after 15 seconds without another event. An event during a scan makes
its result stale. Coldplug uses the same delay.
media-ctl describes sensor, ISP, capture and metadata relationships;
v4l2-ctl describes capabilities, formats and controls. gst-device-monitor-1.0
identifies libcamera cameras. gst-inspect-1.0 associates V4L2 encoder and
converter factories with devices. Metadata, ISP and encoder nodes are not
treated as standalone cameras. Media-controller capture uses libcamera's
pipeline handler and IPA to configure the graph.
video-device sections retain topological paths, entity names, roles,
upstream references and handled=1. Firmware-node paths identify libcamera
sensors. USB paths omit the enumerated bus number. Device nodes, controls
and dynamic factory names stay in /var/run/gst-rtsp/devices.json, tagged with
the boot ID. Ambiguous identities fail discovery.
New device sections use identifiers such as device0. These identifiers
are persistent UCI references; each section's path identifies its topology.
Existing section identifiers remain valid across discovery and upgrades.
Discovery adds missing sections and relationships, preserving existing
values, offline devices and user-deleted streams. camera.configured records
that defaults have already been generated. A private UCI delta directory
separates discovery commits from pending user edits. New inputs and streams
are disabled until their capture and encoding paths have been selected.
Hardware paths and restart behaviour
camera sections describe physical cameras and camera-wide controls. input
sections identify capture inputs. stream sections reference an input and
describe RTSP outputs. One capture procd instance per camera contains all
its enabled streams' capture, processing and encoding branches.
For libcamera, streams with identical raw settings and processing share a
source pad through a tee. Distinct settings request separate source pads;
their size, format and frame rate constrain the hardware outputs directly.
A V4L2 input is captured
once and branches through a tee; different output sizes require independent
hardware converters. Selected converters use DMA import/export with their
passthrough mode disabled. Hardware encoders use DMA import.
Raw buffers stay inside the camera pipeline. No raw-frame socket bridge,
encodebin or automatic software conversion is inserted. Automatic encoder
selection chooses a discovered hardware encoder supporting the requested
codec. An unsupported path fails rather than selecting a software encoder.
Explicit encoder factories and complete pipeline overrides are expert
settings; selecting a software factory explicitly uses that implementation.
Encoded frames pass through unixfdsink and unixfdsrc to each stream's RTSP
process. Abstract Unix stream sockets carry buffer descriptors, caps and
timestamps. Each RTSP instance parses and packetises its encoded stream.
FD-backed buffers are shared; other encoded buffers are copied into shared
memory by unixfdsink. Raw buffers remain inside the camera pipeline.
Separate server instances retain separate RTSP ports and mounts.
Changes to this configuration restart all capture and RTSP instances.
Independent reconfiguration is deferred in favour of keeping acquisition
and encoding together.
DMA capability, format, stride and buffer allocation must agree throughout
the raw path. A pipeline description alone cannot establish end-to-end
copy-free behaviour for an untested driver. Verify allocation and streaming
on the target hardware. The model uses capabilities and topology rather
than SoC names; hardware stream-count and resource limits still apply.
An ISP or post-processor with several capture outputs belongs to one camera
and shares upstream resources. These outputs differ from memory-to-memory
converters, which are explicitly selected through processor references.
Multiple libcamera pads require support in the camera's pipeline handler.
Adding kernel capture nodes alone does not expose those outputs through
libcamera. The UCI camera/input/stream relationships retain multiple-output
requests while the corresponding driver and pipeline support develops.
UCI options
camera:
path Persistent identity, generated by discovery.
source Capture factory, libcamerasrc or v4l2src.
id Libcamera camera ID.
capture video-device section for a standalone V4L2 camera.
exposure Libcamera exposure time in microseconds, or auto.
gain Libcamera analogue gain, or auto.
brightness Libcamera brightness, or auto for the backend default.
contrast Libcamera contrast, or auto for the backend default.
saturation Libcamera chroma saturation, or auto for backend default.
sharpness Libcamera sharpness, or auto for the backend default.
source_properties Additional upstream source properties, gst-launch syntax.
Named controls require libcamera. Exposure and gain select their individual
automatic/manual modes. Other auto values leave backend defaults in effect;
they do not introduce automatic algorithms. Support and ranges depend on
the camera. V4L2-specific extra-controls can use source_properties.
input:
camera Owning camera section.
enabled Enable this capture input, default 0.
capture Optional video-device section overriding the capture node.
width, height V4L2 acquisition size or libcamera output defaults; 0 is auto.
framerate Acquisition frame rate, e.g. 30/1; auto by default.
pixel_format Raw format, e.g. NV12; auto by default.
colourimetry Raw colourimetry; auto by default.
io_mode V4L2 capture requires dmabuf, its generated default.
processor Ordered video-device references for hardware converters.
stream:
enabled Serve this stream, default 0.
input Capture input section.
port Unique RTSP TCP port, generated from 8554 upwards.
mount RTSP URL path, default /test.
codec auto, h264, h265 or mjpeg. Auto prefers hardware H.265,
then H.264, then MJPEG among discovered encoders.
resolution native uses the discovered sensor pixel-array size;
custom uses width and height.
width, height Output size; 0 uses input/backend defaults.
framerate Output frame rate, e.g. 30/1; auto by default.
bitrate H.264/H.265 target bits per second. 0 derives the target
from the output size and frame rate in cbr and vbr mode,
60 bits per 1000 pixels and frame for H.265 and 120 for
H.264, and uses encoder defaults otherwise.
bitrate_mode auto, cbr, vbr or quality; requires discovered V4L2 support.
Generated streams use cbr. Quality disables frame rate
control and has no bitrate target.
quality high, medium or low for fixed-quantiser H.264/H.265.
jpeg_quality JPEG quality, 0..100, subject to driver limits; auto default.
profile H.264/H.265 profile, e.g. high/main; auto by default.
keyframe_interval Frames per GOP; 0 uses encoder defaults.
pixel_format Encoder input format, e.g. NV12; auto by default.
colourimetry Encoder input colourimetry; auto by default.
encoder Encoder factory; auto selects discovered hardware.
encoder_device video-device section selecting its runtime encoder.
processor Ordered video-device references for hardware converters.
output_io_mode Hardware encoders require dmabuf-import, the default.
repeat_headers Request V4L2 SPS/PPS insertion on IDR frames when set to 1.
pipeline Complete pipeline override, ending in a payloader named pay0.
Bitrate and GOP options map to V4L2 controls. Hardware JPEG quality uses the
discovered compression_quality control; an unavailable mapping fails.
MJPEG uses RTP/JPEG payload type 26; H.264/H.265 use dynamic payload type 96.
MJPEG is intended mainly for an optional HTTP browser preview endpoint.
The RTSP preview uses a scaled-down H.265 stream with a lower constant bitrate.
Browser playback of RTSP through JavaScript or WASM needs a browser-compatible
transport bridge; WebRTC is another possible frontend transport. These HTTP
and browser transports remain separate from the current RTSP service.
Example: a main stream from an existing input0:
config stream 'main'
option enabled '1'
option input 'input0'
option port '8554'
option mount '/main'
option codec 'auto'
option resolution 'native'
option framerate 'auto'
option bitrate_mode 'cbr'
option bitrate '0'
option profile 'auto'
option pixel_format 'auto'
option repeat_headers 'auto'
Sensor-native dimensions come from libcamera's PixelArraySize property.
Missing native dimensions fail validation. Format, frame rate and codec
profile negotiate through GStreamer. A derived bitrate assumes 30 frames per
second when the frame rate is auto. High quality reduces both driver-default
I/P quantisers by six, one halving of the H.264/H.265 quantisation step;
medium retains the defaults and low increases them by six. Values are
clamped to discovered control ranges. JPEG quality mode uses the driver's
maximum compression_quality value. Bitrate targets are rejected in quality mode.
A scaled preview requires an independently scaled hardware output. On RV1126,
the current rkisp2 libcamera handler exposes one ISP output, so parallel sizes
require additional hardware scaler and pipeline-handler support. Both H.265
profiles are represented through ONVIF Media2; Media1 cannot describe H.265.
Select capture and processing paths supported by the hardware, enable input0,
then commit and reload. A reload after configuration changes interrupts streams.
uci set gst-rtsp.input0.enabled='1'
uci commit gst-rtsp
/etc/init.d/gst-rtsp reload
Upstream test-launch serves streams without authentication. URLs are
rtsp://<host>:<port>/<mount>.
ONVIF integration
Install onvif-simple-server for CGI services through uhttpd and a separate
procd WS-Discovery instance. Its uci-defaults script adds uhttpd.onvif with
HTTP listeners on port 8080 and document root /www/onvif. Existing uhttpd
sections and an existing uhttpd.onvif section are preserved.
The defaults script also persists a device UUID shared by CGI services and
discovery. CGI URLs use the local address of the accepted HTTP connection.
Discovery announces on every active multicast-capable interface over IPv4
and IPv6, and follows kernel interface and address notifications. Network
changes do not restart the video pipelines.
The gst-rtsp service generates /var/run/onvif-simple-server/config.json
from enabled streams. The capture supervisor reads negotiated caps from
gst-launch and publishes dimensions, frame rate and codec profile. ONVIF
waits for every enabled stream's caps and accepts records only from the
current boot and matching capture pipeline. Codec bitrate, GOP and JPEG
quality use explicit stream values or discovered encoder defaults. Quality
mode reports zero for its unset bitrate limit. The interframe quality value
is the inverse configured I-frame quantiser, maximum QP plus one minus QP;
it describes an encoder setting, not a measured image quality. Bitrate is represented in kilobits
per second. Values that cannot be represented cause generation to fail.
One ONVIF instance describes one camera with all its enabled streams.
Set onvif-simple-server.main.camera to a camera section when several
cameras are enabled. Set stream.onvif to 0 to exclude a stream. Pipeline
overrides require their own ONVIF configuration because the service cannot
derive their negotiated stream parameters.
Options in onvif-simple-server.main:
enabled Enable the ONVIF service, default 1.
uuid Persistent device identity, generated at installation.
camera Optional camera section to advertise.
manufacturer Hardware vendor; defaults to the board's compatible prefix.
model Device model, defaults to system board information.
hardware_id Hardware identifier, defaults to the system board name.
firmware_ver Firmware identity, defaults to the OpenWrt release description.
serial Hardware serial number; persistent device UUID if unavailable.
user, password Optional ONVIF credentials.
config_file JSON configuration, default generated runtime file.
Device information comes from ubus system board. FirmwareVersion carries
the OS release identity. GetHostname reports the current kernel hostname.
The name and hardware scopes carry the hostname and board identifier, with
URI component encoding, in both GetScopes and WS-Discovery. Explicit UCI
identity options override the discovered values. A device-tree or DMI serial
number is used when available; the persistent UUID identifies boards without
a readable hardware serial. An unknown hardware vendor is reported as Unknown.
Camera source_width, source_height, source_framerate and
source_framerate_den describe the physical sensor mode. Without explicit
source settings, onvif-simple-server derives source dimensions from the
largest configured stream.
CGI endpoints return HTTP 503 until their configuration exists. Stopping
gst-rtsp removes its generated configuration and stops discovery. A custom
config_file is managed by its owner and is preserved by the RTSP service.
Encoder setters and imaging services remain optional through upstream's
generic external helpers; see CONTROL_HELPERS.md in the installed ONVIF
data directory. This integration advertises read-only stream settings.
The gst1-mod-unixfd dependency provides the encoded-stream handoff and can
also serve additional consumers. The generated raw-video path remains
within the capture pipeline.
References:
https://gstreamer.freedesktop.org/documentation/unixfd/unixfdsink.html
https://gstreamer.freedesktop.org/documentation/unixfd/unixfdsrc.html
https://gstreamer.freedesktop.org/documentation/video4linux2/v4l2src.html
https://gstreamer.freedesktop.org/documentation/additional/design/dmabuf.html
https://docs.libcamera.org/getting-started.html#using-gstreamer-plugin
|
