Once you connected a robot to the the Social Interaction Cloud (SIC), you want to make it do something. One of the available APIs connectors is the Python API, which enables you to implement and run a wide range of robot behaviors. This brief guide introduces the main components and concepts of this API and provides some code samples that can be used as a starting point.

Abstract SIC Connector

The first main component is the AbstractSICConnector class. It requires the IP address of the SIC and the type of robot you have connected (‘nao’ or ‘pepper’). It sets up the connection to the SIC and enables you to send action commands to the robot and receive data generated by either the robot or the SIC itself. The data contains events (e.g. when a button is pressed ‘LeftBumperPressed' or when an action is finished 'WakeUpDone’) or the results of certain actions (e.g. a recognized intent after a speech recognition attempt).

...

The sleep statements avoid the program to stop before all the events are generated. See what happens when you remove the sleep statements. Most of the time you do not know how long you have to wait for an action to finish. Therefore, sleep statements are not the way to go. Ideally, you want the robot to wait until it has received the necessary data and select it’s next action based on the available data.

Basic SIC Connector

The python API also provides its own concrete implementation of the AbstractSICConnector class, called the BasicSICConnector. It allows you to register callback functions for each action you send. Whenever the action is finished or a result becomes available that callback function is called. For robot actions, e.g. wake_up(), say() or set_eye_color(), a callback function is only called once. You can also register callback functions that listen to touch events (e.g. MiddleTactilTouched) or the result of vision operations (e.g. on_face_recognized(identifier)). These callback functions are called each time that event or result becomes available.

...

A different callback function is that_tickles(). It is subscribed to the MiddleTactilTouched event. Whenever the program is running, that_tickles()is called each time the middle head sensor is touched.

Action, ActionFactory, and ActionRunner

To help define the robot behaviors the python API offers the action package. An Action allows you to prepare an action and (re)use it when necessary. It requires a reference to a method of BasicSICConnector and the input arguments for that method. Optionally you can give it a callback function and a threading.Event() object as lock. Note that you have to explicitly state callback=… and lock=… to do so.

...

sic = BasicSICConnector(server_ip)
action_runner = ActionRunner(sic)
action_runner.run_waiting_action('say', 'Hello, Action Runner!',
                                 additional_callback=hello_action_runner_callback)
# run_waiting_action('say', ...) waits to finish talking before continuing

def hello_action_runner_callback():
  print('Hello Action Runner Done')

# The following actions will run in parallel.
action_runner.load_waiting_action('wake_up')
action_runner.load_waiting_action('set_eye_color', 'green')
action_runner.load_waiting_action('say', 'I am standing up now')
action_runner.run_loaded_actions()  # If you want to keep an action sequence for reuse, add clear=False as input.

action_runner.run_action('say', 'I will start sitting down as I say this. Because I am not a waiting action')
action_runner.run_action('set_eye_color', 'white')
action_runner.run_waiting_action('rest')

State Machines with pytransitions

Implementing a human-robot interaction flow will go more efficiently if your code could have a similar structure. Most interactions can be structured as graph. Each step in the interaction is going from one state to another, based on the input from the user and the goals of the robot. To structure your code using state and state transitions you can use the state machine design pattern. The most important component of state machines are the state transitions. You define what triggers a transition, for example a button press. You can define prerequisites of a state transition. For example, to get from the sleep to the awake state, the robot first needs to stand up. For more information about the state machine pattern you can read this Medium article or this paper.

...