Adafruit BrainCraft HAT - Easy Machine Learning for Raspberry Pi

2020-11-17 | By Adafruit Industries

License: See Original Project

Courtesy of Adafruit

Guide by Lady Ada

Overview

The idea behind the Adafruit BrainCraft HAT is that you’d be able to “craft brains” for Machine Learning on the EDGE, with Microcontrollers & Microcomputers. On ASK AN ENGINEER, our founder & engineer chatted with Pete Warden, the technical lead of the mobile, embedded TensorFlow Group on Google’s Brain team about what would be ideal for a board like this.

coffeecup_1

board_2

And here’s what we designed! The BrainCraft HAT has a 240×240 TFT IPS display for inference output, slots for a camera connector cable for imaging projects, a 5 way joystick and button for UI input, left and right microphones, stereo headphone out, a stereo 1 Watt speaker out, three RGB DotStar LEDs, two 3 pin STEMMA connectors on PWM pins so they can drive NeoPixels or servos, and Grove/STEMMA/Qwiic I2C port. This will let people build a wide range of audio/video AI projects while also allowing easy plug-in of sensors and robotics!

BrainCraft HAT_3

A controllable mini fan attaches to the bottom and can be used to keep your Pi cool while doing intense AI inference calculations. Most importantly, there’s an On/Off switch that will completely disable the audio codec, so that when it's off, there’s no way it's listening to you.

fan_4

Features:

1.54" IPS TFT display with 240x240 resolution that can show text or video
Stereo speaker ports for audio playback - either text-to-speech, alerts or for creating a voice assistant
Stereo headphone out for audio playback through a stereo system, headphones, or powered speakers
Stereo microphone input - perfect for making your very own smart home assistants
Two 3-pin JST STEMMA connectors that can be used to connect more buttons, a relay, or even some NeoPixels!
STEMMA QT plug-and-play I2C port, can be used with any of our 50+ I2C STEMMA QT boards, or can be used to connect to Grove I2C devices with an adapter cable
5-Way Joystick + Button for user interface and control
Three RGB DotStar LEDs for colorful LED feedback

features_5

The STEMMA QT port means you can attach heat image sensors like the Panasonic Grid-EYE or MLX90640. Heat-Sensitive cameras can be used as a person detector, even in the dark! An external accelerometer can be attached for gesture or vibration sensing such as machinery/industrial predictive maintenance projects.

Pinouts

pinouts_6

pinouts_7

pinouts_8

Power

5.0V - Connected to the display backlight
3.3V - Connected to the display power and also the STEMMA QT / Qwiic connector
GND - Ground for everything

Display

The display is a 1.54" wide-angle TFT LCD.

MOSI, SCK, GPIO #25, CE0 - These are the display control pins. Note that MISO is not connected even though it is a SPI pin because you cannot read back from the display
GPIO #26 - This is the display backlight pin. Used to turn on and off the backlight

display_9

Buttons and Joystick

These pins have a 10K pullup to 3.3V so when the button is pressed or the joystick is moved/pressed, you will read a LOW voltage on these pins.

GPIO#17 - Button
GPIO #16 - Joystick select
GPIO #22 - Joystick left
GPIO #23 - Joystick right
GPIO #24 - Joystick up
GPIO #27 - Joystick down

buttons_10

Sound

GPIO #18, GPIO#19, GPIO #20, GPIO #21 - I2S Digital Audio
Speakers - The two speaker connectors are located on the bottom in the middle, labeled Right and Left. Plug in an enclosed speaker or use a JST 2PH cable to attach custom speakers
Microphones - The two mics are in the middle of each side, labeled Left Mic and Right Mic
Headphones - Headphone jack located on the bottom right. Use any headphones or Line-Out to another audio system
On/Off Switch - Located on the left towards the top, switches audio on and off.

sound_11

STEMMA QT Connector

SCL, SDA - I2C data for the STEMMA QT / Qwiic connector. Not used by buttons or display. Can also use with Grove sensors with an adapter cable. Great for quickly adding sensors or accessories with plug-and-play.

connector_12

Digital/Analog Connectors

GPIO#12 and GPIO #13 - 3-pin JST digital or analog connectors. Easily connect things like NeoPixels or servos using this 2mm connector. You can also use a generic JST cable to connect to a breadboard.

digital_analog_13

DotStar LEDs

Three fully color RGB addressable LEDs can provide feedback or a light show. Uses DotStar protocol (not NeoPixel) so any microcomputer can easily control the lights.

GPIO #5 - DotStar LED data pin
GPIO #6 - Dotstar LED clock pin

LEDs_14

Fan

GPIO #4 - The fan is on this pin

fan_15

Required Parts

Before you start, you'll need some parts to make your BrainCraft HAT run! At a minimum you will need:

Raspberry Pi Computer

A working Raspberry Pi (Pi 4+ needed for vision projects, any Pi for audio-only projects)

Raspberry Pi 4 Model B - 2 GB RAM

Power Supply

And an SD card. It can be blank or come with software on it.

SD/MicroSD Memory Card (8 GB SDHC)

For Vision projects

You'll also want a Raspberry Pi camera, a long cable (optional) and camera case (optional).

For Audio Projects

You'll want at least a set of headphones or plug-in speakers!

Cell-phone TRRS Headset - Earbud Headphones w/ Microphone
Mono Enclosed Speaker with Plain Wires - 3W 4 Ohm

Raspberry Pi Setup

OK now you have all your parts in order, it's time to get your Raspberry Pi computer set up with the HAT or Bonnet.

Step 1 - Burn SD Card

Use Etcher or the Raspberry Pi Imager to burn the latest Raspbian Lite to an SD card (you can use full, but we won't be using the desktop software and it takes up a bunch of room.

RaspberryPi_16

Step 2 - Configure log-in access

You'll need to be able to log into your Pi, either enable SSH access (and use and Ethernet cable), use a USB to serial cable, or connect a monitor and keyboard. Basically, get it so you can log in.

We have a quickstart guide here and here that you can follow, or there's dozens of online guides. it is assumed by the next step you are able to log in and type commands in - ideally from a desktop computer, so you can copy and paste in some of the very long commands!

Step 3 - Log in & Enable Internet

Once you've logged in, enable WiFi (if you have built in WiFi) with sudo raspi-config so you can ssh in.

Enable SSH as well if you haven't yet, also via sudo raspi-config

configuraton_17

configuraton_18

After you're done, reboot, and verify you can log into your Pi and that it has internet access by running ping -c 3 raspberrypi.org and seeing successful responses.

access_19

Step 4 - Update/Upgrade

Now that you are logged in, perform an update/update:

sudo apt update

sudo apt-get update

sudo apt-get upgrade

and

sudo apt-get install -y python3-pip

sudo pip3 install --upgrade setuptools

update_20

OK you've now got a nice, clean, connected, and up-to-date Pi!

Blinka Setup

Blinka is our CircuitPython library compatibility layer. It allows many of the libraries that were written for CircuitPython to run on CPython for Linux. To learn more about Blinka, you can check out our CircuitPython on Linux and Raspberry Pi guide.

We put together a script to easily make sure your Pi is correctly configured and install Blinka. It requires just a few commands to run. Most of it is installing the dependencies.

Download: file

Copy Code

cd ~
sudo pip3 install --upgrade adafruit-python-shell
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py
sudo python3 raspi-blinka.py

When it asks you if you want to reboot, choose yes.

reboot_21

Finally, once it reboots, there are just a couple CircuitPython libraries to install for the BrainCraft HAT or Voice Bonnet.

The DotStar library is for controlling the 3 on-board DotStar LEDs and the Motor library is for testing out the GPIO pins.

Download: file

Copy Code

pip3 install --upgrade adafruit-circuitpython-dotstar adafruit-circuitpython-motor adafruit-circuitpython-bmp280

library_22

That's it for Blinka and CircuitPython libraries.

Audio Setup

Start by making sure you've installed I2C support, see the previous page (Blinka Setup) on how to do it!

Install Voicecard software

Make sure you've got the BrainCraft HAT or Voice Bonnet installed, and I2C support installed as well!

When you run sudo i2cdetect -y 1

you should see an entry under 1A, indicating the hardware sees the audio card. The number may also appear as UU if you already installed software.

audio_23

At the command line run:

sudo apt-get install -y git
git clone https://github.com/HinTak/seeed-voicecard
cd seeed-voicecard
git checkout v5.5
sudo ./install.sh

At the end you should see something like this:

commandline_24

Reboot with

sudo reboot

and on reboot run

sudo aplay -l

To list all sound cards, you should see it at the bottom.

rebootrun_25

If your card number differs from the above image, take note of your number.

You can use alsamixer to adjust the volume, don't forget to select the card with F6.

volume_26

A gain of about 60% is plenty loud!

gain_27

Headphone/Speaker Test

Make sure the Audio On/Off switch is set to ON!

With either headphones plugged into the headphone jack or a speaker attached to the speaker port, run.

speaker-test -c2

you will hear white noise coming out of the speakers/headphones!

If you don't hear anything, make sure you have the audio on/off switch set!

set_28

Microphone Test

There are two microphones, and now we can test that they work. This test is best done with headphones, not using the speaker port, because it can cause a painful feedback effect if the speakers are next to the mics!

Run:

sudo arecord -f cd -Dhw:1 | aplay -Dhw:1

If your sound card ID is not #1, then replace the number in both of the -Dhw: parameters with your actual number.

Then either gently rub each microphone or speak to hear yourself echoed!

test_29

Control-C to quit when done

Your audio subsystem is now completely tested!

Fan Service Setup

We have a really simple fan service that will control the onboard fan. The reason we have it set up as a service instead of keeping the fan on all the time is so that it doesn't drain too much power from the Pi during the initial power on.

The fan service basically controls turning GPIO 4 on at startup, which is what the fan is connected to. Installing the fan service is really simple and we have a script for doing that.

To install, just type in the following commands.

Download: file

Copy Code

cd ~
sudo pip3 install --upgrade adafruit-python-shell
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/adafruit_fanservice.py
sudo python3 adafruit_fanservice.py

code_30

A message letting you know what the script does will come up.

script_31

When it asks you if you want to continue, select Yes.

completesetup_32

That's it. You should hear the fan start up right after the script finishes running.

Display Module Install

There's two ways you can use the 1.54" 240x240 display on the BrainCraft HAT. For machine learning purposes, the advanced method is the way to go, so that's what we'll be covering in this guide.

Be aware that you can only choose to do one way at a time. If you choose the advanced way, it will install the kernel driver, which will prevent you from doing it the easy way without uninstalling the driver first.

The easy way is to use 'pure Python 3' and Pillow library to draw to the display from within Python. This is great for showing text, stats, images etc that you design yourself. If you want to do that, the BrainCraft HAT has a pretty close layout to the Adafruit 1.3" Color TFT Bonnet including the same type of display and a joystick, though the pinouts are slightly different. If you choose this option, You can skip this page and view the Python Setup page for instruction for that display.

The advanced way is to install a kernel module to add support for the TFT display that will make the console appear on the display. This is cute because you can have any program print text or draw to the framebuffer (or, say, with pygame) and Linux will take care of displaying it for you. If you don't need the console or direct framebuffer access, please consider using the 'pure Python' technique instead as it is not as delicate.

If you plan on using the Pi Camera for vision projects, you will need to go with the advanced route!

Installing The 1.54" Kernel Module

We have tried to make this as easy as possible for you by providing a script that takes care of everything. There's only a couple of dependencies needed. To get everything setup, just run the following at the terminal:

Download: file

Copy Code

cd ~
sudo pip3 install --upgrade adafruit-python-shell click==7.0
sudo apt-get install -y git
git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git
cd Raspberry-Pi-Installer-Scripts
sudo python3 adafruit-pitft.py --display=st7789_240x240 --rotation=180 --install-type=fbcp

install_33

When you get asked to reboot, reboot!

kernel_34

That's it! You will now have the BrainCraft HAT with a console display on it.

Camera Test

Now that you have everything set up, it's time to do an initial test with the camera. This should display what the camera sees on the display.

raspistill -t 0

camera_35

Python Usage

At this point, you should have just about everything already set up.

Besides the display, audio, and fan, this board has quite a few other useful features on it that can be controlled through Python. We'll go through those and how to control them in Python.

Joystick and Button

The 5-way Joystick and button just use simple digitalio and each uses a separate GPIO, so they're really simple to control. Here's a little script that will setup the GPIOs, Create Internal Pullups, and then print out the value to the terminal.

Download: file

Copy Code

import time
import board
from digitalio import DigitalInOut, Direction, Pull

BUTTON_PIN = board.D17
JOYDOWN_PIN = board.D27
JOYLEFT_PIN = board.D22
JOYUP_PIN = board.D23
JOYRIGHT_PIN = board.D24
JOYSELECT_PIN = board.D16

buttons = [BUTTON_PIN, JOYUP_PIN, JOYDOWN_PIN,
           JOYLEFT_PIN, JOYRIGHT_PIN, JOYSELECT_PIN]
for i,pin in enumerate(buttons):
  buttons[i] = DigitalInOut(pin)
  buttons[i].direction = Direction.INPUT
  buttons[i].pull = Pull.UP
button, joyup, joydown, joyleft, joyright, joyselect = buttons

while True:
  if not button.value:
    print("Button pressed")
  if not joyup.value:
    print("Joystick up")
  if not joydown.value:
    print("Joystick down")
  if not joyleft.value:
    print("Joystick left")
  if not joyright.value:
    print("Joystick right")
  if not joyselect.value:
    print("Joystick select")

  time.sleep(0.01)

Go ahead and save the above code onto your Pi as button_test.py and run it with the following command:

python button_test.py

Now try moving the joystick and press the button and you should see it print out what you're pressing.

printout_36

DotStar LEDs

The 3 DotStar LEDS can be controlled with the DotStar CircuitPython Library. Here's a little script that will setup the DotStar LEDs and then color cycle them.

Download: file

Copy Code

import time
import board
import adafruit_dotstar

DOTSTAR_DATA = board.D5
DOTSTAR_CLOCK = board.D6

dots = adafruit_dotstar.DotStar(DOTSTAR_CLOCK, DOTSTAR_DATA, 3, brightness=0.2)

def wheel(pos):
    # Input a value 0 to 255 to get a color value.
    # The colours are a transition r - g - b - back to r.
    if pos < 0 or pos > 255:
        return (0, 0, 0)
    if pos < 85:
        return (255 - pos * 3, pos * 3, 0)
    if pos < 170:
        pos -= 85
        return (0, 255 - pos * 3, pos * 3)
    pos -= 170
    return (pos * 3, 0, 255 - pos * 3)

while True:
    for j in range(255):
        for i in range(3):
            rc_index = (i * 256 // 3) + j * 5
            dots[i] = wheel(rc_index & 255)
        dots.show()
        time.sleep(0.01)

Go ahead and save the above code onto your Pi as dotstar_test.py and run it with the following command:

python dotstar_test.py

The DotStar LEDs should start color-cycling in a rainbow.

Dotstar_37

GPIO JST connectors

GPIOs 12 and 13 are accessible with the JST connectors on either side of the BrainCraft HAT.

Parts

For this script, we'll just need one part that isn't included with the BrainCraft HAT:

Micro Servo with 3-pin JST Cable - STEMMA Connector Compatible

Wiring

Connect the JST PH 3-pin plug into the GPIO #12 side of the BrainCraftHAT

Download Fritzing Diagram

Code

Download: file

Copy Code

import time
import board
import pulseio
from adafruit_motor import servo

SERVO_PIN = board.D12
pwm = pulseio.PWMOut(SERVO_PIN, frequency=50)
servo = servo.Servo(pwm, min_pulse=750, max_pulse=2250)

while True:
    for angle in range(0, 180, 5):  # 0 - 180 degrees, 5 degrees at a time.
        servo.angle = angle
        time.sleep(0.05)
    for angle in range(180, 0, -5): # 180 - 0 degrees, 5 degrees at a time.
        servo.angle = angle
        time.sleep(0.05)

Go ahead and save the above code onto your Pi as servo_test.py and run it with the following command:

python servo_test.py

The servo should start sweeping back and forth in 5 degree increments.

servo_38

Stemma QT

For the Stemma QT port, you can use any of our 50+ sensors, but we're going to use a script that demonstrates using the BMP280 because it's so simple.

Parts

For this script, we'll just need a BMP280 and a Stemma QT cable:

Wiring

Connect one side of the Stemma QT cable to either port on the BMP280
Connect the other side to the Stemma QT port on the BrainCraft HAT

Download Fritzing Diagram

Code

Download: Project Zip or bmp280_simpletest.py | View on Github

Copy Code

"""Simpletest Example that shows how to get temperature,
   pressure, and altitude readings from a BMP280"""
import time
import board

# import digitalio # For use with SPI
import busio
import adafruit_bmp280

# Create library object using our Bus I2C port
i2c = busio.I2C(board.SCL, board.SDA)
bmp280 = adafruit_bmp280.Adafruit_BMP280_I2C(i2c)

# OR create library object using our Bus SPI port
# spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
# bmp_cs = digitalio.DigitalInOut(board.D10)
# bmp280 = adafruit_bmp280.Adafruit_BMP280_SPI(spi, bmp_cs)

# change this to match the location's pressure (hPa) at sea level
bmp280.sea_level_pressure = 1013.25

while True:
    print("\nTemperature: %0.1f C" % bmp280.temperature)
    print("Pressure: %0.1f hPa" % bmp280.pressure)
    print("Altitude = %0.2f meters" % bmp280.altitude)
    time.sleep(2)