Release G.5.1 / H.2.1 (#420)

* Add G.5.1, H.2.1, and associated features * Update admonitions for beta features * Move "beta" admonition on pages with images * Add example middleware profiles from robot * Add example topic values to hazards
iRobotEducation · Jul 6, 2023 · 15d99f2 · 15d99f2
1 parent bef30f8
commit 15d99f2
Show file tree

Hide file tree

Showing 15 changed files with 358 additions and 27 deletions.
diff --git a/docs/api/hazards.md b/docs/api/hazards.md
@@ -21,23 +21,191 @@ In particular the timestamp will denote when the robot detected the hazard and t
 !!! important
     The `hazard_detection` topic will also contain a `BACKUP_LIMIT` hazard if the robot safety features are preventing it from safely moving further backwards. Look at the [safety documentation](safety.md) for details and how to disable it.
 
+??? example
+    No hazards:
+    ```
+    header:
+      stamp:
+        sec: 1688673217
+        nanosec: 973425138
+      frame_id: base_link
+    detections: []
+    ```
+
+    Many hazards:
+    ```
+    header:
+      stamp:
+        sec: 1688673239
+        nanosec: 782492541
+      frame_id: base_link
+    detections:
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 782576914
+        frame_id: cliff_side_left
+      type: 2
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 782576914
+        frame_id: cliff_front_left
+      type: 2
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 782576914
+        frame_id: cliff_front_right
+      type: 2
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 782576914
+        frame_id: cliff_side_right
+      type: 2
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 781947051
+        frame_id: left_wheel
+      type: 3
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 781947051
+        frame_id: right_wheel
+      type: 3
+    - header:
+        stamp:
+          sec: 1688673239
+          nanosec: 782576914
+        frame_id: base_link
+      type: 0
+    ```
+
 ### The `kidnap_status` topic
 
 By "kidnap" we denote the action of manually lifting the robot and, eventually, placing it back in a location which may be different from the original one.
 
 The Create® 3 robot combines together different sensors data in order to determine when it's being kidnapped.
 A boolean status will be periodically published on the `kidnap_status` topic.
 
+??? example
+    ```
+    header:
+      stamp:
+        sec: 1688672489
+        nanosec: 526097022
+      frame_id: base_link
+    is_kidnapped: false
+    ```
 
 ### The `ir_intensity` topic
 
-Besides the aforementioned sensors, the Create® 3 robot is also equipped with [7 sets of IR emitters and receivers](/hw/mechanical/#ir-proximity-sensors) and it can use them to detect objects at close range.
+[7 sets of IR emitters and receivers](/hw/mechanical/#ir-proximity-sensors) are available in the front bumper to detect objects at close range.
 
 The Create® 3 robot will periodically publish on the `ir_intensity` topic the raw intensity readings obtained from these sensors.
 The message will be a vector where each element corresponds to a different sensor.
 The higher the intensity value is, the closer an obstacle is to the robot.
 The `header` field of each indivdual detection will provide all the information required to localize it.
 In particular the timestamp will denote when the robot detected the hazard and the frame id will denote the location of the sensor that performed the detection.
 
+??? example
+    ```
+    header:
+      stamp:
+        sec: 1688673736
+        nanosec: 121692158
+      frame_id: base_link
+    readings:
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_side_left
+      value: 0
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_left
+      value: 0
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_front_left
+      value: 0
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_front_center_left
+      value: 0
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_front_center_right
+      value: 5
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_front_right
+      value: 0
+    - header:
+        stamp:
+          sec: 1688673736
+          nanosec: 121692158
+        frame_id: ir_intensity_right
+      value: 3
+    ```
+
+### The `cliff_intensity` topic
+
+[4 sets of IR emitters and receivers](/hw/mechanical/#bottom-view) are available in on the bottom of the robot just behind its front bumper to detect presence or absence of the floor.
+
+The Create® 3 robot will periodically publish on the `cliff_intensity` topic the raw intensity readings obtained from these sensors.
+The message will be a vector where each element corresponds to a different sensor.
+The higher the intensity value is, the more intensely the floor is perceived.
+The `header` field of each indivdual detection will provide all the information required to localize it.
+In particular the timestamp will denote the time of the reading and the frame id will denote the location of the sensor that performed the detection.
+
+??? example
+    ```
+    header:
+      stamp:
+        sec: 1688672489
+        nanosec: 986327471
+      frame_id: base_link
+    readings:
+    - header:
+      stamp:
+        sec: 1688672489
+        nanosec: 986327471
+      frame_id: cliff_side_left
+    value: 2207
+    - header:
+      stamp:
+        sec: 1688672489
+        nanosec: 986327471
+      frame_id: cliff_front_left
+    value: 2235
+    - header:
+      stamp:
+        sec: 1688672489
+        nanosec: 986327471
+      frame_id: cliff_front_right
+    value: 2206
+    - header:
+      stamp:
+        sec: 1688672489
+        nanosec: 986327471
+      frame_id: cliff_side_right
+    value: 2187
+    ```
+
 [^1]: ROS 2 is governed by Open Robotics
 [^2]: All trademarks mentioned are the property of their respective owners.
diff --git a/docs/api/ros2.md b/docs/api/ros2.md
@@ -13,6 +13,7 @@ You can see the ROS 2 topics exposed by the Create® 3 robot running the `ros2 t
 ```bash
 $ ros2 topic list -t
 /battery_state [sensor_msgs/msg/BatteryState]
+/cliff_intensity [irobot_create_msgs/msg/IrIntensityVector]
 /cmd_audio [irobot_create_msgs/msg/AudioNoteVector]
 /cmd_lightring [irobot_create_msgs/msg/LightringLeds]
 /cmd_vel [geometry_msgs/msg/Twist]

diff --git a/docs/releases/g_5_1.md b/docs/releases/g_5_1.md
@@ -0,0 +1,34 @@
+# iRobot® Create® 3 Release G.5.1
+[[Click here to download release G.5.1]](https://edu.irobot.com/create3/firmware/G.5.1)
+
+## This release is running ROS 2 Galactic with the following interface library versions:
+
+- [irobot_create_msgs - 1.2.4](https://github.com/iRobotEducation/irobot_create_msgs/tree/1.2.4)
+- [cyclonedds - 0.8.1](https://github.com/eclipse-cyclonedds/cyclonedds/tree/0.8.1)
+- [Fast-DDS - 2.3.3](https://github.com/eProsima/Fast-DDS/tree/2.3.3)
+
+## Release Overview
+For iRobot® Education Bluetooth[^1] users, this is a bugfix release.
+For ROS 2[^2] users, this is primarily a feature release.
+See below for details.
+
+## Changelog (from G.4.5)
+### ROS 2
+* Publications
+    * Add `/cliff_intensity` topic [(#320)](https://github.com/iRobotEducation/create3_docs/issues/320)
+    * Add tf frame for the IMU (called `imu`), to which the `/imu` topic is now connected
+* Middleware
+    * Allow the use of `;` characters in Fast-DDS Discovery Server configuration [(#400)](https://github.com/iRobotEducation/create3_docs/issues/400)
+    * Beta: Allow user to [provide an XML configuration file](../../webserver/rmw-profile-override/) for their preferred middleware [(#407)](https://github.com/iRobotEducation/create3_docs/issues/407)
+
+### Core Robot
+* Webserver / OS
+    * Beta: Allow user full control to [edit ntp.conf](../../webserver/edit-ntp-conf/) [(#333)](https://github.com/iRobotEducation/create3_docs/issues/333)
+    * Remove erroneous log messages about the robot's lost Wi-Fi connection when it had never been connected in the first place
+
+### iRobot® Education Bluetooth protocol mode
+* Fix device number for stall event to match protocol document [(#410)](https://github.com/iRobotEducation/create3_docs/issues/410)
+
+[^1]: The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by iRobot is under license.
+[^2]: ROS 2 is governed by Open Robotics.
+[^3]: All other trademarks mentioned are the property of their respective owners.
diff --git a/docs/releases/h_2_1.md b/docs/releases/h_2_1.md
@@ -0,0 +1,37 @@
+# iRobot® Create® 3 Release H.2.1
+[[Click here to download release H.2.1]](https://edu.irobot.com/create3/firmware/H.2.1)
+
+!!! warning
+    When using Fast-DDS, startup times are about 30s longer than in our Galactic release. We are working on a fix.
+
+## This release is running ROS 2 Humble with the following interface library versions:
+
+- [irobot_create_msgs - 2.1.0](https://github.com/iRobotEducation/irobot_create_msgs/tree/2.1.0)
+- [cyclonedds - 0.9.0](https://github.com/eclipse-cyclonedds/cyclonedds/tree/0.9.0)
+- [Fast-DDS - 2.6.4](https://github.com/eProsima/Fast-DDS/tree/2.6.4)
+
+## Release Overview
+For iRobot® Education Bluetooth[^1] users, this is a bugfix release.
+For ROS 2[^2] users, this is primarily a feature release.
+See below for details.
+
+## Changelog (from H.1.2)
+### ROS 2
+* Publications
+    * Add `/cliff_intensity` topic [(#320)](https://github.com/iRobotEducation/create3_docs/issues/320)
+    * Add tf frame for the IMU (called `imu`), to which the `/imu` topic is now connected
+* Middleware
+    * Allow the use of `;` characters in Fast-DDS Discovery Server configuration [(#400)](https://github.com/iRobotEducation/create3_docs/issues/400)
+    * Beta: Allow user to [provide an XML configuration file](../../webserver/rmw-profile-override/) for their preferred middleware [(#407)](https://github.com/iRobotEducation/create3_docs/issues/407)
+
+### Core Robot
+* Webserver / OS
+    * Beta: Allow user full control to [edit ntp.conf](../../webserver/edit-ntp-conf/) [(#333)](https://github.com/iRobotEducation/create3_docs/issues/333)
+    * Remove erroneous log messages about the robot's lost Wi-Fi connection when it had never been connected in the first place
+
+### iRobot® Education Bluetooth protocol mode
+* Fix device number for stall event to match protocol document [(#410)](https://github.com/iRobotEducation/create3_docs/issues/410)
+
+[^1]: ROS 2 is governed by Open Robotics.
+[^2]: The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by iRobot is under license.
+[^3]: All other trademarks mentioned are the property of their respective owners.
diff --git a/docs/releases/overview.md b/docs/releases/overview.md
@@ -33,13 +33,15 @@ Downloads of a particular version can be found on each individual release page.
 
 ### Humble
 
-* [H.1.2](../h_1_2) (humble-latest)
+* [H.2.1](../h_2_1) (humble-latest)
+* [H.1.2](../h_1_2)
 * [H.1.1](../h_1_1)
 * [H.1.0](../h_1_0)
 * [H.0.0](../h_0_0)
 
 ### Galactic
-* [G.4.5](../g_4_5) (galactic-latest, latest)
+* [G.5.1](../g_5_1) (galactic-latest, latest)
+* [G.4.5](../g_4_5)
 * [G.4.4](../g_4_4)
 * [G.4.3](../g_4_3)
 * [G.4.1](../g_4_1)

diff --git a/docs/webserver/data/edit-ntp-conf.png b/docs/webserver/data/edit-ntp-conf.png
diff --git a/docs/webserver/data/rmw-profile-override.png b/docs/webserver/data/rmw-profile-override.png
diff --git a/docs/webserver/edit-ntp-conf.md b/docs/webserver/edit-ntp-conf.md
@@ -0,0 +1,12 @@
+# iRobot® Create® 3 Webserver - Edit ntp.conf
+The Edit ntp.conf page of the Create® 3 webserver allows the user to modify the robot's NTP daemon configuration file.
+
+!!!warning
+    Please note that this is a beta feature, and as such is not supported by the customer service team.
+    Please exercise caution, as improper use of beta features may result in an inoperable robot.
+
+![Picture of edit ntp.conf page](data/edit-ntp-conf.png)
+
+This page allows the user to directly edit `ntp.conf` on the robot. After pressing "save," the NTP daemon must be [restarted](../webserver/restart-ntpd.md).
+
+[^1]: All trademarks mentioned are the property of their respective owners.
diff --git a/docs/webserver/overview.md b/docs/webserver/overview.md
@@ -22,6 +22,11 @@ Please use the menu to navigate between sections of the webserver, or else navig
 - [Application](../webserver/application.md)
 - Beta Features
     - [Serial Forwarder](../webserver/serial-config.md)
+    - [Set Date and Time](../webserver/set-datetime.md)
+    - [Edit ntp.conf](../webserver/edit-ntp-conf.md)
+    - [Restart ntpd](../webserver/restart-ntpd.md)
+    - [Set Wired Subnet](../webserver/set-wired-subnet.md)
+    - [Override RMW Profile](../webserver/rmw-profile-override.md)
 - [About](../webserver/about.md)
 
 [^1]: ROS 2 is governed by Open Robotics

diff --git a/docs/webserver/restart-ntpd.md b/docs/webserver/restart-ntpd.md
@@ -1,8 +1,9 @@
 # iRobot® Create® 3 Webserver - Restart ntpd
 The "Restart ntpd" beta menu option of the Create® 3 webserver instructs the Create® 3 robot to resynchronize its clock.
 
-Please note that this is a beta feature, and as such is not supported by the customer service team.
-Please exercise caution, as improper use of beta features may result in an inoperable robot.
+!!!warning
+    Please note that this is a beta feature, and as such is not supported by the customer service team.
+    Please exercise caution, as improper use of beta features may result in an inoperable robot.
 
 Selecting the "Restart ntpd" option will spawn a pop-up requesting confirmation.
 Restarting the ntp daemon will trigger a time resynchronization with the first time server found.

diff --git a/docs/webserver/rmw-profile-override.md b/docs/webserver/rmw-profile-override.md
@@ -0,0 +1,58 @@
+# iRobot® Create® 3 Webserver - Override RMW Profile
+The Override RMW Profile page of the Create® 3 webserver allows the user to override the robot's inbuilt RMW profiles for its middleware.
+
+!!!warning
+    Please note that this is a beta feature, and as such is not supported by the customer service team.
+    Please exercise caution, as improper use of beta features may result in an inoperable robot.
+
+![Picture of Override RMW Profile page](data/rmw-profile-override.png)<br><br>
+
+## Usage
+This page allows the user to replace the robot's middleware XML profile file with one of their choosing.
+Leave this box blank in order to use the robot's default profile file.
+
+!!!important
+    After pressing "save," the application must be [restarted](../application/#restart-application).
+
+More details about the XML configuration file can be found on respective vendor sites:
+
+* [Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds/blob/master/docs/manual/options.md)
+* [Fast DDS](https://fast-dds.docs.eprosima.com/en/latest/fastdds/xml_configuration/xml_configuration.html)
+
+## Example for Cyclone DDS
+Replace `INTERFACE` with interface(s) of choice (for example, `usb0,wlan0` to communicate on both the USB and Wi-Fi interfaces)
+
+```xml
+<CycloneDDS>
+   <Domain>
+     <General>
+        <NetworkInterfaceAddress>INTERFACE</NetworkInterfaceAddress>
+    </General>
+   </Domain>
+</CycloneDDS>
+```
+
+## Example for Fast DDS
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+    <transport_descriptors>
+        <transport_descriptor>
+            <transport_id>udp_transport</transport_id>
+            <type>UDPv4</type>
+            <maxMessageSize>65000</maxMessageSize>
+        </transport_descriptor>
+    </transport_descriptors>
+
+    <participant profile_name="broadcast_discovery" is_default_profile="true">
+       <rtps>
+            <userTransports>
+                <transport_id>udp_transport</transport_id>
+            </userTransports>
+            <useBuiltinTransports>false</useBuiltinTransports>
+       </rtps>
+    </participant>
+</profiles>
+```
+
+[^1]: All trademarks mentioned are the property of their respective owners.