# Upkie locomotion
[](https://github.com/tasts-robots/upkie_locomotion/actions/workflows/bazel.yml)
[](https://tasts-robots.org/doc/upkie_locomotion/)
[](https://coveralls.io/github/tasts-robots/upkie_locomotion?branch=main)
[](https://pypi.org/project/upkie_locomotion/)
[](https://github.com/tasts-robots/vulp)
Locomotion code for the [Upkie](https://hackaday.io/project/185729-upkie-wheeled-biped-robot) wheeled biped.
Test it straight from the command line on Linux, no installation required:
<img src="https://user-images.githubusercontent.com/1189580/170496331-e1293dd3-b50c-40ee-9c2e-f75f3096ebd8.png" height="100" align="right" />
```console
git clone https://github.com/tasts-robots/upkie_locomotion.git
cd upkie_locomotion
./tools/bazelisk run -c opt //agents/blue_balancer:bullet
```
Connect a USB controller to move the robot around. 🎮
## Getting started
There is no dependency to install thanks to [Bazel](https://bazel.build/), which builds everything locally. (Compilation will only take a while the first time.) The syntax is the same to deploy to the Raspberry Pi on Upkie with [`raspunzel`](https://github.com/tasts-robots/raspunzel).
The code is organized into *spines*, which communicate with the simulator or actuators using the [Vulp](https://github.com/tasts-robots/vulp) C++ library, and *agents*, the main programs that implement behaviors in Python. In the example above we ran the blue agent. We could also run the Bullet spine independently:
```console
bazel run -c opt //spines:bullet -- --show
```
The ``-c opt`` argument to Bazel makes sure we compile optimized code, while the ``--show`` argument to the spine displays the Bullet visualization.
## Agents
<dl>
<dt>Blue balancer</dt>
<dd>A baseline agent designed to check out Upkie's physical capabilities. It balances the robot using PD feedback from the head's pitch and wheel odometry to wheel velocities, plus a feedforward <a href="https://github.com/tasts-robots/upkie_locomotion/blob/55a331c6a6a165761a85087b7bea35d1403a6cf9/agents/blue_balancer/wheel_balancer.py#L368">non-minimum phase trick</a> for smoother transitions from standing to rolling. An analytical inverse kinematics is plugged in for crouching and standing up (crouching is controlled from D-pad of the USB controller, if one is found).</dd>
<dt>Pink balancer</dt>
<dd>Same as the Blue balancer, but inverse kinematics is computed by <a href="https://github.com/tasts-robots/pink">Pink</a> rather than with a model-specific analytical solution. This is the controller that runs in the <a href="https://www.youtube.com/shorts/8b36XcCgh7s">first</a> <a href="https://www.youtube.com/watch?v=NO_TkHGS0wQ">two</a> videos of Upkie.</dd>
<dt>PPO balancer</dt>
<dd>An agent trained by reinforcement learning to balance with straight legs. Training uses the <code><a href="https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__wheels__env_1_1UpkieWheelsEnv.html#details">UpkieWheelsEnv</a></code> gym environment and the PPO implementation from <a href="https://github.com/DLR-RM/stable-baselines3/">Stable Baselines3</a>.</dd>
</dl>
## Environments
<dl>
<dt><code><a href="https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__servos__env_1_1UpkieServosEnv.html#details">UpkieServosEnv</a></code></dt>
<dd>Upkie with full observation and joint position-velocity-torque actions.</dd>
<dt><code><a href="https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__wheels__env_1_1UpkieWheelsEnv.html#details">UpkieWheelsEnv</a></code></dt>
<dd>Upkie with full observation but only wheel velocity actions.</dd>
</dl>
Environments are single-threaded rather than vectorized. In return, they run as-is on the real robot.
## Observers
<img src="https://tasts-robots.org/doc/upkie_locomotion/observers.png" align="right">
<dl>
<dt><a href="https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1FloorContact.html#details">Floor contact</a></dt>
<dd>Detect contact between the wheels and the floor. Both Blue and Pink agents use contact as a reset flag for their integrators, to avoid over-spinning the wheels while the robot is in the air.</dd>
<dt><a href="https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1WheelContact.html#details">Wheel contact</a></dt>
<dd>Detect contact between a given wheel and the floor.</dd>
<dt><a href="https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1WheelOdometry.html#details">Wheel odometry</a></dt>
<dd>Measure the relative motion of the floating base with respect to the floor. Wheel odometry is part of their secondary task (after keeping the head straight), which is to stay around the same spot on the floor.</dd>
</dl>
## Spines
<dl>
<dt>Bullet</dt>
<dd>Spawn Upkie in a <a href="http://bulletphysics.org/">Bullet</a> simulation. Resetting this spine moves the robot back to its initial configuration in this world.</dd>
<dt>pi3hat</dt>
<dd>Spine is made to be called from a Raspberry Pi with an onboard mjbots <a href="https://mjbots.com/products/mjbots-pi3hat-r4-4b">pi3hat</a>. Servos are stopped when the spine is stopped, and switch to <a href="https://github.com/mjbots/moteus/blob/main/docs/reference.md#theory-of-operation">position mode</a> (which is a position-velocity-torque controller) when the spine idles. Check out the <a href="https://tasts-robots.org/doc/vulp/classvulp_1_1spine_1_1StateMachine.html#details">spine state machine</a> for details.</dd>
</dl>
Raw data
{
"_id": null,
"home_page": null,
"name": "upkie_locomotion",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "St\u00e9phane Caron <stephane.caron@normalesup.org>",
"keywords": "motion control,real time,robotics",
"author": null,
"author_email": "St\u00e9phane Caron <stephane.caron@normalesup.org>",
"download_url": "https://files.pythonhosted.org/packages/8c/00/87bf9d2833ee36d58dbcdfe1180757a4e0f7dba26fb799d17151c74ec965/upkie_locomotion-0.4.0.tar.gz",
"platform": null,
"description": "# Upkie locomotion\n\n[](https://github.com/tasts-robots/upkie_locomotion/actions/workflows/bazel.yml)\n[](https://tasts-robots.org/doc/upkie_locomotion/)\n[](https://coveralls.io/github/tasts-robots/upkie_locomotion?branch=main)\n[](https://pypi.org/project/upkie_locomotion/)\n[](https://github.com/tasts-robots/vulp)\n\nLocomotion code for the [Upkie](https://hackaday.io/project/185729-upkie-wheeled-biped-robot) wheeled biped.\n\nTest it straight from the command line on Linux, no installation required:\n\n<img src=\"https://user-images.githubusercontent.com/1189580/170496331-e1293dd3-b50c-40ee-9c2e-f75f3096ebd8.png\" height=\"100\" align=\"right\" />\n\n```console\ngit clone https://github.com/tasts-robots/upkie_locomotion.git\ncd upkie_locomotion\n./tools/bazelisk run -c opt //agents/blue_balancer:bullet\n```\n\nConnect a USB controller to move the robot around. \ud83c\udfae\n\n## Getting started\n\nThere is no dependency to install thanks to [Bazel](https://bazel.build/), which builds everything locally. (Compilation will only take a while the first time.) The syntax is the same to deploy to the Raspberry Pi on Upkie with [`raspunzel`](https://github.com/tasts-robots/raspunzel).\n\nThe code is organized into *spines*, which communicate with the simulator or actuators using the [Vulp](https://github.com/tasts-robots/vulp) C++ library, and *agents*, the main programs that implement behaviors in Python. In the example above we ran the blue agent. We could also run the Bullet spine independently:\n\n```console\nbazel run -c opt //spines:bullet -- --show\n```\n\nThe ``-c opt`` argument to Bazel makes sure we compile optimized code, while the ``--show`` argument to the spine displays the Bullet visualization.\n\n## Agents\n\n<dl>\n <dt>Blue balancer</dt>\n <dd>A baseline agent designed to check out Upkie's physical capabilities. It balances the robot using PD feedback from the head's pitch and wheel odometry to wheel velocities, plus a feedforward <a href=\"https://github.com/tasts-robots/upkie_locomotion/blob/55a331c6a6a165761a85087b7bea35d1403a6cf9/agents/blue_balancer/wheel_balancer.py#L368\">non-minimum phase trick</a> for smoother transitions from standing to rolling. An analytical inverse kinematics is plugged in for crouching and standing up (crouching is controlled from D-pad of the USB controller, if one is found).</dd>\n\n <dt>Pink balancer</dt>\n <dd>Same as the Blue balancer, but inverse kinematics is computed by <a href=\"https://github.com/tasts-robots/pink\">Pink</a> rather than with a model-specific analytical solution. This is the controller that runs in the <a href=\"https://www.youtube.com/shorts/8b36XcCgh7s\">first</a> <a href=\"https://www.youtube.com/watch?v=NO_TkHGS0wQ\">two</a> videos of Upkie.</dd>\n\n <dt>PPO balancer</dt>\n <dd>An agent trained by reinforcement learning to balance with straight legs. Training uses the <code><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__wheels__env_1_1UpkieWheelsEnv.html#details\">UpkieWheelsEnv</a></code> gym environment and the PPO implementation from <a href=\"https://github.com/DLR-RM/stable-baselines3/\">Stable Baselines3</a>.</dd>\n</dl>\n\n## Environments\n\n<dl>\n <dt><code><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__servos__env_1_1UpkieServosEnv.html#details\">UpkieServosEnv</a></code></dt>\n <dd>Upkie with full observation and joint position-velocity-torque actions.</dd>\n <dt><code><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classenvs_1_1upkie__wheels__env_1_1UpkieWheelsEnv.html#details\">UpkieWheelsEnv</a></code></dt>\n <dd>Upkie with full observation but only wheel velocity actions.</dd>\n</dl>\n\nEnvironments are single-threaded rather than vectorized. In return, they run as-is on the real robot.\n\n## Observers\n\n<img src=\"https://tasts-robots.org/doc/upkie_locomotion/observers.png\" align=\"right\">\n\n<dl>\n <dt><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1FloorContact.html#details\">Floor contact</a></dt>\n <dd>Detect contact between the wheels and the floor. Both Blue and Pink agents use contact as a reset flag for their integrators, to avoid over-spinning the wheels while the robot is in the air.</dd>\n\n <dt><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1WheelContact.html#details\">Wheel contact</a></dt>\n <dd>Detect contact between a given wheel and the floor.</dd>\n\n <dt><a href=\"https://tasts-robots.org/doc/upkie_locomotion/classupkie__locomotion_1_1observers_1_1WheelOdometry.html#details\">Wheel odometry</a></dt>\n <dd>Measure the relative motion of the floating base with respect to the floor. Wheel odometry is part of their secondary task (after keeping the head straight), which is to stay around the same spot on the floor.</dd>\n</dl>\n\n## Spines\n\n<dl>\n <dt>Bullet</dt>\n <dd>Spawn Upkie in a <a href=\"http://bulletphysics.org/\">Bullet</a> simulation. Resetting this spine moves the robot back to its initial configuration in this world.</dd>\n <dt>pi3hat</dt>\n <dd>Spine is made to be called from a Raspberry Pi with an onboard mjbots <a href=\"https://mjbots.com/products/mjbots-pi3hat-r4-4b\">pi3hat</a>. Servos are stopped when the spine is stopped, and switch to <a href=\"https://github.com/mjbots/moteus/blob/main/docs/reference.md#theory-of-operation\">position mode</a> (which is a position-velocity-torque controller) when the spine idles. Check out the <a href=\"https://tasts-robots.org/doc/vulp/classvulp_1_1spine_1_1StateMachine.html#details\">spine state machine</a> for details.</dd>\n</dl>\n",
"bugtrack_url": null,
"license": null,
"summary": "Real-time motion control for Python.",
"version": "0.4.0",
"split_keywords": [
"motion control",
"real time",
"robotics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5c04039a79fb0f0ebf6615b513ed8a01aba3a58957f1ef4928f42d80d04efca0",
"md5": "ad4ee1f75fa83a0e2cf721e899190fca",
"sha256": "ee2727d4a39468db118983a6c91b204e17a46e497b3396c80c2cace80cd0ee36"
},
"downloads": -1,
"filename": "upkie_locomotion-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad4ee1f75fa83a0e2cf721e899190fca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 30057,
"upload_time": "2023-04-06T12:07:11",
"upload_time_iso_8601": "2023-04-06T12:07:11.818426Z",
"url": "https://files.pythonhosted.org/packages/5c/04/039a79fb0f0ebf6615b513ed8a01aba3a58957f1ef4928f42d80d04efca0/upkie_locomotion-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8c0087bf9d2833ee36d58dbcdfe1180757a4e0f7dba26fb799d17151c74ec965",
"md5": "17c442c1ad71c735855b4e9f53ffb590",
"sha256": "18bb4e0e07102ae8296abbe66912a3aaaf49b4220feccdf9043d63bfa2330cea"
},
"downloads": -1,
"filename": "upkie_locomotion-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "17c442c1ad71c735855b4e9f53ffb590",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17426,
"upload_time": "2023-04-06T12:07:14",
"upload_time_iso_8601": "2023-04-06T12:07:14.965001Z",
"url": "https://files.pythonhosted.org/packages/8c/00/87bf9d2833ee36d58dbcdfe1180757a4e0f7dba26fb799d17151c74ec965/upkie_locomotion-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-06 12:07:14",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "upkie_locomotion"
}
JSON