From ee37994cf229d7b3db7bf662945f3cce6925b7f8 Mon Sep 17 00:00:00 2001 From: Mike Ryan Date: Mon, 24 Oct 2022 19:51:00 -0700 Subject: [PATCH 01/16] Misspelled word Corrected a misspelled word --- .../asciidoc/accessories/camera/libcamera_apps_intro.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc b/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc index 183abe713..c6e1a081e 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc +++ b/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc @@ -6,7 +6,7 @@ `libcamera` presents a {cpp} API to applications and works at the level of configuring the camera and then allowing an application to request image frames. These image buffers reside in system memory and can be passed directly to still image encoders (such as JPEG) or to video encoders (such as h.264), though such ancillary functions as encoding images or displaying them are strictly beyond the purview of `libcamera` itself. -For this reason Raspberry Pi supplies a small set of example `libcamera-apps`. These are simple applications, built on top of `libcamera`, and are designed largely to emulate the function of the legacy stack built on Broadcom's propretary GPU code (some users will recognise these legacy applications as `raspstill` and `raspivid`). The applications we provide are: +For this reason Raspberry Pi supplies a small set of example `libcamera-apps`. These are simple applications, built on top of `libcamera`, and are designed largely to emulate the function of the legacy stack built on Broadcom's proprietary GPU code (some users will recognise these legacy applications as `raspstill` and `raspivid`). The applications we provide are: * _libcamera-hello_ A simple "hello world" application which starts a camera preview stream and displays it on the screen. * _libcamera-jpeg_ A simple application to run a preview window and then capture high resolution still images. From 26ba0f7e72738de629736bed4d04a3b3bc4c337a Mon Sep 17 00:00:00 2001 From: Tim Gover Date: Wed, 26 Oct 2022 14:03:48 +0100 Subject: [PATCH 02/16] Update OTP section for programming the device specific private key --- .../computers/raspberry-pi/otp-bits.adoc | 16 +++-- .../raspberry-pi/raspberry-pi-industrial.adoc | 68 +++++++++++++++++-- 2 files changed, 71 insertions(+), 13 deletions(-) diff --git a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc index 79893df54..8f7662b7f 100644 --- a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc @@ -30,8 +30,8 @@ NOTE: On BCM2711 the bootmode is defined by the xref:raspberry-pi.adoc#raspberry 18 -- copy of bootmode register + 28 -- serial number + 29 -- ~(serial number) + -30 -- xref:raspberry-pi.adoc#raspberry-pi-revision-codes[revision code]^1^ + -33 - board revision extended - the meaning depends on the board model. + +30 -- xref:raspberry-pi.adoc#raspberry-pi-revision-codes[revision code] ^1^ + +33 -- board revision extended - the meaning depends on the board model. + This is available via device-tree in `/proc/device-tree/chosen/rpi-boardrev-ext` and for testing purposes this OTP value can be temporarily overridden by setting `board_rev_ext` in `config.txt`. * Compute Module 4 @@ -44,11 +44,13 @@ This is available via device-tree in `/proc/device-tree/chosen/rpi-boardrev-ext` * Raspberry Pi 400 ** Bits 0-7: The default keyboard country code used by https://github.com/raspberrypi-ui/piwiz[piwiz] -36-43 - xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer OTP values] + -45 - MPG2 decode key + -46 - WVC1 decode key + -47-55 - Reserved for signed-boot on Compute Module 4 + -64/65 -- MAC address; if set, system will use this in preference to the automatically generated address based on the serial number + +36-43 -- xref:raspberry-pi.adoc#industrial-use-of-the-raspberry-pi[customer OTP values] + +45 -- MPG2 decode key + +46 -- WVC1 decode key + +47-54 -- SHA256 of RSA public key for secure-boot + +55 -- secure-boot flags (reserved for use by the bootloader) + +56-63 -- 256bit device specific private key + +64-65 -- MAC address; if set, system will use this in preference to the automatically generated address based on the serial number + 66 -- advanced boot register (not BCM2711) * Bits 0-6: GPIO for ETH_CLK output pin diff --git a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc index c281fbb67..afae6757f 100644 --- a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc @@ -25,7 +25,7 @@ The vcmailbox application can be used directly from the command line on Raspberr [,bash] ---- -/opt/vc/bin/vcmailbox 0x00010004 8 8 0 0 +vcmailbox 0x00010004 8 8 0 0 ---- which will return something like: @@ -44,7 +44,7 @@ To set the customer OTP values you will need to use the `SET_CUSTOMER_OTP` (0x38 [,bash] ---- -/opt/vc/bin/vcmailbox 0x00038021 [8 + number * 4] [8 + number * 4] [start_num] [number] [value] [value] [value] ... +vcmailbox 0x00038021 [8 + number * 4] [8 + number * 4] [start_num] [number] [value] [value] [value] ... ---- * `start_num` = the first row to program from 0-7 @@ -55,7 +55,7 @@ So, to program OTP customer rows 4, 5, and 6 to 0x11111111, 0x22222222, 0x333333 [,bash] ---- -/opt/vc/bin/vcmailbox 0x00038021 20 20 4 3 0x11111111 0x22222222 0x33333333 +vcmailbox 0x00038021 20 20 4 3 0x11111111 0x22222222 0x33333333 ---- This will then program rows 40, 41, and 42. @@ -64,7 +64,7 @@ To read the values back, you can use: [,bash] ---- -/opt/vc/bin/vcmailbox 0x00030021 20 20 4 3 0 0 0 +vcmailbox 0x00030021 20 20 4 3 0 0 0 ---- which should display: @@ -81,7 +81,7 @@ It is possible to lock the OTP changes to avoid them being edited again. This ca [,bash] ---- -/opt/vc/bin/vcmailbox 0x00038021 8 8 0xffffffff 0xaffe0000 +vcmailbox 0x00038021 8 8 0xffffffff 0xaffe0000 ---- Once locked, the customer OTP values can no longer be altered. Note that this locking operation is irreversible. @@ -92,7 +92,63 @@ It is possible to prevent the customer OTP bits from being read at all. This can [,bash] ---- -/opt/vc/bin/vcmailbox 0x00038021 8 8 0xffffffff 0xaffebabe +vcmailbox 0x00038021 8 8 0xffffffff 0xaffebabe ---- This operation is unlikely to be useful for the vast majority of users, and is irreversible. + +=== Device specific private key +Eight rows of OTP (256bits) are available for use as a device-specific private key. This is intended to support file-system encryption. + +These rows can be programmed and read using similar `vcmailbox` commands to those used for managing customer OTP rows. If +secure-boot / file-system encryption is not required then the device private key rows can be used to store general purpose information. + +* The device private key rows can only be read via the `vcmailbox` command which requires access to `/dev/vcio` which is restricted to the `video` group on Raspberry Pi OS. +* Raspberry Pi computers do not have a hardware protected key store. It is recommended that this feature is used in conjunction with https://github.com/raspberrypi/usbboot/blob/master/secure-boot-example/README.md[secure-boot] in order to restrict access to this data. +* Raspberry Pi OS does not support an encrypted root-filesystem. + +See https://gitlab.com/cryptsetup/cryptsetup[cryptsetup] for more information about open-source disk encryption. + +==== Key programming script `rpi-otp-private-key` +The https://github.com/raspberrypi/usbboot/blob/master/tools/rpi-otp-private-key[rpi-otp-private-key] script wraps the device private key `vcmailbox` APIs in order to make it easier to read/write a key in the same format as OpenSSL. + +Read the key as a 64-byte hex number +[,bash] +---- +rpi-otp-private-key +---- + +Example output +---- +f8dbc7b0a4fcfb1d706e298ac9d0485c2226ce8df7f7596ac77337bd09fbe160 +---- + +Writes a 64-byte randomly generated number to the device private key. + +**Warning: This operation cannot be undone. ** +[,bash] +---- +# rpi-otp-private-key -w $(openssl rand -hex 32) +---- + +==== Mailbox API for reading/writing the key. +Read all of the rows. +[,bash] +---- +vcmailbox 0x00030081 40 40 0 8 0 0 0 0 0 0 0 0 +---- + +Example output +---- +0x00000040 0x80000000 0x00030081 0x00000028 0x80000028 0x00000000 0x00000008 0xf8dbc7b0 0xa4fcfb1d 0x706e298a 0xc9d0485c 0x2226ce8d 0xf7f7596a 0xc77337bd 0x09fbe160 0x00000000 +---- + +Write all of the row (replace the trailing eight zeros with the key data) +[,bash] +---- +vcmailbox 0x00038081 40 40 0 8 0 0 0 0 0 0 0 0 +---- + +Write the key shown in the previous example +---- +vcmailbox 0x38081 40 40 0 8 0xf8dbc7b0 0xa4fcfb1d 0x706e298a 0xc9d0485c 0x2226ce8d 0xf7f7596a 0xc77337bd 0x09fbe160 +---- From aaed2a2585044edb704f5434dba3a646ce161ba7 Mon Sep 17 00:00:00 2001 From: Andrew Scheller Date: Fri, 28 Oct 2022 11:06:20 +0100 Subject: [PATCH 03/16] Minor copy-edits * Tidy up hyphenation around 'bit', following on from comments in #2672 * 64-bit kernel is no longer beta --- documentation/asciidoc/computers/config_txt/video.adoc | 10 +++++----- .../asciidoc/computers/configuration/boot_folder.adoc | 2 +- .../asciidoc/computers/configuration/device-tree.adoc | 4 ++-- .../asciidoc/computers/os/graphics-utilities.adoc | 4 ++-- .../asciidoc/computers/raspberry-pi/otp-bits.adoc | 2 +- .../raspberry-pi/raspberry-pi-industrial.adoc | 4 ++-- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/documentation/asciidoc/computers/config_txt/video.adoc b/documentation/asciidoc/computers/config_txt/video.adoc index 2e690033e..c78ec8d2e 100644 --- a/documentation/asciidoc/computers/config_txt/video.adoc +++ b/documentation/asciidoc/computers/config_txt/video.adoc @@ -1691,25 +1691,25 @@ Use `framebuffer_depth` to specify the console framebuffer depth in bits per pix | framebuffer_depth | result | notes | 8 -| 8bit framebuffer +| 8-bit framebuffer | Default RGB palette makes screen unreadable | 16 -| 16bit framebuffer +| 16-bit framebuffer | | 24 -| 24bit framebuffer +| 24-bit framebuffer | May result in a corrupted display | 32 -| 32bit framebuffer +| 32-bit framebuffer | May need to be used in conjunction with `framebuffer_ignore_alpha=1` |=== ==== `framebuffer_ignore_alpha` -Set `framebuffer_ignore_alpha` to `1` to disable the alpha channel. Can help with the display of a 32bit `framebuffer_depth`. +Set `framebuffer_ignore_alpha` to `1` to disable the alpha channel. Can help with the display of a 32-bit `framebuffer_depth`. ==== `framebuffer_priority` diff --git a/documentation/asciidoc/computers/configuration/boot_folder.adoc b/documentation/asciidoc/computers/configuration/boot_folder.adoc index 27f273f94..62f0eb16c 100644 --- a/documentation/asciidoc/computers/configuration/boot_folder.adoc +++ b/documentation/asciidoc/computers/configuration/boot_folder.adoc @@ -72,7 +72,7 @@ The boot folder will contain various xref:linux_kernel.adoc#kernel[kernel] image | kernel8.img | BCM2837, BCM2711 | Pi Zero 2 W, Pi 2, Pi 3, Pi 4, Pi 400 -| Beta xref:config_txt.adoc#boot-options[64 bit kernel]. Raspberry Pi 2 with BCM2836 does not support 64-bit. +| xref:config_txt.adoc#boot-options[64-bit kernel]. Raspberry Pi 2 with BCM2836 does not support 64-bit kernels. |=== NOTE: The architecture reported by `lscpu` is `armv7l` for systems running a 32-bit kernel (i.e. everything except `kernel8.img`), and `aarch64` for systems running a 64-bit kernel. The `l` in the `armv7l` case refers to the architecture being little-endian, not `LPAE` as is indicated by the `l` in the `kernel7l.img` filename. diff --git a/documentation/asciidoc/computers/configuration/device-tree.adoc b/documentation/asciidoc/computers/configuration/device-tree.adoc index 7661c24de..ca6da4fca 100644 --- a/documentation/asciidoc/computers/configuration/device-tree.adoc +++ b/documentation/asciidoc/computers/configuration/device-tree.adoc @@ -842,7 +842,7 @@ The UTC build time for the EEPROM bootloader. `capabilities` - 32-bit integer -This bit field, which describes the features supported by the current bootloader. This may be used to check whether a feature (e.g. USB boot) is supported before enabling it in the bootloader EEPROM config. +This bit-field describes the features supported by the current bootloader. This may be used to check whether a feature (e.g. USB boot) is supported before enabling it in the bootloader EEPROM config. |=== | Bit | Feature @@ -878,7 +878,7 @@ The UTC update timestamp set by `rpi-eeprom-update`. `signed_boot` - 32-bit integer -If secure-boot is enabled then this bit field will be non-zero. The individual bits indicate the current secure-boot configuration. +If secure-boot is enabled then this bit-field will be non-zero. The individual bits indicate the current secure-boot configuration. |=== | Bit | Description diff --git a/documentation/asciidoc/computers/os/graphics-utilities.adoc b/documentation/asciidoc/computers/os/graphics-utilities.adoc index c527b313d..673e2da99 100644 --- a/documentation/asciidoc/computers/os/graphics-utilities.adoc +++ b/documentation/asciidoc/computers/os/graphics-utilities.adoc @@ -97,7 +97,7 @@ Displays the enabled and detected state of the Raspberry Pi camera: `1` means ye ==== get_throttled -Returns the throttled state of the system. This is a bit pattern - a bit being set indicates the following meanings: +Returns the throttled state of the system. This is a bit-pattern - a bit being set indicates the following meanings: [cols="^,,"] |=== @@ -211,7 +211,7 @@ Displays the current voltages used by the specific block. ==== otp_dump -Displays the content of the OTP (one-time programmable) memory inside the SoC. These are 32 bit values, indexed from 8 to 64. See the xref:raspberry-pi.adoc#otp-register-and-bit-definitions[OTP bits page] for more details. +Displays the content of the OTP (one-time programmable) memory inside the SoC. These are 32-bit values, indexed from 8 to 64. See the xref:raspberry-pi.adoc#otp-register-and-bit-definitions[OTP bits page] for more details. [[getconfig]] ==== get_config [configuration item|int|str] diff --git a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc index 8f7662b7f..737af3202 100644 --- a/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/otp-bits.adoc @@ -49,7 +49,7 @@ This is available via device-tree in `/proc/device-tree/chosen/rpi-boardrev-ext` 46 -- WVC1 decode key + 47-54 -- SHA256 of RSA public key for secure-boot + 55 -- secure-boot flags (reserved for use by the bootloader) + -56-63 -- 256bit device specific private key + +56-63 -- 256-bit device-specific private key + 64-65 -- MAC address; if set, system will use this in preference to the automatically generated address based on the serial number + 66 -- advanced boot register (not BCM2711) diff --git a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc index afae6757f..94719b823 100644 --- a/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/raspberry-pi-industrial.adoc @@ -34,7 +34,7 @@ which will return something like: 0x00000020 0x80000000 0x00010004 0x00000008 0x800000008 0xnnnnnnnn 0x00000000 0x00000000 ---- -The above uses the https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface[mailbox property interface] `GET_BOARD_SERIAL` with a request size of 8 bytes and response size of 8 bytes (sending two integers for the request 0, 0). The response to this will be two integers (0x00000020 and 0x80000000) followed by the tag code, the request length, the response length (with the 31st bit set to indicate that it is a response) then the 64 bit serial number (where the MS 32bits are always 0). +The above uses the https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface[mailbox property interface] `GET_BOARD_SERIAL` with a request size of 8 bytes and response size of 8 bytes (sending two integers for the request 0, 0). The response to this will be two integers (0x00000020 and 0x80000000) followed by the tag code, the request length, the response length (with the 31st bit set to indicate that it is a response) then the 64-bit serial number (where the MS 32 bits are always 0). === Write and Read Customer OTP Values @@ -98,7 +98,7 @@ vcmailbox 0x00038021 8 8 0xffffffff 0xaffebabe This operation is unlikely to be useful for the vast majority of users, and is irreversible. === Device specific private key -Eight rows of OTP (256bits) are available for use as a device-specific private key. This is intended to support file-system encryption. +Eight rows of OTP (256 bits) are available for use as a device-specific private key. This is intended to support file-system encryption. These rows can be programmed and read using similar `vcmailbox` commands to those used for managing customer OTP rows. If secure-boot / file-system encryption is not required then the device private key rows can be used to store general purpose information. From d2819ac99edd68c19be1b906e60aa322fd4e4204 Mon Sep 17 00:00:00 2001 From: Liz Upton Date: Fri, 28 Oct 2022 11:12:41 +0100 Subject: [PATCH 04/16] CE Spot of rewording, dragged capitalisation into line with the Style Guide, added some consistency. --- documentation/index.json | 44 ++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/documentation/index.json b/documentation/index.json index 434ea3737..341dc2b0b 100644 --- a/documentation/index.json +++ b/documentation/index.json @@ -6,26 +6,26 @@ "default_tab": "yes", "subitems": [ { - "title": "Getting Started", - "description": "This is the stuff about how to get started", + "title": "Getting started", + "description": "How to get started with your Raspberry Pi", "image": "full-sized/Getting-Started.png", "subpath": "getting-started.adoc" }, { "title": "Raspberry Pi OS", - "description": "The official OS of Raspberry Pi", + "description": "The official Raspberry Pi operating system", "image": "full-sized/Raspberry-Pi-OS.png", "subpath": "os.adoc" }, { "title": "Configuration", - "description": "Configuring the Raspberry Pi's settings to suit your needs", + "description": "Configuring your Raspberry Pi's settings", "image": "full-sized/Configuration.png", "subpath": "configuration.adoc" }, { "title": "The config.txt file", - "description": "Low-level control of your Raspberry Pi's settings", + "description": "Low-level settings control", "image": "full-sized/The-config-txt-file.png", "subpath": "config_txt.adoc" }, @@ -36,19 +36,19 @@ "subpath": "linux_kernel.adoc" }, { - "title": "Remote Access", + "title": "Remote access", "description": "Accessing your Raspberry Pi remotely", "image": "full-sized/Remote-Access.png", "subpath": "remote-access.adoc" }, { - "title": "Raspberry Pi Hardware", + "title": "Raspberry Pi hardware", "description": "Technical information about Raspberry Pi hardware", "image": "full-sized/Raspberry-Pi-Hardware.png", "subpath": "raspberry-pi.adoc" }, { - "title": "Compute Module Hardware", + "title": "Compute Module hardware", "description": "Technical information about Raspberry Pi Compute Module hardware", "image": "full-sized/Compute-Module-Hardware.png", "subpath": "compute-module.adoc" @@ -60,14 +60,14 @@ "subpath": "processors.adoc" }, { - "title": "PIP", - "description": "The Product Information Portal (PIP) for Raspberry Pi compliance documents", + "title": "Product Information Portal", + "description": "Raspberry Pi compliance documents", "image": "full-sized/PIP.png", "url": "https://pip.raspberrypi.com/" }, { "title": "Datasheets", - "description": "The Datasheets site for PDF-based documentation", + "description": "PDF documentation", "image": "full-sized/Datasheets.png", "url": "https://datasheets.raspberrypi.com" }, @@ -92,7 +92,7 @@ "subitems": [ { "title": "Camera", - "description": "We have several Raspberry Pi cameras", + "description": "Raspberry Pi camera boards", "image": "full-sized/Camera.png", "subpath": "camera.adoc" }, @@ -103,8 +103,8 @@ "subpath": "display.adoc" }, { - "title": "Keyboard & Mouse", - "description": "We have our own keyboard and mouse", + "title": "Keyboard and mouse", + "description": "Official Raspberry Pi keyboard and mouse", "image": "full-sized/Keyboard-and-Mouse.png", "subpath": "keyboard-and-mouse.adoc" }, @@ -128,7 +128,7 @@ }, { "title": "Raspberry Pi Audio", - "description": "Our range of audio HATs", + "description": "High-definition audio with Raspberry Pi", "image": "full-sized/Audio-HATs.png", "subpath": "audio.adoc" }, @@ -139,14 +139,14 @@ "url": "https://github.com/raspberrypi/hats" }, { - "title": "PIP", - "description": "The Product Information Portal (PIP) for Raspberry Pi compliance documents", + "title": "Product Information Portal", + "description": "Raspberry Pi compliance documents", "image": "full-sized/PIP.png", "url": "https://pip.raspberrypi.com/" }, { "title": "Datasheets", - "description": "The Datasheets site for PDF-based documentation", + "description": "PDF-based documentation", "image": "full-sized/Datasheets.png", "url": "https://datasheets.raspberrypi.com" }, @@ -170,7 +170,7 @@ "subitems": [ { "title": "RP2040", - "description": "Our first microcontroller device", + "description": "Raspberry Pi's flagship microcontroller device", "image": "full-sized/RP2040.png", "subpath": "rp2040.adoc" }, @@ -193,14 +193,14 @@ "subpath": "c_sdk.adoc" }, { - "title": "PIP", - "description": "The Product Information Portal (PIP) for Raspberry Pi compliance documents", + "title": "Product Information Portal", + "description": "Raspberry Pi compliance documents", "image": "full-sized/PIP.png", "url": "https://pip.raspberrypi.com/" }, { "title": "Datasheets", - "description": "The Datasheets site for PDF-based documentation", + "description": "PDF-based documentation", "image": "full-sized/Datasheets.png", "url": "https://datasheets.raspberrypi.com" }, From a9497e0d2b77c2253f68acf73c1a507369860107 Mon Sep 17 00:00:00 2001 From: elliott Date: Sat, 29 Oct 2022 06:27:13 +0800 Subject: [PATCH 05/16] Fixing chip name typo. --- .../asciidoc/microcontrollers/raspberry-pi-pico/about_pico.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/asciidoc/microcontrollers/raspberry-pi-pico/about_pico.adoc b/documentation/asciidoc/microcontrollers/raspberry-pi-pico/about_pico.adoc index aee2efbab..94bc631a9 100644 --- a/documentation/asciidoc/microcontrollers/raspberry-pi-pico/about_pico.adoc +++ b/documentation/asciidoc/microcontrollers/raspberry-pi-pico/about_pico.adoc @@ -40,7 +40,7 @@ NOTE: More information on Fritzing is available on the https://fritzing.org/[fri == Raspberry Pi Pico W and Pico WH -Raspberry Pi Pico W adds on-board single-band 2.4GHz wireless interfaces (802.11n) using the Infineon CYW4343 while retaining the Pico form factor. The on-board 2.4GHz wireless interface has the following features: +Raspberry Pi Pico W adds on-board single-band 2.4GHz wireless interfaces (802.11n) using the Infineon CYW43439 while retaining the Pico form factor. The on-board 2.4GHz wireless interface has the following features: * Wireless (802.11n), single-band (2.4 GHz) * WPA3 From e874e8e4d5ad48569dafd70efd1aec38cbffb9c7 Mon Sep 17 00:00:00 2001 From: Alasdair Allan Date: Fri, 21 Oct 2022 14:35:43 +0100 Subject: [PATCH 06/16] Branch to split the camera documentation --- documentation/asciidoc/computers/camera.adoc | 1 + documentation/asciidoc/computers/camera/introduction.adoc | 3 +++ documentation/index.json | 6 ++++++ 3 files changed, 10 insertions(+) create mode 100644 documentation/asciidoc/computers/camera.adoc create mode 100644 documentation/asciidoc/computers/camera/introduction.adoc diff --git a/documentation/asciidoc/computers/camera.adoc b/documentation/asciidoc/computers/camera.adoc new file mode 100644 index 000000000..7eeafa358 --- /dev/null +++ b/documentation/asciidoc/computers/camera.adoc @@ -0,0 +1 @@ +include::camera/introduction.adoc[] diff --git a/documentation/asciidoc/computers/camera/introduction.adoc b/documentation/asciidoc/computers/camera/introduction.adoc new file mode 100644 index 000000000..99b7750cc --- /dev/null +++ b/documentation/asciidoc/computers/camera/introduction.adoc @@ -0,0 +1,3 @@ +== Introducing the camera software + +Foobar \ No newline at end of file diff --git a/documentation/index.json b/documentation/index.json index 341dc2b0b..4a2980910 100644 --- a/documentation/index.json +++ b/documentation/index.json @@ -41,6 +41,12 @@ "image": "full-sized/Remote-Access.png", "subpath": "remote-access.adoc" }, + { + "title": "Camera software", + "description": "Software and libraries for Raspberry Pi camera hardware", + "image": "full-sized/Camera.png", + "subpath": "camera.adoc" + }, { "title": "Raspberry Pi hardware", "description": "Technical information about Raspberry Pi hardware", From 4517454f8e96cbe8db60d83c004a03066d8ab95b Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 10:22:10 +0100 Subject: [PATCH 07/16] Restructure camera documentation Move the camera software documentation into a new section under Computers. Keep the camera hardware documentation in the existing Accessories space. Signed-off-by: Naushir Patuck --- .../asciidoc/accessories/camera.adoc | 65 ------------------ .../accessories/camera/camera_hardware.adoc | 2 +- documentation/asciidoc/computers/camera.adoc | 1 - .../camera/camera_usage.adoc | 6 +- .../camera/csi-2-usage.adoc | 0 .../camera/gstreamer.adoc | 0 .../camera/images/annotate.jpg | Bin .../camera/images/cam.jpg | Bin .../camera/images/cam2.jpg | Bin .../camera/images/classify.jpg | Bin .../camera/images/detection.jpg | Bin .../camera/images/drc.jpg | Bin .../camera/images/face_detect.jpg | Bin .../camera/images/focus.jpg | Bin .../camera/images/hdr.jpg | Bin .../camera/images/negate.jpg | Bin .../camera/images/nodrc.jpg | Bin .../camera/images/nohdr.jpg | Bin .../camera/images/pose.jpg | Bin .../camera/images/preview_window.jpg | Bin .../camera/images/segmentation.jpg | Bin .../camera/images/sobel.jpg | Bin .../camera/images/sobel_negate.jpg | Bin .../camera/libcamera_3rd_party_tuning.adoc | 0 .../camera/libcamera_apps_building.adoc | 4 +- .../camera/libcamera_apps_getting_help.adoc | 0 .../libcamera_apps_getting_started.adoc | 2 +- .../camera/libcamera_apps_intro.adoc | 0 .../camera/libcamera_apps_libav.adoc | 0 .../camera/libcamera_apps_multicam.adoc | 0 .../camera/libcamera_apps_packages.adoc | 4 +- .../libcamera_apps_post_processing.adoc | 6 +- ...libcamera_apps_post_processing_opencv.adoc | 2 +- ...libcamera_apps_post_processing_tflite.adoc | 2 +- ...ibcamera_apps_post_processing_writing.adoc | 0 .../camera/libcamera_apps_writing.adoc | 0 .../camera/libcamera_detect.adoc | 4 +- .../camera/libcamera_differences.adoc | 2 +- .../camera/libcamera_hello.adoc | 4 +- .../camera/libcamera_jpeg.adoc | 0 .../camera/libcamera_known_issues.adoc | 0 .../camera/libcamera_options_common.adoc | 6 +- .../camera/libcamera_options_still.adoc | 0 .../camera/libcamera_options_vid.adoc | 2 +- .../camera/libcamera_python.adoc | 0 .../camera/libcamera_raw.adoc | 0 .../camera/libcamera_software.adoc | 0 .../camera/libcamera_still.adoc | 2 +- .../camera/libcamera_vid.adoc | 2 +- .../{accessories => computers}/camera/qt.adoc | 0 .../camera/raspicam.adoc | 10 +-- .../camera/timelapse.adoc | 2 +- .../camera/v4l2.adoc | 2 +- .../asciidoc/computers/camera_software.adoc | 64 +++++++++++++++++ documentation/index.json | 2 +- 55 files changed, 97 insertions(+), 99 deletions(-) delete mode 100644 documentation/asciidoc/computers/camera.adoc rename documentation/asciidoc/{accessories => computers}/camera/camera_usage.adoc (81%) rename documentation/asciidoc/{accessories => computers}/camera/csi-2-usage.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/gstreamer.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/annotate.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/cam.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/cam2.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/classify.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/detection.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/drc.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/face_detect.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/focus.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/hdr.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/negate.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/nodrc.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/nohdr.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/pose.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/preview_window.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/segmentation.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/sobel.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/images/sobel_negate.jpg (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_3rd_party_tuning.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_building.adoc (96%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_getting_help.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_getting_started.adoc (83%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_intro.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_libav.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_multicam.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_packages.adoc (83%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_post_processing.adoc (95%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_post_processing_opencv.adoc (95%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_post_processing_tflite.adoc (98%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_post_processing_writing.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_apps_writing.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_detect.adoc (70%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_differences.adoc (96%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_hello.adoc (95%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_jpeg.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_known_issues.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_options_common.adoc (98%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_options_still.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_options_vid.adoc (98%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_python.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_raw.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_software.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_still.adoc (97%) rename documentation/asciidoc/{accessories => computers}/camera/libcamera_vid.adoc (96%) rename documentation/asciidoc/{accessories => computers}/camera/qt.adoc (100%) rename documentation/asciidoc/{accessories => computers}/camera/raspicam.adoc (98%) rename documentation/asciidoc/{accessories => computers}/camera/timelapse.adoc (95%) rename documentation/asciidoc/{accessories => computers}/camera/v4l2.adoc (93%) create mode 100644 documentation/asciidoc/computers/camera_software.adoc diff --git a/documentation/asciidoc/accessories/camera.adoc b/documentation/asciidoc/accessories/camera.adoc index ba048b250..e835019ea 100644 --- a/documentation/asciidoc/accessories/camera.adoc +++ b/documentation/asciidoc/accessories/camera.adoc @@ -1,66 +1 @@ -include::camera/camera_usage.adoc[] - include::camera/camera_hardware.adoc[] - -include::camera/libcamera_apps_intro.adoc[] - -include::camera/libcamera_apps_getting_started.adoc[] - -include::camera/libcamera_hello.adoc[] - -include::camera/libcamera_jpeg.adoc[] - -include::camera/libcamera_still.adoc[] - -include::camera/libcamera_vid.adoc[] - -include::camera/libcamera_apps_libav.adoc[] - -include::camera/libcamera_raw.adoc[] - -include::camera/libcamera_detect.adoc[] - -include::camera/libcamera_options_common.adoc[] - -include::camera/libcamera_options_still.adoc[] - -include::camera/libcamera_options_vid.adoc[] - -include::camera/libcamera_differences.adoc[] - -include::camera/libcamera_apps_post_processing.adoc[] - -include::camera/libcamera_apps_post_processing_opencv.adoc[] - -include::camera/libcamera_apps_post_processing_tflite.adoc[] - -include::camera/libcamera_apps_post_processing_writing.adoc[] - -include::camera/libcamera_apps_multicam.adoc[] - -include::camera/libcamera_apps_packages.adoc[] - -include::camera/libcamera_apps_building.adoc[] - -include::camera/libcamera_apps_writing.adoc[] - -include::camera/libcamera_python.adoc[] - -include::camera/libcamera_3rd_party_tuning.adoc[] - -include::camera/libcamera_known_issues.adoc[] - -include::camera/libcamera_apps_getting_help.adoc[] - -include::camera/raspicam.adoc[] - -include::camera/timelapse.adoc[] - -include::camera/gstreamer.adoc[] - -include::camera/qt.adoc[] - -include::camera/v4l2.adoc[] - -include::camera/csi-2-usage.adoc[] - diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index 32d734f35..b5611364b 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -20,7 +20,7 @@ Depending on the model, the camera may come with a small piece of translucent bl Before proceeding, we recommend ensuring that your kernel, GPU firmware and applications are all up to date. Please follow the instructions on xref:../computers/os.adoc#using-apt[keeping your operating system up to date]. -Then, please follow the relevant setup instructions either for xref:camera.adoc#getting-started[`libcamera`] or for xref:camera.adoc#enabling-the-camera[_Raspicam_]. +Then, please follow the relevant setup instructions either for xref:../computers/camera_software.adoc#getting-started[libcamera] or for xref:../computers/camera_software.adoc#enabling-the-camera[Raspicam]. === Hardware Specification diff --git a/documentation/asciidoc/computers/camera.adoc b/documentation/asciidoc/computers/camera.adoc deleted file mode 100644 index 7eeafa358..000000000 --- a/documentation/asciidoc/computers/camera.adoc +++ /dev/null @@ -1 +0,0 @@ -include::camera/introduction.adoc[] diff --git a/documentation/asciidoc/accessories/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc similarity index 81% rename from documentation/asciidoc/accessories/camera/camera_usage.adoc rename to documentation/asciidoc/computers/camera/camera_usage.adoc index 88b196b33..69adb4bca 100644 --- a/documentation/asciidoc/accessories/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -4,13 +4,13 @@ Raspberry Pi currently sell two types of camera board: an https://www.raspberryp All Raspberry Pi cameras are capable of taking high-resolution photographs, along with full HD 1080p video, and can be fully controlled programmatically. This documentation describes how to use the camera in various scenarios, and how to use the various software tools. -Once xref:camera.adoc#installing-a-raspberry-pi-camera[installed], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `libcamera-still` or `raspistill`. +Once xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `libcamera-still` or `raspistill`. === `libcamera` and the legacy _Raspicam_ camera stack [NOTE] ==== -Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. +Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. ==== Users are encouraged to use the newest OS images and the `libcamera`-based stack because: @@ -32,7 +32,7 @@ Reasons to consider staying with an older OS and using the legacy _Raspicam_ sta * It may perform better on Raspberry Pi 2 and Raspberry Pi Zero devices, as it offloads more to the GPU and is less dependent on the ARM cores. * `libcamera` is still missing certain features, most notably Python bindings. Whilst this work is in progress, users who need a Python interface (such as _Picamera_) will have to stay with the legacy stack for the time being. -Apart from some general information on setting up the camera, most of this documentation is divided into sections on xref:camera.adoc#libcamera-and-libcamera-apps[libcamera and the libcamera-apps], and the xref:camera.adoc#raspicam-commands[legacy _Raspicam_ apps]. Once you've xref:camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], please click on one of these two links. +Apart from some general information on setting up the camera, most of this documentation is divided into sections on xref:camera_software.adoc#libcamera-and-libcamera-apps[libcamera and the libcamera-apps], and the xref:camera_software.adoc#raspicam-commands[legacy _Raspicam_ apps]. Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], please click on one of these two links. ==== Re-enabling the legacy stack diff --git a/documentation/asciidoc/accessories/camera/csi-2-usage.adoc b/documentation/asciidoc/computers/camera/csi-2-usage.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/csi-2-usage.adoc rename to documentation/asciidoc/computers/camera/csi-2-usage.adoc diff --git a/documentation/asciidoc/accessories/camera/gstreamer.adoc b/documentation/asciidoc/computers/camera/gstreamer.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/gstreamer.adoc rename to documentation/asciidoc/computers/camera/gstreamer.adoc diff --git a/documentation/asciidoc/accessories/camera/images/annotate.jpg b/documentation/asciidoc/computers/camera/images/annotate.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/annotate.jpg rename to documentation/asciidoc/computers/camera/images/annotate.jpg diff --git a/documentation/asciidoc/accessories/camera/images/cam.jpg b/documentation/asciidoc/computers/camera/images/cam.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/cam.jpg rename to documentation/asciidoc/computers/camera/images/cam.jpg diff --git a/documentation/asciidoc/accessories/camera/images/cam2.jpg b/documentation/asciidoc/computers/camera/images/cam2.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/cam2.jpg rename to documentation/asciidoc/computers/camera/images/cam2.jpg diff --git a/documentation/asciidoc/accessories/camera/images/classify.jpg b/documentation/asciidoc/computers/camera/images/classify.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/classify.jpg rename to documentation/asciidoc/computers/camera/images/classify.jpg diff --git a/documentation/asciidoc/accessories/camera/images/detection.jpg b/documentation/asciidoc/computers/camera/images/detection.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/detection.jpg rename to documentation/asciidoc/computers/camera/images/detection.jpg diff --git a/documentation/asciidoc/accessories/camera/images/drc.jpg b/documentation/asciidoc/computers/camera/images/drc.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/drc.jpg rename to documentation/asciidoc/computers/camera/images/drc.jpg diff --git a/documentation/asciidoc/accessories/camera/images/face_detect.jpg b/documentation/asciidoc/computers/camera/images/face_detect.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/face_detect.jpg rename to documentation/asciidoc/computers/camera/images/face_detect.jpg diff --git a/documentation/asciidoc/accessories/camera/images/focus.jpg b/documentation/asciidoc/computers/camera/images/focus.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/focus.jpg rename to documentation/asciidoc/computers/camera/images/focus.jpg diff --git a/documentation/asciidoc/accessories/camera/images/hdr.jpg b/documentation/asciidoc/computers/camera/images/hdr.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/hdr.jpg rename to documentation/asciidoc/computers/camera/images/hdr.jpg diff --git a/documentation/asciidoc/accessories/camera/images/negate.jpg b/documentation/asciidoc/computers/camera/images/negate.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/negate.jpg rename to documentation/asciidoc/computers/camera/images/negate.jpg diff --git a/documentation/asciidoc/accessories/camera/images/nodrc.jpg b/documentation/asciidoc/computers/camera/images/nodrc.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/nodrc.jpg rename to documentation/asciidoc/computers/camera/images/nodrc.jpg diff --git a/documentation/asciidoc/accessories/camera/images/nohdr.jpg b/documentation/asciidoc/computers/camera/images/nohdr.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/nohdr.jpg rename to documentation/asciidoc/computers/camera/images/nohdr.jpg diff --git a/documentation/asciidoc/accessories/camera/images/pose.jpg b/documentation/asciidoc/computers/camera/images/pose.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/pose.jpg rename to documentation/asciidoc/computers/camera/images/pose.jpg diff --git a/documentation/asciidoc/accessories/camera/images/preview_window.jpg b/documentation/asciidoc/computers/camera/images/preview_window.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/preview_window.jpg rename to documentation/asciidoc/computers/camera/images/preview_window.jpg diff --git a/documentation/asciidoc/accessories/camera/images/segmentation.jpg b/documentation/asciidoc/computers/camera/images/segmentation.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/segmentation.jpg rename to documentation/asciidoc/computers/camera/images/segmentation.jpg diff --git a/documentation/asciidoc/accessories/camera/images/sobel.jpg b/documentation/asciidoc/computers/camera/images/sobel.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/sobel.jpg rename to documentation/asciidoc/computers/camera/images/sobel.jpg diff --git a/documentation/asciidoc/accessories/camera/images/sobel_negate.jpg b/documentation/asciidoc/computers/camera/images/sobel_negate.jpg similarity index 100% rename from documentation/asciidoc/accessories/camera/images/sobel_negate.jpg rename to documentation/asciidoc/computers/camera/images/sobel_negate.jpg diff --git a/documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc b/documentation/asciidoc/computers/camera/libcamera_3rd_party_tuning.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_3rd_party_tuning.adoc rename to documentation/asciidoc/computers/camera/libcamera_3rd_party_tuning.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_building.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc similarity index 96% rename from documentation/asciidoc/accessories/camera/libcamera_apps_building.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_building.adoc index 0f06bb8fc..059fe6362 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_building.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc @@ -32,7 +32,7 @@ If you want to use the Qt preview window, please also execute sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 ---- -Now proceed directly to the instructions for xref:camera.adoc#building-libcamera-apps[building `libcamera-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`). +Now proceed directly to the instructions for xref:camera_software.adoc#building-libcamera-apps[building `libcamera-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`). ==== Building `libcamera` @@ -174,4 +174,4 @@ sudo ldconfig # this is only necessary on the first build NOTE: If you are using an image where `libcamera-apps` have been previously installed as an `apt` package, and you want to run the new `libcamera-apps` executables from the same terminal window where you have just built and installed them, you may need to run `hash -r` to be sure to pick up the new ones over the system supplied ones. -Finally, if you have not already done so, please be sure to follow the `dtoverlay` and display driver instructions in the xref:camera.adoc#getting-started[Getting Started section] (and rebooting if you changed anything there). +Finally, if you have not already done so, please be sure to follow the `dtoverlay` and display driver instructions in the xref:camera_software.adoc#getting-started[Getting Started section] (and rebooting if you changed anything there). diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_getting_help.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_getting_help.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_getting_help.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_getting_help.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_getting_started.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc similarity index 83% rename from documentation/asciidoc/accessories/camera/libcamera_apps_getting_started.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc index bfa0fc325..df9f58825 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_getting_started.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_getting_started.adoc @@ -15,7 +15,7 @@ libcamera-hello You should see a camera preview window for about 5 seconds. -Users running _Buster_ will need to xref:camera.adoc#binary-packages[install one of the `libcamera-apps` packages] first and then configure their `/boot/config.txt` file xref:camera.adoc#if-you-do-need-to-alter-the-configuration[with the appropriate overlay] for the connected camera. Be aware that _libcamera_ and the legacy _raspicam_ stack cannot operate at the same time - to return to the legacy stack after using _libcamera_ you will need to comment out the `dtoverlay` change you made and reboot the system. +Users running _Buster_ will need to xref:camera_software.adoc#binary-packages[install one of the `libcamera-apps` packages] first and then configure their `/boot/config.txt` file xref:camera_software.adoc#if-you-do-need-to-alter-the-configuration[with the appropriate overlay] for the connected camera. Be aware that _libcamera_ and the legacy _raspicam_ stack cannot operate at the same time - to return to the legacy stack after using _libcamera_ you will need to comment out the `dtoverlay` change you made and reboot the system. NOTE: Raspberry Pi 3 and older devices may not by default be using the correct display driver. Refer to the `/boot/config.txt` file and ensure that either `dtoverlay=vc4-fkms-v3d` or `dtoverlay=vc4-kms-v3d` is currently active. Please reboot if you needed to change this. diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_intro.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_intro.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_intro.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_libav.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_libav.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_multicam.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_multicam.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_multicam.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_multicam.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_packages.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc similarity index 83% rename from documentation/asciidoc/accessories/camera/libcamera_apps_packages.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc index 69d892d7e..ef0f9a483 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_packages.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc @@ -10,7 +10,7 @@ There are two `libcamera-apps` packages available, that contain the necessary ex * `libcamera-apps-lite` omits X Windows support and only the DRM preview is available. This package is pre-installed in the _Bullseye_ release of Raspberry Pi OS Lite, and can be installed in _Buster_ using `sudo apt install libcamera-apps-lite`. -For _Bullseye_ users, official Raspberry Pi cameras should be detected automatically. Other users will need to xref:camera.adoc#if-you-do-need-to-alter-the-configuration[edit their `/boot/config.txt`] file if they have not done so previously. +For _Bullseye_ users, official Raspberry Pi cameras should be detected automatically. Other users will need to xref:camera_software.adoc#if-you-do-need-to-alter-the-configuration[edit their `/boot/config.txt`] file if they have not done so previously. ==== Dependencies @@ -30,4 +30,4 @@ These will be installed automatically when needed. * `libepoxy-dev` contains the necessary `libepoxy` header files and resources. You will only need this if you want support for the X11/GLES preview window. -Subsequently `libcamera-apps` can be xref:camera.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from Github and rebuilt]. +Subsequently `libcamera-apps` can be xref:camera_software.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from Github and rebuilt]. diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc similarity index 95% rename from documentation/asciidoc/accessories/camera/libcamera_apps_post_processing.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc index 17e3aefff..fcc0a17f0 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing.adoc @@ -42,13 +42,13 @@ Image analysis stages often prefer to work on reduced resolution images. `libcam Furthermore, with the post-processing framework being completely open, Raspberry Pi welcomes the contribution of new and interesting stages from the community and would be happy to host them in our `libcamera-apps` repository. The stages that are currently available are documented below. -NOTE: The `libcamera-apps` supplied with the operating system will be built without any optional 3rd party libraries (such as OpenCV or TensorFlow Lite), meaning that certain post-processing stages that rely on them will not be enabled. To use these stages, please follow the instructions for xref:camera.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: The `libcamera-apps` supplied with the operating system will be built without any optional 3rd party libraries (such as OpenCV or TensorFlow Lite), meaning that certain post-processing stages that rely on them will not be enabled. To use these stages, please follow the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. ==== `negate` stage The `negate` stage requires no 3rd party libraries. -On a Raspberry Pi 3 device or a Raspberry Pi 4 running a 32-bit OS, it may execute more quickly if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon`. (Please see the xref:camera.adoc#building-libcamera-and-libcamera-apps[build instructions].) +On a Raspberry Pi 3 device or a Raspberry Pi 4 running a 32-bit OS, it may execute more quickly if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon`. (Please see the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[build instructions].) The `negate` stage has no user-configurable parameters. @@ -70,7 +70,7 @@ image::images/negate.jpg[Image with negate] The `hdr` stage implements both HDR (high dynamic range) imaging and DRC (dynamic range compression). The terminology that we use here regards DRC as operating on single images, and HDR works by accumulating multiple under-exposed images and then performing the same algorithm as DRC. -The `hdr` stage has no dependencies on 3rd party libraries, but (like some other stages) may execute more quickly on Raspberry Pi 3 or Raspberry Pi 4 devices running a 32-bit OS if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon` (please see the xref:camera.adoc#building-libcamera-and-libcamera-apps[build instructions]). Specifically, the image accumulation stage will run quicker and result in fewer frame drops, though the tonemapping part of the process is unchanged. +The `hdr` stage has no dependencies on 3rd party libraries, but (like some other stages) may execute more quickly on Raspberry Pi 3 or Raspberry Pi 4 devices running a 32-bit OS if recompiled using `-DENABLE_COMPILE_FLAGS_FOR_TARGET=armv8-neon` (please see the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[build instructions]). Specifically, the image accumulation stage will run quicker and result in fewer frame drops, though the tonemapping part of the process is unchanged. The basic procedure is that we take the image (which in the case of HDR may be multiple images accumulated together) and apply an edge-preserving smoothing filter to generate a low pass (LP) image. We define the high pass (HP) image to be the difference between the LP image and the original. Next we apply a global tonemap to the LP image and add back the HP image. This procedure, in contrast to applying the tonemap directly to the original image, prevents us from squashing and losing all the local contrast in the resulting image. diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_opencv.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc similarity index 95% rename from documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_opencv.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc index 92e08edf7..94ea88f77 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_opencv.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_opencv.adoc @@ -1,6 +1,6 @@ === Post-Processing with OpenCV -NOTE: These stages all require OpenCV to be installed on your system. You may also need to rebuild `libcamera-apps` with OpenCV support - please see the instructions for xref:camera.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: These stages all require OpenCV to be installed on your system. You may also need to rebuild `libcamera-apps` with OpenCV support - please see the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. ==== `sobel_cv` stage diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_tflite.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc similarity index 98% rename from documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_tflite.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc index f5e6af0f1..379762281 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_tflite.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_tflite.adoc @@ -1,6 +1,6 @@ === Post-Processing with TensorFlow Lite -NOTE: These stages require TensorFlow Lite (TFLite) libraries to be installed that export the {cpp} API. Unfortunately the TFLite libraries are not normally distributed conveniently in this form, however, one place where they can be downloaded is https://lindevs.com/install-precompiled-tensorflow-lite-on-raspberry-pi/[lindevs.com]. Please follow the installation instructions given on that page. Subsequently you may need to recompile `libcamera-apps` with TensorFlow Lite support - please follow the instructions for xref:camera.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. +NOTE: These stages require TensorFlow Lite (TFLite) libraries to be installed that export the {cpp} API. Unfortunately the TFLite libraries are not normally distributed conveniently in this form, however, one place where they can be downloaded is https://lindevs.com/install-precompiled-tensorflow-lite-on-raspberry-pi/[lindevs.com]. Please follow the installation instructions given on that page. Subsequently you may need to recompile `libcamera-apps` with TensorFlow Lite support - please follow the instructions for xref:camera_software.adoc#building-libcamera-and-libcamera-apps[building `libcamera-apps` for yourself]. ==== `object_classify_tf` stage diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_writing.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_post_processing_writing.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_post_processing_writing.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_post_processing_writing.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_apps_writing.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_writing.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_apps_writing.adoc rename to documentation/asciidoc/computers/camera/libcamera_apps_writing.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_detect.adoc b/documentation/asciidoc/computers/camera/libcamera_detect.adoc similarity index 70% rename from documentation/asciidoc/accessories/camera/libcamera_detect.adoc rename to documentation/asciidoc/computers/camera/libcamera_detect.adoc index d7522fed8..e6168a89f 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_detect.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_detect.adoc @@ -1,6 +1,6 @@ === `libcamera-detect` -`libcamera-detect` is not supplied by default in any Raspberry Pi OS distribution, but can be built by users who have xref:camera.adoc#post-processing-with-tensorflow-lite[installed TensorFlow Lite]. In this case, please refer to the xref:camera.adoc#building-libcamera-and-libcamera-apps[`libcamera-apps` build instructions]. You will need to run `cmake` with `-DENABLE_TFLITE=1`. +`libcamera-detect` is not supplied by default in any Raspberry Pi OS distribution, but can be built by users who have xref:camera_software.adoc#post-processing-with-tensorflow-lite[installed TensorFlow Lite]. In this case, please refer to the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[`libcamera-apps` build instructions]. You will need to run `cmake` with `-DENABLE_TFLITE=1`. This application runs a preview window and monitors the contents using a Google MobileNet v1 SSD (Single Shot Detector) neural network that has been trained to identify about 80 classes of objects using the Coco dataset. It should recognise people, cars, cats and many other objects. @@ -14,7 +14,7 @@ Detect objects with the given ``. The name should be taken from the model' Wait at least this many frames after a capture before performing another. This is necessary because the neural network does not run on every frame, so it is best to give it a few frames to run again before considering another capture. -Please refer to the xref:camera.adoc#object_detect_tf-stage[TensorFlow Lite object detector] section for more general information on how to obtain and use this model. But as an example, you might spy secretly on your cats while you are away with: +Please refer to the xref:camera_software.adoc#object_detect_tf-stage[TensorFlow Lite object detector] section for more general information on how to obtain and use this model. But as an example, you might spy secretly on your cats while you are away with: [,bash] ---- diff --git a/documentation/asciidoc/accessories/camera/libcamera_differences.adoc b/documentation/asciidoc/computers/camera/libcamera_differences.adoc similarity index 96% rename from documentation/asciidoc/accessories/camera/libcamera_differences.adoc rename to documentation/asciidoc/computers/camera/libcamera_differences.adoc index d01f30c30..4fae4e4f0 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_differences.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_differences.adoc @@ -8,7 +8,7 @@ Whilst the `libcamera-apps` attempt to emulate most features of the legacy _Rasp * `libcamera` performs its own camera mode selection, so the `--mode` option is not supported. It deduces camera modes from the resolutions requested. There is still work ongoing in this area. -* The following features of the legacy apps are not supported as the code has to run on the ARM now. But note that a number of these effects are now provided by the xref:camera.adoc#post-processing[post-processing] mechanism. +* The following features of the legacy apps are not supported as the code has to run on the ARM now. But note that a number of these effects are now provided by the xref:camera_software.adoc#post-processing[post-processing] mechanism. - opacity (`--opacity`) - image effects (`--imxfx`) - colour effects (`--colfx`) diff --git a/documentation/asciidoc/accessories/camera/libcamera_hello.adoc b/documentation/asciidoc/computers/camera/libcamera_hello.adoc similarity index 95% rename from documentation/asciidoc/accessories/camera/libcamera_hello.adoc rename to documentation/asciidoc/computers/camera/libcamera_hello.adoc index 9c1d93eb1..6ca12dc6a 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_hello.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_hello.adoc @@ -21,7 +21,7 @@ The preview can be halted either by clicking the window's close button, or using The options are classified broadly into 3 groups, namely those that are common, those that are specific to still images, and those that are for video encoding. They are supported in an identical manner across all the applications where they apply. -Please refer to the xref:camera.adoc#common-command-line-options[command line options documentation] for a complete list. +Please refer to the xref:camera_software.adoc#common-command-line-options[command line options documentation] for a complete list. ==== The Tuning File @@ -67,4 +67,4 @@ will display the current red and blue gain values. For the HQ camera, use `--info-text "%focus"` to display the focus measure, which will be helpful for focusing the lens. -A full description of the `--info-text` parameter is given in the xref:camera.adoc#common-command-line-options[command line options documentation]. +A full description of the `--info-text` parameter is given in the xref:camera_software.adoc#common-command-line-options[command line options documentation]. diff --git a/documentation/asciidoc/accessories/camera/libcamera_jpeg.adoc b/documentation/asciidoc/computers/camera/libcamera_jpeg.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_jpeg.adoc rename to documentation/asciidoc/computers/camera/libcamera_jpeg.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_known_issues.adoc b/documentation/asciidoc/computers/camera/libcamera_known_issues.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_known_issues.adoc rename to documentation/asciidoc/computers/camera/libcamera_known_issues.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_options_common.adoc b/documentation/asciidoc/computers/camera/libcamera_options_common.adoc similarity index 98% rename from documentation/asciidoc/accessories/camera/libcamera_options_common.adoc rename to documentation/asciidoc/computers/camera/libcamera_options_common.adoc index f7f2a80cc..3e3e4953b 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_options_common.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_options_common.adoc @@ -231,7 +231,7 @@ During video recording (`libcamera-vid`), specifying a low resolution stream wil Example: `libcamera-hello --lores-width 224 --lores-height 224` -Note that the low resolution stream is not particularly useful unless used in conjunction with xref:camera.adoc#post-processing[image post-processing]. +Note that the low resolution stream is not particularly useful unless used in conjunction with xref:camera_software.adoc#post-processing[image post-processing]. ---- --hflip Read out with horizontal mirror @@ -305,7 +305,7 @@ Example: `libcamera-still -o test.jpg --ev 0.3` The shutter time is fixed to the given value. The gain will still be allowed to vary (unless that is also fixed). -Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:camera.adoc#maximum-exposure-times[in this table]. +Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:../accessories/camera.adoc#maximum-exposure-times[in this table]. Using values above these maximums will result in undefined behaviour. Cameras will also have different minimum shutter times, though in practice this is not important as they are all low enough to expose bright scenes appropriately. @@ -467,7 +467,7 @@ Example: `libcamera-vid -t 10000 --flush -o test.h264` The `--post-process-file` option specifies a JSON file that configures the post-processing that the imaging pipeline applies to camera images before they reach the application. It can be thought of as a replacement for the legacy `raspicam` "image effects". -Post-processing is a large topic and admits the use of 3rd party software like OpenCV and TensorFlowLite to analyse and manipulate images. For more information, please refer to the section on xref:camera.adoc#post-processing[post-processing]. +Post-processing is a large topic and admits the use of 3rd party software like OpenCV and TensorFlowLite to analyse and manipulate images. For more information, please refer to the section on xref:camera_software.adoc#post-processing[post-processing]. Example: `libcamera-hello --post-process-file negate.json` diff --git a/documentation/asciidoc/accessories/camera/libcamera_options_still.adoc b/documentation/asciidoc/computers/camera/libcamera_options_still.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_options_still.adoc rename to documentation/asciidoc/computers/camera/libcamera_options_still.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc b/documentation/asciidoc/computers/camera/libcamera_options_vid.adoc similarity index 98% rename from documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc rename to documentation/asciidoc/computers/camera/libcamera_options_vid.adoc index 32408f2bb..14c664f37 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_options_vid.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_options_vid.adoc @@ -49,7 +49,7 @@ This can select how the video frames are encoded. Valid options are: * h264 - use H.264 encoder (the default) * mjpeg - use MJPEG encoder * yuv420 - output uncompressed YUV420 frames. -* libav - use the libav backend to encode audio and video (see the xref:camera.adoc#libav-integration-with-libcamera-vid[libav section] for further details). +* libav - use the libav backend to encode audio and video (see the xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav section] for further details). Examples: diff --git a/documentation/asciidoc/accessories/camera/libcamera_python.adoc b/documentation/asciidoc/computers/camera/libcamera_python.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_python.adoc rename to documentation/asciidoc/computers/camera/libcamera_python.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_raw.adoc b/documentation/asciidoc/computers/camera/libcamera_raw.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_raw.adoc rename to documentation/asciidoc/computers/camera/libcamera_raw.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_software.adoc b/documentation/asciidoc/computers/camera/libcamera_software.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/libcamera_software.adoc rename to documentation/asciidoc/computers/camera/libcamera_software.adoc diff --git a/documentation/asciidoc/accessories/camera/libcamera_still.adoc b/documentation/asciidoc/computers/camera/libcamera_still.adoc similarity index 97% rename from documentation/asciidoc/accessories/camera/libcamera_still.adoc rename to documentation/asciidoc/computers/camera/libcamera_still.adoc index 6c3677d23..c7bd5c5ba 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_still.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_still.adoc @@ -89,4 +89,4 @@ So to perform a 100 second exposure capture, use `libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate` -For reference, the maximum exposure times of the three official Raspberry Pi cameras can be found in xref:camera.adoc#maximum-exposure-times[this table]. +For reference, the maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#maximum-exposure-times[this table]. diff --git a/documentation/asciidoc/accessories/camera/libcamera_vid.adoc b/documentation/asciidoc/computers/camera/libcamera_vid.adoc similarity index 96% rename from documentation/asciidoc/accessories/camera/libcamera_vid.adoc rename to documentation/asciidoc/computers/camera/libcamera_vid.adoc index 4c2e18fad..90db8d2bd 100644 --- a/documentation/asciidoc/accessories/camera/libcamera_vid.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_vid.adoc @@ -38,7 +38,7 @@ Observe that the output file name is normally only sensible if we avoid over-wri ==== Network Streaming -NOTE: This section describes native streaming from `libcamera-vid`. However, it is also possible to use the libav backend for network streaming. See the xref:camera.adoc#libav-integration-with-libcamera-vid[libav section] for further details. +NOTE: This section describes native streaming from `libcamera-vid`. However, it is also possible to use the libav backend for network streaming. See the xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav section] for further details. ===== UDP diff --git a/documentation/asciidoc/accessories/camera/qt.adoc b/documentation/asciidoc/computers/camera/qt.adoc similarity index 100% rename from documentation/asciidoc/accessories/camera/qt.adoc rename to documentation/asciidoc/computers/camera/qt.adoc diff --git a/documentation/asciidoc/accessories/camera/raspicam.adoc b/documentation/asciidoc/computers/camera/raspicam.adoc similarity index 98% rename from documentation/asciidoc/accessories/camera/raspicam.adoc rename to documentation/asciidoc/computers/camera/raspicam.adoc index 2362b1f1b..fe1a5c5ff 100644 --- a/documentation/asciidoc/accessories/camera/raspicam.adoc +++ b/documentation/asciidoc/computers/camera/raspicam.adoc @@ -36,7 +36,7 @@ The display should show a five-second preview from the camera and then take a pi ==== Basic usage of raspistill -With a camera module xref:camera.adoc#camera-modules[connected and enabled], enter the following command in the terminal to take a picture: +With a camera module xref:../accessories/camera.adoc#camera-modules[connected and enabled], enter the following command in the terminal to take a picture: [,bash] ---- @@ -123,14 +123,14 @@ Use the arrow keys to scroll and type `q` to exit. ==== Basic usage of raspivid -With a camera module xref:camera.adoc#camera-modules[connected and enabled], record a video using the following command: +With a camera module xref:../accessories/camera.adoc#camera-modules[connected and enabled], record a video using the following command: [,bash] ---- raspivid -o vid.h264 ---- -Remember to use `-hf` and `-vf` to flip the image if required, like with xref:camera.adoc#raspistill[raspistill] +Remember to use `-hf` and `-vf` to flip the image if required, like with xref:camera_software.adoc#raspistill[raspistill] This will save a 5 second video file to the path given here as `vid.h264` (default length of time). @@ -1362,7 +1362,7 @@ The applications described here will return a standard error code to the shell o === Long Exposures -The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:camera.adoc#maximum-exposure-times[this table]. +The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#maximum-exposure-times[this table]. Due to the way the ISP works, by default asking for a long exposure can result in the capture process taking up to 7 times the exposure time, so a 200 second exposure on the HQ camera could take 1400 seconds to actually return an image. This is due to the way the camera system works out the correct exposures and gains to use in the image, using it's AGC (automatic gain control) and AWB (automatic white balance) algorithms. The system needs a few frames to calculate these numbers in order to produce a decent image. When combined with frame discards at the start of processing (in case they are corrupt), and the switching between preview and captures modes, this can result in up to 7 frames needed to produce a final image. With long exposures, that can take a long time. @@ -1390,7 +1390,7 @@ e.g. `raspistill --encoding png -o fred.png` -Another option is to output completely formatted YUV420 or RGB data using the xref:camera.adoc#raspiyuv[`raspiyuv`] application. +Another option is to output completely formatted YUV420 or RGB data using the xref:camera_software.adoc#raspiyuv[`raspiyuv`] application. ==== Unprocessed Images diff --git a/documentation/asciidoc/accessories/camera/timelapse.adoc b/documentation/asciidoc/computers/camera/timelapse.adoc similarity index 95% rename from documentation/asciidoc/accessories/camera/timelapse.adoc rename to documentation/asciidoc/computers/camera/timelapse.adoc index c3122f9f0..fc7060a79 100644 --- a/documentation/asciidoc/accessories/camera/timelapse.adoc +++ b/documentation/asciidoc/computers/camera/timelapse.adoc @@ -35,7 +35,7 @@ A good way to automate taking a picture at a regular interval is using `cron`. O crontab -e ---- -This will either ask which editor you would like to use, or open in your default editor. Once you have the file open in an editor, add the following line to schedule taking a picture every minute (referring to the Bash script from the xref:camera.adoc#raspistill[raspistill page], though you can use `libcamera-still` in exactly the same way): +This will either ask which editor you would like to use, or open in your default editor. Once you have the file open in an editor, add the following line to schedule taking a picture every minute (referring to the Bash script from the xref:camera_software.adoc#raspistill[raspistill page], though you can use `libcamera-still` in exactly the same way): ---- * * * * * /home/pi/camera.sh 2>&1 diff --git a/documentation/asciidoc/accessories/camera/v4l2.adoc b/documentation/asciidoc/computers/camera/v4l2.adoc similarity index 93% rename from documentation/asciidoc/accessories/camera/v4l2.adoc rename to documentation/asciidoc/computers/camera/v4l2.adoc index dbc91fa29..8238cf11f 100644 --- a/documentation/asciidoc/accessories/camera/v4l2.adoc +++ b/documentation/asciidoc/computers/camera/v4l2.adoc @@ -1,6 +1,6 @@ == V4L2 Drivers -V4L2 drivers provide a standard Linux interface for accessing camera and codec features. They are loaded automatically when the system is started, though in some non-standard situations you may need to xref:camera.adoc#if-you-do-need-to-alter-the-configuration[load camera drivers explicitly]. +V4L2 drivers provide a standard Linux interface for accessing camera and codec features. They are loaded automatically when the system is started, though in some non-standard situations you may need to xref:camera_software.adoc#if-you-do-need-to-alter-the-configuration[load camera drivers explicitly]. === Driver differences when using `libcamera` or the legacy stack diff --git a/documentation/asciidoc/computers/camera_software.adoc b/documentation/asciidoc/computers/camera_software.adoc new file mode 100644 index 000000000..10f91c100 --- /dev/null +++ b/documentation/asciidoc/computers/camera_software.adoc @@ -0,0 +1,64 @@ +include::camera/camera_usage.adoc[] + +include::camera/libcamera_apps_intro.adoc[] + +include::camera/libcamera_apps_getting_started.adoc[] + +include::camera/libcamera_hello.adoc[] + +include::camera/libcamera_jpeg.adoc[] + +include::camera/libcamera_still.adoc[] + +include::camera/libcamera_vid.adoc[] + +include::camera/libcamera_apps_libav.adoc[] + +include::camera/libcamera_raw.adoc[] + +include::camera/libcamera_detect.adoc[] + +include::camera/libcamera_options_common.adoc[] + +include::camera/libcamera_options_still.adoc[] + +include::camera/libcamera_options_vid.adoc[] + +include::camera/libcamera_differences.adoc[] + +include::camera/libcamera_apps_post_processing.adoc[] + +include::camera/libcamera_apps_post_processing_opencv.adoc[] + +include::camera/libcamera_apps_post_processing_tflite.adoc[] + +include::camera/libcamera_apps_post_processing_writing.adoc[] + +include::camera/libcamera_apps_multicam.adoc[] + +include::camera/libcamera_apps_packages.adoc[] + +include::camera/libcamera_apps_building.adoc[] + +include::camera/libcamera_apps_writing.adoc[] + +include::camera/libcamera_python.adoc[] + +include::camera/libcamera_3rd_party_tuning.adoc[] + +include::camera/libcamera_known_issues.adoc[] + +include::camera/libcamera_apps_getting_help.adoc[] + +include::camera/raspicam.adoc[] + +include::camera/timelapse.adoc[] + +include::camera/gstreamer.adoc[] + +include::camera/qt.adoc[] + +include::camera/v4l2.adoc[] + +include::camera/csi-2-usage.adoc[] + diff --git a/documentation/index.json b/documentation/index.json index 4a2980910..74482b940 100644 --- a/documentation/index.json +++ b/documentation/index.json @@ -45,7 +45,7 @@ "title": "Camera software", "description": "Software and libraries for Raspberry Pi camera hardware", "image": "full-sized/Camera.png", - "subpath": "camera.adoc" + "subpath": "camera_software.adoc" }, { "title": "Raspberry Pi hardware", From 9aa40650fb8cf8705566c1931246065686dca955 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 11:33:33 +0100 Subject: [PATCH 08/16] camera: Update maximum exposure times Update the maximum exposure time numbers, and while at it, fold the table into the hardware comparison table above. Signed-off-by: Naushir Patuck --- .../accessories/camera/camera_hardware.adoc | 24 +++++-------------- .../camera/libcamera_options_common.adoc | 2 +- .../computers/camera/libcamera_still.adoc | 2 +- .../asciidoc/computers/camera/raspicam.adoc | 2 +- 4 files changed, 9 insertions(+), 21 deletions(-) diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index b5611364b..bfba2529d 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -141,6 +141,12 @@ Then, please follow the relevant setup instructions either for xref:../computers | 2.9 | 2.0 | Depends on lens + +| Maximum exposure times (seconds) +| 6 +| 11.76 +| 670.74 + |=== === Software Features @@ -211,24 +217,6 @@ The HQ Camera uses a Hoya CM500 infrared filter. Its transmission characteristic image::images/hoyacm500.png[CM500 Transmission Graph] -=== Maximum Exposure Times - -The maximum exposure times of the three official Raspberry Pi cameras are given in the table below. - -[cols=",^"] -|=== -| Module | Max exposure (seconds) - -| V1 (OMx5647) -| 6 - -| V2 (IMX219) -| 10 - -| HQ (IMX477) -| 230 -|=== - === Mechanical Drawings image:images/RPi-S5-conn.png[camera connector] diff --git a/documentation/asciidoc/computers/camera/libcamera_options_common.adoc b/documentation/asciidoc/computers/camera/libcamera_options_common.adoc index 3e3e4953b..13659d5f9 100644 --- a/documentation/asciidoc/computers/camera/libcamera_options_common.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_options_common.adoc @@ -305,7 +305,7 @@ Example: `libcamera-still -o test.jpg --ev 0.3` The shutter time is fixed to the given value. The gain will still be allowed to vary (unless that is also fixed). -Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:../accessories/camera.adoc#maximum-exposure-times[in this table]. +Note that this shutter time may not be achieved if the camera is running at a frame rate that is too fast to allow it. In this case the `--framerate` option may be used to lower the frame rate. The maximum possible shutter times for the official Raspberry Pi supported can be found xref:../accessories/camera.adoc#hardware-specification[in this table]. Using values above these maximums will result in undefined behaviour. Cameras will also have different minimum shutter times, though in practice this is not important as they are all low enough to expose bright scenes appropriately. diff --git a/documentation/asciidoc/computers/camera/libcamera_still.adoc b/documentation/asciidoc/computers/camera/libcamera_still.adoc index c7bd5c5ba..b70c72839 100644 --- a/documentation/asciidoc/computers/camera/libcamera_still.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_still.adoc @@ -89,4 +89,4 @@ So to perform a 100 second exposure capture, use `libcamera-still -o long_exposure.jpg --shutter 100000000 --gain 1 --awbgains 1,1 --immediate` -For reference, the maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#maximum-exposure-times[this table]. +For reference, the maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#hardware-specification[this table]. diff --git a/documentation/asciidoc/computers/camera/raspicam.adoc b/documentation/asciidoc/computers/camera/raspicam.adoc index fe1a5c5ff..5ec0e9618 100644 --- a/documentation/asciidoc/computers/camera/raspicam.adoc +++ b/documentation/asciidoc/computers/camera/raspicam.adoc @@ -1362,7 +1362,7 @@ The applications described here will return a standard error code to the shell o === Long Exposures -The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#maximum-exposure-times[this table]. +The maximum exposure times of the three official Raspberry Pi cameras can be found in xref:../accessories/camera.adoc#hardware-specification[this table]. Due to the way the ISP works, by default asking for a long exposure can result in the capture process taking up to 7 times the exposure time, so a 200 second exposure on the HQ camera could take 1400 seconds to actually return an image. This is due to the way the camera system works out the correct exposures and gains to use in the image, using it's AGC (automatic gain control) and AWB (automatic white balance) algorithms. The system needs a few frames to calculate these numbers in order to produce a decent image. When combined with frame discards at the start of processing (in case they are corrupt), and the switching between preview and captures modes, this can result in up to 7 frames needed to produce a final image. With long exposures, that can take a long time. From 790c065945e33e58d6e2aa84faa1cef0e54c658d Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 12:26:59 +0100 Subject: [PATCH 09/16] camera: Update sensor module table - Remove Linux integration and C programming API rows - Update resolution list for imx219 and imx477 - Add imx477 sensor size Signed-off-by: Naushir Patuck --- .../accessories/camera/camera_hardware.adoc | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index bfba2529d..e74127ed2 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -49,18 +49,8 @@ Then, please follow the relevant setup instructions either for xref:../computers | Video modes | 1080p30, 720p60 and 640 × 480p60/90 -| 1080p30, 720p60 and 640 × 480p60/90 -| 1080p30, 720p60 and 640 × 480p60/90 - -| Linux integration -| V4L2 driver available -| V4L2 driver available -| V4L2 driver available - -| C programming API -| OpenMAX IL and others available -| OpenMAX IL and others available -| +| 1080p47, 1640 × 1232p41 and 640 × 480p60/206 +| 2028 × 1080p50, 2028 × 1520p40 and 1332 × 990p120 | Sensor | OmniVision OV5647 @@ -85,7 +75,7 @@ Then, please follow the relevant setup instructions either for xref:../computers | Optical size | 1/4" | 1/4" -| +| 1/2.3" | Full-frame SLR lens equivalent | 35 mm From 1c406ae7ebea90aa6f7d41d2ddc8611651f3ce0d Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 12:30:05 +0100 Subject: [PATCH 10/16] camera: Remove "Software Features" section This does not belong in any camera documentation section. It ought to be re-instated in a future product sheet or product brief section. Signed-off-by: Naushir Patuck --- .../accessories/camera/camera_hardware.adoc | 64 +------------------ 1 file changed, 1 insertion(+), 63 deletions(-) diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index e74127ed2..aa1341b6e 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -49,7 +49,7 @@ Then, please follow the relevant setup instructions either for xref:../computers | Video modes | 1080p30, 720p60 and 640 × 480p60/90 -| 1080p47, 1640 × 1232p41 and 640 × 480p60/206 +| 1080p47, 1640 × 1232p41 and 640 × 480p206 | 2028 × 1080p50, 2028 × 1520p40 and 1332 × 990p120 | Sensor @@ -139,68 +139,6 @@ Then, please follow the relevant setup instructions either for xref:../computers |=== -=== Software Features - -==== `libcamera` stack - -[cols=2] -|=== - -| Picture formats -| JPEG, JPEG + DNG (raw), BMP, PNG, YUV420, RGB888 - -| Video formats -| raw h.264 (accelerated), MJPEG - -| Post-processing -| User-definable image effects, customisable DRC and HDR, motion detection, OpenCV integration, TensorFlowLite integration - -| Exposure modes -| normal, short, long, fixed fps, customisable - -| Metering modes -| centre-weighted, average, spot, customisable - -| Automatic white balance modes -| off, auto, incandescent, tungsten, fluorescent, indoor, daylight, cloudy, customisable - -| Triggers -| Keypress, UNIX signal, timeout - -| Extra modes -| timelapse, circular buffer, motion detection, segmented video, many features through flexible post-processing -|=== - -==== Legacy stack - -[cols=2] -|=== - -| Picture formats -| JPEG (accelerated), JPEG + RAW, GIF, BMP, PNG, YUV420, RGB888 - -| Video formats -| raw h.264 (accelerated) - -| Effects -| negative, solarise, posterize, whiteboard, blackboard, sketch, denoise, emboss, oilpaint, hatch, gpen, pastel, watercolour, film, blur, saturation - -| Exposure modes -| auto, night, nightpreview, backlight, spotlight, sports, snow, beach, verylong, fixedfps, antishake, fireworks - -| Metering modes -| average, spot, backlit, matrix - -| Automatic white balance modes -| off, auto, sun, cloud, shade, tungsten, fluorescent, incandescent, flash, horizon - -| Triggers -| Keypress, UNIX signal, timeout - -| Extra modes -| demo, burst/timelapse, circular buffer, video with motion vectors, segmented video, live preview on 3D models -|=== - === HQ Camera IR Filter Transmission The HQ Camera uses a Hoya CM500 infrared filter. Its transmission characteristics are as represented in the following graph. From a0a51abbd537df955a166e49b281cfc5c9412b77 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 13:50:55 +0100 Subject: [PATCH 11/16] camera: Remove unused introduction.adoc Signed-off-by: Naushir Patuck --- documentation/asciidoc/computers/camera/introduction.adoc | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 documentation/asciidoc/computers/camera/introduction.adoc diff --git a/documentation/asciidoc/computers/camera/introduction.adoc b/documentation/asciidoc/computers/camera/introduction.adoc deleted file mode 100644 index 99b7750cc..000000000 --- a/documentation/asciidoc/computers/camera/introduction.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== Introducing the camera software - -Foobar \ No newline at end of file From 0240c65ac831d801b3cc5faaa2b9b9b89bb297d9 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Mon, 24 Oct 2022 13:00:35 +0100 Subject: [PATCH 12/16] camera: Minor updates to the camera guide - s/Raspberry Pi is transitioning/Raspberry Pi has transitioned/ - Add audio-samplerate commandline option for libcamera-vid - Add dependencies for libav integration - Add more obvious links between the camera software and modules documents Signed-off-by: Naushir Patuck --- .../asciidoc/accessories/camera/camera_hardware.adoc | 2 +- documentation/asciidoc/computers/camera/camera_usage.adoc | 4 ++-- .../asciidoc/computers/camera/libcamera_apps_building.adoc | 6 ++++++ .../asciidoc/computers/camera/libcamera_apps_libav.adoc | 6 ++++++ 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index aa1341b6e..4ca62a8f2 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -20,7 +20,7 @@ Depending on the model, the camera may come with a small piece of translucent bl Before proceeding, we recommend ensuring that your kernel, GPU firmware and applications are all up to date. Please follow the instructions on xref:../computers/os.adoc#using-apt[keeping your operating system up to date]. -Then, please follow the relevant setup instructions either for xref:../computers/camera_software.adoc#getting-started[libcamera] or for xref:../computers/camera_software.adoc#enabling-the-camera[Raspicam]. +Then, please follow the relevant setup instructions for the xref:../computers/camera_software.adoc#getting-started[libcamera] software stack. === Hardware Specification diff --git a/documentation/asciidoc/computers/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc index 69adb4bca..0954cd7a1 100644 --- a/documentation/asciidoc/computers/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -1,6 +1,6 @@ == Introducing the Raspberry Pi Cameras -Raspberry Pi currently sell two types of camera board: an https://www.raspberrypi.com/products/camera-module-v2/[8MP device] and a https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[12MP High Quality (HQ)] camera. The 8MP device is also available in https://www.raspberrypi.com/products/pi-noir-camera-v2/[NoIR form] without an IR filter. The original 5MP device is no longer available from Raspberry Pi. +Raspberry Pi currently sell two types of camera board: an https://www.raspberrypi.com/products/camera-module-v2/[8MP device] and a https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[12MP High Quality (HQ)] camera. The 8MP device is also available in https://www.raspberrypi.com/products/pi-noir-camera-v2/[NoIR form] without an IR filter. The original 5MP device is no longer available from Raspberry Pi. Further details on the camera modules can be found in the xref:../accessories/camera.adoc#camera-modules[accessories] page. All Raspberry Pi cameras are capable of taking high-resolution photographs, along with full HD 1080p video, and can be fully controlled programmatically. This documentation describes how to use the camera in various scenarios, and how to use the various software tools. @@ -10,7 +10,7 @@ Once xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed] [NOTE] ==== -Raspberry Pi is transitioning from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. +Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. ==== Users are encouraged to use the newest OS images and the `libcamera`-based stack because: diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc index 059fe6362..4c1c8d776 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_building.adoc @@ -32,6 +32,12 @@ If you want to use the Qt preview window, please also execute sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5 ---- +If you want xref:camera_software.adoc#libav-integration-with-libcamera-vid[libav] support in `libcamera-vid`, additional libraries must be installed: + +---- +sudo apt install libavcodec-dev libavdevice-dev libavformat-dev libswresample-dev +---- + Now proceed directly to the instructions for xref:camera_software.adoc#building-libcamera-apps[building `libcamera-apps`]. Raspberry Pi OS Lite users should check that _git_ is installed first (`sudo apt install -y git`). ==== Building `libcamera` diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc index 4b9c30e3f..c54a6064d 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_libav.adoc @@ -37,6 +37,12 @@ Sets the audio encoding bitrate in bits per second. Example: To record audio at 16 kilobits/sec with the mp2 codec use `libcamera-vid --codec libav -o test.mp4 --audio_codec mp2 --audio-bitrate 16384` +---- + --audio-samplerate, Set the audio sampling rate +---- + +Set the audio sampling rate in Hz for encoding. Set to 0 (default) to use the input sample rate. + ---- --audio-device, Chooses an audio recording device to use ---- From 692a447047477472291a025fe6a551535331dfd3 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Tue, 25 Oct 2022 10:18:44 +0100 Subject: [PATCH 13/16] camera: Remove duplicate HQ camera filter removal section Remove the section from the camera hardware document, and include the existing filter removal adoc file to avoid duplicating the contents. Signed-off-by: Naushir Patuck --- .../asciidoc/accessories/camera.adoc | 2 ++ .../accessories/camera/camera_hardware.adoc | 24 ------------------- 2 files changed, 2 insertions(+), 24 deletions(-) diff --git a/documentation/asciidoc/accessories/camera.adoc b/documentation/asciidoc/accessories/camera.adoc index e835019ea..13902c2b6 100644 --- a/documentation/asciidoc/accessories/camera.adoc +++ b/documentation/asciidoc/accessories/camera.adoc @@ -1 +1,3 @@ include::camera/camera_hardware.adoc[] + +include::camera/hqcam_filter_removal.adoc[] diff --git a/documentation/asciidoc/accessories/camera/camera_hardware.adoc b/documentation/asciidoc/accessories/camera/camera_hardware.adoc index 4ca62a8f2..169d72112 100644 --- a/documentation/asciidoc/accessories/camera/camera_hardware.adoc +++ b/documentation/asciidoc/accessories/camera/camera_hardware.adoc @@ -157,27 +157,3 @@ image:images/RPi-S5-conn.png[camera connector] * Camera Module v2 https://datasheets.raspberrypi.com/camera/camera-v2-schematics.pdf[PDF] * HQ Camera Module https://datasheets.raspberrypi.com/hq-camera/hq-camera-schematics.pdf[PDF] - -=== Raspberry Pi HQ Camera Filter Removal - -The High Quality Camera contains an IR filter, which is used to reduce the camera's sensitivity to infrared light. This ensures that outdoor photos look more natural. However, some nature photography can be enhanced with the removal of this filter; the colours of sky, plants, and water can be affected by its removal. The camera can also be used without the filter for night vision in a location that is illuminated with infrared light. - -WARNING: *This procedure cannot be reversed:* the adhesive that attaches the filter will not survive being lifted and replaced, and while the IR filter is about 1.1mm thick, it may crack when it is removed. *Removing it will void the warranty on the product*. Nevertheless, removing the filter will be desirable to some users. - -To remove the filter: - -. Work in a clean and dust-free environment, as the sensor will be exposed to the air. -image:images/rpi_hq_cam_sensor.jpg[camera sensor] -. Unscrew the two 1.5 mm hex lock keys on the underside of the main circuit board. Be careful not to let the washers roll away. There is a gasket of slightly sticky material between the housing and PCB which will require some force to separate. -image:images/rpi_hq_cam_gasket.jpg[camera gasket] -. Lift up the board and place it down on a very clean surface. Make sure the sensor does not touch the surface. -. Before completing the next step, read through all of the steps and decide whether you are willing to void your warranty. *Do not proceed* unless you are sure that you are willing to void your warranty. -. Turn the lens around so that it is "looking" upwards and place it on a table. -You may try some ways to weaken the adhesive, such as a little isopropyl alcohol and/or heat (~20-30 C). Using a pen top or similar soft plastic item, push down on the filter only at the very edges where the glass attaches to the aluminium - to minimise the risk of breaking the filter. The glue will break and the filter will detach from the lens mount. -image:images/rpi_hq_cam_ir_filter.jpg[camera ir filter] -. Given that changing lenses will expose the sensor, at this point you could affix a clear filter (for example, OHP plastic) to minimize the chance of dust entering the sensor cavity. -image:images/rpi_hq_cam_clear_filter.jpg[camera protective filter] -. Replace the main housing over the circuit board. Be sure to realign the housing with the gasket, which remains on the circuit board. -. The nylon washer prevents damage to the circuit board; apply this washer first. Next, fit the steel washer, which prevents damage to the nylon washer. -. Screw down the two hex lock keys. As long as the washers have been fitted in the correct order, they do not need to be screwed very tightly. -. Note that it is likely to be difficult or impossible to glue the filter back in place and return the device to functioning as a normal optical camera. From e5d28ad2974c9ce6c9089ec116cd4ce756bca3a4 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Tue, 25 Oct 2022 10:29:20 +0100 Subject: [PATCH 14/16] camera: Move all legacy Raspicam sections to the end of the document Add a large warning box at the start of the Raspicam section noting that it is now deprecated. Signed-off-by: Naushir Patuck --- .../computers/camera/camera_usage.adoc | 47 +------------------ .../asciidoc/computers/camera/raspicam.adoc | 43 +++++++++++++++++ .../asciidoc/computers/camera_software.adoc | 3 +- 3 files changed, 45 insertions(+), 48 deletions(-) diff --git a/documentation/asciidoc/computers/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc index 0954cd7a1..ed62b1ad8 100644 --- a/documentation/asciidoc/computers/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -4,49 +4,4 @@ Raspberry Pi currently sell two types of camera board: an https://www.raspberryp All Raspberry Pi cameras are capable of taking high-resolution photographs, along with full HD 1080p video, and can be fully controlled programmatically. This documentation describes how to use the camera in various scenarios, and how to use the various software tools. -Once xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `libcamera-still` or `raspistill`. - -=== `libcamera` and the legacy _Raspicam_ camera stack - -[NOTE] -==== -Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. -==== - -Users are encouraged to use the newest OS images and the `libcamera`-based stack because: - -* It will continue to be developed moving forward. -* Raspberry Pi and 3rd parties can fix bugs and problems in the camera stack. -* Raspberry Pi and 3rd parties can add new features to the camera stack. -* It is much easier to add support for new cameras. -* 3rd parties can add support directly for their own cameras. -* Nearly all aspects of the camera tuning can be changed by users. -* It integrates much more conveniently with other standard Linux APIs. -* Raspberry Pi supply a set of `libcamera-apps` which emulate most of the features of the legacy applications. -* It provdes a feature-rich post-processing framework integrating OpenCV and TensorFlow Lite. -* Libcamera makes it easier to control the parameters of the image sensor and the camera system. -* It is fully supported on 64-bit operating systems. - -Reasons to consider staying with an older OS and using the legacy _Raspicam_ stack might include: - -* It may perform better on Raspberry Pi 2 and Raspberry Pi Zero devices, as it offloads more to the GPU and is less dependent on the ARM cores. -* `libcamera` is still missing certain features, most notably Python bindings. Whilst this work is in progress, users who need a Python interface (such as _Picamera_) will have to stay with the legacy stack for the time being. - -Apart from some general information on setting up the camera, most of this documentation is divided into sections on xref:camera_software.adoc#libcamera-and-libcamera-apps[libcamera and the libcamera-apps], and the xref:camera_software.adoc#raspicam-commands[legacy _Raspicam_ apps]. Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], please click on one of these two links. - -==== Re-enabling the legacy stack - -The legacy camera stack can be re-enabled in Bullseye using the following steps. - -1. Ensure your system is up-to-date and reboot it. -2. Run `sudo raspi-config`. -3. Navigate to `Interface Options` and select `Legacy camera` to enable it. -4. Reboot your Raspberry Pi again. - -These steps are shown in the following video. - -video::E7KPSc_Xr24[youtube] - -NOTE: More information can be found in the https://www.raspberrypi.com/news/bullseye-camera-system/[blog post] discussing the transition. - -WARNING: The legacy camera stack cannot be re-enabled on a 64-bit Raspberry Pi OS release. +Once you've xref:../accessories/camera.adoc#installing-a-raspberry-pi-camera[installed your camera module], there are various ways the cameras can be used. The simplest option is to use one of the provided camera applications, such as `libcamera-still` or `libcamera-vid`. diff --git a/documentation/asciidoc/computers/camera/raspicam.adoc b/documentation/asciidoc/computers/camera/raspicam.adoc index 5ec0e9618..fa815fbee 100644 --- a/documentation/asciidoc/computers/camera/raspicam.adoc +++ b/documentation/asciidoc/computers/camera/raspicam.adoc @@ -1,3 +1,46 @@ +== Raspicam applications + +[WARNING] +==== +Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. As such, the _Raspicam_ stack is now deprecated. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. +==== + +Users are encouraged to use the newest OS images and the `libcamera`-based stack because: + +* It will continue to be developed moving forward. +* Raspberry Pi and 3rd parties can fix bugs and problems in the camera stack. +* Raspberry Pi and 3rd parties can add new features to the camera stack. +* It is much easier to add support for new cameras. +* 3rd parties can add support directly for their own cameras. +* Nearly all aspects of the camera tuning can be changed by users. +* It integrates much more conveniently with other standard Linux APIs. +* Raspberry Pi supply a set of `libcamera-apps` which emulate most of the features of the legacy applications. +* It provdes a feature-rich post-processing framework integrating OpenCV and TensorFlow Lite. +* Libcamera makes it easier to control the parameters of the image sensor and the camera system. +* It is fully supported on 64-bit operating systems. + +Reasons to consider staying with an older OS and using the legacy _Raspicam_ stack might include: + +* It may perform better on Raspberry Pi 2 and Raspberry Pi Zero devices, as it offloads more to the GPU and is less dependent on the ARM cores. +* `libcamera` is still missing certain features, most notably Python bindings. Whilst this work is in progress, users who need a Python interface (such as _Picamera_) will have to stay with the legacy stack for the time being. + +== Re-enabling the legacy stack + +The legacy camera stack can be re-enabled in Bullseye using the following steps. + +1. Ensure your system is up-to-date and reboot it. +2. Run `sudo raspi-config`. +3. Navigate to `Interface Options` and select `Legacy camera` to enable it. +4. Reboot your Raspberry Pi again. + +These steps are shown in the following video. + +video::E7KPSc_Xr24[youtube] + +NOTE: More information can be found in the https://www.raspberrypi.com/news/bullseye-camera-system/[blog post] discussing the transition. + +WARNING: The legacy camera stack cannot be re-enabled on a 64-bit Raspberry Pi OS release. + == Raspicam commands `raspistill`, `raspivid` and `raspiyuv` are command line tools for using the camera module. diff --git a/documentation/asciidoc/computers/camera_software.adoc b/documentation/asciidoc/computers/camera_software.adoc index 10f91c100..ecc66032f 100644 --- a/documentation/asciidoc/computers/camera_software.adoc +++ b/documentation/asciidoc/computers/camera_software.adoc @@ -50,8 +50,6 @@ include::camera/libcamera_known_issues.adoc[] include::camera/libcamera_apps_getting_help.adoc[] -include::camera/raspicam.adoc[] - include::camera/timelapse.adoc[] include::camera/gstreamer.adoc[] @@ -62,3 +60,4 @@ include::camera/v4l2.adoc[] include::camera/csi-2-usage.adoc[] +include::camera/raspicam.adoc[] From e0ea289a657438e10ba3821f3c142a2116d772f1 Mon Sep 17 00:00:00 2001 From: Naushir Patuck Date: Fri, 28 Oct 2022 09:07:49 +0100 Subject: [PATCH 15/16] camera: Some minor review tidy-ups - s/accessories/camera hardware/ - s/Github/GitHub/ - Remove the sentence about Python bindings missing in libcamera Signed-off-by: Naushir Patuck --- documentation/asciidoc/computers/camera/camera_usage.adoc | 2 +- .../asciidoc/computers/camera/libcamera_apps_packages.adoc | 2 +- documentation/asciidoc/computers/camera/raspicam.adoc | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/documentation/asciidoc/computers/camera/camera_usage.adoc b/documentation/asciidoc/computers/camera/camera_usage.adoc index ed62b1ad8..0b908cc24 100644 --- a/documentation/asciidoc/computers/camera/camera_usage.adoc +++ b/documentation/asciidoc/computers/camera/camera_usage.adoc @@ -1,6 +1,6 @@ == Introducing the Raspberry Pi Cameras -Raspberry Pi currently sell two types of camera board: an https://www.raspberrypi.com/products/camera-module-v2/[8MP device] and a https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[12MP High Quality (HQ)] camera. The 8MP device is also available in https://www.raspberrypi.com/products/pi-noir-camera-v2/[NoIR form] without an IR filter. The original 5MP device is no longer available from Raspberry Pi. Further details on the camera modules can be found in the xref:../accessories/camera.adoc#camera-modules[accessories] page. +Raspberry Pi currently sell two types of camera board: an https://www.raspberrypi.com/products/camera-module-v2/[8MP device] and a https://www.raspberrypi.com/products/raspberry-pi-high-quality-camera/[12MP High Quality (HQ)] camera. The 8MP device is also available in https://www.raspberrypi.com/products/pi-noir-camera-v2/[NoIR form] without an IR filter. The original 5MP device is no longer available from Raspberry Pi. Further details on the camera modules can be found in the xref:../accessories/camera.adoc#camera-modules[camera hardware] page. All Raspberry Pi cameras are capable of taking high-resolution photographs, along with full HD 1080p video, and can be fully controlled programmatically. This documentation describes how to use the camera in various scenarios, and how to use the various software tools. diff --git a/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc b/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc index ef0f9a483..4c8f8738d 100644 --- a/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc +++ b/documentation/asciidoc/computers/camera/libcamera_apps_packages.adoc @@ -30,4 +30,4 @@ These will be installed automatically when needed. * `libepoxy-dev` contains the necessary `libepoxy` header files and resources. You will only need this if you want support for the X11/GLES preview window. -Subsequently `libcamera-apps` can be xref:camera_software.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from Github and rebuilt]. +Subsequently `libcamera-apps` can be xref:camera_software.adoc#building-libcamera-apps-without-rebuilding-libcamera[checked out from GitHub and rebuilt]. diff --git a/documentation/asciidoc/computers/camera/raspicam.adoc b/documentation/asciidoc/computers/camera/raspicam.adoc index fa815fbee..32c9c82f8 100644 --- a/documentation/asciidoc/computers/camera/raspicam.adoc +++ b/documentation/asciidoc/computers/camera/raspicam.adoc @@ -2,7 +2,7 @@ [WARNING] ==== -Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. As such, the _Raspicam_ stack is now deprecated. Raspberry Pi OS images from _Bullseye_ onwards will contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ will contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. +Raspberry Pi has transitioned from a legacy camera software stack based on proprietary Broadcom GPU code to an open-source stack based on `libcamera`. As such, the _Raspicam_ stack is now deprecated. Raspberry Pi OS images from _Bullseye_ onwards contain *only* the `libcamera`-based stack. Raspberry Pi OS images up to and including _Buster_ still contain the legacy _Raspicam_ stack, though the `libcamera` stack and applications can be installed xref:camera_software.adoc#libcamera-and-libcamera-apps-packages[using _apt_], or built by following the xref:camera_software.adoc#building-libcamera-and-libcamera-apps[normal build instructions]. ==== Users are encouraged to use the newest OS images and the `libcamera`-based stack because: @@ -22,7 +22,6 @@ Users are encouraged to use the newest OS images and the `libcamera`-based stack Reasons to consider staying with an older OS and using the legacy _Raspicam_ stack might include: * It may perform better on Raspberry Pi 2 and Raspberry Pi Zero devices, as it offloads more to the GPU and is less dependent on the ARM cores. -* `libcamera` is still missing certain features, most notably Python bindings. Whilst this work is in progress, users who need a Python interface (such as _Picamera_) will have to stay with the legacy stack for the time being. == Re-enabling the legacy stack From 2f359a054499c07edd197af31626731190677b4b Mon Sep 17 00:00:00 2001 From: Alasdair Allan Date: Mon, 31 Oct 2022 15:05:28 +0000 Subject: [PATCH 16/16] smaller --- .../camera/hqcam_filter_removal.adoc | 38 +++++++++++-------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/documentation/asciidoc/accessories/camera/hqcam_filter_removal.adoc b/documentation/asciidoc/accessories/camera/hqcam_filter_removal.adoc index 666421816..78124773a 100644 --- a/documentation/asciidoc/accessories/camera/hqcam_filter_removal.adoc +++ b/documentation/asciidoc/accessories/camera/hqcam_filter_removal.adoc @@ -6,18 +6,26 @@ WARNING: *This procedure cannot be reversed:* the adhesive that attaches the fil To remove the filter: -. Work in a clean and dust-free environment, as the sensor will be exposed to the air. -image:images/rpi_hq_cam_sensor.jpg[camera sensor] -. Unscrew the two 1.5 mm hex lock keys on the underside of the main circuit board. Be careful not to let the washers roll away. There is a gasket of slightly sticky material between the housing and PCB which will require some force to separate. -image:images/rpi_hq_cam_gasket.jpg[camera gasket] -. Lift up the board and place it down on a very clean surface. Make sure the sensor does not touch the surface. -. Before completing the next step, read through all of the steps and decide whether you are willing to void your warranty. *Do not proceed* unless you are sure that you are willing to void your warranty. -. Turn the lens around so that it is "looking" upwards and place it on a table. -You may try some ways to weaken the adhesive, such as a little isopropyl alcohol and/or heat (~20-30 C). Using a pen top or similar soft plastic item, push down on the filter only at the very edges where the glass attaches to the aluminium - to minimise the risk of breaking the filter. The glue will break and the filter will detach from the lens mount. -image:images/rpi_hq_cam_ir_filter.jpg[camera ir filter] -. Given that changing lenses will expose the sensor, at this point you could affix a clear filter (for example, OHP plastic) to minimize the chance of dust entering the sensor cavity. -image:images/rpi_hq_cam_clear_filter.jpg[camera protective filter] -. Replace the main housing over the circuit board. Be sure to realign the housing with the gasket, which remains on the circuit board. -. The nylon washer prevents damage to the circuit board; apply this washer first. Next, fit the steel washer, which prevents damage to the nylon washer. -. Screw down the two hex lock keys. As long as the washers have been fitted in the correct order, they do not need to be screwed very tightly. -. Note that it is likely to be difficult or impossible to glue the filter back in place and return the device to functioning as a normal optical camera. +* Work in a clean and dust-free environment, as the sensor will be exposed to the air. + +image:images/rpi_hq_cam_sensor.jpg[camera sensor, width="70%"] + +* Unscrew the two 1.5 mm hex lock keys on the underside of the main circuit board. Be careful not to let the washers roll away. There is a gasket of slightly sticky material between the housing and PCB which will require some force to separate. + +image:images/rpi_hq_cam_gasket.jpg[camera gasket, width="70%"] + +* Lift up the board and place it down on a very clean surface. Make sure the sensor does not touch the surface. +* Before completing the next step, read through all of the steps and decide whether you are willing to void your warranty. *Do not proceed* unless you are sure that you are willing to void your warranty. +* Turn the lens around so that it is "looking" upwards and place it on a table. +* ou may try some ways to weaken the adhesive, such as a little isopropyl alcohol and/or heat (~20-30 C). Using a pen top or similar soft plastic item, push down on the filter only at the very edges where the glass attaches to the aluminium - to minimise the risk of breaking the filter. The glue will break and the filter will detach from the lens mount. + +image:images/rpi_hq_cam_ir_filter.jpg[camera ir filter, width="70%"] + +* Given that changing lenses will expose the sensor, at this point you could affix a clear filter (for example, OHP plastic) to minimize the chance of dust entering the sensor cavity. + +image:images/rpi_hq_cam_clear_filter.jpg[camera protective filter, width="70%"] + +* Replace the main housing over the circuit board. Be sure to realign the housing with the gasket, which remains on the circuit board. +* The nylon washer prevents damage to the circuit board; apply this washer first. Next, fit the steel washer, which prevents damage to the nylon washer. +* Screw down the two hex lock keys. As long as the washers have been fitted in the correct order, they do not need to be screwed very tightly. +* Note that it is likely to be difficult or impossible to glue the filter back in place and return the device to functioning as a normal optical camera.