Synchronous and external trigger documentation. #3046
Conversation
|
@naushir - please can you review? |
| The global shutter camera can be triggered externally by pulsing the XTR pin on the board. | ||
| Multiple cameras can be connected to the same pulse leading to a better way to synchronise two cameras. | ||
|
|
||
| The low puslewidth is equal to the exposure time. i.e. a low pulse of 10ms leads to an exposure time of 10ms. |
There was a problem hiding this comment.
Maybe mention how to control the framerate as well? Perhaps a diagram might be helpful here.
| @@ -0,0 +1,53 @@ | |||
| == External Trigger | |||
| === IMX296 | |||
There was a problem hiding this comment.
Perhaps this should be titled "External Trigger on the Raspberry Pi Global Shutter Camera" and remove the IMX296 subsection?
|
|
||
| ==== Note | ||
| When running libcamera apps, you will need to specify a fixed shutter duration, so that the AGC controller | ||
| knows not to change the shutter speed during exposure control. This will force the camera to only change gain. |
There was a problem hiding this comment.
This will force the camera to only change gain.
I would replace with something like:
This would ensure the AGC does not try adjusting camera's shutter speed, which is controlled by the external trigger pulse.
|
|
||
| include::camera/synchronous_cameras.adoc[] | ||
|
|
||
| include::camera/external_trigger.adoc[] |
There was a problem hiding this comment.
At the end seems reasonable at the moment. The legacy camera stack stuff is going away on the bookworm branch so as far as I remember the entire raspicam.adoc section disappears.
|
|
||
| ==== Boot up both Raspberry Pis | ||
|
|
||
| The file `/sys/module/imx477/parameters/trigger_mode` determines which board outputs pulses, or waits to recieve pulses (master and slave). |
There was a problem hiding this comment.
Instead of master/slave throughout, I think we might want to use source/sink as per the module param description in the driver.
| [,bash] | ||
| ---- | ||
| sudo su | ||
| echo 2 > /sys/module/imx477/parameters/trigger_mode |
|
|
||
| Starting the slave and the master within around 2 seconds of each other, leads to the slave recording a frame before the master, | ||
| but this is unpredictable, and if this window is missed, then the slave runs behind. | ||
| It is hence better to start up the slave with a noticable delay between the master, and then account for the dropped frame later. |
There was a problem hiding this comment.
I would possibly remove this last paragraph as a workaround, and link back to using external trigger to avoid this problem.
| libcamera-vid --frames 299 -o sync.h264 | ||
| ---- | ||
| ==== Note | ||
| Due to limitations of the IMX296 sensor board, we are unable to get the slave to record exactly the same amount of frames as the master. |
There was a problem hiding this comment.
Due to limitations of the IMX296 sensor board
Due to limitations of the IMX296 sensor (i.e. remove board)
| ---- | ||
| ==== Note | ||
| Due to limitations of the IMX296 sensor board, we are unable to get the slave to record exactly the same amount of frames as the master. | ||
| **The master will record one extra frame before the slave starts recording.** This will need to be accounted for later. |
There was a problem hiding this comment.
This will need to be accounted for later.
This will need to be accounted for later in the application.
|
Once this has been approved/merged, can we link this PR in the following thread please? |
| pwm.freq(framerate) | ||
|
|
||
| pwm.duty_u16(int((1 - shutter / frame_length) * 65535)) | ||
| ``` |
There was a problem hiding this comment.
One thing to correct here - I think strictly speaking this calculation might need to be
pwm.duty_u16(int((1 - (shutter - 14) / frame_length) * 65535))
There was a problem hiding this comment.
Also probably should adjust the pulse diagram to show that exposure time = time for the low pulse width + 14.26us
documentation/asciidoc/computers/camera/synchronous_cameras.adoc
Outdated
Show resolved
Hide resolved
| The global shutter camera can be triggered externally by pulsing the XTR pin on the board. | ||
| Multiple cameras can be connected to the same pulse leading to a better way to synchronise two cameras. | ||
|
|
||
| The low puslewidth is equal to the exposure time. i.e. a low pulse of 10ms leads to an exposure time of 10ms. Framerate is directly controlled by how often you pulse the pin. |
There was a problem hiding this comment.
Need to change the wording to add the 14.26us offset for the exposure time.
aallan
added
enhancement
documentation
camera 📷
waiting for revisions
|
Aparat from the section ordering question, looks good! |
| The global shutter camera can be triggered externally by pulsing the XTR pin on the board. | ||
| Multiple cameras can be connected to the same pulse leading to a better way to synchronise two cameras. | ||
|
|
||
| The low puslewidth plus an extra 14.26us is equal to the exposure time. i.e. a low pulse of 10000us leads to an exposure time of 10014.26us. |
There was a problem hiding this comment.
I think this would be more readable if re-ordered to something like:
"The exposure time is equal to the low pulse-width time plus an additional 14.26us" ?
| in external trigger mode. | ||
|
|
||
| Next solder a wire to the touchpoint of XTR on the GS Camera board. | ||
| Connect these to the pico - XTR to any pin. Pin 28 is used in this example. Ground is not needed to be connected. |
There was a problem hiding this comment.
I think 'pico' needs to be capitalised as 'Pico'? Also, this is the first time that the word 'Pico' appears in this page, so it might need a bit of earlier explanatory context?
| exit | ||
| ---- | ||
|
|
||
| ==== Raspberry Pi Pico Code |
There was a problem hiding this comment.
Should probably clarify that this is "Raspberry Pi Pico MicroPython Code" ?
| @@ -0,0 +1,56 @@ | |||
| == External Trigger on the Global Shutter Camera | |||
| The global shutter camera can be triggered externally by pulsing the XTR pin on the board. | |||
There was a problem hiding this comment.
I'm guessing that "XTR" is an abbreviation of "eXternal TRigger"? Is it worth explaining that?
| Run the code on the pico, and run the code for the camera: | ||
| [,bash] | ||
| ---- | ||
| libcamera-hello -t 0 --qt-preview --shutter 3000 |
There was a problem hiding this comment.
So there's no option that you need to give to the libcamera apps to tell them that they're being used in "external trigger" mode?
| === IMX477 | ||
| ==== Preparation | ||
|
|
||
| Connect a potential divider of 2x 1.5KOhm Resistors to 3v3 and ground, creating 1.65V. This can be connected to either Pi. |
There was a problem hiding this comment.
This definitely feels like this page is missing an introductory section, before diving straight into details about connecting resistors? 🤔
|
|
||
| Connect a potential divider of 2x 1.5KOhm Resistors to 3v3 and ground, creating 1.65V. This can be connected to either Pi. | ||
|
|
||
| Solder the GND and XVS touchpoints of each HQ Camera board to each other. |
There was a problem hiding this comment.
Worth explaining what XVS stands for?
|
|
||
| Solder the GND and XVS touchpoints of each HQ Camera board to each other. | ||
|
|
||
| Connect the XVS wires to the 1.65V potential divider pull up. |
There was a problem hiding this comment.
I think it'd be good to have a wiring diagram here. Perhaps something generated using Fritzing.
There was a problem hiding this comment.
Can't seem to find any sort of generic camera (or the GS camera) on fritzing. Is there an alternative or shall I just say "Connect to XVS pin" on the wiring diagram?
There was a problem hiding this comment.
Can't seem to find any sort of generic camera (or the GS camera) on fritzing. Is there an alternative or shall I just say "Connect to XVS pin" on the wiring diagram?
Must admit the only part I can find is the NoIR camera. A labelled wire heading off to the side is fine.
| @@ -0,0 +1,83 @@ | |||
| == Synchronous Captures | |||
| === IMX477 | |||
There was a problem hiding this comment.
https://www.raspberrypi.com/documentation/accessories/camera.html#hardware-specification tells me that IMX477 is the "HQ Camera", so that's probably a more suitable header than "IMX477" 🙂
| Start the source running | ||
| [,bash] | ||
| ---- | ||
| libcamera-vid --frames 300 --qt-preview -o sync.h264 |
There was a problem hiding this comment.
Probably makes more sense to have the source and sink recording to different filenames, rather than having them both using sync.h264 ?
| libcamera-vid --frames 300 --qt-preview -o sync.h264 | ||
| ---- | ||
|
|
||
| Frames should be synchronous. Use --frames to ensure the same amount of frames are captured, and that the recordings are exactly the same length. |
|
|
||
| Solder the GND and XVS touchpoints of each HQ Camera board to each other. | ||
|
|
||
| Connect the XVS wires to the 1.65V potential divider pull up. |
There was a problem hiding this comment.
Feels like a simple wiring diagram would be really useful here?
|
|
||
| Solder the GND of each Camera board to each other. Also solder 2 wires to the XHS touchpoints on each board and connect these. No pullup is needed for XHS pin. | ||
|
|
||
| On the boards that you wish to act as sinks, solder the two halves of the MAS pad together. This enters the sensor into sink mode. |
There was a problem hiding this comment.
I dunno if it might be worth explaining or clarifying why the wiring for this camera is different for the wiring for the other camera?
|
I hope you don't mind all the comments I've left here. IMHO this could also do with a bit more of an introductory explanation of what the synchronous and external trigger modes actually mean, and when you might choose one over the other? |
|
Something else which just occurred to me - if we're telling users about soldering wires to their cameras, I guess a) we ought to warn them that this will void their warranty (?) and b) we ought to tell users to remove the protective backing from the GS Camera before trying to solder to it? |
|
I've updated based off the comments. We also need @simon-martin-rpi to approve before it gets merged. |
aallan
added
waiting for comment
| === Preparation | ||
|
|
||
| NOTE: Soldering wires to your camera module will void the camera's warranty. When soldering to the Global Shutter Camera, please remove the plastic back cover to avoid damaging the cover. | ||
|
|
There was a problem hiding this comment.
Sorry late to comment on this, but I would remove the warranty sentence completely.
There was a problem hiding this comment.
Agreed.
After discussions with @simon-martin-rpi, I'd probably go with something along the lines of "WARNING: The modification includes removing an SMD soldered part. You should not attempt this modification unless you feel you are competent to complete it." or something along those lines.
I would prefer if we did not mention anything about warranty for this change. |
Added files to documentation about how to externally trigger IMX296 and information about synchronising cameras for IMX477 & IMX296
| First, remove/desolder resistor 11 on the GS Camera board. This connects GP0 to XTR and without removal, the camera will not operate | ||
| in external trigger mode. | ||
| The location of the resistor is displayed below. | ||
|
|
There was a problem hiding this comment.
Just one small change needed here:
First, remove/desolder resistor 11 on the GS Camera board. This connects GP0 to XTR and without removal, the camera will not operate in external trigger mode. If you have transistor Q2 fitted, remove/desolder the component along with R11. This is needed as the drive strength on the Raspberry Pi Pico is not strong enough to bring the XTRIG line low, and the the camera will not operate in external trigger mode.
We also want to circle the Q2 in the image below.
bebon901
force-pushed
the
develop
branch
2 times, most recently
from
100920b
to
6875f8f
Compare
|
Any more changes needed for this? If not, let's hit the big green button. |
|
Okay, I'm actually going through this now it's merged and it's not sitting well where it currently is located. So I think I'm going to move this out of the software section and into the hardware section of the documentation. It's more properly a "hardware" not a "software" thing as you're hacking on the hardware of the camera. I PR'ed it at #3072, and have now merged to However. I've just noticed we're missing a wiring diagram for the GS camera in the synhronous capture section? Presumably we need a wiring image in this section as well? |
|
No wiring diagram showing how to connect to the Pico (Firzting part is at https://datasheets.raspberrypi.com/pico/Pico-R3-Fritzing.fzpz) in the External Trigger section either? |
|
I've pushed this live to the documentation site with #3073. Should be up when the cache times out, so 15 minutes or so. |
@bebon901 can you create a new PR with these when you get a chance please? |
The potential-divider instructions at https://www.raspberrypi.com/documentation/accessories/camera.html#using-the-hq-camera say "2 equally high impedance ( > 1kOhm) resistors" but the corresponding part for https://www.raspberrypi.com/documentation/accessories/camera.html#using-the-gs-camera says "2x 1.5KOhm Resistors". Could/should these be made the same? There's also a 'pi' in lower-case which should be 'Pi'. "This enters the sensor into sink mode." could probably be phrased better 😉 This reads much better than the initial version, thank you for incorporating my suggestions @bebon901 😃 |
|
From the page,
Might want to explain why ground doesn't need to be connected, because that's pretty weird and people are going to wonder. I know I'm confused. |
|
For illustrative purposes, I've gone in and done an updated version of the wiring diagram for the HQ camera.
|
The wiring diagram for the GS Camera would be exactly the same, just the user connects an extra wire between each camera board (which wouldn't be shown on this wiring diagram anyway). Can reference picture for the HQ camera, or create a new diagram, whichever you feel more suitable |
Added files to documentation about how to externally trigger IMX296 and information about synchronising cameras for IMX477 & IMX296