This guide introduces the main components and concepts of this API and provides some code samples that can be used as a starting point.

Requirements

1. The Python-SIC connector requires Python 3 (with tkinter enabled).

   1. Make sure Python can compile native extensions (e.g. for Windows see https://www.scivision.dev/python-windows-visual-c-14-required).

   2. You can use a Python editor of your choice (Pycharm for example).

2. The Python skeleton project itself can be found in the ‘python’ folder at https://bitbucket.org/socialroboticshub/connectors. It is recommended to simply download this repository or even fork it directly (which you can do using the + button at the top-left of the page). Once you have your download or cloned fork, make sure the required dependencies are installed

   1. It is possible to install all of the dependencies by running the command: pip install -r requirements.txt in the folder.

Table of Contents

Abstract SIC Connector

Introduction

The first main component is the AbstractSICConnector class. It enables you to send action commands to the robot and receive data generated by either the robot or the SIC itself.

• action commands

  • use the methods available in the SIC connector

  • allow you to create your application using the SIC framework

• data generated

  • contains events (e.g.: when a button is pressed LeftBumperPressed or when an action is finished WakeUpDone)

  • the results of certain actions (e.g.: a recognised intent after a speech recognition attempt)

Input

• IP address of the used SIC server (usually localhost)

Usage

The AbstractSICConnector class is abstract, meaning that it itself does not do anything with the incoming data. To process the incoming data you can implement your own concrete SIC Connector class by inheriting the AbstractSICConnector class and overriding the empty event handlers.

Example

In the below MyConnector example, you see that it uses the AbstractSICConnectorclass as a parent, inheriting all its methods. Two things have been added:

...

You will find extensive documentation for each available action and on_* trigger on

Basic SIC Connector

Introduction

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.

• callback functions

  • called when the action is finished or a result becomes available

  • e.g.:

    • for device actions (e.g.: wake_up, say or set_eye_color), the callback function is called only once

    • for touch events (e.g. MiddleTactilTouched), the callback function is called every time the event becomes available

    • the result of vision operations (e.g. on_face_recognized(identifier)), the callback function is called every time the result becomes available

Example

import threading
from social_interaction_cloud.basic_connector import BasicSICConnector
from time import sleep


class Example:

    def __init__(self, server_ip):
        self.sic = BasicSICConnector(server_ip)

        self.awake_lock = threading.Event()

    def run(self):
        # active Social Interaction Cloud connection
        self.sic.start()

        # set language to English
        self.sic.set_language('en-US')

        # stand up and wait until this action is done (whenever the callback function self.awake is called)
        self.sic.wake_up(self.awake)
        self.awake_lock.wait()  # see https://docs.python.org/3/library/threading.html#event-objects

        self.sic.say_animated('You can tickle me by touching my head.')
        # Execute that_tickles call each time the middle tactile is touched
        self.sic.subscribe_touch_listener('MiddleTactilTouched', self.that_tickles)

        # You have 10 seconds to tickle the robot
        sleep(10)
        
        # Unsubscribe the listener if you don't need it anymore.
        self.sic.unsubscribe_touch_listener('MiddleTactilTouched')

        # Go to rest mode
        self.sic.rest()

        # close the Social Interaction Cloud connection
        self.sic.stop()

    def awake(self):
        """Callback function for wake_up action. Called only once.
        It lifts the lock, making the program continue from self.awake_lock.wait()"""

        self.awake_lock.set()

    def that_tickles(self):
        """Callback function for touch listener. Everytime the MiddleTactilTouched event is generated, this
         callback function is called, making the robot say 'That tickles!'"""
        
        self.sic.say_animated('That tickles!')


example = Example('127.0.0.1')
example.run()

...

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

Introduction

To help define behaviors, the Python API offers some additional facilities related to actions. An Action allows you to prepare an action and (re)use it when necessary.

Usage

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.

...

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 Interaction Flows

Implementing a social interaction flow will go more efficiently if your code could have a similar structure to a graph/flowchart.Each step in the interaction is going from one state to another, based on the input from an end-user and the goals of the robot.

...

• define what triggers a transition (e.g.: a button press)

• define prerequisites of a state transition (e.g.: to get from the sleep to the awake state, a robot first needs to stand up)

Usage

In order to facilitate the implementation of state machines, the library pytransitions ca be used. It is “a lightweight, object-oriented finite state machine implementation in Python with many extensions”. Read their guide to learn more.

Example

Let’s look at an example of how to use it together with the SIC Python API. The example is comprised of a basic interaction flow. In this interaction flow, the robot starts by being asleep, wakes up, introduces itself and gets acquainted with the person and then says goodbye.

...