Routes - ResgreenGroup/Botway-Documentation GitHub Wiki

Current Location: Home->Customizing BotWay->Routes

Summary

Routes provide a way to control the actions of a Robot at each tag it encounters. Commands such as: Wait, Speed Up, Pin Up, Follow Left... etc. are used to control how and where the Robot travels. Each Route is a collection of Tags. Each Tag physically placed in the robot's path will trigger BotWay to send that robot a command when the Tag is read. Tags can have multiple commands associated with them, and they can have different sets of commands in different routes. When a Robot arrives at a Tag the combination of the Route, Tag, and Robot type are used to know which commands to run at that location. Commands vary by Robot type and capability and are determined by the manufacturer. An example command for ResGreen Robots can be found at the bottom of this page.

Editing Through BotWay

Routes2

After logging in as Admin, click the "Edit Routes" Button to display a grid of cells. Each row displays the following:

Route: Name of route
Tag: ID of tag
Robot: Robot type
Delay: A delay in milliseconds to wait before sending command
Jump: What route the robot will change to when it reads this tag
Command: Command to be sent to the robot

Commands are sent to the Robot in the "data1" element of the Action Topic. Click Here for a detailed description of all BotWay communications. Commands may be enclosed by quotes or curly braces. Quoted commands are sent in "data1" as simple text. Commands enclosed in curly braces are sent in "data1" as a JSON object and must be properly formed JSON.

Image: Route Editor dialog window.

Cells can be edited by single or double clicking the cell. Editing with a single click will overwrite what was previously written in a cell. Double clicking will bring up the cursor and allows for precise editing of existing text. Once a cell has been edited and the user selects another cell, the changed cell will turn yellow to indicate it has been modified.
The "Insert Above" and "Insert Below" buttons are used to create new rows. When these are pressed after a cell is selected, a new empty row will appear above or below the current row. These buttons can also be used to add multiple rows. When the user selects multiple rows, then presses one of these buttons, BotWay will insert a number of new rows equal to the number of selected rows; If the user were to highlight 17 rows and press the "Insert Below" button, 17 blank rows will be inserted below the bottom-most row of selected rows.
The "Remove Row" Button is used to delete selected rows. Highlight one or more rows then press this button to put them into a "To Be Deleted" state; the row will be grayed out and its row number will be highlighted in red. The row will not actually be deleted until the user hits the "Save" button.
The Filter feature is found in the top right of the routes dialogue window. Typing something into this field will cause BotWay to hide any line in the route table without that text somewhere in the line. These lines are not deleted; when the text is removed from the "filter" section, all lines will reappear. For example; typing "fScan:"1"" into the filter will remove any line that does not have an "fScan:"1"" in the line. When filtered, the "Insert Above" and "Insert Below" buttons will be disabled.
The user can use the key combination of "ctrl + quote" to copy information from existing cells quickly. When a cell is selected and this command is used, the information in the cell above the selected cell is copied and pasted into the selected cell. This can be used to fill multiple cells at once as well. If the user highlights a column of cells and performs this action, then every highlighted cell will be filled with the information from cell above the topmost entry in the highlighted column of cells. This also applies to multiple selected columns at once. If the user highlights multiple columns of cells and uses "ctrl + quote," then each column will be filled with information from the cell immediately above each column. An example is shown in the images below. Modeled after Excel.

Image: An array of empty cells highlighted in preparation for using "ctrl + quote" to copy above information.

Image: Same array of cells filled with copies of the information above the highlighted columns.

The "undo" button or "ctrl + z" will revert the most recent change made in the route editor. This will not revert a cell that the user is currently editing. Cells are only changed once the user clicks away from a cell. To exit a cell without making changes, click the "Escape" key.
The "redo" button or "ctrl + y" will restores an edit that was previously undone.
Errors are shown when the user types something into a cell in an unacceptable format; for example, the "delay" column only accepts integers between 0 and 10000 and any character other than a number will trigger an error. Errors are denoted by the cell turning light pink. The user will be unable to save the route editor while an error is present within it. Error information is also displayed on the bottom of the route editor dialogue window. Specific information about the error may be displayed by hovering over the cell to display a message detailing the error.

Find and Replace

The route editor has a built in find and replace feature. Press "ctrl + f" to open a find-and-replace dialogue window.

Image: Find and Replace window.

Type the text to be searched for in the "Find" field. RegEx can be used here.
Click the Magnifying glass to locate the next instance of the text in the "Find" field.
Type the desired replacement text into the "Replace" field.
Press the arrows button to replace the next instance of the text in the "Find" field with the text in the "Replace" field.
The "Replace ALL" button will replace all instances of the text in the "Find" field with the text in the "Replace" field.
Checking the "Whole Word" box will only locate instances of text in the "Find" field that have characters before and after them that are not letters or numbers.
For example, typing "z" into the "Find" field will find all four of these examples: rzr, r z r, 1z1, and "z." However, if "Whole Word" is selected, only r z r and "z" will be found.
Selecting the "reverse" option will move up the route table instead of down when finding new instances of the text in the "Find" field.
At the bottom of the find and replace window, the current instance and the total number of found instances are listed

Saving Route Data

When the user enters edit mode and wishes to modify route data, they must save the changes in both the route editor dialogue window and in the map display toolbar. This format is implemented so that the user may make multiple rounds of edits to the route data in a single instance of edit mode. When the user opens the route editor and saves their changes in the route editor but not in the map display toolbar, then opens the route editor again, their changes will still be present, but BotWay will not distribute the changed route instructions until the changes are saved from the map display toolbar. The user may make changes to the route data, save and exit out of the route editor dialogue window, do other tasks in edit mode, then come back to the route editor and still see their changes made.

The user may add lines to the route data wherever they want, or edit an existing line in the route data to change the route name. When the user does this and then saves the route data dialogue window, the lines in the route editor will be sorted by route name.

Multiple Commands on a single tag

Ordinarily, one route in BotWay supports a single command for a single robot per tag in the route. Jumping routes has already been described for cases where the user would like to see different commands run at separate times when a robot passes a tag multiple times. However, BotWay is capable of supporting multiple commands at the same tag on a route. BotWay can have multiple commands at a single tag when the recipient types are different. It can also have multiple commands at a tag for a single recipient type. Commands will be sent from the top command down based on their order in the route editor. Shown below are examples of acceptable use of multiple commands at a single tag.

Image: Valid uses of multiple commands at a single tag.

The first case is when each command has a different recipient type as shown in lines 1-5. When a robot reads a tag, it sends the tag number that was read, the route that it was on, and its client type to BotWay. BotWay finds the appropriate Tag-Route-client type combination in the route editor and sends the command to the robot.

The second case is when a single robot receives multiple commands at a tag, but each command is given an increasingly large delay. This example in lines 6-8 shows a PullBuddy arriving at tag 10. The first command gives it a "Hold" action for 15 seconds. The second command is carried out after a delay of 2 seconds relative to the first command, and the third command is carried out after a delay of 10 seconds relative to the second command or 12 seconds after the first command. When a robot is to receive multiple delayed commands at a tag, the user is responsible for managing how long the delays are and matching it to how long the initial hold command is. Whenever the robot receives a Hold 0 in its command, it will not proceed until it gets a "Go" command, so the hold has to be finite if the robot is to keep going. The amount of time in each delay cell cannot exceed 10000.

Adding a Route in BotWay

This example is for a single route where each tag has one command.

Log in as Admin and enter edit mode. Then click the "Routes" button in the map display toolbar.
Add a number of rows equal to the number of tags that the route is made up of by using the "Insert Above" or "Insert Below" buttons. Instructions can be found earlier in this page.
Fill out each row with the route number, tag number, Robot type, time delay, target route for a jump, and command message. The jump column can be left blank if no route switching occurs, but every other cell must be filled in with something, including the time delay column. The command can either be a JSON Object (by surrounding it in curly braces) or raw text (by surrounding it in double quotes). BotWay does not need to know what the command is; it just sends what is supplied. In this way, interoperability with other robot types is allowed since the manufacturer determines the message format and BotWay sends what is written.
Click the "Save" button in the route editor dialogue window, then click the "Save" save button in the map display toolbar to finalize any route changes. Both buttons must be clicked to save the route data changes. Examples of a command can be found below.