Controlcommand()

Robot Skill Controls Overview

The ARC project desktop contains many windows; each window represents a robot skill control. A robot skill control is a small program that runs inside ARC and is typically contributed by a partner. Examples include GPT-3 integrations, vision detection (face, emotion, color, glyph), servo gait and animation controllers, speech recognition, and many more. Each robot skill control provides a specific behavior that increases your robot's capabilities.

Common robot skill controls include Connection, Camera, and Auto Position. Because each robot skill is a separate program, ARC provides a way for robot skills to communicate. That mechanism is the script command ControlCommand(). Using ControlCommand(), an event in one control can instruct another robot skill to perform an action. For example, when the Speech Recognition control detects the phrase "Follow My Face," it can instruct the Camera control to enable face tracking.

Video Example

ARC workspace with multiple robot skill controls
ARC workspace showing multiple robot skill control windows.

The example above demonstrates detecting speech recognition text and using cognitive services to respond to more complex messages. When creating projects, review the manuals for each robot skill you plan to use — each skill documents the commands and variables it exposes.

Detailed script and cognitive services integration example
Detailed example showing speech detection with cognitive services integration.

In the Code

In the earlier example, the Speech Recognition robot skill used the phrase "Follow My Face" to instruct the Camera control to begin face tracking. Below are the implementations for that command in both script and Blockly form.

EZ-Script

EZ-Script code for Follow My Face command
EZ-Script implementation used inside the Speech Recognition control.

Blockly

Blockly blocks for Follow My Face command
Blockly implementation of the same behavior.

What Commands Are Available?

Each robot skill accepts a specific set of ControlCommand() parameters; not every skill supports the same commands. ARC queries each robot skill asking, "What control commands do you accept?" and presents the available commands in several places. Below are the locations where you can find the available ControlCommand() options for robot skills within your project.

Cheat Sheet

Displayed when editing a script, the Cheat Sheet shows available commands for the control.

Cheat Sheet tab showing ControlCommand options
Cheat Sheet inside the script editor listing control commands.

Right-Click Menu

Right-click inside the script editor to view commands relevant to the current control.

Right-click menu showing control commands in script editor
Right-click context menu in the editor that lists ControlCommand options.

Blockly

Blockly provides a utility block that lists ControlCommand() options for the selected control.

Blockly ControlCommand block in Utility category
Blockly's Utility category includes a ControlCommand block.

How It Works

ARC uses a Robot Skill Control Manager that tracks all robot skill controls in the project. The manager assigns each control a unique name when it is added to the project; you can also edit a control's name on its configuration page. The ControlCommand() function requires the name of the target robot skill as its first parameter; subsequent parameters vary depending on the skill and are documented in the cheat sheet, right-click menu, or Blockly block.

Diagram of ARC ControlCommand framework
ARC Control Command framework showing how controls interact through the Robot Skill Control Manager.

ControlCommand() Is Non-Blocking

ControlCommand() does not wait for the destination robot skill to finish executing its action. For example, if your script instructs the Auto Position control to perform the "Wave" action, your script will immediately continue to the next line without waiting for the wave to complete: 

controlCommand("Auto Position", "AutoPositionAction", "Wave");
Audio.SayEZB("I am waving");

EZ-Script

EZ-Script showing non-blocking ControlCommand example
EZ-Script example: instruct Auto Position to wave, then speak immediately.

Blockly

Blockly showing non-blocking ControlCommand example
Blockly equivalent of the non-blocking command sequence.

Because the Auto Position control runs as a separate program, ControlCommand() merely sends a one-way instruction: "Do this." It does not receive an immediate response or block until the action completes.

What If I Want to Wait?

Most ControlCommand() calls are non-blocking. A few commands explicitly support waiting; those will include "Wait" in the parameter name. For example, the Scripting control accepts a ScriptStartWait command that waits for the script to finish. These wait-capable commands are rare.

If a control does not provide a built-in wait command, you can often monitor variables that the control sets to indicate status. For instance, some controls expose a status variable such as $AutoPositionStatus, which is 1 while the action is running and 0 when it finishes. Not every control provides such a variable, but those that do usually list it on their configuration page. You can also view all project variables using the Variable Watcher.

RoboScratch and Blockly include explicit "wait" commands for common tasks (for example, "Wait for Auto Position" or "Wait for Sound"). These commands clearly indicate "(Wait)" in their titles. Below is an example showing how to wait for an Auto Position action to complete before speaking: 

controlCommand("Auto Position", "AutoPositionAction", "Wave");
sleep(500);
while (getVar("$AutoPositionStatus"));
Audio.SayEZB("I finished waving");

EZ-Script

EZ-Script waiting for Auto Position status
EZ-Script example that waits for the Auto Position status variable before proceeding.

Blockly

Blockly waiting for Auto Position status
Blockly equivalent that waits for the Auto Position action to complete.

In the example above, the sleep(500) call provides a short delay to ensure the Auto Position control has time to start the action. The loop that checks getVar("$AutoPositionStatus") waits until the status variable changes (the Auto Position control sets the variable to 0 when it finishes). After the loop exits, the script speaks the confirmation phrase.