/
Getting started

Getting started

Owned by Ligthart, M.E.U. (Mike)
Last updated: Mar 28, 2025 by Karen Chiang
6 min read

The Social Interaction Cloud (SIC) is a native python framework. It can be used via the social-interaction-cloud python package. The framework uses Redis for message brokering. To help you get started you can clone the sic_applications repository. Below you will find the basic instructions for cloning the repository and setting up the Social Interaction Cloud.

General prerequisites

  • Python >= 3.10, <= 3.12

Latest version of SIC

  • 2.0.32

If you want to upgrade to the latest version, run this command in your venv:

pip install social-interaction-cloud --upgrade

Install

Below you can find the installation instructions for Linux, MacOS, and Windows.

In these instructions we will perform git operations through a basic terminal and use Python's standard venv to create a virtual environment. If you're more familiar with other tools like PyCharm, VisualStudio, or Conda, feel free to use them instead. It is advised not to mix venvs. If you are going to use Python’s standard venv, do not mix it with your conda environment, as it might lead to unexpected behavior.

You can watch this video as well (Windows): Tutorial 1: Getting Started

Be aware that the Windows commands we use here are for Git Bash. If you are using the Windows Command Prompt, the slashes are backslashes \ .

Instructions

# Install git/redis/system dependencies for pyaudio sudo apt update sudo apt install git redis portaudio19-dev python3-pyaudio # Clone the sic_applications repo git clone https://github.com/Social-AI-VU/sic_applications.git # Create and activate virtual environment within the sic_applications folder cd sic_applications python -m venv venv_sic source venv_sic/bin/activate # Install social-interaction-cloud pip install social-interaction-cloud # Recommended on linux & mac: install libturbo-jpeg sudo apt-get install -y libturbojpeg pip install -U git+https://github.com/lilohuang/PyTurboJPEG.git
# Install git/redis/system dependencies for pyaudio brew install git redis portaudio # Clone the sic_applications repo git clone https://github.com/Social-AI-VU/sic_applications.git # Create and activate virtual environment within the sic_applications folder cd sic_applications python -m venv venv_sic source venv_sic/bin/activate # Install social-interaction-cloud pip install social-interaction-cloud # Recommended on linux & mac: install libturbo-jpeg brew install jpeg-turbo pip install -U git+https://github.com/lilohuang/PyTurboJPEG.git

For Windows users, the installation is not as as straightforward as for Ubuntu or Mac users, but it’s also fairly simple.

  1. Go to the official Git Download for Windows and download the latest version of the installer. A file named Git-2.xx.xx-64-bit.exe should be downloaded.

  2. Run the downloaded installer. You can keep the default settings by clicking Next through each step, and then click Install at the end.

  3. After installation, open Git Bash and run the following commands:

# Clone the sic_applications repo git clone https://github.com/Social-AI-VU/sic_applications.git # Create and activate virtual environment within the sic_applications folder cd sic_applications python -m venv venv_sic source venv_sic/Scripts/activate # In a Command Prompt, use venv_sic\Scripts\activate # Install social-interaction-cloud pip install social-interaction-cloud

Note: When a venv is activated, you should see parentheses with its name at the beginning of your terminal prompt, like (venv_sic) C:\Users\YourUsername\sic_applications>

Optional Install libturbo-jpeg

  1. Download and run installer from https://sourceforge.net/projects/libjpeg-turbo/files/2.1.5.1/libjpeg-turbo-2.1.5.1-gcc64.exe/download

  2. Add the bin folder where you installed libjpeg-turb to the PATH environment variable (see e.g. How to Edit the PATH Environment Variable on Windows 11 & 10 for how to do this)

  3. Make sure that the dll is called turbojpeg.dll (e.g. by copying and renaming libturbojpeg.dll)

  4. Pip Install PyTurboJPEG via

    pip install -U git+https://github.com/lilohuang/PyTurboJPEG.git

If you somehow can’t make git clone work, just go to the repository sic_applications , click the Code button. A drop down menu will appear. In this menu, you will see an option that says Download ZIP. Click on it.

Running your first application

Running any application consists of two (or three) steps:

  1. Start Redis

  2. (Optional) Start a service, such as face detection

  3. Run your program

We will cover two examples: running an application without a service (step 1 and 3) and with a service (step 1, 2, and 3).

Example 1: Running an application without a service

For this example we will show your computer’s camera output on your screen. The code for this example is available in the sic_applications/demos folder and called demo_desktop_camera.py. An equivalent example showing Nao’s camera output can be found here Display an image from the robot

Step 1: starting Redis on your laptop

To enable communication between all your devices, we have to start Redis server. Make sure Redis is always up and running when you run any demos.

# Navigate to the repo where you cloned the sic_applications cd sic_applications # Start the Redis server redis-server conf/redis/redis.conf

Troubleshoot (Could not create server TCP listening socket *:6379: bind: Address already in use)

For Ubuntu/Debian users, if you encounter the error Could not create server TCP listening socket *:6379: bind: Address already in use., please use the following command to stop the Redis server first

sudo systemctl stop redis-server.service

And, if you wish to prevent Redis server from starting automatically at boot, you can run

sudo systemctl disable redis-server.service

If you still can’t kill Redis server, you can use ps aux | grep redis-server command to find the PID (process ID) of the Redis server. And, terminate the process using kill PID

 

For macOS users, the process should be similar; just find the PID of the Redis server and kill the process:

lsof -i tcp:6379

And kill the pid shown:

kill -9 pid

The commands below are for the Git Bash:

# Navigate to the repo where you cloned the sic_applications cd sic_applications # Start the Redis server cd conf/redis redis-server.exe redis.conf

Troubleshoot (Could not create server TCP listening socket *:6379: bind; Failed listening on port 6379 (TCP), aborting.)

It means that port 6379 is already in use, probably by a previous instance of the Redis server that is still running in the background. You can either leave it as it is because it means that there is already a Redis server running, or if you really want to kill it and restart the server, find the PID and kill the program.

Step 3: running an application

To start the camera demo from the terminal, use the following commands.

# Activate the same virtual environment where you pip installed # social-interaction-cloud in the installation steps source venv_sic/bin/activate # Go to sic_applications and the demo script cd sic_applications/demos/desktop python demo_desktop_camera.py
# Activate the same virtual environment where you pip installed # social-interaction-cloud in the installation steps source venv_sic/Scripts/activate # Go to sic_applications and the demo script cd sic_applications/demos/desktop python demo_desktop_camera.py

If all goes well, a display should pop up showing you the camera output from your webcam!

And you should get the following output:

[SICComponentManager 145.108.228.128]: INFO: Manager on device 145.108.228.128 starting [SICComponentManager 145.108.228.128]: INFO: Started component manager on ip "145.108.228.128" with components: [SICComponentManager 145.108.228.128]: INFO: - DesktopMicrophoneSensor [SICComponentManager 145.108.228.128]: INFO: - DesktopCameraSensor [SICComponentManager 145.108.228.128]: INFO: - DesktopSpeakersActuator [DesktopCameraSensor 145.108.228.128]: INFO: Starting sensor DesktopCameraSensor [DesktopCameraSensor 145.108.228.128]: INFO: Started component DesktopCameraSensor

Troubleshoot

  • You might get a warning to allow the python script to access your camera. Click allow, and start demo_desktop_camera.py again.

 

  • If you have a problem connecting to the Redis server, even after running it in another terminal, it could be that your firewall is blocking communication from the robot. Please turn off your firewall to allow the robot to connect to the Redis server.

 

Example 2: running an application with a service

In this example we will use the face detection service to draw a bounding box around a face that is detected in your laptop camera feed. It uses the sic_applications/demos demo_desktop_camera_facedetection.py.

The Available services page provides more details about which services are available, how to use them, and how to extend them.

Step 1: starting Redis on your laptop

It is the same as in example 1.

Step 2: run the service

Services might need additional dependencies installed before being able to run them. You can install them with the appropriate service tag. For example,

pip install --upgrade social-interaction-cloud[face-detection,dialogflow]

A service can easily be run by opening a new terminal and calling the run-service command, for example run-face-detectionor run-dialogflow. See the Available services page for more info about the dependencies and run commands for each service.

Note: the --upgrade ensures the new dependencies are installed if you already have previously installed the social interaction cloud.

For our example we will start the face-detection service.

# Activate the same virtual environment where you pip installed # social-interaction-cloud in the installation steps (e.g. in sic-applications) source venv_sic/bin/activate # First, install all the extra dependencies that this service depends on. pip install --upgrade social-interaction-cloud[face-detection] # Run the face-detection server run-face-detection
# Activate the same virtual environment where you pip installed the # social interaction cloud in the installation steps (e.g. in sic-applications) source venv_sic/Scripts/activate # First, install all the extra dependencies that this service depends on. pip install --upgrade social-interaction-cloud[face-detection] # Run the face-detection server run-face-detection

If successful, you should get the following output:

[SICComponentManager 192.168.2.6]: INFO: Manager on device 192.168.2.6 starting [SICComponentManager 192.168.2.6]: INFO: Started component manager on ip "192.168.2.6" with components: [SICComponentManager 192.168.2.6]: INFO: - FaceDetectionComponent

Step 3: run the application

Run the demo file demo_desktop_camera_facedetection.py.

# Activate the virtual environment in sic_applications source venv_sic/bin/activate # Go to sic_applications and the demo script cd demos/desktop python demo_desktop_camera_facedetection.py
# Activate the virtual environment in sic_applications source venv_sic/Scripts/activate # Go to sic_applications and the demo script cd demos/desktop python demo_desktop_camera_facedetection.py

If all goes well, a display should pop up showing a bounding box around the detected face! If the image appears upside down, go to line 34 in demo_desktop_camera_facedetection.py and change the flip parameter to -1.

And that's it! 🎉

Go have some fun with robots, see Getting started with the Nao robot | Starting SIC on the Robot (NAOv6) and Getting started with Franka Emika Research 3.

Related content