The Sailor Hat for Raspberry Pi requires additional software on the Raspberry Pi Operating System to fully utilize the device functionality. An installation script is provided to automatically install all required software on a fresh Raspberry Pi OS installation. Use of the installation script is described in the Getting Started Section. You will only need to follow the manual installation instructions if you prefer not to have automated scripts modify your system configuration or if you have to troubleshoot your installation.
For manual installation, the required software and configuration changes, as well as the firmware software details, are described below.
Enabling I2C and SPI
The I2C and SPI interfaces need to be enabled. This can be done either by running
raspi-config or by editing
If you use
raspi-config, skip until the end of this subsection.
sudo nano /boot/config.txt
Find the following line:
and edit it by removing the comment marker at the beginning:
Enabling the new interfaces
sudo nano /boot/config.txt
Scroll down to the
You need to add three new lines there. First, enable the RTC (if your device has one):
Then, configure the kernel to signal the Sailor Hat on power off:
Again, write the file by pressing Ctrl-O and exit Nano by pressing Ctrl-X.
Raspberry Pi configuration file changes for the RTC
Raspberry Pi doesn’t have a real-time clock by default. Instead, the system implements a “fake hwclock” that fetches the current time from the internet and then saves the time to a file at regular intervals. The time is then set from that file at boot to avoid things such as filesystem checks at every boot.
If your SH-RPi has a real-time clock, this fake hwclock functionality needs to be disabled and replaced with actual hwclock calls. These six commands do the trick:
sudo apt-get update sudo apt-get -y remove fake-hwclock sudo update-rc.d -f fake-hwclock remove sudo systemctl disable fake-hwclock sudo sed -i -e "s,^\(if \[ \-e /run/systemd/system \] ; then\),if false; then\n#\1," /lib/udev/hwclock-set
Raspberry Pi daemon
To make the Raspberry Pi OS aware of the power state, a daemon (service software) needs to be installed.
If you have cloned the SH-RPi-daemon repository, you can install the daemon by issuing the following commands:
sudo apt install -y python3-pip sudo pip3 install .
Next, you will have to install the service definition file and enable the service:
sudo install -o root shrpid.service /lib/systemd/system sudo systemctl daemon-reload sudo systemctl enable shrpid
That’s it! After a reboot, the daemon will start automatically.
Note: The Automated installation script described in the Getting Started Section will perform all software installation steps described above automatically.
The command-line interface is a Python script that can be used to control the Sailor Hat for Raspberry Pi from the Raspberry Pi command line. It is installed by the installation script described in the Getting Started Section.
shrpi, can be run with the
--help option to get instructions on the different commands. Some main use-cases are described below.
Print the current status and configuration of the Sailor Hat for Raspberry Pi.
shrpi set <option> <value>
Set different configuration values. For example,
shrpi set led 50
will set the LED brightness to 50%.
shrpi sleep 3600
Shut down the Raspberry Pi and turn it back on after 3600 seconds (1 hour).
shrpi sleep 15:00
Shut down the Raspberry Pi and turn it back on at 15:00 (3pm).
shrpi sleep 15:00:00
shrpid implements a REST API that can be used to query the current status and configuration of the Sailor Hat for Raspberry Pi and to set configuration values.
The API is available on a file socket at
/var/run/shrpid.sock. An example query with
curl is shown below:
curl --unix-socket /var/run/shrpid.sock http://localhost/state
For further details on available commands, see the SH-RPi-daemon source code.
The program code running on the onboard ATtiny1616 microcontroller is called the SH-RPi firmware.
The firmware repository is at https://github.com/hatlabs/SH-RPi-firmware.
The following subsections describe how to update the firmware to get new features or if you want to hack it yourself.
Updating the firmware
It is possible to update the SH-RPi firmware using the Raspberry Pi itself. This requires some jumpers and a bit of software configuration.
Flashing is performed over ATtiny’s UPDI interface using
Place jumpers on all pins on the PROG header as shown in red in the figure below. This will connect the microcontroller programmer circuitry and the debugging serial interface to the Raspberry Pi. In addition, the 5V output of the buck controller is forced on, so that the Raspberry Pi won’t turn itself off when starting the flashing process.
Set the red jumpers to enable self-flashing.
Note! For proper operation afterwards, it is essential that you remove at least the third jumper from the PROG header. Otherwise, the Raspberry Pi will not be able to turn itself off.
Raspberry Pi configuration changes
The next step is to enable the serial UARTs on the Raspberry Pi. They are used for both the UPDI and serial debugging interfaces. On Bluetooth-enabled Pis, the UART is normally reserved by the onboard Bluetooth circuitry. So, let’s disable Bluetooth.
Add the following lines at the end of
``ìni dtoverlay=disable-bt dtoverlay=uart5
The first one disables the Bluetooth modem. The second one enables the UART5 interface on the GPIOs 12 and 13 on pins 32 and 33. This is the serial interface used by the SH-RPi firmware for debugging. We also need to disable the system service initializing the Bluetooth modem: ```bash sudo systemctl disable hciuart
Finally, prevent the system serial console from attaching to the serial port. Remove the
console=serial0,115200 part from the beginning of
Reboot to allow the changes to take place.
Installing Flashing Software
Thanks to the PlatformIO framework, all necessary tools can be downloaded and installed automatically. We just need to get
the firmware source code first. Let’s install the
git version control system and clone the firmware repository:
sudo apt update sudo apt -y install git git clone email@example.com:hatlabs/SH-RPi-firmware.git
Now, we can install the PlatformIO framework:
sudo pip3 install -U platformio
platformio.ini file and change the
[env] ... upload_port = /dev/ttyAMA0 monitor_port = /dev/ttyAMA1
Finally, we can build and upload the firmware. The first time you run this command, it will download and install the necessary tools. This may take a while.
cd SH-RPi-firmware pio run -t upload
The white status LEDs will turn off during the flashing. After a few seconds, they will turn on again and the flashing is complete. At this point, remove the jumpers from the PROG header.
If you want to keep using Bluetooth, remember to undo the steps you made previously. To do this, you’ll need to reverse the changes you made to
/boot/cmdline.txt, and re-enable the
- Remove the following lines from
console=serial0,115200back to the beginning of
hciuartservice by running:
sudo systemctl enable hciuart
- Reboot your Raspberry Pi for the changes to take effect.
That’s it! You have successfully updated the firmware on your Sailor Hat for Raspberry Pi and restored Bluetooth functionality if desired.