--DEPRECATED-- msgconnector, HATP's middleware --DEPRECATED--
This module is now deprecated ! HATP relies on ROS to transport messages. |
This page presents msgconnector's usage. msgconnector is responsible to carry messages form a module to another.
It is also responsible to the connection to other middlewares: OPRS, ORO, YARP.
|
![/!\](/moin_static1911/moniker/img/alert.png "/!\"){kind=small}
The way to install msgconnector is described in HATP/install.
1. Principle
msgconnector is composed of a server (MsgSever) that once started allows the different clients to connect. When a client connects it gives its name. This name is then used to carry a message from a client to another.
It is possible to declare several clients with the same name, then all the message are repeated to all the clients with the same name.
The message passed are usually using the JSON format (see JSON) but it is not mandatory.
Finally msgconnector can be connected to other middleware to extend the reach of HATP's messages. To do so bridges need to be started. So far the implemented bridge are:
- OPRS
- ORO
- YARP
- print (which is in fact just a backend to print all messages that it receives).
If you need an additional bridge put the request on the tracker, see the troubleshooting section at the bottom of this page.
2. Start the server
The default usage for the server is simply:
MsgServer
It starts the server on localhost and on the port 5500.
The help gives:
MsgServer --help
Usage: Default: MsgServer
Compact: MsgServer address:port [max_time]
Standard: MsgServer address port [max_time]
Complete: MsgServer [-a address] [-p port] [-t max_time] [-m max_connections]
Allowed options:
--help Produce help message
-a [ --address ] arg The address of the server (default : localhost)
-p [ --port ] arg The port number of the server (default : 5500)
-t [ --time ] arg The maximum inactivity time in second before the
automatic-shutdown of the server (default : 3600)
-n [ --noLimit ] Deactivate the time limit, the server runs until
shutdown by hand (opposite of time)
-m [ --max-clients ] arg Maximum number of clients that can connect at the
same time (default : 10)It is indeed possible to change the following parameters:
adrress, port on which the server starts
time which is how long the server will wait after the last message before automatically quitting
max_clients which is the number of clients that can be connected at the same time.
To connect the MsgServer over the network the address should be ":<port>" or nothing to connect over the network, not localhost.
3. Use a bridge
3.1. Use OPRS bridge
msgconnector-OPRS-bridge <NAME_OF_HATP> <NAME_OF_MSG_CLIENT> <MSGC_SERV> <NAME_OF_OPRS> <OPRS_SERV> <VERBOSE_MODE>
The parameters are:
<NAME_OF_HATP>: Registered name of hatponboard, usually "HATP".
<NAME_OF_MSG_CLIENT>: Name of this bridge on OPRS's side.
<MSGC_SERV>: The address of msgconnector's server, usually "localhost".*
<NAME_OF_OPRS>: Name of this bridge on HATP's side, should be the name of the OPRS module you want to talk to.
<OPRS_SERV>: The address of OPRS's server.*
<VERBOSE_MODE>: Can be 0 or 1 to toggle the verbose mode (all message processed are printed out).
*: The address can be a hostname like localhost.
3.2. Use ORO bridge
msgconnector-ORO-bridge <NAME_OF_BRIDGE> <MSGC_SERV> <ORO_SERV> <VERBOSE_MODE>
The parameters are:
<NAME_OF_BRIDGE>: The name of this bridge on HATP's side.
<MSGC_SERV>: The address of msgconnector's server, usually "localhost".
<ORO_SERV>: The address of ORO's server.
<VERBOSE_MODE>: Can be 0 or 1 to toggle the verbose mode (all message processed are printed out).
3.3. Use YARP bridge
msgconnector-YARP-bridge <NAME_OF_MSGC> <MSGC_SERV> <NAME_OF_YARPIN> <NAME_OF_YARPOUT> <VERBOSE_MODE>
The parameters are:
<NAME_OF_MSGC>: Name of the HATP's module that will be the target of the bridge messages.
<MSGC_SERV>: The address of msgconnector's server, usually "localhost".
<NAME_OR_YARPIN>: The name of this bridge on HATP's side.
<NAME_OR_YARPOUT>: The name of this bridge on YARP's side.
<VERBOSE_MODE>: Can be 0 or 1 to toggle the verbose mode (all message processed are printed out).
3.4. Use the print bridge
msgconnector-PRINT-bridge <NAME_OF_BRIDGE> <MSGC_SERV>
The parameters are:
<NAME_OF_MSGC>: Name of this bridge.
<MSGC_SERV>: The address of msgconnector's server, usually "localhost".
4. Introduction to the API
This section shows some basic usages to send and receive messages using msgconnector.
4.1. Create a client
The msgconnector API is client based, the server is responsible of transferring the messages. If several clients have the same name they will all receive the messages sent to one, the message transfer is based on the name of the agents.
4.1.1. Add msgconnector to a project
There are two ways to integrate msgconnector to a project: (1) using CMake and find_package, or (2) using pkgconfig. In this section we only show the CMake fashion.
Here is the extract of the CMakeLists.txt:
find_package(msgconnector REQUIRED)
include_directories(${msgconnector_INCLUDE_DIRS})
target_link_libraries(<target> ${msgconnector_LIBRARIES})
However if msgconnector was not installed system wide, for instance if it was installed using robotpkg you will have to specifiy the path to the Findmsgconnector.cmake.
To do so, invoke the CMake executable as follow:
cmake [<OTHER_OPTIONS>] -DCMAKE_MODULES_PATH=<path/to/directory/containing/Findmsgconnector>
If msgconnetor has been installed using robotpkg (as advised) then the path is -DCMAKE_MODULES_PATH=${ROBOTPKG_BASE}/share/cmake/Modules.
4.1.2. Connect a new client
Here is the minimum code to connect to msgconnector with a new client:
#include <iostream>
#include <msgClient.hh>
int main(int argc, char ** argv){
msgClient client;
client.connect(<name>, <server>, <server_port>);
}
When calling connect, the name corresponds to the name of this client, the server can be: an IP address or a hostname (by default use "localhsot") finally the server_port is 5500 by default but can be any port the server listens to.
4.1.3. Send messages and broadcast messages
To send a message there are two options: send a message to a recipient or send a broadcast message. When the message is sent to a recipient, the message is transferred by the server to ALL client with the target name. The broadcast is simply sent to all the clients.
If a message is sent to a recipient not connected, it does not trigger an error, it is supposed a normal behaviour.
Reminder: the message are usually using the JSON format.
To send a message to a recipient:
client.sendMessage(<recipient>, <message>);
To send a broadcast message:
client.sendBroadcastMessage(<message>);
The parameters for both send functions are std::string.
4.1.4. Receive messages
Now that message can be sent, it is time to receive messages. There are three ways to retrieve messages: it is possible to wait for the message (blocking), or wait for the message for a given time (blocking with a timeout) and finally it is possible to directly get a message if present.
4.1.4.1. Wait for a message
Using this solution the code will wait indefinitely for a message to arrive, the only things that can stop it are: a message or the server exiting.
while(client.isConnected()){
std::pair<std::string, std::string> result = client.getBlockingMessage();
std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
}
The pair is composed as follow: <sender, message>. However if the sender is the empty string it means an error occurred, then the message will contain "NOT_CONNECTED" (defined as #define STATUS_DISCONNECTED "NOT_CONNECTED".
4.1.4.2. Wait for a message (with a timeout)
This solution allows to wait for a message for a given time, if the time is exceeded a timeout is returned.
while(client.isConnected()){
std::pair<std::string, std::string> result = client.getMessageTimeout(<time>);
if(result.second==STATUS_TIMEOUT){
std::cout<<"#### Wait timeouted"<<std::endl;
}else{
std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
}
}
The time parameter is expressed in ms. The pair is formed as in blocking message, and again an empty first field means an error: STATUS_DISCONNECTED or STATUS_TIMEOUT.
4.1.4.3. Non-blocking message retrieving
This last solution allows to directly retrieve a message
while(client.isConnected()){
if(client.isMessageWaiting()){
std::pair<std::string, std::string> result = client.getMessage();
std::cout<<"#### Message from "<<result.first<<": "<<result.second<<std::endl;
}
//Something else
}
4.2. Run the example
Once compiled, to execute the code you first need to start the server: see here.
5. Changelog
5.1. Version 2.0.0
- Use libhatp to parse solution plan instead of doing it manually
- Fix automatic exit after an inactivity time
- Message max size in now 96Ko
- Add the tool HATPGoalTester that allow to send a request from command line
- Fix install/uninstall proccesses
Change the name of the repository and the project to msgconnector
- Add "package" target
5.2. Version 2.1.0
- Add install rules for the bridges
5.3. Version 2.2.0
- Improve packaging system
- Fix missing includes (due to update of the compiler)
5.4. Version 2.3.0
Change from epoll to select (allow to compile on NetBSD, ...)
5.5. Version 2.4.0
- Fix compilation in NstBSD
- Change the isConnected test (change in the API behaviour)
- Better error detection in both server and client
- Install Findmsgconnector to help CMake find it
5.6. Version 2.5.0
- Change parameters parsing for the server
5.7. Version 2.6.0
- Update OpenPRS bridge to allow to request the database for the initial state
5.8. Version 2.7.0
- Allow to request the whole OpenPRS database at once
5.9. Version 2.8.0
- Fix the binary installation (and RPATH management)
5.10. Version 2.8.1
- Correct the socket-error detection
5.11. Version 2.8.2
- Allow to start the server without a time limit
5.12. Version 2.8.3
- Add the possibility to send broadcast messages
- Client no longer automatically connect to localhost, possible to specify the server
5.13. Version 2.8.4
Server now binds to all addresses: allow to use msgconnector over network
- Socket is now blocking
5.14. Version 2.9.0
- Add the possibility to wait for a message with a timeout
- Improve the Findmsgconnector.cmake
In print-bridge detect when MsgServer exited
5.15. Version 2.9.1
- Better handling of "isConnected"
5.16. Version 2.10.0
- Fix client bug when server disconnects
5.17. Version 2.11.0
- Port client lib to Windows
5.18. Version 2.11.1
- Fix compilation issue for Windows compiler (Visual Studio)
5.19. Version 2.12.0
- Fix maximum number of connections on the server
5.20. Version 2.13.0
- Client now wait for a ACK/NACK for server
6. License, Troubleshooting and Maintainer
HATP is distributed under 2-clause BSD license. (See here for details.)
The page to report problems or for pull request: Openrobots/msgconnector.
Current maintainer(s):
Raphaël Lallement: raphael.lallement [at] laas.fr, Website.