Microcontroller Setup: the Micro-RDK
ALPHA
The micro-RDK is in alpha 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 is currently limited to the following supported resources:
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:
- Install the required software
- Set up your development enviroment 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.
- Minimal configuration: 384kB Ram 4MB flash
- Recommended configuration: 384kB Ram + 8MB SPIRAM + 4MB Flash
Software Requirements
The micro-RDK is written in Rust. To be able to program the ESP32 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 enviroment
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/npmenard/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 Robot
Navigate to the Viam app and add a new robot in your desired location.
Click on the name of the robot to go to the robot’s page. Then, navigate to the Config tab.
Configure an esp32 board
Info
Theesp32
board model is not currently provided for you as a built-in option in the Viam app, so you cannot use the Config Builder to configure this board.
To add an esp32
board, navigate to the Config tab of your robot’s page in the Viam app and select Raw JSON mode.
Copy the following JSON template and paste it into your configuration inside the "components"
array:
{
"attributes": {
"pins": [
<int>
],
"analogs": [
{
"pin": "<number>",
"name": "<your-analog-name>"
}
]
},
"depends_on": [],
"model": "esp32",
"name": "<your-board-name>",
"type": "board"
}
{
"attributes": {
"pins": [15],
"analogs": [
{
"pin": "34",
"name": "sensor"
}
]
},
"depends_on": [],
"model": "esp32",
"name": "board",
"type": "board"
}
Edit and fill in the attributes as applicable. Click Save config.
The following attributes are available for esp32
boards:
Name | Type | Inclusion | Description |
---|---|---|---|
pins | object | Required | The pin number of any GPIO pins you wish to use as input/output with the GPIOPin API. |
analogs | object | Optional | Attributes of any pins that can be used as analog-to-digital converter (ADC) inputs. See configuration info. |
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-robot-template.git
You will be prompted to paste your robot’s JSON configuration into the terminal. To obtain this:
- Navigate to your new robot’s page on the Viam app.
- Click on the Setup tab.
Keep your
Mode
andArchitecture
selections at default. - Click the Copy viam-server config button on the right side of the Setup tab. The micro-RDK needs this JSON file, which contains your robot part secret key and cloud app address, to connect to the Viam app.
- Paste the
viam-server
config into your terminal when prompted.
Caution
Do not share your location secret, part secret, or robot address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your robot, or to the computer running your robot.
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 robot’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!