REST interface#

The ARI robot has a REST interface available for integrators to use. This REST interface simplifies tasks of monitoring and management of the robot, allowing simple and robust integration.

General considerations#

The REST interface is offered on port 80 on the robot. This document assumes you either connects to the robot’s WiFi (robot set as access point), or, if the robot is connected to your network, it has been added to the DNS with the appropriate name (ari**-Xc**, where X is the serial number).

Standard html codes are used for the different interfaces, according to the following table:

HTML Code

Status

200

Success on GET requests

201

Success on POST requests

204

Success on DELETE requests

400

Protocol is not readable (Content-type must be set to application/json or application/x-www-form-urlencoded)

403

Code returned when an operation is not allowed.

500

There was an internal error on the server.

Robot monitoring interfaces#

There are several endpoints that convey general information on the state of the hardware of the robot.

Docked state#

Indicates if the robot is connected to a dock station.

Endpoint: http://ari-Xc/topic/is_docked

Request type: GET

Result:

1{
2  "msg": {
3    "data": false
4  },
5  "topic_name": "is_docked"
6}

The msg.data field is true if the robot is docked, false otherwise.

The topic_name field contains the name of the topic endpoint accessed.

Charging state#

Indicates the charging state of the robot.

Endpoint: http://ari-Xc/topic/is_charging

Request type: GET

Result:

1{
2  "msg": {
3    "data": false
4  },
5  "topic_name": "is_charging"
6}

The msg.data field is set true if the robot is charging (either on the dock or from the back port), false otherwise.

The topic_name field contains the name of the topic endpoint accessed.

Power diagnostic#

Contains information about the power state of the robot.

Endpoint: http://ari-Xc/topic/power_diagnostic

Request Type: GET

Result:

 1{
 2  "msg": {
 3    "header": {
 4      "stamp": {
 5        "secs": 1592840672,
 6        "nsecs": 856730268
 7      },
 8      "frame_id": "power_status",
 9      "seq": 3570
10    },
11    "charger": 0.1,
12    "pc": 19.3,
13    "charge": 80,
14    "dock": 0.1,
15    "input": 38.2,
16    "is_emergency": false,
17    "is_connected": false
18  },
19  "topic_name": "power_diagnostic"
20}

The msg field contains:

  • header.stamp: Epoch time split in seconds and nanoseconds at which the message was sent.

  • header.frame_id: identifier of the message

  • header.seq: internal sequence number of the message

  • charger: Voltage received from the charger

  • pc: Voltage received on the PC

  • charge: Voltage of the battery

  • dock: Voltage received through the dock port

  • input: Voltage received from the back port

  • is_emergency: True if the emergency button is pressed, false otherwise

  • is_connected: True if the robot is being charged, wither from the front or from the back port

The topic_name field contains the name of the topic endpoint accessed.

Text-to-Speech

Triggers robot speech given an input text.

Endpoint: http://ari-Xc/action/tts

Request Type: POST

Payload:

1{
2  "rawtext": {
3      "text": "Hey, Juana, how are you?",
4      "lang_id": "en_GB"
5  }
6}

rawtext.text is the string of the user input that is to be said

rawtext.lang_id is RFC 3006 code to select the language the text will be said in (e.g. en_GB for British English).

Optional parameters:

speakerName: gives the option to choose a variety of speakers for the same language, if the platform allows it

wait_before_speaking: indicates how many seconds the platform has to wait before saying the text

Response:

 1{
 2  "response": {
 3    "msg": {
 4      "rawtext": {
 5        "text": "Hello people! How are you doing?",
 6        "lang_id": "en_GB"
 7      }
 8    },
 9    "goal_id": "goal_6487fd70-d508-4bd7-a909-08fbd59e9b3f",
10    "action_name": "tts"
11  }
12}

The response.msg field contains a copy of the received message.

The response.goal_id field contains the internal goal id for the created goal.

The response.action_name field contains the action endpoint to which the message has been sent.

Variations#

In order to execute motions alongside speech, it is possible to include the desired motion as a tag name.

Endpoint: http://ari-Xc/action/tts

Request Type: POST

Payload:

1{"rawtext": {"text": "Hey, Juana, <mark name='doTrick trickName=show_left'/>", "lang_id": "en_GB"}}

The above request will result in ARI showing its left arm as it says the text given.

A second usage of this method is to define a configuration file on the robot that lists different possible sentences classified into sections and keys. It is useful when a same behaviour is to be done in multiple languages.

Endpoint: http://ari-Xc/action/tts

Request Type: POST

Payload:

1{"section": "receptionist", "key": "greetings", "lang_id": "en_GB"}

section/key refers to the group of sentences that will be randomly selected.

In the above example, [receptionist] would be the name of the section, “greetings” the key name. The robot will select one of the three sentences at random. There can be as many sections and keys as desired.

1[receptionist]
2
3greetings=Hello! Touch my screen to interact with me!
4greetings= How are you? I am ARI. Do you want to play with me?
5greetings=Hey, nice to meet you! Can I help you with something?

lang_id is RFC 3006 code to select the language the text will be said in (e.g. “en_GB” for British English).

arguments (optional) contain the values by which occurrences of ‘%s’ of the configuration file will be replaced in the main text. For example:

1{
2  "section": "receptionist",
3  "key": "greetings",
4  "lang_id": "en_GB",
5  "arguments": ["Maria", "Tic Tac Toe"]
6}

1[receptionist]
2
3greetings=Hello %s! Touch my screen to play %s with me!

It will result in “Hello Maria! Touch my screen to play Tic Tac Toe with me!

Response:

 1{
 2  "response": {
 3    "msg": {
 4      "text": {
 5        "section": "receptionist",
 6        "key": "greetings",
 7        "lang_id": "en_GB"
 8      }
 9    },
10    "goal_id": "goal_6487fd70-d508-4bd7-a909-08fbd59e9b3f",
11    "action_name": "tts"
12  }
13}

The response.msg field contains a copy of the received message.

The response.goal_id field contains the internal goal id for the created goal.

The response.action_name field contains the action endpoint to which the message has been sent.

To visualize the feedback or result of the request, execute a GET request, defining the goal id of the request that was executed in the first place.

Endpoint: http://ari-Xc/action/tts?goal_a78f2947-6ddb-4a58-b4f3-cf7bd2e8f7ba

Request Type: GET

Payload:

Payload:

1{}

Response:

1{
2  "goal_6487fd70-d508-4bd7-a909-08fbd59e9b3f": "SUCCEEDED"
3}

It indicates that the text-to-speech was successful.

Executing motions#

The following endpoint enables triggering motions on ARI.

Request URL: http://ari-Xc/action/motion_manager

Request Method: POST

Payload:

1{"filename": "shake_left"}

The filename field contains the name of the motion to be executed.

Response:

1{
2  "response": {
3    "msg": {
4      "filename": "shake_left"
5    },
6    "goal_id": "goal_0bc3677e-8579-4447-bada-9ffe965626d4",
7    "action_name": "motion_manager"
8  }
9}

The response.msg field contains a copy of the received message.

The response.goal_id field contains the internal goal id for the created goal

The response.action_name field contains the endpoint to which the message has been sent.

In order to review the status of the request, you may do the following GET request, by adding a question mark ? and the goal ID obtained previously.

Request URL: http://ari-Xc/action/motion_manager?goal_0bc3677e-8579-4447-bada-9ffe965626d4

Request Method: GET

Payload:

1{}

Response:

 1{
 2  "/interaction_profile_manager-232-1613745938.6713457": "SUCCEEDED",
 3  "/interaction_profile_manager-229-1613745919.206712378": "SUCCEEDED",
 4  "/interaction_profile_manager-228-1613745912.406713513": "SUCCEEDED",
 5  "/interaction_profile_manager-244-1613746029.6708203": "SUCCEEDED",
 6  "/interaction_profile_manager-241-1613746011.6671771": "SUCCEEDED",
 7  "/interaction_profile_manager-231-1613745932.106732579": "SUCCEEDED",
 8  "/interaction_profile_manager-234-1613745954.306731998": "SUCCEEDED",
 9  "/interaction_profile_manager-240-1613746002.206710218": "SUCCEEDED",
10  "/interaction_profile_manager-247-1613746051.206706584": "SUCCEEDED",
11  "/interaction_profile_manager-233-1613745947.506710338": "SUCCEEDED",
12  "/interaction_profile_manager-246-1613746045.606716141": "SUCCEEDED",
13  "/interaction_profile_manager-239-1613745993.406716273": "SUCCEEDED",
14  "/interaction_profile_manager-236-1613745971.906710098": "ABORTED",
15  "/interaction_profile_manager-227-1613745902.606728662": "SUCCEEDED",
16  "/interaction_profile_manager-237-1613745979.6731839": "SUCCEEDED",
17  "goal_cb938245-1ad9-4fec-94f0-5b8f017db6b3": "ACTIVE",
18  "/interaction_profile_manager-245-1613746038.806699379": "SUCCEEDED",
19  "/interaction_profile_manager-238-1613745984.906711559": "SUCCEEDED",
20  "/interaction_profile_manager-230-1613745926.206720104": "SUCCEEDED",
21  "/interaction_profile_manager-235-1613745963.106722929": "SUCCEEDED",
22  "/interaction_profile_manager-243-1613746023.406714303": "SUCCEEDED",
23  "/interaction_profile_manager-242-1613746017.806672347": "SUCCEEDED"
24}

In the above example, it indicates the goal has succeeded and the time when it was active.

Docking#

The following endpoint triggers autonomous docking of the robot.

Request URL: http://ari-Xc/action/dock

Request Method: POST

Payload:

1{"retry_delay": {"secs": "0", "nsecs": "0"}, "use_current_pose": "False"}

retry_delay indicates the maximum time the docking mechanism should start retrying

If use_current_pose is set to true, it will use the current pose for detection.

Response:

 1{
 2  "response": {
 3    "msg": {
 4      "retry_delay": {
 5        "secs": "0",
 6        "nsecs": "0"
 7      },
 8      "use_current_pose": "False"
 9    },
10    "goal_id": "goal_26752d4b-1c0d-494c-9048-5ac3c6096c5b",
11    "action_name": "dock"
12  }
13}

The response.msg field contains a copy of the received message.

The response.goal_id field contains the internal goal id for the created goal

The response.action_name field contains the endpoint to which the message has been sent.

Request URL: http://ari-Xc/action/dock

Request Method: POST

Payload:

1{"retry_delay": {"secs": "0", "nsecs": "0"}, "use_current_pose": "True"}

In this case, as use_current_pose is set to True, it will use a pre-defined position of the dock station to reach for the dock.

Response:

 1{
 2  "response": {
 3    "msg": {
 4      "retry_delay": {
 5        "secs": "0",
 6        "nsecs": "0"
 7      },
 8      "use_current_pose": "True"
 9    },
10    "goal_id": "goal_095b986c-e7ce-4d56-a30e-7f097b650abb",
11    "action_name": "dock"
12  }
13}

Undocking#

The following endpoint triggers autonomous undocking of the robot.

Request URL: http://ari-Xc/action/undock

Request Method: POST

Payload:

1{}

Response:

1{
2  "response": {
3    "msg": {},
4    "goal_id": "goal_80b0669f-bea4-4814-9241-cd17baaf18cc",
5    "action_name": "undock"
6  }
7}

Sending a navigation goal#

Sends the robot to the specified location in the map. Users should ensure a valid map is loaded on the robot.

Request URL: http://ari-Xc/action/move_base

Request Method: POST

Payload:

 1{
 2  "header": {
 3    "stamp": {
 4      "secs": 1592840672,
 5      "nsecs": 856730268
 6    },
 7    "frame_id": "map"
 8  },
 9  "pose": {
10    "position": {
11      "x": 1.0,
12      "y": 0.0,
13      "z": 0.0
14    },
15    "orientation": {
16      "x": 0,
17      "y": 0,
18      "z": 0,
19      "w": 1
20    }
21  }
22}

header mentions the frame_id, that is, the coordinate frame where the goal is sent

pose indicates the position and orientation (in quaternions) of the navigation goal.

Response:

1{
2  "response": {
3    "msg": {},
4    "status": "",
5    "goal_id": "goal_80b0669f-bea4-4814-9241-cd17baaf18cc",
6    "action_name": "move_base"
7  }
8}
  • The status field contains an unsigned int 8 (characters) status,

    according to the following table:

State ID

State

Explanation

0

PENDING

The goal is pending to be processed

1

ACTIVE

The goal is currently being processed

2

PREEMPTED

The goal receive a cancel request after it started executing

3

SUCCEEDED

The goal was achieved successfully

4

ABORTED

The goal was aborted during execution

5

REJECTED

The goal was rejected because it was not valid or was unattainable

Access head camera#

The following endpoint enables accessing data stream from ARI’s head RGB camera.

Request URL: http://ari-Xc/topic/head_front_camera

Request Method: GET

Response:

 1{
 2  "msg": {
 3    "header": {
 4      "stamp": {
 5        "secs": 1592840672,
 6        "nsecs": 856730268
 7      },
 8      "frame_id": "",
 9      "seq": 1
10    },
11   "data": "/9j/4AAQSkZJRgABAQAAAQ"
12   "format": "rgb8; jpeg compressed bgr8"
13  },
14  "topic_name": "head_front_camera"
15}

format specifies the format of the data (jpeg, png)

data is a compressed image buffer consisting of a uint8 array