@ifollow/ros-client

Roslibjs Client
====

This is a wrapper around the roslibjs package aiming to improve shortcomings of the original roslib package by introducing a fluent API as well as some useful error and fault handling mechanisms.

For the official roslibjs repository please head to https://github.com/RobotWebTools/roslibjs

It includes documentation about interacting with the robot.

Main Features

* Fluent API
* Automatic connection recovery
* Reconnect support for topics

Documentation

Establishing a reliable connection with ROS is one of the main objectives of this library. It is, also, quite simple and straightforward. Just instantiate the library like so:

var RosClient = require("roslibjs-client"); // This is not necessary in the browser
var client = new RosClient({
url: "ws://192.168.0.11:9090"
});

Once you instantiate the client, it will connect to the said URL and stay connected. If the connection drops, it will try to reconnect every 5 seconds. You can change this interval by passing an additional reconnectInterval option in milliseconds. It is set to 5000 by default.

$3

Listening to ROS topics is much more reliable and efficient with this library because the handlers will tolerate connection drops. If your app gets disconnected from ROS, all the topics you have subscribed to are still stored by Roslibjs Client and once the connection is gained, it will instantly resubscribe to all the topics you want to listen.

You also don't have to worry about subscribing to a certain Topic multiple times. Behind the scenes, Roslibjs Client will always subscribe to a Topic once no matter how many handlers you attach to it.

To start listening to a topic simply do:

var listener = client.topic.subscribe(topic_name, message_type, function(message) {
// Here you can handle the message
});

To stop listening to it, simply call listener.dispose()

And that's all there is to it, really. This handler will continue to work even after you lose and gain connectivity.

$3

To publish a message over a ROS Topic run simply:

client.topic.publish(topic_name, message_type, payload);

$3

To make a service call run the following:

client.service.call(service_name, service_type, payload);

This returns a promise that will resolve when the service call is finished. Using that promise you can retrieve the response.

$3

To make a call run the following:

var listener = client.action.send(name, action, payload, timeout, feedback_callback, timeout_callback, result_callback);

> feedback_callback is a function to receive feedbacks about currently being performed actions

> timeout_callback is a function to receive timeout events based on passed timeout parameter

> result_callback is a function to receive final result of executed group of actions

To cancel the action, simply call listener.cancel() and it will stop the action and unsubscribe from feedback and result callbacks

$3

RosClient extends EventEmitter2 and offers two simple events that you can listen to:

1. connected will be fired once when RosClient connects to the target.
2. disconnected will be fired once the connection is lost.

You can easily listen to these events like so:

client.on("connected", function() {
alert("Connection established!");
});

Interacting with the robot

$3

* Request a robot
* Send a group of actions to a robot
* Groups are either stackable or overwritable
* An action can be mandatory or optional, meaning it has to succeed to continue the following actions or it can fail
* If action is mandatory and fails, it will retry a specific number of times

$3

This feature is a synchronous service:
Availability: returns robot name (for ex. ilogistics_2_0001*)
* No avaibility: returns 'None'

It requires to connect to the central server as follow:
``
var client = new RosClient({
url: "ws://ifollow-server:9090"
});

client.service.call(
"/get_robot_for_picking",
"ifollow_ll_msgs/AssignRobotGlobalStateMachine",
{})
`

Retrieving a robot name means client can now connect to the robot as follow:
`
var client = new RosClient({
url: "ws://ilogistics-2-0001:9090"
});
`
> Be aware that retrieved robot name is ilogistics_2_0001 and url uses ilogistics-2-0001

$3

This feature is an asynchronous service, for which you can use the Promise.then method to get the result as follow:
`
client.action.send(
'/task_manager/picking_care_server',
'ifollow_ll_msgs/TaskManagerOrderAction',
{
label: 'A random name you choose',
overwrite: true,
actions: [
{ label: '', order: '', optional_success: false, retry_count: 0},
...
!!!! See parameters definition below !!!
]
},
undefined, // if not used, timeout must be undefined
function (feedback) {
console.log("Feedback: ", feedback);
},
function () {
console.log("Timed out!");
// In that case, you can, as an example, cancel the group
},
function (result) {
console.log("Result: ", result);
})
`

#### Group of actions structure

| Data | Type | Description |
|---|---|---|
| label |string | Give it a name |
| overwrite | bool | Wether this group will override the previously sent ones or just stack |
| actions | action[] | List of the actions to perform |

#### Action structure

| Data | Type | Description |
|---|---|---|
| label |string | Label of the action (see below) |
| order | string | Order of the action (see below) |
| optional_success | bool | Wether the action is optional or mandatory |
| retry_count | uint_8 | If the action is mandatory, the robot will retry the action this number of time |

#### Actions type

| Label | Order | Description |
|---|---|---
| AutoNav | Stop point label | Sends robot to a location point
| Lift | Up | Lift up the plate
| Lift | Down | Lift down the plate
| Procedure | GetOutOfRoll | Goes out of the roll
| Procedure | SetAvailable | Release robot from duty as it was assigned when requesting a robot
| Procedure | Dock | Go to charging station
| Procedure | Undock | Goes out of charging station
| Wait | Number of seconds or 'Pause' | Pause robot in between two actions

#### Feedback structure

| Data | Type | Description |
|---|---|---|
| id_group | int | Group id |
| group_label | string | Group name you provided calling the action |
| instuction_position_in_the_group | int | |
| number_of_instructions_in_the_group |int | |
| id_action | int | |
| label_action | string | Label of the action you provided calling the action |
| order_action | string | Order of the action you provided calling the action |
| result | int | Type of result (see below) |


#### Result structure

| Data | Type | Description |
|---|---|---|
| output | int | Type of result |

#### Result type

| Label | Value | Description |
|---|---|---|
| OUTPUT_PENDING | 0 | |
| OUTPUT_ACTIVE | 1 | |
| OUTPUT_PREEMPTED | 2 | |
| OUTPUT_SUCCEEDED | 3 | |
| OUTPUT_ABORTED | 4 | |
| OUTPUT_REJECTED | 5 | |
| OUTPUT_PREEMPTING | 6 | |
| OUTPUT_RECALLING | 7 | |
| OUTPUT_RECALLED | 8 | |
| OUTPUT_LOST | 9 | |
| OUTPUT_OVERWRITING | 10 | |
| OUTPUT_OVERWRITTEN | 11 | |
| OUTPUT_STALLED | 12 | |
| OUTPUT_BUSY | 13 | |

$3

This feature is a synchronous service:
`
client.service.call(
'/task_manager/pause_current_group',
'ifollow_ll_msgs/PauseTaskManagerGroup',
{
pause: true or false
})
`

$3

This feature is an asynchronous service, for which you can use the Promise.then method to get the result as follow:
`
client.action.send(
'/task_manager/cancel_group',
'ifollow_ll_msgs/CancelTaskManagerGroup',
{
group_label: 'The name you chose before'
})
``