Viam Micro-RDK ESP32 Sensor Modules Example

(In)stability Notice

Warning The Viam Micro-RDK is currently in beta.

Overview

This project in this repository was generated from the Micro-RDK Module Template, and demonstrates how to produce modular resources for the Micro-RDK.

Usage

Setup

If you don't yet have a Micro-RDK robot project, please create one by following the Micro-RDK Development Setup instructions.

Installation

To add this module to a robot project, just add this repository to the [dependencies] section of the Cargo.toml file in the robot project:

diff --git a/Cargo.toml b/Cargo.toml
index 79fbc5c..949b5ab 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -32,6 +32,8 @@ async-channel = "1.8.0"
 smol = "1.2"
 futures-lite = "1.12.0"
 micro-rdk = {version = "0.0.3", git = "https://github.com/viamrobotics/micro-rdk.git", features = ["esp32"]}
+micro-rdk-esp32-sensor-examples = { git = "https://github.com/viam-labs/micro-rdk-esp32-sensor-examples" }

Rebuild the project per the above Micro-RDK Development Setup instructions and reflash the board.

Instantiating the Sensors

You can now instantiate the sensors by adding them as new components in your robot configuration on app.viam.com.

To instantiate the Wifi RSSI Sensor, add the following to the components section of your configuration (edit using the Raw JSON mode):

    {
      "name": "my-wifi-sensor",
      "type": "sensor",
      "model": "wifi-rssi",
      "attributes": {},
      "depends_on": []
    }

To instantiate the free heap sensor, add the following:

    {
      "attributes": {},
      "depends_on": [],
      "type": "sensor",
      "model": "free-heap",
      "name": "my-free-heap-sensor"
    }

Reboot the ESP32 board (by, say, pressing the physical "boot" button, or hitting Ctrl-R if the monitor is active) so that it can pull the new configuration from app.viam.com, and these sensors should now be available to query in your language of choice with the Viam SDK (you can find this code on the Code Sample page for your robot):

    # wifi-sensor
    wifi_sensor = Sensor.from_robot(robot, "my-wifi-sensor")
    wifi_sensor_return_value = await wifi_sensor.get_readings()
    print(f"wifi-sensor get_readings return value: {wifi_sensor_return_value}")

    # free-heap-sensor
    free_heap_sensor = Sensor.from_robot(robot, "my-free-heap-sensor")
    free_heap_sensor_return_value = await free_heap_sensor.get_readings()
    print(f"free-heap-sensor get_readings return value: {free_heap_sensor_return_value}")

Implementation Walkthrough

This project was created by using the Micro-RDK Module Template and cargo generate:

$ cargo install cargo-generate
$ cargo generate --git https://github.com/viamrobotics/micro-rdk templates/module

When prompted by the template, the project was named micro-rdk-esp32-sensor-examples and esp32 selected for the target platform. The generated project has the form of a library crate, where src/lib.rs defines an initially empty implementation of the well-known Micro-RDK module entry point register_models:

micro-rdk-esp32-sensor-examples/src/lib.rs

Lines 3 to 5 in 02d7c8e

	pub fn register_models(_registry: &mut ComponentRegistry) -> anyhow::Result<(), RegistryError> {
	Ok(())
	}

The generated project also includes a package.metadata section in its Cargo.toml which identifies the library crate as being a Micro-RDK module:

micro-rdk-esp32-sensor-examples/Cargo.toml

Lines 12 to 13 in 02d7c8e

	[package.metadata.com.viam]
	module = true

A subsequent commit adds definitions of the FreeHeapSensor and WifiRSSISensor

That commit also introduces a crate-local register_model function for each sensor:

• FreeHeapSensor:

  micro-rdk-esp32-sensor-examples/src/free_heap_sensor.rs

  Lines 21 to 25 in 9cc59d5

  	pub fn register_model(registry: &mut ComponentRegistry) -> anyhow::Result<(), RegistryError> {
  	registry.register_sensor("free-heap", &FreeHeapSensor::from_config)?;
  	log::info!("free-heap sensor registration ok");
  	Ok(())
  	}

• WifiRSSISensor:

  micro-rdk-esp32-sensor-examples/src/wifi_rssi_sensor.rs

  Lines 19 to 23 in 9cc59d5

  	pub(crate) fn register_model(registry: &mut ComponentRegistry) -> anyhow::Result<(), RegistryError> {
  	registry.register_sensor("wifi-rssi", &WifiRSSISensor::from_config)?;
  	log::info!("wifi-rssi sensor registration ok");
  	Ok(())
  	}

Finally, the top level register_models entry point is updated to delegate to the register_model function for both sensors:

micro-rdk-esp32-sensor-examples/src/lib.rs

Lines 6 to 10 in 9cc59d5

	pub fn register_models(registry: &mut ComponentRegistry) -> anyhow::Result<(), RegistryError> {
	wifi_rssi_sensor::register_model(registry)?;
	free_heap_sensor::register_model(registry)?;
	Ok(())
	}

The Micro-RDK module is now ready to be used in a Micro-RDK project, just by adding it as an ordinary dependency in the dependencies section of the project's Cargo.toml file, as noted in the Installation section above.

Related Reading

Please see https://github.com/viam-labs/micro-rdk-modular-driver-examples for another example of modular Micro-RDK sensors.