[Documentation] [TitleIndex] [WordIndex

Only released in EOL distros:  

websocket_gui

Package Summary

A declarative widget library based on ros.js

websocket_gui

Package Summary

A declarative widget library based on ros.js

Overview

Using a robot, you want to display information provided by the platform and its sensors. Some tools like webui and QGroundControl already exist but own dependencies with ROS and/or others plug-in. This implicates to install additional software on your visualization computer which could be constraining.

In order to avoid that problem, the remote lab project developed a robot web application wviz based on the websocket protocol. However, this API is still low level and requires some ROS and JavaScript backgrounds.To make things easier for the user, we developed the websocket_gui stack.

websocket_gui furnishes several widgets to display information from ROS messages in a web browser based on rosjs. Its low level communication protocol is managed by the rosbridge node.

List of widgets :

Architecture

Overall

To run this stack, you need the following infrastructure which is quite simple. On the left side, you have your robot with ROS. Rosbridge is a necessary node to create the interface between ROS and your web browser from the client side. When the connection is opened and data are received by the client side, they are displayed calling widgets based on web libraries like JavaScript, HTML5 and CSS3.

infrastructure_150x150_p3.png

Widget concepts

With these widgets, you can display several information, and/or data in the same screen with different types of display. To make things easier for the user, the HTML structure of your page also called Document Object Model is built automatically. If you are familiar with this concept, you can jump to the Widgets section. Otherwise take a look to the next section.

HTML5 and CSS3

HTML and CSS are programming languages used to create web pages. They have been invented by Tim Berners-Lee and Håkon Wium Lie in the 90's. Few years later, the first one created the World Web Consortium W3C which is the reference website (I hope your future Holly Bible) in this field.

4_widgets_custom_s1.png

JavaScript

JavaScript is the programming language of scripts for the Web. It has been developed in Netscape, by Brendan Eich. It has to be directly included in the web page and make a HTML page more dynamic for the user. Using this stack, you will be confronted to two JavaScript functions:

Widgets

This section lists available widgets.

Altimeter

This widget looks like to a plane altimeter. A needle rotates according the value of the parameter specified in option. At the bottom of this widget, a counter displays the current value.

   1  document.body.innerHTML+=Altimeter(style,topic_name,delay_ms,dictionary)

This widget resizes itself according the height and the width of the body element. It finds the optimal scale to keep its ratio. Moreover the altimeter is centred in its div.

DisplayImage

This widget display images from a ROS image topic. Two modes are available. Firstly, you can stream video as another message type from ROS using rosjs (included in rosbridge). In order to increase performance benefits mjeg_server has been developed. It's a streaming server that subscribes to a ROS image topic, publishes data as MJPEG streams via HTTP and displays it in your browser.

   1 document.body.innerHTML+=DisplayImage(style,topic_name,period_ms,port_opt)

This widget resizes itself according the height and the width of the body element. It finds the optimal scale to keep the image ratio.

DisplayTopic

This widget displays a topic like the rostopic echo command in ROS.

   1 document.body.innerHTML+=DisplayTopic(style,topic_name,period_ms)

The size of the font is defined by default.

Plot

It plots one or several data from a topic according the timestamps contained in the message header. If the message does not own timestamps, a pseudo time is automatically created.This widget uses a JavaScript library flot.

   1 document.body.innerHTML+=Graph(style,topic_name,period_ms,dictionary)

This widget adapts its scale division for a proper display and resizes itself automatically.

Log

This widget displays a console showing main steps of the process. A color code is established to display information, warning and error. Two sources can provide messages, ROS (as rxconsole) and JavaScript.

   1 document.body.innerHTML+=Log(style,topic_name,bool_rxconsole,bool_js)

RosTurtle

This widget displays a turtle drawing a square and its trajectory like turtlesim

   1 document.body.innerHTML+=RosTurtle(style,teleop_turtle)

Display the turtle and its trajectory sensed from /turtle1/pose . If teleop_turtle set to true you can control the turtle clicking on arrow or using arrows on your keyboard. When the webbrowser is resized the trajectory is clear.

Battery

This widget displays a battery and the battery_voltage.

   1 document.body.innerHTML+=Battery(style,topic_name,period_ms,dict)

If no key "key" is present in the dictionary, the widget searches for default key iteratively. If no key is found, an error message is written in the Log widget.

Installation

To use the websocket_gui, you will need the trunk of the websocket_gui stack: and one additional package such as rosbridge.

In order to download and build the websocket_gui stack, open a terminal and follow these steps:

  Show EOL distros: 

   1 #Go to your working ros directory
   2 cd somewhere/in/my/ros/folder
   3 
   4 #Clone the brown_remotelab stack containing rosbridge package in this directory
   5 git clone --recursive https://brown-ros-pkg.googlecode.com/svn/trunk/distribution/brown_remotelab
   6 #Build rosbridge
   7 cd brown_remotelab/rosbridge
   8 make
   9 
  10 #Clone the websocket_gui stack in this directory
  11 git clone --recursive https://github.com/ethz-asl/websocket_gui
  12 #Build it
  13 cd websocket_gui
  14 make
  15 
  16 #Install dependencies for the Map widget
  17 #gdal library (http://www.gdal.org/)
  18 sudo apt-get install gdal-bin python-gdal libgdal-doc
  19 #Mapserver library (http://mapserver.org/)
  20 sudo apt-get install cgi-mapserver mapserver-doc mapserver-bin python-mapscript php5-mapscript
  21 #Test mapserv for cgi by typing in your favorite browser:
  22 http://localhost/cgi-bin/mapserv
  23 #You should obtain the following answer:
  24 "No query information to decode. QUERY_STRING is set, but empty." 
  25 
  26 #Now your installation is successful, let's play with some widgets 

   1 #This installation supposed you have set your ros environment and created a ros workspace.
   2 
   3 #Add the brown_remotelab stack containing rosbridge package to the overlay
   4 roslocate info brown_remotelab | rosws merge
   5 
   6 #Add the websocket_gui package to the overlay
   7 roslocate info websocket_gui | rosws merge
   8 
   9 #Update repositories in the overlay
  10 rosws update
  11 
  12 #Build packages
  13 rosmake websocket_gui
  14 rosmake rosbridge
  15 
  16 #Install dependencies for the Map widget
  17 #gdal library (http://www.gdal.org/)
  18 sudo apt-get install gdal-bin python-gdal libgdal-doc
  19 #Mapserver library (http://mapserver.org/)
  20 sudo apt-get install cgi-mapserver mapserver-doc mapserver-bin python-mapscript php5-mapscript apache2
  21 #Test mapserv for cgi by typing in your favorite browser:
  22 http://localhost/cgi-bin/mapserv
  23 #You should obtain the following answer:
  24 "No query information to decode. QUERY_STRING is set, but empty." 
  25 
  26 #Now your installation is successful, let's play with some widgets 

TOtest.

Quick start

First example with a well known turtle ...

This example works with the [[http://wiki/turtlesim|turtlesim] node used in the ros_tutorial. A turtle pops and draws a rectangle. The altimeter displays the turtle angle.

Open you favourite terminal and write the following commands:

 roslaunch websocket_gui turtle_draw_rectangle.launch

This launch file starts the turtlesim and the draw_square nodes.

Then open in firefox or google chrome somewhere/in/my/ros/folder/websocket_gui/examples/html/turtle_drawing_rectangle.html.

Well this is a really basic example, it would be more funny if we could teleop the turtle... Okay, so let's do it

Second example to teleop the turtle

Let's take the first example and improve it in order to control the turtle's movements.

If you ran the first example, you can stop the last launch file.

Open you favourite terminal and write the following commands:

 roslaunch websocket_gui turtle_teleop.launch

It's the same launch file compared to the previous except that the draw_square node has been removed.

A turtle pops and does not move but don't be too sad,.

Open in firefox or google chrome somewhere/in/my/ros/folder/websocket_gui/examples/html/turtle_teleop.html.

You can teleop the turtle pressing your keyboard arrays or clicking on the arrays drawn into the page.

Turtle examples were fun but quite simplistic. Now let's talk about a more practical example.

Third example with a micro-helicopter

For this example we will not use the turtlesim package. Our inputs will be provided by a rosbag which is a sample of a dataset. It was acquired on a micro-helicopter platform by a team from the ETHZ. To run this example properly, you need to install the following packages for the rosbag: - ethzasl_sensor_fusion - asctec_mav_framework Open you favourite terminal and write the following commands:

   1  #Go to your working ros directory
   2  cd somewhere/in/my/ros/folder
   3  #Download ethzasl_sensor_fusion
   4  git clone git://github.com/ethz-asl/ethzasl_sensor_fusion
   5  #Download asctec_mav_framework
   6  git clone https://github.com/ethz-asl/asctec_mav_framework
   7  #Build packages
   8  rosmake ethzasl_sensor_fusion
   9  rosmake asctec_mav_framework
  10  #It's done! Now you just have to start the launch file
  11  roslaunch websocket_gui helicopter.launch
  12  #It launches the rosbridge node and plays the rosbag in loop.

Open in firefox or google chrome somewhere/in/my/ros/folder/websocket_gui/examples/html/helicopter.html.

In this example the map uses maps.google API and is online which could present difficulties if you don't have access on your experiment place.

A tool has been developed to download tiles from the internet and create your own local map. It will be present in the next example.

Forth example with a micro-helicopter and an offline map

In order to process the tiles downloaded and create the "map" server, some packages must be installed.

Open you favourite terminal and write the following commands:

   1  #Install mapserver packages http://mapserver.org/
   2  sudo apt-get install mapserver-bin mapserver-doc cgi-mapserver python-mapscript php5-mapscript
   3  #Install gdal libraries http://www.gdal.org/
   4  sudo apt-get install gdal-bin
   5  #go to the script directory
   6  cd somewhere/in/my/ros/folder/websocket_gui/tools/Map/script
   7  #Execute script
   8  python GetMap.py 47.418912 8.566297 1123 674 -z 0.25 -s 256 -a
   9  # Open in firefox or google chrome ''somewhere/in/my/ros/folder/websocket_gui/examples/html/helicopter2.html
  10  

Files and Organization

This part parses the websocket_gui directory and details all files purpose. If you want to create your own widget, it will help you to find out how this API works.

In your terminal, write the following command

 cd websocket_gui
 ls

You obtain:

websocket_gui.png

Let's make a review of the main files and directories.

build

Contains websocket_gui.js generated from the Makefile and grouping all the JavaScript API.

examples

examples_ls.png

js

js_ls.png

Contains all the JavaScript API.

API functioning

Opening a html page, two process will be executed in parallel. The first one is link to your widget: Firstly the widget function creates a WidgetWithTask Object. A widget_task and a resize_widget_task functions are store in this object. Then the WidgetWithTask object is added the websocket_gui_obj which is a instance of WebSocketGui. Finaly the <div> element associated to the widget is returned.

During this time,

Report a Bug

You can use our issue tracker


2022-05-28 13:08