Manage Micro-RDK

Micro-RDK CLI

The Viam Micro-RDK installer is a command line tool that you can also use to troubleshoot. It allows you to:

  • View logs locally and debug issues when your device has not connected to the Viam app
  • Change wifi credentials on your microcontroller
  • Overwrite firmware using a serial cable

Download the latest release of the installer for your architecture:

You can also build the micro-rdk-installer CLI from source:

  1. Clone the repository:

    git clone https://github.com/viamrobotics/micro-rdk.git

  2. Change directories into the repository:

    cd micro-rdk/micro-rdk-installer

  3. Build the CLI:

    cargo build

  4. The executable will be at target/debug/micro-rdk-installer.

Usage

The following commands are available:

CommandDescription
write-flashFlash a pre-compiled binary (viam-micro-server) directly to an ESP32 connected to your computer with a data cable.
write-credentialsWrite Wi-Fi and machine credentials to the NVS storage partition of an ESP32 running viam-micro-server.
create-nvs-partitionGenerate a binary of a complete NVS data partition that contains Wi-Fi and security credentials for a machine.
monitorMonitor an ESP32 currently connected to your computer with a data cable.
helpPrint this list of commands or the help for a specific command.

Command options

OptionDescription
-h, --helpPrint help for a specific command

Command examples

The following command examples use the micro-rdk-installer-macos executable. Change the executable to the appropriate one for your architecture.

# Flash a pre-compiled binary to an ESP32 using app config credentials downloaded from the Viam app setup tab
./micro-rdk-installer-macos write-flash --app-config=~/Downloads/my-microcontroller-main.json

# Monitor an ESP32 currently connected to your computer with a data cable
./micro-rdk-installer-macos monitor

# Get help for a specific command
./micro-rdk-installer-macos create-nvs-partition --help

Over-the-air updates

Over-the-air updates are available for `viam-server` and the Micro-RDK. For information about `viam-server` see [Deploy software packages to machines](/manage/software/deploy-software/). The following information covers the Micro-RDK.

To remotely update the firmware on your microcontroller without a physical connection to the device, add the OTA (over-the-air) service to your microcontroller’s configuration in the Viam app. Use JSON mode to add the service as in the template below, then configure the URL from which to fetch new firmware, and the version name.

The firmware hosting endpoint must use HTTP/2.

{
  "services": [
    {
      "name": "OTA",
      "api": "rdk:service:generic",
      "model": "rdk:builtin:ota_service",
      "attributes": {
        "url": "<URL where firmware is stored in cloud storage>",
        "version": "<version name>"
      }
    }
  ]
}

{
  "services": [
    {
      "name": "OTA",
      "api": "rdk:service:generic",
      "model": "rdk:builtin:ota_service",
      "attributes": {
        "url": "https://storage.googleapis.com/jordanna/micro-rdk-server-esp32-ota.bin",
        "version": "myVersion1"
      }
    }
  ]
}

Your device checks for configuration updates periodically. If the device receives a configuration with the OTA service and a modified version field in it, the device downloads the new firmware to an inactive partition and restarts. When the device boots it loads the new firmware.