OpenJAUS

A major portion of the JAUS specification is implemented by the use of service oriented architectures. These services are defined by the JAUS Service Interface Definition Language (JSIDL). A JAUS service will be represented by a set of messages (input and output messages).

Detailed information about JSIDL and JAUS messaging transporting can be found in theses documents:

    AS5684A - JAUS Service Interface Definition Language

    AS5669A - JAUS_SDP Transport Specification

These documents can be obtained from the Society of Automotive Engineers (SAE).

    Obtaining SAE JAUS documentation

The most efficient means to implement a JAUS service, and its messages, is to refer to the JAUS Service Set document that describes the desired service.

The intent of this article is to provide a better understanding of JAUS services and their messages by providing guidance on how o read and interpret the JAUS Service Set documents.

Reading and Interpreting JAUS Service Set Documents

The content layout of a JAUS Service Set document will vary depending upon which document is being viewed.

There are two types of layouts both of which provide the same information but organized differently.

Layout 1.

Section: SERVICE DEFINITIONS

            Contains subsections that provide a textual definition for each Service Definition for a specific JAUS Service Set.

            Each subsection consist of the following:

                Service Name

                    Description

                    Assumptions

                    Vocabulary

                    Protocol Behavior

Section: DECLARED TYPES

            Contains three subsections that describe the messages related to services.

            The subsections are:

                CommandClass

                QueryClass

                InformClass

Layout 2. 

Section: SERVICE DEFINITIONS

              Contains subsections that provide a textual definition for each Service Definition for a specific JAUS Service Set.

              Each subsection consist of the following:

                Service Name

                    Description

                    Assumptions

                    Vocabulary

                    Encoding

                        Input Set

                        Output Set    

                    Protocol Behavior

The section DECLARED TYPES and subsection Encoding provide the same type of information.

Service Name

This heading provides the name and version level of the service.

It also provides a graphical representation of what other services might be inherited. This is useful for determining if the service is a controlled and/or managed service.

Description

The heading provides information about what the overall objective of the particular service is. 

Assumptions

The heading will list any assumptions about the operation of the service or how the messages might interact in the transport level.

Vocabulary

This heading provides a list of the messages associated with the service. The list is typically segregated into Input Set and Output Set messages along with an indication as to of the message is a command or not.

Encoding or DECLARED TYPES

This heading(Encoding) or section(DECLARED TYPES) provides a detailed description about the purpose and operation of the message. This information should be reviewed thoroughly in order to derive a concise understanding of how to use the message.

The heading or section will also provide details about how the body of the message is constructed.

A message is comprised of different field types and it is these fields that describe the encoded data.

The fields are classified as the following:

Fields

• Composite Fields
  • array
  • record
  • list
  • variant
  • sequence
• Simple Fields
  • Primitive Fields
    • fixed_field
    • variable_field
    • bit_field
  • String Fields
    • fixed_length_string
    • variable_length_string
  • BLOB Fields
    • variable_length_field
    • variable_format_field
• Meta Fields
  • count_field
  • vtag_field
  • format_field
  • presence_vector
  • type and units field

For detailed information on these fields the AS5684A - JAUS Service Interface Definition Language document should be referenced.

The scope of this article will focus only on the following fields:

• Composite Fields
  • record
  • list
  • variant
  • sequence
• Meta Fields
  • count_field
  • vtag_field
  • presence_vector

Composite Fields

Composite Fields are containers that provide a means to create complex data structures by combining a set Simple Fields in various ways. The body of a message may contain a single composite field or multiple combinations of composite fields.

Sequence

A sequence represents an arrangement of one or more Composite Fields leading to a heterogeneous or homogeneous sequence. A message body may define a sequence within another sequence sequence and can be optional at runtime. This is denoted by the boolean attribute named optional. When set true, the sequence may not be included in the container sequence if it is not required.

The Composite Fields contained within a sequence can be optional at runtime. If any of the composite fields within a sequence are specified as being optional, the sequence will have a Meta Field called the presence_vector as its first field. This Meta Field is used to indicate the presence or absence of the optional Composite Fields within the record.

Message Body Layout Example

Body

               sequence 1

                                (presence_vector)

                                record (optional)

                  variant

                        record

                        record

                            sequence 2 (optional)

            list

                        record

Record

A record represents an arrangement of one or more Simple Fields leading to a heterogeneous or homogeneous set that is ordered.

The Simple Fields contained within a record can be optional at runtime. If any of the Simple Fields within a record are specified as being optional, the record will have a Meta Field,  presence_vector, as its first field. This Meta Field is used to indicate the presence or absence of the optional Simple Fields within the record.

The record has a name attribute that is required, and an optional interpretation attribute that may be used to provide a brief textual interpretation for the record. The name of the record must be a valid identifier and must be unique within the scope of the encapsulating body or list parent element.

A record defined within a sequence can be optional at runtime. This is specified by the boolean attribute called optional. If this attribute is set to true, the entire record may not be included in the sequence if it is not required.

List
A list field represents a variable sized sequence of Composite fields of the same type. The size of the sequence is determined at runtime from the value a Meta field called count_field which is the first field in the list.
A list defined within a sequence can be optional at runtime. This is specified by the boolean attribute called optional. If this attribute is set to true, the entire list may not be included in the sequence if it is not required.

Variant
A variant field represents a composite field that can hold zero or one of several different types of pre-defined composite fields at runtime. The pre-defined set of composite fields are specified as a sequence and the type of field contained within the variant at runtime is determined from the value in a Meta field called the vtag_field which is the first field in the variant. If the nth composite field in the sequence is chosen, then the value of the vtag_field must be set to n, where n=0 if the first composite field in the sequence is chosen at runtime.

This essentially means that when a variant is in the message body, any one of the Composite fields under the variant may be present in the message. The vtag_field value will denote which Composite Field is present.

count_field

This value denotes the size of the Composite or Simple Field that it is associated with.

vtag_field
The vtag_field specifies the index of the chosen Composite Field from the sequence of Composite Fields within a variant.

presence_vector
The presence_vector is an optional field that is used in a record and a sequence. When used, it will be the first field within the record or sequence. It is used to indicate the presence or absence of optional Simple Fields when used in a record, or groups of Simple Fields (encapsulated in a record, list, variant or a sub-sequence) when used in a sequence.

The presence_vector is a bit field where each bit indicates the presence or absence of a record (when used in a sequence) or of a simple field (when used in a record).

Example of presence_vector used in a sequence

Body

       sequence

             (presence_vector = unsigned byte))

             record_1 (optional)

             record_2 (optional)

             record_3

A presence_vector value of 00000011 indicates that record_1 & record_2 are present in the message. The record_3 is present always as it is not listed as optional.

A presence_vector value of 00000001 indicates that only the optional record record_1 is present. The record_3 is present always as it is not listed as optional.

Example of presence_vector used in a record

For this record even though there 4 elements in the record only bits 1,2 and 3 of the presence_vector are valid because the optional attribute of Element_1 is set to false.

The presence_vector will denote which of the elements of the records that has its optional attribute set to true will have a valid value in the message. The absence of a bit does not imply the element is not in the message, only that its value should be considered invalid.

Interpreting a Message Encoding Description from a Service Set Document

The Encoding or DECALARED TYPES section of the document will use a table format to describe a particular message. This table will include the message body layout (the Composite Fields it contains) and also a breakdown of each of the Composite Fields.

This example will use the message ReportManipulatorSpecifications from the AS6057A - JAUS Manipulator Service Set v2.0 service set document.

This is a complex message that includes a single sequence with multiple Composite Fields, some of which are optional.

REPORT MANIPULATOR SPECIFICATIONS MESSAGE ENCODING

record name= ManipulatorCoordinateSystemRec, optional=true
Field #	Name	Type	Units	Optional?	Interpretation
1	<fixed_field> manipulator coordinate sys. x	unsigned integer	meter	false	x coordinate of origin of manipulator base coordinate system measured with respect to vehicle coordinate system Scaled integer: Lower limit = -30 m Upper limit = +30 m
2	<fixed_field> manipulator coordinate sys. y	unsigned integer	meter	false	y coordinate of origin of manipulator base coordinate system measured with respect to vehicle coordinate system Scaled integer: Lower limit = -30 m Upper limit = +30 m
Fields omitted for brevity
7	<fixed_field> c component of unit quaternion q	unsigned integer	one	false
vtag= 0, record name= RevoluteJoint1OffsetRec
1	<presence_vector>	unsigned byte	one	false
2	< fixed_field> Joint1Offset	Unsigned short integer	meter	false	Joint offset Scaled value Lower limit = -10 m Upper limit = +10 m
3	< fixed_field> Joint 1 – Min value	unsigned integer	radian	true	Scaled value Lower limit = -8pi rad Upper limit = +8pi rad Note: This field is omitted by using the presence vector for joints that can rotate continuously without limit.
Fields omitted for brevity
6	< fixed_field> Joint 1 – Max torque	unsigned integer	N m	true	Scaled value Lower limit = 0 N m Upper limit = 5000 N m
vtag= 1, record name= PrismaticJoint1AngleRec
1	<presence_vector>	unsigned byte	one	false
2	< fixed_field> Joint1Angle	Unsigned short integer	radian	false	Scaled value Lower limit = - pi rad Upper limit = +pi rad
3	< fixed_field> Joint 1 – Min value	unsigned integer	meter	true	Scaled value Lower limit = -10 m Upper limit = +10 m
Fields omitted for brevity
6	< fixed_field> Joint 1 – Max force	unsigned integer	N	true	Scaled value Lower limit = 0 N Upper limit = 5000 N
vtag= 0, record name= RevoluteJointSpecificationRec
1	<presence_vector>	unsigned byte	one	false
2	< fixed_field> Link a(i)(i+1) – Link Length	unsigned integer	meter	false	Link Length Scaled value Lower limit = -10 m Upper limit = +10 m
3	< fixed_field> Link a(i)(i+1)– Twist Angle	unsigned integer	radian	true	Scaled value Lower limit = - pi rad Upper limit = +pi rad
Fields omitted for brevity
8	< fixed_field> Joint (i+1) – Max torque	unsigned integer	N m	true	Scaled value Lower limit = 0 N m Upper limit = 5000 N m
vtag=1, record name= PrismaticJointSpecificationRec
1	<presence_vector>	unsigned byte	one	false
2	< fixed_field> Link a(i)(i+1) – Link Length	unsigned short Integer	meter	false	Link Length Scaled value Lower limit = -10 m Upper limit = +10 m
3	< fixed_field> Link a(i)(i+1)– Twist Angle	unsigned short Integer	radian	true	Scaled value Lower limit = - pi rad Upper limit = +pi rad
Fields omitted for brevity
8	< fixed_field> Joint (i+1)– Max force	unsigned Integer	N	true	Scaled value Lower limit = 0 N Upper limit = 5000 N
record name=JointNameRec
1	<variable_length_str> Description	count_field= unsigned_byte	one	false	A human-readable string that can be used to label each joint on a user interface.

The top of the table provides the message body layout.

For this message, the body contains a single sequence.

The sequence contains a record (ManipulatorCoordinateSystemRec) and it is listed as optional. Therefore, a presence_vector meta_tag precedes the record name and bit 1 of the presence_vector indicates if the record will be present in the message..

The sequence then shows a variant (FirstJointParameters) being present.

This variant will consist of two possible records (RevoluteJoint1OffsetRec, RevoluteJoint1OffsetRec). 

The vtag_field value will denote which one. 0 = RevoluteJoint1OffsetRec; 1 = RevoluteJoint1OffsetRec

The sequence then shows a list(JointSpecificationList) being present. Under the list name is a vairant(JointSpecifications). This indicates that the list will contain a number of Complex Fields that are variants. The number of variants to expect is denoted by the count_field value.

The variant JointSpecifications will consist of two possible records (RevoluteJointSpecificationRec, PrismaticJointSpecificationRec). 

The vtag_field value will denote which one. 0 = RevoluteJointSpecificationRec; 1 = PrismaticJointSpecificationRec

The sequence ends with another list(JointNamesList). Under the list name is a record(JointNameRec). This indicates that the list will contain a number of Complex Fields that are records. The number of records to expect is denoted by the count_field value.

The remainder of the table is related to the breakdown of the Complex Fields shown in the message body.

record name=ManipulatorCoordinateSystemRec

The record has seven Simple fields (elements) none of which are optional. Thus, all the fields will contain valid data.

vtag= 0, record name= RevoluteJoint1OffsetRec; vtag= 1, record name= PrismaticJoint1AngleRec

These records are related to the variant, FirstJointParameters.

Their first field is a presence_vector which indicates that some of the fields in the records are optional. Thus, the presence_vector field should be examined to determine which optional fields will have valid data.

Remember that the bits in the presence_vector are only related to the fields that have its optional attribute set to true.

vtag= 0, record name= RevoluteJointSpecificationRec; vtag=1, record name= PrismaticJointSpecificationRec

These records are related to the variant, JointSpecifications.

Their first field is a presence_vector which indicates that some of the fields in the records are optional. Thus, the presence_vector field should be examined to determine which optional fields will have valid data.

Remember that the bits in the presence_vector are only related to the fields that have its optional attribute set to true.

record name=JointNameRec

This record contains a single Simple Field and will be considered to have valid data if the presence_vector preceding the record name ManipulatorCoordinateSystemRec indicates that it is present.

Protocol Behavior

This heading gives details as to how a component with a service will behave during its operation. The service protocol involves the state of the service, transitions between the states, causes of the transitions, actions taken in the states and conditions needed before taking those actions. The JAUS Service Set documents will describe these activities using diagrams and tables.

States and Transitions Diagram

The states are depicted as rectangles with rounded corners and they represent the situations during the life of a component that has a service.

Transitions are depicted by labeled and directed arrows and they indicate state changes from a single source state to a single destination state. The transition may result in a state remaining in the same state. Certain actions will be taken as the transition precedes to its destination state.

State Transition Table

This table will provide information on the cause for the transition, what action to take before the transition and what conditions must be met before the action can occur. If the conditions are not met then the transition will not take place.

The trigger can be an incoming message or an internal event. If the trigger is an internal event it will be represented in italics. This applies to the conditions and actions as well. All conditions are local to the component (internal events). Some actions will be internal only (meaning no outgoing message is sent).

From the example table below it can be seen that the transition from the 'Prepared' state to the 'Done' state via transition 'D' will occur when the Commit Trigger (incoming message) is received and the isCommit Condition is true causing the sendMesage(COMMITTED) Action to be taken.

It is possible that more than one type of Trigger can cause a particular transition to occur. This is depicted by the 'C' transition in the table.

Also, a transition can result in different conditions and actions being taken. This is depicted by the 'B' transition.

Condition Table

This table will provide for each Condition what criteria must be met before it is considered to be true.

Action Table

This table will provide details at what operations a particular action will perform.