Updates for synchronous and externally triggered cameras (WIP) #4089
Conversation
Update synchronized cameras documentation to: - Deprecate the XVS sync method for GS Cam, in favour of XTRIG - Recommend "always-on" property instead of using pull-ups - Recommend "trigger-mode" for IMX477 be set using the new OF property (better for source and sink on same Pi) while noting that the module parameter still works and that "trigger-mode" means something quite different for IMX296! - Document the need to edit the pipeline config file for timeout - Some attempt to tidy the structure while covering all the options - Remove $ prompts from scripts/commands, so they can be copy-pasted
If you use the |
|
It's a bit messy, but hard to make it simpler without omitting required information (indeed it does omit repeating the "timeout-defeat" instructions for GS external trigger, but presumably people will infer that it needs to be done as in the previous section). I feel this stuff would be better as a separate Application Note rather than part of the generic camera documentation? Conspicuous by is absence is any mention of the new S/W synchronization method! |
|
|
||
| This step is only necessary if you have more than one camera with XTR wired in parallel. | ||
|
|
||
| As the superuser, edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. |
There was a problem hiding this comment.
We generally don't use phrasing like "As the superuser..." - I think I'd probably just go with "Edit /boot/firmware/config.txt and change..."
You could link to https://www.raspberrypi.com/documentation/computers/config_txt.html#common-hardware-configuration-options if you really want to.
There was a problem hiding this comment.
I'll remove it (and the other one below).
I suppose it was a sort of echo of a previous use of that word.
| ---- | ||
| dtoverlay=imx296,always-on | ||
| ---- | ||
| When using the CAM0 port on a Raspberry Pi 5, CM4 or CM5, append `,cam0` to that line without a space. If both cameras are on the same Raspberry Pi you will need two dtoverlay lines, only one of them with `cam0`. |
There was a problem hiding this comment.
"only one of them with" -> "only one of them ending with" ?
|
|
||
| === Starting the camera | ||
|
|
||
| Enable external triggering through superuser mode: |
There was a problem hiding this comment.
I think I'd shorten this to just "Enable external triggering:"
There was a problem hiding this comment.
Inherited from the original at L26, but can be shortened.
But now I'm wondering if I strictly need to edit external_trigger.adoc? The original was nice and succinct. The "always-on" parameter is perhaps not essential in this case because the driver is quite low impedance.
| Making use of the XVS pin (Vertical Sync) allows one camera to pulse when a frame capture is initiated. | ||
| The other camera can then listen for this sync pulse, and capture a frame at the same time as the other camera. | ||
| The High Quality (HQ) Camera supports synchronous captures. | ||
| Using the XVS pin (Vertical Sync) allows one camera (the "source") to pulse when a frame capture is initiated. |
There was a problem hiding this comment.
"to pulse" -> "to send a pulse" ?
There was a problem hiding this comment.
Yes. And I probably should re-check the datasheet and whether or not we're using "fast trigger mode" or whatever it is... to check that the final part of the sentence is accurate too.
| === Using the HQ Camera | ||
| [NOTE] | ||
| ==== | ||
| Global Shutter (GS) Cameras can also be operated in a synchronous mode. However, the source camera will record one extra frame. Instead, for the GS Camera we recommend using an xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger source]. You cannot synchronise a GS Camera to an HQ Camera. |
There was a problem hiding this comment.
People might misinterpret "You cannot synchronise a GS Camera to an HQ Camera." to mean that you can synchronise an HQ Camera to a GS Camera"? 😉 Perhaps changing "to" to "with" is safer?
|
|
||
| Solder the GND and XVS test points of each HQ Camera board to each other. | ||
| *For GS Cameras only,* you will also need to connect the XHS (Horizontal Sync) test point of each camera. On any GS Camera that you wish to act as a sink, bridge the two halves of the MAS pad with solder. |
There was a problem hiding this comment.
"test point of each camera." -> "test point of each camera together." ?
|
|
||
| [source,console] | ||
| As the superuser, edit `/boot/firmware/config.txt`. Change `camera_auto_detect=1` to `camera_auto_detect=0`. |
|
|
||
| Solder the GND of each Camera board to each other. Also solder 2 wires to the XHS test points on each board and connect these. No pullup is needed for XHS pin. | ||
| If the cameras are not all started within 1 second, the `rpicam-vid` application can time out. To prevent this, you must edit a configuration file on any Raspberry Pi(s) with sink cameras. On Raspberry Pi 5 or CM5, make a copy of the file `/usr/share/libcamera/pipeline/rpi/pisp/example.yaml`. On other Raspberry Pi models, make a copy of the file `/usr/share/libcamera/pipeline/rpi/vc4/rpi_apps.yaml`. |
There was a problem hiding this comment.
Perhaps it's worth suggesting two different commands to copy each of those files to the same filename in the user's home folder, and then using that filename in the export LIBCAMERA_RPI_CONFIG_FILE= line below? 🤷♂️
| ---- | ||
| $ ffmpeg -i source.h264 -vf select="gte(n\, 1)" source.h264 | ||
| ---- | ||
| NOTE: When using the GS camera in synchronous mode, the sink will not record exactly the same number of frames as the source. **The source records one extra frame before the sink starts recording**. Because of this, you need to specify that the sink records one less frame with the `--frames` option. You could use `ffmpeg` to delete the first frame from the source camera's video recording. |
There was a problem hiding this comment.
"You could use" -> "Alternatively you could use"
There was a problem hiding this comment.
Not alternatively, but as well as!
Ben's original doc was somewhat ambiguous about which camera got the extra frame, needed the different command line and needed post-processing.
I need to test this again because getting it wrong leads to a (soft) lockup if the sink doesn't get the right number of syncs.
There was a problem hiding this comment.
Not alternatively, but as well as!
Ahhh, in which case perhaps the "could" ought to be "should then" ? (and perhaps worth bringing back the example ffmpeg command line)
There was a problem hiding this comment.
Yes. I was trying to corral the GS-Cam-specific bits into NOTEs, but the ffmpeg command can't really go inside one of those, so might have to re-jig the structure.
It would be nice if we could obliterate GS Camera from this part, but somebody is bound to be using it already...
There was a problem hiding this comment.
Isn't the GS-Cam even more suited to synchronised captures, than a rolling-shutter camera? 🤔
There was a problem hiding this comment.
Well it would be nice to steer GS Cam users towards the alternative "external trigger" method (which requires fewer wires, is software-configurable, and doesn't have the asymmetry / off-by-one-frame issues)
Sadly, now that we've documented this method we can't really un-document it.
There was a problem hiding this comment.
Ahhh, now I see what you're saying 🙂 Yeah, I guess all we can do is strongly-discourage it.
|
Ah, I've belatedly noticed that we do already document Software Camera Synchronisation, although it's well hidden under rpicam-apps and could maybe do with being bumped a bit up the hierarchy. I should definitely link there from here. |
Update synchronized cameras documentation to:
Deprecate the XVS sync method for GS Cam, in favour of XTRIG
Recommend "always-on" property instead of using pull-ups
Recommend "trigger-mode" for IMX477 be set using the new OF property (better for source and sink on same Pi) while noting that the module parameter still works and that "trigger-mode" means something quite different for IMX296!
Document the need to edit the pipeline config file for timeout
Some attempt to tidy the structure while covering all the options
Remove $ prompts from scripts/commands, so they can be copy-pasted