This tutorial is for OpenJAUS 3.3. OpenJAUS 3.3 is no longer in development or maintainence by the OpenJAUS team. This tutorial is provided for reference and support of legacy systems only. For new development please use OpenJAUS 4.0

JAUS messages are used to communicate information to and from a system component. The OpenJAUS library provides components with a set of functions to send and receive JAUS messages. All messages to and from an OpenJAUS component are in the form of the JausMessage data type. The OpenJAUS message library contains the functions that transform a generic JausMessage into a specific message form, i.e. QueryGlobalPose, ReportComponentStatus, etc. These functions must be used in order to explicitly access the data within a specific JAUS message type. The message library also defines specific data structures for each of the standard JAUS messages, and functions to create and destroy those data structures.

Creating a JAUS message of a specific type is done by invoking its create function. This will allocate the memory required for the message and return the data structure containing the message fields. Each message data structure also contains all of the fields defined for the standard JAUS message header. Creating and setting up a message is done on a type by type basis. The fields for a particular message type can be found by looking at its cooresponding header file in libjaus. This is an example of how to create and setup a ReportGlobalPoseMessage.

 // Declare the message variable
ReportGlobalPoseMessage myReportGposMsg;
 // Create the message
myReportGposMsg = reportGlobalPoseMessageCreate();
 // Clear all presence vector bits
myReportGposMsg->presenceVector = 0;
 // Turn on only latitude and longitude bits
jausUnsignedShortSetBit(&myReportGposMsg->presenceVector, JAUS_POSE_PV_LATITUDE_BIT);
jausUnsignedShortSetBit(&myReportGposMsg->presenceVector,  JAUS_POSE_PV_LONGITUDE_BIT);
 myReportGposMsg->latitudeDegrees = 29.646190;    // Set the latitude of the reported location
myReportGposMsg->longitudeDegrees = -82.349187;  // Set the longitude of the reported location
 

When the component is finished with a message, it simply calls the corresponding destroy() function.

 reportGlobalPoseMessageDestroy(myReportGposMsg);
 

Sending JAUS a message from a component is done by calling the function ojCmptSendMessage(). When this function is called the JAUS message source address is automatically set to that of the sending component's. However, the message destination address must be explicitly set before sending the message. Typically when a specific type of JAUS message needs to be sent, it first must be cast into the generic type form. The sudo-code block below shows the pattern usually implemented to send a specific message. Notice that the jausMessage must be destroyed after it is sent. This is because memory allocated for the jausMessage during the specificMessageToJausMessage() step must be freed after it is no longer needed.

 // Copy destination address into message
jausAddressCopy(mySpecificMessage->destination, someAddress);
 // Convert specific message type into JausMessage type
jausMessage = specificMessageToJausMessage(mySpecificMessage);
 // Send the message via the component and node manager
ojCmptSendMessage(myComponent, jausMessage);
 // Free allocated memory
jausMessageDestroy(jausMessage);
 

Receiving a JAUS message in a component is done by setting up a callback function for the specific message command code. After the OjCmpt is running, the callback function will be invoked upon receiving a message with that command code. If no callback function is registered for a command code, the message is automatically processed by the ojCmptDefaultMessageProcessor() function. This function handles most of the core functionality of a JAUS component. This includes processing incoming commands for authority, state, exclusive control, service connections and discovery (See defaultJausMessageProcessor.c in libopenJaus to identify the implemented command codes and their associated default behavior). If a message is not processed in the default message processor then it is simply ignored. It is possible to override the default message processor by explicitly registering a callback function for the desired command code. If the default behavior needs to be extended, then a registered callback can execute its behavior and also pass the message to ojCmptDefaultMessageProcessor().

Message callback functions must follow the prototype form "void callbackname(OjCmpt, JausMessage);". Registration of the callback function with the component is usually done between the ojCmptCreate() step and the ojCmptRun() step (See Creating an OpenJAUS component for details on these steps). The function to register the message callback is ojCmptSetMessageCallback(). The following example shows how this would be done for a JAUS_QUERY_GLOBAL_POSE message.

 // Function prototype of message callback
void myQueryGlobalPoseCallback(OjCmpt myGpos, JausMessage queryMessage);
 // Register the callback function with the myGpos component
ojCmptSetMessageCallback(myGpos, JAUS_QUERY_GLOBAL_POSE, myQueryGlobalPoseCallback);
 

The message callback function implementation is responsible for converting the JausMessage type into the type of the specific message. The following example shows how the response to a query GPOS message might be implemented.

 // Query global pose message callback function
void myQueryGlobalPoseCallback(OjCmpt myGpos, JausMessage message)
{
 JausMessage txMessage;
  // Parse the message into its queryGloablPose message form
 QueryGlobalPoseMessage queryGlobalPose;
 queryGlobalPose = queryGlobalPoseMessageFromJausMessage(message);
  // Verify there are no errors in parsing
 if(queryGlobalPose)
 {
  // Copy the source to destination
  jausAddressCopy(myReportGposMsg->destination, queryGlobalPose->source);
   // Serialize the report global pose message response
  txMessage = reportGlobalPoseMessageToJausMessage(myReportGposMsg);
   // Send the report response
  ojCmptSendMessage(myGpos, txMessage);
   // Destroy the sent JausMessage
  jausMessageDestroy(txMessage);
   // Destroy the query message
  queryGlobalPoseMessageDestroy(queryGlobalPose);
 }
 else
 {
  printf("Error unpacking JAUS_QUERY_GLOBAL_POSE\n");
 }
}