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.

1. Listening to Topics

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.

2. Publishing a Topic

To publish a message over a ROS Topic run simply:

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

3. Service Calls

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.

4. Action Calls

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

5. Events

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

Main features

• 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

Request a robot

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

Send actions to the robot

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

Pause and unpause the currently processing group

This feature is a synchronous service:

client.service.call(
	'/task_manager/pause_current_group', 
	'ifollow_ll_msgs/PauseTaskManagerGroup', 
	{
		pause: true or false
	})

Cancel a group

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'
	})