Table of Contents

• Table of Contents
• Micro-RDK (RDK for Microcontroller)
  • Contact
  • (In)stability Notice
  • Getting Started
    • Installing ESP-IDF
    • Installing the Rust ESP Toolchain
    • Installing cargo generate
    • Updating cargo espflash
    • (Optional) Installing QEMU for esp32
      • MacOS
      • Linux
  • Your first esp32 robot
    • Create a new robot
    • Generate a new micro-rdk project
    • Upload!!!
  • Next Steps
    • Configure the esp32 as a remote
    • Modifying generated template
      • Exposing other gpio pins
      • Adding a new analog reader
    • Troubleshooting
  • Building for QEMU
  • License

Micro-RDK (RDK for Microcontroller)

Viam provides an open source robot architecture that provides robotics functionality via simple APIs.

The Micro-RDK is a lightweight version of Viam's RDK. Its goal is to be run on resource-limited embedded systems. The only microcontroller currently supported is the ESP32.

Website: viam.com

Documentation: docs.viam.com

Cloud App: app.viam.com

Contact

• Community Slack: join
• Support: https://support.viam.com

(In)stability Notice

Warning This is an alpha release of the Viam Micro-RDK. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.

Getting Started

Installing ESP-IDF

ESP-IDF is the development framework for Espressif SoCs supported on Windows, Linux and macOS. To properly support cameras we use our own fork on the ESP-IDF. Start by following these instructions up to step 2.

mkdir -p ~/esp
cd ~/esp
git clone https://github.com/npmenard/esp-idf
cd esp-idf
git checkout v4.4.1
git submodule update --init --recursive

You will then need to install the tools for ESP-IDF:

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

Finally to activate ESP-IDF use . $HOME/esp/esp-idf/export.sh. Note that you shouldn't add this to your .bashrc or .zshrc to avoid conflicts with other toolchains.

Installing the Rust ESP Toolchain

To install the rust toolchain run:

curl -LO https://github.com/esp-rs/rust-build/releases/download/v1.64.0.0/install-rust-toolchain.sh
chmod a+x install-rust-toolchain.sh
./install-rust-toolchain.sh

The script will give you two variables to add to your .zshrc or .bashrc. You may do so, but this may cause conflicts with other toolchains. The installer will also produce a file called export-esp.sh which you may retain under a name and location of your choice, and then source when needed:

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

Installing cargo generate

cargo install cargo-generate

Updating cargo espflash

The default version of espflash has a bug therefore we need to update it to a beta version.

cargo install [email protected]

(Optional) Installing QEMU for esp32

Espressif maintains a pretty good QEMU emulator supporting the ESP32, we recommend using it during development. See here for more information.

MacOS

git clone https://github.com/espressif/qemu
cd qemu
./configure --target-list=xtensa-softmmu \
    --enable-gcrypt \
    --enable-debug --enable-sanitizers \
    --disable-strip --disable-user \
    --disable-capstone --disable-vnc \
    --disable-sdl --disable-gtk --extra-cflags="-I/opt/homebrew/Cellar/libgcrypt/1.10.1/include -I/opt/homebrew//include/"
cd build && ninja

Linux

First, make sure you have the libgcrypt library and headers installed. On Ubuntu or Debian, this is:

sudo apt-get install libgcrypt20 libgcrypt20-dev

Then, install QEMU itself:

git clone https://github.com/espressif/qemu
cd qemu
./configure --target-list=xtensa-softmmu     --enable-gcrypt \
    --enable-debug --enable-sanitizers  --disable-strip --disable-user \
    --disable-capstone --disable-vnc --disable-sdl --disable-gtk
cd build && ninja

Add export QEMU_ESP32_XTENSA=<path-to-clone-qemu>/build/ to your .zshrc or .bashrc

Your first esp32 robot

Congratulation for making it this far, just a few more steps and you will be running your first esp32 robot!

Create a new robot

You will want to navigate to app.viam.com and create a new robot with an empty config in your favorite location. The Mode and Architecture selections can be ignored and left at the default. You may also skip any setup steps about downloading, installing, or starting viam-server, since it is not used on the ESP32 board.

Generate a new micro-rdk project

Using a template we are going to create a new micro-rdk project that can be uploaded to an esp32. You will be asked several questions needed to setup Wifi among other things. At one point you will be asked to input a viam robot configuration. Use the Copy viam-server config button on the Setup tab for your new robot to obtain the correct value.

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

If you like, you can initialize a new revision control repository in the newly created directory to track any changes you need to make to the generated project. All of the generated files should be safe to commit with the exception of viam.json, since it contains a secret key.

Upload!!!

Modify src/main.rs to you liking and run :

make upload

While running make upload you may be presented with an interactive menu of different serial port options to use to connect to the board. Once you have identified the correct choice for your environment, you may bypass the menu by providing the correct port as an argument to future invocations of make upload:

make ESPFLASH_FLASH_ARGS="-p /dev/cu.usbserial-130" upload

If successful, make upload will retain a serial connection to the board until Ctrl-C is pressed, so 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.

If everything went well the esp32 connected will be programmed and you will be able to see your robot live on app.viam.com.

NOTE: If you encounter a crash due to stack overflow, you may need to increase the stack available to the main task. Edit the generated sdkconfig.defaults file as follows and re-flash the board:

diff --git a/sdkconfig.defaults b/sdkconfig.defaults
index f75b465..2b0ba9c 100644
--- a/sdkconfig.defaults
+++ b/sdkconfig.defaults
@@ -1,5 +1,5 @@
 # Rust often needs a bit of an extra main task stack size compared to C (the default is 3K)
-CONFIG_ESP_MAIN_TASK_STACK_SIZE=24576
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=32768
 CONFIG_ESP_MAIN_TASK_AFFINITY_CPU1=y
 # Use this to set FreeRTOS kernel tick frequency to 1000 Hz (100 Hz by default).

Next Steps

Configure the esp32 as a remote

In order to control the robot now running on the esp32, you will need another robot to host your application, since the esp32 cannot do so.

• Navigate to app.viam.com, and either create and configure a new robot, or select an existing robot to which you would like to add the esp32-backed robot.
• Add the esp32-backed robot as a "remote" of your new or existing robot:
  • Navigate to the Control tab of the esp32-backed robot and copy its Remote Address.
  • Navigate to the Config tab of the robot from which you want to control the esp32-based robot, select the Remotes tab, and create a new remote.
  • Set the Address field of the new remote to be the Remote Address you copied above.
  • Set TLS for the remote to Enabled.
• Ensure that the controlling robot is live.
• The esp32-backed robot should now be programmatically available in the application controlling the robot to which the esp-backed robot was added as a remote.

Modifying generated template

You can find the declaration of the robot in the generated file src/main.rs, in this example we expose one gpio pin (pin 18) and one analog reader attached to gpio pin 34.

Exposing other gpio pins

Once you selected an appropriate gpio pin (according to the pinout diagram you can add to the collection of exposed pins. For example, if you want to expose gpio pin 21 simply change the line :

let pins = vec![PinDriver::output(periph.pins.gpio18.downgrade_output())?];

to

let pins = vec![PinDriver::output(periph.pins.gpio18.downgrade_output())?,
    PinDriver::output(periph.pins.gpio21.downgrade_output())?,];

You will now be able to change & read the state of pin 21 from app.viam.com

Adding a new analog reader

Adding a new analog reader requires a couple more steps, first you will want to identify a pin capable of analog reading. In the pinout diagram of the Esp32 the pins are labeled like this ADCn_y where n is the adc number (1 or 2, noting that 2 cannot be used with WiFi enabled) and y is the channel number. Once you identify an appropriate pin follow these steps to add it, for example we want to add gpio pin 35 which is labeled ADC1_7 in the pinout diagram

• Create a new ADC channel

let my_analog_channel = adc_chan: AdcChannelDriver<_, Atten11dB<adc::ADC1>> =
            AdcChannelDriver::new(periph.pins.gpio35)?;

• Create the actual Analog reader, note here that adc1 is declared above

let my_analog_reader = Esp32AnalogReader::new("A2".to_string(), my_analog_channel, adc1.clone());

• Finally add it the the collection of analog readers

let analog_readers = vec![
            Rc::new(RefCell::new(analog1)),
            Rc::new(RefCell::new(my_analog_reader)),
        ];

Troubleshooting

• If you are unable to connect to the esp32-backed robot as a remote, try adding :4545 to the end of the value set in the remotes Address field above.

Building for QEMU

Navigate to the root of the Micro-RDK repository, once here run . $HOME/esp/esp-idf/export.sh if you haven't done so already. You will need to comment out two lines from the file sdkconfig.defaults:

CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y

You can then run:

make sim-local

Or if you want to connect a debugger:

make debug-local

License

Copyright 2022-2023 Viam Inc.

AGPLv3 - See LICENSE file