From abac575ed3d2573cedf6b80291a015088dda1628 Mon Sep 17 00:00:00 2001 From: mbostic Date: Mon, 3 Apr 2023 19:26:54 +0200 Subject: [PATCH 1/3] CB doc update --- noetic/conveyorbot/fiducials.md | 37 +++++++--------------------- noetic/conveyorbot/routesetup.md | 25 ++++++++++--------- noetic/conveyorbot/usage.md | 42 ++++++++++++++++++++++++++------ 3 files changed, 57 insertions(+), 47 deletions(-) diff --git a/noetic/conveyorbot/fiducials.md b/noetic/conveyorbot/fiducials.md index 0db0c15..a0bb270 100644 --- a/noetic/conveyorbot/fiducials.md +++ b/noetic/conveyorbot/fiducials.md @@ -20,41 +20,22 @@ ConveyorBot uses several types of fiducials: | 🟩 **Go marker** has a single arrow which point to the direction where the ConveyorBot will drive. | | | 🟥 **Stop marker** is made to halt the ConveyorBot in that spot. After the ConveyorBot moves on top of the Stop marker it rotates in a direction of a marker arrow. While ConveyorBot waits on a Stop marker the user can load or unload the packages. The robot will resume following markers when user presses the CONTINUE button on the touchscreen of the ConveyorBot. | | | 🟦 **Turn marker** is made for creating crossroads. Crossroad is a couple of markers in the same location (they must not overlap!), where each is pointing in an arbitrary/different direction. Purpose of Turn markers and crossroads is to change the driving direction of the ConveyorBot. | | -| 🟪 **Bidirectional marker** is the only marker with 2 arrows in it. ConveyorBot drives allong the arrow that requires less robot rotation. Bidirectional marker is good for two-way routes where ConveyorBot requires to move in both directions for example narrow aisles where there is not enough space for both a forward and return path. | | +| 🟪 **Bidirectional marker** is the only marker with 2 arrows on it. ConveyorBot drives along the arrow that requires less robot rotation. Bidirectional marker is good for two-way routes where ConveyorBot requires to move in both directions for example narrow aisles where there is not enough space for both a forward and return path. | |
-ConveyorBot can be used either with STag or ArUco markers (default and recommended being STag). The analogy of marker types is the same for both. Each marker has a unique numeric ID, which is written on it. This way marker types are correctly distinguished which correspond to the correct ConveyorBot manevers. +ConveyorBot can be used either with STag or ArUco markers (default and recommended being STag). The analogy of marker types is the same for both. Each marker has a unique numeric ID, which is written on it. This way marker types are correctly distinguished which correspond to the correct ConveyorBot maneuvers. -ConveyorBot markers specifically, are rugged prefabricated sticky vinyl stickers that can be peeled off and placed on another floor location. However, it's not recommended to peel them off too many times as they'll stick less each time. +ConveyorBot markers specifically, are rugged prefabricated sticky vinyl stickers that can be peeled off and placed on another floor location. However, it's not recommended to peel them off too many times as they'll stick less each time. In fact, we recommend that while initially setting up the markers, you shouldn't unpeel the stickers, but just stick them to the ground with a tape which doesn't leave traces on the ground or on the marker, and is easy to unpeel (we recommend masking tape). This is so that it is easier to correct a marker's position on the ground if you realize afterwards that the way in which you initially positioned the marker is not ideal. Once you are happy with the position, you can stick the marker on the ground with the glue on its back. ## Generating Markers -You can also print out markers on regular paper, though this requires a few modifications on the robot side (mainly marker size). We've provided a selection of scripts that offer a simple terminal UI, which enables user to re-configure fiducials according to their need. - -Said scripts can be found in the ConveyorBot repository in the `breadcrumb/breadcrumb_detect/scripts` directory: - -- `ArUco/gen_markers.py` -> generate Aruco markers with frames -- `STag/gen_markers_autogen.py` -> generate STag markers with frames by generating also the inner part. -- `STag/gen_markers.py` -> generate STag markers with frames by getting the inner part from downloaded image library. Download the required images from [here](https://drive.google.com/drive/folders/0ByNTNYCAhWbIV1RqdU9vRnd2Vnc). - -Script were tested using python2.7. - -### ArUco Dictionary ID - -You can generate ArUco markers from any dictionary you prefer. -Make sure you set the corresponding `dictionary` parameter in launch file. -We performed most of the test with dictionary with **ID 7**. -For more information about ArUco refer to [`ArUco`](http://docs.opencv.org/trunk/d5/dae/tutorial_aruco_detection.html). - -### STag Library HD - -You can generate STag markers from any library you prefer. -Make sure you set the corresponding `libraryHD` parameter in launch file. -We performed most of the test with library **HD15**, which suited our needs. -For more information about STag refer to [`STag`](https://github.com/usrl-uofsc/stag_ros). +It might happen that you run out of markers which are provided with your Conveyorbot. +Right now, to obtain additional markers, we recommend you contact UbiquityRobotics and we will print new markers for you. If you are interested in printing them on your own, because maybe you want to experiment with different materials of markers, you can also ask us to send you a PDF with the markers. We are also working on a webpage where you will be able to generate them on your own. Note that you need to be careful to print them exactly in the size in which they are in the PDF (a side of the inner black square which contains the white shape inside of it has to be 18cm long). ### Packs -Generally each pack should correspond to a standalone route, but you can generate yourself packs according to your preference. -Take note that each marker has a unique id, while a number is unique only to the pack. \ No newline at end of file +A "pack" is a number on each marker which says to which "marker setup" a marker belongs. +A marker setup is a group of all of the markers on which a robot can drive. In other words, robots can't go from one marker setup to another by following any marker sequence. A marker setup usually means all of the markers which form the "main circular route" and all of the "branches" connected to it. +It is not necessary to use this number (you might just use number 1 for all marker setups), but it is a convenient way of differentiating between different marker setups if you want to do so. +It is a rule that each marker on a marker setup has to be unique (has to have a unique ID). If you have 2 or more marker setups, you can use a marker with the same ID on each of them (but only once on each). More information about route setup will be in Route Setup section. \ No newline at end of file diff --git a/noetic/conveyorbot/routesetup.md b/noetic/conveyorbot/routesetup.md index 7615a39..4c5b412 100644 --- a/noetic/conveyorbot/routesetup.md +++ b/noetic/conveyorbot/routesetup.md @@ -11,15 +11,21 @@ nav_exclude: false To set up a route you'll first have to place [fiducial markers](noetic_conveyorbot_fiducials) in desired locations, and then use the touchscreen to set up which turn markers each robot should follow. +Please read [usage guide](noetic_conveyorbot_usage) section first to get the general understanding of how routes work. + +**Note that this page is a work in progress and some parts might be outdated. If you are unsure about some details, contact Ubiquity Robotics support.** + ## How to place floor markers -To make sure your setup works as intended, set of rules need to be followed to prevent undesired behaviour: +To make sure your setup works as intended, set of rules need to be followed to prevent undesired behavior: - Each marker should accurately point towards the next one
+- Markers shouldn't be too close together (crossroads are exceptions) + - Before sticking markers to the ground using their strong adhesive back side, it is recommended to stick them to the ground using some tape, so that you can test if your route setup is correct. Be careful that you don't cover the inner black part of the marker with the tape. After you've made sure the route is setup correctly, you can stick the markers by removing their back side. Stick the markers onto clean, smooth floor.
-- Route loops should be set up in a way that makes the robots turn only left or right depending on where the lidar is mounted. This is done to prevent blind spot collisions and to simplify robot to robot interactions.
+- Route loops should be set up in a way that makes the robots turn only left or right depending on where the lidar is mounted. This is done to prevent "T-shaped" collisions and to simplify robot to robot interactions. **It is currently necessary to place the lidar in "shell left" position and setup routes so that robot does left turns (robot drives counter-clockwise from bird's-eye view) This limitation will be soon removed and you will be able to setup routes in both directions**
- TURN markers should be used to create crossroads (or switches, in railroad terms)
@@ -39,8 +45,11 @@ By default, the GO markers which are rotated in the opposite direction as the ro ### Circuit route -If you want multiple robots to drive on the same marker setup, you should arrange the markers in a so-called "Circuit route", so that the robots won't collide into each other. This type of marker setup is recommended even if you have only one robot, because you never know when you will add another robot to your fleet. We divide circuit route into an inbound and an outbound path. Inbound serves as the path for robots to drive to the goal and the outbound is the path which is used for the robots to return back to the starting point. The inbound and outbound paths should be at a little more (about 20 cm more) than 1 robot width apart, so that the robots can pass each other without collision. If you have space, its convienient to place the routes 1 meter apart. On both ends of the path, markers should be arranged in a specific way, shown in the image bellow. +If you want multiple robots to drive on the same marker setup, you should arrange the markers in a so-called "Circuit route", so that the robots won't collide into each other. This type of marker setup is recommended even if you have only one robot, because you never know when you will add another robot to your fleet. We divide circuit route into an inbound and an outbound path. Inbound serves as the path for robots to drive to the goal and the outbound is the path which is used for the robots to return back to the starting point. The inbound and outbound paths should be at a little more (about 20 cm more) than 1 robot width apart, so that the robots can pass each other without collision. If you have space, its convenient to place the routes 1 meter apart. On both ends of the path, markers should be arranged in a specific way, shown in the image bellow. When setting up a route, the measurements from the image bellow need to be considered. + +Circuit route includes one "Main circular route" which can be seen either as "main inbound and outbound paths", or just as a circular route. You can set it up in a inbound-outbound style where inbound and outbound paths are close together (e.g. if you want the whole Main circular route in one hallway) or you can set it up as a big "looping route" which "ends where it begins" and has "inbound and outbound paths" far apart (e.g. in separate hallways). So, the style of "Main circular route" is dependent on your specific use case. + If you want to include a STOP marker into the Circuit route, the best way of placing it is one meter behind the GO marker. GO markers must be max 4-5 meters apart regardless of where you put the STOP markers, because the STOP markers are ignored in the case if you don't want the robot to stop on them. As seen from the image, on each end of the Circuit route, there is a TURN marker, which you need to include into the route on the touchscreen. This can't be a GO marker, because it would be ignored as it is turned in opposite direction as the robot's driving direction. @@ -52,10 +61,10 @@ You can also do "branches" from the main circular route similarly as shown on th -As you can see, there is a possibility that two robots would collide into each other on the marker where the branch merges back into the main route. This is handeled in a way that the robot comming from the branch always "looks" to the left with LIDAR in order to see if there is another robot approaching from the main route. If this is the case, the robot approaching from the branch will stop and wait for the robot on the main route to pass. +As you can see, there is a possibility that two robots would collide into each other on the marker where the branch merges back into the main route. This is handled in a way that the robot coming from the branch always "looks" to the left with LIDAR in order to see if there is another robot approaching from the main route. If this is the case, the robot approaching from the branch will stop and wait for the robot on the main route to pass. This is the so-called "T-shaped collision avoidance". But this introduces a problem. The robots **always** look to the left when turning right on a marker in order to detect a potential robot on the main route. This means that if the robot is just turning right (and it is not going back to the main route), ideally there should also be about two meters of clearance on the left side of the robot so that the wall or any other obstacle is not detected as the robot approaching from the main route. So, if the robot is driving in a hallway which is turning right, you should put the inbound path as close to the right wall as needed so that there is still 2 meters of clearance on the left side of the robot. Or, if that's not possible, you should disable t collision detection for each individual marker, that makes the robot turn right, on which you don't want the robot to stop because of the obstacle on the left. This can be done on the touchscreen's route settings screen. By clicking on any marker in the route, a popup will open where you can check the "Disable T collision check" checkbox. -Bear in mind that to rejoin the main route at the point where the main route makes a 90 degree turn will create problems with this collision avoidance. Please rejoin the main route a few cm earlier than where the main route takes a 90 degree turn. +Bear in mind that to rejoin the main route at the point where the main route makes a 90 degree turn will create problems with this collision avoidance. (This is because the robot "looks" into reverse direction to which the marker on the main route is facing. So if the robot on the main route is not approaching that marker from marker's reverse direction, T-shaped collision avoidance won't work). Please rejoin the main route a few dm earlier than where the main route takes a 90 degree turn (by placing a marker there and pointing the last marker on the branch towards it). ### Narrow hallway limitations @@ -100,9 +109,3 @@ If you want to completely ignore a marker, put it into the right (“Don’t fol When creating the route, you have to be careful that the first marker is close enough for the robot to detect it, otherwise the robot won't start. You can see if the first marker is detected in the Debug screen. It should have a green outline on the camera image. A special case, where you have to specify GO, STOP and BIDIR markers in the route is, if there are two markers from the same crossroads in the route one after another. This would happen, for example, when the route goes from a crossroad to the STOP marker, which is directed back to the same crossroad. In this case, this STOP marker also has to be specified in the marker list. In general, at least one marker on a part of the route which goes out of the crossroad and then back to the same crossroad has to be specified. This is a current issue and it will be resolved in further updates. Note that after changing the route in any way, it will be resent to the robot automatically and started from beginning, so you should move the robot to the start of the route after doing that. - -### Remainder route -(Be aware that this is an experimental feature and might not work as expected in all cases. It will also probably be removed in the future.) -When performing an action which would override an unfinished route, a remainder of that route is saved as a route with name “\”. This is useful, because if the user accidentally selects a different route or exits the software, he/she won’t have to manually drive the robot to the end/start of the route, but the robot will just continue where it left by selecting the “\” route. -Depending on where the robot was interrupted, the remainder might be one marker too long - the first marker of the remainder route might not be visible by the robot anymore. In that case, the user should delete the first marker by manually editing the remainder route. - diff --git a/noetic/conveyorbot/usage.md b/noetic/conveyorbot/usage.md index 48b40e6..93a274c 100644 --- a/noetic/conveyorbot/usage.md +++ b/noetic/conveyorbot/usage.md @@ -9,14 +9,25 @@ nav_exclude: false # Basic Usage -Before using conveyorbot, it is necessary to [set up routes](noetic_conveyorbot_setup). +Before using Conveyorbot, it is necessary to [set up routes](noetic_conveyorbot_setup). If routes are already set up and you just want to run the robot on a particular route, this page should provide enough information to do so. It is also recommended that you first read this page before setting up routes, so that you understand the basic operation of the robot. -Initially when robot boots up, the touchscreen display should show a **Loading** screen. After the system is ready you should be able to see a screen with a **START** button. +## Turning Conveyorbot on and off + +On the right side of the shell of the robot, a bit above its right wheel, there is a black power switch and a red emergency stop push button. To start up the robot, you should switch the power switch to the "on" state and wait for the boot process to finish. +To shut down the robot, you should press the Power off button in the navigation bar of the robot's touchscreen and wait for the shut down process to finish. After that, you can switch the power switch to the "off" state. +If you need to stop the robot in an emergency situation, you can push the emergency stop button. This will cause the robot to stop moving (but won't turn off the robot). If you want it to start moving again, rotate the emergency stop button a bit to release it. +Note that it might also happen that the robot won't move, because the emergency stop button is pressed without you being aware of it. In this case, release it. + +## Starting the robot + +Initially when the robot boots up, the touchscreen display shows a **Loading screen**. After the system is ready, you should be able to see a screen with a **START** button and a drop-down list from which a desired route can be selected. -From initial pose, it will wait for the user to press START and the move to towards the detected marker. -It is important that the robot sees the first marker, otherwise it will not move and pop-up a warning on the screen. +You should first select a route and then the Conveyorbot will wait for the user to press the START button. This will cause it to start driving on that route. +It is important that the robot initially sees (detects) one marker which is a part of the selected route, otherwise it will not move and a warning will be shown on the screen. To make sure that the robot sees a particular marker, you can open the **Joystick control screen** with the monitor-shaped button in the navigation bar. There you will see an image of what the robot currently sees, and currently detected markers will be outlined with a green outline. If the marker from which you wish to start the robot is not in the camera's field of view, you can move the robot with the joystick on the right side of that screen so that the marker will be in the field of view. It is also required that if you want to start the robot from a green "GO" marker, the robot should be directed in the same direction as the GO marker, since oppositely directed GO markers are ignored by default. This means that the robot has to be on the "other side" of the GO marker (on the side without the arrow) and needs to be facing towards the marker (and have it in the camera's FOV). If you are starting the robot from a purple "BIDIRECTIONAL" marker, note that the robot will start driving in one of the two directions to which the arrows of the marker are pointing - in the direction which requires less robot rotation. [Here](noetic_conveyorbot_fiducials) is more information about each type of markers. + +## Navigation and stopping