Push to production

Gemfile.lock

@@ -52,12 +52,12 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    mini_portile2 (2.8.2)
+    mini_portile2 (2.8.4)
     minima (2.5.1)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    nokogiri (1.15.3)
+    nokogiri (1.15.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     pathutil (0.16.2)

README.md

@@ -139,7 +139,7 @@ which will delete the `build/` and `documentation/html/` directories.
 If you want to build the Pico C SDK Doxygen documentation alongside the main documentation site you can do so with,
 
 ```
-$ make build_doxygen_doc
+$ make build_doxygen_adoc
 $ make
 ```
 

documentation/asciidoc/accessories/camera.adoc

@@ -2,4 +2,8 @@ include::camera/camera_hardware.adoc[]
 
 include::camera/filters.adoc[]
 
-include::camera/lens.adoc[]
+include::camera/lens.adoc[]
+
+include::camera/synchronous_cameras.adoc[]
+
+include::camera/external_trigger.adoc[]

documentation/asciidoc/accessories/camera/external_trigger.adoc

@@ -0,0 +1,66 @@
+== External Trigger on the GS Camera
+
+The Global Shutter (GS) camera can be triggered externally by pulsing the external trigger (denoted on the board as XTR) connection on the board. Multiple cameras can be connected to the same pulse, allowing for an alternative way to synchronise two cameras.
+
+The exposure time is equal to the low pulse-width time plus an additional 14.26us. i.e. a low pulse of 10000us leads to an exposure time of 10014.26us. Framerate is directly controlled by how often you pulse the pin. A PWM frequency of 30Hz will lead to a framerate of 30 frames per second.
+
+image::images/external_trigger.jpg[alt="Image showing pulse format",width="80%"]
+
+=== Preparation
+
+WARNING: This modification includes removing an SMD soldered part. You should not attempt this modification unless you feel you are competent to complete it. When soldering to the Camera board, please remove the plastic back cover to avoid damaging it.
+
+If your board has transistor Q2 fitted, shown in blue on the image below, you will need to remove R11 from the board, as shown in red. This connects GP0 to XTR and without removal, the camera will not operate in external trigger mode.
+The location of the components is displayed below.
+
+image::images/resistor.jpg[alt="Image showing resistor to be removed",width="80%"]
+
+Next solder a wire to the touchpoint of XTR on the GS Camera board. We can use a Raspberry Pi Pico to provide the trigger. Connect these to the Pico - XTR to any pin. Ground does not need to be connected.
+
+==== Boot up the Raspberry Pi with the camera connected.
+
+Enable external triggering through superuser mode:
+
+[,bash]
+----
+sudo su
+echo 1 > /sys/module/imx296/parameters/trigger_mode
+exit
+----
+
+==== Raspberry Pi Pico Micropython Code
+
+[,python]
+----
+from machine import Pin, PWM
+
+from time import sleep
+
+pwm = PWM(Pin(28))
+
+framerate = 30
+shutter = 6000  # In microseconds
+
+frame_length = 1000000 / framerate
+pwm.freq(framerate)
+
+pwm.duty_u16(int((1 - (shutter - 14) / frame_length) * 65535))
+----
+
+The low pulsewidth is equal to the shutter time, and the frequency of the PWM equals the framerate.
+
+NOTE: In this example Pin 28 is used to connect to the XTR touchpoint on the GS camera board.
+
+=== Operation
+
+Run the code on the Pico, and set the camera running:
+
+[,bash]
+----
+libcamera-hello -t 0 --qt-preview --shutter 3000
+----
+
+A frame should now be generated every time that the Pico pulses the pin. Variable framerate is acceptable, and can be controlled by simply
+varying the duration between pulses. No options need to be passed to libcamera-apps to enable external trigger.
+
+NOTE: When running libcamera apps, you will need to specify a fixed shutter duration (the value does not matter). This will ensure the AGC does not try adjusting camera's shutter speed, which is controlled by the external trigger pulse.

documentation/asciidoc/accessories/camera/synchronous_cameras.adoc

@@ -0,0 +1,100 @@
+== Synchronous Captures
+
+Both the HQ Camera and the Global Shutter Camera, have support for synchronous captures.
+Making use of the XVS pin (Vertical Sync) allows one camera to pulse when a frame capture is initiated.
+The other camera can then listen for this sync pulse, and capture a frame at the same time as the other camera.
+
+=== Using the HQ Camera
+
+For correct operation, both cameras require a 1.65v pull up voltage on the XVS line, which is created by a potential divider through the 3.3v and GND pins on the Raspberry Pi.
+
+image::images/synchronous_camera_wiring.jpg[alt="Image showing potential divider setup",width="50%"]
+
+Connect a potential divider of 2 equally high impedance ( > 1kOhm) resistors to 3v3 and ground, creating 1.65V. This can be connected to either Pi.
+
+Solder the GND and XVS touchpoints of each HQ Camera board to each other.
+
+Connect the XVS wires to the 1.65V potential divider pull up.
+
+==== Boot up both Raspberry Pis
+
+The file `/sys/module/imx477/parameters/trigger_mode` determines which board outputs pulses, or waits to recieve pulses (source and sink).
+This parameter can only be altered in superuser mode.
+
+On the sink, run:
+[,bash]
+----
+sudo su
+echo 2 > /sys/module/imx477/parameters/trigger_mode
+exit
+----
+
+On the source, run:
+[,bash]
+----
+sudo su
+echo 1 > /sys/module/imx477/parameters/trigger_mode
+exit
+----
+
+Start the sink running:
+[,bash]
+----
+libcamera-vid --frames 300 --qt-preview -o sink.h264
+----
+
+Start the source running
+[,bash]
+----
+libcamera-vid --frames 300 --qt-preview -o source.h264
+----
+
+Frames should be synchronous. Use --frames to ensure the same number of frames are captured, and that the recordings are exactly the same length.
+Running the sink first ensures that no frames are missed.
+
+NOTE: The potential divider is needed to pull up the XVS pin to high whilst the source is in an idle state.
+This ensures that no frames are created or lost upon startup. The source whilst initialising goes from LOW to HIGH which can trigger a false frame.
+
+=== Using the GS Camera
+
+NOTE: The Global Shutter (GS) camera can also be operated in a synchonous mode. However, the source camera will record one extra frame. A much better alternative method to ensure that both cameras capture the same amount of frames is to use the xref:camera.adoc#external-trigger-on-the-gs-camera[external trigger method].
+
+To operate as source and sink together, the Global Shutter Cameras also require connection of the XHS (horizontal sync) pins together. However, these do not need connection to a pullup resistor.
+
+Create a potential divider made of 2x 1.5KOhm Resistors to 3v3 and ground, creating 1.65V. This can be connected to either pi.
+
+Solder 2 wires to the XVS touchpoint on each board and connect both of these wires together to the 1.65V potential divider.
+
+Solder the GND of each Camera board to each other. Also solder 2 wires to the XHS touchpoints on each board and connect these. No pullup is needed for XHS pin.
+
+On the boards that you wish to act as sinks, solder the two halves of the MAS pad together. This enters the sensor into sink mode.
+
+==== Boot up both Raspberry Pis
+
+Start the sink running:
+[,bash]
+----
+libcamera-vid --frames 300 -o sync.h264
+----
+Allow a delay before you start the source running (see note below). Needs to be roughly > 2 seconds.
+
+Start the source running:
+[,bash]
+----
+libcamera-vid --frames 299 -o sync.h264
+----
+
+[NOTE]
+=====
+Due to limitations of the IMX296 sensor, we are unable to get the sink to record exactly the same amount of frames as the source.
+**The source will record one extra frame before the sink starts recording.** This will need to be accounted for later in the application.
+Because of this, you need to specify that the sink records one less frame in the '--frames' option.
+
+FFmpeg has the ability to resync these two videos. By dropping the first frame from the source, we then get two recordings of the same frame
+ length and with the same starting point.
+
+[,bash]
+----
+ffmpeg -i source.h264 -vf select="gte(n\, 1)" source.h264
+----
+=====

documentation/asciidoc/accessories/sense-hat/software.adoc

@@ -25,16 +25,11 @@ Finally, a reboot may be required if I2C was disabled or the kernel was not up-t
 
 == Getting started
 
-[.float-group]
---
-image::images/experiment-with-the-sense-hat.png[role="related thumb right",link=https://github.com/raspberrypipress/released-pdfs/raw/main/experiment-with-the-sense-hat.pdf]
 After installation, example code can be found under `/usr/src/sense-hat/examples`.
 
-
-You can find more information on how to use the Sense HAT in the Raspberry Pi Press book https://github.com/raspberrypipress/released-pdfs/raw/main/experiment-with-the-sense-hat.pdf[Experiment with the Sense HAT]. Written by The Raspberry Pi Foundation's Education Team, it is part of the MagPi Essentials series published by Raspberry Pi Press. The book covers the background of the Astro Pi project, and walks you through how to make use of all the Sense HAT features using the xref:sense-hat.adoc#using-the-sense-hat-with-python[Python library]. 
-
-You can download this book as a PDF file for free, it has been released under a Creative Commons https://creativecommons.org/licenses/by-nc-sa/3.0/[Attribution-NonCommercial-ShareAlike] 3.0 Unported (CC BY NC-SA) licence.
---
+[.booklink, booktype="free", link=https://github.com/raspberrypipress/released-pdfs/raw/main/experiment-with-the-sense-hat.pdf, image=image::images/experiment-with-the-sense-hat.png[]]
+=== Further reading
+You can find more information on how to use the Sense HAT in the Raspberry Pi Press book https://github.com/raspberrypipress/released-pdfs/raw/main/experiment-with-the-sense-hat.pdf[Experiment with the Sense HAT]. Written by The Raspberry Pi Foundation's Education Team, it is part of the MagPi Essentials series published by Raspberry Pi Press. The book covers the background of the Astro Pi project, and walks you through how to make use of all the Sense HAT features using the xref:sense-hat.adoc#using-the-sense-hat-with-python[Python library].
 
 === Using the Sense HAT with Python
 

documentation/asciidoc/computers/config_txt/boot.adoc

@@ -111,7 +111,7 @@ This is particularly useful to insert a delay before reading the EDID of the mon
 
 === `boot_delay`
 
-The `boot_delay` command instructs to wait for a given number of seconds in `start.elf` before loading the kernel: the default value is `1`. The total delay in milliseconds is calculated as `(1000 x boot_delay) + boot_delay_ms`. This can be useful if your SD card needs a while to get ready before Linux is able to boot from it.
+The `boot_delay` command instructs to wait for a given number of seconds in `start.elf` before loading the kernel: the default value is `0`. The total delay in milliseconds is calculated as `(1000 x boot_delay) + boot_delay_ms`. This can be useful if your SD card needs a while to get ready before Linux is able to boot from it.
 
 === `boot_delay_ms`
 

documentation/asciidoc/computers/config_txt/misc.adoc

@@ -1,12 +1,5 @@
 == Miscellaneous Options
 
-=== `avoid_warnings`
-
-The xref:configuration.adoc#firmware-warning-icons[warning symbols] can be disabled using this option, although this is not advised.
-
-`avoid_warnings=1` disables the warning overlays.
-`avoid_warnings=2` disables the warning overlays, but additionally allows turbo mode even when low-voltage is present.
-
 === `logging_level`
 
 Sets the VideoCore logging level. The value is a VideoCore-specific bitmask.

documentation/asciidoc/computers/config_txt/overclocking.adoc

@@ -339,8 +339,6 @@ With firmware from 12th September 2016 or later, when the core temperature is be
 
 For the Raspberry Pi 3 Model B+, the PCB technology has been changed to provide better heat dissipation and increased thermal mass. In addition, a soft temperature limit has been introduced, with the goal of maximising the time for which a device can "sprint" before reaching the hard limit at 85°C. When the soft limit is reached, the clock speed is reduced from 1.4GHz to 1.2GHz, and the operating voltage is reduced slightly. This reduces the rate of temperature increase: we trade a short period at 1.4GHz for a longer period at 1.2GHz. By default, the soft limit is 60°C, and this can be changed via the `temp_soft_limit` setting in config.txt.
 
-See the page on xref:configuration.adoc#firmware-warning-icons[warning icons] for more details.
-
 === Monitoring Voltage
 
 It is essential to keep the supply voltage above 4.8V for reliable performance. Note that the voltage from some USB chargers/power supplies can fall as low as 4.2V. This is because they are usually designed to charge a 3.7V LiPo battery, not to supply 5V to a computer.
@@ -349,8 +347,6 @@ To monitor the Raspberry Pi's PSU voltage, you will need to use a multimeter to
 
 If the voltage drops below 4.63V (+-5%), recent versions of the firmware will show a yellow lightning bolt symbol on the display to indicate a lack of power, and a message indicating the low voltage state will be added to the kernel log.
 
-See the page on xref:configuration.adoc#firmware-warning-icons[warning icons] for more details.
-
 === Overclocking Problems
 
 Most overclocking issues show up immediately with a failure to boot. If this occurs, hold down the `shift` key during the next boot. This will temporarily disable all overclocking, allowing you to boot successfully and then edit your settings.

documentation/asciidoc/computers/config_txt/what_is_config_txt.adoc

@@ -44,7 +44,21 @@ Causes the content of the specified file to be inserted into the current file.
 
 For example, adding the line `include extraconfig.txt` to `config.txt` will include the content of `extraconfig.txt` file in the `config.txt` file.
 
-*Include directives are not supported by bootcode.bin or the EEPROM bootloader*
+[NOTE]
+====
+
+*Include directives are not supported by the bootcode.bin or EEPROM bootloaders*.
+
+Settings which are handled by the bootloader and so which will only take effect if they are specified in `config.txt` (rather than any additional included file) are:
+
+* `bootcode_delay`,
+* `gpu_mem`, `gpu_mem_256`, `gpu_mem_512`, `gpu_mem_1024`,
+* `total_mem`,
+* `sdram_freq`,
+* `start_x`, `start_debug`, `start_file`, `fixup_file`,
+* `uart_2ndstage`.
+
+====
 
 ==== Conditional Filtering
 

documentation/asciidoc/computers/configuration.adoc

@@ -28,8 +28,6 @@ include::configuration/kernel-command-line-config.adoc[]
 
 include::configuration/uart.adoc[]
 
-include::configuration/warning-icons.adoc[]
-
 include::configuration/led_blink_warnings.adoc[]
 
 include::configuration/securing-the-raspberry-pi.adoc[]

documentation/asciidoc/computers/linux_kernel/building.adoc

@@ -12,6 +12,8 @@ The instructions below are divided into native builds and cross-compilation; cho
 
 === Building the Kernel Locally
 
+IMPORTANT: Building the 64-bit kernel on the 32-bit distribution of Raspberry Pi OS is a cross-compilation exercise because it requires the installation of the cross-compiler (`gcc-aarch64-linux-gnu`). If you're running the 32-bit distribution of Raspberry Pi OS on a Pi 4B, Pi 400, CM4 or CM4S then you'll be running a 32-bit userland, and 64-bit kernel — so if you want to explicitly build a 32-bit kernel you should set `ARCH=arm`, and to boot this kernel you'll need to set `arm_64bit=0` in `config.txt`. Instructions for <<cross-compiling-the-kernel,cross-compiling the kernel>> can be found later on this page.  
+
 On a Raspberry Pi, first install the latest version of https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit[Raspberry Pi OS]. Then boot your Raspberry Pi, log in, and ensure you're connected to the internet to give you access to the sources.
 
 First install Git and the build dependencies:

documentation/asciidoc/computers/os/using-gpio.adoc

@@ -151,12 +151,7 @@ button.when_pressed = led.on
 button.when_released = led.off
 ----
 
+[.booklink, booktype="free", link=https://github.com/raspberrypipress/released-pdfs/raw/main/simple-electronics-with-gpio-zero.pdf, image=image::images/simple-electronics-with-gpio-zero.jpg[]]
 ==== Going further
 
-[.float-group]
---
-image::images/simple-electronics-with-gpio-zero.jpg[role="related thumb right",link=https://github.com/raspberrypipress/released-pdfs/raw/main/simple-electronics-with-gpio-zero.pdf]
-You can find more information on how to program electronics connected to your Raspberry Pi with the GPIO Zero Python library in the Raspberry Pi Press book https://github.com/raspberrypipress/released-pdfs/raw/main/simple-electronics-with-gpio-zero.pdf[Simple Electronics with GPIO Zero]. Written by Phil King, it is part of the MagPi Essentials series published by Raspberry Pi Press. The book gets you started with the GPIO Zero library, and walks you through how to use it by building a series of projects. 
-
-You can download this book as a PDF file for free, it has been released under a Creative Commons https://creativecommons.org/licenses/by-nc-sa/3.0/[Attribution-NonCommercial-ShareAlike] 3.0 Unported (CC BY NC-SA) licence.
---
+You can find more information on how to program electronics connected to your Raspberry Pi with the GPIO Zero Python library in the Raspberry Pi Press book https://github.com/raspberrypipress/released-pdfs/raw/main/simple-electronics-with-gpio-zero.pdf[Simple Electronics with GPIO Zero]. Written by Phil King, it is part of the MagPi Essentials series published by Raspberry Pi Press. The book gets you started with the GPIO Zero library, and walks you through how to use it by building a series of projects.

documentation/asciidoc/computers/raspberry-pi/frequency-management.adoc

@@ -2,7 +2,7 @@
 
 All Raspberry Pi models perform a degree of thermal management to avoid overheating under heavy load. The SoCs have an internal temperature sensor, which software on the GPU polls to ensure that temperatures do not exceed a predefined limit; this is 85°C on all models. It is possible to set this to a lower value, but not to a higher one. As the device approaches the limit, various frequencies and sometimes voltages used on the chip (ARM, GPU) are reduced. This reduces the amount of heat generated, keeping the temperature under control.
 
-When the core temperature is between 80°C and 85°C, a warning icon showing a red half-filled thermometer will be displayed, and the ARM cores will be progressively throttled back. If the temperature reaches 85°C, an icon showing a fully filled thermometer will be displayed, and both the ARM cores and the GPU will be throttled back. See the page on xref:configuration.adoc#firmware-warning-icons[warning icons] for images of the icons.
+When the core temperature is between 80°C and 85°C the ARM cores will be progressively throttled back. If the temperature reaches 85°C both the ARM cores and the GPU will be throttled back.
 
 For Raspberry Pi 3 Model B+, the PCB technology has been changed to provide better heat dissipation and increased thermal mass. In addition, a soft temperature limit has been introduced, with the goal of maximising the time for which a device can "sprint" before reaching the hard limit at 85°C. When the soft limit is reached, the clock speed is reduced from 1.4GHz to 1.2GHz, and the operating voltage is reduced slightly. This reduces the rate of temperature increase: we trade a short period at 1.4GHz for a longer period at 1.2GHz. By default, the soft limit is 60°C, and this can be changed via the `temp_soft_limit` setting in xref:config_txt.adoc#overclocking-options[config.txt].