Skip to content

Commit 7c6bb0b

Browse files
nathan-continonathan-contino
authored
Merge pull request #3782 from raspberrypi/sense-hat-instruction-flow-improvements
Update Sense HAT flow to avoid confusing users
2 parents caec0ab + 686423e commit 7c6bb0b

File tree

9 files changed

+184
-169
lines changed

9 files changed

+184
-169
lines changed

‎documentation/asciidoc/accessories/ai-kit/about.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ The Raspberry Pi AI Kit bundles the xref:m2-hat-plus.adoc#m2-hat-plus[Raspberry
1818
* M.2 2242 form factor
1919

2020
[[ai-kit-installation]]
21-
== Installation
21+
== Install
2222

2323
To use the AI Kit, you will need:
2424

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
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.
44

5-
IMPORTANT: Before proceeding, you should update the Raspberry Pi OS running on your Raspberry Pi to the latest version.
5+
IMPORTANT: Before proceeding, update the version of Raspberry Pi OS running on your Raspberry Pi to the latest version.
66

77
=== The EEPROM write-protect link
88

‎documentation/asciidoc/accessories/m2-hat-plus/about.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The M.2 HAT+ is _only_ compatible with the https://www.raspberrypi.com/products/
3030
** 1 knurled double-flanged drive attachment screw to secure and support the M.2 peripheral
3131

3232
[[m2-hat-plus-installation]]
33-
== Installation
33+
== Install
3434

3535
To use the Raspberry Pi M.2 HAT+, you will need:
3636

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
include::sense-hat/intro.adoc[]
22

3-
include::sense-hat/software.adoc[]
4-
53
include::sense-hat/hardware.adoc[]
4+
5+
include::sense-hat/software.adoc[]

‎documentation/asciidoc/accessories/sense-hat/hardware.adoc‎

Lines changed: 3 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
== Sense HAT hardware
1+
== Features
22

33
The Sense HAT has an 8×8 RGB LED matrix and a five-button joystick, and includes the following sensors:
44

@@ -18,143 +18,8 @@ Schematics and mechanical drawings for the Sense HAT and the Sense HAT V2 are av
1818
1919
=== LED matrix
2020

21-
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.
21+
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.
2222

2323
=== Joystick
2424

25-
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.
26-
27-
== Calibrate
28-
29-
Install the necessary software and run the calibration program as follows:
30-
31-
[source,console]
32-
----
33-
$ sudo apt update
34-
$ sudo apt install octave -y
35-
$ cd
36-
$ cp /usr/share/librtimulib-utils/RTEllipsoidFit ./ -a
37-
$ cd RTEllipsoidFit
38-
$ RTIMULibCal
39-
----
40-
41-
The calibration program displays the following menu:
42-
43-
----
44-
Options are:
45-
46-
m - calibrate magnetometer with min/max
47-
e - calibrate magnetometer with ellipsoid (do min/max first)
48-
a - calibrate accelerometers
49-
x - exit
50-
51-
Enter option:
52-
----
53-
54-
Press lowercase `m`. The following message will then show. Press any key to start.
55-
56-
----
57-
Magnetometer min/max calibration
58-
--------------------------------
59-
Waggle the IMU chip around, ensuring that all six axes
60-
(+x, -x, +y, -y and +z, -z) go through their extrema.
61-
When all extrema have been achieved, enter 's' to save, 'r' to reset
62-
or 'x' to abort and discard the data.
63-
64-
Press any key to start...
65-
----
66-
67-
After it starts, you should see output similar to the following scrolling up the screen:
68-
69-
----
70-
Min x: 51.60 min y: 69.39 min z: 65.91
71-
Max x: 53.15 max y: 70.97 max z: 67.97
72-
----
73-
74-
Focus on the two lines at the very bottom of the screen, as these are the most recently posted measurements from the program.
75-
76-
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.
77-
78-
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.
79-
80-
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.
81-
82-
In addition to those steps, you can also do the ellipsoid fit by performing the steps above, but pressing `e` instead of `m`.
83-
84-
When you're done, copy the resulting `RTIMULib.ini` to `/etc/` and remove the local copy in `~/.config/sense_hat/`:
85-
86-
[source,console]
87-
----
88-
$ rm ~/.config/sense_hat/RTIMULib.ini
89-
$ sudo cp RTIMULib.ini /etc
90-
----
91-
92-
== Read and write EEPROM data
93-
94-
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:
95-
96-
[source,ini]
97-
----
98-
dtparam=i2c_vc=on
99-
dtparam=i2c_arm=on
100-
----
101-
102-
Enter the following command to reboot:
103-
104-
[source,console]
105-
----
106-
$ sudo systemctl reboot
107-
----
108-
109-
Download and build the flash tool:
110-
111-
[source,console]
112-
----
113-
$ git clone https://github.com/raspberrypi/hats.git
114-
$ cd hats/eepromutils
115-
$ make
116-
----
117-
118-
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.
119-
120-
=== Read
121-
122-
EEPROM data can be read with the following command:
123-
124-
[source,console]
125-
----
126-
$ sudo ./eepflash.sh -f=sense_read.eep -t=24c32 -r
127-
----
128-
129-
=== Write
130-
131-
Download EEPROM settings and build the `.eep` binary:
132-
133-
[source,console]
134-
----
135-
$ wget https://github.com/raspberrypi/rpi-sense/raw/master/eeprom/eeprom_settings.txt -O sense_eeprom.txt
136-
$ ./eepmake sense_eeprom.txt sense.eep /boot/firmware/overlays/rpi-sense-overlay.dtb
137-
----
138-
139-
Disable write protection:
140-
141-
[source,console]
142-
----
143-
$ i2cset -y -f 1 0x46 0xf3 1
144-
----
145-
146-
Write the EEPROM data:
147-
148-
[source,console]
149-
----
150-
$ sudo ./eepflash.sh -f=sense.eep -t=24c32 -w
151-
----
152-
153-
Re-enable write protection:
154-
155-
[source,console]
156-
----
157-
$ i2cset -y -f 1 0x46 0xf3 0
158-
----
159-
160-
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.
25+
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.

‎documentation/asciidoc/accessories/sense-hat/intro.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
== Introducing the Sense HAT
1+
== About
22

3-
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.
3+
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.
44

55
image::images/Sense-HAT.jpg[width="70%"]
66

7-
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.
7+
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.
88

9-
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.
9+
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.

0 commit comments

Comments
 (0)