From dcdd4c4e72fc4a9e05d53f2a12683daf3ab534ec Mon Sep 17 00:00:00 2001 From: glannuzel Date: Wed, 17 Apr 2024 10:47:59 +0200 Subject: [PATCH] Update SDK --- config/_default/menus/menus.en.toml | 42 ++--- content/advanced/safety/mobile-base.md | 2 +- .../sdk/{development => advanced}/_index.md | 20 +- .../mobile-base.md} | 138 +++++++------- .../mobile-base.md} | 173 ++++++++++-------- content/sdk/getting-started/safety.md | 2 +- content/sdk/mobile-base/getting-started.md | 87 --------- content/sdk/mobile-base/mobile-base-alone.md | 28 --- content/sdk/mobile-base/safety.md | 1 - 9 files changed, 185 insertions(+), 308 deletions(-) rename content/sdk/{development => advanced}/_index.md (54%) rename content/sdk/{mobile-base/drive-control-modes.md => advanced/mobile-base.md} (97%) rename content/sdk/{mobile-base/moving-the-base.md => first-moves/mobile-base.md} (69%) delete mode 100644 content/sdk/mobile-base/getting-started.md delete mode 100644 content/sdk/mobile-base/mobile-base-alone.md diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index 8b181fc0..304ec7ab 100644 --- a/config/_default/menus/menus.en.toml +++ b/config/_default/menus/menus.en.toml @@ -271,44 +271,26 @@ parent = "sdk-first-moves" url = "/sdk/first-moves/record" +[[sdk]] + name = "8. Use the mobile base" + weight = 370 + parent = "sdk-first-moves" + url = "/sdk/first-moves/mobile-base" + ################## -## Mobile base section +## Advanced section ################## [[sdk]] - name = "Mobile base" + name = "Advanced" weight = 40 - identifier = "sdk-mobile-base" + identifier = "sdk-advanced" [[sdk]] - name = "Getting started with the mobile base" + name = "Mobile base modes" weight = 400 - parent = "sdk-mobile-base" - url = "/sdk/mobile-base/getting-started" - -[[sdk]] - name = "Moving the mobile base" - weight = 410 - parent = "sdk-mobile-base" - url = "/sdk/mobile-base/moving-the-base" - -[[sdk]] - name = "Advanced" - weight = 420 - parent = "sdk-mobile-base" - url = "/sdk/mobile-base/drive-control-modes" - -[[sdk]] - name = "Anti-collision safety" - weight = 430 - parent = "sdk-mobile-base" - url = "/sdk/mobile-base/safety" - -[[sdk]] - name = "Using the mobile base without Reachy" - weight = 440 - parent = "sdk-mobile-base" - url = "/sdk/mobile-base/mobile-base-alone" + parent = "sdk-advanced" + url = "/sdk/advanced/mobile-base" ############################################# # Menu main - add parts to main page nav menu here! diff --git a/content/advanced/safety/mobile-base.md b/content/advanced/safety/mobile-base.md index 1cbf5258..431b797f 100644 --- a/content/advanced/safety/mobile-base.md +++ b/content/advanced/safety/mobile-base.md @@ -22,7 +22,7 @@ We recommend that you get a feel for the inertia of the robot by holding on to t Block a wheel with your foot and try to gently tilt the robot. -Then use the controller to move around the robot as explained in [Moving the mobile base]({{< ref "sdk/mobile-base/moving-the-base" >}}) +Then use the controller to move around the robot as explained in [Moving the mobile base]({{< ref "sdk/first-moves/mobile-base" >}}) {{< video "videos/advanced/mobile-base/controller_mouvement.mp4" "100%" >}} diff --git a/content/sdk/development/_index.md b/content/sdk/advanced/_index.md similarity index 54% rename from content/sdk/development/_index.md rename to content/sdk/advanced/_index.md index 5c53d07a..59631e7c 100644 --- a/content/sdk/development/_index.md +++ b/content/sdk/advanced/_index.md @@ -1,10 +1,10 @@ ---- -title : "Developing with Python SDK" -description: "Use Reachy 2 Python SDK." -lead: "" -date: 2023-07-25T17:37:16+02:00 -lastmod: 2023-07-25T17:37:16+02:00 -draft: false -images: [] -type: docs ---- +--- +title : "Advanced Python SDK features" +description: "Use Reachy 2 Python SDK, advanced features." +lead: "" +date: 2023-07-25T17:37:16+02:00 +lastmod: 2023-07-25T17:37:16+02:00 +draft: false +images: [] +type: docs +--- diff --git a/content/sdk/mobile-base/drive-control-modes.md b/content/sdk/advanced/mobile-base.md similarity index 97% rename from content/sdk/mobile-base/drive-control-modes.md rename to content/sdk/advanced/mobile-base.md index 2d19d584..912b896c 100644 --- a/content/sdk/mobile-base/drive-control-modes.md +++ b/content/sdk/advanced/mobile-base.md @@ -1,70 +1,70 @@ ---- -title: "Advanced" -description: "Drive modes and control modes description for the mobile base." -date: 2023-07-26T08:32:17+02:00 -lastmod: 2023-07-26T08:32:17+02:00 -draft: false -images: [] -type: docs -toc: true -weight: "160" ---- -## Drive modes -### Overview -The drive mode impacts the way the mobile base accepts commands. We could say it's the current state of the mobile base. - -In most cases, there is no need to think about these modes or to handle them in your code. Below are the most common use cases. -* If you want to use the set_speed method to spam speed commands (e.g. pilot the robot with a controller), the mode has to be manually changed to 'cmd_vel': - ```python - reachy_mobile.mobile_base.drive_mode = 'cmd_vel' - ``` -* If you want to push the robot easily, this will set the wheels in a compliancy state: - ```python - reachy_mobile.mobile_base.drive_mode = 'free_wheel' - ``` -* On the contrary, if you want the robot to apply a passive resistance to movement, use: - ```python - reachy_mobile.mobile_base.drive_mode = 'brake' - ``` - -You can use this [Jupyter Notebook](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/drive-modes.ipynb) to explore the drive modes with your mobile base. - -### Detailed behaviour -This section is only useful if you intend to interact directly with the Hardware Abstraction Layer (HAL). - -Six drive modes are available for the mobile base: -* **cmd_vel**: in this mode, speed instructions can be spammed to the wheels controllers. This mode is used for the *set_speed* method. -* **brake**: in this mode, the wheels will be stiff. -* **free_wheel**: in this mode, the wheels will be as compliant as possible. -* **emergency_stop**: in this mode, the wheels will stop receiving mobility commands. Switching to this mode will also stop the mobile base hal code. This is a safety mode. -* **speed**: another mode to send speed instructions, but less frequently than with the cmd_vel mode. This mode is actually not used at this level (python SDK level), but is implemented at the ROS level, in case one might need it. -* **goto**: this mode is used for the *goto* method. - -*note: the 'speed' and 'goto' modes can't be changed by hand. The drive mode is handled automagically when requesting a set_speed or a goto.* - -The code for the [HAL can be found here](https://github.com/pollen-robotics/zuuu_hal) - -## Control modes -### Overview -The control mode dictates the low level control strategy used by the mobile bases's HAL. - -Two control modes are possible: -* ***open_loop*** (default mode): in this mode, the wheels are compliant and the control is smoother. - ```python - reachy_mobile.mobile_base.control_mode = 'open_loop' - ``` - -* ***pid***: in this mode, the wheels are stiff and the control is more precise. - ```python - reachy_mobile.mobile_base.control_mode = 'pid' - ``` -:bulb: We recommend that you run the following [Jupyter Notebook](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/control-modes.ipynb) to get a feel of what the control mode does. - -### Detailed behaviour -Regardless of how the mobile base is piloted (goto, set_speed, controller), the HAL always ends up calculating a goal rotational speed for each wheel. -The control mode only changes the used strategy to reach that rotational speed. -* In the open_loop mode, a simple affine model was identified to match a PWM to a goal rotational speed. The VESC controllers then apply the PWM directly to the motors of the wheels, without any other low level control. The measures can be found [here](https://github.com/pollen-robotics/zuuu_hal/tree/main/measures). While the model is simple, it does account for the static friction and the experimental data shows a good fit when the mobile base is on a flat surface. - -{{< img-center "images/sdk/mobile-base/affine_pwm_model.png" 400x "" >}} - +--- +title: "Mobile base drive and control modes" +description: "Drive modes and control modes description for the mobile base." +date: 2023-07-26T08:32:17+02:00 +lastmod: 2023-07-26T08:32:17+02:00 +draft: false +images: [] +type: docs +toc: true +weight: "160" +--- +## Drive modes +### Overview +The drive mode impacts the way the mobile base accepts commands. We could say it's the current state of the mobile base. + +In most cases, there is no need to think about these modes or to handle them in your code. Below are the most common use cases. +* If you want to use the set_speed method to spam speed commands (e.g. pilot the robot with a controller), the mode has to be manually changed to 'cmd_vel': + ```python + reachy_mobile.mobile_base.drive_mode = 'cmd_vel' + ``` +* If you want to push the robot easily, this will set the wheels in a compliancy state: + ```python + reachy_mobile.mobile_base.drive_mode = 'free_wheel' + ``` +* On the contrary, if you want the robot to apply a passive resistance to movement, use: + ```python + reachy_mobile.mobile_base.drive_mode = 'brake' + ``` + +You can use this [Jupyter Notebook](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/drive-modes.ipynb) to explore the drive modes with your mobile base. + +### Detailed behaviour +This section is only useful if you intend to interact directly with the Hardware Abstraction Layer (HAL). + +Six drive modes are available for the mobile base: +* **cmd_vel**: in this mode, speed instructions can be spammed to the wheels controllers. This mode is used for the *set_speed* method. +* **brake**: in this mode, the wheels will be stiff. +* **free_wheel**: in this mode, the wheels will be as compliant as possible. +* **emergency_stop**: in this mode, the wheels will stop receiving mobility commands. Switching to this mode will also stop the mobile base hal code. This is a safety mode. +* **speed**: another mode to send speed instructions, but less frequently than with the cmd_vel mode. This mode is actually not used at this level (python SDK level), but is implemented at the ROS level, in case one might need it. +* **goto**: this mode is used for the *goto* method. + +*note: the 'speed' and 'goto' modes can't be changed by hand. The drive mode is handled automagically when requesting a set_speed or a goto.* + +The code for the [HAL can be found here](https://github.com/pollen-robotics/zuuu_hal) + +## Control modes +### Overview +The control mode dictates the low level control strategy used by the mobile bases's HAL. + +Two control modes are possible: +* ***open_loop*** (default mode): in this mode, the wheels are compliant and the control is smoother. + ```python + reachy_mobile.mobile_base.control_mode = 'open_loop' + ``` + +* ***pid***: in this mode, the wheels are stiff and the control is more precise. + ```python + reachy_mobile.mobile_base.control_mode = 'pid' + ``` +:bulb: We recommend that you run the following [Jupyter Notebook](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/control-modes.ipynb) to get a feel of what the control mode does. + +### Detailed behaviour +Regardless of how the mobile base is piloted (goto, set_speed, controller), the HAL always ends up calculating a goal rotational speed for each wheel. +The control mode only changes the used strategy to reach that rotational speed. +* In the open_loop mode, a simple affine model was identified to match a PWM to a goal rotational speed. The VESC controllers then apply the PWM directly to the motors of the wheels, without any other low level control. The measures can be found [here](https://github.com/pollen-robotics/zuuu_hal/tree/main/measures). While the model is simple, it does account for the static friction and the experimental data shows a good fit when the mobile base is on a flat surface. + +{{< img-center "images/sdk/mobile-base/affine_pwm_model.png" 400x "" >}} + * In the pid mode, the HAL gives the goal rotational speeds directly to the VESC controllers of each wheel. The VESC will use a PID controller to control the speeds. \ No newline at end of file diff --git a/content/sdk/mobile-base/moving-the-base.md b/content/sdk/first-moves/mobile-base.md similarity index 69% rename from content/sdk/mobile-base/moving-the-base.md rename to content/sdk/first-moves/mobile-base.md index ad4022b8..7b600d06 100644 --- a/content/sdk/mobile-base/moving-the-base.md +++ b/content/sdk/first-moves/mobile-base.md @@ -1,81 +1,92 @@ ---- -title: "Moving the mobile base" -description: "Presentation of the different functions available to make the mobile base move" -date: 2023-07-26T08:32:46+02:00 -lastmod: 2023-07-26T08:32:46+02:00 -draft: false -images: [] -type: docs -toc: true -weight: "150" ---- - -## Frame conventions -### REP 105 “Coordinate Frames for Mobile Platforms” -Our design is coherent with ROS' conventions described in [REP 105 “Coordinate Frames for Mobile Platforms”](https://www.ros.org/reps/rep-0105.html) - -### Robot frame -The robot frame or egocentric frame or base_link frame is **rigidly attached to the robot**. Its (0, 0) point is the projection on the floor of the center of the mobile base. -**X in front, Y to the left, Theta positive counterclockwise.** - -{{< img-center "images/sdk/mobile-base/robot_frame.png" 400x "" >}} - -### Odom frame -The odom frame is a **world-fixed frame**. The position (x, y, theta) of the robot in the odom frame is continuously updated by the HAL through odometry calculations. These calculations currently only use the measurements from the wheels to estimate the movement of the robot. While the position of the robot is continuous, **it should never be relied upon for long-term reference as it will always drift.** - -{{< img-center "images/sdk/mobile-base/odom_frame.png" 400x "" >}} - -The initial position of the odom frame matches the position of the robot when the HAL was started. The odom frame can also be reset to the current position of the robot using: - ```python - reachy_mobile.mobile_base.reset_odometry() - ``` - - -## Moving the mobile base -There are two interfaces in the SDK to control the mobile base: spamming speed commands or setting a goal position in the odom frame. -### Using the set_speed method -Since the mobile base is holonomic, the set_speed method expects 3 speed commands expressed in the robot frame: -- x_vel, in m/s. The instantaneous speed positive in front of the robot. -- y_vel, in m/s. The instantaneous speed positive to the left of the robot. -- rot_vel, in deg/s. The instantaneous rotational speed positive counterclockwise. - -See the [joy_controller code](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/scripts/joy_controller.py) for a working example. - -:bulb: As a safety measure, the HAL will stop the wheels if it didn't receive a new goal speed in the last 200ms. - -:bulb: The way this is implemented in the HAL is simply to listen to the /cmd_vel topic, apply some smoothing, perform the kinematic calculations and send the speed commands to the wheels. This makes it very easy to create control interfaces using ROS, see the [keyboard example](https://github.com/pollen-robotics/zuuu_hal/blob/main/examples/zuuu_teleop_keyboard.py) or the [joy controller example](https://github.com/pollen-robotics/zuuu_hal/blob/main/examples/zuuu_teleop_joy.py). - -*Note: the HAL has a drive mode to set speed commands for variable amounts of time. Instead of relying on a topic, it creates a service. The niche usage didn't warrant the added complexity, so the interface with the SDK was not made. But if needed, it exists!* -### Using the goto method -The goto method expects a goal position in the odom frame, composed of 3 elements: x in m, y in m and theta in deg. - -:warning: The most important thing to get used to, is the fact that the odom frame is world-fixed and that the position of the robot is always updated as long as the HAL is running (the HAL is automatically started during the robot boot-up). So by default, **if you ask for a ```goto(0, 0, 0)``` the robot will try to comeback to the position it was at boot-up.** - -To perform a goto relative to the current position of the robot, use the method ```reset_odometry()```. For example, create an instance of reachy with: - -```python -from reachy_sdk import ReachySDK - -reachy_mobile = ReachySDK(host='your-reachy-ip', with_mobile_base=True) -``` - -Reset the odometry frame, and ask the robot to move 50cm in front of it: -```python -reachy_mobile.mobile_base.reset_odometry() -reachy_mobile.mobile_base.goto(x=0.5, y=0.0, theta=0.0) -``` -Now, ask for a goto(0,0,0). The robot should go back to its previous position: -```python -reachy_mobile.mobile_base.goto(x=0.0, y=0.0, theta=0.0) -``` - -**We recommend taking the time to play around with this concept.** You can use [this Jupyer notebook to explore the goto method.](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/goto.ipynb) - -By default, the robot will always try to reach the goal position, meaning that even if the robot did reach its position and you push it, it will try to come back to the the goal position again. - -However, you can define two types of stop conditions through optional parameters (see the above Jupyter notebook for a working example). -- A timeout, expressed in seconds. The robot stops the goto when the elapsed time since the start of the command is superior to the timeout. There is a **default timeout that scales with the distance asked by the goto**. -- A spatial tolerance, expressed with 4 values: delta_x (the error in m along the X axis), delta_y (the error in m along the Y axis), delta_theta (the angle error in deg) and distance (the l2 distance between the current position and the goal position in m). The robot stops the goto when it is close enough to satisfy all 4 conditions simultaneously. -explored in : - -:bulb: *Note: the goto behaviour is implemented in the HAL using 3 independent PIDs, one to reduce delta_x, one for delta_y and one for delta_theta. The PIDs can't be tuned at the SDK level, but they can at the HAL level.* \ No newline at end of file +--- +title: "8. Use the mobile base" +description: "How to use the mobile base." +lead: "" +date: 2023-07-25T17:38:34+02:00 +lastmod: 2023-07-25T17:38:34+02:00 +draft: false +type: docs +images: [] +toc: true +weight: "140" +--- + +## What is accessible on the mobile base +The following elements are accessible with *reachy.mobile_base*: +* mobile base version, +* battery level, +* odometry of the base, +* control and drive modes, +* goto and set_speed methods to make the mobile base move. + +## Frames + +### Robot frame +The robot frame or egocentric frame or base_link frame is **rigidly attached to the robot**. Its (0, 0) point is the projection on the floor of the center of the mobile base. +**X in front, Y to the left, Theta positive counterclockwise.** + +{{< img-center "images/sdk/mobile-base/robot_frame.png" 400x "" >}} + +*It follows ROS' conventions described in [REP 105 “Coordinate Frames for Mobile Platforms”](https://www.ros.org/reps/rep-0105.html)* + +### Odom frame +The odom frame is a **world-fixed frame**. The position (x, y, theta) of the robot in the odom frame is continuously updated by the HAL through odometry calculations. These calculations currently only use the measurements from the wheels to estimate the movement of the robot. While the position of the robot is continuous, **it should never be relied upon for long-term reference as it will always drift.** + +{{< img-center "images/sdk/mobile-base/odom_frame.png" 400x "" >}} + +The initial position of the odom frame matches the position of the robot when the HAL was started. The odom frame can also be reset to the current position of the robot using: + ```python + reachy_mobile.mobile_base.reset_odometry() + ``` + +## Moving the mobile base + +### Using the goto method +The `goto()` method expects a goal position in the [odom frame]({{< ref "/sdk/first-moves/mobile-base#odom-frame" >}}), composed of 3 elements: x in meters, y in meters and theta in degrees. + +:warning: The most important thing to get used to, is the fact that the odom frame is world-fixed and that the position of the robot is always updated as long as the HAL is running (the HAL is automatically started during the robot boot-up). So by default, **if you ask for a ```goto(0, 0, 0)``` the robot will try to comeback to the position it was at boot-up.** + +To perform a goto relative to the current position of the robot, use the method ```reset_odometry()```. For example, create an instance of reachy with: + +```python +from reachy2_sdk import ReachySDK + +reachy = ReachySDK(host='your-reachy-ip') +``` + +Reset the odometry frame, and ask the robot to move 50cm in front of it: +```python +reachy.mobile_base.reset_odometry() +reachy.mobile_base.goto(x=0.5, y=0.0, theta=0.0) +``` +Now, ask for a goto(0,0,0). The robot should go back to its previous position: +```python +reachy_mobile.mobile_base.goto(x=0.0, y=0.0, theta=0.0) +``` + +We recommend taking the time to play around with this concept. + +> Note the **goto() method of the mobile base does not work like [moves methods explained previously]({{< ref "/sdk/first-moves/moves">}})** + + +By default, the robot will always try to reach the goal position, meaning that even if the robot did reach its position and you push it, it will try to come back to the goal position again. + +However, you can define two types of stop conditions through optional parameters. + +- A timeout, expressed in seconds. The robot stops the goto when the elapsed time since the start of the command is superior to the timeout. There is a **default timeout that scales with the distance asked by the goto**. + +- A spatial tolerance, expressed with 4 values: delta_x (the error in m along the X axis), delta_y (the error in m along the Y axis), delta_theta (the angle error in deg) and distance (the l2 distance between the current position and the goal position in m). The robot stops the goto when it is close enough to satisfy all 4 conditions simultaneously. + +### Using the set_speed method +Since the mobile base is holonomic, the `set_speed()` method expects 3 speed commands expressed in the robot frame: +- x_vel, in m/s. The instantaneous speed positive in front of the robot. +- y_vel, in m/s. The instantaneous speed positive to the left of the robot. +- rot_vel, in deg/s. The instantaneous rotational speed positive counterclockwise. + +See the [joy_controller code](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/scripts/joy_controller.py) for a working example. + +:bulb: As a safety measure, the HAL will stop the wheels if it didn't receive a new goal speed in the last 200ms. + +:bulb: The way this is implemented in the HAL is simply to listen to the /cmd_vel topic, apply some smoothing, perform the kinematic calculations and send the speed commands to the wheels. This makes it very easy to create control interfaces using ROS, see the [keyboard example](https://github.com/pollen-robotics/zuuu_hal/blob/main/examples/zuuu_teleop_keyboard.py) or the [joy controller example](https://github.com/pollen-robotics/zuuu_hal/blob/main/examples/zuuu_teleop_joy.py). + +*Note: the HAL has a drive mode to set speed commands for variable amounts of time. Instead of relying on a topic, it creates a service. The niche usage didn't warrant the added complexity, so the interface with the SDK was not made. But if needed, it exists!* diff --git a/content/sdk/getting-started/safety.md b/content/sdk/getting-started/safety.md index 65f3660e..1faf164e 100644 --- a/content/sdk/getting-started/safety.md +++ b/content/sdk/getting-started/safety.md @@ -37,7 +37,7 @@ The robot is delivered with an emergency stop button. Pressing the emergency stop button will **immediately power off all motors**, from the arms to the mobile base wheels. Nevertheless it won't power off the computer, which means you won't lose anything running on the computer. -> If at anytime you feel that you're losing control of the robot's movements or notice an unexpected behavior, **never hesitate to press the emergency stop button**. +> If you feel like you are losing control of the robot's movements or notice an unexpected behavior at anytime, **never hesitate to press the emergency stop button**. Someone must be holding the emergency stop button at any time when using the robot, being ready to press the button if needed, and keep its attention focused on the robot. diff --git a/content/sdk/mobile-base/getting-started.md b/content/sdk/mobile-base/getting-started.md deleted file mode 100644 index ae494914..00000000 --- a/content/sdk/mobile-base/getting-started.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Getting started with the mobile base" -description: "Quick overview of the mobile base control using the Python SDK" -date: 2023-07-26T08:32:26+02:00 -lastmod: 2023-07-26T08:32:26+02:00 -draft: false -images: [] -type: docs -toc: true -weight: "140" ---- - -## Overview -To control the mobile base, we developed a Python SDK working similarly to *reachy-sdk* but only for the mobile base: [mobile-base-sdk](https://github.com/pollen-robotics/mobile-base-sdk). As with *reachy-sdk*, you can use *mobile-base-sdk* to connect to the base remotely from another computer, as long as your computer and Reachy's computer are connected to the same network. - -However, to avoid having to use two different Python SDks when working on Reachy mobile, we integrated the use of mobile-base-sdk in reachy-sdk so that when you're accessing the mobile base with the *reachy_mobile.mobile_base* attribute, you are actually using *mobile-base-sdk*. - -Having a dedicated SDK for the mobile base still gives the advantage of having the possibility to work on the mobile base alone. -More detailed in the page [Using the mobile base without Reachy]({{< ref "/sdk/mobile-base/mobile-base-alone" >}}). - -## Installation -If you did not do it yet, follow the instructions from the [install page]({{< ref "/sdk/getting-started/install" >}}) to learn how to install Reachy's Python SDK on your computer. We recommend performing the installation in a virtual environment. - -> :bulb: You will need to make sure that you get a version of [reachy-sdk](https://github.com/pollen-robotics/reachy-sdk) > 0.5.1 to be able to connect to the mobile base. - -Even though you used PyPi for the installation, we recommend cloning the [mobile-base-sdk repository](https://github.com/pollen-robotics/mobile-base-sdk) on your computer as it gives you access to many [examples](https://github.com/pollen-robotics/mobile-base-sdk/tree/main/mobile_base_sdk/examples) to learn how to use the mobile base. - -## Connecting to Reachy mobile -Connecting to the mobile base using Reachy's Python SDK is as simple as connecting to Reachy. When instanciating the ReachySDK object with your Reachy's IP as in the [Hello World page]({{< ref "/sdk/getting-started/hello-world" >}}), you just have to specify that you are using a mobile base. - -```python -from reachy_sdk import ReachySDK - -reachy_mobile = ReachySDK(host='your-reachy-ip', with_mobile_base=True) -``` - -The mobile base is then accessible with the *reachy_mobile.mobile_base* attribute. - -```python -reachy_mobile.mobile_base ->>> -``` - -## What is accessible on the mobile base -The following are accessible with *reachy_mobile.mobile_base*: -* mobile base version, -* battery level, -* odometry of the base, -* control and drive modes, -* goto and set_speed methods to make the mobile base move. - -The section [moving the mobile base]({{< ref "/sdk/mobile-base/moving-the-base" >}}) details the use of the goto and set_speed methods, the odometry of the base while the [advanced]({{< ref "/sdk/mobile-base/drive-control-modes" >}}) section explains the role of the control and drive modes. - -## Moving the mobile base - -### Using the goto method -You can move the base with just one line of code, using the goto method. For example, you can make a 90 degrees rotation: - -```python -reachy_mobile.mobile_base.reset_odometry() -reachy_mobile.mobile_base.goto(x=0.0, y=0.0, theta=90.0) -``` - -Okay, that was 2 lines of code, but the first one is not needed and was added for safety. The section [moving the mobile base]({{< ref "/sdk/mobile-base/moving-the-base" >}}) is dedicated to explaining how to move the base using the Python SDK. - -Check the [getting-started notebook](https://github.com/pollen-robotics/reachy-sdk/blob/main/reachy_sdk/examples/mobile-base-getting-started.ipynb) for a detailed getting started example using the Python SDK. - - -### Using a joystick -The best (and easiest) way to get a sense of how the mobile base moves is by moving it yourself! It is easy to do that with the [joy_controller.py script](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/scripts/joy_controller.py) where you can fully control the mobile base using an Xbox or PlayStation joystick (a controller should be included with your Reachy mobile). - -To start controlling the base with *joy_controller.py*, just type: -```bash -cd ~/dev/mobile-base-sdk/examples/script -python3 joy_controller.py -``` -The left joystick will be used for translation and the right one for rotation. - -

- {{< video "videos/sdk/lidar_safety_360.mp4" "80%" >}} -

- -The script reads the controller and uses the *mobile-base-sdk* to send speed commands to the mobile base. Don't hesitate to take a look at the [code](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/scripts/joy_controller.py) to have an example of good practices for an app involving the base. - -## Hardware Abstraction Layer -In this documentation, you'll find references to the Hardware Abstraction Layer (HAL). The HAL is the ROS2 middleware that interacts with the hardware while the SDK interacts with the HAL. This modular software architecture allows for more flexibility and a simple, high level interface. However, if you need more control or a feature that wasn't ported to the SDK, you can interact directly with the HAL. The philosophy behind this documentation is to give an easy access to the most common usages, and to give pointers that can be useful when pursuing a more advanced usage. The [HAL repository can be found here.](https://github.com/pollen-robotics/zuuu_hal) diff --git a/content/sdk/mobile-base/mobile-base-alone.md b/content/sdk/mobile-base/mobile-base-alone.md deleted file mode 100644 index fd14c583..00000000 --- a/content/sdk/mobile-base/mobile-base-alone.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Using the mobile base without Reachy" -description: "How to use the mobile base without a Reachy" -date: 2023-07-26T08:32:35+02:00 -lastmod: 2023-07-26T08:32:35+02:00 -draft: false -images: [] -type: docs -toc: true -weight: "180" ---- - -There is no need to instanciate the entire Reachy stack to interact with the mobile base. -Instanciating the *mobile-base-sdk* alone is very fast and easy: -```python -from mobile_base_sdk import MobileBaseSDK - -mobile_base = MobileBaseSDK('your-reachy-ip') -``` -This will work even if the upper body is not powered (the computer has to be powered though). - -Once the object 'mobile_base' is implemented the syntax is the same to what has been covered in the rest of the documentation, just remove the "reachy." keyword. For example, to read the odometry just type: - -```python -mobile_base.odometry -``` - -You can use this [Jupyter Notebook](https://github.com/pollen-robotics/mobile-base-sdk/blob/main/mobile_base_sdk/examples/notebooks/getting-started.ipynb) example to test this. diff --git a/content/sdk/mobile-base/safety.md b/content/sdk/mobile-base/safety.md index 924cdf94..faa56964 100644 --- a/content/sdk/mobile-base/safety.md +++ b/content/sdk/mobile-base/safety.md @@ -20,7 +20,6 @@ The safety is active regardless of how you command the mobile base (teleop, cont :warning: The safety only works with obstacles that can be seen by the LIDAR. Small obstacles that are below the LIDAR won't be seen. Similarly, the LIDAR will see the legs of a table, but not the table top. -:bulb: We recommend that you get a feel of how this safety works by moving around with the controller see [(getting started)]({{< ref "sdk/mobile-base/getting-started#controlling-the-mobile-base-with-a-joystick">}}). Drive slowly into a wall, the mobile base should slow down and then stop. The safety should prevent the collision even when driving into the wall at full speed, which we do not recommend though :). ## Detailed behaviour