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 the Mendel Linux system image to the board and then accessing the board's terminal. Once you have terminal access, you can begin running TensorFlow Lite models.

If you want to learn more about the Dev Board hardware, see the 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-microB 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
    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).

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
Note: If you have already flashed the board once before (or it's bricked), instead read Reflash the Coral Dev Board.

Now flash the board as follows:

  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 && 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 USB-microB cable to connect your host computer to the serial console port on the board (see figure 2). The orange and green LEDs on the board should illuminate.

    Note: The board should not be powered on yet.

    Figure 2. A USB-microB 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 3).

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

    Figure 3. 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 skip to step 7 and log in, 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. Connect to fastboot over USB.

    Use your USB-C cable to connect your host computer to the USB-C data port labeled "OTG" on the Dev Board. (This is the connection used to flash the system image.)

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

    Now open a new terminal on your host computer (do not use the screen terminal) and execute the following command:

    fastboot devices
    

    You should see a line printed like this:

    1b0741d6f0609912        fastboot
    

    If you don't see anything printed, verify the board is in fastboot mode (see step 4), and be sure you have the latest version of fastboot (as per the requirements above).

  6. Download and flash the system image.

    From the same terminal (where you ran fastboot), execute the following:

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

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

  7. Log in.

    Switch back to the serial console to observe the flashing progress. It takes about 5 minutes to complete. When it's done, the system reboots and the console prompts you to login. (The login prompt might be obscured by some logs, so press Enter when you notice the logging has stopped.)

    Login is mendel
    Password is mendel

    You should now be in the board's terminal.

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).

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 serial console:

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.

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:

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

sudo apt-get update

sudo apt-get dist-upgrade

Connect to the board's shell via MDT

Using the serial console was necessary only to enable fastboot. Now that you have the Mendel system on the board, you can unplug the microB USB cable and open a shell using MDT over the USB-C cable (see figure 5). (You should have installed MDT on your host computer, as per the above requirements.)

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.

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

To open the shell, run this command on your host computer:

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.

Run a model on the Edge TPU

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 ssh 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.

Try the Edge TPU Python API

The edgetpu_demo shown above performs an inference on each frame of the video using the Edge TPU Python library (the edgetpu Python module). This library includes APIs that make it easy to perform an image classification or object detection inference. So we've created some other sample code to show how you can use these APIs.

First, go to the home directory and download our bird classifier model, labels file, and photo (this is on the Dev Board terminal):

cd ~

wget https://dl.google.com/coral/canned_models/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
https://dl.google.com/coral/canned_models/inat_bird_labels.txt \
https://coral.withgoogle.com/static/docs/images/parrot.jpg

Now navigate to the directory where we've shared the sample scripts and run image classification with the parrot image (shown in figure 5):

cd /usr/lib/python3/dist-packages/edgetpu/demo/

python3 classify_image.py \
--model ~/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
--label ~/inat_bird_labels.txt \
--image ~/parrot.jpg
Figure 5. parrot.jpg

You should see results like this:

---------------------------
Ara macao (Scarlet Macaw)
Score :  0.761719

To learn more about the Python API, see the Edge TPU API overview & demos.

For details about how to create compatible TensorFlow Lite models, read TensorFlow Models on the Edge TPU.

Caution: When you're done, 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.