Set up an ESP32

Viam maintains a lightweight version of viam-server for microcontrollers.

Supported microcontrollers

ESP32 microcontrollers must have at least 2 cores, 384kB SRAM, 2MB PSRAM and 8MB flash to work with Viam. The following microcontrollers have been tested with Viam:

About ESP32 microcontroller setup

Because microcontrollers do not run operating systems and are instead flashed with firmware, the setup process is different than for regular computers and SBCs.

To use an ESP32 controller with custom hardware, you build a firmware version from the Micro-RDK and modules to support your hardware.

To quickly try out Viam for microcontrollers, you can use the pre-built binary viam-micro-server which supports the following components:

Quickstart with pre-built firmware

Viam provides installers to flash an ESP32 from macOS or Linux running on the x86_64 or ARM64 (AArch64) processor architectures.

To get started quickly with the pre-built viam-micro-server binary, follow these steps:

  1. Create a Viam app account. The Viam app is the online hub for configuring and managing devices as well as viewing data.

  2. Add a new machine using the button in the top right corner of the LOCATIONS tab in the app. A machine represents your device.

  3. From your machine’s page in the Viam app, click View setup instructions and follow the steps for your operating system. The app provides commands to install viam-micro-server and connect it to the cloud with your machine’s unique credentials.

  4. A secure connection is automatically established between your machine and the Viam app. When you update your machine’s configuration, viam-micro-server automatically gets the updates.

    You are ready to configure any of the components listed above on your machine.

Build and flash custom firmware

If you are using your ESP32 with resources that are not supported by the pre-built binary, you can build your own firmware with the Micro-RDK and your choice of modules.

Set up your development environment

The Micro-RDK (from which viam-micro-server is built) is written in Rust. To be able to develop for the Micro-RDK on macOS and Linux systems, you must install the following software on your development machine:

  1. Install dependencies:

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

    If you haven’t already, install Homebrew:

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

    Then, install dependencies:

    brew install cmake dfu-util ninja

  2. If you do not yet have a Rust environment installed, install it with rustup.

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

    Once completed, start a new shell instance, or run . "$HOME/.cargo/env" in the current one.

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

  3. Install espup and ESP development utilities with cargo:

    cargo install cargo-espflash cargo-generate espflash espup ldproxy

  4. Use espup to download and install the ESP Rust toolchain:

    espup install -s -f /dev/null -v 1.85.0
Prior versions of the above `espup` instructions created a file called `export-rs.sh` which needed to be sourced before proceeding. That requirement [no longer applies](https://github.com/esp-rs/esp-idf-hal/issues/319#issuecomment-1785168921) for Micro-RDK development. The above command redirects `espup`'s production of the setup script to `/dev/null` to avoid cluttering the home directory. If you would like to instead retain the setup script, replace `/dev/null` in the above command with the location where you would like the script to be written, or remove the `-f /dev/null` entirely and the file will be written to `$HOME/export-esp.sh` by default.

Build your firmware

Create firmware that integrates an existing module with the Micro-RDK:

  1. Create a new machine and obtain its credentials:

    Navigate to the Viam app and add a new machine. Click on the name of the machine to go to the machine’s page, then select the CONFIGURE tab.

    Then select the part status dropdown to the right of your machine’s name on the top of the page and copy the Machine cloud credentials:

    Restart button on the machine part info dropdown

    The Micro-RDK needs these credentials, which contains your machine part secret key and cloud app address, to connect to the Viam app.

  2. Generate a new project skeleton from this template:

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

    Follow the prompts:

    • Select templates/project when prompted.
    • Give the project a name of your choice.
    • Select esp32 for MCU.
    • If you wish to configure an esp32-camera or a fake camera as a component of your machine, select true for Include camera module?.
    • For Machine cloud credentials, paste in the machine cloud credentials you obtained in step 1.

    Hit Enter to generate the project. The CLI automatically initializes a git repository in the generated directory for version control and in case you want to use cloud build later.

  3. Navigate into the generated project:

    cd <path-to/your-project-directory>

  4. Add any desired modules to the project by including them in the dependencies section of the Cargo.toml for the generated project:

    To use any of the example modules provided by Viam:

    [dependencies]
...
micro-rdk-modular-driver-example = { git = "https://github.com/viamrobotics/micro-rdk.git", rev = "v0.5.0", package = "micro-rdk-modular-driver-example", features = ["esp32"] }

    Be sure to specify the correct Micro-RDK version that matches your development environment in place of v0.5.0.

    During development, you’ll typically use a local path dependency to reference your module directory, for example:

    [dependencies]
my-module = { path = "../my-module" }

    For modules hosted in a Git repository, you can specify the repository URL and optionally a specific commit (rev), branch (branch), or tag (tag), for example:

    [dependencies]
my-module = { git = "https://github.com/username/my-module.git", tag = "v1.0.0" }

  5. Compile the project using one of the following commands, depending on whether you want to use over-the-air (OTA) firmware updates or not:

    make build-esp32-ota

    make build-esp32-bin

    The first build may be fairly time consuming, as ESP-IDF must be cloned and built, and all dependent Rust crates must be fetched and built. Subsequent builds will be faster.

Flash your ESP32

Upload the generated firmware to your ESP32:

  1. Use a data cable to connect your ESP32 board to a USB port on your development machine.

  2. Run the following command to flash the firmware to your ESP32:

    make flash-esp32-bin

    When prompted, select the serial port that your ESP32 is connected to through a data cable.

    If the flash is 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.

  3. Navigate to your new machine’s page on the Viam app. If successful, the status indicator should turn green and show Live.

Configure and test your machine

You can now configure the models you included in your firmware and test them:

  1. Navigate to your machine’s page in the Viam app.

  2. From the CONFIGURE tab, click JSON mode. Micro-RDK components and services must be configured in JSON.

  3. Add your components and services to the machine configuration. If you are using one of the example modules, find configuration details in the example modules README. For example, if you want to use a free heap sensor, your configuration could look like this:

    {
  "components": [
    {
      "name": "my-free-heap-sensor",
      "api": "rdk:component:sensor",
      "model": "free-heap",
      "attributes": {}
    }
  ]
}

  4. Click Builder mode and find the configuration card of the component you want to test.

  5. Click to open the Test section of the card and use the interface to test the component.

Troubleshooting

Error: xtensa-esp32-elf-gcc: error: unrecognized command line option '--target=xtensa-esp32-espidf' when building on macOS

This is caused by an upstream bug. To work around this issue, ensure that CRATE_CC_NO_DEFAULTS=1 is set in the environment when building.

Error: error: externally-managed-environment when building ESP-IDF on macOS

This is encountered when attempting to build ESP-IDF projects while using Python obtained from Homebrew. Homebrew’s Python infrastructure is not intended for end-user consumption but is instead made available to support Homebrew packages which require a python interpreter. The preferred workaround for this issue is to obtain a user-facing python installation not from Homebrew, but there are other, less safe, workarounds. Please see the macOS specific notes in the development technical notes on GitHub for more details.

Error: Failed to open serial port

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.

Error: espflash::timeout

If you get the following error while connecting to your ESP32:

`Error: espflash::timeout

  × Error while connecting to device
  ╰─▶ Timeout while running command

Run the following command, replacing <YOUR_PROJECT_NAME> with the name of your project firmware (for example, esp32-camera):

espflash flash --erase-parts nvs --partition-table partitions.csv  target/xtensa-esp32-espidf/release/<YOUR_PROJECT_NAME> --baud 115200 && sleep 2 && espflash monitor

Try the connection command again. The baud rate on your device may not have been fast enough to connect. If successful, the Viam app will show that your machine part’s status is Live.

You can also try disconnecting and reconnecting the ESP32 to the USB port, then retrying the flash command.

Error: viam.json not found

If you get the error viam.json not found try the following to manually add your machine cloud credentials as a file in your project:

  1. Navigate to your machine’s page on the Viam app and select the CONFIGURE tab.

  2. Select the part status dropdown to the right of your machine’s name on the top of the page:

    Restart button on the machine part info dropdown

  3. Click the copy icon underneath Machine cloud credentials. The Micro-RDK needs this JSON object, which contains your machine part secret key and cloud app address, to connect to the Viam app.

  4. Navigate to the directory of the project you just created.

  5. Create a new viam.json file and paste the machine cloud credentials from the Viam app in.

  6. Save the file.

Error: failed to run custom build command for esp32-explorer (/host)

This may occur for various reasons such as your machine cloud credentials, WiFi SSID, or password not being populated. Check that your machine cloud credentials are provided in your project directory as viam.json and ensure that your WiFi credentials are provided.

Error: invalid value 460800 for --before <BEFORE>

Change "-b" to "-B in the Makefile, as "-B" is the Baudrate config. Run the following commands to flash esp32-server.bin to your ESP32 microcontroller at a high baud rate, wait for 2 seconds, and observe the device’s output:

espflash write-bin 0x0 target/esp32-server.bin -B 460800  && sleep 2 && espflash monitor

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.

Previous

Viam basics

Next

Modules for ESP32