TITLE: FarmBot Use Instructions
AUTHORS: Mia Ruppel, Sven K Nelson, Grace Sidberry, Madison Mitchell, Daniel Kick, Shawn K. Thomas, Katherine E. Guill, Melvin J. Oliver, Jacob D. Washburn

[DESCRIPTION]
This protocol contains instructions for setting up and running the RootBot system.

[STEPS]
SECTION: Software Set Up
1. Installation: Go to https://software.farm.bot/v12/FarmBot-OS/farmbot-os.html#installation for instructions on how to install FarmBot OS
SECTION: Software Set Up
2. Configuration: Go to https://software.farm.bot/v12/FarmBot-OS/farmbot-os/configurator.html for instructions on how to configure FarmBot for specific needs
SECTION: Software Set Up
3. Using the Farm Bot Web app: In the installation and configuration process, you will have created a web app account for FarmBot with credentials that you can use to login into the site
 
SECTION: Building Commands (For first time setup only)
4. Once the FarmBot software is setup and running with your RootBot you will need to create the basic commands needed for the RootBot to pickup, move, image, and replace the soil plates. These commands will be slightly different depending on the customization of your rootbot and require some trial and error to determine the exact X,Y, and Z coordinates based on your machine.
After logging in, there is a main interface showing the manual controls for the robot and a representative image that corresponds to the inside of the machine  
SECTION: Building Commands (For first time setup only)
5. To build the sequence needed to move the plates and take photos of the roots, click on the ‘sequence’ tab on the topmost toolbar pictured with the numbered boxes.    

SECTION: Building Commands (For first time setup only)
6. The choice to add sequences should show up as a plus button  

SECTION: Building Commands (For first time setup only)
7. The sequence of commands for each slot you desire to use in the rootbot will consist of six main steps: 1) a MOVE TO command directing the gantry to the specific slot in the rootbot, 2) a PICK UP PLATE (RELATIVE VERSION) command instructing the RootBot on how to pick up the plate from the slot, 3) a TAKE PHOTO OF ROOTS command moving the plate to the camera and cueing the camera Pi to take the image, 4) a second MOVE TO command moving the plate back to the slot it came from,  5) a RETURN PLATE TO SLOT (RELATIVE VERSION) command putting the plate back in its slot, and 6) and SEND MESSAGE command, which is optional but recommended for monitoring and  troubleshooting purposes. 
 
SECTION: Scheduling Image Times
9. Before starting an experiment, check the connectivity of the FarmBot web app to ensure it is online. You can look at this by clicking on the button that says connectivity
  

SECTION: Scheduling Image Times
9.1. This should bring up a diagram showing the status of your computer’s connection and FarmBot’s connection to the Raspberry Pi in the gantry system. Every part of the chain should have a green checkmark by it meaning it’s connected. if there are connectivity issues, it’ll show up red with an ‘x’  instead.
  

SECTION: Scheduling Image Times
10. After connectivity has been ensured, go back to the manual controls on the main interface. At the beginning of each experiment, the ‘find home’ button needs to be pressed so the gentry has a home point to orient itself. 
  

SECTION: Scheduling Image Times
11. Once the gantry has found the homepoint, it’s time to start scheduling events for when the plates should be picked up and photographed. At the top, there’s a long toolbar with many tabs. The one pictured with a mini calendar is the ‘events’ tab. 
  

SECTION: Scheduling Image Times
12. Pressing on the events tab will bring up a menu with a plus button that when clicked allows the user to add events.
  

SECTION: Scheduling Image Times
13. Once the plus button is clicked, another menu pops up where specifications of the sequence to run on the plates in each slot and when are chosen
  

SECTION: Scheduling Image Times
13.1. Here’s an example of what an event could look like:
  

SECTION: Scheduling Image Times
13.2. Once the time specifications are correct, the event can be saved and will be added to the list of upcoming events that can be seen whenever the events tab is opened.
  

SECTION: Building Commands (For first time setup only)
8. These commands need to be setup for each slot in the RootBot, however once they are setup and saved they can be easily used through the scheduling interface described next.
SECTION: Building Commands (For first time setup only)
7.1. The MOVE TO commands consist of a number values directing the RootBot gantry to a specific location. An example can be seen in the image above but the exact values will very depending on the design of the system. 
SECTION: Building Commands (For first time setup only)
7.2. The PICK UP PLATE (RELATIVE VERSION) command is a custom command consisting of a series of MOVE RELATIVE commands. This command can be created and saved once and then re-used for each new slot you program.
  

SECTION: Building Commands (For first time setup only)
7.3. The TAKE PHOTO OF ROOTS command is another complex command that consists of moving the plate to the photo position, sending and audio signal to the camera Pi, waiting for 18,000 milliseconds to ensure enough time for the image to be taken, and moving the plate back to its slot position.
        

SECTION: Building Commands (For first time setup only)
7.4. The RETURN PLATE TO SLOTE (RELATIVE VERSION) command is the last complex command of the series and consists of several relative move commands bring the plate back to it original location.
  

SECTION: Loading plates into the RootBot
14. Since the soil plats have live emerging roots in them care must be taken to prevent light exposure.  The plates can be kept under a think dark cloth, box or other means while being transported to the RootBot and carefully places into their slot while still covered. 
SECTION: Loading plates into the RootBot
15. It is important that the plates line up exactly with the RootBot Gantry system's hock to ensure successful pickup. We have found that the best way to do this is to run the initial scheduled pickup and photo of the roots right after placing them in the RootBot and monitor/guide the first pickup of each plate.  This can be done by opening the RootBot door and making sure the hocks line up at the beginning of each pickup, then closing the door quickly before the plate comes out of the slot to minimize any light exposure.  Once each plate has been successfully picked up once the RootBot will place it back in the exact spot so that it is picked up correctly the next time automatically.