initial create3 documentation

Signed-off-by: Alberto Soragna <[email protected]>

README.md

@@ -1,2 +1,20 @@
 # create3_docs
-Documentation for the iRobot Create3 robot
+
+Documentation for the iRobot Create3 robot.
+
+### Build the docs locally
+
+Install required dependencies:
+
+```bash
+pip3 install mkdocs
+pip3 install mkdocs-material
+```
+
+Build the documentation locally:
+
+```bash
+mkdocs serve
+```
+
+Open `http://127.0.0.1:8000/` in a browser to visualize the docs.

docs/api/docking.md

@@ -0,0 +1,57 @@
+# Create3 Docking
+
+The Create3 robot is equipped with a docking station to recharge it between experiments.
+
+Through the ROS 2 APIs users can command docking and undocking autonomous behaviors.
+
+Note that, in order for the robot to detect the dock, determine its location and understand when it is succesfully docked, it is necessary that the docking station is connected to a power source.
+
+## Built-in docking behaviors
+
+#### Undocking
+
+You can command the robot to undock using the following ROS 2 action.
+
+```bash
+ros2 action send_goal /undock irobot_create_msgs/action/Undock "{}"
+```
+
+The robot will move backward out of the dock and then it will rotate 180 degrees.
+
+This action will fail if the robot is already undocked.
+
+#### Docking
+
+You can command the robot to dock using the following ROS 2 action.
+
+```bash
+ros2 action send_goal /dock irobot_create_msgs/action/DockServo "{}"
+```
+
+The robot will first search for the dock in its immediate surroundings.
+Note that the action will fail if the robot is too far from the dock.
+You can check if the dock is visible by subscribing to the `/dock` ROS 2 topic.
+
+Then the robot will align with the dock and carefully drive onto it.
+
+This action will fail if the robot is already docked.
+
+## Docking sensor data
+
+The Create3 robot exposes several docking-related information through its ROS 2 publications.
+These should allow users to write their own algorithms taking into account the presence of the dock in the environment and even to write their own docking and undocking procedures.
+
+#### IR opcodes
+
+The Create3 docking station transmit several IR signals.
+The Create3 robot is equipped with two different sensors that are capable of detecting them.
+
+![Docking signals](data/create3_dock_codes.png)
+
+The robot will publish these signals in the `/ir_opcode` ROS 2 topic.
+Each message will contain a time-stamped detection of one of those signals, including the identifier of the sensor that detected it.
+
+#### Dock information
+
+More high-level information is produced by the robot in the `/dock` ROS 2 topic.
+Here it's possible to quickly know if the robot is able to see the dock from its current location and whether it is currently docked or not.

docs/api/reflexes.md

@@ -0,0 +1,85 @@
+# Reflexes
+
+With the word "reflex" we denote a set of autonomous reactive behaviors that the Create3 robot will trigger when it detects obstacles or hazards.
+
+Reflexes are high-priority behaviors and will temporarily override any user-provided command for their short duration.
+
+Reflexes can be enabled or disabled on the Create3 using the corresponding ROS 2 parameters exposed by the `motion_control` ROS 2 node.
+
+## Reflex parameters
+
+The `reflexes_enabled` parameter controls whether reflexes should be executed or not. It accepts boolean values.
+When this parameter is set to `false`, no reflexes will be enabled, regardless of their specific parameters values.
+
+Reflexes are enabled by default.
+
+### Bumps reflex
+
+The `reflex.REFLEX_BUMP` ROS 2 parameter enables (`true`) or disables (`false`) the bump reflex.
+It will trigger as soon as the robot bumps into an obstacle and it will move the robot away from it.
+The reflex will continue until the robot has cleared the bump.
+
+This reflex is enabled by default.
+
+### Cliffs reflex
+
+The `reflex.REFLEX_CLIFF` ROS 2 parameter enables (`true`) or disables (`false`) the cliff reflex.
+It will trigger as soon as the robot detects a cliff and it will move the robot away from it.
+The reflex will continue until the robot has cleared the cliff.
+
+This reflex is enabled by default.
+
+### Dock avoidance reflex
+
+The `reflex.REFLEX_DOCK_AVOID` ROS 2 parameter enables (`true`) or disables (`false`) the dock avoidance reflex.
+It will trigger as soon as the robot gets close to the dock and tries to move towards it.
+The reflex will stop forward movements.
+
+This reflex is disabled by default.
+
+### Gyro calibration reflex
+
+The `reflex.REFLEX_GYRO_CAL` ROS 2 parameter enables (`true`) or disables (`false`) the gyro calibration reflex.
+It will trigger while the robot is stationary and will try to recalibrate the internal gyroscope.
+
+This reflex is enabled by default.
+
+### Panic reflex
+
+The `reflex.REFLEX_PANIC` ROS 2 parameter enables (`true`) or disables (`false`) the dock avoidance reflex.
+It will trigger when the robot is trapped and unable to clear obstacles or hazards.
+The reflex will try more aggressive maneuvers to allow the robot to recover from this situation
+
+This reflex is enabled by default.
+
+### Proximity slowdown reflex
+
+The `reflex.REFLEX_PROXIMITY_SLOWDOWN` ROS 2 parameter enables (`true`) or disables (`false`) the dock avoidance reflex.
+It will trigger when the robot's IR sensors detect an obstacle in close proximity.
+The reflex will reduce the robot movement speed in order to better prepare for an eventual impact.
+
+This reflex is enabled by default.
+
+### Stuck reflex
+
+The `reflex.REFLEX_STUCK` ROS 2 parameter enables (`true`) or disables (`false`) the dock avoidance reflex.
+It will trigger when the robot is stuck, i.e. it's pushing against an obstacle and its wheels are losing traction.
+The reflex will try aggressive maneuvers to allow the robot to recover from this situation
+
+This reflex is enabled by default.
+
+### Virtual Wall reflex
+
+The `reflex.REFLEX_VIRTUAL_WALL` ROS 2 parameter enables (`true`) or disables (`false`) the cliff reflex.
+It will trigger as soon as the robot detects an iRobot virtual wall it will move the robot away from it.
+The reflex will continue until the robot has cleared the virtual wall.
+
+This reflex is enabled by default.
+
+### Wheel drop reflex
+
+The `reflex.REFLEX_WHEEL_DROP` ROS 2 parameter enables (`true`) or disables (`false`) the cliff reflex.
+It will trigger as soon as the robot detects that one of its wheels is fully extended (dropped).
+The robot will drive the other wheel in order to return to a flat surface.
+
+This reflex is enabled by default.

docs/api/ros2.md

@@ -0,0 +1,105 @@
+# ROS 2 APIs
+
+The Create3 robot is based on ROS 2 and, as such, it exposes all its user-facing APIs through ROS 2 entities (topics, services, actions and parameters).
+
+The purpose of this page is to give a quick overview of these ROS 2 APIs.
+If you are interested in more details, have a look at the other pages in this section.
+
+## ROS 2 Topics
+
+You can see the ROS 2 topics exposed by the robot running the `ros2 topic list` command.
+
+```bash
+$ ros2 topic list
+/battery_state
+/cmd_lightring
+/cmd_vel
+/dock
+/hazard_detection
+/imu
+/interface_buttons
+/ir_intensity
+/ir_opcode
+/kidnap_status
+/mouse
+/odom
+/parameter_events
+/rosout
+/slip_status
+/stop_status
+/tf
+/tf_static
+/wheel_ticks
+/wheel_vels
+```
+
+## ROS 2 Services
+
+You can see the ROS 2 services exposed by the robot running the `ros2 service list` command.
+
+```bash
+$ ros2 service list
+/e_stop
+/motion_control/describe_parameters
+/motion_control/get_parameter_types
+/motion_control/get_parameters
+/motion_control/list_parameters
+/motion_control/set_parameters
+/motion_control/set_parameters_atomically
+/robot_power
+/static_transform/describe_parameters
+/static_transform/get_parameter_types
+/static_transform/get_parameters
+/static_transform/list_parameters
+/static_transform/set_parameters
+/static_transform/set_parameters_atomically
+```
+
+## ROS 2 Actions
+
+You can see the ROS 2 actions exposed by the robot running the `ros2 action list` command.
+
+```bash
+$ ros2 action list
+/dock
+/undock
+/wall_follow
+```
+
+## ROS 2 Parameters
+
+You can see the ROS 2 parameters exposed by the robot running the `ros2 param list` command.
+
+```bash
+$ ros2 param list
+/motion_control:
+  max_speed
+  qos_overrides./parameter_events.publisher.depth
+  qos_overrides./parameter_events.publisher.durability
+  qos_overrides./parameter_events.publisher.history
+  qos_overrides./parameter_events.publisher.reliability
+  reflexes.REFLEX_BUMP
+  reflexes.REFLEX_CLIFF
+  reflexes.REFLEX_DOCK_AVOID
+  reflexes.REFLEX_GYRO_CAL
+  reflexes.REFLEX_PANIC
+  reflexes.REFLEX_PROXIMITY_SLOWDOWN
+  reflexes.REFLEX_STUCK
+  reflexes.REFLEX_VIRTUAL_WALL
+  reflexes.REFLEX_WHEEL_DROP
+  reflexes_enabled
+  safety_override
+  use_sim_time
+/static_transform:
+  qos_overrides./parameter_events.publisher.depth
+  qos_overrides./parameter_events.publisher.durability
+  qos_overrides./parameter_events.publisher.history
+  qos_overrides./parameter_events.publisher.reliability
+  qos_overrides./tf_static.publisher.depth
+  qos_overrides./tf_static.publisher.history
+  qos_overrides./tf_static.publisher.reliability
+  use_sim_time
+  wheel_base
+  wheels_encoder_resolution
+  wheels_radius
+```

docs/api/safety.md

@@ -0,0 +1,64 @@
+# Create3 Safety Overrides
+
+By default, the Create3 robot has some safety features enabled.
+Their purpose is to make sure that the robot does not get into dangerous sitations and it is able to detect and react properly to cliff hazards.
+
+Safety features are configurable by the user through a ROS 2 parameter.
+This will allow the more adventurous users to have full control over the robot.
+
+!!! important 
+    The robot will temporarily re-enable safety features whenever it is commanded to execute any of the built-in autonomous behaviors.
+
+The `safety_override` parameter exposed by the `motion_control` ROS 2 node should be used to control and override safety features.
+It's a `string` parameter and it accepts 3 possible values:
+
+ - `none` Safety features are fully enabled. This is the default value. 
+ - `backup_only` Overrides the robot backup limit safety feature, disabling it.
+ - `full` Safety features are fully disabled.
+
+Note that the parameter server will reject changes if there are typos in the new safety value set by the users.
+
+The following sections briefly describe what the safety features do.
+
+## Backup Limit
+
+The Create3 robot is equipped with cliff sensors, but they are located only in the front of the robot.
+This means that the robot is not able to detect cliff hazards while driving backward.
+
+In order to make the robot safe, thus we need to make sure that the robot never moves backward more than what it's safe to do.
+Under standard circumstances, the robot is allowed to briefly move backward only if it has first traveled forward (i.e. if it has "explored" the space making sure that it does not present cliff hazards).
+
+If the robot is kidnapped (i.e. first lifted by the user and then placed somewhere), the backup limit will immediately trigger.
+
+The Create3 robot signals to the user when the backup limit is about to be triggered in multiple ways:
+
+ - Through the `HazardDetectionsVector` ROS 2 message: an hazard of type `BACKUP_LIMIT` will be published in the vector.
+ - By logging a warning message.
+ - By changing the color of the lights to orange.
+
+If the user ignores these alerts and keeps driving the robot backward, the robot will suddenly break and stop.
+From this point, the robot will refuse any backward movement.
+The user will have to drive the robot forward in order to re-enable backward movements.
+As soon as the user will drive the robot forward, the lights will go back to the default white color.
+Safe backward movements will not be immediately re-allowed, but rather the robot will have to keep driving forward for a little while.
+This moment will be identified by the `BACKUP_LIMIT` hazard disappearing from the `HazardDetectionsVector` message.
+
+The backup limit and its related alerts are active only when `safety_override = none`.
+
+!!! attention 
+    The robot will not stop if there are cliffs when driving backward!
+
+
+## Maximum speed
+
+In order to stop when a cliff hazards is detected, it is also necessary to make sure that the robot is not driving too fast.
+Safety features will thus limit the robot speed.
+
+You can check the current maximum robot speed through the read-only parameter `max_speed` exposed by the `motion_control` ROS 2 node.
+
+When `safety_override = none` or `safety_override = backup_only` the maximum speed will be limited to 0.306 m/s.
+
+By fully disabling safety features, i.e. setting `safety_override = full` the robot will be allowed to drive at its true maximum speed of 0.460 m/s.
+
+!!! attention 
+    The robot may not be able to stop in time if driving at full speed if a cliff is detected!

docs/index.md

@@ -0,0 +1,15 @@
+# Welcome to iRobot Create3
+
+TODO: add pictures and videos
+
+### Overview
+
+What is Create3?
+
+### Useful links
+
+Here you can find additional content on the iRobot Create3:
+
+ - [Create ROS 2 Messages Definitions](https://github.com/iRobotEducation/irobot_create_msgs)
+ - [Create3 Gazebo Simulator](https://github.com/iRobotEducation/create3_sim)
+ - [Create3 Examples](https://github.com/iRobotEducation/create3_examples)

docs/robot-setup/robot.md

@@ -0,0 +1,3 @@
+# The Robot
+
+This page describes the Create3 robot.

docs/robot-setup/start.md

@@ -0,0 +1,3 @@
+# Start Your Robot
+
+This page describes the steps required to start your robot for the first time.