Customization - ResgreenGroup/Botway-Documentation GitHub Wiki

Current Location: Home->Customizing BotWay-> Customization

These files are described here for informational purposes, but modifying any of these files should be left to qualified technicians only.
BotWay can be customized and managed through a series of .xml files. A description of any .xml files that modify BotWay can be found here. Any .xml files where information is persisted are found in the "Data" folder. Any .properties files that modify aspects of BotWay are found in the BotWay folder itself.

---

This folder contains locations where BotWay persists information in several .xml files regarding specific aspects of BotWay. The admin can specify which folder in Data is to be the current data path for BotWay in the BotWay.properties file. SubFolders can be made here but that will require the user to change the working folder in the BotWay.properties file. Most .properties files can be changed from the settings menus well, but not as extensively as editing them here.

• Stores all of the created button commands from BotWay. When an admin creates anything new from the "buttons" window in edit mode in BotWay, the data for it can be found here. Every line of a button in buttonData.xml can be modified with the button editor window in edit mode; there is no need to manually change the button data in this file. For a full description of each button and what it does, see the Buttons Page.

  
  Image: ButtonData.xml example. Contains one example of each button type.

• This file stores information on every client that has ever connected to this instance of BotWay including their uuid, vehicle name, manufacturer, client model, client serial number, timestamp of last connection, last route, and last tag read. Shown below is an example of clientData.xml.

  
  Image: clientData.xml example.

• clientTypes.xml: This file stores all acceptable clients that may subscribe to and interact with BotWay. If a particular robot or device is not in this list, it will be ignored by BotWay. Shown below is an example of clientTypes.xml. This example details a list of acceptable robots that may interact with the instance of BotWay run by ResGreenGroup. Robots report their client type in their IdentityReport topic.

Image: clientTypes.xml example.

• This file contains information that initializes each job queue in the Job queue display part of the BotWay dashboard and it contains information on every job currently in each queue. Shown below is an example of jobData.xml. The only parts of jobData.xml that the user should modify are the initialization of queues and stations. DO NOT touch the individual jobs in a queue. Job queues are initialized with a queue name. Stations in the job queue are formed from a return route and a tag ID. The tag ID specifies the tag that is to be turned into a station and the return route specifies the route that a robot will take after it completes a job that was assigned at that station. Job Queue "A" is initialized on line 4, then tag 18 is turned into a station on line 5. Whenever a robot is assigned a job from queue "A" at tag 18 and completes the job, then the robot will be instructed to begin traveling on route 10. Lines 6 and 21 contain information about individual jobs in the queue.

  
  Image: jobData.xml example.

• This is a text document where the BotWay writes all logged information to.
  • routeData.xml: This file contains the route information that robots can travel along. Routes can be made from within BotWay or made directly in routeData.xml. Wherever a route is created, the other location is updated whenever route data is saved. Shown below is an example of routeData.xml. Be mindful of whether the robots accept short form or long form commands; this example has long form commands. To manually create route data in routeData.xml, initialize a route like on line 3 and give it a name. Then, initialize a tag and give it a name like on line 4 or line 9. Initialize a command at each tag for each robot type that will travel the route. This example contains commands for PullBuddy robots only. The command must be surrounded by double quotes or curly braces. Commands in curly braces must be properly formed JSON. BotWay does not check or modify anything inside a command; it just sends the command to the robot and relies on the robot being able to decipher it. This is to maximize interoperability with environments that use BotWay but do not have RGGI Robots.
  
  Image: routeData.xml example.

• This file contains information for customizing staging areas in BotWay. Staging areas are collections of tags that are given special status as places where loading and unloading of LHFs takes place. BotWay can query the tags in a staging area and then direct an incoming robot to the first instance of a tag with the staging state that matched its query. For a full description of each line in stagingData.xml, visit the Dynamic Staging Page. Each station has a position in the dynamic staging status screen on the BotWay dashboard. The dynamic staging status area is broken up into a grid with the position in the top left possessing the coordinates row = 0, column = 0. The cell's position moves to the right if column value is increased and moves down if the row value is increased. The cell ID is a unique string that BotWay pings when the station is queried. The tag assigned to the station is given in the "tag" line. When a robot is trying to enter a staging area, BotWay must be given either a "stagePut" command or a "stageGet" command. "StagePut" commands are for when the robot will be dropping of an LHF and "stageGet" commands are for when the robot will be retrieving an LHF from the staging area. "PutRouteID" specifies which route to switch the robot to when BotWay performs a "stagePut" command and this station is the location that the robot is assigned. "GetRouteID" specifies which route top switch to if BotWay performs a "stageGet" command and this station is where the robot is assigned. Finally, the "status" line specifies what the occupancy state of the station is. This can be changed here, by BotWay performing a "stageSet" command, or by control clicking a cell in the dynamic staging area in the BotWay dashboard.

  

  
  Image: stagingData.xml example.

• This file contains information about every tag currently created in BotWay, whether they are displayed or docked. Shown below is an example of tagData.xml. Every tag is scaled a distance from the top left corner of the map image at x=0.0, y=0.0. Orientation describes where the text labeling the tag is in relation to the dot that represents the tag. Tag 10 is currently being displayed, while tag 11 was previously displayed and has now been docked. Its last location is saved so that when it is taken out of the dock, it returns to the same position.

  
  Image: tagData.xml example.

• This file contains information on any triggers created by an operator in BotWay Editor. Shown below is an example of triggerData.xml. Each trigger in this file has a Boolean condition, device or robot target name, and 4 spots for data modification. These data elements are identical in the .xml file across devices, despite the fact that devices that may be connected to BotWay may be very different. This leads to data elements doing different things depending on the device. For example, if the device is a wireless stacklight, data 1 data 2 and data 3 adjust RGB values and data 4 modifies the pattern that the light flashes. However, if the device is a Lora Gateway switch, data 1 controls on/off status and the other data elements do nothing.

  
  Image: triggerData.xml example.

• This file contains information about every vehicle that has connected to this version of BotWay since it was opened, but not every client ever like in clientData.xml. Shown below is an example of vehicleData.xml. Several pieces of information about the vehicle are shown here, including its uuid, route, tag, current battery voltage, minimum safe battery voltage, vehicle type, status, traffic status, error status, first communication, and last communication. Furthermore, cycle information is available for the vehicle.

  
  Image: vehicleData.xml example.

• This file allows the operator to adjust several main properties about BotWay.

  
  Image: botway.Properties example.

<confirmExit>Yes</confirmExit> enables or disables a confirmation window when closing BotWay.

<mainLoopRate>500</mainLoopRate> Specifies how often in ms BotWay will wait before it analyzes its environment again.

<timeBeaconRate>5000</timeBeaconRate> Specifies how frequently BotWay publishes the current time to the Time topic.

<heartBeatRate>30000</heartBeatRate> BotWay sends a heartbeat at this rate if it does not receive any communications from the robot.

<triggerCheckRate>300</triggerCheckRate> Specifies how frequently in ms to check if any trigger conditions have been fulfilled.

<monitor>true</monitor> Enables or disables the monitor window when logged out.

<monitorLimit>1000</monitorLimit> Sets a cap on how many lines are allowed to be saved in the monitor window, but not the monitor log.

<outputToConsole>false</outputToConsole> Enables or disables printing the monitor log to the computer terminal.

<logStdOutStdErr>false</logStdOutStdErr> Enables BotWay to write any errors or messages that occur at the OS level to the Standard Out and Standard Error ports.

<saveStatusError>false</saveStatusError> Enables or disables saving a robot's status log as a CSV in the data path working folder.

<statusLogDisplayLines>100</statusLogDisplayLines> Sets a cap on how many lines are saved in a robot's status log.

<mainRightSplit>260</mainRightSplit> Indicates the division between the map display and the windows on the right side of BotWay like the job queue and the traffic status display. Updates when BotWay is closed.

<mainLeftSplit>165</mainLeftSplit> Indicates the division between the map display and robot tiles section of BotWay. Updates when BotWay is closed.

<logo>images/Logo.BotWay.png</logo> Specifies the image to display in BotWay as the banner. Can be set in the "settings" window.

<zoomLevel>105</zoomLevel> Specifies magnification level. Can be set from the map display toolbar.

<homePage>https://resgreengroup.com/</homePage> Specifies the URL that is available in the "About BotWay" window.

<helpLink>https://github.com/ResgreenGroup/Botway-Documentation/wiki</helpLink> Specifies the URL that the user is taken to when the "BotWay Wiki" button is selected.

<mapHeaderColor>-16776961</mapHeaderColor> Specifies map header color.

<mapFooterColor>-16777216</mapFooterColor> Specifies map footer color.

<mqtt> initializes the section that specifies the IP and port to connect to the mqtt broker.

Image: Example of autoruns.

• Humans can interact with the robots that are run by BotWay. The interface controlled by this file is one such way. This file works on a computer or a tablet and allows operators to dispense jobs and summon robots without having a full instance of BotWay on their machines. Shown below is an example of jobMonitor.xml. It specifies the mqtt port to connect to, sets up colors for each different status a job can be, and sets up buttons corresponding to commands that can be issued to robots or devices. Each button has an ID, location, route, tag, and title.

  
  Image: jobMonitor.xml example.

• In order to use peripherals in an environment without Wi-Fi, LoRa signals may be used with a LoRa gateway. This .xml file specifies how many lines deep into the monitor to read, which mqtt host to connect to, which physical port to use, and the speed in bits per second between the software side and hardware side of a LoRa gateway. Shown below is an example of loraGateway.xml.

  
  Image: loraGateway.xml example.

• virtualAGV.jar is a virtual robot used for testing. It has properties specified in virtualAGV.xml. Shown below is an example of virtualAGV.xml. It must follow the correct data path and connect to the proper IP host in order to work

  
  Image: virtualAGV.xml example.

• virtualDevice.jar is a virtual pushbutton used for testing. It has 4 buttons that can be used to create button commands in BotWay. virtualDevice.xml specifies which mqtt port to connect to. Shown below is an example of virtualDevice.xml.

  
  Image: virtualDevice.xml example.

• virtualStacklight.jar is a virtual device that is used for testing. It has 3 sections that light up diferent colors based on triggers created in BotWay. virtualStacklight.xml specifies the mqtt port to connect to. Shown below is an example of virtualStacklight.xml.

  
  Image: virtualStacklight.xml example.