Getting Started with pHAT BEAT

This tutorial will show you how to install the pHAT BEAT software and Python library, and then walk through its functionality. You'll learn how to change the settings in the ALSA config. (ALSA deals with sound output in Linux), how to control the VU meter LEDs separately, and how to use the buttons on the board.

If you haven't already soldered the header to your pHAT BEAT, then you can follow our guide to soldering pHATs here.

Connecting speakers

The push-fit speaker terminals on pHAT BEAT make it really simple to connect up one or two speakers (the DIP switch on the underside switches between mono and stereo modes).

It's easiest if the bare ends of your speakers wires are "tinned" with a little solder. You can do this by melting a little blob of solder on the end of your soldering iron and then "painting" it onto the bare wire to cover it in a thin coating of solder (if it's too thick then the wire won't fit into the terminal).

If you've bought one of our 5W speakers, or have the Pirate Radio kit, then the ends of the wires should already be tinned.

Once your wires have been tinned, simply push them into the terminals, making sure to put the red wires into the positive terminals and the black ones into the ground terminals. Push the wires in firmly. If they're seated properly then they will "lock" into the terminal and should not pull out easily.

To remove the wires, use something pointed like a pencil and press it fairly firmly (although not too firmly as the clips can break) on the clip on top of the terminal while pulling the wire out.

Installing the software

We always recommend using the most up-to-date version of Raspbian, as this is what we test our boards and software against, and it often helps to start with a completely fresh install of Raspbian, although this isn't necessary.

As with most of our boards, we've created a really quick and easy one-line-installer to get your pHAT BEAT set up. We'd suggest that you use this method to install the pHAT BEAT software.

Open a new terminal, and type the following, making sure to type 'y' or 'n' when prompted:

curl -sS get.pimoroni.com/phatbeat  | bash

Once that's done, it probably a good idea to reboot your Pi to let the changes propagate, if the installer doesn't prompt you to reboot.

Testing the audio

Pop the pHAT BEAT with connected speaker onto your Pi, noting that it may reboot if it's currently switched on. Don't worry too much about that!

You can test that audio is being output correctly and that the VU meter is working as it should using speaker-test in the terminal. Open a terminal, if you don't still have it open and type the following:

speaker-test -c2 -t wav

You should hear audio and see the meter reacting accordingly. Press control and c to stop the speaker test.

ALSA configuration

The one-line-installer takes care of reconfiguring ALSA to route the audio out correctly through the I2S interface used by pHAT BEAT, and will also install an ALSA plugin to enable the VU meter LEDs called Pi VU Meter.

The ALSA configuration file is located at /etc/asound.conf. You can edit it, in the terminal, by typing sudo nano /etc/asound.conf.

The section of the ALSA configuration that controls the VU meter settings should look something like the following:

pcm_scope.pivumeter {
    type pivumeter
    decay_ms 500
    peak_ms 400
    brightness 128
    output_device phat-beat
}

The decay_ms and peak_ms settings set how long the meter pauses when it peaks and decays respectively in milliseconds. Reducing these will make the meter more "twitchy" and increasing them will make it smoother but less reactive.

The brightness setting controls the overall brightness of the meter, and can range from 0 to 255, with 0 being off and 255 being full brightness.

output_device sets what the output device for the meter is. In this case, it should be left as phat-beat.

An additional line can be added inside the curly brackets to specify whether the VU meter bars should be flipped 180 degrees or not. This is relevant if you are mounting pHAT BEAT in a different orientation than the default (default being vertically with the power button on the top edge). To flip the meter, add bar_reverse 1 to the section above.

To save the ALSA configuration, if you've made changes, and return to the terminal press control and x, then y, then enter.

Controlling the VU meter LEDs separately

The one-line-installer for pHAT BEAT will also install the Python library, in addition to configuring ALSA, allowing you to control the VU meter LEDs and the buttons.

The LEDs are arranged in two columns of eight, beginning at the bottom left corner and finishing at the top right corner (if you're looking at the board with the power button on the top edge). They can be set either by their index between 0 and 15, in one continuous chain, or as two columns indexed 0 to 7 and specifying channel=0 with 0 being the left column or channel and 1 being the right column or channel.

We'll set the first pixel on each channel to red. Open a terminal, and then type sudo python to open a Python prompt. Type the following:

import phatbeat

for channel in (0,1):
    phatbeat.set_pixel(0, 255, 0, 0, channel=channel)

phatbeat.show()

First, we import the phatbeat library.

Then, we have a for loop that allows us to loop through both channels and set the first pixel (remember that, in Python, things are indexed from 0, so the first item is actually index 0).

The phatbeat.set_pixel() function needs to be given first the index of the pixel we want to set (0 in this case), and then three values between 0 and 255 that are the RGB values of the colour we want to set. In this case, we passed 255, 0, 0 because we want to set the colour to pure red. We also specify the channel number (note that if we hadn't passed the channel= option then it would have treated the pixels as one continuous row of 16 pixels).

Finally, we call phatbeat.show() to actually push the data to the pixels and display it.

To clear those pixels, we can use the phatbeat.clear() function, again followed by phatbeat.show():

phatbeat.clear()
phatbeat.show()

To set them the other way, treating them as a single chain of 16 pixels, try the following. We'll set them all to cyan, a mix between blue and green.

for p in range(16):
    phatbeat.set_pixel(p, 0, 255, 255)

phatbeat.show()

Handling button presses

The buttons on pHAT BEAT can be linked to a function of your choice using decorators. In Python, decorators are functions that are attached to other functions, in this case triggering that function when an event happens - a button press.

Each button is represented by a constant that describes that button's function, for example phatbeat.BTN_PLAYPAUSE represents the play/pause button as you might imagine. The six button constants are:

  • BTN_FASTFWD
  • BTN_REWIND
  • BTN_PLAYPAUSE
  • BTN_VOLUP
  • BTN_VOLDN
  • BTN_ONOFF

We'll start with a simple example of how to attach a button decorator to a function that prints out a message when that button is pressed.

@pb.on(phatbeat.BTN_PLAYPAUSE)
def playpause(pin):
    print('Play/pause pressed!')

Once you've typed that, try pressing the play/pause button and see what happens. You'll notice that the decorator is called @phatbeat.on, and indeed all decorators in Python use this @ notation. The decorator is passed the constant for the button to which we want to attach it. Also note that we pass our playpause function a variable called pin. This pin variable is returned by the decorator and can be used within our playpause function if we wish.

We'll take it a little further now and make the play/pause buttons light the LEDs on pHAT BEAT when the button is pressed, introducing another function of the LEDs, the ability to light them all at once. We'll set them all to magenta when the volume up button is pressed.

@phatbeat.on(phatbeat.BTN_VOLUP)
def lightleds(pin):
    phatbeat.set_all(255, 0, 255)
    phatbeat.show()

You could add a second function to toggle the LEDs back off when, for example, the volume down button is pressed.

@phatbeat.on(phatbeat.BTN_VOLDN)
def clearleds(pin):
    phatbeat.clear()
    phatbeat.show()

The function of the buttons on pHAT BEAT becomes even more powerful when used with Python's subprocess library to run shell commands. For example, you could link the volume up and down buttons to the volume set by alsamixer in the terminal.

Taking it further

There are loads of opportunities for working pHAT BEAT into other projects. Why not use it to build a little synth or drum machine by combining it with Piano HAT or Drum HAT and use the VU meter LEDs as a step sequencer? Or how about combining it with a little USB microphone to create your own all-in-one Alexa clone?

Shopping basket

Need something for this project? You can use the links below to add products to your Pimoroni Shop basket for easy checkout.

Pirate Radio - Pi Zero W Project Kit
£40.00
pHAT BEAT
£16.50
Raspberry Pi Universal Power Supply
£8.00
NOOBS 8GB SD Card (2.2.0)
£6.50
Antex XS25 Soldering Iron (UK Plug)
£30.00
Antex Lead Free Solder 2m
£3.00
GPIO Hammer Header (Solderless)
Male + Female + Installation Jig £6.00
GPIO Hammer Header (Solderless)
Male £2.00
GPIO Hammer Header (Solderless)
Female £3.00
Want to checkout or change something? Click here to view your cart.

Tutorial
Beginner
LEDs, Raspberry Pi, Pi Zero

Sandy Macdonald

sandy@pimoroni.com
@sandyjmacdonald
http://sandyjmacdonald.github.io
Formerly, Sandy worked at the University of York, in the biology department, analysing data and telling people that they should have used more replicates. Now a fully-fledged crew member at Pimoroni - head of digital content - working on learning materials and digital chunterings. Find him on Twitter and most everywhere else, as sandyjmacdonald.