Merge pull request #13 from iml130/development

Development to master -> More Documentation, Docker.
iml130 · Apr 17, 2019 · 7b4f1f3 · 7b4f1f3
2 parents 6d77a03 + 43fc50e
commit 7b4f1f3
Show file tree

Hide file tree

Showing 40 changed files with 411 additions and 5,342 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,6 @@
 [submodule "firos/include/FiwareObjectConverter"]
 	path = firos/include/FiwareObjectConverter
 	url = https://github.com/iml130/FiwareObjectConverter.git
+[submodule "firos/include/genpy"]
+	path = firos/include/genpy
+	url = https://github.com/ros/genpy.git
diff --git a/README.md b/README.md
@@ -1,25 +1,35 @@
 # FIROS
 
 [![FIWARE Robotics](https://nexus.lab.fiware.org/static/badges/chapters/robotics.svg)](https://www.fiware.org/developers/catalogue/)
-[![License: MIT](https://img.shields.io/github/license/iml130/firos.svg)](https://opensource.org/licenses/MIT)<!--[![Docker badge](https://img.shields.io/docker/pulls/fiware/sigfox-iotagent.svg)](https://hub.docker.com/r/fiware/firos/)--> [![](https://img.shields.io/badge/tag-firos-orange.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/fiware+ros)
+[![License: MIT](https://img.shields.io/github/license/iml130/firos.svg)](https://opensource.org/licenses/MIT)<!--[![Docker badge](https://img.shields.io/docker/pulls/fiware/sigfox-iotagent.svg)](https://hub.docker.com/r/fiware/firos/)-->
+[![](https://img.shields.io/badge/tag-firos-orange.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/fiware+ros)
 <br/> [![Documentation badge](https://img.shields.io/readthedocs/firos.svg)](https://firos.rtfd.io)
-[![Build badge](https://img.shields.io/travis/iml130/firos.svg)](https://travis-ci.org/iml130/firos/)<!--
-[![Coverage Status](https://coveralls.io/repos/github/iml130/firos/badge.svg?branch=master)](https://coveralls.io/github/iml130/firos?branch=master)--> ![Status](https://nexus.lab.fiware.org/repository/raw/public/badges/statuses/incubating.svg)
+[![Build Status](https://travis-ci.com/iml130/firos.svg?branch=master)](https://travis-ci.com/iml130/firos)<!--
+[![Coverage Status](https://coveralls.io/repos/github/iml130/firos/badge.svg?branch=master)](https://coveralls.io/github/iml130/firos?branch=master)-->
+![Status](https://nexus.lab.fiware.org/repository/raw/public/badges/statuses/incubating.svg)
 
-FIROS works as a translator between the robotics field and the cloud world, transforming ROS messages into NGSI v2 to publish them in the cloud, and vice versa. The following figure depicts the integration of FIROS inside the FIWARE platform.
+FIROS works as a translator between the robotics field and the cloud world, transforming ROS messages into NGSI v2 to
+publish them in the cloud, and vice versa. The following figure depicts the integration of FIROS inside the FIWARE
+platform.
 
 ![alt text](doc/firos.png "FIROS Integration")
 
-FIROS is a tool that helps connecting robots to the cloud. For this purpose it uses the [Robot Operating System (ROS)](http://www.ros.org/) and the [FIWARE Context Broker](http://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker) as a way to publish and listen robot's data.
+FIROS is a tool that helps connecting robots to the cloud. For this purpose it uses the
+[Robot Operating System (ROS)](http://www.ros.org/) and the
+[FIWARE Context Broker](http://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker) as a
+way to publish and listen robot's data.
 
-FIROS works as a translator between the robotics field and the cloud world, transforming ROS messages into NGSI to publish them in the cloud, and vice versa.
+FIROS works as a translator between the robotics field and the cloud world, transforming ROS messages into NGSI to
+publish them in the cloud, and vice versa.
 
-This project is a fork from the **outdated** [Ikergunes FIROS package](https://github.com/Ikergune/firos). 
+This project is a fork from the **outdated** [Ikergunes FIROS package](https://github.com/Ikergune/firos).
 
-This project is part of [FIWARE](https://www.fiware.org/). For more information check the FIWARE Catalogue entry for the [Robotics](https://github.com/Fiware/catalogue/tree/master/robotics).
+This project is part of [FIWARE](https://www.fiware.org/). For more information check the FIWARE Catalogue entry for the
+[Robotics](https://github.com/Fiware/catalogue/tree/master/robotics).
 
 | :books: [Documentation](https://firos.rtfd.io) | :dart: [Roadmap](doc/roadmap.md) |
-| ------------------------------------- |  ------------------------------- |
+| ---------------------------------------------- | -------------------------------- |
+
 
 ## Contents
 
@@ -30,25 +40,30 @@ This project is part of [FIWARE](https://www.fiware.org/). For more information
 -   [Contributors](#Contributors)
 -   [Additional Resources](#Additional%20Resources)
 
+## Install
 
-## Install 
 Refer to the Installation-Guide [here](doc/install/install.md)
 
 ## Usage
+
 Refer to the User-Guide [here](doc/user/introduction.md)
 
 ## Troubleshooting
 
 TBD
 
 ## License
+
 FIROS is licensed under [MIT License](https://opensource.org/licenses/MIT).
 
 ## Contributors
+
 Dominik Lux, Peter Detzner
 
 ## Additional Resources
+
 ### Presentations
+
 FIROS-Helping Robots to be Context Aware
 ([Slideshare](https://de.slideshare.net/FI-WARE/fiware-global-summit-FIROS-helping-robots-to-be-context-aware),
 28.11.2018 FIWARE Global Summit, Malaga)
diff --git a/doc/install/configuration-files.md b/doc/install/configuration-files.md
@@ -1,6 +1,6 @@
 # Configuration-Files
 
-Firos needs 3 different configuration files inside the Configuration-Folder. An example Configuration-Folder can be
+FIROS needs 3 different configuration files inside the Configuration-Folder. An example Configuration-Folder can be
 found in the `config`-Folder at the base of this repository. It needs to contain the files `config.json`, `robots.json`
 and `whitelist.json` (optionally: `robotdescriptions.json`).
 
@@ -47,7 +47,7 @@ Here is the list of all possibilities for a configuration:
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: |
 | "interface"            | Can be `"public"` or another string of one of the interfaces given by `ip link` or by `ifconfig`. If set to `"public"`, the public IP-address is set for the Map-Server (via [this](http://ip.42.pl/raw)). Otherwise the (specified) interface IP-address is used. |    x     |
 | "log_level"            | Can be either `"INFO"` (Default), `"DEBUG"`, `"WARNING"`, `"ERROR"` or `"CRITICAL"`.                                                                                                                                                                               |          |
-| "node_name"            | This sets the ROS-Node-Name for this firos instance. the default is `"firos"`.                                                                                                                                                                                     |
+| "node_name"            | This sets the ROS-Node-Name for this FIROS instance. the default is `"firos"`.                                                                                                                                                                                     |
 | "ros_subscriber_queue" | The queue-size of the `rospy.Publisher`. See more [here](http://wiki.ros.org/rospy/Overview/Publishers%20and%20Subscribers). Default is `10`                                                                                                                       |          |
 | "context_type"         | This sets the context type of an entity (the `type`-value of the base-entity). Default is `"ROBOT"` but can be changed if necessary                                                                                                                                |          |
 | "rosbridge_port"       | Changes the ROS-Port, where to listen. Default is `9090`                                                                                                                                                                                                           |          |
@@ -131,11 +131,36 @@ needed ones, which need to be displayed from/or need to obtain information on th
 }
 ```
 
+The Information given by the `robots.json` is appended/replaced to the `whitelist.json` which is described below.
+
 ---
 
 ## `whitelist.json`
 
-TODO WIP
+As the name suggests, the `whitelist.json` functions as a whitelist to let FIROS know which messages it should keep
+track of. Given an environment where already ROS-Applications are running, FIROS will automatically subscribe to all
+available topics if no `whitelist.json` is given. In a small ROS-World with few ROS-Applications, this can be desirable.
+But this can cause problems in a ROS-World, where many ROS-Applications are running. To let FIROS only subscribe to
+specific topics, the following configuration can be used:
+
+```json
+{
+    "turtle2": {
+        "publisher": ["cmd_vel"],
+        "subscriber": ["pose"]
+    }
+}
+```
+
+This only allows FIROS to subscribe/publish to `"/turtle2/pose"` and `"turtle2/cmd_vel"` plus the extra-configuration
+given in `robots.json` which in the above example would also be `"/turtle1/pose"` and `"turtle1/cmd_vel"`.
+
+**Note**, that an empty configuration of `whitelist.json` (`-> {}`) will also behave as an
+non-existent-configuration-file. Usually for normal usecases, the `whitelist.json` contains the same information as the
+`robots.json` and should be sufficient.
+
+**Note:** The FIROS only captures running ROS-Applications at the startup. All applications started after FIROS will not
+be recognized.
 
 ---