Create an application with `pal_app`#

pal_app is an utility that quickly creates an application template, ready for deployment on the robot.

Important

As of pal-sdk-23.12, you must run pal_app from inside an SDK Docker image to be able to develop an app.

See Developing with the SDK Docker image and ROS if you do not yet have your SDK Docker image set up.

Create an application skeleton#

Create on your computer a development workspace (that we will mount in the SDK Docker image):

mkdir ~/ws

Start the SDK Docker image (replacing customer_id by your own PAL-provided customer ID):

docker run -it -v $HOME/ws:/home/pal/ws registry.gitlab.com/pal-robotics/customer_id/dockers:latest bash

Inside the container, create a new app skeleton:

cd ws
mkdir src && cd src
pal_app create

Follow the instructions on screen. You will be asked to introduce:

ID: An ID for your new app. Must be a valid ROS identifier without spaces or hyphens. For instace, first_app.
App name: Full name of your application. For instance, My First App.
Robot type: The target robot your application will be deployed on. For now, only PAL’s robots is available.
Application controller type: The type of controller for you application. For now, only Python script is available.

Note

Since we are creating files in a shared (mounted) directory, the files are accessible (and can be freely edited/modified) from the host machine, and will not be lost when you close the Docker session.

The script generates the following file structure:

first_app
├── pages
│   ├── en_GB
│   │   ├── landing_page
│   │   │   ├── js
│   │   │   │   ├── main.js
│   │   │   ├── style
│   │   │   │   └── style.css
│   │   │   └── index.html
│   │   └── question_sample_page
│   │       └── ...
│   ├── README.md
│   └── zip_pages.sh
├── res
│   └── data.yaml
├── scripts
│   └── run_app
├── src
│   └── first_app
│       ├── application_controller.py
│       └── __init__.py
├── CMakeLists.txt
├── package.xml
├── README.md
└── setup.py

The pal_app generates a complete simple application as an example to start working on. It works as follows:

You’ll be able to access two web pages: landing page and content page. These are located in the pages folder.
The supervisor, aplicatoin_controller.py manages the pages to be displayed based on the touch input on the touchscreen. At the landing page, you will be able to START the interaction, which will trigger the content page. This latter displays a question, and based on the user response, the robot would do one action or another (not implemented since the goal is just to provide an skeleton of the code for the developer to further implement as desired).
The EXIT button in the content page takes you back to the landing page.

Let’s deploy it onto your robot.

Deploy the application on the robot#

To install your application on the robot, you need to follow the following two steps:

pal_deploy your ROS package to the robot
Install the touchscreen content (if you are using any)

Deploying the ROS package#

from inside your SDK Docker image, go to your development workspace:

cd ~/ws

then run:

rosrun pal_deploy deploy.py --package first_app ari-0c

(replace ari-0c by your actual robot’s hostname)

With the code deployed, you can now ssh onto the robot (ssh pal@ari-0c, password pal).

Install the touchscreen content#

The pages/ subfolder contains the web content meant to be displayed on the robot’s touchscreen. You will find one subfolder per language, and further subfolders for each touchscreen page.

Note

Your application controller can easily change the active (displayed) page via the ROS topic /web/go_to.

However, the pages must first be published on the robot, via the robot’s ARI’s Touchscreen manager.

Installing the pages on the robot#

You first need to create a zip archive for each of your pages. You can either manually zip the content of each subfolders, or use the provided zip_pages.sh script:

cd pages
sh zip_pages.sh

Each of the created zip file must then be uploaded to the robot’s Touchscreen manager, following the instructions to upload Custom HTML.

Updating web content

If you modify one of the pages, you must re-zip the corresponding folder, and re-upload it to the Touchscreen manager.

Run your application#

ssh onto the robot (ssh pal@ari-0c, password pal), and start your application:

rosrun first_app run_app

You should see a slowly-increasing counter and… not much else! You can press the buttons in the screens and navigate from one the other.

Background behaviours and event-driven programming#

We will see in a minute how to customize this default behaviour. We can however already see that applications can have background behaviours (like the counter).

They can also react to events by registering callbacks on specific ROS topics. The most important topic is the /intents topic. When the robot receives a command (or autonomously decides it must do something), it will normally be published as an intent (see below) on the /intents topic.

Our application can already react to some intents. Open another terminal on the robot, and type:

rostopic pub /intents hri_actions_msgs/Intent "{intent: '__intent_engage_with__'}"

By doing so you manually trigger the intent ENGAGE_WITH, and you should hear the robot say: “Hello! Nice to meet you!” while bowing.

Note

If you are not running the code directly on the robot, you can also type rostopic echo /tts/goal to display the text that is sent to the text-to-speech engine.

Hint

If you want to know more about the main concepts and components required to build an application, head now to Introduction to robot app programming.

Implement your application logic#

Let see how to customize the default application skeleton.

Intents are usually generated by your robot’s users. For instance, an intent might be generated:

through automatic perception (eg, someone approaches and seems to interact),
through verbal interaction (eg, someone tells the robot to go somewhere)
through interactions with the touchscreen (eg, someone presses a button to trigger a behaviour).

Your application template already contains examples of each of these possible interactions.

Let’s go through the generate application controller template. Open first_app/src/first_app/application_controller.py in your favourite text editor (outside or inside of the Docker image), and read on.

Code generated explanation:#

The Application Controller class begins with the __init__() function.

application_controller.py#

def __init__(self) -> None:

    rospy.loginfo("[APPLICATION test] initialising...")


    # this member variable will be set to 'True' if the application manager
    # or the user request the application to stop.
    self.cancellation_requested = False

    #######################################
    #
    # TODO: Add here any initialization steps
    # that should occurs only once.
    #

This function initializes the class and performs any necessary one-time initialization steps. Currently, it sets the self.cancellation_requested member variable to False.

The next function is on_intent(), which is responsible for handling each published intent. It gets called whenever an intent is published. Inside this function, the first action is to print the received intent using rospy.loginfo(). After that, you can define how your application should react to the received user intent.

application_controller.py#

def on_intent(self, msg):

    rospy.loginfo("[APPLICATION test] Received an intent: %s" % msg.intent)

    #######################################
    #
    # TODO: Define here how your application
    # should react when receiving an user
    # intent.

Following the log message, the code extracts and saves the data provided by the intent, if it exists.

application_controller.py#

data = json.loads(msg.data) if msg.data else {}
source = msg.source
modality = msg.modality
confidence = msg.confidence
priority_hint = msg.priority

After printing the intent and saving all the information, the next step is the management of the specific intents.

After processing the intent information, the code proceeds to handle specific intents.

The ENGAGE_WITH intent and the PRESENT_CONTENT are made as an example of what you can do.

application_controller.py#

if msg.intent == Intent.ENGAGE_WITH:
    # the 'data' dictionary should contain at least the following keys:
    # - recipient

    # As an example, we call here the TTS and play_motion action server
    # to implement a very simple behaviour when someone engages with the
    # robot.
    import actionlib
    from pal_interaction_msgs.msg import TtsAction, TtsGoal
    from play_motion_msgs.msg import PlayMotionAction, PlayMotionGoal

    tts = actionlib.SimpleActionClient('tts', TtsAction)
    play_motion = actionlib.SimpleActionClient('play_motion', PlayMotionAction)

    tts_goal = TtsGoal()
    tts_goal.rawtext.text = "Hello, I'm ARI. Nice to meet you!"
    tts_goal.rawtext.lang_id = "en_GB"

    tts.send_goal_and_wait(tts_goal)

    motion_goal = PlayMotionGoal(motion_name="bow")

    play_motion.send_goal_and_wait(motion_goal)

The code starts handling the ENGAGE_WITH intent. It imports necessary modules and creates action clients for the TTS and play_motion actions. This serves as a simple example of how an intent can be utilized. You can customize this example to define the behavior you want for the ENGAGE_WITH intent.

Similarly, the code snippet starting from line 117 deals with the PRESENT_CONTENT intent. It imports the necessary module and creates a publisher to the /web/go_to topic. The code sets the appropriate parameters in the WebGoTo message and publishes it, causing the robot to display the desired web page.

application_controller.py#

elif msg.intent == Intent.PRESENT_CONTENT:
    # the 'data' dictionary should contain at least the following keys:
    # - object (the content identifier)

    # handle intents to present specific content by simply
    # loading the corresponding page onto the touchscreen
    from pal_web_msgs.msg import WebGoTo

    web_goto_pub = rospy.Publisher('/web/go_to', WebGoTo, queue_size=1)

    rospy.loginfo("Displaying page %s on the touchscreen..." % data["object"])
    msg = WebGoTo()
    msg.type = WebGoTo.TOUCH_PAGE
    msg.value = data["object"]
    web_goto_pub.publish(msg)

These code snippets provide examples of how to handle specific intents, but you can modify them according to your application’s requirements and desired behavior for each intent.

Configure for automatic launch at start-up#

You can configure your app to automatically start when the robot is turned on. See Configure an application to launch at start-up for the details.

Next steps#

Follow Tutorial: Creating a simple multi-modal interaction to learn how to create a first custom application from scratch.

Create an application with pal_app#

Create an application skeleton#

Deploy the application on the robot#

Deploying the ROS package#

Install the touchscreen content#

Installing the pages on the robot#

Run your application#

Background behaviours and event-driven programming#

Implement your application logic#

Code generated explanation:#

Configure for automatic launch at start-up#

Next steps#

Create an application with `pal_app`#