Lesson 04: Google Coral Edge TPU and PyCoral on Pi 5

Product Link: Coral.ai

The Coral M.2 Accelerator with Dual Edge TPU integrates two Edge TPU coprocessors into systems via an M.2 E-key interface. Each coprocessor performs 4 trillion operations per second (TOPS) at 2 watts, doubling inference capability to 8 TOPS. It supports high-speed ML inferencing, running models like MobileNet v2 at nearly 400 FPS. The device is compatible with Debian Linux and Windows 10 and supports TensorFlow Lite models. The module measures 22 mm x 30 mm and requires compatible card slots for both TPUs.

4.1 Configure the Google Coral Edge TPU

Step 1: Configure Hardware Settings

First, you must edit the Raspberry Pi configuration file to enable the necessary hardware settings for the Coral Edge TPU. Open the config file by running:

sudo nano /boot/firmware/config.txt

Add the following lines to the file:

[all]
# Enable the PCIe External connector.
dtparam=pciex1
kernel=kernel8.img
# Enable Pineboards Hat Ai
dtoverlay=pineboards-hat-ai

Save and close the file, then reboot your Raspberry Pi to apply these changes.

sudo reboot

Step 2: Update the Kernel

Kernel version 6.6.30 or higher is required for the Pineboards Hat Ai overlay. This version is currently only available via rpi-update. To check your kernel version, use this command:


uname -a

Expected output:

Linux pi5 6.6.62+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.6.62-1+rpt1 (2024-11-25) aarch64 GNU/Linux

You should see 6.6.xx+rpt-rpi-v8. The important part is the v8 at the end. If the version ends with v8+, you may need to downgrade the Kernel Firmware. If your Pi 5 Kernel version does not meet the required specifications, refer to the guide on [1.3 Update Pi 5 Kernel Firmware and Install Kerner Headers (Optional)] to update the Kernel.

Step 3: Check Physical Connection

To verify that the Google Coral is properly connected, run the following command in the terminal:


lspci | grep Coral
0000:06:00.0 System peripheral: Global Unichip Corp. Coral Edge TPU
0000:07:00.0 System peripheral: Global Unichip Corp. Coral Edge TPU

If no result is displayed, ensure the following:

All physical connections are secure and correctly configured according to the instructions provided with your PCIe HAT.
All steps outlined in this guide up to this point have been completed accurately.

Step 4: Install the PCIe Driver and Edge TPU Runtime

Update your package list:

sudo apt update

Add the Google Coral Edge TPU package repository:

echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list

Import the repository GPG key:


curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

Update your package list again:

sudo apt-get update

Install the necessary packages:

sudo apt-get install cmake libedgetpu1-std devscripts debhelper dkms dh-dkms

Step 5: Install the Gasket Driver

Clone the Gasket driver repository:

git clone https://github.com/google/gasket-driver.git

Change into the directory and build the driver:


cd gasket-driver
sudo debuild -us -uc -tc -b

Go back to the parent directory and install the built package:


cd ..
sudo dpkg -i gasket-dkms_1.0-18_all.deb

If you encounter an error during this step, verify the kernel firmware version and ensure the kernel header files are installed. For assistance, refer to [1.3 Update Pi 5 Kernel Firmware and Install Kerner Headers (Optional)].

Step 6: Set Up the udev Rule

Add a udev rule to manage device permissions:

sudo sh -c "echo 'SUBSYSTEM==\"apex\", MODE=\"0660\", GROUP=\"apex\"' >> /etc/udev/rules.d/65-apex.rules"

Create a new group and add your user to it:


sudo groupadd apex
sudo adduser $USER apex

Reboot your Raspberry Pi to apply all changes:

sudo reboot

Verify if the driver is loaded using the following command:


sudo lspci -v

Expected output:


0000:01:00.0 System peripheral: Global Unichip Corp. Coral Edge TPU (prog-if ff)
Subsystem: Global Unichip Corp. Coral Edge TPU
Flags: bus master, fast devsel, latency 0, IRQ 39
Memory at 1800100000 (64-bit, prefetchable) [size=16K]
Memory at 1800000000 (64-bit, prefetchable) [size=1M]
Capabilities: [80] Express Endpoint, MSI 00
Capabilities: [d0] MSI-X: Enable+ Count=128 Masked-
Capabilities: [e0] MSI: Enable- Count=1/32 Maskable- 64bit+
Capabilities: [f8] Power Management version 3
Capabilities: [100] Vendor Specific Information: ID=1556 Rev=1 Len=008 <?>
Capabilities: [108] Latency Tolerance Reporting
Capabilities: [110] L1 PM Substates
Capabilities: [200] Advanced Error Reporting
Kernel driver in use: apex
Kernel modules: apex

Your Raspberry Pi is now configured to use the Coral Edge TPU. You can begin deploying machine learning models and running inference tasks with improved processing power.

4.2 Installing PyCoral for Google Coral on Pi 5

Google Coral TPUs often provide the first AI experience for many Raspberry Pi users, with PyCoral being a popular solution for utilizing these devices. While there are some challenges, following this guide will ensure a working installation.

Note: This guide applies to the standard Google Coral TPU and the Dual Edge Coral TPU.

Update System Packages

Start by updating your system packages to ensure everything is up-to-date:


sudo apt update
sudo apt upgrade

Installing the Necessary Drivers for the Coral TPU

Follow the [4.1 Configure the Google Coral Edge TPU] to configure the drivers on Pi 5.

PyCoral on Docker Container

Installing Docker for Raspberry Pi 5

Follow the [2.1 Installing Docker on Raspberry Pi 5] to configure the Docker on Pi 5.

Creating PyCoral Docker Container

With Docker installed, you can create a Docker container to run PyCoral. Jeff Geerling has provided a ready-to-use Dockerfile, so we’ll use that.

Create a Dockerfile:
Create a file named Dockerfile.

nano Dockerfile

Add the following content:


FROM debian:10 
 
WORKDIR /home 
ENV HOME /home 
RUN cd ~ 
RUN apt-get update 
RUN apt-get install -y git nano python3-pip python-dev pkg-config wget usbutils curl 
 
RUN echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" \ 
| tee /etc/apt/sources.list.d/coral-edgetpu.list 
RUN curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - 
RUN apt-get update 
RUN apt-get install -y edgetpu-examples

Build the Docker Image: Run the following command to build the Docker image:
```
sudo docker build -t "coral" .
```
This will create a Docker container with the necessary environment for running PyCoral.

Testing the PyCoral Docker Container

Now that you have created the Docker container, it's time to test your Google Coral TPU.

Verify the Coral TPU Device: Check if the /dev/apex_0 device is present:
```
ls /dev | grep apex
apex_0
apex_1
        
```
If apex_0 or apex_1 is not displayed, ensure all connections are correct and previous steps were followed.

Initialize the Docker Container: Run the Docker container, passing the apex_0 device:


sudo docker run -it --device /dev/apex_0:/dev/apex_0 --device /dev/apex_1:/dev/apex_1 coral /bin/bash

Run an Example Script: Within the Docker container, execute a sample PyCoral script:


python3 /usr/share/edgetpu/examples/classify_image.py \
--model /usr/share/edgetpu/examples/models/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
--label /usr/share/edgetpu/examples/models/inat_bird_labels.txt \
--image /usr/share/edgetpu/examples/images/bird.bmp

Expected Output: You should see classification results similar to:


---------------------------
Poecile atricapillus (Black-capped Chickadee)
Score :  0.44140625
---------------------------
Poecile carolinensis (Carolina Chickadee)
Score :  0.29296875

Exit the Container: Press CTRL+D to exit the container and return to Raspberry Pi OS.

This confirms that your PyCoral Docker container is set up and functioning correctly with your Google Coral TPU on Raspberry Pi 5.

PyCoral on Local

Install the PyCoral Library in venv

Here, recommand creating an enviroment that using Python 3.8.x, since the pycore that download from google-coral.github.io is a very old version of pycoral which does not have pycoral.adapter module.

Install the PyCoral Library

To interact with the Edge TPUs using Python, install the PyCoral library:

Create and activate a Python virtual environment:


python3 -m venv coral_env
source coral_env/bin/activate

Upgrade pip and install PyCoral:


pip install --upgrade pip
pip install --extra-index-url https://google-coral.github.io/py-repo/ pycoral

Test the Edge TPUs

Download example scripts and test the Edge TPUs:

Clone the PyCoral repository:


git clone https://github.com/google-coral/pycoral.git
cd pycoral

Install example requirements:


bash examples/install_requirements.sh classify_image.py

Run an example script:


python3 examples/classify_image.py \
  -m test_data/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
  -l test_data/inat_bird_labels.txt \
  -i test_data/parrot.jpg

Install the PyCoral local

Install Dependencies

Install the necessary dependencies:


sudo apt install git curl python3-pip

Install TensorFlow Lite Runtime

Add the TensorFlow Lite package repository:


echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
sudo apt update

Install TensorFlow Lite runtime:


sudo apt install python3-tflite-runtime

Install PyCoral

Use pip to install the PyCoral library:


pip3 install pycoral

Verify Installation

Run a simple verification script to ensure everything is installed correctly. Create a new Python script:


nano verify_pycoral.py

Add the following lines to the script:


from pycoral.utils.edgetpu import list_edge_tpus

devices = list_edge_tpus()
print("Detected Edge TPUs:", devices)

Run the script:


python3 verify_pycoral.py

If the installation was successful, you should see a list of detected Edge TPUs.

You have successfully installed PyCoral on your Raspberry Pi 5. Now, You can develop and run your machine learning models on the Google Coral Edge TPU.