## Set some parameters for the page
#pragma section-numbers 2
#pragma keywords HATP, hatp, htn planning, hatpconsole, hatptester
#pragma description Homepage for HATP software, an open-source HTN task planner



= --DEPRECATED-- msgconnector, HATP's middleware --DEPRECATED-- =

||<bgcolor="#FF5555"> 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.

||<bgcolor="#EEEEFF"> <<TableOfContents(3)>>||

/!\ '''The way to install msgconnector is described in [[HATP/install]].'''



== 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 [[http://en.wikipedia.org/wiki/JSON|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.''








== Start the server ==
<<Anchor(start-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.





== Use a bridge ==

=== Use OPRS bridge ===
<<Anchor(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`.

=== Use ORO bridge ===
<<Anchor(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).

=== Use YARP bridge ===
<<Anchor(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).

=== Use the print bridge ===
<<Anchor(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`".




== Introduction to the API ==

This section shows some basic usages to send and receive messages using msgconnector.

=== 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.

==== 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:
{{{#!highlight cmake numbers=disable
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`.

==== Connect a new client ====

Here is the minimum code to connect to msgconnector with a new client:
{{{#!highlight c++ numbers=disable
#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.

==== 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 [[http://en.wikipedia.org/wiki/JSON|JSON format]].

To send a message to a recipient:
{{{#!highlight c++ numbers=disable
client.sendMessage(<recipient>, <message>);
}}}

To send a broadcast message:
{{{#!highlight c++ numbers=disable
client.sendBroadcastMessage(<message>);
}}}

The parameters for both send functions are `std::string`.

==== 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.

===== 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.

{{{#!highlight c++ numbers=disable
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"`.

===== 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.

{{{#!highlight c++ numbers=disable
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`.

===== Non-blocking message retrieving =====

This last solution allows to directly retrieve a message

{{{#!highlight c++ numbers=disable
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
}
}}}

=== Run the example ===

Once compiled, to execute the code you first need to start the server: see [[#start-server|here]].


== Changelog ==

=== 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

=== Version 2.1.0 ===

 * Add install rules for the bridges

=== Version 2.2.0 ===

 * Improve packaging system
 * Fix missing includes (due to update of the compiler)

=== Version 2.3.0 ===

 * Change from epoll to '''select''' (allow to compile on NetBSD, ...)

=== 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

=== Version 2.5.0 ===

 * Change parameters parsing for the server

=== Version 2.6.0 ===

 * Update OpenPRS bridge to allow to request the database for the initial state

=== Version 2.7.0 ===

 * Allow to request the whole OpenPRS database at once

=== Version 2.8.0 ===

 * Fix the binary installation (and RPATH management)

=== Version 2.8.1 ===

 * Correct the socket-error detection

=== Version 2.8.2 ===

 * Allow to start the server without a time limit

=== Version 2.8.3 ===

 * Add the possibility to send broadcast messages
 * Client no longer automatically connect to localhost, possible to specify the server

=== Version 2.8.4 ===

 * Server now binds to all addresses: allow to use '''msgconnector over network'''
 * Socket is now blocking

=== 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

=== Version 2.9.1 ===

 * Better handling of "isConnected"

=== Version 2.10.0 ===

 * Fix client bug when server disconnects

=== Version 2.11.0 ===

 * Port client lib to Windows

=== Version 2.11.1 ===

 * Fix compilation issue for Windows compiler (Visual Studio)

=== Version 2.12.0 ===

 * Fix maximum number of connections on the server

=== Version 2.13.0 ===

 * Client now wait for a ACK/NACK for server


== License, Troubleshooting and Maintainer ==

HATP is distributed under 2-clause BSD license. ([[http://opensource.org/licenses/BSD-2-Clause|See here for details.]])

The page to report problems or for pull request: [[https://git.openrobots.org/projects/msgconnector|Openrobots/msgconnector]].

Current maintainer(s):
 * '''Raphaël Lallement''': [[mailto:raphael.lallement [at] laas.fr|raphael.lallement [at] laas.fr]], [[http://homepages.laas.fr/rlalleme|Website]].
##Later can use <<MailTo(raphael DOT lallement AT laas DOT fr)>>