Microcontroller Setup: the Micro-RDK

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:

• Motor
• Encoder
• Base
• GPIO Pin
• Analog Reader

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:

1. Install the required software
2. Set up your development enviroment 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.

• 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

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

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

go install github.com/viamrobotics/canon@latest

brew install viamrobotics/brews/canon

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

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

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

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

cargo install espup

cargo install cargo-espflash v2.0.0-rc.1

cargo install ldproxy

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

. $HOME/esp/export-rs.sh

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

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:

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 and Architecture 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.

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