Using Extra Params with Viam's SDKs

How to utilize and define the extra parameters that many resource API methods offer in the Go and Python SDKs.

Utilize

Use extra parameters to pass information to a resource's driver that is not specified as a parameter in the built-in resource type’s API specification.

To do this, you must code your own modified implementation of the resource type’s API for a model. See Extend Viam with Modular Resources for more information and instructions on modifying API specifications.

An example of how to check the values of keys in an extra parameter of a built-in resource API method, the sensor component’s Readings:

# Readings depends on extra parameters.
@abc.abstractmethod
async def get_readings(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):

    # Define an empty dictionary for readings.
    readings = {}

    # If extra["type"] is temperature or humidity, get the temperature or humidity from helper functions and return these values as the readings the sensor has provided.
    if extra["type"] is "temperature":
        readings["type"] = get_temp()
    elif extra["type"] is "humidity":
        readings["type"] = get_humidity()
    # If the type is not one of these two cases, raise an exception.
    else: 
        raise Exception(f"Invalid sensor reading request: type {type}")

    return readings

// Readings depends on extra parameters.
func (s *mySensor) Readings(ctx context.Context, extra map[string]interface{}) (map[string]interface{}, error) {

    // Define an empty map for readings.
    readings := map[string]interface{}{}

    // If extra["type"] is temperature or humidity, get the temperature or humidity from helper methods and return these values as the readings the sensor has provided.
    if readingType, ok := extra["type"]; ok {
        rType, ok := readingType.(string)
        if !ok {
            return nil, errors.New("invalid sensor reading request")
        }
        switch rType {
        case "temperature":
            readings[rType] = getTemp()
        case "humidity":
            readings[rType] = getHumidity()
        // If the type is not one of these two cases, return an error.
        default:
            return nil, errors.Errorf("Invalid sensor reading request: type %s", rType)
        }
    }

    // Return the readings and `nil`/no error.
    return readings, nil
}

Define

Optional[Dict[str, Any]] indicates you are required to pass in an object of either type Dict[str, Any] or None as a parameter when calling this method.

An object of type Dict[str, Any] is a dictionary with keys of type str and values of any type,

For example:

async def main():
    ... # Connect to the robot.

    # Get your sensor resource from the robot.
    your_sensor = YourSensor.from_robot(robot, "your-sensor")
    
    # Define a dictionary containing extra information.
    your_info = {"type": "temperature", "description": "more info", "id": 123}

    # Send this information in an call to the sensor resource's API.
    await your_sensor.get_readings(extra=your_info)

extra (map[string]interface{}) indicates you are required to pass in an object of either type map[string]interface{} or nil as a parameter when calling this method.

An object of type map[string]interface{} is an map with keys of type string and values of any type that you have cast to an interface.

For example:

func main() {
    ... // Connect to the robot

    // Get your sensor resource from the robot.
    yourSensor, err := YourSensor.FromRobot(robot, "your-sensor")

    // Define a map containing extra information.
    your_info := map[string]interface{}{"type": "temperature", "description": "more info", "id": 123}

    // Send this information in an call to the sensor resource's API.
    err := yourSensor.Readings(context.Background(), your_info)
}


Have questions, or want to meet other people working on robots? Join our Community Discord.