diff --git a/documentation/asciidoc/accessories/ai-kit/about.adoc b/documentation/asciidoc/accessories/ai-kit/about.adoc index 7fcc78d349..4cfb42b96b 100644 --- a/documentation/asciidoc/accessories/ai-kit/about.adoc +++ b/documentation/asciidoc/accessories/ai-kit/about.adoc @@ -18,7 +18,7 @@ The Raspberry Pi AI Kit bundles the xref:m2-hat-plus.adoc#m2-hat-plus[Raspberry * M.2 2242 form factor [[ai-kit-installation]] -== Installation +== Install To use the AI Kit, you will need: diff --git a/documentation/asciidoc/accessories/audio/update-firmware.adoc b/documentation/asciidoc/accessories/audio/update-firmware.adoc index f6460327f6..d5a16fdb9e 100644 --- a/documentation/asciidoc/accessories/audio/update-firmware.adoc +++ b/documentation/asciidoc/accessories/audio/update-firmware.adoc @@ -2,7 +2,7 @@ Raspberry Pi Audio Boards use an EEPROM that contains information that is used by the host Raspberry Pi device to select the appropriate driver at boot time. This information is programmed into the EEPROM during manufacture. There are some circumstances where the end user may wish to update the EEPROM contents: this can be done from the command line. -IMPORTANT: Before proceeding, you should update the Raspberry Pi OS running on your Raspberry Pi to the latest version. +IMPORTANT: Before proceeding, update the version of Raspberry Pi OS running on your Raspberry Pi to the latest version. === The EEPROM write-protect link diff --git a/documentation/asciidoc/accessories/m2-hat-plus/about.adoc b/documentation/asciidoc/accessories/m2-hat-plus/about.adoc index a7379dd73a..e069e48753 100644 --- a/documentation/asciidoc/accessories/m2-hat-plus/about.adoc +++ b/documentation/asciidoc/accessories/m2-hat-plus/about.adoc @@ -30,7 +30,7 @@ The M.2 HAT+ is _only_ compatible with the https://www.raspberrypi.com/products/ ** 1 knurled double-flanged drive attachment screw to secure and support the M.2 peripheral [[m2-hat-plus-installation]] -== Installation +== Install To use the Raspberry Pi M.2 HAT+, you will need: diff --git a/documentation/asciidoc/accessories/sense-hat.adoc b/documentation/asciidoc/accessories/sense-hat.adoc index 7ce6103288..c0db67f2bb 100644 --- a/documentation/asciidoc/accessories/sense-hat.adoc +++ b/documentation/asciidoc/accessories/sense-hat.adoc @@ -1,5 +1,5 @@ include::sense-hat/intro.adoc[] -include::sense-hat/software.adoc[] - include::sense-hat/hardware.adoc[] + +include::sense-hat/software.adoc[] diff --git a/documentation/asciidoc/accessories/sense-hat/hardware.adoc b/documentation/asciidoc/accessories/sense-hat/hardware.adoc index bd08da9bbf..735ce713aa 100644 --- a/documentation/asciidoc/accessories/sense-hat/hardware.adoc +++ b/documentation/asciidoc/accessories/sense-hat/hardware.adoc @@ -1,4 +1,4 @@ -== Sense HAT hardware +== Features The Sense HAT has an 8×8 RGB LED matrix and a five-button joystick, and includes the following sensors: @@ -18,143 +18,8 @@ Schematics and mechanical drawings for the Sense HAT and the Sense HAT V2 are av === LED matrix -The LED matrix is an RGB565 https://www.kernel.org/doc/Documentation/fb/framebuffer.txt[framebuffer] with the id "RPi-Sense FB". The appropriate device node can be written to as a standard file or mmap-ed. The included 'snake' example shows how to access the framebuffer. +The LED matrix is an RGB565 https://www.kernel.org/doc/Documentation/fb/framebuffer.txt[framebuffer] with the id `RPi-Sense FB`. The appropriate device node can be written to as a standard file or mmap-ed. The included snake example shows how to access the framebuffer. === Joystick -The joystick comes up as an input event device named "Raspberry Pi Sense HAT Joystick", mapped to the arrow keys and `Enter`. It should be supported by any library which is capable of handling inputs, or directly through the https://www.kernel.org/doc/Documentation/input/input.txt[evdev interface]. Suitable libraries include SDL, http://www.pygame.org/docs/[pygame] and https://python-evdev.readthedocs.org/en/latest/[python-evdev]. The included 'snake' example shows how to access the joystick directly. - -== Calibrate - -Install the necessary software and run the calibration program as follows: - -[source,console] ----- -$ sudo apt update -$ sudo apt install octave -y -$ cd -$ cp /usr/share/librtimulib-utils/RTEllipsoidFit ./ -a -$ cd RTEllipsoidFit -$ RTIMULibCal ----- - -The calibration program displays the following menu: - ----- -Options are: - - m - calibrate magnetometer with min/max - e - calibrate magnetometer with ellipsoid (do min/max first) - a - calibrate accelerometers - x - exit - -Enter option: ----- - -Press lowercase `m`. The following message will then show. Press any key to start. - ----- - Magnetometer min/max calibration - -------------------------------- - Waggle the IMU chip around, ensuring that all six axes - (+x, -x, +y, -y and +z, -z) go through their extrema. - When all extrema have been achieved, enter 's' to save, 'r' to reset - or 'x' to abort and discard the data. - - Press any key to start... ----- - -After it starts, you should see output similar to the following scrolling up the screen: - ----- - Min x: 51.60 min y: 69.39 min z: 65.91 - Max x: 53.15 max y: 70.97 max z: 67.97 ----- - -Focus on the two lines at the very bottom of the screen, as these are the most recently posted measurements from the program. - -Now, pick up the Raspberry Pi and Sense HAT and move it around in every possible way you can think of. It helps if you unplug all non-essential cables to avoid clutter. - -Try and get a complete circle in each of the pitch, roll and yaw axes. Take care not to accidentally eject the SD card while doing this. Spend a few minutes moving the Sense HAT, and stop when you find that the numbers are not changing any more. - -Now press lowercase `s` then lowercase `x` to exit the program. If you run the `ls` command now, you'll see a new `RTIMULib.ini` file has been created. - -In addition to those steps, you can also do the ellipsoid fit by performing the steps above, but pressing `e` instead of `m`. - -When you're done, copy the resulting `RTIMULib.ini` to `/etc/` and remove the local copy in `~/.config/sense_hat/`: - -[source,console] ----- -$ rm ~/.config/sense_hat/RTIMULib.ini -$ sudo cp RTIMULib.ini /etc ----- - -== Read and write EEPROM data - -Enable I2C0 and I2C1 by adding the following line to the xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`] file: - -[source,ini] ----- -dtparam=i2c_vc=on -dtparam=i2c_arm=on ----- - -Enter the following command to reboot: - -[source,console] ----- -$ sudo systemctl reboot ----- - -Download and build the flash tool: - -[source,console] ----- -$ git clone https://github.com/raspberrypi/hats.git -$ cd hats/eepromutils -$ make ----- - -NOTE: These steps may not work on Raspberry Pi 2 Model B Rev 1.0 and Raspberry Pi 3 Model B boards. The firmware will take control of I2C0, causing the ID pins to be configured as inputs. - -=== Read - -EEPROM data can be read with the following command: - -[source,console] ----- -$ sudo ./eepflash.sh -f=sense_read.eep -t=24c32 -r ----- - -=== Write - -Download EEPROM settings and build the `.eep` binary: - -[source,console] ----- -$ wget https://github.com/raspberrypi/rpi-sense/raw/master/eeprom/eeprom_settings.txt -O sense_eeprom.txt -$ ./eepmake sense_eeprom.txt sense.eep /boot/firmware/overlays/rpi-sense-overlay.dtb ----- - -Disable write protection: - -[source,console] ----- -$ i2cset -y -f 1 0x46 0xf3 1 ----- - -Write the EEPROM data: - -[source,console] ----- -$ sudo ./eepflash.sh -f=sense.eep -t=24c32 -w ----- - -Re-enable write protection: - -[source,console] ----- -$ i2cset -y -f 1 0x46 0xf3 0 ----- - -WARNING: This operation will not damage your Raspberry Pi or Sense HAT, but if an error occurs, the HAT may no longer be automatically detected. The steps above are provided for debugging purposes only. +The joystick comes up as an input event device named `Raspberry Pi Sense HAT Joystick`, mapped to the arrow keys and **Enter**. It should be supported by any library which is capable of handling inputs, or directly through the https://www.kernel.org/doc/Documentation/input/input.txt[evdev interface]. Suitable libraries include SDL, http://www.pygame.org/docs/[pygame] and https://python-evdev.readthedocs.org/en/latest/[python-evdev]. The included `snake` example shows how to access the joystick directly. diff --git a/documentation/asciidoc/accessories/sense-hat/intro.adoc b/documentation/asciidoc/accessories/sense-hat/intro.adoc index 333a612f73..5b8e68aa2a 100644 --- a/documentation/asciidoc/accessories/sense-hat/intro.adoc +++ b/documentation/asciidoc/accessories/sense-hat/intro.adoc @@ -1,9 +1,9 @@ -== Introducing the Sense HAT +== About -The https://www.raspberrypi.com/products/sense-hat/[Raspberry Pi Sense HAT] is an add-on board that gives your Raspberry Pi an array of sensing capabilities. The on-board sensors allow you to monitor pressure, humidity, temperature, colour, orientation, and movement. The bright 8×8 RGB LED matrix allows you to visualise data from the sensors, and the five-button joystick lets users interact with your projects. +The https://www.raspberrypi.com/products/sense-hat/[Raspberry Pi Sense HAT] is an add-on board that gives your Raspberry Pi an array of sensing capabilities. The on-board sensors allow you to monitor pressure, humidity, temperature, colour, orientation, and movement. The 8×8 RGB LED matrix allows you to visualise data from the sensors. The five-button joystick lets users interact with your projects. image::images/Sense-HAT.jpg[width="70%"] -The Sense HAT was originally developed for use on the International Space Station, as part of the educational https://astro-pi.org/[Astro Pi] programme run by the https://raspberrypi.org[Raspberry Pi Foundation] in partnership with the https://www.esa.int/[European Space Agency]. It is well suited to many projects that require position, motion, orientation, or environmental sensing. The Sense HAT is powered by the Raspberry Pi computer to which it is connected. +The Sense HAT was originally developed for use on the International Space Station as part of the educational https://astro-pi.org/[Astro Pi] programme run by the https://raspberrypi.org[Raspberry Pi Foundation] in partnership with the https://www.esa.int/[European Space Agency]. It is well-suited to many projects that require position, motion, orientation, or environmental sensing. Because it is an add-on board, the Sense HAT connects to a Raspberry Pi device, drawing power from that device. -An officially supported xref:sense-hat.adoc#use-the-sense-hat-with-python[Python library] provides access to all of the on-board sensors, the LED matrix, and the joystick. The Sense HAT is compatible with any Raspberry Pi computer with a 40-pin GPIO header. +An officially supported xref:sense-hat.adoc#use-the-sense-hat-with-python[Python library] provides access to the on-board sensors, LED matrix, and joystick. The Sense HAT is compatible with any Raspberry Pi device with a 40-pin GPIO header. diff --git a/documentation/asciidoc/accessories/sense-hat/software.adoc b/documentation/asciidoc/accessories/sense-hat/software.adoc index 300da3d316..2bc3d3201e 100644 --- a/documentation/asciidoc/accessories/sense-hat/software.adoc +++ b/documentation/asciidoc/accessories/sense-hat/software.adoc @@ -1,37 +1,102 @@ -== Installation +== Install -In order to work correctly, the Sense HAT requires an up-to-date kernel, I2C to be enabled, and a few libraries to get started. +In order to work correctly, the Sense HAT requires: -Ensure your APT package list is up-to-date: +* an up-to-date kernel +* https://en.wikipedia.org/wiki/I%C2%B2C[I2C] enabled on your Raspberry Pi +* a few dependencies +Complete the following steps to get your Raspberry Pi device ready to connect to the Sense HAT: + +. First, ensure that your Raspberry Pi runs the latest software. Run the following command to update: ++ [source,console] ---- -$ sudo apt update +$ sudo apt update && sudo apt upgrade ---- -Next, install the sense-hat package, which will ensure the kernel is up to date, enable I2C, and install the necessary libraries and programs: - +. Next, install the `sense-hat` package, which will ensure the kernel is up to date, enable I2C, and install the necessary dependencies: ++ [source,console] ---- $ sudo apt install sense-hat ---- -Finally, a reboot may be required if I2C was disabled or the kernel was not up-to-date prior to the install: - +. Finally, reboot your Raspberry Pi to enable I2C and load the new kernel, if it changed: ++ [source,console] ---- $ sudo reboot ---- -== Getting started +== Calibrate -After installation, example code can be found under `/usr/src/sense-hat/examples`. +Install the necessary software and run the calibration program as follows: -[.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[]] +[source,console] +---- +$ sudo apt update +$ sudo apt install octave -y +$ cd +$ cp /usr/share/librtimulib-utils/RTEllipsoidFit ./ -a +$ cd RTEllipsoidFit +$ RTIMULibCal +---- -=== Further reading +The calibration program displays the following menu: -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#use-the-sense-hat-with-python[Python library]. +---- +Options are: + + m - calibrate magnetometer with min/max + e - calibrate magnetometer with ellipsoid (do min/max first) + a - calibrate accelerometers + x - exit + +Enter option: +---- + +Press lowercase `m`. The following message will then show. Press any key to start. + +---- +Magnetometer min/max calibration +------------------------------- +Waggle the IMU chip around, ensuring that all six axes +(+x, -x, +y, -y and +z, -z) go through their extrema. +When all extrema have been achieved, enter 's' to save, 'r' to reset +or 'x' to abort and discard the data. + +Press any key to start... +---- + +After it starts, you should see output similar to the following scrolling up the screen: + +---- +Min x: 51.60 min y: 69.39 min z: 65.91 +Max x: 53.15 max y: 70.97 max z: 67.97 +---- + +Focus on the two lines at the very bottom of the screen, as these are the most recently posted measurements from the program. + +Now, pick up the Raspberry Pi and Sense HAT and move it around in every possible way you can think of. It helps if you unplug all non-essential cables to avoid clutter. + +Try and get a complete circle in each of the pitch, roll and yaw axes. Take care not to accidentally eject the SD card while doing this. Spend a few minutes moving the Sense HAT, and stop when you find that the numbers are not changing any more. + +Now press lowercase `s` then lowercase `x` to exit the program. If you run the `ls` command now, you'll see a new `RTIMULib.ini` file has been created. + +In addition to those steps, you can also do the ellipsoid fit by performing the steps above, but pressing `e` instead of `m`. + +When you're done, copy the resulting `RTIMULib.ini` to `/etc/` and remove the local copy in `~/.config/sense_hat/`: + +[source,console] +---- +$ rm ~/.config/sense_hat/RTIMULib.ini +$ sudo cp RTIMULib.ini /etc +---- + +== Getting started + +After installation, example code can be found under `/usr/src/sense-hat/examples`. === Use the Sense HAT with Python @@ -46,3 +111,86 @@ https://github.com/RPi-Distro/RTIMULib[RTIMULib] is a {cpp} and Python library t The RTIMULibDrive11 example comes pre-compiled to help ensure everything works as intended. It can be launched by running `RTIMULibDrive11` and closed by pressing `Ctrl C`. NOTE: The C/{cpp} examples can be compiled by running `make` in the appropriate directory. + +== Troubleshooting + +=== Read and write EEPROM data + +These steps are provided for debugging purposes only. + +NOTE: On Raspberry Pi 2 Model B Rev 1.0 and Raspberry Pi 3 Model B boards, these steps may not work. The firmware will take control of I2C0, causing the ID pins to be configured as inputs. + +Before you can read and write EEPROM data to and from the Sense HAT, you must complete the following steps: + +. Enable I2C0 and I2C1 by adding the following line to the xref:../computers/config_txt.adoc#what-is-config-txt[`/boot/firmware/config.txt`] file: ++ +[source,ini] +---- +dtparam=i2c_vc=on +dtparam=i2c_arm=on +---- + +. Run the following command to reboot: ++ +[source,console] +---- +$ sudo reboot +---- + +. Download and build the flash tool: ++ +[source,console] +---- +$ git clone https://github.com/raspberrypi/hats.git +$ cd hats/eepromutils +$ make +---- + +==== Read + +To read EEPROM data, run the following command: + +[source,console] +---- +$ sudo ./eepflash.sh -f=sense_read.eep -t=24c32 -r +---- + +==== Write + +NOTE: This operation will not damage your Raspberry Pi or Sense HAT, but if an error occurs, your Raspberry Pi may fail to automatically detect the HAT. + + +. First, download EEPROM settings and build the `.eep` binary: ++ +[source,console] +---- +$ wget https://github.com/raspberrypi/rpi-sense/raw/master/eeprom/eeprom_settings.txt -O sense_eeprom.txt +$ ./eepmake sense_eeprom.txt sense.eep /boot/firmware/overlays/rpi-sense-overlay.dtb +---- + +. Next, disable write protection: ++ +[source,console] +---- +$ i2cset -y -f 1 0x46 0xf3 1 +---- + +. Write the EEPROM data: ++ +[source,console] +---- +$ sudo ./eepflash.sh -f=sense.eep -t=24c32 -w +---- + +. Finally, re-enable write protection: ++ +[source,console] +---- +$ i2cset -y -f 1 0x46 0xf3 0 +---- + +[.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#use-the-sense-hat-with-python[Python library]. diff --git a/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc b/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc index fc5e1eac91..e1cb7efa60 100644 --- a/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc +++ b/documentation/asciidoc/accessories/tv-hat/about-tv-hat.adoc @@ -1,4 +1,5 @@ -== About the TV HAT +[[tv-hat]] +== About .The Raspberry Pi TV HAT image::images/tv-hat.jpg[width="80%"] @@ -23,7 +24,8 @@ Digital Video Broadcasting – Terrestrial (DVB-T) is the DVB European-based con .DTT system implemented or adopted (Source: DVB/EBU/BNE DTT Deployment Database, March 2023) image::images/dvbt-map.png[width="80%"] -== Setup Instructions +[[tv-hat-installation]] +== Install Follow our xref:../computers/getting-started.adoc[getting started] documentation and set up the Raspberry Pi with the newest version of Raspberry Pi OS. diff --git a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc index bab9a95009..fa90c7a3f3 100644 --- a/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc +++ b/documentation/asciidoc/computers/raspberry-pi/eeprom-bootloader.adoc @@ -428,15 +428,15 @@ src_port@src_ip/dev_name,dst_port@dst_ip/dst_mac E.g. 6665@169.254.1.1/,6666@/ ---- -In order to simplify parsing, the bootloader requires every field separator to be present. The source IP address must be specified but the following fields may be left blank and assigned default values. +In order to simplify parsing, the bootloader requires every field separator to be present. You must specify the source IP address, but you can leave the following fields blank to use their default values: -* src_port - 6665 -* dev_name - "" (the device name is always ignored) -* dst_port - 6666 -* dst_ip - 255.255.255.255 -* dst_mac - 00:00:00:00:00 +* `src_port` - `6665` +* `dev_name` - `""` (the device name is always ignored) +* `dst_port` - `6666` +* `dst_ip` - `255.255.255.255` +* `dst_mac` - `00:00:00:00:00` -One way to view the data is to connect the test Raspberry Pi 4 to another Raspberry Pi running WireShark and select "`udp.srcport == 6665`" as a filter and select *Analyze -> Follow -> UDP stream* to view as an ASCII log. +One way to view the data is to connect the test Raspberry Pi 4 to another Raspberry Pi running WireShark and select `udp.srcport == 6665` as a filter and select *Analyze -> Follow -> UDP stream* to view as an ASCII log. `NETCONSOLE` should not be enabled by default because it may cause network problems. It can be enabled on demand via a GPIO filter: