Skip to content

Service Documentation

This document provides instructions on how to run the HelloRIC UI Communication service and interact with its WebSocket and HTTP endpoints.

How to Run the Service

To run the HelloRIC UI Communication service, you first need to source your ROS2 environment and then use the appropriate command to start the service.

Using ROS2 Run

You can run the service node with the following command. This will start the FastAPI server and make it available for receiving WebSocket connections and HTTP requests.

# Source your ROS2 workspace
source install/setup.bash

ros2 run helloric_ui_com helloric_ui_com

Using Docker

When running the service in Docker, you can enter the container where the service is already configured:

docker exec -it helloric_ui_com bash

Command Line Parameters

You can customize the behavior of the service by passing command line arguments:

ros2 run helloric_ui_com helloric_ui_com --host 0.0.0.0 --port 7000 --log_level info
Argument Description Default
--host Server host address 0.0.0.0
--port Server port number 7000
--log_level Logging level (critical, error, info, warn, debug) info

WebSocket Communication

Connection Endpoint: /ws

The WebSocket endpoint provides real-time bidirectional communication for audio processing and emotion display.

Connecting to WebSocket

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

ws.onopen = function(event) {
    console.log('Connected to HelloRIC UI Communication');
};

ws.onmessage = function(event) {
    if (typeof event.data === 'string') {
        // Handle JSON messages
        const data = JSON.parse(event.data);
        handleJsonMessage(data);
    } else {
        // Handle binary audio data
        handleAudioData(event.data);
    }
};

Initial Response

Upon connection, the client receives initial default state:

{
    "microphoneActive": true,
    "emotion": "calm"
}

Sending Audio Data

Send raw audio bytes for processing:

// Send audio data as binary
const audioData = new Uint8Array(audioBuffer);
ws.send(audioData);

Receiving Audio Messages

Audio responses come in two parts:

  1. JSON Metadata with emotion, text, and message ID: 

    {
    "emotion": "happy",
    "text": "Hello! How can I help you?",
    "messageId": 1634567890123
}

  2. Binary Audio Data with 4-byte message ID header followed by audio bytes.

Sending JSON Commands

Send service commands as JSON:

// Clear chat history
ws.send(JSON.stringify({
    "service": "clear_history"
}));

Supported JSON Commands

Command Description Example
clear_history Clear the chat conversation history {"service": "clear_history"}

HTTP API Endpoints

The service provides RESTful HTTP endpoints for tour management operations.

/tour (GET)

Retrieve a list of all available tours.

Request: 

curl http://localhost:7000/tour

Response: 

["tour1", "tour2", "sample_tour"]

/tour/{tour_name} (GET)

Retrieve details of a specific tour.

Request: 

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

Response: 

{
    "tour_name": "sample_tour",
    "map_name": "sample_map",
    "steps": [
        {
            "description": "Go to entrance",
            "destination": "entrance_point",
            "dialogue": "Welcome to the tour!"
        },
        {
            "description": "Visit main hall",
            "destination": "main_hall",
            "dialogue": "This is our main exhibition hall."
        }
    ]
}

Error Response: 

{
    "detail": "Tour 'nonexistent_tour' not found"
}

/tour (POST)

Create a new tour.

Request: 

curl -X POST http://localhost:7000/tour \
  -H "Content-Type: application/json" \
  -d '{
    "tour_name": "new_tour",
    "map_name": "building_map",
    "steps": [
      {
        "description": "Start at reception",
        "destination": "reception",
        "dialogue": "Welcome! Let me show you around."
      }
    ]
  }'

Response: 

{
    "success": true
}

/tour (PUT)

Update an existing tour.

Request: 

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

Response: 

{
    "success": true
}

/tour/{tour_name} (DELETE)

Delete a specific tour.

Request: 

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

Response: 

{
    "success": true
}

Data Models

Tour Step Model

Each tour step contains the following fields:

Field Type Required Description
description string Yes Human-readable description of the step
destination string or null No Target location identifier for the step
dialogue string or null No Speech content to be delivered at this step

Tour Model

Each tour contains the following fields:

Field Type Required Description
tour_name string Yes Unique identifier for the tour
map_name string Yes Associated map identifier
steps array of TourStep Yes Ordered list of tour steps

Integration with ROS2

The service acts as a bridge between web clients and ROS2 services:

ROS2 Services Used

Service Name Service Type Description
/chat ric_messages/srv/Chat Audio processing and conversation
/clear_history std_srvs/srv/Empty Clear conversation history
/tour_create ric_messages/srv/TourCreate Create new tour
/tour_delete ric_messages/srv/TourDelete Delete existing tour
/tour_get ric_messages/srv/TourGet Retrieve tour details
/tour_list ric_messages/srv/TourList List available tours
/tour_update ric_messages/srv/TourUpdate Update existing tour

ROS2 Topic Subscriptions

Topic Name Message Type Description
/play_audio ric_messages/msg/PlayAudio Receive audio playback commands

ROS2 Services Provided

Service Name Service Type Description
/microphone/set_enabled std_srvs/srv/SetBool Control microphone state

Testing the Service

WebSocket Testing

Use the provided test script to verify WebSocket functionality:

python3 src/test/test.py

This script connects to the WebSocket endpoint and sends test messages.

HTTP API Testing

Test the tour management endpoints:

python3 src/test/test_tgm.py

Manual Testing

You can test individual endpoints manually:

# Test WebSocket connection
wscat -c ws://localhost:7000/ws

# Test HTTP endpoints
curl http://localhost:7000/tour

Checking Service Status

To verify the service is running: 

# Check if the service process is running
ps aux | grep helloric_ui_com

# Check if the port is open
netstat -tlnp | grep 7000

Logs and Debugging

View service logs: 

# When running directly
ros2 run helloric_ui_com helloric_ui_com --log_level debug

# When running in Docker
docker logs helloric_ui_com

Enable more verbose logging by setting the log level to debug: 

ros2 run helloric_ui_com helloric_ui_com --log_level debug