Basic Tutorial

This is the basic tutorial guide for building a simple delivery program. These steps will have you write, test, and debug throughout the tutorial.

Step 1: Create A New Program

First, create a new program in the Program Editor:

1. Navigate to the Program Editor app by either clicking the Program Editor icon on the Cloud Portal homepage or by using the top navigation bar. Note: Make sure the correct site name is listed in the top navigation bar.
2. Click on the + button on the left panel to add a new program.
3. In the Program Name, name your new program (i.e. "Simple Delivery").
4. Enter a new or existing namespace for the program. If the entered value does not match any existing namespaces, a new one will automatically be created.
5. Enter the following preliminary code:

   DISPLAY "Starting a delivery!"
   SLEEP 3
   GOTO "Front Desk"
   DOCK
   • Each line of code represents a command.
   • This block of code utilizes the DISPLAY, SLEEP, GOTO, and DOCK commands.
   • For more information on these commands, view the Command Library.
6. Assign a Program Icon on the left panel. Note: An icon must be assigned (even if it is "empty") for the program to successfully save!
7. Enter a change note describing your changes at the bottom.
8. Click Save.

The program should now be successfully saved on the Program Editor's cloud.

Step 2: Run the Program

Now that the program has been created, try running the program with the robot!

1. Navigate to the Robot Control app.
2. Click on the Sync button on the right to ensure that the robot can read the latest program information from the cloud.
3. After waiting a few seconds for syncing to complete, enter the program's name. Syntax for program names is "Namespace"/"Program Name". For example, a program named "Simple Delivery" under the BrandonKing namespace is listed as BrandonKing/Simple Delivery.
4. Click the Queue Program button.
5. Observe the robot's behavior. Did it run the program? If so, did it perform the expected commands?

Everytime a program is saved and updated, repeat these steps to view the program's output and fix bugs as necessary.

Step 3: Pickup Location

Now that the first draft of the program successfully displays a message, navigates to the Front Desk, then docks, we will add more commands to the first delivery navigation destination, or the pickup location.

1. Go back to the Program Editor.
2. Navigate to your program to view the Code Editor.
3. After the GOTO command line and before the DOCK command line, enter the following lines of code:

   PLAY_SOUND "shimmy"
   SHIMMY
   OPEN_LID
   DISPLAY_CONFIRM "Please insert an item to deliver.", "Send", -1
   DISPLAY "Delivering item now!"
   CLOSE_LID
   PLAY_SOUND "R5_Thank you 2"
   SLEEP 2
   • This code block uses new commands - PLAY_SOUND, SHIMMY, OPEN_LID, DISPLAY_CONFIRM, and CLOSE_LID.
   • PLAY_SOUND is a sound command that plays an audio file (in this case, "shimmy" and "R5_Thank you 2") by file name.
   • SHIMMY is a movement command that causes the robot to "dance."
   • OPEN_LID is a hardware command that fully opens the robot's lid.
   • DISPLAY_CONFIRM is a display command that shows a message and a confirmation button.
   • CLOSE_LID is a hardware command that closes the robot's lid.
4. Enter program change notes, then click Save.

Repeat Step 2: Run the Program to check if the program updates were successful. With these changes, once at the first delivery destination, the robot will now play a sound, do a dance, open its lid, display a confirmation message, close its lid, play a "thank you" sound, then finally, go back to the dock.

note

If there were any issues during this code update, check if:

• all commands are spelled correctly
• all file names and display message strings are wrapped in quotations ("")
• the robot was properly synced

These are common errors that would prevent the program from correctly running. If these troubleshooting tips do not work, ask your instructor for more assistance.

Once the robot is able to successfully execute all the desired commands at the pickup location, we will now add commands for the drop-off location.

Step 4: Drop-off Location

At the drop-off location, we want the robot to get to the location, open the lid, display a confirmation message, then close the lid, similar to the previous section.

1. In your program's Code Editor, enter the following code after the SLEEP 2 line but before the DOCK line:

   # Delivery drop-off section
   GOTO "800"
   PLAY_SOUND "R5_Drive By Greeting"
   OPEN_LID
   DISPLAY_CONFIRM "Please take your item", "Okay", 60
   CLOSE_LID
   
   DISPLAY "Delivery complete!"
   SLEEP 2
   DISPLAY "Thank you, have a nice day!"
   PLAY_SOUND "shimmy"
   SHIMMY
   
   # Dock section
   DISPLAY "Going back to dock!"
   SLEEP 3
   • No new commands are added here, but comment lines (#) are now used to document the code.

2. Enter program change notes, then click Save.

3. Test out this new addition of code by running the program.

Did the robot successfully go to the pickup location, the drop-off location, then dock, with all of the small command steps in between? If so, congratulations! That is the basis of a robot's general delivery program. Robots use this simple logic to make countless daily deliveries in various hotels and hospitals globally. Let's review what the full program looks like right now:

/Simple Delivery

# Begin DeliveryDISPLAY "Starting a delivery!"SLEEP 3# Delivery pickup sectionGOTO "Front Desk"PLAY_SOUND "shimmy"SHIMMYOPEN_LIDDISPLAY_CONFIRM "Please insert an item to deliver.", "Send", -1DISPLAY "Delivering item now!"CLOSE_LIDPLAY_SOUND "R5_Thank you 2"SLEEP 2# Delivery drop-off sectionGOTO "800"PLAY_SOUND "R5_Drive By Greeting"OPEN_LIDDISPLAY_CONFIRM "Please take your item.", "Okay", 60CLOSE_LIDDISPLAY "Delivery complete!"SLEEP 2DISPLAY "Thank you, have a nice day!"PLAY_SOUND "shimmy"SHIMMY# Dock sectionDISPLAY "Going back to dock!"SLEEP 3DOCK

You might have small variations from this example code - nothing to worry about! Here, all of the different program sections are annotated with comment lines. Additionally, extra line breaks do not affect the code. As long as your version of the program works similarly, there should be no issues.

Now that we have a solid foundation for the base delivery, let's add some more advanced features to the program.

Step 5: Event Handlers

SaviScript includes interesting features called event handlers. Some commands have unique events that occur when certain conditions are met. These events can be checked and utilized to introduce more options within the program, allowing for more decision branches. We will focus on a simple example of this: DISPLAY_CONFIRM's event handlers.

Currently in our program, the first instance of DISPLAY_CONFIRM is set to not timeout ("-1"), but the second instance of this command does timeout after 60 seconds. What will happen after 60 seconds? Since there are no event handlers specified, after 60 seconds, the dialog box will timeout, and the program will proceed to the next line of code.

If we wanted to instead have a timeout occurence result in a different output, we can define the event handler logic. In the Code Editor, enter the following code at the top of your program:

# Event handlers are defined at the top of the program
ON "confirm_timeout" {
    DISPLAY "No items to deliver..."
    SLEEP 3
    CLOSE_LID
    DISPLAY "Returning to dock."
    SLEEP 3
    DOCK
    CANCEL_ALL
}

then click Save.

Upon running the program again, try letting the second DISPLAY_CONFIRM command timeout. After 60 seconds, the event handler should happen, sending the robot back to the dock and canceling the rest of the program.

What happens when we have multiple events that meet the handler's criteria? Currently, we have the first DISPLAY_CONFIRM never timeout. If we changed the timeout value for that to anything other than "-1", this newly added event handler will occur on both timeout instances, which would not quite make sense with the DISPLAY messages we set. This is a slightly more complex logic sequence, so we will try using multiple programs to handle this.

Step 6: Sub-Programs

Sub-programs are useful when multiple event handlers are needed within a parent program. They can also be used to break up the parent program into simpler sections once code becomes more complex. For our program, we will break up each DISPLAY_CONFIRM command into separate sub-programs that we will RUN from the parent program (Simple Delivery).

1. Create a new program from the Program Editor by clicking the + button.

2. Name the program "Pickup Confirm" under the same namespace as the parent program.

3. Enter the following code:

   /Pickup Confirm

   ON "confirm_timeout" {
   DISPLAY "No items to deliver..."
   SLEEP 3
   CLOSE_LID
   DISPLAY "Returning to dock."
   SLEEP 3
   DOCK
   CANCEL_ALL
   }
   
   DISPLAY_CONFIRM "Please insert an item to deliver.", "Send", 10

   Note: To cut down on idle time waiting during testing, the code is adjusted to timeout in 10 seconds, rather than the previous 60 seconds.

4. Set a program icon, describe program changes in the notes, and click Save.

5. Repeat steps 6-1 to 6-4 above to create another program named "Drop-off Confirm" with the following code:

   /Drop-off Confirm

   ON "confirm_timeout" {
   DISPLAY "Delivery failed..."
   SLEEP 3
   CLOSE_LID
   DISPLAY "Returning to pickup location."
   SLEEP 3
   GOTO "Front Desk"
   DISPLAY "Delivery failed. Item will be returned..."
   OPEN_LID
   DISPLAY_CONFIRM "Please take item.", "Okay", -1
   CLOSE_LID
   DISPLAY "Returning to dock."
   SLEEP 3
   DOCK
   CANCEL_ALL
   }
   
   DISPLAY_CONFIRM "Please take your item.", "Okay", 10

6. Once both sub-programs are successfully created, navigate back to the parent "Simple Delivery" program and modify the program to instead use RUN commands and remove the existing event handler:

   /Simple Delivery

   # Begin DeliveryDISPLAY "Starting a delivery!"SLEEP 3# Delivery pickup sectionGOTO "Front Desk"PLAY_SOUND "shimmy"SHIMMYOPEN_LIDRUN "BrandonKing/Pickup Confirm"DISPLAY "Delivering item now!"CLOSE_LIDPLAY_SOUND "R5_Thank you 2"SLEEP 2# Delivery drop-off sectionGOTO "800"PLAY_SOUND "R5_Drive By Greeting"OPEN_LIDRUN "BrandonKing/Drop-off Confirm"CLOSE_LIDDISPLAY "Delivery complete!"SLEEP 2DISPLAY "Thank you, have a nice day!"PLAY_SOUND "shimmy"SHIMMY# Dock sectionDISPLAY "Going back to dock!"SLEEP 3DOCK

7. Click Save and run the parent program.

Using sub-programs, the robot is able to now seamlessly interact with the user based on various event output conditions. If neither DISPLAY_CONFIRM command results in a timeout, the program will behave exactly the same as the original basic delivery program. However, now the robot can adapt to timeouts and return back to the dock (if timeout occurred at the pickup location) or return back to the pickup location and return the delivery item (if timeout occurred at the drop-off location).

Step 7: Additional Deliveries

The final addition to our program will use the DISPLAY_CHOICE command to allow users to select additional deliveries after the basic delivery program is completed. DISPLAY_CHOICE is a display command that provides users with a list of options to choose.

We will use the sub-program method to create a "More Deliveries Choice" program:

/More Deliveries Choice

# Additional deliveriesON "choice_made" AS C WHERE C.name == "Yes" {    DISPLAY "Awesome, let's do another delivery!"    SLEEP 3    QUEUE_PROGRAM "BrandonKing/Simple Delivery"}ON "choice_made" AS C WHERE C.name == "No" {    DISPLAY "Returning to dock!"    SLEEP 3    DOCK    CANCEL_ALL}DISPLAY_CHOICE {    "title": "Any other deliveries?"    "choices": [{        "name": "Yes"        "title": "Yes"        "icon": "CheckCircle"        },{        "name": "No"        "title": "No"        "icon": "cancel2"            }]}

This sub-program utilizes the QUEUE_PROGRAM command, which is a behavior command that runs the specified program after all commands in the current program are executed. There are two DISPLAY_CHOICE options, "Yes" and "No", with corresponding names and icons for each choice option, and each have corresponding event handlers that will execute different commands for each. "Yes" will queue the parent program again, while "No" returns the robot back to the dock and ends all programs.

The parent program will also be modified again:

/Simple Delivery

# Begin DeliveryDISPLAY "Starting a delivery!"SLEEP 3# Delivery pickup sectionGOTO "Front Desk"PLAY_SOUND "shimmy"SHIMMYOPEN_LIDRUN "BrandonKing/Pickup Confirm"DISPLAY "Delivering item now!"CLOSE_LIDPLAY_SOUND "R5_Thank you 2"SLEEP 2# Delivery drop-off sectionGOTO "800"PLAY_SOUND "R5_Drive By Greeting"OPEN_LIDRUN "BrandonKing/Drop-off Confirm"CLOSE_LIDDISPLAY "Delivery complete!"SLEEP 2DISPLAY "Thank you, have a nice day!"PLAY_SOUND "shimmy"SHIMMYRUN "BrandonKing/More Deliveries Check"

The entire "Dock section" will now be replaced by the RUN command, as the docking sequence is now covered by the "No" choice once all deliveries are finished.

Test the full "Simple Delivery" program to check if all parts of the program's logic work as intended. The robot will run deliveries until there are no deliveries left to complete, at which point it will finally return to the dock.

Further Reading

Now that you have completed a full basic delivery program, check out other resources on SaviScript Commands and learn more about other Cloud Portal apps.