upkie.envs.upkie_servos.UpkieServos Class Reference

Upkie with actions and observations corresponding to the moteus servo API. More...

Public Member Functions
def	__init__ (self, float fall_pitch=1.0, float frequency=200.0, bool frequency_checks=True, Optional[RobotState] init_state=None, bool regulate_frequency=True, str shm_name="/upkie", Optional[dict] spine_config=None)
	Initialize environment. More...
dict	get_neutral_action (self)
	Get the neutral action where servos don't move. More...
def	get_env_observation (self, dict spine_observation)
	Extract environment observation from spine observation dictionary. More...
dict	get_spine_action (self, dict env_action)
	Convert environment action to a spine action dictionary. More...
Public Member Functions inherited from upkie.envs.upkie_base_env.UpkieBaseEnv
None	__init__ (self, float fall_pitch=1.0, Optional[float] frequency=200.0, bool frequency_checks=True, Optional[RobotState] init_state=None, bool regulate_frequency=True, str shm_name="/upkie", Optional[dict] spine_config=None, int spine_retries=10)
	Initialize environment. More...
def	__del__ (self)
	Stop the spine when deleting the environment instance.
None	close (self)
	Stop the spine properly.
Optional[float]	dt (self)
	Regulated period of the control loop in seconds, or None if there is no loop frequency regulation.
Optional[float]	frequency (self)
	Regulated frequency of the control loop in Hz, or None if there is no loop frequency regulation.
None	update_init_rand (self, **kwargs)
	Update initial-state randomization. More...
Tuple[np.ndarray, dict]	reset (self, *Optional[int] seed=None, Optional[dict] options=None)
	Resets the spine and get an initial observation. More...
Tuple[np.ndarray, float, bool, bool, dict]	step (self, np.ndarray action)
	Run one timestep of the environment's dynamics. More...
bool	detect_fall (self, dict spine_observation)
	Detect a fall based on the base-to-world pitch angle. More...
def	get_env_observation (self, dict spine_observation)
	Extract environment observation from spine observation dictionary. More...
dict	get_spine_action (self, action)
	Convert environment action to a spine action dictionary. More...
None	log (self, str name, Any entry)
	Log a new entry to the "log" key of the action dictionary. More...
None	bullet_extra (self, dict bullet_action)
	Prepend for the next step an extra action for the Bullet spine. More...

Public Attributes
	action_space
	Action space.
	observation_space
	Observation space.
Public Attributes inherited from upkie.envs.upkie_base_env.UpkieBaseEnv
	fall_pitch
	Fall detection pitch angle, in radians.
	init_state
	Initial state for the floating base of the robot, which may be randomized upon resets.
	model
	Robot model read from its URDF description.

Static Public Attributes
int	version = 4
	Environment version number.

Detailed Description

Upkie with actions and observations corresponding to the moteus servo API.

Action space

The action space is a dictionary with one key for each servo:

• left_hip: left hip joint (qdd100)
• left_hip: left knee joint (qdd100)
• left_hip: left wheel joint (mj5208)
• right_hip: right hip joint (qdd100)
• right_hip: right knee joint (qdd100)
• right_hip: right wheel joint (mj5208)

The value for each servo dictionary is itself a dictionary with the following keys:

• position: commanded joint angle \(\theta^*\) in [rad] (NaN to disable) (required).
• velocity: commanded joint velocity \(\dot{\theta}^*\) in [rad] / [s] (required).
• feedforward_torque: feedforward joint torque \(\tau_{\mathit{ff}}\) in [N m].
• kp_scale: scaling factor \(k_{p}^{\mathit{scale}}\) applied to the position feedback gain, between zero and one.
• kd_scale: scaling factor \(k_{d}^{\mathit{scale}}\) applied to the velocity feedback gain, between zero and one.
• maximum_torque: maximum joint torque \(\tau_{\mathit{max}}\) (feedforward + feedback) enforced during the whole actuation step, in [N m].

The resulting torque applied by the servo is then:

\[ \begin{align*} \tau & = \underset{ [-\tau_{\mathit{max}}, +\tau_{\mathit{max}}]}{ \mathrm{clamp} } \left( \tau_{\mathit{ff}} + k_{p} k_{p}^{\mathit{scale}} (\theta^* - \theta) + k_{d} k_{d}^{\mathit{scale}} (\dot{\theta}^* - \dot{\theta})) \right) \end{align*} \]

Position and velocity gains \(k_{p}\) and \(k_{d}\) are configured in each moteus controller directly and don't change during execution. We can rather modulate the overall feedback gains via the normalized parameters \(k_{p}^{\mathit{scale}} \in [0, 1]\) and \(k_{d}^{\mathit{scale}} \in [0, 1]\). Note that the servo regulates the torque above at its own frequency, which is higher (typically 40 kHz) than the agent and the spine frequencies. See the moteus reference for more details.

Observation space

The observation space is a dictionary with one key for each servo. The value for each key is a dictionary with keys:

• position: Joint angle in [rad].
• velocity: Joint velocity in [rad] / [s].
• torque: Joint torque in [N m].
• temperature: Servo temperature in degree Celsius.
• voltage: Power bus voltage of the servo, in [V].

As with all Upkie environments, full observations from the spine (detailed in Observations) are also available in the info dictionary returned by the reset and step functions.

Constructor & Destructor Documentation

__init__()

def upkie.envs.upkie_servos.UpkieServos.__init__	(		self,
		float	fall_pitch = 1.0,
		float	frequency = 200.0,
		bool	frequency_checks = True,
		Optional[RobotState]	init_state = None,
		bool	regulate_frequency = True,
		str	shm_name = "/upkie",
		Optional[dict]	spine_config = None
	)

Initialize environment.

Parameters

fall_pitch	Fall pitch angle, in radians.
frequency	Regulated frequency of the control loop, in Hz.
frequency_checks	If regulate_frequency is set and this parameter is true (default), a warning is issued every time the control loop runs slower than the desired frequency. Set this parameter to false to disable these warnings.
init_state	Initial state of the robot, only used in simulation.
regulate_frequency	Enables loop frequency regulation.
shm_name	Name of shared-memory file.
spine_config	Additional spine configuration overriding the default upkie.config.SPINE_CONFIG. The combined configuration dictionary is sent to the spine at every reset.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

Reimplemented in upkie.envs.upkie_servo_positions.UpkieServoPositions, and upkie.envs.upkie_servo_torques.UpkieServoTorques.

Member Function Documentation

get_env_observation()

def upkie.envs.upkie_servos.UpkieServos.get_env_observation	(		self,
		dict	spine_observation
	)

Extract environment observation from spine observation dictionary.

Parameters

spine_observation

Full observation dictionary from the spine.

Returns

Environment observation.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

get_neutral_action()

dict upkie.envs.upkie_servos.UpkieServos.get_neutral_action

(

self

)

Get the neutral action where servos don't move.

Returns

Neutral action where servos don't move.

get_spine_action()

dict upkie.envs.upkie_servos.UpkieServos.get_spine_action	(		self,
		dict	env_action
	)

Convert environment action to a spine action dictionary.

Parameters

env_action

Environment action.

Returns

Spine action dictionary.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

---

The documentation for this class was generated from the following file:

• upkie/envs/upkie_servos.py