Fix HAT+ specification link and clean up a lot of code blocks, sectio…

…n titles, and more

documentation/asciidoc/accessories/audio.adoc

@@ -1,4 +1,3 @@
-
 include::audio/introduction.adoc[]
 
 include::audio/dac_pro.adoc[]
@@ -16,4 +15,3 @@ include::audio/getting_started.adoc[]
 include::audio/hardware-info.adoc[]
 
 include::audio/update-firmware.adoc[]
-

documentation/asciidoc/accessories/audio/codec_zero.adoc

@@ -22,6 +22,7 @@ The Codec Zero includes an EEPROM which can be used for auto-configuration of th
 In addition to the green (GPIO23) and red (GPIO24) LEDs, a tactile programmable button (GPIO27) is also provided.
 
 ==== Pinouts
+
 [cols="1,12"]
 |===
 | *P1/2* | Support external PHONO/RCA sockets if needed. P1: AUX IN, P2: AUX OUT.

documentation/asciidoc/accessories/audio/configuration.adoc

@@ -15,6 +15,7 @@ $ sudo nano /boot/firmware/config.txt
 
 Find the `dtparam=audio=on` line in the file and comment it out by placing a # symbol at the start of the line. Anything written after the # symbol in any given line will be disregarded by the program. Your `/boot/firmware/config.txt` file should now contain the following entry:
 
+[source,ini]
 ----
 #dtparam=audio=on
 ----
@@ -28,7 +29,7 @@ $ sudo reboot
 
 Alternatively, the `/boot/firmware/config.txt` file can be edited directly onto the Raspberry Pi's microSD card, inserted into your usual computer. Using the default file manager, open the `/boot/firmware/` volume on the card and edit the `config.txt` file using an appropriate text editor, then save the file, eject the microSD card and reinsert it back into your Raspberry Pi.
 
-=== Attaching the HAT
+=== Attach the HAT
 
 The Raspberry Pi audio boards attach to the Raspberry Pi’s 40-pin header. They are designed to be supported on the Raspberry Pi using the supplied circuit board standoffs and screws. No soldering is required on the Raspberry Pi audio boards for normal operation unless you are using hardwired connections for specific connectors such as XLR (External Line Return) connections on the DAC Pro.
 
@@ -45,6 +46,7 @@ $ grep -a . /proc/device-tree/hat/*
 
 If the vendor string says "Raspberry Pi Ltd." then no further action is needed (but see below for the extra Codec Zero configuration). If it says "IQaudIO Limited www.iqaudio.com" then you will need the additional config.txt settings outlined below. If it says "No such file or directory" then the HAT is not being detected, but these config.txt settings may still make it work.
 
+[source,ini]
 ----
 # Some magic to prevent the normal HAT overlay from being loaded
 dtoverlay=
@@ -103,8 +105,9 @@ In order for your project to operate with your required settings when it is powe
 $ sudo nano /etc/rc.local
 ----
 
-Add the chosen script command above the exit 0 line and then Ctrl X, Y and Enter to save. The file should now look similar to this depending on your chosen setting:
+Add the chosen script command above the exit 0 line and then *Ctrl X*, *Y* and *Enter* to save. The file should now look similar to this depending on your chosen setting:
 
+[source,bash]
 ----
 #!/bin/sh -e
 #
@@ -154,7 +157,7 @@ Press `Ctrl+X`, then the `Y` key, then *Enter* to save. Reboot once more to comp
 $ sudo reboot
 ----
 
-=== Muting and unmuting the DigiAMP{plus}
+=== Mute and unmute the DigiAMP{plus}
 
 The DigiAMP{plus} mute state is toggled by GPIO22 on Raspberry Pi. The latest audio device tree
 supports the unmute of the DigiAMP{plus} through additional parameters.
@@ -163,12 +166,14 @@ Firstly a "one-shot" unmute when kernel module loads.
 
 For Raspberry Pi boards:
 
+[source,ini]
 ----
 dtoverlay=rpi-digiampplus,unmute_amp
 ----
 
 For IQaudIO boards:
 
+[source,ini]
 ----
 dtoverlay=iqaudio-digiampplus,unmute_amp
 ----
@@ -179,12 +184,14 @@ window will cancel mute.)
 
 For Raspberry Pi boards:
 
+[source,ini]
 ----
 dtoverlay=rpi-digiampplus,auto_mute_amp
 ----
 
 For IQaudIO boards:
 
+[source,ini]
 ----
 dtoverlay=iqaudio-digiampplus,auto_mute_amp
 ----
@@ -201,7 +208,7 @@ $ sudo sh -c "echo out >/sys/class/gpio/gpio22/direction"
 $ sudo sh -c "echo 1 >/sys/class/gpio/gpio22/value"
 ----
 
-to mute the amp once more:
+To mute the amp once more:
 
 [source,console]
 ----

documentation/asciidoc/accessories/audio/dac_plus.adoc

@@ -7,6 +7,7 @@ image::images/DAC+_Board_Diagram.jpg[width="80%"]
 A Texas Instruments PCM5122 is used in the DAC{plus} to deliver analogue audio to the phono connectors of the device. It also supports a dedicated headphone amplifier and is powered via the Raspberry Pi through the GPIO header.
 
 ==== Pinouts
+
 [cols="1,12"]
 |===
 | *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right

documentation/asciidoc/accessories/audio/dac_pro.adoc

@@ -11,6 +11,7 @@ dedicated headphone amplifier. The DAC Pro is powered by a Raspberry Pi through
 As part of the DAC Pro, two three-pin headers (P7/P9) are exposed above the Raspberry Pi's USB and Ethernet ports for use by the optional XLR board, allowing differential/balanced output.
 
 ==== Pinouts
+
 [cols="1,12"]
 |===
 | *P1* | Analogue out (0-2V RMS), carries GPIO27, MUTE signal (headphone detect), left and right

documentation/asciidoc/accessories/audio/digiamp_plus.adoc

@@ -6,7 +6,7 @@ DigiAMP{plus} uses the Texas Instruments TAS5756M PowerDAC and must be powered f
 
 image::images/DigiAMP+_Board_Diagram.jpg[width="80%"]
 
-DigiAMP{plus}’s power in barrel connector is 5.5mm x 2.5mm. 
+DigiAMP{plus}’s power in barrel connector is 5.5mm × 2.5mm.
 
 At power-on, the amplifier is muted by default (the mute LED is illuminated). Software is responsible for the mute state and LED control (Raspberry Pi GPIO22).
 

documentation/asciidoc/accessories/audio/getting_started.adoc

@@ -1,6 +1,6 @@
 == Getting started
 
-=== Creating a toy chatter box
+=== Create a toy chatter box
 
 As an example of what Raspberry Pi Audio Boards can do, let's walk through the creation of a toy chatter box. Its on-board microphone, programmable button and speaker driver make the Codec Zero an ideal choice for this application. 
 
@@ -16,13 +16,13 @@ image::images/Chatterbox_Labels.png[width="80%"]
 
 Use a small flat-head screwdriver to attach your speaker to the screw terminals. For the additional push button, solder the button wires directly to the Codec Zero pads as indicated, using GPIO pin 27 and Ground for the switch, and +3.3V and Ground for the LED, if necessary. 
 
-=== Setting up your Raspberry Pi
+=== Set up your Raspberry Pi
 
 In this example, we are using Raspberry Pi OS Lite. Refer to our guide on xref:../computers/getting-started.adoc#installing-the-operating-system[installing Raspberry Pi OS] for more details.
 
 Make sure that you update your operating system before proceeding and follow the instructions provided for Codec Zero configuration, including the commands to enable the on-board microphone and speaker output.
 
-=== Programming your Raspberry Pi
+=== Program your Raspberry Pi
 
 Open a shell — for instance by connecting via SSH — on your Raspberry Pi and run the following to create our Python script:
 
@@ -106,12 +106,14 @@ pause()
 
 Press `Ctrl+X`, then the `Y` key, then *Enter* to save. To make the script executable, type the following:
 
+[source,console]
 ----
 $ sudo chmod +x chatter_box.py
 ----
 
-Enter the following to create a crontab daemon that will automatically start the script each time the device is powered on:
+Next, we need to create a crontab daemon that will automatically start the script each time the device is powered on. Run the following command to open your crontab for editing:
 
+[source,console]
 ----
 $ crontab -e
 ----
@@ -122,9 +124,9 @@ You will be asked to select an editor; we recommend you use `nano`. Select it by
 @reboot python /home/<username>/chatter_box.py
 ----
 
-Ctrl X, Y and Enter to save, then reboot your device. 
+Press *Ctrl X*, then *Y*, then *Enter* to save, then reboot your device with `sudo reboot`.
 
-=== Operating your device
+=== Use the toy chatter box
 
 The final step is to ensure that everything is operating as expected. Press the button and release it when you hear the burp. The recording will now begin for a period of five seconds. Once you have released the button, press it briefly again to hear the recording. Repeat this process as many times as you wish, and your sounds will be played at random. You can delete all recordings by pressing and holding the button, keeping the button pressed during the first burp and recording process, and releasing it after at least 20 seconds, at which point you will hear another burp sound confirming that the recordings have been deleted.
 

documentation/asciidoc/accessories/audio/hardware-info.adoc

@@ -52,6 +52,7 @@ image::images/pin_out_new.jpg[width="80%"]
 
 To store the AlsaMixer settings, add the following at the command line:
 
+[source,console]
 ----
 $ sudo alsactl store
 ----
@@ -67,6 +68,7 @@ $ sudo alsactl store -f /home/<username>/usecase.state
 
 To restore a saved file, run the following command, replacing `<username>` with your username:
 
+[source,console]
 ----
 $ sudo alsactl restore -f /home/<username>/usecase.state
 ----

documentation/asciidoc/accessories/audio/introduction.adoc

@@ -5,6 +5,7 @@ Raspberry Pi Audio Boards bring high quality audio to your existing hi-fi or Ras
 Each board has a specific purpose and set of features. The highest audio quality playback is available from our DAC PRO, DAC{plus} and DigiAMP{plus} boards, which support up to full HD audio (192kHz); while the Codec Zero supports up to HD audio (96kHz) and includes a built-in microphone, making it ideal for compact projects.
 
 === Features at a glance
+
 [cols="2,1,1,1,1,1,1,1,1,1"]
 |===
 | | *Line out* | *Balanced out* | *Stereo speakers* | *Mono speaker* | *Headphones* | *Aux in* | *Aux out* | *Ext mic* | *Built-in mic*

documentation/asciidoc/accessories/audio/update-firmware.adoc

@@ -12,35 +12,36 @@ image::images/write_protect_tabs.jpg[width="80%"]
 
 NOTE: In some cases the two pads may already have a 0Ω resistor fitted to bridge the write-protect link, as illustrated in the picture of the Codec Zero board above.
 
-=== EEPROM Programming
+=== Program the EEPROM
 
 Once the write-protect line has been pulled down, the EEPROM can be programmed. 
 
 You should first install the utilities and then run the programmer. Open up a terminal window and type the following:
 
+[source,console]
 ----
 $ sudo apt update
 $ sudo apt install rpi-audio-utils
 $ sudo rpi-audio-flash
 ----
 
-After starting you will be presented with a warning screen.
+After starting, you will see a warning screen.
 
 image::images/firmware-update/warning.png[]
 
-Selecting "Yes" to proceed will present you with a menu allowing you to select your hardware.
+Select "Yes" to proceed. You should see a menu where you can select your hardware.
 
 image::images/firmware-update/select.png[]
 
 NOTE: If no HAT is present, or if the connected HAT is not a Raspberry Pi Audio board, you will be presented with an error screen. If the firmware has already been updated on the board, a message will be displayed informing you that you do not have to continue.
 
-After selecting the correct hardware a screen will display while the new firmware is flashed to the HAT.
+After selecting the hardware, a screen will display while the new firmware is flashed to the HAT.
 
 image::images/firmware-update/flashing.png[]
 
 Afterwards a screen will display telling you that the new firmware has installed.
 
 image::images/firmware-update/flashed.png[]
 
-NOTE: If the firmware fails to install correctly, an error screen will be displayed. In the first instance you should remove and reseat the HAT board and try flashing the firmware again.
+NOTE: If the firmware fails to install correctly, you will see an error screen. Try removing and reseating the HAT, then flash the firmware again.
 

documentation/asciidoc/accessories/build-hat.adoc

@@ -29,4 +29,3 @@ include::build-hat/links-to-other.adoc[]
 include::build-hat/compat.adoc[]
 
 include::build-hat/mech.adoc[]
-

documentation/asciidoc/accessories/build-hat/introduction.adoc

@@ -1,4 +1,5 @@
-== Introducing the Build HAT
+[[about-build-hat]]
+== About
 
 The https://raspberrypi.com/products/build-hat[Raspberry Pi Build HAT] is an add-on board that connects to the 40-pin GPIO header of your Raspberry Pi, which was designed in collaboration with LEGO® Education to make it easy to control LEGO® Technic™ motors and sensors with Raspberry Pi computers. 
 
@@ -8,7 +9,7 @@ NOTE: A full list of supported devices can be found in the xref:build-hat.adoc#d
 
 It provides four connectors for LEGO® Technic™ motors and sensors from the SPIKE™ Portfolio. The available sensors include a distance sensor, a colour sensor, and a versatile force sensor. The angular motors come in a range of sizes and include integrated encoders that can be queried to find their position.
 
-The Build HAT fits all Raspberry Pi computers with a 40-pin GPIO header, including — with the addition of a ribbon cable or other extension device — Raspberry Pi 400. Connected LEGO® Technic™ devices can easily be controlled in Python, alongside standard Raspberry Pi accessories such as a camera module.
+The Build HAT fits all Raspberry Pi computers with a 40-pin GPIO header, including, with the addition of a ribbon cable or other extension device, Raspberry Pi 400. Connected LEGO® Technic™ devices can easily be controlled in Python, alongside standard Raspberry Pi accessories such as a camera module.
 
 The Raspberry Pi Build HAT power supply (PSU), which is https://raspberrypi.com/products/build-hat-power-supply[available separately], is designed to power both the Build HAT and Raspberry Pi computer along with all connected LEGO® Technic™ devices.
 
@@ -26,5 +27,5 @@ NOTE: The HAT works with all 40-pin GPIO Raspberry Pi boards, including Raspberr
 
 [NOTE]
 ====
-The Build HAT can not power the Raspberry Pi 400 as it does not support being powered via the GPIO headers.
+The Build HAT cannot power the Raspberry Pi 400, since it does not support power supply over the GPIO headers.
 ====

documentation/asciidoc/accessories/build-hat/net-brick.adoc

@@ -1,17 +1,17 @@
-=== Using the Build HAT from .NET
+=== Use the Build HAT from .NET
 
 The Raspberry Pi Built HAT is referred to "Brick" in LEGO® parlance and you can talk directly to it from .NET using the https://datasheets.raspberrypi.com/build-hat/build-hat-serial-protocol.pdf[Build HAT Serial Protocol].
 
 You can create a `brick` object as below,
 
-[csharp]
+[source,csharp]
 ----
 Brick brick = new("/dev/serial0");
 ----
 
 but you need to remember to dispose of the `brick` at the end of your code.
 
-[csharp]
+[source,csharp]
 ----
 brick.Dispose();
 ----
@@ -20,18 +20,18 @@ WARNING: If you do not call `brick.Dispose()` your program will not terminate.
 
 If you want to avoid calling `brick.Dispose` at the end, then create your brick with the `using` statement:
 
-[csharp]
+[source,csharp]
 ----
 using Brick brick = new("/dev/serial0");
 ----
 
 In this case, when reaching the end of the program, your brick will be automatically disposed.
 
-==== Displaying the information
+==== Display Build HAT information
 
 You can gather the various software versions, the signature, and the input voltage:
 
-[csharp]
+[source,csharp]
 ----
 var info = brick.BuildHatInformation;
 Console.WriteLine($"version: {info.Version}, firmware date: {info.FirmwareDate}, signature:");
@@ -45,15 +45,15 @@ NOTE: The input voltage is read only once at boot time and is not read again aft
 
 The functions `GetSensorType`, `GetSensor` will allow you to retrieve any information on connected sensor.
 
-[csharp]
+[source,csharp]
 ----
 SensorType sensor = brick.GetSensorType((SensorPort)i);
 Console.Write($"Port: {i} {(Brick.IsMotor(sensor) ? "Sensor" : "Motor")} type: {sensor} Connected: ");
 ----
 
 In this example, you can as well use the `IsMotor` static function to check if the connected element is a sensor or a motor.
 
-[csharp]
+[source,csharp]
 ----
 if (Brick.IsActiveSensor(sensor))
 {
@@ -72,9 +72,9 @@ else
 
 Most sensors implements events on their special properties. You can simply subscribe to `PropertyChanged` and `PropertyUpdated`. The changed one will be fired when the value is changing while the updated one when there is a success update to the property. Depending on the modes used, some properties may be updated in the background all the time while some others occasionally.
 
-You may be interested only when a color is changing or the position of the motor is changing, using it as a tachometer. In this case, the `PropertyChanged` is what you need!
+You may be interested only when a colour is changing or the position of the motor is changing, using it as a tachometer. In this case, the `PropertyChanged` is what you need!
 
-[csharp]
+[source,csharp]
 ----
 Console.WriteLine("Move motor on Port A to more than position 100 to stop this test.");
 brick.WaitForSensorToConnect(SensorPort.PortA);
@@ -102,11 +102,11 @@ void MotorPropertyEvent(object? sender, PropertyChangedEventArgs e)
 }
 ----
 
-==== Waiting for initialization
+==== Wait for initialization
 
 The brick can take a long time before it initializes. A wait for a sensor to be connected has been implemented.
 
-[csharp]
+[source,csharp]
 ----
 brick.WaitForSensorToConnect(SensorPort.PortB);
 ----