Skip to content

Commit

Permalink
Merge pull request #3782 from raspberrypi/sense-hat-instruction-flow-…
Browse files Browse the repository at this point in the history 
…improvements

Update Sense HAT flow to avoid confusing users
  • Loading branch information
@nathan-contino
nathan-contino authored Jul 18, 2024
2 parents caec0ab + 686423e commit 7c6bb0b
Show file tree
Hide file tree
Showing 9 changed files with 184 additions and 169 deletions.
2 changes: 1 addition & 1 deletion documentation/asciidoc/accessories/ai-kit/about.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion documentation/asciidoc/accessories/audio/update-firmware.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion documentation/asciidoc/accessories/m2-hat-plus/about.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
4 changes: 2 additions & 2 deletions documentation/asciidoc/accessories/sense-hat.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
include::sense-hat/intro.adoc[]

include::sense-hat/software.adoc[]

include::sense-hat/hardware.adoc[]

include::sense-hat/software.adoc[]
141 changes: 3 additions & 138 deletions documentation/asciidoc/accessories/sense-hat/hardware.adoc
View file
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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.
8 changes: 4 additions & 4 deletions documentation/asciidoc/accessories/sense-hat/intro.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 7c6bb0b

Please sign in to comment.