viam-micro-server Development Setup

viam-micro-server is the lightweight version of viam-server which can run on resource-limited embedded systems (ESP32) that cannot run the fully-featured viam-server.

This page provides instructions for you to customize viam-micro-server and create modules.

Follow these steps to install and build viam-micro-server on your ESP32 for development:

1. Install the required software
2. Set up your development environment with Viam’s Canon CLI utility (recommended) or manually
3. Install viam-micro-server

Software requirements

viam-micro-server is written in Rust. To be able to develop viam-micro-server on macOS and Linux systems, you must install the following software on your development machine:

1. Install dependencies:

   • Linux
   • macOS

   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
   

2. Install Rust and cargo

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

   Once completed open a new tab on your terminal or run . "$HOME/.cargo/env".

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

3. Install cargo-generate with cargo

   Run the following command to install cargo-generate:

   cargo install cargo-generate
   

4. Install espflash

   Run the following command to install espflash:

   cargo install espflash
   

Set up your development environment

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 viam-micro-server

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

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

3. Generate a new project from this template to create a new viam-micro-server project to upload to your ESP32 by running:

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

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

   You will be prompted to paste your machine’s viam-server robot JSON configuration into the terminal, which is the same thing as its machine cloud credentials.

   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 Machine cloud credentials. viam-micro-server needs this JSON, which contains your machine part secret key and cloud app address, to connect to the Viam app.
   • Paste the machine cloud credentials 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.

4. Upload viam-micro-server to your ESP32

   Now, flash the project to your ESP32 and it will connect to the Viam app from which you can then remotely control it:

   • Use Canon
   • Local environment

   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
   

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

   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.

5. Navigate to your new machine’s page on the Viam app. If successful, Live should be displayed underneath Last online.

Troubleshooting

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:

espflash flash --erase-parts nvs --partition-table partitions.csv  target/xtensa-esp32-espidf/release/esp32-camera --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.

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:
3. Click the copy icon underneath Machine cloud credentials. viam-micro-server needs this JSON, 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 viam-server machine cloud credentials 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.