The Micro-RDK Development Setup
BETA
The micro-RDK is in beta mode and many features supported by the RDK are still being added to the micro-RDK. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.
The micro-RDK is a lightweight version of the Robot Development Kit (RDK) which can run on resource-limited embedded systems that cannot run the fully-featured viam-server.
The only microcontroller the micro-RDK currently supports is the ESP32.
Client API usage with the micro-RDK currently supports the following resources:
Click on each supported resource to see supported models, API methods, and configuration info.
See GitHub for code examples and more information on the micro-RDK.
Get started
Follow these steps to install and build the micro-RDK on your ESP32 for development:
- Install the required software
- Set up your development environment manually or with Viam’s Canon CLI utility (recommended)
- 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:
- ESP32-WROOM Series (until v0.1.7)
- ESP32-WROVER Series
Your microcontroller should have at least the following resources available to work with the micro-RDK:
- 2 Cores + 384kB SRAM + 2MB PSRAM + 4MB Flash
Tip
The main difference between the WROOM and WROVER is that the WROVER has additional RAM with the SPIRAM chip. If you would like to allow more than one concurrent connection to your device we recommend using the WROVER.
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
Tip
You only need to follow these steps if you are not using Canon to build the micro-RDK.
If you have completed your set up with Canon, skip this section and continue to install the Micro-RDK.
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
Tip
To avoid conflicts with other toolchains, adding this command to your .bashrc or .zshrc is not recommended.
Instead, save this command to run in any future terminal session where you need to activate the ESP-IDF development framework.
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 v2.0.0-rc.1
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
Tip
To avoid conflicts with other toolchains, adding this command to your .bashrc or .zshrc is not recommended. Instead, save this command to run in any future terminal session where you need to activate the ESP-IDF development framework.
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:
- Click the copy icon underneath Viam server configuration to copy the
viam-serverapp 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-serverapp config into your terminal when prompted.
Caution
Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
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.
Troubleshooting
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.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!