JAUS Services Protocol Behavior

All JAUS services are described by a JAUS Service Definition (JSD) which specifies the message set and protocol required for compliance. Each JSD is fully compliant with the JAUS Service Interface Definition Language [JSIDL].

Obtaining the SAE JAUS Service Set documents is strongly recommended in order to properly design for JAUS compliance.

Information on obtaining JAUS Service Set documents can be found here:

Obtaining JAUS Service Set documentation


There are essentially three types of messages related to a service.

  • Commands (Set)
  • Requests (Query)
  • Responses (Report, Confirm)


The message protocol for each service describes how the messages should be initiated and what actions they should perform.

The protocol will consist of three parts.

  • Trigger - An incoming message (Command or Request)
  • Actions - Activity to perform. (Provide a Response, setting of values to be used by the robot)
  • Guard -  Set of conditions that need to be true in order to implement the Action


The basic flow of a protocol is that when a message is received (Trigger) a set of conditions (Guard) may need to be met and then some activity (Action) is performed that is related to the incoming message.


The Digital Audio service is a good example of a service that has a protocol consisting of Triggers that have multiple Guards and multiple Actions for an associated Trigger.

The RAS-G IOP V2 - Overarching Profile Custom Services, Messages, Transports document provides details about this service.

The Digital Audio service will utilize theses messages:

  • SetDigitalAudioConfiguration
  • QueryDigitalAudioCapabilities
  • QueryDigitalAudioConfiguration
  • SetDigitalAudioConfigurationResponse
  • ReportDigitalAudioCapabilities
  • ReportDigitalAudioConfiguration


When viewing a JAUS Service Set document there will be a Protocol Behavior section for each service described in the document.

The Protocol Behavior section will describe the protocol behavior using a tabular format similar to the following:



   Digital Audio Service State Transitions

Trigger    
Guard
Actions
QueryDigitalAudioCapabilities
NONE
sendReportDigitalAudioCapabilities
QueryDigitalAudioConfiguration
NONE
sendReportDigitalAudioConfiguration
SetDigitalAudioConfiguration
isControllingClient && isValidCommand && isValidSensor
setConfiguration, sendSetDigitalAudioConfigurationResponseSuccess
SetDigitalAudioConfiguration
isControllingClient && !isValidSensor
sendSetDigitalAudioConfigurationResponseSensorNotFound
SetDigitalAudioConfiguration
isControllingClient && !isValidCommand
sendSetDigitalAudioConfigurationResponseUnsupported


Digital Audio Service Guards

Guard
Interpretation
isControllingClient && isValidCommand && isValidSensor
True if the command message was received from the client currently controlling this component AND all sensor IDs specified by the message are valid AND all configuration elements specified by the messages are valid.
isControllingClient && !isValidSensor
True if the command message was received from the client currently controlling this component AND NOT all sensor IDs specified by the message are valid.
isControllingClient && !isValidCommand
True if the command message was received from the client currently controlling this component AND NOT all configuration elements specified by the message are valid.


Digital Audio Service Transition Actions

Action
Interpretation
sendReportDigitalAudioCapabilities
Send a ReportDigitalAudioCapabilities message to querying client
sendReportDigitalAudioConfiguration
Send a ReportDigitalAudioConfiguration message to querying client
setConfiguration
Changes the current configuration for the given sensors
sendSetDigitalAudioConfigurationResponseSuccess
Send a sendSetDigitalAudioConfigurationResponseSuccess message to querying client
sendSetDigitalAudioConfigurationResponseSensorNotFound
Send a sendSetDigitalAudioConfigurationResponseSensorNotFound message to querying client
sendSetDigitalAudioConfigurationResponseUnsupported
Send a sendSetDigitalAudioConfigurationResponseUnsupported message to querying client



OpenJAUS Implementation of JAUS Services Protocol

When the OpenJAUS SDK is used to implement JAUS services the services protocol is implemented automatically.

The SDK will receive incoming JAUS messages (Triggers), call the appropriate Guard methods and then call the appropriate Action methods if the Guard conditions are met.


  • Triggers - The SDK will receive these messages and pass the message object to the Action method associated with the Trigger.


  • Guards - The SDK will automatically call the appropriate Guard for the incoming Trigger. The isControllingClient method is already implemented by the SDK. Other Guards, such as isValidSensor, are robot specific and need to be implemented by the developer. Some services have different Guards than those mentioned for the Digital Audio service. The developer should refer to the SDK service class definitions to determine if there is a Guard method that requires implementation. Keep in mind that while a Guard method may need to be implemented it would not need to be called by another developer implemented method. The SDK will call the Guard methods automatically.


  • Actions - The SDK will automatically call an Action method when its corresponding Trigger message is received and any required Guard conditions have been met. The incoming message object will be passed to the Action method. A developer will need to implement the Action method and use the passed message object for information on how to perform the requested action. 
    • Capabilities & Configuration messages - A Report Capabilities message is used to indicate what elements of a service a robot is capable of performing. A Report Configuration message is used to indicate what the current state, performance level,  operational mode (etc.) that the elements of a service are at. Therefore, it is important that the Report Configuration message provide information that matches the information provided by any previous Report Capabilities message. The Report Configuration message should not report the presence of an service element that was not designated as available in a Report Capabilities message.