upkie.envs.upkie_ground_velocity.UpkieGroundVelocity Class Reference

Environment where Upkie is used as a wheeled inverted pendulum. 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 left_wheeled=True, float max_ground_velocity=1.0, bool regulate_frequency=True, str shm_name="/upkie", Optional[dict] spine_config=None, float wheel_radius=0.06)
	Initialize environment. More...
Tuple[np.ndarray, Dict]	reset (self, *Optional[int] seed=None, Optional[dict] options=None)
	Resets the environment and get an initial observation. More...
np.ndarray	get_env_observation (self, dict spine_observation)
	Extract environment observation from spine observation dictionary. More...
Dict[str, Dict[str, float]]	get_upper_leg_servo_action (self)
	Get servo actions for both hip and knee joints. More...
Dict[str, Dict[str, float]]	get_wheel_servo_action (self, float left_wheel_velocity)
	Get servo actions for wheel joints. More...
dict	get_spine_action (self, np.ndarray 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
	observation_space
	Observation space.
	action_space
	Action space.
	left_wheeled
	Set to True (default) if the robot is left wheeled, that is, a positive turn of the left wheel results in forward motion. More...
	wheel_radius
	Wheel radius in [m].
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 = 3
	Environment version number.

Detailed Description

Environment where Upkie is used as a wheeled inverted pendulum.

With this environment, Upkie keeps its legs straight and actions only affect wheel velocities. This way, it behaves like a wheeled inverted pendulum. This ground-velocity environment is used for instance by the MPC balancer and PPO balancer agents.

Note

For reinforcement learning with neural-network policies: the observation space and action space are not normalized.

Action space

The action corresponds to the ground velocity resulting from wheel velocities. The action vector is simply:

\[ a =\begin{bmatrix} \dot{p}^* \end{bmatrix} \]

where we denote by \(\dot{p}^*\) the commanded ground velocity in [m] / [s], which is internally converted into wheel velocity commands. Note that, while this action is not normalized, [-1, 1] m/s is a reasonable range for ground velocities.

Observation space

Vectorized observations have the following structure:

\[ \begin{align*} o &= \begin{bmatrix} \theta \\ p \\ \dot{\theta} \\ \dot{p} \end{bmatrix} \end{align*} \]

where we denote by:

• \(\theta\) the pitch angle of the base with respect to the world vertical, in radians. This angle is positive when the robot leans forward.
• \(p\) the position of the average wheel contact point, in meters.
• \(\dot{\theta}\) the body angular velocity of the base frame along its lateral axis, in radians per seconds.
• \(\dot{p}\) the velocity of the average wheel contact point, in meters per seconds.

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_ground_velocity.UpkieGroundVelocity.__init__	(		self,
		float	fall_pitch = 1.0,
		float	frequency = 200.0,
		bool	frequency_checks = True,
		Optional[RobotState]	init_state = None,
		bool	left_wheeled = True,
		float	max_ground_velocity = 1.0,
		bool	regulate_frequency = True,
		str	shm_name = "/upkie",
		Optional[dict]	spine_config = None,
		float	wheel_radius = 0.06
	)

Initialize environment.

Parameters

fall_pitch	Fall detection 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.
left_wheeled	Set to True (default) if the robot is left wheeled, that is, a positive turn of the left wheel results in forward motion. Set to False for a right-wheeled variant.
max_ground_velocity	Maximum commanded ground velocity in m/s. The default value of 1 m/s is conservative, don't hesitate to increase it once you feel confident in your agent.
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.
wheel_radius	Wheel radius in [m].

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

Member Function Documentation

get_env_observation()

np.ndarray upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.get_env_observation	(		self,
		dict	spine_observation
	)

Extract environment observation from spine observation dictionary.

Parameters

spine_observation

Spine observation dictionary.

Returns

Environment observation vector.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

get_spine_action()

dict upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.get_spine_action	(		self,
		np.ndarray	action
	)

Convert environment action to a spine action dictionary.

Parameters

action

Environment action.

Returns

Spine action dictionary.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

get_upper_leg_servo_action()

Dict[str, Dict[str, float]] upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.get_upper_leg_servo_action

(

self

)

Get servo actions for both hip and knee joints.

Returns

Servo action dictionary.

get_wheel_servo_action()

Dict[str, Dict[str, float]] upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.get_wheel_servo_action	(		self,
		float	left_wheel_velocity
	)

Get servo actions for wheel joints.

Parameters

[in]

left_wheel_velocity

Left-wheel velocity, in [rad] / [s].

Returns

Servo action dictionary.

reset()

Tuple[np.ndarray, Dict] upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.reset	(		self,
		*Optional[int]	seed = None,
		Optional[dict]	options = None
	)

Resets the environment and get an initial observation.

Parameters

seed	Number used to initialize the environment’s internal random number generator.
options	Currently unused.

Returns

• observation: Initial vectorized observation, i.e. an element of the environment's observation_space.
• info: Dictionary with auxiliary diagnostic information. For Upkie this is the full observation dictionary sent by the spine.

Reimplemented from upkie.envs.upkie_base_env.UpkieBaseEnv.

Member Data Documentation

left_wheeled

upkie.envs.upkie_ground_velocity.UpkieGroundVelocity.left_wheeled

Set to True (default) if the robot is left wheeled, that is, a positive turn of the left wheel results in forward motion.

Set to False for a right-wheeled variant.

---

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

• upkie/envs/upkie_ground_velocity.py