Get started with the Dev Board

The Coral Dev Board is a single-board computer that contains an Edge TPU coprocessor. It's ideal for prototyping new projects that demand fast on-device inferencing for machine learning models. This page is your guide to get started.

The setup requires flashing Mendel Linux to the board, and then accessing the board's shell terminal. Once you have terminal access and update some of the software, we'll show you how to run an image classification model on the board.

If you want to learn more about the hardware, see the Dev Board datasheet.

Warning: Use caution when handling the Dev Board to avoid electrostatic discharge or contact with conductive materials (metals). Failure to properly handle the Dev Board can result in a short circuit, electric shock, serious injury, death, fire, or damage to your board and other property.

Requirements

Note: Do not power the board or connect any cables until instructed to do so.

Before you begin, collect the following hardware:

  • Linux or Mac computer (referred to below as "host computer")
  • USB-A to USB-micro-B cable (to connect your PC to the board's serial port)
  • USB-A to USB-C cable (to connect your PC to the board's data port)
  • 2 - 3A (5V) USB Type-C power supply (such as a phone charger)
  • Ethernet cable or Wi-Fi connection

You also need the following software tools on your host computer:

  • A serial console program such as screen, picocom, or PuTTY (among many others).

    Our instructions use screen and it's available on Mac computers by default.

    If you're on Linux and don't already prefer another program, we suggest you install screen as follows:

    sudo apt-get install screen

  • The latest fastboot tool.

    Even if you already have fastboot (perhaps for Android projects), you may need to update it, so we suggest you get the latest version now.

    Download the Android SDK Platform-tools.

    There are many tools in this package, but you only need fastboot, so save that one (and delete the rest):

    mkdir -p ~/.local/bin
    
    sudo mv ~/Downloads/platform-tools/fastboot ~/.local/bin/

    Now verify it works:

    fastboot --version

    For Mac compatibility, the version must be 28.0.2 or higher.

  • The Mendel Development Tool (MDT).

    MDT is a command line tool that helps you perform tasks with connected Mendel devices, such as this Dev Board. For example, MDT can list connected devices, install Debian packages on a device, open a shell with a device, and more.

    Install MDT using pip as follows:

    pip3 install --user mendel-development-tool
    Help! If you're on a Mac and see an error that pip3 is not found, then you probably don't have Python3. To resolve, install Homebrew, run brew install python3, and then try again.
    Note: The --user flag installs the mdt executable in your user directory. On Linux, that's ~/.local/bin/. On a Mac, it's something like /Users/yourname/Library/Python/3.7/bin/. If you remove that flag, it requires root access and will install at /usr/local/bin. So make sure that the appropriate path is in your PATH environment variable.

Now you're ready to flash the board and log in.

Note: Although you can connect a keyboard and monitor to the board, we do not recommend it because the system is not designed to operate as a desktop environment and doing so can affect the system performance. So our documentation emphasizes use of a terminal when interacting with the Dev Board (either with the serial console or SSH).

1. Flash the board

The factory settings do not include a system image, only the U-Boot bootloader.

Before you begin the flashing procedure, verify the following:

  • The board is completely unplugged (not powered and not connected to your computer).
  • The boot mode switches are set to eMMC mode (see figure 1):
Boot mode Switch 1 Switch 2 Switch 3 Switch 4
eMMC ON OFF OFF OFF
Figure 1. Boot switches set to eMMC mode

Now flash the board as follows.

Note: If you have already flashed the board once before (or it's bricked), instead read Reflash the Coral Dev Board.

1. Initiate fastboot mode

If your Dev Board was manufactured before April 10, 2019, then you need to initiate fastboot on the board as follows.

You can determine the manufactured date from the serial number etched onto the heat sink, as shown in figure 2.

Figure 2. The manufactured date in the serial number
Field Description
Year Last digit of the year of manufacture: 0 - 9
Month Month of manufacture: 1 to 9 (Jan to Sep), A (Oct), B (Nov), C (Dec)
Day Day of manufacture: 01 to 31 (1st to 31st)

If your serial number starts with "9410" or higher, then it was manufactured on April 10th, 2019, or later, so you can skip to execute the flash script (because your board automatically boots into fastboot mode).

But if the date reads "9409" or lower, then you need to perform the following steps to enable fastboot mode:

  1. Install the udev rule or driver on your host computer.

    This is required to communicate with the Dev Board over the serial console.

    • On Linux:

      Run the following commands to add the required udev rule:

      sudo sh -c "echo 'SUBSYSTEM==\"usb\", ATTR{idVendor}==\"0525\", MODE=\"0664\", \
      GROUP=\"plugdev\", TAG+=\"uaccess\"' >> /etc/udev/rules.d/65-edgetpu-board.rules"
      
      sudo udevadm control --reload-rules && sudo udevadm trigger
    • On Mac:

      Caution: Before installing the following package, be sure you've applied all available macOS software updates. Otherwise, you might be blocked from installing due to system security that disables the Allow button in System Preferences.

      Install the CP210x USB to UART Bridge Virtual COM Port (VCP) driver for Mac.

  2. Connect to the serial console.

    Use your micro-B USB cable to connect your host computer to the serial console port on the board (see figure 3). The orange and green LEDs on the board should illuminate.

    Note: The board should not be powered on yet.

    Figure 3. A micro-B USB cable connected to the serial console port

    Now open a terminal on your host computer and start the serial console as follows:

    • On Linux:

      Determine the device filename for the serial connection by running this command on your Linux computer:

      dmesg | grep ttyUSB
      

      You should see two results such as this:

      [ 6437.706335] usb 2-13.1: cp210x converter now attached to ttyUSB0
      [ 6437.708049] usb 2-13.1: cp210x converter now attached to ttyUSB1
      

      Then use the name of the first filename listed as a cp210x converter to open the serial console connection (this example uses ttyUSB0 as shown from above):

      screen /dev/ttyUSB0 115200
    • On Mac:

      screen /dev/cu.SLAB_USBtoUART 115200

    The prompt should disappear and your terminal should become completely blank. That's expected, because you've established a connection but the board is not turned on yet.

    Help! If screen prints Cannot access line '/dev/ttyUSB0', then your Linux user account is not in the plugdev and/or dialout system group. Ask your system admin to add your account to both groups, and then restart your computer for it to take effect.

    If you see [screen is terminating], it might also be due to the system groups, or there's something else wrong with screen—ensure all screen sessions are closed (type screen -ls to see open sessions), unplug the USB cable from the Dev Board, and then try again.

  3. Power the board.

    Plug in your 2 - 3A power cable to the USB-C port labeled "PWR" (see figure 4).

    Caution: Do not attempt to power the board by connecting it to your computer.

    Figure 4. A USB-C power cable connected to the board (in addition to the serial cable)

    The board's red LED will illuminate and the fan might turn on.

    Help! If you still don't see anything in the serial console screen, press Enter.

    Your serial console (the screen terminal) should arrive at the u-boot prompt. You should see a "Welcome" message that tells you to visit g.co/coral/setup, which brings you to this page. So you're all good; you can continue.

    Note: If you instead see a long stream of messages, followed by a login prompt, then your board is already flashed with a system image. You can either disconnect the serial console and connect to the shell with MDT or if you still want to reflash the board, then instead read Reflash the Coral Dev Board.
  4. Start fastboot.

    In your serial console's u-boot prompt, execute the following:

    fastboot 0
    

    The cursor should simply move to the next line. Fastboot is now waiting for the host to begin flashing a system image.

  5. Disconnect the serial console.

    You won't need the serial console connection anymore, so you can close the terminal and remove the micro-B USB cable.

2. Execute the flash script

Now you're ready to flash the board.

  1. Connect the USB-C cable.

    Use your USB-C cable to connect your host computer to the USB-C data port labeled "OTG" on the Dev Board. (If you skipped the above procedure to initiate fastboot, then you also need to plug in your 2 - 3A power cable to the USB-C port labeled "PWR" and wait a few moments for the board to power on.)

    Figure 5. A USB-C data cable and power cable connected to the board
  2. Verify fastboot sees your device.

    Open a new terminal on your host computer and execute the following command:

    fastboot devices
    

    You should see a line printed like this (your numbers will be different):

    1b0741d6f0609912        fastboot
    

    If you don't see anything printed, be sure you have the latest version of fastboot (as per the requirements above). If you recently updated fastboot but it's still blank, then repeat the steps to initiate fastboot mode.

  3. Download and flash the system image.

    From the same terminal, execute the following:

    cd ~/Downloads
    
    curl -O https://dl.google.com/coral/mendel/enterprise/mendel-enterprise-day-13.zip
    unzip mendel-enterprise-day-13.zip \ && cd mendel-enterprise-day-13
    bash flash.sh

    This starts the flashing process and you'll see various output.

It takes about 5 minutes for flashing to complete. When it's done, the board reboots and your terminal prompt returns to you.

Just a few more steps and you'll be running a TensorFlow Lite model...

2. Connect to the board's shell via MDT

Now that you have the Mendel system on the board, you can initiate a secure shell session using the MDT tool. Using MDT is just an easy way to generate an OpenSSH public/private key pair, push the public key onto the board, and then establish an SSH connection. (You should have already installed MDT on your host computer, as per the above requirements.)

First, be sure you still have the USB data and power connected, as shown in figure 5.

Now make sure MDT can see your device by running this command from your host computer:

mdt devices

You should see output showing your board hostname and IP address:

orange-horse        (192.168.100.2)
Note: Your board's hostname is randomly generated the first time it boots from a new flashing. We do this to ensure that each device within a local fleet is likely to have a unique name. Of course, you can change this name using standard Linux hostname tooling (such as hostname).

Now to open the device shell, run this command:

mdt shell

After a moment, you should see the board's shell prompt.

Note: You must connect to the board via MDT over USB at least once before you can SSH via any other method. Using USB allows MDT to generate an SSH public/private key pair and push it to the board's authorized_keys file, which then allows you to authenticate with SSH. (Using MDT is just easier than manually copying the key over the serial console.)

For more information about what you can do with MDT, read about the Mendel Development Tool.

3. Connect to the internet

You'll need the board online to download system updates, models, and samples.

Either connect an Ethernet cable to the board or select a Wi-Fi network by running the following command in the device shell:

nmtui

Then select Activate a connection and select a network from the list under Wi-Fi (wlan0).

Alternatively, use the following command to connect to a known network name:

nmcli dev wifi connect <NETWORK_NAME> password <PASSWORD> ifname wlan0

Verify your connection with this command:

nmcli connection show

You should see your selected network listed in the output. For example:

NAME                UUID                                  TYPE             DEVICE
MyNetworkName       61f5d6b2-5f52-4256-83ae-7f148546575a  802-11-wireless  wlan0

The DEVICE name is wlan0 for a Wi-Fi connection or eth0 for an Ethernet connection.

4. Update the Mendel software

Some of our software updates are delivered with Debian packages separate from the system image, so make sure you have the latest software by running the following commands:

sudo apt-get update

sudo apt-get dist-upgrade

You should also install the TensorFlow Lite Python runtime:

wget https://dl.google.com/coral/python/tflite_runtime-1.14.0-cp37-cp37m-linux_aarch64.whl

pip3 install tflite_runtime-1.14.0-cp37-cp37m-linux_aarch64.whl

5. Run our demo app

Now you're ready to run a TensorFlow Lite model on the Edge TPU!

For a video demo of the Edge TPU performance, run the following command from the Dev Board terminal:

edgetpu_demo --stream

Then on your desktop (that's connected to the Dev Board)—if you're connected to the board using MDT over USB—open 192.168.100.2:4664 in a browser. If you're instead connected to the board by other means (such as SSH over LAN or with an Ethernet cable), type the appropriate IP address into your browser with port 4664.

You should then see a video playing in your browser. The footage of the cars is a recording, but the MobileNet model is executing in real time on your Dev Board to detect each car.

Or if you have a monitor attached to the Dev Board, you can instead see the demo on that screen:

edgetpu_demo --device
Caution: Avoid touching the heat sink during operation. Whether or not the fan is running, the heat sink can become very hot to the touch and might cause burn injuries.

6. Run a model using the TensorFlow Lite API

The demo above is rather complicated, so we've created some simple examples that demonstrate how to perform an inference on the Edge TPU using the TensorFlow Lite Python API.

Follow these steps to run our image classification example (this requires the TensorFlow Lite Python runtime you should have installed during step 4):

  1. Download the example code from GitHub:

    sudo apt-get install git
    
    mkdir coral && cd coral
    git clone https://github.com/google-coral/tflite.git
  2. Download the bird classifier model, labels file, and a bird photo:

    cd tflite/python/examples/classification
    
    bash install_requirements.sh
  3. Run the image classifier with the bird photo (shown in figure 6):

    python3 classify_image.py \
    --model models/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
    --labels models/inat_bird_labels.txt \
    --input images/parrot.jpg
    
Figure 6. parrot.jpg

You should see results like this:

INFO: Initialized TensorFlow Lite runtime.
----INFERENCE TIME----
Note: The first inference on Edge TPU is slow because it includes loading the model into Edge TPU memory.
13.1ms
2.7ms
3.1ms
3.2ms
3.1ms
-------RESULTS--------
Ara macao (Scarlet Macaw): 0.76562

Congrats! You just performed an inference on the Edge TPU using TensorFlow Lite.

To demonstrate varying inference speeds, the example repeats the same inference five times. It prints the time to perform each inference and then the top classification result (the label ID/name and the confidence score, from 0 to 1.0).

To learn more about how the code works, take a look at the classify_image.py source code and read about how to run inference with TensorFlow Lite.

Note: The example above uses the TensorFlow Lite Python API, but you can also run an inference using the Edge TPU Python API or the TensorFlow Lite C++ API. For information about each option, read the Edge TPU inferencing overview.

Next steps

If you got the Coral Camera, see the guide to connect a camera to the Dev Board.

To run some other types of neural networks, check out our example projects, including examples that perform real-time object detection, pose estimation, keyphrase detection, on-device transfer learning, and more.

If you want to create your own model, see these pages:

Caution: When you're done with the Dev Board, do not simply unplug the Dev Board. Doing so could corrupt the system image if any write operations are in progress. Instead, safely shutdown the system with the following command:
sudo shutdown now

When the red LED on the Dev Board turns off, you can unplug the power.