<<PackageHeader(master_discovery_fkie)>> <<TOC(4)>>

== Overview ==
This package contains discovery nodes to detect a ROS master in a multi robot system. There are currently two nodes 'master_discovery' and 'zeroconf' which uses different discovery strategies. 'zeroconf' node uses an avahi implementation of zeroconf technique. The 'master_discovery' node sends periodically a multicast message to notify about an available ROS master.  Furthermore the ROS master will be monitored for changes. On changes other discovery nodes are notified using a timestamp. This feature is used e.g. by [[http://www.ros.org/wiki/master_sync_fkie|master_sync]] to syncronize the ROS masters. Moreover an XML-RPC server created by a discovery node helps to avoid a lot of requests on remote ROS master for a synchronization.

== Usage ==
=== Getting started ===
Although the nodes are written in Python we need to generate message and service types:

{{{{#!wiki version fuerte electric
{{{
rosmake master_discovery_fkie
}}}
}}}}
{{{{#!wiki version groovy hydro indigo
{{{
catkin_make
}}}
}}}}
Run the node:

{{{
rosrun master_discovery_fkie master_discovery
}}}
To use `zeroconf` for discovering you need to run:

{{{
rosrun master_discovery_fkie zeroconf
}}}
''In this case you have to install `python-avahi` and `avahi-daemon`!''

=== Interface ===
{{{{#!wiki version fuerte electric
{{{
#!clearsilver CS/NodeAPI
pub {
0.name = ~changes
0.type = master_discovery_fkie/MasterState
0.desc = Description of the ROS master
1.name = ~linkstats
1.type = master_discovery_fkie/LinkStatesStamped
1.desc = The list with links and their quality, determined from packet loss. Not available if using `zeroconf` node.
}
srv {
0.name = ~list_masters
0.type = master_discovery_fkie/DiscoverMasters
0.desc = The list with all known ROS masters and their description
}
param {
0.name = ~name
0.type = String
0.desc = The name of the ROS master
0.default = `hostname`

1.name = ~rpc_port
1.type = int
1.desc = The port number for XML-RPC server created by the node.
1.default = `11611`
2.name = ~rosmaster_hz
2.type = int
2.desc = The test rate of ROS master state in `Hz`.
2.default = `1`
3.name = ~heartbeat_hz
3.type = int
3.desc = The send rate of the heartbeat packets in `Hz` '''(only for `master_discovery` node)'''.
3.default = `2`

4.name = ~mcast_group
4.type = String
4.desc = The IPv4 multicast group used for discovery '''(only for `master_discovery` node)'''.
4.default = "226.0.0.0"
5.name = ~mcast_port
5.type = int
5.desc = The port number of the socket used for discovery '''(only for `master_discovery` node)'''.
5.default = `11511`

6.name = ~static_hosts
6.type = list
6.desc = The list of hosts wich are pinged using a unicast messages '''(only for `master_discovery` node)'''. /!\ This can lead to a high load on the network!
6.default = `[]`

}
}}}
}}}}
{{{{#!wiki version groovy hydro indigo jade kinetic melodic
{{{
#!clearsilver CS/NodeAPI
pub {
0.name = ~changes
0.type = multimaster_msgs_fkie/MasterState
0.desc = Description of the ROS master
1.name = ~linkstats
1.type = multimaster_msgs_fkie/LinkStatesStamped
1.desc = The list with links and their quality, determined from packet loss. Not available if using `zeroconf` node.
}
srv {
0.name = ~list_masters
0.type = multimaster_msgs_fkie/DiscoverMasters
0.desc = The list with all known ROS masters and their description
1.name = ~refresh
1.type = std_srvs/Empty
1.desc = Let the master discovery send heartbeat requests to update the neighbors
}
param {
0.name = ~name
0.type = String
0.desc = The name of the ROS master
0.default = `hostname`

1.name = ~rpc_port
1.type = int
1.desc = The port number for XML-RPC server created by the node.
1.default = `11611`

2.name = ~rosmaster_hz
2.type = int
2.desc = The test rate of ROS master state in `Hz`.
2.default = `1`

3.name = ~heartbeat_hz
3.type = int
3.desc = The send rate of the heartbeat packets in `Hz` '''(only for `master_discovery` node)'''.
3.default = `2`

4.name = ~mcast_group
4.type = String
4.desc = The IPv4 multicast group used for discovery. You can bind to defined interface by adding @address to the group. '''(only for `master_discovery` node)'''.
4.default = "226.0.0.0"

5.name = ~mcast_port
5.type = int
5.desc = The port number of the socket used for discovery '''(only for `master_discovery` node)'''.
5.default = `11511`

51.name = ~interface
51.type = str
51.desc = Bind the master_discovery to an interface address. If this is not specified the ROS_IP or default interface will be used. '''(only for `master_discovery` node)'''
51.default = ``

6.name = ~robot_hosts (since v0.4.0)
6.type = list
6.desc = The list of hosts to request a heardbeat message using a unicast messages. Unlike `static_host` this parameter is set on control station.  '''(only for `master_discovery` node)'''. /!\ This can lead to a high load on the network!
6.default = `[]`

7.name = ~static_hosts (until v0.4.0)
7.type = list
7.desc = The list of hosts wich are pinged using a unicast messages '''(only for `master_discovery` node)'''. /!\ This can lead to a high load on the network!
7.default = `[]`

8.name = ~remove_after
8.type = float
8.desc = remove an offline host after this time in [sec]
8.default = `300.0`

9.name = ~active_request_after
9.type = float
9.desc = send an update request, if after this time no hearbeats are received [sec] '''(only for `master_discovery` node)'''
9.default = `60.0`

10.name = ~send_mcast
10.type = bool
10.desc = disables the send of multicast messages. '''(only for `master_discovery` node)'''
10.default = `True`

11.name = ~listen_mcast (since v0.7.0)
11.type = bool
11.desc = disables the listening to multicast messages. If listen_mcast and send_mcast are False, only unicast socket will be created. '''(only for `master_discovery` node)'''
11.default = `True`

}
}}}
}}}}
== XML-RPC API ==
`masterContacts()`

 . Retrieve the contact information of the ROS master and remote discovery node.
 <<BR>> ''Parameters''
  . `empty`
 ''Returns''
  . `[str, str, str, str, str]`
   . (timestamp of the ROS master state, ROS master URI, master name, name of this service, URI of this RPC server)

`masterInfo()`

 . Retrieve list representation of ''complete'' ROS system state (i.e. publishers, subscribers, services and their types, URI's). <<BR>> ''Parameters''
  . `empty`
 ''Returns''
  . `(float, float, str, str,`
   . `[ [str,[str] ] ],`  `[ [str,[str] ] ],` `[ [str,[str] ] ],`  `[ [str,str] ],` `[ [str,str,str,int,str] ],` `[ [str,str,str,str,str] ])`
   . (stamp, stamp of local changes, masteruri, name, publishers, subscribers, services, topicTypes, nodes, serviceProvider)
   <<BR>>     System state is in list representation:
   {{{
[stamp, stamp of local changes, masteruri, name, publishers, subscribers, services, topicTypes, nodes, serviceProvider]
}}}
   `publishers` is of the form:
   {{{
[ [topic1, [topic1Publisher1...topic1PublisherN]] ... ]
}}}
   `subscribers` is of the form:
   {{{
[ [topic1, [topic1Subscriber1...topic1SubscriberN]] ... ]
}}}
   `services` is of the form:
   {{{
[ [service1, [service1Provider1...service1ProviderN]] ... ]
}}}
   `nodes` is of the form:
   {{{
[ [topicName1, topicType1], ... ]
}}}
   `topicTypes` is of the form:
   {{{
[ [nodename, XML-RPC URI, origin ROS_MASTER_URI, pid, {str(local) or str(remote)} ], ... ]
}}}
   `serviceProvider` is of the form:
   {{{
[ [service, XML-RPC URI, origin ROS_MASTER_URI, type, {str(local) or str(remote)} ], ... ]
}}}

## AUTOGENERATED DON'T DELETE
## CategoryPackage