## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links
## note.0=
## descriptive title for the tutorial
## title = Basic ROS functionality with roslibjs
## multi-line description to be displayed in search
## description = This tutorial shows you how to publish, subscribe, and perform service calls with roslibjs.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for
## level= BeginnerCategory
## keywords = roslibjs, web interface, teleoperation, Robot Web Tools
####################################
<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>
<<TableOfContents(4)>>
=== Getting Started ===
This tutorial involves writing a single HTML file, which will contain the HTML and JavaScript needed to communicate with ROS over rosbridge. To begin, create a file `simple.html` with your favorite text editor.
The complete code for this tutorial can be found in the [[https://github.com/RobotWebTools/roslibjs/tree/develop/examples|roslibjs repo]].
=== The HTML Code ===
{{{
#!cplusplus block=html_example
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/eventemitter2@6.4.9/lib/eventemitter2.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/roslib@1/build/roslib.min.js"></script>
<script type="text/javascript" type="text/javascript">
// Connecting to ROS
// -----------------
var ros = new ROSLIB.Ros({
url : 'ws://localhost:9090'
});
ros.on('connection', function() {
console.log('Connected to websocket server.');
});
ros.on('error', function(error) {
console.log('Error connecting to websocket server: ', error);
});
ros.on('close', function() {
console.log('Connection to websocket server closed.');
});
// Publishing a Topic
// ------------------
var cmdVel = new ROSLIB.Topic({
ros : ros,
name : '/cmd_vel',
messageType : 'geometry_msgs/Twist'
});
var twist = new ROSLIB.Message({
linear : {
x : 0.1,
y : 0.2,
z : 0.3
},
angular : {
x : -0.1,
y : -0.2,
z : -0.3
}
});
cmdVel.publish(twist);
// Subscribing to a Topic
// ----------------------
var listener = new ROSLIB.Topic({
ros : ros,
name : '/listener',
messageType : 'std_msgs/String'
});
listener.subscribe(function(message) {
console.log('Received message on ' + listener.name + ': ' + message.data);
listener.unsubscribe();
});
// Calling a service
// -----------------
var addTwoIntsClient = new ROSLIB.Service({
ros : ros,
name : '/add_two_ints',
serviceType : 'rospy_tutorials/AddTwoInts'
});
var request = new ROSLIB.ServiceRequest({
a : 1,
b : 2
});
addTwoIntsClient.callService(request, function(result) {
console.log('Result for service call on '
+ addTwoIntsClient.name
+ ': '
+ result.sum);
});
// Getting and setting a param value
// ---------------------------------
ros.getParams(function(params) {
console.log(params);
});
var maxVelX = new ROSLIB.Param({
ros : ros,
name : 'max_vel_y'
});
maxVelX.set(0.8);
maxVelX.get(function(value) {
console.log('MAX VAL: ' + value);
});
</script>
</head>
<body>
<h1>Simple roslib Example</h1>
<p>Check your Web Console for output.</p>
</body>
</html>
}}}
=== Code Explanation ===
Now that we have an example, let's look at each piece.
<<CodeRef(html_example,6,7)>>
We first need to import all of the required `JavaScript` files for the application, including `EventEmitter2` and `roslibjs`. Here, we use the [[https://robotwebtools.github.io/|Robot Web Tools]] CDN. The files can also be downloaded directly from their `GitHub` repos.
<<CodeRef(html_example,13,15)>>
Next, we need to create a `Ros` node object to communicate with a `rosbridge v2.0` server. In this example, the script will connect to `localhost` on the default port of `9090`.
The [[https://robotwebtools.github.io/roslibjs/Ros.html|ROSLIB.Ros docs]] details `ROSLIB.Ros` constructor options and available functions.
<<CodeRef(html_example,17,19)>>
This adds a listener for a `connection` event to the `ros` object. The two blocks following the `connection` event listener do the same for `error` and `close` events. This way, we can monitor the connection to the [[rosbridge_suite|rosbridge server]].
<<CodeRef(html_example,32,36)>>
A `ROSLIB.Topic` corresponds to a [[Topics|ROS Topic]]. The topic declares the topic name, message type, and passes in the ROS object from earlier. Topics can be used to subscribe or publish or both.
The [[https://robotwebtools.github.io/roslibjs/Topic.html|ROSLIB.Topic docs]] contains information on `ROSLIB.Topic` functions.
<<CodeRef(html_example,38,50)>>
To publish, we first need to create a new `ROSLIB.Message`. It takes in an object literal that matches up to the message definition on the ROS system. Nested objects are fine. See the [[https://robotwebtools.github.io/roslibjs/Message.html|ROSLIB.Message docs]] for available options when constructing a `ROSLIB.Message` object.
After we have the message, we just pass it to the `ROSLIB.Topic` to publish. If you followed the steps in Running the Example below, you can verify the message was published in the terminal by `rostopic echo cmd_vel`.
<<CodeRef(html_example,55,64)>>
The `listener` topic is created in the same fashion as the `cmdVel` topic above, accept it's dealing with the "/listener" topic name and "std_msgs/String" message type.
Subscribing happens by calling `subscribe()` on the topic and passing in a callback. Whenever ROS publishes a message on the "/listener" topic, rosbridge will forward that message to the browser and the callback function will be called with the message.
<<CodeRef(html_example,69,73)>>
[[Services|ROS services]] are also supported. First, we need to create a `ROSLIB.Service` object, which is similar to the `ROSLIB.Topic` object above in that it's responsible for all interactions with ROS services.
Check out the [[https://robotwebtools.github.io/roslibjs/Service.html|ROSLIB.Service docs]] for all `ROSLIB.Service` options.
<<CodeRef(html_example,75,85)>>
Like how a topic is called with a `ROSLIB.Message` object, a service is called with a `ROSLIB.ServiceRequest`.
The service is called on the service object with `addTwoIntsClient.callService` and passed two parameters: the `ROSLIB.ServiceRequest` and a callback function. The callback function will be called when the ROS service responds.
The [[https://robotwebtools.github.io/roslibjs/ServiceRequest.html|ROSLIB.ServiceRequest docs]] and [[https://robotwebtools.github.io/roslibjs/ServiceResponse.html|ROSLIB.ServiceResponse docs]] outline the available parameters for `ROSLIB.ServiceRequest` and `ROSLIB.ServiceResponse` objects.
<<CodeRef(html_example,90,102)>>
Getting and setting [[Parameter Server|ROS params]] is also supported. Like `ROSLIB.Topic` and ROSLIB.Service`, `ROSLIB.Param` acts as the core object for dealing with a particular param.
Setting a param can be done with a simple `param.set(value)`. Getting a param takes in a callback, which will be called when the server returns. Check out the [[https://robotwebtools.github.io/roslibjs/Param.html|ROSLIB.Param docs]] for available functions.
NOTE: Setting/Getting ROS Parameters requires a [[rosapi]] node to be running. See the discussion [[https://github.com/RobotWebTools/roslibjs/issues/364|roslibjs#364]].
=== Running the Example ===
At this point we are ready to run the example. To do so, you will need to have installed the following packages:
* ros-hydro-ros-base (basic ROS installation)
* ros-hydro-rosbridge-server ([[rosbridge_server]])
* ros-hydro-common-tutorials (Basic ROS tutorial package)
* ros-hydro-rospy-tutorials (Rospy tutorial package)
To begin, we will launch ROS. To do so, run the following in a terminal:
. {{{
roscore
}}}
Next, start publishing a message from the server to test our `JavaScript` subscriber:
. {{{
rostopic pub /listener std_msgs/String "Hello, World"
}}}
Then start subscribing to a topic to test publishing from the browser:
. {{{
rostopic echo /cmd_vel
}}}
Now run a service server that will return service calls from the browser:
. {{{
rosrun rospy_tutorials add_two_ints_server
}}}
Once everything is running, we can launch the `rosbridge v2.0` server with the following:
. {{{
roslaunch rosbridge_server rosbridge_websocket.launch
}}}
Finally, you are now ready to bring up your HTML page in a web browser. You can open up the file directly in the browser without running a web server. The data outputted happens in the Web Console. Instructions to view the Web Console depends on the browser:
* [[https://developers.google.com/chrome-developer-tools/|Open up Web Inspector in Chrome]]
* [[https://developer.mozilla.org/en-US/docs/Tools/Web_Console|Open up the Web Console in Firefox]]
## AUTOGENERATED DO NOT DELETE
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE