Skip to content

Running with Docker

This project can be run using Docker and Docker Compose for easy deployment and development. Install Docker and Docker Compose if not already available.

IMPORTANT: Make sure to also clone the ric-messages and mapdesc_msgs git submodules located in src folder with:

git submodule update --init

Quick Start

  1. Clone the repository and navigate to the project directory
  2. Install Docker and Docker Compose for your operating system
  3. Clone the required git submodules (see above)
  4. Start the software stack using Docker Compose:
docker compose up
  1. Also start the dependencies you might need such as: ros_chat, tour_persistence_node and emotion
  2. Send ROS2 messages according to the usage below
  3. Stop the server either by aborting using CTRL-C or docker compose stop if started detached -d

Note: The ROS2 node makes use of rmw_zenoh for ROS2 communication. Use the provided zenoh_router for this purpose.

Development Setup

For development, you can run the HelloRIC UI Communication server directly using Docker:

docker compose up -d

This will build and run the helloric_ui_com service, which provides: - WebSocket endpoint at /ws for real-time communication - RESTful HTTP endpoints for tour management - Integration with ROS2 ecosystem

Services

The Docker Compose configuration defines the main communication service.

The helloric_ui_com Service

This service runs the FastAPI server that bridges web interfaces with ROS2 nodes.

  • Provides WebSocket communication for real-time audio and emotion data
  • Offers RESTful HTTP API for tour management operations
  • Integrates with ROS2 services for chat, tour management, and microphone control
  • Exposes port 7000 for web client connections

Environment Variables

Variable Description Default Value
PYTHONUNBUFFERED Prevents Python from buffering stdout and stderr 1
RMW_IMPLEMENTATION ROS2 middleware implementation rmw_zenoh_cpp
ROS_AUTOMATIC_DISCOVERY_RANGE Disables automatic discovery in ROS2 OFF
ZENOH_ROUTER_CHECK_ATTEMPTS Number of attempts to check for Zenoh router. 0 means wait indefinitely 0
ZENOH_CONFIG_OVERRIDE Zenoh configuration override, see rmw_zenoh mode="client";connect/endpoints=["tcp/host.docker.internal:7447"]

Important: The node uses rmw_zenoh for ROS2 communication. Use the provided zenoh_router for this purpose.

ROS2 Node Interface

The HelloRIC UI Communication node provides the following ROS2 interfaces:

  • /play_audio topic subscriber for sending audio to the emotion UI to be played. Check out ric_messages/msg/PlayAudio for exact interface type.
  • /microphone/set_enabled service for toggling the microphone state on the emotion UI. Check out std_srvs/srv/SetBool for exact interface type.

The node also communicates with other nodes such as ros_chat and tour_persistence_node.

Manual Setup

For manual installation and setup, follow the relevant documentation on: - ROS2 documentation for building packages and running nodes - FastAPI documentation for the web server setup

Note: The recommended way to build the ROS2 node as of writing is using colcon.

Usage

WebSocket Communication

Connect to the WebSocket endpoint for real-time communication:

const ws = new WebSocket('ws://localhost:7000/ws');

// Send audio data
ws.send(audioByteArray);

// Send JSON commands
ws.send(JSON.stringify({
    "service": "clear_history"
}));

// Receive audio and emotion data
ws.onmessage = function(event) {
    if (typeof event.data === 'string') {
        const data = JSON.parse(event.data);
        // Handle emotion and text data
        console.log('Emotion:', data.emotion);
        console.log('Text:', data.text);
        console.log('Message ID:', data.messageId);
    } else {
        // Handle binary audio data
        const audioData = event.data;
    }
};

HTTP API for Tour Management

The service provides RESTful endpoints for tour management:

Get Tour List

curl http://localhost:7000/tour

Get Specific Tour

curl http://localhost:7000/tour/sample_tour

Create Tour

curl -X POST http://localhost:7000/tour \
  -H "Content-Type: application/json" \
  -d '{
    "tour_name": "sample_tour",
    "map_name": "sample_map",
    "steps": [
      {
        "description": "Go to entrance",
        "destination": "entrance_point",
        "dialogue": "Welcome to the tour!"
      }
    ]
  }'

Update Tour

curl -X PUT http://localhost:7000/tour \
  -H "Content-Type: application/json" \
  -d '{
    "tour_name": "sample_tour",
    "map_name": "sample_map",
    "steps": [
      {
        "description": "Updated step",
        "destination": "new_location",
        "dialogue": "Updated dialogue"
      }
    ]
  }'

Delete Tour

curl -X DELETE http://localhost:7000/tour/sample_tour

Development

Building the Container

To build the container locally:

docker build -t helloric_ui_com .

Running Tests

To run the test suite:

# Run WebSocket tests
python3 src/test/test.py

# Run tour management tests
python3 src/test/test_tgm.py

# Run integration tests
python3 src/test/test_postman.py

Debugging

Access the running container for debugging:

docker exec -it helloric_ui_com bash

View service logs:

docker logs helloric_ui_com