uFldMessageHandler: Handling Incoming Node Messages
Maintained by: mikerb@mit.edu Get PDF
1 Overview
2 Typical Application Topology
3 Inter-vehicle Messaging Sequence of Events
4 Building an Outgoing Node Message
5 Building an Outgoing Node Message - A Note of Caution
6 Event Flags
7 Configuration Parameters of uFldMessageHandler
7.1 Variables Published
7.2 Variables Subscriptions
8 Command Line Usage of uFldMessageHandler
9 Terminal and AppCast Output
1 Overview
The uFldMessageHandler application handles incoming messages from a remote MOOSDB. In MOOS, applications "talk" to each other through the normal publish-subscribe means of a common MOOSDB. Distinct robots or vehicles can also share information between vehicles and MOOSDBs using pShare. But often we want to simulate inter-vehicle messaging where messages are sometimes dropped, and messages are subject to inter-vehicle range limitations, band-width limitations, and limitations on message frequency. To simulate this we use the uFldNodeComms and uFldMessageHandler apps in concert. A message meant for another vehicle is packaged up in a format containing the message itself and a bit of routing information. The receiving vehicle, running uFldMessageHandler, unpacks the message and injects the message to the local vehicle by posting to the local MOOSDB. The job of routing and applying communications limitations is done by uFldNodeComms and is not the focus here. The sole job of uFldMessageHandler is to do the message unpacking and posting of information, while also keeping some stats for debugging if needed.
2 Typical Application Topology
In the uField Toolbox typical arrangement, messages arrive from a shoreside MOOS community running uFldNodeComms and pShare as shown below in Figure 2.1.
Figure 2.1: Typical uFldMessageHandler Topology: A vehicle (node) sends a message to another vehicle by wrapping the message content and addressee information in a single string sent to the shoreside. On the shoreside, the uFldNodeComms application redirects the message to the appropriate vehicle(s). The message is received on the vehicle by the uFldMessageHandler application which parses the MOOS variable and the variable value from the string and posts the variable-value pair to the local MOOSDB.
3 Inter-vehicle Messaging Sequence of Events
The functionality of uFldMessageHandler may be paraphrased:
- A source vehicle alpha wishes to send a message to vehicle bravo of the form SPEED=2.5.
- A local message is posted on vehicle alpha of the form:
NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=SPEED,double_val=2.5
- The above message is shared from alpha to the shoreside community using pShare.
- The message is received in the shoreside community as the variable NODE_MESSAGE and handled by uFldNodeComms and republished as NODE_MESSAGE_BRAVO.
- The message is then shared out to bravo using pShare arriving in vehicle bravo as NODE_MESSAGE.
- On vehicle bravo, the NODE_MESSAGE is handled by uFldMessageHandler. The source variable and value are parsed and a post to the local MOOSDB on bravo is made, SPEED=2.5
- A scope on the MOOSDB on bravo would show the source of the SPEED=2.5 posting to be "uFldMessageHandler", and the auxiliary source would show "alpha"
4 Building an Outgoing Node Message
To construct an outgoing node message, there are two options. A message can be created through normal string construction, for example:
string m_hostname; // previously set name of ownship string m_dest_name; // previously set name of vehicle to communicate string m_moos_varname; // previously set name of MOOS variable to send string m_msg_contents; // previously set contents of message; string msg; msg += "src_node=" + m_hostname; msg += ",dest_node=" + m_dest_name; msg += ",var_name=" + m_moos_varname; msg += ",string_val=" + m_msg_contents; Notify("NODE_MESSAGE_LOCAL", msg);
The above works, but may be prone to typos and may not be very "future-proof" if the format for inter-vehicle messaging changes. Another way to accomplish this is to use the NodeMessage class which has the serializing and de-serializing steps implemented:
#include "NodeMessage.h" // In the lib_ufield library string m_hostname; // previously set name of ownship string m_dest_name; // previously set name of vehicle to communicate string m_moos_varname; // previously set name of MOOS variable to send string m_msg_contents; // previously set contents of message; NodeMessage node_message; node_message.setSourceNode(m_hostname); node_message.setDestNode(m_dest_name); node_message.setVarName(m_moos_varname); node_message.setStringVal(m_msg_contents); string msg = node_message.getSpec(); Notify("NODE_MESSAGE_LOCAL", msg);
In the opposite direction, creating a NodeMessage instance from a string is done with:
#include "NodeMessageUtils.h" // In the lib_ufield library string node_message_str; // previously set string containing a message NodeMessage node_message = string2NodeMessage(node_message_str);
Note that the NodeMessage class is part of the lib_ufield library. The uFldMessageHandler app links to this library, but if the above class is being used in a new app, to create a message, the lib_ufield library needs to be linked as part of the build process of the new app.
5 Building an Outgoing Node Message - A Note of Caution
Note the structure of a node message, such as the one below, uses commas as component delimiters:
NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=SPEED,double_val=2.5
Some care must be taken if the contents of the outgoing message is a string also containing commas, such as:
NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=INFO,string_val=good,bad,ugly
In this case the string contents should be wrapped in double quotes:
NODE_MESSAGE_LOCAL = src_node=alpha,dest_node=bravo,var_name=INFO,string_val="good,bad,ugly"
If the message is built using the NodeMessage class as in the second example in Section 4 above, the double quotes are added automatically in the setStringVal() function if the argument is not quoted and it contains a comma.
6 Event Flags
With the optional msg_flag and bad_msg_flag, the user may configure events (postings) to be made whenever an incoming message results in a successful posting, and whenever an incoming message does not result in a posting.
The msg_flag is configured with variable-value pair, for example:
msg_flag = GOOD_POSTING=true
Likewise, the bad_msg_flag is configured with variable-value pair, for example:
bad_msg_flag = FAILED_POSTING=true
The value component of any posting may contain one or more of several supported macros. A macro is expanded at the time of posting. Supported macros include:
- $[CTR]: The total of all received messages, regardless of whether a message resulted in a posting.
- $[GOOD_CTR]: The total of all received messages that resulted in a posting.
- $[BAD_CTR]: The total of all received messages that did not result in a posting.
Of course multiple postings may be configured. For example:
msg_flag = GOOD_POSTING=true
msg_flag = POSTING_COUNT=$[CTR]
7 Configuration Parameters of uFldMessageHandler
The following parameters are defined for uFldMessageHandler.
Listing 7.1 - Configuration parameters for uFldMessageHandler.
appcast_trunc_msg: | Number of characters allowed in the appcast report for each line reporting a successful message. For example, Lines 19-24 in Listing 9.1. The default is 75. Setting it to zero means no truncating will be applied. |
strict_addressing: | If true, only messages with a destination specified by dest_node, matching the local community name are processed. Other messages with a destination specified by a group designation are ignored. The default is false. |
msg_flag: | A variable-value pair posted upon receipt of a valid, un-rejected incoming message and posting to the MOOSDB. Section 6. |
bad_msg_flag: | A variable-value pair posted upon receipt of a valid, but rejected incoming message. Section 6. |
aux_info: | Adjust the content of the source auxilliary field. By default this is set to "node". If set to "node+app", the source auxialliary field of posted messages will contain both the sending node and the sending app. |
An Example MOOS Configuration Block [top]
Listing 7.2 shows an example MOOS configuration block produced from the following command line invocation:
$ uFldMessageHandler --example or -e
Listing 7.2 - Example configuration of the uFldMessageHandler application.
1 ===============================================================
2 uFldMessageHandler Example MOOS Configuration
3 ===============================================================
4
5 ProcessConfig = uFldMessageHandler
6 {
7 AppTick = 4
8 CommsTick = 4
9
10 strict_addressing = false // the default
11 appcast_trunc_msg = 75 // default: the number of chars per
12 // line in the appcasting output
13
14 msg_flag = RETURN=true
15 bad_msg_flag = TOTAL_BAD=$[BAD_CTR]
16
17 aux_info = node+app // {node or node+app} Default is node
18
19 app_logging = true // {true or file} By default disabled
20 }
7.1 Variables Published [top]
The primary output of uFldMessageHandler to the MOOSDB are the messages posted by parsing incoming NODE_MESSAGE postings. A summary is also posted periodically to recap message handling totals.
- APPCAST: Contains an appcast report identical to the terminal output. Appcasts are posted only after an appcast request is received from an appcast viewing utility. Section 9.
- UMH_SUMMARY_MSGS: A summary of total messages, valid messages and rejected messages handled thus far. An example: UMH_SUMMARY_MSGS=total=3,valid=3,rejected=0
Further publications will be made if the app is configure with any msg_flag or bad_msg_flag flags. For example if configured with msg_flag=POSTING=$[CTR]
, the variable POSTING will be posted each time uFldMessageHhandler posts an incoming message. The value of POSTING will be the total number of messages posted by uFldMessageHandler thus far.
7.2 Variables Subscriptions [top]
The uFldMessageHandler application subscribes to the following MOOS variables:
- APPCAST_REQ: A request to generate and post a new apppcast report, with reporting criteria, and expiration.
- NODE_MESSAGE: Incoming node messages.
8 Command Line Usage of uFldMessageHandler
The uFldMessageHandler application is typically launched with pAntler, along with a group of other vehicle modules. However, it may be launched separately from the command line. The command line options may be shown by typing:
$ uFldMessageHandler --help or -h
Listing 8.1 - Command line usage for the uFldMessageHandler tool.
1 =============================================================== 2 Usage: uFldMessageHandler file.moos [OPTIONS] 3 =============================================================== 4 5 SYNOPSIS: 6 ------------------------------------ 7 The uFldMessageHandler tool is used for handling incoming 8 messages from other nodes. The message is a string that 9 contains the source and destination of the message as well as 0 the MOOS variable and value. This app simply posts to the 11 local MOOSDB the variable-value pair contents of the message. 12 13 Options: 14 --alias=<ProcessName> 15 Launch uFldMessageHandler with the given process name 16 rather than uFldMessageHandler. 17 --example, -e 18 Display example MOOS configuration block. 19 --help, -h 10 Display this help message. 21 --interface, -i 22 Display MOOS publications and subscriptions. 23 --version,-v 24 Display the release version of uFldMessageHandler. 25 --web,-w 26 Open browser to: 27 https://oceanai.mit.edu/ivpman/apps/uFldMessageHandler 28 29 Note: If argv[2] does not otherwise match a known option, 30 then it will be interpreted as a run alias. This is 31 to support pAntler launching conventions.
9 Terminal and AppCast Output
The uFldMessageHandler application produces some useful information to the terminal and identical content through appcasting. An example is shown in Listing 9.1 below. On line 2, the name of the local community or vehicle name is listed on the left. On the right, "0/0(841) indicates there are no configuration or run warnings, and the current iteration of uFldMessageHandler is 841. In lines 4-9, general tallies are shown of received, invalid, and rejected messages. In lines 11-15, the tallies for received messages sorted by source vehicle are shown. The variable-value columns reflect only the last received message.
Listing 9.1 - Example appcast and terminal output of uFldMessageHandler.
1 =================================================================== 2 uFldMessageHandler gilda 0/0(841) 3 =================================================================== 4 Overall Totals Summary 5 ====================================== 6 Total Received Valid: 5 7 Invalid: 0 8 Rejected: 0 9 Time since last Msg: 101.3 10 11 Per Source Node Summary 12 ====================================== 13 Source Total Elapsed Variable Value 14 ------ ----- ------- -------- ----- 15 henry 5 101.3 RETURN true 16 17 Last Few Messages: (oldest to newest) 18 ====================================== 19 Valid Mgs: 20 src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed 21 src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed 22 src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed 23 src_node=henry,dest_node=gilda,var_name=UPDATE_LOITER,string_val=speed 24 src_node=henry,dest_node=gilda,var_name=RETURN,string_val=true 25 Invalid Mgs: 26 NONE 27 Rejected Mgs: 28 NONE
The information group starting on line 17 shows the last five received valid, invalid and rejected messages. Note that a rejected message may be rejected for being invalid, or if the destination field doesn't match, or if strict addressing is enabled and there is not a precise destination field match.
Document Maintained by: mikerb@mit.edu
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF