Visit the pi-topPULSE product page on the pi-top website for more information.
- Boot into pi-topOS (released on or after 12-07-2017)
- Plug in pi-topPULSE
- Follow on-screen instructions, if necessary
- Instructions will appear in pi-topDASHBOARD and in a messagebox on the desktop, and will typically ask the user to reboot. If no messages appear and the red LED on the underside turns off shortly after being plugged in, the hardware should be ready to use.
- Enjoy - check out the examples to see what you can do! And try asking Alexa questions via pi-topDASHBOARD! (Note: you will need to be logged in for this)
- Run the following commands in the terminal (with an internet connection):
sudo apt update
sudo apt install pt-pulse
- Plug in pi-topPULSE
- Follow on-screen instructions, if necessary
- Instructions will appear in pi-topDASHBOARD and in a messagebox on the desktop, and will typically ask the user to reboot. If no messages appear and the red LED on the underside turns off shortly after being plugged in, the hardware should be ready to use.
- Enjoy - check out the examples to see what you can do! See here for more on using pi-top's Alexa Voice Service integration.
pi-topPULSE is a 7x7 LED grid, speaker and microphone combined into a single device that can be used as a HAT or pi-top addon. Additionally the device features ambient lights which reflect the state of the LED array, four around the speaker, and three on the underside. The speaker has an output of 2W, and the microphone has 200Hz to 11KHz response and automatic gain control (AGC).
pi-topPULSE uses a variety of interfaces to communicate with the Raspberry Pi: the speaker uses I2S, and the LEDs and microphone use serial (UART), Tx and Rx respectively.
For information on the pi-topPULSE's GPIO pinout, see here.
pi-topPULSE uses the following resources:
- GPIO pins 3 and 5 for I2C communication and control.
- GPIO pins 8 and 10 for UART (serial) communication.
- GPIO pins 12, 35 and 40 for I2S
- The device controller is exposed on I2C address 0x24
Note: GPIO pins are references by their physical number
For a full pinout of the pi-topPULSE, see this GPIO Pinout
All pi-topPULSE software and libraries are included and configured 'out-of-the-box' as standard on pi-topOS (released on or after 12-07-2017). Simply connect a pi-topPULSE to your pi-top, reboot if instructed to do so, and it will be automatically initialised and ready to produce light, capture and play audio. Volume control is handled by the operating system.
Download the latest version of pi-topOS here.
As mentioned in the Hardware, the speaker on the pi-topPULSE uses I2S. This has the following implications:
-
On an original pi-top or pi-topCEED I2S must be enabled, which will require a reboot from a typical Raspbian configuration (using the default sound drivers). This is also true in reverse: if you have previously configured a pi-topPULSE and you wish to use the standard HDMI or 3.5mm sound outputs, this will also require a reboot.
-
On a new pi-top, the hub has the capability to convert HDMI audio to I2S before sending it to the pi-topPULSE. As a result, enabling I2S and rebooting is no longer required.
-
In both the above cases, the very first time a pi-topPULSE is connected, a reboot may still be required to enable UART. You will be prompted to reboot if so.
Automatic initialisation is performed by the software contained in the package called pt-device-manager. This installs a program called pt-device-manager, which runs in the background and scans for newly connected devices. If a device is detected (and its supporing library is installed), it will be initialised and enabled automatically.
When the pt-pulse package is installed, pt-device-manager will also be installed as dependency, thus starting the background process. Depending on whether running on an original pi-top or a new pi-top the user will be notified if a reboot is required. If a reboot is not required, the device will be initialised and ready to use.
For more information about pt-device-manager, see this repository.
The pi-topPULSE software can be found on the Raspbian software repositories. To install it, simply run the following commands at the terminal and then reboot:
sudo apt update
sudo apt install pt-pulse
This will install the ptpulse Python library, as well as its dependencies, including pt-device-manager (see above).
If you prefer to manually install the packages or want to install a specific set of packages see the Manual Configuration and Installation instructions.
For more information on how to use the library files, take a look at the initialisation section of the 'Manual Configuration and Installation' instructions. Also check out the examples folder for guidance of what the library is capable of.
As the pi-topPULSE has the capability to both record and playback audio, it can be used to interact with voice assistants such as Amazon Alexa. We have integrated Alexa into pi-topOS, and created an open source repository to show how to make use of this yourself. See here for more on using pi-top's Alexa Voice Service integration. Note: this implementation requires a pi-top account.
Once installed, pi-topPULSE can be used in Python3 by importing the modules in the ptpulse library: configuration, microphone and ledmatrix. In the future we aim to produce some formal documentation for this library, but for the time being there is some sample code in the examples folder of this repository.
Note that using the ptpulse Python module requires root access to function. If you are running a script, make sure that you are running it with root access. You can do this with the "sudo" command:
sudo python3 my_cool_pulse_script.py
Alternatively, if you are running Python in IDLE, please make sure you start LXTerminal and run idle or idle3 with the "sudo" command, like so:
sudo idle3
- Currently, pi-topPULSE is only supported on Raspberry Pi 3. This is due to problems setting the UART clock speed on earlier Raspberry Pi models. It might be possible to get this to work on earlier versions, but this is not currently supported.
-
If you are running Linux kernel version 4.9.x previous to 4.9.35, pi-topPULSE may not be fully functional. In particular, this issue prevents the pi-topPULSE LEDs from working. If you are experiencing this issue, please check your kernel version by typing
uname -rat the terminal. You can update your kernel version to the latest by runningsudo apt install raspberrypi-kernel. -
If you are attempting to use Python 3, and have installed manually, you need to ensure that you have the latest version of the PySerial module. Take a look at the script in the
manual-installdirectory for how to do this.
- This LED indicates that the sampling rate of the microphone is set to 16kHz. By default, when plugged in, you will see that this LED is switched on, and can be used as a guide to show that it has not yet been initialised. Once initialised, the default sample rate is 22050Hz (~22KHz), and this is why the red LED is switched off. Note: pi-top's Amazon Alexa Voice Service integration uses 16kHz, which is denoted with the red LED being on. In this context, the red LED can be considered as an indicator that the pi-topPULSE is capturing audio.
- This is a known issue, and we are evaluating the best user experience for resolving this issue. In the meantime, this issue is captured here - follow the instructions to re-enable Bluetooth.