SIC framework

The SIC framework can be installed on your machine by making use of Docker.

Requirements

• Java 8+ (e.g. download JDK 19 and follow installation instructions)

• Python 3.8+

• Please make sure that you have at least 8 GBs of RAM on your machine. We also highly recommend a somewhat decent processor.

• It is worth checking if your WiFi adapter's drivers are up-to-date (see e.g. here on how to do that).

Installation

1. Download and install Git and the Git-LFS extension.

   1. On Windows, make sure Git is configured to 'checkout as-is', e.g. by configuring this in the installation (re-install Git if you are unsure about this)

      Open

      

       

   2. Make sure that Git-LFS is enabled (by running git lfs install)

2. Make sure ports 6379, and 8000-8003 can be reached on your machine (i.e. by a robot).

   • On Windows and Mac, this is generally not a problem (though some firewalls like McAfee might interfere, and make sure to allow Docker to work on all networks when requested); on Linux systems your firewall will likely have to be adjusted.

3. Our infrastructure runs in Docker containers, so please check if you meet the relevant system requirements in order to download and install Docker Desktop (Windows/Mac) or Docker Engine (Linux).

   • Using Docker Desktop may cause conflicts with virtualisation tools like VirtualBox and VMWare.

   • If you cannot use Docker Desktop, download and install Docker Toolbox instead.

   • Please read and follow the installation instructions of either tool carefully!

4. Clone the SIC Git repository in a folder under your user directory:

   • git clone https://bitbucket.org/socialroboticshub/docker.git

Running the Infrastructure (locally)

Running with Docker Desktop or Docker Engine

This is the preferred most performant mechanism. SIC will be available on 127.0.0.1 and on the IP-addresses of your machine itself (due to port forwarding).

1. Make sure Docker Desktop or Docker Engine is running (it is by default after installation) and up-to-date .

2. In a terminal, navigate to the location of the cloned docker repository.

   • See the bottom of this page for solutions to common issues.

3. (Optional) Check for and receive updates

   1. use git pull in the docker repository.

4. Here, you can use the docker-compose command to control the infrastructure:

   1. docker-compose up <services>: starts the requested services.

      1. If there were updates, add the --build flag to the command (after up, so docker-compose up --build <services>) when starting the framework (so: only once)

      2. <services> can be one or more of: [face_recognition, people_detection, dialogflow, webserver, emotion_detection, robot_memory, stream_audio, stream_video, wizard, text_to_speech, sentiment_analysis]. If none of these services are needed for your application, use ‘redis’.

      3. Use the -d flag if you do not want live logging output; otherwise kill with CTRL-C or CMD-C.

      4. Launching a service for the first time might take some time (especially for face_recognition, people_detection and emotion_detection). You will be asked permission to share quite some folders on the first launch; accept them all.

   2. docker-compose down: kills all services.

      • You can also add explicit services to kill.

5. See the devices page for more information on connecting devices to the infrastructure. Always make sure the required services are running first.

Running with Docker Toolbox (legacy)

This is a less performant and deprecated, but more compatible mechanism. SIC will be available on 192.168.99.100 (be aware that almost all applications assume 127.0.0.1 by default) and on the IP-addresses of your machine itself (due to port forwarding).

1. Use the ‘Docker Quickstart Terminal’ shortcut to start the basic Docker instance.

   1. After the very first run, a modification is needed to the VM that is created by the toolbox. Open the ‘Oracle VM Virtualbox Manager’ on your machine, right-click on the ‘default’ VM and select ‘Properties’. Then navigate to ‘Network’ > ‘Adapter 1’ > ‘Advanced’ > ‘Port Forwarding’, and use the green plus-icon at the top-right to add rules for port 6379 and ports 11880-11884. After clicking ‘OK’ on all dialogs, shutdown the Docker VM (called ‘default’) by right-clicking on it and selecting ‘Shutdown > Shutdown via ACPI’. Start again at step 1.

2. As soon as you see the '$' prompt, navigate to the location of the docker repository you cloned, e.g. cd /c/Users/Vincent/Git/docker.

3. (Optional) Check for and receive updates

   1. use git pull in the docker repository.

4. Here, you can use the docker-compose command to control the infrastructure:

   1. docker-compose up <services>: starts the requested services.

      1. If there were updates, add the --build flag to the command (after up, so docker-compose up --build <services>) when starting the framework (so: only once)

      2. <services> can be one or more of: [face_recognition, people_detection, dialogflow, webserver, emotion_detection, robot_memory, stream_audio, stream_video, wizard, text_to_speech, sentiment_analysis]. If none of these services are needed for your application, use ‘redis’.

      3. Use the -d flag if you do not want live logging output; otherwise kill with CTRL-C or CMD-C.

      4. Launching a service for the first time might take some time (especially for face_recognition, people_detection and emotion_detection). You will be asked permission to share quite some folders on the first launch; accept them all.

   2. docker-compose down: kills all services.

      • You can also add explicit services to kill.

5. See the devices page for more information on connecting devices to the infrastructure. Always make sure the required services are running first and remember to change 127.0.0.1 to 192.168.99.100 where needed.

Creating an Application

You are now ready to develop and run your application(s). For our Python API, please see the Python connector page. You could also make use of a GOAL Agent; see the EIS connector.

Always make sure to use the correct server IP address in your applications depending on the installation method you chose (so either 127.0.0.1 or 192.168.99.100).

Common issues

• Upon docker-compose up, I get an error (on Windows) saying ‘An attempt was made to access a socket in a way forbidden by its access permissions’

• I see an ‘invalid or corrupt jarfile’ error when trying to run a JAR file or a specific service

• I see a ‘failed to connect to <IP>:6379’ error when trying to run a JAR file or my application

• I get an empty pop-up (Python) or an exception (GOAL) when trying to launch my application

• My Docker containers are taking forever to start and/or I am having performance issues with the services

More issues will be documented on the Frequently Asked Questions page.