Micro-RDK Development Setup

Follow these steps to install and build the micro-RDK on your ESP32 for development:

  1. Install the required software
  2. Set up your development environment manually or with Viam’s Canon CLI utility (recommended)
  3. Install the Micro-RDK

Hardware requirements

You need an Espressif ESP32 microcontroller to use the micro-RDK. Viam recommends purchasing the ESP32 with a development board. The following ESP32 microcontrollers are supported:

Your microcontroller should have at least the following resources available to work with the micro-RDK:

  • 2 Cores + 384kB SRAM + 2MB PSRAM + 4MB Flash

Software requirements

The micro-RDK is written in Rust. To be able to develop the micro-RDK on macOS and Linux systems, you must install the following software on your development machine:

Install dependencies

sudo apt-get install git libssl-dev dfu-util libusb-1.0-0 libudev-dev

If you haven’t already, install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then, install dfu-util:

brew install dfu-util

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

See the Rust Installation guide for more information and other installation methods.

Install cargo-generate with cargo

cargo installs automatically when downloading Rust with rustup.

Run the following command to install cargo-generate:

cargo install cargo-generate

Install espflash

Run the following command to install espflash

cargo install espflash

Set up your development environment

Canon is a CLI utility for managing a Docker-based canonical environment.

Canon requires a working installation of Docker Engine.

Install Docker Engine before proceeding. If you are running Docker Engine on Linux, make sure that you go through the post installation steps to run Docker automatically on startup.

Make sure your system has Go 1.19 or later installed. Verify your version of Go with go version.

go install github.com/viamrobotics/canon@latest

Make sure to add the go binary folder to your PATH by running: export PATH=$PATH:$(go env GOPATH)/bin.

brew install viamrobotics/brews/canon

To set up the Docker development environment for ESP manually, complete the following instructions:

Install build dependencies

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
brew install cmake ninja dfu-util

Install and activate the ESP-IDF

Clone Viam’s fork of the ESP-IDF, the development framework for Espressif SoCs (System-on-Chips) supported on Windows, Linux and macOS:

mkdir -p ~/esp
cd ~/esp
git clone --depth 1 -b v4.4.4 --single-branch --recurse-submodules --shallow-submodules https://github.com/viamrobotics/esp-idf

Then, install the required tools for ESP-IDF:

cd ~/esp/esp-idf
./install.sh esp32

To activate ESP-IDF, run the following command to source (.) the activation script export.sh:

. $HOME/esp/esp-idf/export.sh

Install the Rust ESP toolchain and activate the ESP-RS virtual environment

First, install the following tools with cargo:

cargo install espup
cargo install cargo-espflash
cargo install ldproxy

To download and install the esp-rs toolchain, run:

espup install -s -f ~/esp/export-rs.sh -v 1.67.0

To activate the ESP Rust toolchain, run the following command to source (.) the activation script export-rs.sh:

. $HOME/esp/export-rs.sh

Install the micro-RDK

Create a new machine

Navigate to the Viam app and add a new machine in your desired location.

Click on the name of the machine to go to the machine’s page. Then, navigate to the CONFIGURE tab.

Configure your machine with an ESP32

Client API usage with the micro-RDK is currently limited to the following supported resources:

See micro-RDK to get a list of supported models and instructions on how to configure them. Follow this guide to configure an esp32 board on your machine.

Generate a new project from the micro-RDK template

Start Docker on your development machine. If you haven’t already, complete Docker’s Linux post installation steps to set up Docker to run whenever your system boots up.

Use the Micro-RDK template to create a new Micro-RDK project to upload to your ESP32 by running:

cargo generate --git https://github.com/viamrobotics/micro-rdk.git

Select templates/project when prompted.

You will be prompted to paste your machine’s viam-server app JSON configuration into the terminal. To obtain this:

  • Navigate to your new machine’s page on the Viam app and select the CONFIGURE tab.
  • Select the part status dropdown to the right of your machine’s name on the top of the page: The part status dropdown of an offline machine.
  • Click the copy icon underneath Viam server configuration to copy the viam-server app JSON configuration. The micro-RDK needs this JSON, which contains your machine part secret key and cloud app address, to connect to the Viam app.
  • Paste the viam-server app config into your terminal when prompted.

Upload the micro-RDK to your ESP32

Now, upload the project to connect to your ESP32 and remotely control it live on the Viam app:

cd <your-path-to/your-project-directory>
canon bash -lc "make build-esp32-bin"
make flash-esp32-bin

Make sure you have run . ~/dev/esp/export-rs.sh and . ~/dev/esp/esp-idf/export.sh before running the following command:

make upload

If successful, you will retain a serial connection to the board until you press Ctrl-C. To manage this connection, consider running it within a dedicated terminal session, or under tmux or screen. While the serial connection is live, you can also restart the currently flashed image with Ctrl-R.

Navigate to your new machine’s page on the Viam app. If successful, Live should be displayed underneath Last online.


If you run into the error Failed to open serial port when flashing your ESP32 with Linux, make sure the user is added to the group dialout with sudo gpasswd -a $USER dialout

You can find additional assistance in the Troubleshooting section.

You can also ask questions in the Community Discord and we will be happy to help.