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)
Note
If passing an object of type None
, you do not have to specify None
in the method call.
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)
}
Note
If passing an object of type nil
, you must specify nil
in the method call or the method will fail.
Have questions, or want to meet other people working on robots? Join our Community Discord.
Was this page helpful?
Glad to hear it! If there is anything we could be doing better, please create an issue.
We're sorry about that. If you'd like to talk to us for help, please join the Community Discord. To ensure we know what's wrong with this page, you can also open an issue.