Calypso Module 10: Switching Pages

Learning Goal: In this module you will learn how to program more sophisticated behaviors by using more than one page of rules.

Visiting Two Cubes in Sequence

Suppose we want Cozmo to first travel to a red cube and then travel to a blue one:

When we're designing a complex behavior with multiple goals, it's helpful to put the rules for each goal on a separate page, so they don't interfere with each other. We'll start with the rules to visit the red cube. If Cozmo doesn't see a red cube, we'll have him move around randomly until he does. These rules will go on page 1.


The first two rules above are an example of the Default Value idiom: if Cozmo sees a red cube he'll move toward it, and if not, he'll turn randomly until he does.

The third rule introduces a new feature of Calypso: switching to a different page. On page 2 we'll put the rules for visiting the blue cube:


To enter rules on page 2, you need to know how to turn off Novice Mode so you can move to another page.

Turning Off Novice Mode and Moving Between Pages

Calypso starts out in Novice Mode where certain features are disabled to prevent beginners from getting lost. Now it's time to leave Novice Mode so you can write programs with more than one page.

Bring up the Home menu (use the Start button on the controller, the Home key on a PC keyboard, or command-uparrow on a Mac) and go to Settings. Put the cursor on the Novice Mode button and use the left stick or the left/right arrow keys to change the value to Normal Mode. Then press A or hit Enter to confirm.

Once you're in Normal Mode you can move between pages. You can use the bumper (shoulder) buttons on the game controller to do this. Or you can use the Page Up and Page Down buttons on the PC keyboard, or option-uparrow and option-downarrow on the Mac. You can also switch pages by moving the pencil up to the page number and using the left and right stick or left and right arrow keys, or by clicking on the page number with the mouse, which brings up a page menu.

Calypso programs always start on page 1, so if you write rules on other pages, you must include a way to get to them from page 1. That's what the "switch to page" tile is for.

Be Careful of the D-Pad

In Novice Mode the D-Pad is disabled. Once you switch to normal mode, you can use the D-Pad to switch characters so you can program the cubes, but we'll leave that for another day. You can also use the D-Pad to switch between viewing the rules and viewing a state machine diagram. We'll discuss these diagrams later in this module.

For now, if you accidentally press on the D-Pad and change to a different character (shown in the top right corner of the screen), use the D-Pad left/right buttons to return to Cozmo. Similarly, if you press the D-Pad up/down buttons and end up looking at a diagram with circles and arrows, press the button again to return to the rules view.

Running Your First Multi-Page Program

Go ahead and enter the rules shown above for both page 1 and page 2. Then arrange two cubes in front of Cozmo, and press the Start button to run the program. You can change a cube's color by right-clicking on it in the world map. Make one cube blue, then make another cube red.

When Cozmo bumps the red cube he will switch to page 2. Calypso always shows you the currently active page, so the display will automatically switch to show you the page 2 rules.

Finite State Machines

When a program has multiple pages, we can draw a diagram to show how control flows from one page to the next. For example, the program we wrote above is described by this diagram:

Diagrams like this are called finite state machine (FSM) diagrams, and are widely used in computer science. Each page corresponds to a state node, drawn as a circle. Each "switch to page" action corresponds to a state transition, drawn as an arrow. Calypso automatically constructs this diagram for you when you swtich from the rules view to the state machine view. You can do this by pressing the D-Pad up or down buttons, or hitting control-uparrow or control-downarrow on a PC keyboard (Fn-uparrow or Fn-downarrow on a Mac).

When you're runing the program Calypso is in execution mode rather than editor mode. In execution mode you can also switch from the rules view to the finite state machine view. In the rules view, Calypso shows you the currently active page. In the FSM view, Calypso shows you the currently active state by drawing a dashed circle around it:

When Cozmo bumps a cube and switches to page 2, the state machine view reflects this:

Finite state machine diagrams offer a convenient way to reason about how your program will behave. For example, from the diagrams above you can see that the program switches from page 1 to page 2 only in response to a bumped event. And once it reaches page 2, there is no way to get back to page 1.


Let's look at a slightly more complex state machine program with three pages and a loop. The first page sets the context by having Cozmo speak some instructions. We only want to do this at the start of the program, so Cozmo immediately switches to page 2 and never comes back to page 1.

On page 2 Cozmo waits for the user to tap a cube, which he turns red. As soon as he's done that, he switches to page 3 to chase down the cube.


On page 3 Cozmo will move toward the red cube, if he can see it on his world map. While on this page he will ignore any further taps, since there is no rule to respond to them. When he reaches the red cube, he turns off the glow, asks you to tap on another cube, and returns to page 2 to await the next tap.


Remember that you can switch to the state machine view at any time to see the state machine diagram Calypso has created for your program. For the above program, the diagram looks like this:

The above program is an example of an idiom called "Set The Table". When preparing for a meal, we first set the table with everything we'll need; then we can sit down and eat. In computer terminology, setting the table is called initialization. It means we set things up the way we want them to start off; then we get on with what we're going to be doing.

Since programs always start on page 1, that's where well put the rules to "set the table". When we're done, we'll switch to another page to begin the real work. We will never return to page 1. You can see this from the state machine diagram in the flash card: there is an arrow leaving page 1 but no arrows coming into it.

Why Multiple Pages Are Necessary

Let's return to the first program we wrote in this module: the one where Cozmo first travels to a red cube and then to a blue one. Why won't the following rules produce this behavior?

It is a mistake to think of a Calypso program as a serial procedure whose steps are performed in a fixed order. The Second Law tells us that any rule that can run, will run. And the Third Law tells us that when actions conflict, the earliest wins. As long as a red cube is visible, the first rule continues to run. And as long as it can run, its action will override the second rule. So Cozmo will go to the red cube even if it's farther away than the blue one, and then he will get stuck there; he cannot leave as long as it remains red.

What if we told Cozmo to pursue the blue cube after he bumps the red one, using these rules:

Make a prediction: What do you think will happen if you run this program with both red and blue cubes visible?

Go ahead and run the program and see if your prediction is correct before reading further.

This program behaves the same way as the first one: the red pursue rule will always override the blue pursue rule because it precedes it and can always run.

Let's try another solution:

Now the red pursue rule comes last, so if the blue pursue rule can run, its action will win. When it can't run, the red pursue rule's action takes over. The red pursue rule can always run. But sometimes its action is overridden.

Make a prediction: What do you think will happen if you run this program with both red and blue cubes visible?

Go ahead and run the program and see if your prediction is correct before reading further.

The problem with the program above is that the parent rule's "WHEN bumped" condition will only be true briefly. As soon as Cozmo turns away from the red cube he will no longer be bumping it, so the parent rule can no longer run, and thus the blue pursue rule indented below it will no longer be considered. The red pursue rule will immediately take over again.

Now you see why having multiple pages is useful. Putting each pursuit on its own page prevents the rules from interfering with each other.

The Fifth Law of Calypso

The Fifth Law of Calypso says: "On every rule cycle, earlier actions affect later rules." When a rule runs, it "fires" its action if the action is not blocked or overridden. The action might change the color of a cube or the value of a score, or cause Cozmo to grab or drop something. This can affect the ability of later rules to run, or change the object selected by a later rule's WHEN part. So the order in which actions are taken is important.

The Fifth Law tells us that on each rule cycle, actions are taken in the order in which they appear on the page, and each action's effects will be felt by all the rules below it. This is illustrated in the graphic above, where the first rule turns a cube blue, thereby enabling the second rule, which grabs blue things. This in turn enables the third rule, which when Cozmo is holding a blue thing, switches to page 2.

The fifth law applies only within a rule cycle. A page of rules is still not a sequential procedure, because on each cycle only some rules will run, and the Second Law tells us there is no requirement that the first rule on a page must run before the second rule can be considered. The sequentiality of effects applies only within each rule cycle. So rule 1's action could be performed after rule 2's action if rule 1 fires on a later cycle.

The Fifth Law explains an important property of the "switch to page" tile. If a "switch to page" action fires, it takes effect immediately. All the remaining rules on the page are skipped, even if they could run. This is quite useful. Consider the following program:



On page 1, if Cozmo sees a cube he will immediately switch io page 2, ignoring the "say" rule. Thus, as a result of the Fifth Law, he will only say "Show me a cube" if he doesn't already see one.

On page 2, after Cozmo bumps a cube and says "Excuse me", he switches to page 3. Since there are no rules on page 3, Cozmo has nothing to do, so he'll just chill. This is a convenient way to stop a program without leaving execution mode.

Copying State Machines to Other Cubes

In some applications we want all three cubes to behave the same way. If the behavior requires a complex state machine, it is convenient to develop it for just one cube and then copy the final state machine to the other two cubes.

To perform this operation, switch to the state machine view for the cube containing the state machine you want to copy. Then either type control-C or click on the "Copy to other cubes" item in the keyboard help menu. This cube's state machine will be copied to the other two cubes, replacing any existing code there.

Review and Discovery

Do the Module 10 Review and Discovery activity to review what you've learned.

Next Module

In the next module you'll learn ...

Back to Calypso Curriculum overview.

Copyright © 2017 Visionary Machines LLC.