Skip to content

Tutorial: Parameter Management

In this tutorial we will discuss how parameters are managed in Stretch Body and show examples of how to customize your robot by overriding parameters.

Overview

Stretch Body shares a global set of parameters across all of the hardware it manages. All members of the Device class have an instance of RobotParams. This class constructs a dictionary of the device parameters and well as the global parameters for each device. For example from iPython try:

import stretch_body.arm
a=stretch_body.arm.Arm()

a.params
Out[7]: 
{'chain_pitch': 0.0167,
 'chain_sprocket_teeth': 10,
 'gr_spur': 3.875,
 'i_feedforward': 0,
 'calibration_range_bounds': [0.515, 0.525],
 'contact_model': 'effort_pct',
 'contact_model_homing': 'effort_pct',
 'contact_models': {'effort_pct': {'contact_thresh_calibration_margin': 10.0,
   'contact_thresh_max': [-90.0, 90.0],
   'contact_thresh_default': [-45.0, 45.0],
   'contact_thresh_homing': [-45.0, 45.0]}},
 'motion': {'default': {'accel_m': 0.14, 'vel_m': 0.14},
  'fast': {'accel_m': 0.3, 'vel_m': 0.3},
  'max': {'accel_m': 0.4, 'vel_m': 0.4},
  'slow': {'accel_m': 0.05, 'vel_m': 0.05},
  'trajectory_max': {'vel_m': 0.4, 'accel_m': 0.4}},
 'range_m': [0.0, 0.52]}

Or to access another device params:

a.robot_params['lift']

Out[9]: 
{'calibration_range_bounds': [1.094, 1.106],
 'contact_model': 'effort_pct',
 'contact_model_homing': 'effort_pct',
 'contact_models': {'effort_pct': {'contact_thresh_calibration_margin': 10.0,
   'contact_thresh_max': [-100, 100],
   'contact_thresh_default': [-69.0, 69.0],
   'contact_thresh_homing': [-69.0, 69.0]}},
 'belt_pitch_m': 0.005,
 'motion': {'default': {'accel_m': 0.2, 'vel_m': 0.11},
  'fast': {'accel_m': 0.25, 'vel_m': 0.13},
  'max': {'accel_m': 0.3, 'vel_m': 0.15},
  'slow': {'accel_m': 0.05, 'vel_m': 0.05},
  'trajectory_max': {'accel_m': 0.3, 'vel_m': 0.15}},
 'pinion_t': 12,
 'i_feedforward': 1.2,
 'range_m': [0.0, 1.1]}

Parameter Organization

Stretch Body utilizes a prioritized parameter organization such that default settings can be easily overridden

Priority Name Location Description
1 user_params $HELLO_FLEET_PATH/$HELLO_FLEET_ID/ stretch_user_params.yaml Yaml file for users to override default settings and to define custom configurations.
2 configuration_params $HELLO_FLEET_PATH/$HELLO_FLEET_ID/ stretch_configuration_params.yaml Robot specific data (eg, serial numbers and calibrations). Calibration tools may update these.
3 external_params Imported via a list defined as params in stretch_user_params.yaml External Python parameter dictionaries for 3rd party devices and peripherals.
4 nominal_params stretch_body.robot_params_RE2V0.py Generic systems settings (Common across all robots of a given model.
5 nominal_system_params stretch_body.robot_params.py Generic systems settings (Common across all robots models).

This allows the user to override any of the parameters by defining it in their stretch_user_params.yaml. It also allows Hello Robot to periodically update parameters defined in the Python files via Pip upadates.

The tool stretch_params.py will print out all of the robot parameters as well as their origin. For example:

>>$stretch_params.py 
############################################################ Parameters for stretch-re2-2002 
Origin          Parameter                                                              Value                         
--------------------------------------------------------------------------------------------------------------------------------- ...         
stretch_body.robot_params.nominal_params         param.arm.chain_pitch          0.0167                        
stretch_body.robot_params.nominal_params         param.arm.chain_sprocket_teeth         10                                     ...               
stretch_configuration_params.yaml       param.arm.contact_models.effort_pct.contact_thresh_default     [-45.0, 45.0]         

Manually Querying and Modifying Parameters

A quick way to query parameters is with the stretch_params.py tool. For example, to look at parameters relating to the arm motion:

>>$ stretch_params.py | grep arm | grep motion
stretch_body.robot_params.nominal_params    param.arm.motion.default.accel_m    0.14                          
stretch_body.robot_params.nominal_params    param.arm.motion.default.vel_m      0.14                          
stretch_body.robot_params.nominal_params    param.arm.motion.fast.accel_m       0.3                           
stretch_body.robot_params.nominal_params    param.arm.motion.fast.vel_m         0.3                           
stretch_body.robot_params.nominal_params    param.arm.motion.max.accel_m        0.4                           
stretch_body.robot_params.nominal_params    param.arm.motion.max.vel_m          0.4                           
stretch_body.robot_params.nominal_params    param.arm.motion.slow.accel_m       0.05                          
stretch_body.robot_params.nominal_params    param.arm.motion.slow.vel_m         0.05                          
...               

The tool display each parameter's value as well as which parameter file it was loaded from.

Now let's say you want to override the default motion settings for the arm. You could add the following to your stretch_user_params.yaml:

arm:
  motion:
    default:
      vel_m: 0.1
      accel_m: 0.1

Run the tool again and we see:

>>$ stretch_params.py | grep arm | grep motion | grep default
stretch_body.robot_params.nominal_params    param.arm.motion.default.accel_m    0.1                          
stretch_body.robot_params.nominal_params    param.arm.motion.default.vel_m      0.1  

The factory parameter settings should suffice for most use cases.

Programmatically Modifying and Storing Parameters

A user want to compute the value of a parameter programmatically and modify the robot settings accordingly. For example, in the Stretch Factory tool REx_base_calibrate_wheel_seperation.py we see that the parameter wheel_seperation_m is recomputed as the variable d_avg. This new value could be used during the robot execution by simply

robot.base.params['wheel_seperation_m']=d_vag

, or it could be saved as a user override as :

robot.write_user_param_to_YAML('base.wheel_separation_m', d_avg)

This will update the file stretch_user_params.yaml


All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.