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 currently supports only the following resources:

Click on each supported resource to see supported models, API methods, and configuration info.

See GitHub for code examples and more information on 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. The following ESP32 microcontrollers are supported:

Your microcontroller should have the following resources available to work with the micro-RDK:

  • 2 Cores + 384kB SRAM + 4MB Flash

Install the micro-RDK

The micro-RDK installer is a CLI that allows you to flash a build of micro-RDK, along with your machine’s credentials and your wifi information, directly to your ESP32.

With this installation, you can use your ESP32 with all supported resource APIs, but you cannot write your own code directly interacting with the chip. If you want to program the chip directly, follow the setup instructions in the Micro-RDK Development Setup instead.

Flash your ESP32 with the micro-RDK installer

Navigate to the Viam app and add a new machine in your desired location.

  1. Click on the name of the machine to go to its page.

  2. Click on the Setup tab.

  3. Select your computer’s architecture as Architecture and select Micro-RDK as RDK type.

  4. Follow the instructions to flash the micro-RDK directly to an ESP32 connected to your computer through a data cable.

    To see the micro-RDK server logs through the serial connection, add --monitor to the command in step 3. If the program cannot auto-detect the serial port to which your ESP32 is connected, you may be prompted to select the correct one among a list.

Go back to your new machine’s page on the Viam app. If successful, your machine will show that it’s Live.

For more micro-rdk-installer CLI usage options, see GitHub.

Configure your machine

The micro-RDK provides different component models than the fully featured RDK. See Micro-RDK to get a list of supported models and instructions on how to configure them.

Next steps

Recommendations when using an SDK

In some cases your connection to the ESP32 with an SDK can fail, be unstable or be slow. This is usually caused by the SDK background task that monitors the connection to the micro-RDK. We recommend the following changes to the default settings in your SDK code when connecting to an ESP32 if you run into similar issues:

# Replace the connect function found in the code sample tab with the following
async def connect():
    opts = RobotClient.Options(
        # Micro-RDK configures once at boot,
        # so we don't need to check if the components have changed
        refresh_interval=0,
        # Checking the connection can safely be disabled
        check_connection_interval=0,
        # Same for Attempting to reconnect
        attempt_reconnect_interval=0,
        disable_sessions=True,
        # Micro-RDK doesn't support sessions so it is safe to disable them
        dial_options=DialOptions.with_api_key(
            # Replace "<API-KEY-ID>" (including brackets)
            # with your machine's api key id
            api_key_id='<API-KEY-ID>',
            # Replace "<API-KEY>" (including brackets)
            # with your machine's api key
            api_key='<API-KEY>')
    )
    # Replace "<ROBOT-URL>" (including brackets) with your machine's url
    return await RobotClient.at_address('<ROBOT-URL>', opts)
// Replace the call to client.New with the following block
robot, err := client.New(
    context.Background(),
    "<ROBOT-URL>", // Replace "<ROBOT-URL>" (including brackets) with your machine's url
    logger,
    client.WithDisableSessions(), // Micro-RDK doesn't support sessions so it is safe to disable them
    client.WithCheckConnectedEvery(0), // Checking the connection can safely be disabled
    client.WithReconnectEvery(0), // Same for Attempting to reconnect
    client.WithRefreshEvery(0), // Micro-RDK configures once at boot, so we don't need to check if the components have changed
    client.WithDialOptions(rpc.WithEntityCredentials(
        // Replace "<API-KEY-ID>" (including brackets) with your machine's api key id
        "<API-KEY-ID>",
        rpc.Credentials{
            Type: rpc.CredentialsTypeAPIKey,
            // Replace "<API-KEY>" (including brackets) with your machine's api key
            Payload: "<API-KEY>",
        })),
    )
if err != nil {
    logger.Fatal(err)
}

Troubleshooting

Linux port permissions

If a “Permission Denied” or similar port error occurs, first check the connection of the ESP32 to the machine’s USB port. If connected and the error persists, run sudo usermod -a -G dialout $USER to add the current user to the dialout group, restart your terminal, and try again.

MacOS executable permissions

When using a machine running a version of MacOS, the user is blocked from running the executable by default. To fix this, Control+Click the binary in Finder and then, in the following two prompts select Open. Close whatever terminal window this opens to be able to run the installer.

Error: FlashConnect

This may occur because the serial port chosen if/when prompted is incorrect. However, if the correct port has been selected, try the following:

  1. Run the installer as explained above.
  2. When prompted to select a serial port:
    1. Hold down the “EN” or enable button on your ESP32.
    2. With the above button held down, select the correct serial port.
    3. Press and hold down the “EN” and “Boot” buttons at the same time. Then release both.

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.