Update Compute Module IO Board camera configuration doc for Bookworm #3188

nathan-contino · 2023-10-17T17:24:12Z

Closes CM4 IO board camera configuration documentation has been superceeded #2748
Removes redundant instructions which duplicated quickstart (with extra and sometimes conflicting information)
Streamlined Device Tree section with explicit instructions, a clear starting point, and a straightforward purpose
Actually Works for both I/O boards, tested with both Compute Module form factors
Includes a minor pin configuration update -- adding a couple of missing pin configuration section names and formatting the names of those sections in monospace instead of bold (since they refer to device tree source code!)
Link fix for updated title

TODO: Add an image of the J6 jumper cable setup required on the CM4 I/O board. We have an Asana task brewing for that, should be done Oct 18. Will likely update the main section modified here with that image in a follow-up PR after merge once the photo is available.

lurch

Lots of in-depth feedback, but that's because this is very deep technical info!

lurch · 2023-10-17T23:03:47Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

-=== Updating your System
-
-The camera software is under constant development. Please ensure your system is up to date prior to using these instructions.
+Before configuring a camera, ensure your system runs the latest available software:


'runs' -> 'is running' ?

You missed out this change?

lurch · 2023-10-17T23:10:53Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

-. (CM4 only) Add jumpers to J6.
-. Power up and run `+sudo wget https://datasheets.raspberrypi.com/cmio/dt-blob-dualcam.bin -O /boot/firmware/dt-blob.bin+`
-. Reboot for the dt-blob.bin file to be read.
+. _(CM1, CM3, CM3+, and CM4S only)_: Add the following directive to `/boot/firmware/config.txt` to accommodate the swapped GPIO pin assignment on the I/O board:


Might be neater to combine this section with the next, rather than have the repeated _(CM1, CM3, CM3+, and CM4S only)_: Add the following directive to /boot/firmware/config.txt ... ?

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

lurch · 2023-10-17T23:17:22Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+  * `2` to `CAM1_101`
+  * `3` to `CAM1_100`


I think these are IO1 and IO0 rather then 101 and 100 ?

lurch · 2023-10-18T00:06:36Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+
+By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.
+
+The following Device Tree Source files enable single and dual cameras for CM1, CM3, and CM4:


Are these example Device Tree Source files?
(and another minor nitpick, but I think this is the first place where you don't explicitly mention CM3+ or CM4S 😉 )

The omission is intentional -- these Device Tree Source files don't include CM3+ or CM4S because they predate those Compute Modules. Sadly I don't have the bandwidth (or the material access) to build those entire source trees in this PR.

CM3+ is identical to CM3 from the firmware's perspective.

These files were in the documentation repo until the major reorg.
It looks like I have updates for CM4S (and 02W) in my copy of the files. Not sure why they haven't been published.

lurch · 2023-10-18T00:10:56Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc


-The `pin_config` section in the `pins_cm { }` (Compute Module 1), `pins_cm3 { }` (Compute Module 3), or `pins_cm4 { }` (Compute Module 4) section of the source dts needs the camera's LED and power enable pins set to outputs:
+To use the HQ camera, pass its index (`0`) to the `--camera` option of any `libcamera` subcommand:


Why demonstrate using camera index 1 before demonstrating camera index 0?

lurch · 2023-10-18T00:14:23Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

@@ -123,16 +336,23 @@ pin_define@CAMERA_0_SDA_PIN { type = "internal"; number = <0>; };
 pin_define@CAMERA_0_SCL_PIN { type = "internal"; number = <1>; };
 ----

-Indentation and line breaks are not critical, so the example files expand these blocks out for readability.
+To add a second camera, set the *NUM_CAMERAS* parameter the `pin_defines` subsection of your device's pin configuration to `2`:


'parameter the' -> 'parameter in the' ?

lurch · 2023-10-18T00:17:24Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+
+==== Configure camera pins with Device Tree
+
+By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.


And a minor stylistic point, but this paragraph seems to have multiple consecutive "To do X, do Y." sentences.

lurch · 2023-10-18T00:20:45Z

documentation/asciidoc/computers/configuration/pin-configuration.adoc

+* `pins_3bplus`: Raspberry Pi 3 Model B+
+* `pins_3aplus`: Raspberry Pi 3 Model A+
+* `pins_pi0`: Raspberry Pi Zero
+* `pins_pi0w`: Raspberry Pi Zero W


Does Raspberry Pi Zero 2 W need to be added too?

Yes, but I couldn't track down that value. Technically this will need to be updated for the 5 soon anyway, that'll be a good reminder to add this as well.

This is all legacy firmware configuration. It does not apply to Pi5.

Other than configuring the legacy camera and DSI display on CMs, dt-blobs should not be needed or used. The main downside it that they totally replace the one built into the firmware, therefore it breaks if there is ever a change of syntax required.

The master copy is https://github.com/raspberrypi/firmware/blob/master/extra/dt-blob.dts
Pi02W is pins_pi02w

nathan-contino · 2023-10-18T08:38:40Z

@aallan Updated to address Andrew's feedback. Ready to merge when you are.

6by9

This is slightly hard to read in asciidoc format, but we appear to have a serious mismash of legacy and libcamera stuff here. The two are independent and should not be mixed.

6by9 · 2023-10-18T10:44:48Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+
+If a custom board doesn't work with these overlays, create a new Device Tree that describes the entire board.
+
+==== Configure camera pins with Device Tree


You're switching to configuring the legacy camera stack with this section, but nothing has said as much.

dt-blobs are irrelevant for libcamera, and whilst the dt-blob (ab)uses Device Tree syntax, this is not Device Tree.

There shouldn't be anything about the legacy camera stack present in the documentation any more at all. All of that needs to just go. It should have been pulled out as part of the Bookworm milestone but it obviously got missed. 😐

I'll open a PR to remove this section. Unfortunately I wasn't able to test these instructions -- I just cleaned up the section that already existed.

It should have been pulled out as part of the Bookworm milestone but it obviously got missed.

Ahh, I wasn't aware that the dt-blob stuff was "legacy" and not applicable to libcamera.

@6by9 As we're not including legacy camera stuff in the documentation, does that mean that all of the Device Tree / DTS / dt-blob stuff mentioned in this PR ought to be ripped out (even the "custom boards" part) ? Or are they any parts that are still relevant in the "libcamera world"?

6by9 · 2023-10-18T10:54:04Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+
+By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.
+
+The following Device Tree Source files enable single and dual cameras for CM1, CM3, and CM4:


CM3+ is identical to CM3 from the firmware's perspective.

These files were in the documentation repo until the major reorg.
It looks like I have updates for CM4S (and 02W) in my copy of the files. Not sure why they haven't been published.

6by9 · 2023-10-18T10:59:11Z

documentation/asciidoc/computers/configuration/pin-configuration.adoc

+* `pins_3bplus`: Raspberry Pi 3 Model B+
+* `pins_3aplus`: Raspberry Pi 3 Model A+
+* `pins_pi0`: Raspberry Pi Zero
+* `pins_pi0w`: Raspberry Pi Zero W


This is all legacy firmware configuration. It does not apply to Pi5.

Other than configuring the legacy camera and DSI display on CMs, dt-blobs should not be needed or used. The main downside it that they totally replace the one built into the firmware, therefore it breaks if there is ever a change of syntax required.

The master copy is https://github.com/raspberrypi/firmware/blob/master/extra/dt-blob.dts
Pi02W is pins_pi02w

6by9 · 2023-10-18T10:59:59Z

documentation/asciidoc/computers/compute-module/cmio-camera.adoc

+
+==== Configure camera pins with Device Tree
+
+By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.


This is NOT Linux device tree.

aallan · 2023-10-18T11:07:16Z

CM3+ is identical to CM3 from the firmware's perspective.

These files were in the documentation repo until the major reorg.

They're hosted on datasheets.raspberrypi.com, or at least I think these are the files you're talking about @6by9 ?

It looks like I have updates for CM4S (and 02W) in my copy of the files. Not sure why they haven't been published.

I can push them to the datasheets site along with the rest, drop me an email?

aallan · 2023-10-18T11:11:42Z

Okay, this looks like it needs another pass picking up the raised issues. Raised an issue #3192.

nathan-contino · 2023-10-18T11:13:26Z

Opened a follow-up PR to address comments: #3193

Update Compute Module IO Board camera configuration doc for Bookworm

e9a71be

nathan-contino added the bookworm 🐛 Issue with Bookworm label Oct 17, 2023

nathan-contino added 2 commits October 17, 2023 18:33

Switch missing image to block comment to placate ninja

d941d1e

Workaround ninja failure, attempt 2

5704bb4

lurch requested changes Oct 18, 2023

View reviewed changes

lurch added the camera 📷 label Oct 18, 2023

Implement changes to address Andrew feedback

615e5cd

aallan approved these changes Oct 18, 2023

View reviewed changes

aallan merged commit bd89164 into develop Oct 18, 2023

aallan deleted the bookworm-update-cm-camera-instructions branch October 18, 2023 09:00

6by9 reviewed Oct 18, 2023

View reviewed changes

aallan mentioned this pull request Oct 18, 2023

Resolve issues around camera configuration for Compute Modules #3192

Closed

nathan-contino mentioned this pull request Oct 18, 2023

Removed legacy CM Camera info #3193

Merged

lurch added the compute module Issues around CM and CMIO boards label Oct 18, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Compute Module IO Board camera configuration doc for Bookworm #3188

Update Compute Module IO Board camera configuration doc for Bookworm #3188

nathan-contino commented Oct 17, 2023 •

edited

Loading

lurch left a comment

lurch Oct 17, 2023

lurch Oct 18, 2023

lurch Oct 17, 2023

lurch Oct 17, 2023

nathan-contino Oct 18, 2023

lurch Oct 18, 2023

nathan-contino Oct 18, 2023

6by9 Oct 18, 2023

lurch Oct 18, 2023

lurch Oct 18, 2023

lurch Oct 18, 2023

lurch Oct 18, 2023

nathan-contino Oct 18, 2023

6by9 Oct 18, 2023

nathan-contino commented Oct 18, 2023

6by9 left a comment

6by9 Oct 18, 2023

aallan Oct 18, 2023

nathan-contino Oct 18, 2023

lurch Oct 18, 2023

6by9 Oct 18, 2023

6by9 Oct 18, 2023

6by9 Oct 18, 2023

aallan commented Oct 18, 2023 •

edited

Loading

aallan commented Oct 18, 2023

nathan-contino commented Oct 18, 2023


		By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.

		The following Device Tree Source files enable single and dual cameras for CM1, CM3, and CM4:


		The `pin_config` section in the `pins_cm { }` (Compute Module 1), `pins_cm3 { }` (Compute Module 3), or `pins_cm4 { }` (Compute Module 4) section of the source dts needs the camera's LED and power enable pins set to outputs:
		To use the HQ camera, pass its index (`0`) to the `--camera` option of any `libcamera` subcommand:


		==== Configure camera pins with Device Tree

		By default, the GPIOs used for the camera on the Compute Module are set to input mode. To xref:configuration.adoc#changing-the-default-pin-configuration[override these default settings], create a custom xref:configuration.adoc#device-trees-overlays-and-parameters[Linux Device Tree]. To define a custom Device Tree, create a custom a Device Tree Source (`dts`) file. To load your custom Device Tree, xref:configuration.adoc#changing-the-default-pin-configuration[compile your Device Tree Source file into a `dt-blob.bin` file]and place it in the boot partition. Raspberry Pi OS will load this Device Tree into firmware when the system boots.


		If a custom board doesn't work with these overlays, create a new Device Tree that describes the entire board.

		==== Configure camera pins with Device Tree

Update Compute Module IO Board camera configuration doc for Bookworm #3188

Update Compute Module IO Board camera configuration doc for Bookworm #3188

Conversation

nathan-contino commented Oct 17, 2023 • edited Loading

lurch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathan-contino commented Oct 18, 2023

6by9 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aallan commented Oct 18, 2023 • edited Loading

aallan commented Oct 18, 2023

nathan-contino commented Oct 18, 2023

nathan-contino commented Oct 17, 2023 •

edited

Loading

aallan commented Oct 18, 2023 •

edited

Loading