Common Control Language (CCL) – A Proposed Standard Language · PDF fileAUV Common...

AUV Common Control Language (CCL) – A Proposed Standard Language and Framework for AUV

Monitoring & Control

Layer 2 – CCL Support Library

Library Version 1.1 21 September 2007

(CCL Version 2.14)

Principal Author: Rick J. Komerska

Autonomous Undersea Systems Institute (AUSI)

Copyright (c) 2007 Autonomous Undersea Systems Institute.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2

or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included in the section entitled "GNU Free Documentation License".

Change History Library Version: 1.1 CCL Version: 2.14 Date: 21 September 2007 Author: Rick Komerska Change: Clarified Monitor & Report inform messaging within the serialization library functions. The

inform response is only sent for “completed”, non-acknowledgement type messages. The upgrade of the CCL version also reflects this clarification.

Library Version: 1.0 CCL Version: 2.13 Date: 9 July 2007 Author: Rick Komerska Change: Completed documentation. Library Version: 1.0 CCL Version: 2.13 Date: 22 June 2007 Author: Rick Komerska Change: Baseline.

TABLE OF CONTENTS SUMMARY..................................................................................................................................................................1 1 INTRODUCTION..............................................................................................................................................2 2 PROJECT FILES ..............................................................................................................................................3

2.1 CCL.H FILE .................................................................................................................................................3 2.1.1 Vocabulary ...........................................................................................................................................3 2.1.2 Data Structures.....................................................................................................................................4

2.2 ADDITIONAL PROJECT FILES .......................................................................................................................5 3 BUILD ENVIRONMENT .................................................................................................................................6

3.1 WINDOWS ...................................................................................................................................................6 3.2 LINUX..........................................................................................................................................................6

4 LIBRARY API ...................................................................................................................................................7 4.1 USAGE OVERVIEW ......................................................................................................................................7 4.2 UTILITY DATA STRUCTURES .......................................................................................................................8

4.2.1 Request Header Data Structures ..........................................................................................................9 4.2.2 Monitor Request Data Structures .......................................................................................................10 4.2.3 Execute Convention Request Data Structures ....................................................................................13 4.2.4 Maneuver Request Data Structures ....................................................................................................15 4.2.5 Configure Request Data Structures ....................................................................................................18 4.2.6 Navigate Request Data Structures......................................................................................................20 4.2.7 Inform Header Data Structures ..........................................................................................................23 4.2.8 Monitor Inform Data Structures .........................................................................................................24 4.2.9 Execute Convention Inform Data Structure........................................................................................29 4.2.10 Maneuver Inform Data Structure .......................................................................................................29 4.2.11 Configure Inform Data Structure .......................................................................................................30 4.2.12 Navigate Inform Data Structure .........................................................................................................31 4.2.13 Communicate Inform Data Structure .................................................................................................31

4.3 ERROR CODES ...........................................................................................................................................32 4.4 GENERAL SUPPORT FUNCTIONS ................................................................................................................33

4.4.1 getCCL_LanguageVersion ()..............................................................................................................33 4.4.2 getCCL_LibraryVersion ()..................................................................................................................33 4.4.3 getCCL_TypeAndContext().................................................................................................................33

4.5 LOW LEVEL SERIALIZATION / DE-SERIALIZATION FUNCTIONS..................................................................34 4.5.1 serialMON_Req() and serialMON_Inf() ............................................................................................35 4.5.2 deserialMON_Req() and deserialMON_Inf() .....................................................................................35 4.5.3 serialEXC_Req() and serialEXC_Inf() ...............................................................................................36 4.5.4 deserialEXC_Req() and deserialEXC_Inf()........................................................................................36 4.5.5 serialMAN_Req() and serialMAN_Inf() .............................................................................................37 4.5.6 deserialMAN_Req() and deserialMAN_Inf()......................................................................................37 4.5.7 serialCFG_Req() and serialCFG_Inf() ..............................................................................................38 4.5.8 deserialCFG_Req() and deserialCFG_Inf().......................................................................................38 4.5.9 serialNAV_Req() and serialNAV_Inf() ...............................................................................................39 4.5.10 deserialNAV_Req() and deserialNAV_Inf()........................................................................................39 4.5.11 serialCOM_Inf() .................................................................................................................................40 4.5.12 deserialCOM_Inf() .............................................................................................................................40

4.6 ASCII STRING MESSAGING FUNCTIONS....................................................................................................41 4.6.1 serialCCLstr().....................................................................................................................................41 4.6.2 deserialCCLstr().................................................................................................................................41

5 ASCII STRING MESSAGE FORMAT .........................................................................................................42

5.1 MONITOR STATUS REQUEST......................................................................................................................43 5.2 MONITOR STATUS INFORM........................................................................................................................45 5.3 MONITOR SYSTEM CAPABILITIES REQUEST ..............................................................................................48 5.4 MONITOR SYSTEM CAPABILITIES INFORM.................................................................................................49 5.5 MONITOR FILE REQUEST...........................................................................................................................54 5.6 MONITOR FILE INFORM .............................................................................................................................55 5.7 MONITOR SENSOR CAPABILITIES REQUEST...............................................................................................57 5.8 MONITOR SENSOR CAPABILITIES INFORM.................................................................................................59 5.9 MONITOR COMMUNICATIONS INTERFACE CAPABILITIES REQUEST...........................................................61 5.10 MONITOR COMMUNICATIONS INTERFACE CAPABILITIES INFORM .............................................................62 5.11 EXECUTE CONVENTION SYSTEM ADMIN REQUEST ...................................................................................64 5.12 EXECUTE CONVENTION SYSTEM ADMIN INFORM......................................................................................65 5.13 EXECUTE CONVENTION START MISSION REQUEST ...................................................................................66 5.14 EXECUTE CONVENTION START MISSION INFORM......................................................................................67 5.15 EXECUTE CONVENTION STOP MISSION REQUEST......................................................................................68 5.16 EXECUTE CONVENTION STOP MISSION INFORM........................................................................................69 5.17 EXECUTE CONVENTION ABORT MISSION REQUEST...................................................................................70 5.18 EXECUTE CONVENTION ABORT MISSION INFORM.....................................................................................71 5.19 EXECUTE CONVENTION START BEHAVIOR REQUEST ................................................................................72 5.20 EXECUTE CONVENTION START BEHAVIOR INFORM ..................................................................................73 5.21 EXECUTE CONVENTION STOP BEHAVIOR REQUEST ..................................................................................74 5.22 EXECUTE CONVENTION STOP BEHAVIOR INFORM.....................................................................................75 5.23 EXECUTE CONVENTION UPDATE BEHAVIOR REQUEST..............................................................................76 5.24 EXECUTE CONVENTION UPDATE BEHAVIOR INFORM................................................................................77 5.25 MANEUVER GOTO WAYPOINT REQUEST ..................................................................................................78 5.26 MANEUVER GOTO WAYPOINT INFORM.....................................................................................................79 5.27 MANEUVER SPEED AND BEARING REQUEST..............................................................................................80 5.28 MANEUVER SPEED AND BEARING INFORM................................................................................................81 5.29 MANEUVER STATION KEEP REQUEST .......................................................................................................82 5.30 MANEUVER STATION KEEP INFORM..........................................................................................................83

GNU FREE DOCUMENTATION LICENSE.........................................................................................................84

1

Summary The following document and associated software library provides an implementation of the language described in the Layer 1 – CCL Vocabulary and Message Set Specification within the C programming language. Specifically, the products in this layer define data types, structures and variables which encapsulate the Layer 1 specification, as well as functions for serializing and de-serializing messages into bandwidth efficient byte strings suitable for underwater transmission. Finally, these products also document and implement an ASCII string messaging API which provides a simple means of constructing and understanding a common subset of the full CCL message set. The Layer 2 CCL library implementation is currently used in the Solar-powered AUV (SAUV) control system as well as the Modular Mission Planning Toolkit (MMPT), an application developed by Technology Systems, Inc. for mission planning and AUV monitoring and control. This implementation is currently supported in both the Windows and Linux development environments. The “Common Control Language” (CCL) is a protocol that aims to provide a means for different autonomous vehicle and instrument platforms and their users to communicate with each other using a common set of commands and information. It is specifically tailored for autonomous platforms operating in the underwater domain. This effort is part of a broader program to research and develop technology and systems to enable Multiple Cooperating AUVs (MCAUV) (ONR Award #N00014-04-1-0264). This is a team-based effort involving the Autonomous Undersea Systems Institute (AUSI), Naval Undersea Warfare Center – Newport (NUWCDIVNPT), Technology Systems Inc. (TSI), Falmouth Scientific Inc. (FSI), and others.

2

1 Introduction Our approach in the research and development of an AUV common control language has been to divide the problem domain into five layers. Fig. 2 lists these layers in order of increasing platform capability and framework support. Each layer is designed to build upon the previous layer, providing ever-increasing system capabilities which leverage tools which already exist or are currently being developed. Potential users are free to use the software tools utilized by this team, or develop their own implementations, depending upon the user’s mission needs, vehicle capabilities and legacy tools.

Layer Provides 1. Vocabulary and Message Set Specification • AUV domain specific vocabulary

• Message types and format • Expressive messaging context

2. CCL Support Library • Implementation of vocabulary and message set • Bit-level encoding of messages optimized for

low bandwidth channel • Serialization / deserialization of messages • ASCII string messaging API

3. Basic Behavior Process Set • Distributed control environment (DICE) framework for managing behavior processes

• Software processes to interpret CCL messages and which interface to both vehicle-specific and high-level problem solving processes

4. Mission Interpreter • C language-like grammar for mission level development

• Automatic generation of executable behaviors based on a mission file

• Ability to update tasks in real-time • Sequential execution of behaviors • Libraries to support interpretation of mission

grammar and task interface to basic behaviors 5. Cost-based Real-time Planning • Adaptive re-planning which allows

optimization of tasks to cope with dynamic aspects of the environment, working toward individual and potential group goals

• Sequential or parallel execution of behaviors Figure 1. CCL Framework Layers This document provides a reference for a software library which provides an implementation of the language described in the Layer 1 – CCL Vocabulary and Message Set Specification using the C programming language. The remainder of this document is arranged as follows: Section 2 describes the file set necessary to build the library, Section 3 provides details on the Windows and Linux build environments, Section 4 details the library API functions, and Section 5 defines an ASCII string format for easily coding and decoding messages. The software library source code is freely available from AUSI upon request. It is covered under the GNU Lesser General Public License to facilitate dissemination and usage of the library. This reference document is covered under the GNU Free Documentation License.

3

2 Project Files The concept of generic behaviors provides a way of logically segmenting the expressed desired behavior of one platform to another platform, or group of platforms. The breakout of project files is aligned along this concept. As of this writing, the following generic behavior categories and their implied meanings are proposed: Maneuver – "Move or relocate in this manner." Navigate – "Provide path constraints and positional information.” Communicate – “Provide a conduit for command, control and information messages.” Configure – “Change some pre-configured platform aspect.” Monitor – “Watch some aspect of the platform or environment and notify another platform when this changes in some defined way.” Sense – “Utilize on-board mission sensors to effectively collect environmental data.” Exec Convention – “Carry out a well-known system-level action.”

2.1 CCL.h File The CCL.h file incorporates core vocabulary and data structures in a single header file. It is the fundamental implementation file of the CCL Layer 1 specification.

2.1.1 Vocabulary A vocabulary has been defined which incorporates terms which support the use of generic behaviors and which encapsulate many of the underwater domain-specific concepts of interest to AUV developers and users. Use of these vocabulary types helps to reduce communication bandwidth. Currently, 60 enumeration sets incorporating over 250 words have been defined. For development purposes, we have currently implemented the vocabulary types in the C programming language as enumeration sets. Fig. 2 shows a sample set, along with the equivalent “English gloss” text encoded as a complimentary character string array variable. Note that this method allows for easy string parsing using the enumeration constants as input into the string array. typedef enum CCL_VERT_LOCATION_ENUM { CCL_VERT_DEPTH, // requires depth value [m] CCL_VERT_ALTITUDE, // requires altitude value [m] CCL_VERT_CURRENT_DEPTH, CCL_VERT_CURRENT_ALTITUDE, CCL_VERT_CONFIGURED_DEPTH, CCL_VERT_CONFIGURED_ALTITUDE, CCL_VERT_OFFSET_PLATFORM, // requires offset value [m], +down/-up CCL_VERT_SURFACE, CCL_VERT_BOTTOM, CCL_VERT_LOCATION_ENUM_MAX // array bounds usage - not a language element } CCL_VERT_LOCATION_ENUM; const static ACHAR* CCL_VERT_LOCATION_STR[] = { "DEPTH", "ALTITUDE", "CURRENT_DEPTH", "CURRENT_ALTITUDE", "CONFIGURED_DEPTH", "CONFIGURED_ALTITUDE", "PLATFORM_OFFSET", "SURFACE", "BOTTOM" };

Figure 2. Sample Vocabulary Enumeration Set

4

2.1.2 Data Structures Data structures are used to provide logical segments for grouping, communicating and parsing of domain-specific commands and information. Information in the data structures is defined at the bit level. Currently, there are 62 structures which have been defined; see Appendix C for a complete list. Communication devices used in the AUV domain such as acoustic and RF modems rely upon serial communications which have a 1 B transmission granularity. In addition, programming for most AUVs is done using higher level languages such as C and C++, whose functions also work at this 1 B level. These restrictions force us to pack the bit fields in the structures which have a granularity of 1 B. This can lead to a slight increase in transmission bandwidth, depending on how the bit fields are arranged and grouped. Although we have been careful to try and balance flexibility and reusability in the vocabulary and grammar with minimum transmission size, there is probably room for improvement here in the future. CCL relies upon a mapping from the basic C language data types, as shown in Fig. 3. This lets us explicitly control the size of the basic data types across any compiler. This allows for fine control over message sizes, which is important in bandwidth constrained communications links.

typedef unsigned char ABYTE; // 1 B typedef char ACHAR; // 1 B typedef short AINT16; // 2 B typedef unsigned short AUINT16; // 2 B typedef int AINT32; // 4 B typedef unsigned int AUINT32; // 4 B typedef float AFLT32; // 4 B typedef double AFLT64; // 8 B typedef long ATIME32; // 4 B

Figure 3. Basic Data Types For development purposes, we have currently implemented the data structures in the C programming language as bit fields. We assume a 32-bit operating system, and define an unsigned character as 1 B, an unsigned short as 2 B and an unsigned integer as 4 B. We also assume structures can be packed along a 1 B boundary. Data type and structure names adhere to a 63 significant initial character limit. Fig. 4 shows an example of both a data type and data structure, and how they are used together. Note that in the CCL_TIME_INTERVAL_STRUCT structure, the units:2 denotes that 2 bits are allocated to represent the CCL_TIME_INTERVAL_ENUM (defined above it), while the time:14 denotes that 14 bits are used to store the actual time interval value. In this case, 14 bits provides a dynamic range from 0 to 16,383, which implies we can use this structure to represent time intervals from 0 – 4.5 hours at 1 second resolution, 0 – 273.1 hours at 1 minute resolution, 0 – 682.6 days at 1 hour resolution, or 0 – 44.9 years at 1 day resolution. typedef enum CCL_TIME_INTERVAL_ENUM { CCL_TIME_SEC, // "SECONDS" CCL_TIME_MIN, // "MINUTES" CCL_TIME_HRS, // "HOURS" CCL_TIME_DAYS // "DAYS" } CCL_TIME_INTERVAL_ENUM; typedef struct { // 2 B AUINT16 units:2; // CCL_TIME_INTERVAL_ENUM AUINT16 time:14; // 0...16K range } CCL_TIME_INTERVAL_STRUCT; // Time interval in specified units

Figure 4. Example Data Type and Structure Sets

5

2.2 Additional Project Files In addition to the CCL.h file, additional project files provide the interface and implementation for serialization / de-serialization of messages, as well as support the ASCII string message parsing. These include the following: CCLsupport.h CCLsupport.c CCLmonitor.h CCLmonitor.c CCLcommunicate.h CCLcommunicate.c CCLconfigure.h CCLconfigure.c CCLexecConvention.h CCLexecConvention.c CCLmaneuver.h CCLmaneuver.c CCLnavigate.h CCLnavigate.c bitsizes.h Project files which support the building of the library in both the Windows and Linux operating systems are also present. These files are listed below. Settings relevant to these build environments are detailed in section 3. Windows: Linux: libCCL.dsp Makefile libCCL.dsw

6

3 Build Environment Implementations for both Windows and Linux have been created which are used to produce a linkable library for use in your specific application.

3.1 Windows The Windows version of the library has been developed, built and tested using the Microsoft Visual Studio IDE, with the Microsoft Visual C++ 6.0 tools. The project and workspace names are “libCCL”. The library is built using the multi-threaded run-time C libraries and 4 B structure alignment boundaries. Project settings are encapsulated in the libCCL.dsp file, and use the following project options: Compiler: /nologo /Zp4 /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "CCL_TOOLKIT_DLL_EXPORTS" /D "_WIN32_VANILLA" /FR"Release/" /Fo"Release/" /Fd"Release/" /FD /c Linker: kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /incremental:no /pdb:"Release/libCCL.pdb" /machine:I386 /out:"Release/libCCL.dll" /implib:"Release/libCCL.lib" Making the project produces the libCCL.lib and libCCL.dll files, which are then available for use. All of the relevant files are contained in a zip file archive for distribution purposes.

3.2 Linux The Linux version of the CCL library has been built using Slackware versions 7.1 and up. Compiler/linker combinations tested span from egcs-2.91.66/ld 2.9.1 through gcc 3.3.6/ld 2.15.92.0.2. Project options and settings are contained in an included Makefile, which is used to build both a static and a dynamic library. All of the relevant files are contained in a tarball archive for distribution purposes.

7

4 Library API The following section details the API used for serialization and de-serialization of messages. Section 4.1 presents an overview of the process, using a Maneuver request message as an example. Section 4.2 details the utility data structures which are used by the serialization and de-serialization library routines. Section 4.3 describes the validation error codes produced when these routines are called. Sections 4.4 and 4.5 detail the library’s functional interface.

4.1 Usage Overview Figure 5 depicts an example of the serialization and deserialization flow of a CCL message using the Maneuver request message. In this example, a human operator builds a vehicle command using either the ASCII string protocol (Sec. 5) or by having the mission control program fill a MAN_REQ_STRUCT data structure. The latter approach is usually done by taking user input through a graphical user interface. If an ASCII string is used, a library call to serialCCLstr() is made to perform a validation check as well as produce the serialized CCL message payload. If the data structure is filled directly, a call to serialMAN_Req() will perform the validation check and produce the CCL payload. Note that if the validation check fails, no serialized message is produced. After a valid message is produced, it is then wrapped as payload within the appropriate network and/or framing protocols and sent to the modem for transmission.

Figure 5. Sample CCL Message Serialization / De-serialization Process Flow

MAN_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT internalMsg processID contextID taskName SUP_MSG_ADDRESS_STRUCT CCL_ADDRESS_STRUCT group_id host_id CCL_ADDRESS_STRUCT group_id host_id CCL_HEADER_STRUCT context beh_type string_api_support beh_subtype thread_id

CCL_REQ_HDR_STRUCT ack_type use_authority group_head group_tail group_loop beh_stacking SUP_REQ_HDR_SUP_STRUCT CCL_AUTHORITY_STRUCT level pecking_order SUP_LOOP_STRUCT CCL_LOOP_STRUCT options loop_n_times SUP_TIME_UNION timeAbs CCL_TIME_INTERVAL_STRUCT units time MAN_REQ_UNION

MAN_GOTO_STRUCT CCL_GOTO_OPT_STRUCT

target_xy target_z use_config_radius_tol use_config_depth_tol path_type speed timeout

SUP_HORZ_LOCATION_UNION CCL_LAT_LNG_STRUCT lat lng CCL_NE_STRUCT north east vertLoc CCL_POS_TOL_STRUCT units val CCL_POS_TOL_STRUCT units val speed SUP_TIME_UNION timeAbs CCL_TIME_INTERVAL_STRUCT units time

Type an ASCII message:"REQUEST GOTO 43.246124 -77.135246 11.0 65"

Library call:serialMAN_Req()

Library call:serialCCLstr()

GUI / machine fill aMAN_REQ_STRUCTdata structure

or1110010001…Serialized CCL message

Library call:deserialMAN_Req(),fills a MAN_REQ_STRUCT data structure

MAN_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT internalMsg processID contextID taskName SUP_MSG_ADDRESS_STRUCT CCL_ADDRESS_STRUCT group_id host_id CCL_ADDRESS_STRUCT group_id host_id CCL_HEADER_STRUCT context beh_type string_api_support beh_subtype thread_id

CCL_REQ_HDR_STRUCT ack_type use_authority group_head group_tail group_loop beh_stacking SUP_REQ_HDR_SUP_STRUCT CCL_AUTHORITY_STRUCT level pecking_order SUP_LOOP_STRUCT CCL_LOOP_STRUCT options loop_n_times SUP_TIME_UNION timeAbs CCL_TIME_INTERVAL_STRUCT units time MAN_REQ_UNION

MAN_GOTO_STRUCT CCL_GOTO_OPT_STRUCT

target_xy target_z use_config_radius_tol use_config_depth_tol path_type speed timeout

SUP_HORZ_LOCATION_UNION CCL_LAT_LNG_STRUCT lat lng CCL_NE_STRUCT north east vertLoc CCL_POS_TOL_STRUCT units val CCL_POS_TOL_STRUCT units val speed SUP_TIME_UNION timeAbs CCL_TIME_INTERVAL_STRUCT units

time

Read / Parse aMAN_REQ_STRUCTdata structure

or

Library call:deserialCCLstr()

Read / Parse an ASCII message:"REQUEST GOTO 43.246124 -77.135246 11.0 65"

Wrap message in network & framing protocols and transmit

Receive message, unwrap from framing & network protocols

Message Creation & Serialization

Message Receipt & De-serialization

Library call:getCCL_TypeAndContext(),to determine how to de-serialize message

1110010001…

Serialized CCL message

8

Upon message receipt, the vehicle platform unwraps the CCL message from any framing and network protocols and uses the library function getCCL_TypeAndContext() to determine the proper deserializtion routines to use. This function will also indicate whether the message can safely be decoded using the ASCII string API, as presently the ASCII message protocol is a subset of the full CCL message set. In our example, the deserialMAN_Req() function may be called to fill out a MAN_REQ_STRUCT data structure, which may then be appropriately parsed by the platform control software. Alternately, if the CCL message can be de-serialized using the ASCII string API, this may be done and the resulting ASCII string handled appropriately. The message process flow described above is used for communication between any type of sending or receiving node that uses the CCL library, whether the node be a human operator or an instrument platform.

4.2 Utility Data Structures The CCL library uses the set of data structures listed in Table 1 to facilitate the serialization and de-serialization process. These structures are defined along the generic behavior functional categories described in section 2 and are used as input (for serialization) and output (for de-serialization) in the library functions described in section 4.5. The data structures contain all possible relevant CCL message options within their respective structures. For example, the MAN_REQ_STRUCT contains data fields for specifying ‘GoTo Waypoint’, ‘Follow Path’, ‘Speed and Bearing’, ‘Move’, and ‘Station Keep’ maneuver requests. When serializing a message, it is up to the calling program to fill in the appropriate data fields. When serialized, only the relevant information is pulled from the data structures to produce the message payload. Note that it is also up to the calling program to appropriately parse a de-serialized data structure. This is a non-trivial task as many of the structure fields will not be relevant to the particular message received, and should not be read. This task can be done by parsing from the top down, with an understanding of the relevant CCL message options and data types described in the Layer 1 – CCL Vocabulary and Message Set Specification.

Table 1. CCL Message Utility Data Structure Set

Data Structure Purpose Description MON_REQ_STRUCT Monitor Request Table 3 EXC_REQ_STRUCT Execute Convention Request Table 10 MAN_REQ_STRUCT Maneuver Request Table 17 CFG_REQ_STRUCT Configure Request Table 23 NAV_REQ_STRUCT Navigate Request Table 27 MON_INF_STRUCT Monitor Inform Table 32 EXC_INF_STRUCT Execute Convention Inform Table 38 MAN_INF_STRUCT Maneuver Inform Table 39 CFG_INF_STRUCT Configure Inform Table 40 NAV_INF_STRUCT Navigate Inform Table 44 COM_INF_STRUCT Communicate Inform Table 45

Tables 2 through 46 define the sub-structures and data fields that comprise the structures listed in Table 1. Fields that may require input are shown in red. Specifically, Table 2 lists the structures common to all ‘request’ type messages and Tables 3 through 30 describe the ‘request’ type messages across the generic behavior categories. Table 31 lists the structures common to all ‘inform’ type messages, and Tables 32 through 46 describe the ‘inform’ type messages across the generic behavior categories. Note the convention in assigning type definitions in this library: the type prefix indicates the file it originates in (e.g., CCL_LOOP_STRUCT is defined in CCL.h, MAN_REQ_STRUCT is defined in CCLmaneuver.h, SUP_TIME_UNION is defined in CCLsupport.h). The type postfix (_STRUCT, _UNION, _ENUM) indicates whether this is a data structure, data union, or enumeration, respectively. All type definitions are capitalized.

9

4.2.1 Request Header Data Structures

Table 2. Request Message Header Data Structure Fields Fields Type Valid Range Description SUP_INTERPROC_CXT_STRUCT Interprocess context information. internalMsg ABOOL 0,1 Destination of this message

(internal=1 or external=0). processID AINT32 AINT32 Process ID. Utility field for internal

platform messaging. contextID AINT32 AINT32 Utility field for internal platform

messaging. taskName ACHAR[] 15 char Process task name. Utility field for

internal platform messaging. SUP_MSG_ADDRESS_STRUCT Message address info. CCL_ADDRESS_STRUCT Source of message.

group_id ABYTE 0...2 Source group ID. host_id ABYTE 0...62 Source host ID. CCL_ADDRESS_STRUCT Destination for message. group_id ABYTE 0...3 (broadcast=3) Destination group ID. host_id ABYTE 0...63 (broadcast=63) Destination host ID. CCL_HDR_STRUCT context ABYTE CCL_CONTEXT_ENUM Type of ‘request’. beh_type ABYTE CCL_BEH_ENUM Generic behavior category. string_api_support ABYTE CCL_BOOLEAN_ENUM Is ASCII message formatting

supported? beh_subtype AUINT16 CCL_MANEUVER_ENUM,

CCL_NAVIGATE_ENUM, CCL_COMMUNICATE_ENUM, CCL_CONFIGURE_ENUM, CCL_MONITOR_ENUM, or CCL_EXEC_CONV_ENUM

Flavor of behavior, depending on generic behavior category.

thread_id AUINT16 0...8,191 Message context thread ID. CCL_REQ_HDR_STRUCT ack_type ABYTE CCL_REQUEST_ACK_ENUM Specify acknowledgment type. use_authority ABYTE CCL_BOOLEAN_ENUM Specify message authority level. group_head ABYTE CCL_BOOLEAN_ENUM Command clustering indicator. group_tail ABYTE CCL_BOOLEAN_ENUM Command clustering indicator. group_loop ABYTE CCL_BOOLEAN_ENUM Specify behavior repetition

(looping) parameters. beh_stacking ABYTE CCL_BEHAVIOR_STACKING

_ENUM Queue or replace current behavior with this behavior.

SUP_REQ_HDR_SUP_STRUCT CCL_AUTHORITY_STRUCT level ABYTE 0...7 Sendor or message authority level. pecking_order ABYTE 0...31 Authority rank, within a level.

SUP_LOOP_STRUCT CCL_LOOP_STRUCT options ABYTE CCL_LOOP_ENUM Specify how to loop behavior(s). loop_n_times ABYTE 0...63 Maximum loop bound.

SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for ending looping. CCL_TIME_INTERVAL_STRUCT units AUINT16 CCL_TIME_INTERVAL

_ENUM Units for specifying looping time interval.

time AUINT16 AUINT16 Interval range (dynamic value).

10

4.2.2 Monitor Request Data Structures

Table 3. Monitor Request Data Structure Fields Fields Description Sub-structures MON_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_REQ_HDR_STRUCT SUP_REQ_HDR_SUP_STRUCT

See Table 2.

MON_REQ_UNION Specific type of monitor and report request. MON_REQ_STATUS_STRUCT Monitor and report on system status. See Table 5. MON_REQ_CAPS_STRUCT Monitor and report on system capabilities. See Table 6. MON_REQ_FILE_STRUCT Monitor and report on a file. See Table 7. MON_REQ_SENSOR_CAPS_STRUCT Monitor and report on mission sensor capabilities. See Table 8. MON_REQ_COMMS_CAPS_STRUCT Monitor and report on comms interface capabilities. See Table 9.

Table 4. Monitor Request Report Scheduling Data Structure Fields Fields Type Valid Range Description MON_SCHEDULE_STRUCT Report scheduling options. CCL_MON_SCHEDULE_STRUCT action AUINT16 CCL_BEHAVIOR_ACTION

_ENUM Starting or stopping behavior indicator.

specify_start_time AUINT16 CCL_BOOLEAN_ENUM Start time specified. specify_end_time AUINT16 CCL_BOOLEAN_ENUM Stop time specified. schedule AUINT16 CCL_SCHEDULE_ENUM Type of scheduling. num_params AUINT16 0...3 Parameter count for event schedule. one_time_report AUINT16 CCL_BOOLEAN_ENUM Indicate single report only. specify_update_period AUINT16 CCL_BOOLEAN_ENUM Indicate reporting time interval. report_to AUINT16 CCL_ADDRESS_ENUM Send the report to this address.

startTime ATIME32 ATIME32 Start time. endTime ATIME32 ATIME32 Stop time. CCL_REGION_STRUCT For scheduling on spatial aspects. shape AUINT16 CCL_VOLUME_GEOMETRY

_ENUM Shape of spatial region.

x_constrained AUINT16 CCL_BOOLEAN_ENUM Indicate specify reference lat/lng or offsets and x extent.

y_constrained AUINT16 CCL_BOOLEAN_ENUM Indicate specify reference lat/lng or offsets and y extent.

z_constrained AUINT16 CCL_BOOLEAN_ENUM Indicate specify reference depth and z extent.

use_latlng AUINT16 CCL_BOOLEAN_ENUM Indicate specify lat/lng center, else offset from fixed origin.

angle AUINT16 0...180 Rotation degrees ccw from north. within_region AUINT16 CCL_BOOLEAN_ENUM Indicate inside or outside region. lat_or_n AFLT32 AFLT32 Reference lat or north offset [m]. lng_or_e AFLT32 AFLT32 Reference lng or east offset [m]. depth AFLT32 AFLT32 Reference depth [m]. x_extent_units AUINT16 CCL_LENGTH_UNIT_ENUM North or x extent unit. x_extent_val AUINT16 0...8,191 North or x extent (dynamic value). y_extent_units AUINT16 CCL_LENGTH_UNIT_ENUM East or y extent unit. y_extent_val AUINT16 0...8,191 East or y extent (dynamic value). z_extent_units AUINT16 CCL_LENGTH_UNIT_ENUM Depth extent unit. z_extent_val AUINT16 0...8,191 Depth extent (dynamic value).

11

MON_PARAM_EVENT_STRUCT Array of parameter information for scheduling on events.

CCL_PARAM_TRIGGER_HDR _STRUCT

Information for event triggering based on parameter value.

deriv_type ABYTE CCL_VALUE_DERIVATIVE _ENUM

Specify parameter value or derivative.

rel_operator ABYTE CCL_RELATION_OPERATOR _ENUM

Math relational operator for trigger equation.

log_operator ABYTE CCL_LOGICAL_OPERATOR _ENUM

Math logical operator for chaining multiple event trigger equations.

SUP_PARAM_STRUCT Parameter for event scheduling. CCL_PARAM_ID_STRUCT parameter_id ABYTE CCL_PARAMETER_ENUM or

custom ID from 0..127 Standard or custom parameter ID.

custom_flag ABYTE CCL_BOOLEAN_ENUM Indicate custom parameter. customParamSize ABYTE 0...32 Byte size of custom parameter. SUP_PARAM_VAL_UNION Values for trigger equations. byte32Val ABYTE[] 32 bytes Custom parameter value. byte15Val ABYTE[] 15 bytes char8Val ACHAR[] 7 char char16Val ACHAR[] 15 char char32Val ACHAR[] 31 char charVal ACHAR ACHAR ucharVal ABYTE ABYTE shortVal AINT16 AINT16 ushortVal AUINT16 AUINT16 longVal AINT32 AINT32 ulongVal AUINT32 AUINT32 floatVal AFLT32 AFLT32 doubleVal AFLT64 AFLT64 timeVal ATIME32 ATIME32

CCL_TIME_INTERVAL_STRUCT For 1st and 2nd derivative triggers. units AUINT16 CCL_TIME_INTERVAL

_ENUM Units for specifying time interval for derivative calculations.

time AUINT16 AUINT16 Interval range (dynamic value). CCL_TIME_INTERVAL_STRUCT units AUINT16 CCL_TIME_INTERVAL

_ENUM Units for specifying time interval for periodic updates.

time AUINT16 AUINT16 Interval range (dynamic value). CCL_ADDRESS_STRUCT Report to address. group_id ABYTE 0...3 (broadcast=3) Destination group ID.

host_id ABYTE 0...63 (broadcast=63) Destination host ID.

12

Table 5. Monitor Request “Report Status” Data Structure Fields Fields Type Valid Range Description MON_REQ_STATUS_STRUCT MON_SCHEDULE_STRUCT See Table 4. CCL_STATUS_REQ_OPT_STRUCT System status reporting options. extended_params ABYTE 0...15 Additional parameters to report.

MON_STATUS_REQ_PARAM _STRUCT

0...15 Array of additional parameters to report.

deriv ABYTE CCL_VALUE_DERIVATIVE _ENUM

Report on parameter value, 1st or 2nd derivative.

CCL_PARAM_ID_STRUCT parameter_id ABYTE CCL_PARAMETER_ENUM or


custom_flag ABYTE CCL_BOOLEAN_ENUM Indicate custom parameter. CCL_TIME_INTERVAL_STRUCT units AUINT16 CCL_TIME_INTERVAL



Table 6. Monitor Request “Report Capabilities” Data Structure Fields Fields Type Valid Range Description MON_REQ_CAPS_STRUCT MON_SCHEDULE_STRUCT See Table 4.

Table 7. Monitor Request “Report File” Data Structure Fields Fields Type Valid Range Description MON_REQ_FILE_STRUCT MON_SCHEDULE_STRUCT See Table 4. CCL_FILE_REQ_OPT_STRUCT File reporting options. filename_len AUINT16 1...15 Filename length. dirname_len AUINT16 0...31 Directory path length (0=default

directory). name ACHAR[] 1...15 Filename. path ACHAR[] 0...31 Directory path.

Table 8. Monitor Request “Report Sensor Capabilities” Data Structure Fields Fields Type Valid Range Description MON_REQ_SENSOR_CAPS_STRUCT MON_SCHEDULE_STRUCT See Table 4. CCL_SENSOR_CAPS_REQ_OPT _STRUCT

Sensor capabilities reporting options.

type ABYTE CCL_MISSION_SENSOR _ENUM

Sensor type.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance

13

Table 9. Monitor Request “Report Comms Interface Capabilities” Data Structure Fields Fields Type Valid Range Description MON_REQ_COMMS_CAPS_STRUCT MON_SCHEDULE_STRUCT See Table 4. CCL_COMMS_CAPS_REQ_OPT _STRUCT

Comms interface capabilities reporting options.

type ABYTE CCL_COMM_INTERFACE _ENUM

Comms interface type.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance.

4.2.3 Execute Convention Request Data Structures

Table 10. Execute Convention Request Data Structure Fields Fields Description Sub-structures EXC_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_REQ_HDR_STRUCT SUP_REQ_HDR_SUP_STRUCT

See Table 2.

EXC_REQ_UNION Specific type of exec convention request. Note that ‘Stop Mission’ does not have a union member.

EXC_SYSADM_REQ_STRUCT Perform system admin type actions on platform. See Table 11. EXC_STARTMISS_REQ_STRUCT Start a new mission. See Table 12. EXC_ABORTMISS_REQ_STRUCT Abort an existing mission. See Table 13. EXC_STARTBEH_REQ_STRUCT Start a new behavior (within a mission). See Table 14. EXC_STOPBEH_REQ_STRUCT Stop an existing behavior (within a mission). See Table 15. EXC_UPDATEBEH_REQ_STRUCT Update a mission behavior on the fly. See Table 16.

Table 11. Execute Convention Request “System Admin” Data Structure Fields Fields Type Valid Range Description EXC_SYSADM_REQ_STRUCT CCL_SYS_ADM_REQ_OPT_STRUCT System administration options. action ABYTE CCL_SYS_ADM_CONTROL

_ENUM System admin function.

restart_time ABYTE CCL_TIME_ENUM Specify restart time. SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for restart. CCL_TIME_INTERVAL_STRUCT units AUINT16 CCL_TIME_INTERVAL

_ENUM Units for specifying restart time interval.


14

Table 12. Execute Convention Request “Start Mission” Data Structure Fields Fields Type Valid Range Description EXC_STARTMISS_REQ_STRUCT CCL_START_MISS_REQ_OPT _STRUCT

Start mission options.

name_len ABYTE 1...15 Mission name size. name ACHAR[] 1...15 Mission name.

Table 13. Execute Convention Request “Abort Mission” Data Structure Fields

Fields Type Valid Range Description EXC_ABORTMISS_REQ_STRUCT CCL_ABORT_MISS_REQ_OPT _STRUCT

Abort mission options.

name_len ABYTE 0...15 Abort mission name size. 0=use configured abort mission, else use named mission.

name ACHAR[] 0...15 Abort mission name.

Table 14. Execute Convention Request “Start Behavior” Data Structure Fields Fields Type Valid Range Description EXC_STARTBEH_REQ_STRUCT CCL_START_BEH_REQ_OPT _STRUCT

Start behavior options.

name_len ABYTE 1...15 Behavior name size. name ACHAR[] 1...15 Behavior name.

Table 15. Execute Convention Request “Stop Behavior” Data Structure Fields

Fields Type Valid Range Description EXC_STOPBEH_REQ_STRUCT CCL_STOP_BEH_REQ_OPT _STRUCT

Stop behavior options.

name_len ABYTE 1...15 Behavior name size. name ACHAR[] 1...15 Behavior name.

Table 16. Execute Convention Request “Update Behavior” Data Structure Fields

Fields Type Valid Range Description EXC_UPDATEBEH_REQ_STRUCT CCL_UPDATE_BEH_REQ_OPT _STRUCT

Update behavior options.

beh_name_len ABYTE 1...15 Behavior name size. filename_len ABYTE 0...15 Filename length. dirname_len AUINT16 0...31 Directory path length. 0=default

directory. update_attached AUINT16 CCL_BOOLEAN_ENUM Indicator if update code attached to

this message (e.g. do not use file option).

beh_len AUINT16 0...511 Size of update code. beh_code_type AUINT16 CCL_FILE_ENCODING

_ENUM Encoding of update code.

15

behName ACHAR[] 1...15 Behavior name. fileName ACHAR[] 0...15 Filename (if update code not

attached). pathName ACHAR[] 0...31 Directory path (if update code not

attached). behCode ABYTE[] 0...511 Update code (if not using file

option).

4.2.4 Maneuver Request Data Structures

Table 17. Maneuver Request Data Structure Fields Fields Description Sub-structures MAN_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_REQ_HDR_STRUCT SUP_REQ_HDR_SUP_STRUCT

See Table 2.

MAN_REQ_UNION Specific type of maneuver request. MAN_GOTO_STRUCT Transit to a specific waypoint. See Table 18. MAN_FOLLOW_PATH_STRUCT Follow a pre-determined path. See Table 19. MAN_SPD_AND_BRNG_STRUCT Move at a given speed and bearing. See Table 20. MAN_MOVE_STRUCT Move at a given velocity vector and orientation. See Table 21. MAN_STATION_KEEP_STRUCT Station keep at a given location. See Table 22.

Table 18. Maneuver Request “GoTo Waypoint” Data Structure Fields Fields Type Valid Range Description MAN_GOTO_STRUCT CCL_GOTO_OPT_STRUCT Goto waypoint maneuver options. target_xy AUINT16 CCL_HORZ_LOCATION

_ENUM Waypoint position in the horizontal plane.

target_z AUINT16 CCL_VERT_LOCATION _ENUM

Waypoint position in the vertical plane.

use_config_radius_tol AUINT16 CCL_BOOLEAN_ENUM Indicator to use configured tolerance in xy waypoint position.

use_config_depth_tol AUINT16 CCL_BOOLEAN_ENUM Indicator to use configured tolerance in z waypoint position.

path_type AUINT16 CCL_MANEUVER_PATH _ENUM

Transit path specifier.

speed AUINT16 CCL_SPEED_ENUM Transit speed specifier. timeout AUINT16 CCL_TIME_ENUM Timeout specifier.

SUP_HORZ_LOCATION_UNION CCL_LAT_LNG_STRUCT lat AFLT32 AFLT32 Waypoint latitude (decimal deg.) lng AFLT32 AFLT32 Waypoint longitude (decimal deg.)

CCL_NE_STRUCT north AFLT32 AFLT32 Waypoint n offset from origin [m]. east AFLT32 AFLT32 Waypoint e offset from origin [m].

vertLoc AFLT32 AFLT32 Waypoint vertical distance value [m].

16

CCL_POS_TOL_STRUCT Horizontal waypoint tolerance. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying tolerance. val AUINT16 0...8,191 Tolerance range (dynamic value).

CCL_POS_TOL_STRUCT Vertical waypoint tolerance. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying tolerance. val AUINT16 0...8,191 Tolerance range (dynamic value).

speed AUINT16 AUINT16 Specified speed [cm/s]. SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for ending

maneuver. CCL_TIME_INTERVAL_STRUCT Relative time for ending maneuver. units AUINT16 CCL_TIME_INTERVAL

_ENUM Units for specifying timeout interval.


Table 19. Maneuver Request “Follow Path” Data Structure Fields Fields Type Valid Range Description MAN_FOLLOW_PATH_STRUCT CCL_FOLLOW_PATH_OPT_STRUCT Path following maneuver options. pathkey_len ABYTE 0...15 Maneuver path length. If =0, use

configured path else use named path.

timeout ABYTE CCL_TIME_ENUM Timeout specifier. pathKey ACHAR[] 0...15 Named path identifier. SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for ending




Table 20. Maneuver Request “Speed and Bearing” Data Structure Fields Fields Type Valid Range Description MAN_SPD_AND_BRNG_STRUCT CCL_SPD_AND_BRNG_OPT _STRUCT

Speed and bearing maneuver options.

boundary_z AUINT16 CCL_VERT_LOCATION _ENUM

Specify boundary depth or altitude.

speed AUINT16 CCL_SPEEP_ENUM Specify speed. duration AUINT16 CCL_TIME_ENUM Specify duration.

bearing AUINT16 0...3,600 Specified true bearing [tenths of deg].

speed AUINT16 AUINT16 Specified speed [cm/s]. vertBound AFLT32 AFLT32 Boundary depth or altitude. CCL_TIME_INTERVAL_STRUCT Relative time for ending maneuver. units AUINT16 CCL_TIME_INTERVAL



17

Table 21. Maneuver Request “Move” Data Structure Fields Fields Type Valid Range Description MAN_MOVE_STRUCT Specify 3DOF motion with 3DOF

orientation constraints. CCL_MOVE_OPT_STRUCT Move maneuver options. heading_constrained ABYTE CCL_BOOLEAN_ENUM Specify heading angle. pitch_constrained ABYTE CCL_BOOLEAN_ENUM Specify pitch angle. roll_constrained ABYTE CCL_BOOLEAN_ENUM Specify roll angle. ns_vel_spec ABYTE CCL_BOOLEAN_ENUM Specify n/s speed vector

component. ew_vel_spec ABYTE CCL_BOOLEAN_ENUM Specify e/w speed vector

component. ds_vel_spec ABYTE CCL_BOOLEAN_ENUM Specify depth/surface speed vector

component. duration ABYTE CCL_TIME_ENUM Specify maneuver duration.

heading AUINT16 0...3,600 Specified compass heading [tenths of deg].

pitch AINT16 -1,800...1,800 Specified pitch angle [+/- tenths of deg.].

roll AINT16 -1,800...1,800 Specified roll angle [+/- tenths of deg.].

nsSpeed AINT16 AINT16 Speed vector along n/s axis [+/- cm/s].

ewSpeed AINT16 AINT16 Speed vector along e/w axis [+/- cm/s].

dsSpeed AINT16 AINT16 Speed vector along vertical axis [+/- cm/s].

CCL_TIME_INTERVAL_STRUCT Relative time for ending maneuver. units AUINT16 CCL_TIME_INTERVAL



Table 22. Maneuver Request “Station Keep” Data Structure Fields Fields Type Valid Range Description MAN_STATION_KEEP_STRUCT CCL_STATION_KEEP_OPT _STRUCT

Station keep maneuver options.

target_xy_constrained AUINT16 CCL_BOOLEAN_ENUM Specify horizontal station keep constraint.

target_xy AUINT16 CCL_HORZ_LOCATION _ENUM

Specify horizontal station keep position.

target_z_constrained AUINT16 CCL_BOOLEAN_ENUM Specify depth or altitude station keep constraint.

drift_radius AUINT16 CCL_BOOLEAN_ENUM Specify horizontal drift radius. drift_depth AUINT16 CCL_BOOLEAN_ENUM Specify vertical drift distance. heading_control AUINT16 CCL_BOOLEAN_ENUM Specify fixed heading. pitch_control AUINT16 CCL_BOOLEAN_ENUM Specify fixed pitch angle. roll_control AUINT16 CCL_BOOLEAN_ENUM Specify fixed roll angle. timeout AUINT16 CCL_TIME_ENUM Specify maneuver timeout.

SUP_HORZ_LOCATION_UNION CCL_LAT_LNG_STRUCT lat AFLT32 AFLT32 Station keep origin latitude

(decimal deg.) lng AFLT32 AFLT32 Station keep origin longitude

(decimal deg.)

18

CCL_NE_STRUCT north AFLT32 AFLT32 Station keep origin n offset from

origin [m]. east AFLT32 AFLT32 Station keep origin e offset from

origin [m]. vertLoc AFLT32 AFLT32 Station keep origin depth or

altitude. CCL_POS_TOL_STRUCT Horizontal drift tolerance. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying tolerance. val AUINT16 0...8,191 Tolerance range (dynamic value).

CCL_POS_TOL_STRUCT Vertical drift tolerance. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying tolerance. val AUINT16 0...8,191 Tolerance range (dynamic value).

heading AUINT16 0...3,600 Specified fixed compass heading [tenths of deg].

pitch AINT16 -1,800...1,800 Specified fixed pitch angle [+/- tenths of deg.].

roll AINT16 -1,800...1,800 Specified fixed roll angle [+/- tenths of deg.].

SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for ending




4.2.5 Configure Request Data Structures

Table 23. Configure Request Data Structure Fields Fields Description Sub-structures CFG_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_REQ_HDR_STRUCT SUP_REQ_HDR_SUP_STRUCT

See Table 2.

CFG_REQ_UNION Specific type of configure request. CFG_PARAMS_STRUCT Configure one or more system parameters. See Table 24. CFG_SENSOR_STRUCT Configure a mission sensor. See Table 25. CFG_COMMS_IF_STRUCT Configure a communications interface. See Table 26.

19

Table 24. Configure Request “System Parameters” Data Structure Fields Fields Type Valid Range Description CFG_PARAMS_STRUCT CCL_CFG_PARAMS_REQ_OPT _STRUCT

System parameter configuration options.

num_params ABYTE 1...15 Specify number of parameters to configure.

SUP_PARAM_STRUCT Info for array of parameters. CCL_PARAM_ID_STRUCT parameter_id ABYTE CCL_PARAMETER_ENUM or


custom_flag ABYTE CCL_BOOLEAN_ENUM Indicate custom parameter. customParamSize ABYTE 0...32 Byte size of custom parameter. SUP_PARAM_VAL_UNION New configured value. byte32Val ABYTE[] 32 bytes Custom parameter value. byte15Val ABYTE[] 15 bytes char8Val ACHAR[] 7 char char16Val ACHAR[] 15 char char32Val ACHAR[] 31 char charVal ACHAR ACHAR ucharVal ABYTE ABYTE shortVal AINT16 AINT16 ushortVal AUINT16 AUINT16 longVal AINT32 AINT32 ulongVal AUINT32 AUINT32 floatVal AFLT32 AFLT32 doubleVal AFLT64 AFLT64 timeVal ATIME32 ATIME32

Table 25. Configure Request “Sensor” Data Structure Fields Fields Type Valid Range Description CFG_SENSOR_STRUCT CCL_SENSOR_OPT_STRUCT Sensor configuration options. type ABYTE CCL_MISSION_SENSOR

_ENUM Specify sensor type to configure.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance of sensor type.

CCL_SENSOR_CFG_STRUCT control ABYTE CCL_DEVICE_CONTROL

_ENUM Configure sensor control.

sample_rate ABYTE TBD Configure sample rate. power_level ABYTE TBD Configure power level. sensitivity_threshold ABYTE TBD Configure sensitivity threshold. gain ABYTE TBD Configure gain. log_rate ABYTE TBD Configure log rate.

20

Table 26. Configure Request “Communications Interface” Data Structure Fields Fields Type Valid Range Description CFG_COMMS_IF_STRUCT CCL_COMMS_IF_OPT_STRUCT Comms interface configuration

options. type ABYTE CCL_COMM_INTERFACE

_ENUM Specify communications interface type to configure.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance of interface type.

CCL_COMMS_IF_CFG_STRUCT control ABYTE CCL_DEVICE_CONTROL

_ENUM Configure interface control.

power_level ABYTE TBD Configure power level. sensitivity_threshold ABYTE TBD Configure sensitivity threshold. gain ABYTE TBD Configure gain. baud_rate ABYTE TBD Configure baud rate.

4.2.6 Navigate Request Data Structures

Table 27. Navigate Request Data Structure Fields Fields Description Sub-structures NAV_REQ_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_REQ_HDR_STRUCT SUP_REQ_HDR_SUP_STRUCT

See Table 2.

NAV_REQ_UNION Specific type of navigate request. NAV_GPS_FIX_STRUCT Obtain a GPS fix. See Table 28. NAV_AVD_REG_STRUCT Avoid the indicated region until told otherwise. See Table 29. NAV_SET_PATH_STRUCT Define a path. See Table 30.

Table 28. Navigate Request “GPS Fix” Data Structure Fields Fields Type Valid Range Description NAV_GPS_FIX_STRUCT CCL_GPS_FIX_REQ_OPT_STRUCT GPS fix options. use_config_timeout ABYTE CCL_BOOLEAN_ENUM Specify whether to use configured

timeout or provided time interval. CCL_TIME_INTERVAL_STRUCT Provided timeout on GPS Fix. units AUINT16 CCL_TIME_INTERVAL



21

Table 29. Navigate Request “Avoid Region” Data Structure Fields Fields Type Valid Range Description NAV_AVD_REG_STRUCT CCL_AVOID_REG_REQ_OPT _STRUCT

Avoidance region options.

action AUINT16 CCL_BEHAVIOR_ACTION _ENUM

Start or stop avoiding this region.

shape AUINT16 CCL_VOLUME_GEOMETRY _ENUM

General shape of region.

x_constrained AUINT16 CCL_BOOLEAN_ENUM If true, specify lat/lng or offsets and x extent.

y_constrained AUINT16 CCL_BOOLEAN_ENUM If true, specify lat/lng or offsets and y extent.

z_constrained AUINT16 CCL_BOOLEAN_ENUM If true, specify depth and z extent. use_latlng AUINT16 CCL_BOOLEAN_ENUM If true, specify lat/lng, else origin

offsets. within_region AUINT16 CCL_BOOLEAN_ENUM Specify whether reference is inside

or outside region shape. angle ABYTE 0...180 Rotation angle of shape about its

centroid, deg ccw from north. SUP_HORZ_LOCATION_UNION CCL_LAT_LNG_STRUCT lat AFLT32 AFLT32 Centroid latitude (decimal deg.) lng AFLT32 AFLT32 Centroid longitude (decimal deg.)

CCL_NE_STRUCT north AFLT32 AFLT32 Centroid n offset from origin [m]. east AFLT32 AFLT32 Centroid e offset from origin [m].

vertLoc AFLT32 AFLT32 Centroid vertical distance value [m].

CCL_POS_TOL_STRUCT X direction extent. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying x extent. val AUINT16 0...8,191 Extent range (dynamic value).

CCL_POS_TOL_STRUCT Y direction extent. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying y extent. val AUINT16 0...8,191 Extent range (dynamic value).

CCL_POS_TOL_STRUCT Z direction extent. units AUINT16 CCL_LENGTH_UNIT_ENUM Units for specifying z extent. val AUINT16 0...8,191 Extent range (dynamic value).

22

Table 30. Navigate Request “Set Path” Data Structure Fields Fields Type Valid Range Description NAV_SET_PATH_STRUCT CCL_SET_PATH_OPT_STRUCT Path specification options. target_xy ABYTE CCL_HORZ_LOCATION

_ENUM Specify fixed horizontal path location.

per_segment_xy ABYTE CCL_BOOLEAN_ENUM Indicate if specifying per-segment horizontal locations.

target_z ABYTE CCL_VERT_LOCATION _ENUM

Specify fixed vertical path location.

per_segment_z AUINT32 CCL_BOOLEAN_ENUM Indicate if specifying per-segment vertical locations.

speed AUINT32 CCL_SPEED_ENUM Specify fixed path speed.

per_segment_spd AUINT32 CCL_BOOLEAN_ENUM Indicate if specifying per-segment speeds.

num_segments AUINT32 0...31 Number of path segments (see below). If=0, use existing specified path.

path AUINT32 CCL_MANEUVER_PATH _ENUM

Transit path specifier.

save_path AUINT32 CCL_BOOLEAN_ENUM If true, save this path using specified file and directory info.

filename_len AUINT32 0...15 Filename length. dirname_len AUINT32 0...31 Directory name length. pathkey_len AUINT32 0...15 Path reference key length. set_as_config AUINT32 CCL_BOOLEAN_ENUM Specify to make this default path. timeout AUINT32 CCL_TIME_ENUM Specify path-following behavior

timeout. SUP_HORZ_LOCATION_UNION Fixed horizontal location. CCL_LAT_LNG_STRUCT lat AFLT32 AFLT32 Fixed latitude (decimal deg.) lng AFLT32 AFLT32 Fixed longitude (decimal deg.)

CCL_NE_STRUCT north AFLT32 AFLT32 Fixed n offset from origin [m]. east AFLT32 AFLT32 Fixed e offset from origin [m].

fixedVertLoc AFLT32 AFLT32 Fixed vertical distance value [m]. fixedSpeed AUINT16 AUINT16 Fixed speed [cm/s]. NAV_PATH_SEGMENT_STRUCT 0...31 Array of path segments. CCL_LOC_SPEC_STRUCT xy_loc_spec ABYTE CCL_HORZ_LOCATION

_ENUM Specify per-segment horizontal location.

z_loc_spec ABYTE CCL_VERT_LOCATION _ENUM

Specify per-segment vertical location.

SUP_HORZ_LOCATION_UNION Per-segment waypoint location. CCL_LAT_LNG_STRUCT lat AFLT32 AFLT32 Waypoint latitude (decimal deg.) lng AFLT32 AFLT32 Waypoint longitude (decimal deg.)

CCL_NE_STRUCT north AFLT32 AFLT32 Waypoint n offset from origin [m]. east AFLT32 AFLT32 Waypoint e offset from origin [m].

vertLoc AFLT32 AFLT32 Per-segment vertical location [m]. speed AUINT16 AUINT16 Per-segment speed [cm/s].

fileName ACHAR[] 1...15 Navigation path filename. dirName ACHAR[] 0...31 Filename directory, 0=default

directory. pathKey ACHAR[] 0...15 Unique path file reference key.

23

SUP_TIME_UNION timeAbs ATIME32 ATIME32 Absolute time for ending path-

following behavior. CCL_TIME_INTERVAL_STRUCT Relative time for ending behavior. units AUINT16 CCL_TIME_INTERVAL



4.2.7 Inform Header Data Structures

Table 31. Inform Message Header Data Structure Fields Fields Type Valid Range Description SUP_INTERPROC_CXT_STRUCT Interprocess context information. internalMsg ABOOL 0,1 Destination of this message

(internal=1 or external=0). processID AINT32 AINT32 Process ID. Utility field for internal

platform messaging. contextID AINT32 AINT32 Utility field for internal platform

messaging. taskName ACHAR[] 15 char Process task name. Utility field for

internal platform messaging. SUP_MSG_ADDRESS_STRUCT Message address info. CCL_ADDRESS_STRUCT Source of message.

group_id ABYTE 0...2 Source group ID. host_id ABYTE 0...62 Source host ID. CCL_ADDRESS_STRUCT Destination for message. group_id ABYTE 0...3 (broadcast=3) Destination group ID. host_id ABYTE 0...63 (broadcast=63) Destination host ID. CCL_HDR_STRUCT context ABYTE CCL_CONTEXT_ENUM Type of ‘inform’. beh_type ABYTE CCL_BEH_ENUM Generic behavior category. string_api_support ABYTE CCL_BOOLEAN_ENUM Is ASCII message formatting

supported? beh_subtype AUINT16 CCL_MANEUVER_ENUM,

CCL_NAVIGATE_ENUM, CCL_COMMUNICATE_ENUM, CCL_CONFIGURE_ENUM, CCL_MONITOR_ENUM, or CCL_EXEC_CONV_ENUM

Flavor of behavior, depending on generic behavior category.

thread_id AUINT16 0...8,191 Message context thread ID. CCL_INF_HDR_STRUCT raison_d_etre ABYTE CCL_RDE_ENUM Reason for this message. ack_type ABYTE CCL_ACK_TYPE_ENUM If applicable, specify ack type. ack_status ABYTE CCL_ACK_STATUS_ENUM Additional ack type info.

SUP_INF_HDR_SUP_STRUCT CCL_ADDRESS_STRUCT Solicitor of this message. group_id ABYTE 0...2 Solicitor’s group ID. host_id ABYTE 0...62 Solicitor’s host ID.

24

4.2.8 Monitor Inform Data Structures

Table 32. Monitor Inform Data Structure Fields Fields Description Sub-structures MON_INF_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

MON_INF_UNION Specific type of report. MON_INF_STATUS_STRUCT Report on system status. See Table 33. CCL_CAPS_STRUCT Report on system capabilities. See Table 34. MON_INF_FILE_STRUCT Report on a file. See Table 35. MON_INF_SENSOR_CAPS_STRUCT Report on mission sensor capabilities. See Table 36. MON_INF_COMMS_CAPS_STRUCT Report on communication interface capabilities. See Table 37.

Table 33. Monitor Inform “Status Report” Data Structure Fields Fields Type Valid Range Description MON_INF_STATUS_STRUCT CCL_STATUS_INF_OPT_STRUCT Status report options. extended_params ABYTE 0...15 Number of extended parameters.

CCL_STATUS_STRUCT time ATIME32 ATIME32 Status collection time [sec]. agent_id AUINT32 0...62 Reporting agent host ID. group_id AUINT32 0...2 Reporting agent group ID. health AUINT32 CCL_PLATFORM_HEALTH

_ENUM Overall system health indicator.

heading AUINT32 0...359 Platform heading [deg]. speed AUINT32 0...1,023 Platform speed [cm/s]. avoiding_obstacle AUINT32 CCL_BOOLEAN_ENUM Indicator if avoiding obstacle. current_nav AUINT16 CCL_NAVIGATION_ENUM Current navigation strategy. maneuver_type AUINT16 CCL_MANEUVER_CONTROL

_ENUM Current maneuver behavior.

maneuver_index AUINT16 0...255 Current maneuver index ID. ops_mode AUINT16 CCL_OPERATIONS_MODE

_ENUM Operations mode.

altitude AUINT16 AUINT16 Platform altitude [cm]. available_energy AUINT16 AUINT16 Current available energy [whrs]. depth AFLT32 AFLT32 Platform depth [m]. lat AFLT32 AFLT32 Platform latitude [decimal deg]. lng AFLT32 AFLT32 Platform longitude [decimal deg]. path_segment AUINT32 0...255 Current path segment index ID. num_tasks AUINT32 0...7 Number of valid aggregate

behavior IDs (experimental). taskID_1 AUINT32 0...7 Aggregate behavior ID. taskID_2 AUINT32 0...7 Aggregate behavior ID. taskID_3 AUINT32 0...7 Aggregate behavior ID. taskID_4 AUINT32 0...7 Aggregate behavior ID. taskID_5 AUINT32 0...7 Aggregate behavior ID. taskID_6 AUINT32 0...7 Aggregate behavior ID. taskID_7 AUINT32 0...7 Aggregate behavior ID.

25

platform_mode ABYTE CCL_PLATFORM_CONTROL _ENUM

Current platform control mode.

MON_STATUS_INF_PARAM _STRUCT

0...15 Array of optional extended parameter info.

CCL_PARAM_ACCESS_INFO _STRUCT

access_status ABYTE CCL_ACCESS_PARAM_ENUM Success at accessing parameter. init_state ABYTE CCL_PARAM_STATE_ENUM Indicator if parameter is initialized.

SUP_PARAM_STRUCT CCL_PARAM_ID_STRUCT parameter_id ABYTE CCL_PARAMETER_ENUM or


custom_flag ABYTE CCL_BOOLEAN_ENUM Indicate custom parameter. customParamSize ABYTE 0...32 Byte size of custom parameter. SUP_PARAM_VAL_UNION Extended parameter report values. byte32Val ABYTE[] 32 bytes Custom parameter value. byte15Val ABYTE[] 15 bytes char8Val ACHAR[] 7 char char16Val ACHAR[] 15 char char32Val ACHAR[] 31 char charVal ACHAR ACHAR ucharVal ABYTE ABYTE shortVal AINT16 AINT16 ushortVal AUINT16 AUINT16 longVal AINT32 AINT32 ulongVal AUINT32 AUINT32 floatVal AFLT32 AFLT32 doubleVal AFLT64 AFLT64 timeVal ATIME32 ATIME32

deriv ABYTE CCL_VALUE_DERIVATIVE _ENUM

Specify extended parameter value or derivative.

CCL_TIME_INTERVAL_STRUCT For 1st and 2nd derivative report. units AUINT16 CCL_TIME_INTERVAL



Table 34. Monitor Inform “System Capabilities Report” Data Structure Fields Fields Type Valid Range Description CCL_CAPS_STRUCT lang_release AUINT16 CCL_BOOLEAN_ENUM CCL release/pre-release version

indicator. lang_major_rev AUINT16 0...15 CCL major version number. lang_minor_rev AUINT16 0...2,047 CCL minor version number. name ACHAR[] 0...15 Platform name. agent_id ABYTE 0...62 Platform host ID. group_id ABYTE 0...2 Platform group ID. platform_class AUINT32 CCL_PLATFORM_CLASS

_ENUM Size class of platform.

ops_range AUINT32 0...16,383 Operational range [km]. mission_role AUINT32 CCL_MISSION_ROLE_ENUM Primary mission role. ops_mode AUINT32 CCL_OPERATIONS_MODE

_ENUM Primary mission operations mode.

length AUINT32 0...1.023 Representative length [dm]. longitudinal_control AUINT32 CCL_BOOLEAN_ENUM Longitudinal control capability. lateral_control AUINT32 CCL_BOOLEAN_ENUM Lateral control capability. body_type AUINT32 CCL_BODY_ENUM Platform body type. propulsion_type AUINT32 CCL_PROPULSION_ENUM Platform propulsion system. displacement AUINT32 0...65,535 Platform displacement [kg].

26

diameter AUINT32 0...1,023 Representative diameter [cm]. vertical_control AUINT32 CCL_BOOLEAN_ENUM Vertical control capability. max_depth AUINT32 0...16,383 Maximum command depth [m]. min_altitude AUINT32 0...16,383 Minimum command altitude [cm]. heading_control AUINT32 CCL_BOOLEAN_ENUM Heading (yaw) control capability. pitch_control AUINT32 CCL_BOOLEAN_ENUM Pitch control capability. roll_control AUINT32 CCL_BOOLEAN_ENUM Roll control capability. max_roll AUINT32 0...180 Symmetric max roll angle [deg]. min_turn_radius AUINT32 0...1,023 Minimum turn radius [dm]. max_speed AUINT32 0...1,023 Maximum command speed [cm/s]. underwater_navigation AUINT32 CCL_NAVIGATION_ENUM Primary underwater navigation

scheme. surface_navigation AUINT32 CCL_NAVIGATION_ENUM Primary surface navigation scheme. min_speed AUINT32 0...1,023 Minimum command speed [cm/s]. cruise_speed AUINT32 0...1,023 Cruise command speed [cm/s]. max_yaw_rate AUINT32 0...255 Maximum yaw rate [deg/s]. min_pitch AUINT32 0...90 Minimum pitch angle [deg]. max_pitch AUINT32 0...90 Maximum pitch angle [deg]. obstacle_avoid_ss AUINT32 CCL_BOOLEAN_ENUM Obstacle avoidance capability. available_energy AUINT32 0...65,535 Currently available energy [whrs]. reserve_energy AUINT32 0...65,535 Reserve energy capacity [whrs]. capacity_energy AUINT32 0...65,535 Maximum energy capacity [whrs]. endurance_units AUINT32 CCL_TIME_INTERVAL

_ENUM Units of platform endurance estimate.

endurance_low_load AUINT32 0...1,023 Estimate of platform endurance under “low” energy loading or “optimistic” conditions.

endurance_high_load AUINT32 0...1,023 Estimate of platform endurance under “high” energy loading or “conservative” conditions.

energy_strategy AUINT32 CCL_ENERGY_MANAGEMENT _ENUM

Primary platform energy management strategy.

other_energy AUINT32 CCL_BOOLEAN_ENUM Other energy source or storage capability.

solar_energy AUINT32 CCL_BOOLEAN_ENUM Solar energy generation capability. fuel_cell_energy AUINT32 CCL_BOOLEAN_ENUM Fuel cell energy capability. diesel_energy AUINT32 CCL_BOOLEAN_ENUM Diesel energy capability. nuclear_energy AUINT32 CCL_BOOLEAN_ENUM Nuclear energy capability. data_collect_role AUINT32 CCL_DATA_COLLECTION

_ENUM Primary mission data collection role.

disk_capacity AUINT32 0...1,048,575 Mission data store capacity [MB]. disk_pct_available AUINT32 0...100 Mission data store available [%]. network_protocol AUINT32 CCL_NETWORK_PROTOCOL

_ENUM Primary platform network protocol.

other_comms AUINT32 0...3 Number of instances of “other” comms interface types.

satellite_comms AUINT32 0...3 Number of instances of satellite comms interface types.

acoustic_comms AUINT32 0...3 Number of instances of acoustic comms interface types.

rf_comms AUINT32 0...3 Number of instances of RF comms interface types.

cellular_comms AUINT32 0...3 Number of instances of cellular comms interface types.

cpu_capability AUINT32 0...255 Benchmark index for primary controller CPU [ref machine TBD].

other_sensors AUINT32 0...3 Number of instances of “other” mission sensor types.

ctd_sensors AUINT32 0...3 Number of instances of CTD mission sensor types.

27

pressure_sensors AUINT32 0...3 Number of instances of pressure sensor mission sensor types.

altimeter_sensors AUINT32 0...3 Number of instances of altimeter mission sensor types.

temperature_sensors AUINT32 0...3 Number of instances of temperature mission sensor types.

salinity_sensors AUINT32 0...3 Number of instances of salinity mission sensor types.

conductivity_sensors AUINT32 0...3 Number of instances of conductivity mission sensor types.

dissolved_oxygen_sensors AUINT32 0...3 Number of instances of DO mission sensor types.

fluorometer_sensors AUINT32 0...3 Number of instances of fluorometer mission sensor types.

turbidity_sensors AUINT32 0...3 Number of instances of turbidity mission sensor types.

transmissometer_sensors AUINT32 0...3 Number of instances of transmissometer mission sensor types.

optical_backscatter _sensors

AUINT32 0...3 Number of instances of optical backscatter mission sensor types.

dvl_sensors AUINT32 0...3 Number of instances of DVL mission sensor types.

magnetic_flux_sensors AUINT32 0...3 Number of instances of magnetic flux mission sensor types.

subbottom_profiler_sensors AUINT32 0...3 Number of instances of subbottom profiler mission sensor types.

sidescan_sonar_sensors AUINT32 0...3 Number of instances of sidescan sonar mission sensor types.

multibeam_sonar_sensors AUINT32 0...3 Number of instances of multibeam sonar mission sensor types.

still_cameras AUINT32 0...3 Number of instances of still camera mission sensor types.

video_cameras AUINT32 0...3 Number of instances of video camera mission sensor types.

audio_recorders AUINT32 0...3 Number of instances of audio recorder mission sensor types.

Table 35. Monitor Inform “File Report” Data Structure Fields

Fields Type Valid Range Description MON_INF_FILE_STRUCT CCL_FILE_INF_OPT_STRUCT File report options. file_access_status AUINT16 CCL_FILE_ACCESS_ENUM File access status. file_size AUINT16 0...511 File size in bytes. filename_len AUINT16 1...15 File name length. content_type ABYTE CCL_FILE_CONTENT_ENUM File content type. encoding ABYTE CCL_FILE_ENCODING

_ENUM File encoding type.

name ACHAR[] 1...15 File name. contents ABYTE[] 0...511 File contents [B].

28

Table 36. Monitor Inform “Sensor Capabilities” Data Structure Fields Fields Type Valid Range Description MON_INF_SENSOR_CAPS_STRUCT CCL_SENSOR_CAPS_INF_OPT _STRUCT

Sensor capabilities report options.

num_sensor_caps ABYTE 0...7 Number of sensor capability descriptions in this report.

MON_SENSOR_CAPS_INF_STRUCT 0...7 Array of sensor capabilities. CCL_SENSOR_CAPS_STRUCT Specific sensor capability. type AUINT16 CCL_MISSION_SENSOR

_ENUM Mission sensor type.

instance AUINT16 0...3 Specific instance of sensor. 0=all instances, 1-3= specific instance.

sensor_class AUINT16 CCL_SENSOR_CLASS_ENUM Sensor class type. description_len AUINT16 0...15 Sensor descriptive label length. state AUINT16 CCL_DEVICE_STATE_ENUM Mission sensor state. active AUINT16 CCL_SENSOR_ACTIVE

_ENUM Sensor active trigger type.

directionality AUINT16 CCL_SENSOR_DIRECTION _ENUM

Sensor directionality type.

sample_rate AUINT16 TBD Sample rate. power_level AUINT16 TBD Power level. sensitivity_threshold AUINT16 TBD Sensitivity threshold. gain AUINT16 TBD Gain. log_rate AUINT16 TBD Log rate. range AUINT16 TBD Range. sensitivity_at_range AUINT16 TBD Sensitivity at range. resolution AUINT16 TBD Resolution. frequency_at_resolution AUINT16 TBD Frequency at resolution. power_use_on_units AUINT16 CCL_POWER_UNIT_ENUM Units for specifying power usage

while sensor is on. power_use_on AUINT16 0...1,023 Power usage while on (dynamic

value). power_use_sleep_units AUINT16 CCL_POWER_UNIT_ENUM Units for specifying power usage

while sensor in sleep mode. power_use_sleep AUINT16 0...1,023 Power usage when sleeping

(dynamic value). description ACHAR[] 0...15 Sensor description.

Table 37. Monitor Inform “Comms Interface Capabilities” Data Structure Fields Fields Type Valid Range Description MON_INF_COMMS_CAPS_STRUCT CCL_COMMS_CAPS_INF_OPT _STRUCT

Comms interface capabilities report options.

num_comms_caps ABYTE 0...7 Number of comms interface capability descriptions in this report.

MON_COMMS_CAPS_INF_STRUCT 0...7 Array of comms capabilities. CCL_COMMS_CAPS_STRUCT Specific comms interface

capability. type AUINT16 CCL_COMM_INTERFACE

_ENUM Comms interface type.

instance AUINT16 0...3 Specific instance of interface. 0=all instances, 1-3= specific instance.

description_len AUINT16 0...15 Interface descriptive label length.

29

state AUINT16 CCL_DEVICE_STATE_ENUM Comms interface state. power_level AUINT16 TBD Power level. sensitivity_threshold AUINT16 TBD Sensitivity threshold. gain AUINT16 TBD Gain. baud_rate AUINT16 TBD Baud rate. range ABYTE TBD Range. sensitivity_at_range ABYTE TBD Sensitivity at range. resolution ABYTE TBD Resolution. frequency_at_resolution ABYTE TBD Frequency at resolution. power_use_on_units AUINT16 CCL_POWER_UNIT_ENUM Units for specifying power usage

while interface is on. power_use_on AUINT16 0...1,023 Power usage while on (dynamic

value). power_use_sleep_units AUINT16 CCL_POWER_UNIT_ENUM Units for specifying power usage

while interface in sleep mode. power_use_sleep AUINT16 0...1,023 Power usage when sleeping

(dynamic value). description ACHAR[] 0...15 Comms interface description.

4.2.9 Execute Convention Inform Data Structure

Table 38. Execute Convention Inform Data Structure Fields Fields Description Sub-structures EXC_INF_STRUCT Generic acknowledgment message. SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

4.2.10 Maneuver Inform Data Structure

Table 39. Maneuver Inform Data Structure Fields Fields Description Sub-structures MAN_INF_STRUCT Generic acknowledgment message. SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

30

4.2.11 Configure Inform Data Structure

Table 40. Configure Inform Data Structure Fields Fields Description Sub-structures CFG_INF_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

CFG_INF_UNION Specific type of configure failure acknowledgement. CFG_PARAMS_ACK_STRUCT Detailed failure report on configuring system parameters. See Table 41. CFG_SENSOR_ACK_STRUCT Detailed failure report on configuring a mission sensor. See Table 42. CFG_COMMS_IF_ACK_STRUCT Detailed failure report on configuring a comms interface. See Table 43.

Table 41. Configure Inform “System Parameters” Data Structure Fields Fields Type Valid Range Description CFG_PARAMS_ACK_STRUCT CCL_CFG_PARAMS_INF_OPT _STRUCT

Detailed ack of failed configure attempt of system parameters.

num_params ABYTE 1...15 Number of system parameters in this ack message which failed configuration.

CFG_PARAM_VAL_ACCESS _STRUCT

1...15 Array of parameter status which failed configuration.

CCL_PARAM_ID_STRUCT Specific parameter. parameter_id ABYTE CCL_PARAMETER_ENUM or


custom_flag ABYTE CCL_BOOLEAN_ENUM Indicate custom parameter. CCL_PARAM_ACCESS_INFO _STRUCT

Reason for configuration failure.

access_status ABYTE CCL_ACCESS_PARAM_ENUM Success at configuring parameter. init_state ABYTE CCL_PARAM_STATE_ENUM Indicator if parameter is initialized.

Table 42. Configure Inform “Sensor” Data Structure Fields

Fields Type Valid Range Description CFG_SENSOR_ACK_STRUCT CCL_SENSOR_OPT_STRUCT Detailed ack of failed configure

attempt of mission sensor. type ABYTE CCL_MISSION_SENSOR

_ENUM Specify sensor type to configure.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance of sensor type.

CCL_CFG_SENSOR_FAIL_STRUCT Sensor which failed configuration. control_set_fail ABYTE CCL_BOOLEAN_ENUM Control set failure indicator. sample_rate_set_fail ABYTE CCL_BOOLEAN_ENUM Sample rate set failure indicator. power_level_set_fail ABYTE CCL_BOOLEAN_ENUM Power level set failure indicator. sensitivity_thresh_set _fail

ABYTE CCL_BOOLEAN_ENUM Sensitivity threshold set failure indicator.

gain_set_fail ABYTE CCL_BOOLEAN_ENUM Gain set failure indicator. log_rate_set_fail ABYTE CCL_BOOLEAN_ENUM Log rate set failure indicator.

31

Table 43. Configure Inform “Communications Interface” Data Structure Fields Fields Type Valid Range Description CFG_COMMS_IF_ACK_STRUCT CCL_COMMS_IF_OPT_STRUCT Detailed ack of failed configure

attempt of comms interface. type ABYTE CCL_COMM_INTERFACE

_ENUM Specify communications interface type to configure.

instance ABYTE 0...3 0=all instances, 1,2,3=specific instance of interface type.

CCL_CFG_COMMS_IF_FAIL _STRUCT

Comms interface which failed configuration.

control_set_fail ABYTE CCL_BOOLEAN_ENUM Control set failure indicator. power_level_set_fail ABYTE CCL_BOOLEAN_ENUM Power level set failure indicator. sensitivity_thresh_set _fail

ABYTE CCL_BOOLEAN_ENUM Sensitivity threshold set failure indicator.

gain_set_fail ABYTE CCL_BOOLEAN_ENUM Gain set failure indicator. baud_rate_set_fail ABYTE CCL_BOOLEAN_ENUM Baud rate set failure indicator.

4.2.12 Navigate Inform Data Structure

Table 44. Navigate Inform Data Structure Fields Fields Description Sub-structures NAV_INF_STRUCT Generic acknowledgment message. SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

4.2.13 Communicate Inform Data Structure

Table 45. Communicate Inform Data Structure Fields Fields Description Sub-structures COM_INF_STRUCT SUP_INTERPROC_CXT_STRUCT SUP_MSG_ADDRESS_STRUCT CCL_HDR_STRUCT CCL_INF_HDR_STRUCT SUP_INF_HDR_SUP_STRUCT

See Table 31.

COM_MESSAGE_STRUCT Container for unsolicited and/or custom messages.

32

Table 46. Communicate Inform “Message” Data Structure Fields

Fields Type Valid Range Description COM_MESSAGE_STRUCT CCL_MSG_INF_OPT_STRUCT Message options. message_size AUINT16 0...255 Size of message contents [B]. encoding AUINT16 CCL_FILE_ENCODING

_ENUM Encoding of message contents.

content_type AUINT16 CCL_FILE_CONTENT_ENUM Type of message contents. msg ABYTE[] 0...255 Array of message contents.

4.3 Error Codes A standard return code is used with all API functions to inform the calling code the status of the call. These codes and their respective English gloss are shown in Fig. 6. typedef enum SUP_SERIAL_ERROR_ENUM { SUP_SERIAL_NO_ERROR, SUP_SERIAL_LIB_BUF_LEN_EXCEEDED, SUP_SERIAL_USER_BUF_LEN_EXCEEDED, SUP_SERIAL_ZERO_LEN_BUF, SUP_SERIAL_BYTE_MISMATCH, SUP_SERIAL_UNSUPPORTED_ENUM, SUP_SERIAL_UNSUP_CXT_TYPE, SUP_SERIAL_UNSUP_BEH_TYPE, SUP_SERIAL_UNSUP_BEH_SUBTYPE, SUP_SERIAL_VAL_OUT_OF_RANGE, SUP_SERIAL_STR_MISSING_TOKEN, SUP_SERIAL_STR_UNKNOWN_TOKEN, SUP_SERIAL_STR_API_UNSUPPORTED, SUP_SERIAL_ERROR_ENUM_MAX // array bounds usage, not a language element } SUP_SERIAL_ERROR_ENUM; static ACHAR* SUP_SERIAL_ERROR_STR[] = { "No Error", "Error: Library buffer length exceeded", "Error: User buffer length exceeded", "Error: Zero length buffer", "Error: Byte length mismatch", "Error: Unsupported enumeration", "Error: Unsupported message context type", "Error: Unsupported message behavior type", "Error: Unsupported message behavior subtype", "Error: Value out of range", "Error: Missing string token", "Error: Unknown string token", "Error: ASCII string API does not support this message" };

Figure 6. Error Code Set with Associated ASCII Strings

33

4.4 General Support Functions Below are the functions used to find the CCL language and library versions and to determine the type (e.g. Maneuver, Navigate) and context (e.g. Inform, Request) of a message.

4.4.1 getCCL_LanguageVersion () This function is used to find the CCL language version that this library is equipped to parse. Do not use this library for any version of CCL other than the one it was designed for. It uses the following signature: CCL_VERSION_STRUCT getCCL_LanguageVersion() Inputs: <none> Outputs: <none> Return Value: CCL_VERSION_STRUCT, a structure copy containing the pre-release/release flag, in addition to major and minor version numbers.

4.4.2 getCCL_LibraryVersion () This function is used to get the software library version. It uses the following signature: CCL_VERSION_STRUCT getCCL_LibraryVersion() Inputs: <none> Outputs: <none> Return Value: CCL_VERSION_STRUCT, a structure copy containing the pre-release/release flag, in addition to major and minor version numbers.

4.4.3 getCCL_TypeAndContext() This function is used to returns the CCL_BEH_ENUM and CCL_CONTEXT_ENUM of a payload message, to indicate the proper deserialization routine to be called. It uses the following signature: SUP_SERIAL_ERROR_ENUM getCCL_TypeAndContext(const ABYTE* payload, AUINT32 payloadLen,

CCL_BEH_ENUM* type, CCL_CONTEXT_ENUM* context, CCL_BOOLEAN_ENUM* stringAPIsupported)

Inputs:

payload Pointer to a user input CCL message. payloadLen Length of the actual CCL message. Outputs:

type Pointer to a CCL_BEH_ENUM variable indicating type of CCL message. context Pointer to a CCL_CONTEXT_ENUM variable indicating the context of the

message. stringAPIsupported Pointer to a CCL_BOOLEAN_ENUM indicating if this message may be

safely de-serialized using the ASCII string API. Return Value: Error code as SUP_SERIAL_ERROR_ENUM. Note that the type variable is not altered if an error is encountered.

34

4.5 Low Level Serialization / De-serialization Functions Listed below are the functions used to serialize and de-serialize messages. Data structures have been defined which are used as containers for message commands, information and data, and are used in the API of the serialization and de-serialization functions. To serialize a message, the user first fills the appropriate container structure, then passes this structure to the appropriate serialization routine. This produces a byte string optimized for minimum size which can then be passed to the communications interface. Conversely, to de-serialize a message, the user passes the received byte string to the appropriate de-serialization function. The function will then fill an empty container structure with values found in the byte string. The user can then pull these values from the returned container structure. The optimized byte string formats are defined in the “Layer 1 – CCL Vocabulary and Message Set Specification”. The functions and associated container structures provide the most comprehensive method for specifying messages using the CCLv2 language. It does require the user to know how to fill the structures appropriately. See Sections 4.5 and 5 for a description of methods for constructing and de-constructing messages using human-readable ASCII strings.

35

4.5.1 serialMON_Req() and serialMON_Inf() Monitor and Report is the primary interface for specifying how the platform should watch and record some aspect of itself or environment and report these aspects to others. It contains provisions to express one of five message types: Status, Capabilities, File, Sensor Capabilities and Comms Interface Capabilities. The functions described in this section provide a mechanism to convert commands, information and data encoded in a MON_REQ_STRUCT or MON_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLmonitor.h for definitions of the appropriate container structures. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM serialMON_Req(const MON_REQ_STRUCT* monReq, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) SUP_SERIAL_ERROR_ENUM serialMON_Inf(const MON_INF_STRUCT* monInf, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) Inputs:

monReq / monInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must

be at least as large as required to hold the serialized payload byte string. bufLen Length of the pre-allocated ABYTE output serial buffer.

Outputs:

buf Buffer filled with serialized payload. payloadLen Actual length of filled buffer.

Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

4.5.2 deserialMON_Req() and deserialMON_Inf() These functions provide a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard MON_REQ_STRUCT or MON_INF_STRUCT container structure. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM deserialMON_Req(const ABYTE* buf, AUINT32 payloadLen, MON_REQ_STRUCT* monReq) SUP_SERIAL_ERROR_ENUM deserialMON_Inf(const ABYTE* buf, AUINT32 payloadLen, MON_INF_STRUCT* monInf) Inputs:

buf Buffer filled with serialized payload. payloadLen Length of input ABYTE serial buffer.

monReq / monInf Pre-allocated empty container structure to be filled with message data. Outputs:

monReq / monInf Container structure filled with message data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

36

4.5.3 serialEXC_Req() and serialEXC_Inf() Execute Convention is the primary interface for specifying how a platform should carry out a well-known action. It contains provisions to express one of seven message types: System Admin, Start Mission, Stop Mission, Abort Mission, Start Behavior, Stop Behavior, and Update Behavior. The functions described in this section provide a mechanism to convert commands, information and data encoded in a EXC_REQ_STRUCT or EXC_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLexecConvention.h for definitions of the appropriate container structures. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM serialEXC_Req(const EXC_REQ_STRUCT* excReq, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) SUP_SERIAL_ERROR_ENUM serialEXC_Inf(const EXC_INF_STRUCT* excInf, ABYTE* buf, AUINT32 bufLen,


excReq / excInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must


Outputs:



4.5.4 deserialEXC_Req() and deserialEXC_Inf() These functions provide a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard EXC_REQ_STRUCT or EXC_INF_STRUCT container structure. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM deserialEXC_Req(const ABYTE* buf, AUINT32 payloadLen, EXC_REQ_STRUCT* excReq) SUP_SERIAL_ERROR_ENUM deserialEXC_Inf(const ABYTE* buf, AUINT32 payloadLen, EXC_INF_STRUCT* excInf) Inputs:


excReq / excInf Pre-allocated empty container structure to be filled with message data. Outputs:

excReq / excInf Container structure filled with message data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

37

4.5.5 serialMAN_Req() and serialMAN_Inf() Maneuver is the primary interface for commanding the platform to move or relocate itself to a new position. It contains provisions to express one of five specific message types: GoTo Waypoint, Follow Path, Speed and Bearing, Move, and Station Keep. The functions described in this section provide a mechanism to convert commands, information and data encoded in a MAN_REQ_STRUCT or MAN_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLmaneuver.h for definitions of the appropriate container structures. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM serialMAN_Req(const MAN_REQ_STRUCT* manReq, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) SUP_SERIAL_ERROR_ENUM serialMAN_Inf(const MAN_INF_STRUCT* manInf, ABYTE* buf, AUINT32 bufLen,


manReq / manInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must


Outputs:



4.5.6 deserialMAN_Req() and deserialMAN_Inf() These functions provide a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard MAN_REQ_STRUCT or MAN_INF_STRUCT container structure. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM deserialMAN_Req(const ABYTE* buf, AUINT32 payloadLen, MAN_REQ_STRUCT* manReq) SUP_SERIAL_ERROR_ENUM deserialMAN_Inf(const ABYTE* buf, AUINT32 payloadLen, MAN_INF_STRUCT* manInf) Inputs:


manReq / manInf Pre-allocated empty container structure to be filled with message data. Outputs:

manReq / manInf Container structure filled with message data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

38

4.5.7 serialCFG_Req() and serialCFG_Inf() Configure is the primary interface for specifying how the platform should reconfigure aspects of itself. It contains provisions to express one of three message types: System Parameters, Sensor and Comms Interface, reflecting the notion that key internal aspects of the platform can be accessed and modified. The functions described in this section provide a mechanism to convert commands, information and data encoded in a CFG_REQ_STRUCT or CFG_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLconfigure.h for definitions of the appropriate container structures. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM serialCFG_Req(const CFG_REQ_STRUCT* cfgReq, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) SUP_SERIAL_ERROR_ENUM serialCFG_Inf(const CFG_INF_STRUCT* cfgInf, ABYTE* buf, AUINT32 bufLen,


cfgReq / cfgInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must


Outputs:



4.5.8 deserialCFG_Req() and deserialCFG_Inf() These functions provide a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard CFG_REQ_STRUCT or CFG_INF_STRUCT container structure. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM deserialCFG_Req(const ABYTE* buf, AUINT32 payloadLen, CFG_REQ_STRUCT* cfgReq) SUP_SERIAL_ERROR_ENUM deserialCFG_Inf(const ABYTE* buf, AUINT32 payloadLen, CFG_INF_STRUCT* cfgInf) Inputs:


cfgReq / cfgInf Pre-allocated empty container structure to be filled with message data. Outputs:

cfgReq / cfgInf Container structure filled with message data. Return Value: rror code as SUP_SERIAL_ERROR_ENUM.

39

4.5.9 serialNAV_Req() and serialNAV_Inf() Navigate is the primary interface for specifying path constraints and position updates for the platform as it maneuvers. It contains provisions to express one of three message types: GPS Fix, Avoid Region and Set Path. The functions described in this section provide a mechanism to convert commands, information and data encoded in a NAV_REQ_STRUCT or NAV_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLnavigate.h for definitions of the appropriate container structures. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM serialNAV_Req(const NAV_REQ_STRUCT* navReq, ABYTE* buf, AUINT32 bufLen,

AUINT32* payloadLen) SUP_SERIAL_ERROR_ENUM serialNAV_Inf(const NAV_INF_STRUCT* navInf, ABYTE* buf, AUINT32 bufLen,


navReq / navInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must


Outputs:



4.5.10 deserialNAV_Req() and deserialNAV_Inf() These functions provide a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard NAV_REQ_STRUCT or NAV_INF_STRUCT container structure. These functions employ the following signatures: SUP_SERIAL_ERROR_ENUM deserialNAV_Req(const ABYTE* buf, AUINT32 payloadLen, NAV_REQ_STRUCT* navReq) SUP_SERIAL_ERROR_ENUM deserialNAV_Inf(const ABYTE* buf, AUINT32 payloadLen, NAV_INF_STRUCT* navInf) Inputs:


navReq / navInf Pre-allocated empty container structure to be filled with message data. Outputs:

navReq / navInf Container structure filled with message data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

40

4.5.11 serialCOM_Inf() Communicate is the primary interface for implementing the sending and receiving of messages between platforms. There are currently no message request types specified. As for message inform types, Message is used as a container for unsolicited inform type communications. The function described in this section provides a mechanism to convert commands, information and data encoded in a COM_INF_STRUCT container structure into a low level byte string suitable for use by the communications interface. See the file CCLcommunicate.h for definitions of the appropriate container structures. This function employs the following signature: SUP_SERIAL_ERROR_ENUM serialCOM_Inf(const COM_INF_STRUCT* comInf, ABYTE* buf, AUINT32 bufLen,


comInf Container structure holding information to be serialized. buf Pre-allocated ABYTE serial buffer to fill with payload string. The buffer must


Outputs:



4.5.12 deserialCOM_Inf() This function provides a mechanism to de-construct a low level byte string typically received by the communications interface and fill a standard COM_INF_STRUCT container structure. This function employs the following signature: SUP_SERIAL_ERROR_ENUM deserialCOM_Inf(const ABYTE* buf, AUINT32 payloadLen, COM_INF_STRUCT* comInf) Inputs:


comInf Pre-allocated empty container structure to be filled with message data. Outputs:

comInf Container structure filled with message data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

41

4.6 ASCII String Messaging Functions The two functions below are used to serialize and deserialize human-readable ASCII strings to and from, respectively, the binary format used in message transmission. This method provides an alternative to using the utility data structures and API described in sections 4.2 and 4.5. Presently though, only a subset of the full CCL specification is implemented in the library. The ASCII string formats are described in detail in Section 5.

4.6.1 serialCCLstr() This function provides a mechanism to create a CCLv2 binary message based on an ASCII string input. The ASCII string is composed of a mix of CCL vocabulary strings and numerical values separated by whitespace. This function is essentially a parsing wrapper which uses the routines described in section 4.4 to convert the ASCII string to the low level byte string suitable for use by the communications interface. It uses the following signature: SUP_SERIAL_ERROR_ENUM serialCCLstr(const ACHAR* str, ABYTE* buf, AUINT32 bufLen,


buf Pre-allocated ABYTE buffer to fill with payload string must be at least as large as serialized payload length.

bufLen Length of input ABYTE buffer. str ASCII message string to be serialized. Outputs: buf Buffer filled with serialized payload. payloadLen Length of buf payload actually filled with data. Return Value: Error code as SUP_SERIAL_ERROR_ENUM.

4.6.2 deserialCCLstr() This function provides a mechanism to create an ASCII string from an input CCLv2 binary message. The ASCII string is nominally composed of a mix of CCL vocabulary strings and numerical values separated by whitespace, unless the verbose switch is used, which generates a more human-readable output. This function is essentially a parsing wrapper which uses the routines described in section 4.4 to convert the low level byte string received by the communications interface to a human-readable ASCII string. It uses the following signature: SUP_SERIAL_ERROR_ENUM deserialCCLstr(const ABYTE* buf, AUINT32 payloadLen, ACHAR* str,

AUINT32 strLen, ABYTE verbose) Inputs:


str Pre-allocated ACHAR buffer to fill with payload string. The buffer must be at least as large as required to hold the de-serialized payload ASCII string.

payloadLen Length of the ACHAR string output buffer. verbose Adjust formatting of output string: 0=standard whitespace separated keywords

and numerical values, 1=column formatted output with units. Outputs:

str ACHAR buffer filled with de-serialized payload string. Note that the string is filled with valid ASCII content up to the point where an error occurs.


42

5 ASCII String Message Format Below are the formatting rules for how messages are constructed and de-constructed into human-readable strings. This API was developed to provide a simple way for human users to build and parse messages. It uses the serialCCLstr() and deserialCCLstr() functions defined in section 4.3 to convert these strings to and from the low level byte strings. The appropriate vocabulary string labels (e.g. CCL_PLATFORM_HEALTH_STR) are defined in the CCL.h file. This API currently provides only a subset of the full messaging capability that is available when directly using the container structures and low level functions described in section 4.4. The available syntax supports what we believe to be some of the most useful message types at this time. To keep the syntax simple, many of the less common message options are preset; continued field testing and user feedback will help us adjust this syntax, including which options are exposed and which are preset, as further development occurs. To guarantee that messages will be properly serialized and de-serialized, this API relies on the use of the ‘string_api_support’ variable in the CCL_HDR_STRUCT portion of every message. A message which is received with this bit set true is guaranteed to be able to be parsed using this API. A call to getCCL_TypeAndContext() will provide the value of this bit for a received message. Messages which are constructed using this API will automatically have this bit set true. For request messages, there are several keywords and variables which may be set. A thread variable provides a unique conversation thread ID and may be set by the user if desired. If not used, a value of “0” is set for the thread ID. Acknowledgment of message receipt and completion may be set; if not, the default is ‘no acknowledgment requested’. Authority and grouping are not used, and the default behavior stacking rule is set to ‘replace’. The request imperative is used exclusively (the ‘command’ and ‘urgent request” imperatives are not used at this time). Legend: The message contents appears inside quotes. BOLD COURIER denotes explicit keywords, REGULAR COURIER denotes a keyword from a set, () denotes grouping of options, | separates keyword and/or value options, <variable_name> identifies variable values, [] denotes optional keywords or values *n denotes ‘n’ number of sets

43

5.1 Monitor Status Request Request that, for a ‘start behavior’ action, a status message be sent to the indicated agent in a group, using optional start, end and interval times for scheduling purposes. Omitting the scheduling implies a one-time status poll request. If a periodic reporting schedule has been established, a ‘stop behavior’ request will immediately terminate this. Agent and group variables use integer identifier values. Omitting the group and agent implies the report be broadcast to all groups and agents (e.g. group 3, agent 63). For ‘start behavior’ requests, the specification of the agent and group is used to indicate where the status report should be sent. For ‘stop behavior’ requests, the receiving platform should stop any reporting to the indicated agent/group. All reporting should be stopped if ‘stop behavior’ is issued with broadcast group and agent specified, or a ‘stop all behavior’ is specified. At this time, a limited subset of extended parameters is available for reporting. If num_params is zero, then only core status is requested. Parameters are 0th derivative scalar quantities representing a snapshot of data at the time requested. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) num_params (0…15) parameter_string (CCL_PARAMETER_STR) group (0…3, 3 is broadcast across groups) agent (0…63, 63 is broadcast within a group) begin (local time string, “YYYY:MM:DD:hh:mm:ss” for start time, 0 implies begin upon message receipt) end (local time string, “YYYY:MM:DD:hh:mm:ss” for end time, 0 implies continue until explicitly stopped) interval (0…16383 minutes, 0 implies a one-time poll occurring at the ‘begin’ time)

String Type Options Description CCL_MSG_THREAD_STR "MSG_THREAD_NOT_USED"

"MSG_THREAD_USE_ID" The thread_id provides a unique conversation thread ID for matching a request to a response (acknowledgements and/or reports).

CCL_REQUEST_ACK_STR "REQUEST_NO_ACK", "REQUEST_ACK_RECEIVED", "REQUEST_ACK_COMPLETED", "REQUEST_ACK_RECEIVED_AND_COMPLETED"

Allows the requesting agent ability to specify if an acknowledgement for receiving and/or completing the request is required.

CCL_PARAMETER_STR "WATER_TEMPERATURE" "CONDUCTIVITY" "DISSOLVED_OXYGEN" "FLUORESCENCE" "TURBIDITY"

Limited subset of extended parameters available to be reported on. Units are specified in CCL specification: • Water Temp [mC] • Conductivity [uS/cm] • DO [ug/l] • Fluorescence [ug/l] • Turbidity [NTU]

Both serialization and de-serialization functionality are enabled for this message type. Serialization uses the following syntax, where thread ID specification, message acknowledgment, scheduling specifications and report recipient are optional. If this information is omitted, then ‘one time report’, ‘message thread ID not used’, ‘no acknowledgment requested’ and ‘broadcast report to requesting agent’ are assumed. A shorthand is also employed such that if the ‘STOP’ or ‘START’ keyword is not used, the ‘START 0 0 0’ sequence is assumed, resulting in a

44

one-time immediate poll request. Also, specifying only ‘REQUEST STATUS’ will request a one-time immediate poll of core status. (See examples below.) Note that when a request is de-serialized into string format, the omitted default thread information, acknowledgement option, extended parameter count, behavior action, scheduling parameters and report recipient are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] STATUS [STOP | (START <begin> <end> <interval> <num_params> (<parameter_string>)*num_params)] [<group> <agent>]" Examples: "REQUEST STATUS" Request that a single core status report be sent to the requesting agent. "REQUEST STATUS 0 62" Request that a single core status report be sent to group 0, agent 62. "REQUEST STATUS START 0 0 5 5 DISSOLVED_OXYGEN TURBIDITY WATER_TEMPERATURE CONDUCTIVITY FLUORESCENCE" Request that a status report be sent to the requesting agent, beginning upon message receipt and continuing at 5 minute periodic intervals, until explicitly stopped. Status should also contain the indicated extended data snapshot parameters: dissolved oxygen, turbidity, water temperature, conductivity and fluorescence. "REQUEST STATUS START 0 0 5 0 2 44" Request that a core status report be sent to agent 44 within group 2, beginning upon message receipt and continuing at 5 minute periodic intervals, until explicitly stopped. "REQUEST STATUS START 2007:07:21:16:40:00 0 10 0 2 44" Request that a core status report be sent to agent 44 within group 2, beginning on July 21, 2007, at 4:40:00 pm, and continuing at 10 minute periodic intervals, until explicitly stopped. "REQUEST REQUEST_ACK_RECEIVED STATUS START 2007:07:21:16:40:00 0 10 0 0 63" Request that a core status report be broadcast to all agents within group 0, beginning on July 21, 2007, at 4:40:00 pm, and continuing at 10 minute periodic intervals, until explicitly stopped. Send an acknowledgment message to the requestor that this request was received. "REQUEST STATUS START 0 2007:07:21:16:40:30 10 0" Request that a core status report be sent to the requesting agent, beginning immediately and continuing until July 21, 2007, at 4:40:30 pm, at 10 minute periodic intervals. "REQUEST MSG_THREAD_USE_ID 71 STATUS 0 44" Request that a core status report be sent to agent 44 within group 0, using a message context thread ID of 71. "REQUEST STATUS STOP" Request that all status reporting from the receiving agent to the requesting agent cease. "REQUEST STATUS STOP 2 54" Request that all status reporting cease from the receiving agent to agent 54 within group 2.

45

5.2 Monitor Status Inform Provide a core status message with some accompanying context. For a polled message, the agent and group id of the solicitor are included. The thread variable provides a unique conversation thread ID. Note that status results are only reported for “completed”, non-acknowledgement type messages. At this time, only a limited subset of extended parameter enumeration types is supported. Parameters are 0th derivative scalar quantities representing a snapshot of data at the time requested. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread (0…8191) group (0...2)

agent (0...62) ack_status_string (CCL_ACK_STATUS_STR) time (sec UTC)

platform_mode (CCL_PLATFORM_CONTROL_STR) health (CCL_PLATFORM_HEALTH_STR)

heading (0...359 deg) speed (0...1023 cm/s) avoiding_obstacle (CCL_BOOLEAN_STR) current_nav (CCL_NAVIGATION_STR) maneuver_type (CCL_MANEUVER_CONTROL_STR) maneuver_index (0...255) ops_mode (CCL_OPERATIONS_MODE_STR) path_segment (0...255) altitude (0...65535 cm) available_energy (0...65535 wHrs)

depth (0.0...11000.0 m) lat (-90.0...+90.0 deg) lng (-180.0...+180.0 deg) num_tasks (0…7) task1 (0…7) task2 (0…7) task3 (0…7) task4 (0…7) task5 (0…7) task6 (0…7) task7 (0…7) num_params (0…15) parameter_string (CCL_PARAMETER_STR)

String Type Options Description CCL_ACK_STATUS_STR "SUCCESS"

"OTHER_FAILURE" "BEYOND_CAPS" "INSUFFICIENT_INFORMATION" "NOT_UNDERSTOOD" "INSUFFICIENT_AUTHORITY" "RESOURCE_NOT_FOUND" "TIMED_OUT"

Indicator of acknowledgment of success or reason for failure.

CCL_PLATFORM_CONTROL_STR "IDLE", "REMOTELY_OPERATED", "RUNNING_MISSION"

Specifies the control state of the platform.

CCL_PLATFORM_HEALTH_STR "HEALTH_OK" "OTHER_FAILURE" "LOSS_OF_POSITION"

Specifies the current health of the system, or latest failure mode.

46

"LOSS_OF_DEPTH" "LOSS_OF_ALTITUDE" "LOSS_OF_COMPASS" "LOSS_OF_POWER" "LOSS_OF_THRUST" "LOW_ENERGY" "COLLISION" "LEAK_DETECTED" "PRESSURE_OOB"

CCL_BOOLEAN_STR "FALSE" "TRUE"

Affirm or disavow reference quantity.

CCL_NAVIGATION_STR "OTHER" "DEAD_RECKONING" "ACOUSTIC_LBL" "ACOUSTIC_SBL" "ACOUSTIC_USBL" "ACOUSTIC_MODEM_RANGING" "DOPPLER_SONAR" "INERTIAL" "GPS" "GPS_WAAS" "INTEGRATED" "MAGNETIC_DIPOLE" "GEOPHYSICAL"

Specifies the current navigational strategy.

CCL_MANEUVER_CONTROL_STR "NOT_MANEUVERING" "GOTO" "FOLLOW_PATH" "SPEED_AND_BEARING" "MOVE" "STATION_KEEP"

Specifies the current maneuvering basic behavior.

CCL_OPERATIONS_MODE_STR "OVERT", "COVERT"

Specifies the current operations mode of the platform.

CCL_PARAMETER_STR "WATER_TEMPERATURE" "CONDUCTIVITY" "DISSOLVED_OXYGEN" "FLUORESCENCE" "TURBIDITY"

Limited subset of extended parameters available to be reported on. Units are specified in CCL specification: • Water Temp [mC] • Conductivity [uS/cm] • DO [ug/l] • Fluorescence [ug/l] • Turbidity [NTU]

"(INFORM | WARN | URGENT_WARN) <thread> (UNSOLICITED | (POLLED <group> <agent>) | TIMED_EVENT | ACK) (RECEIVED | COMPLETED) <ack_status_string> STATUS [<time> <group> <agent> <platform_mode> <health> <heading> <speed> <avoiding_obstacle> <current_nav> <maneuver_type> <maneuver_index> <ops_mode> <path_segment> <altitude> <available_energy> <depth> <lat> <lng> <num_tasks> <task1> <task2> <task3> <task4> <task5> <task6> <task7> <num_params> (<parameter_string> <value>)*num_params]" Examples: "INFORM 0 ACK RECEIVED OTHER_FAILURE STATUS" Acknowledge that a status request failed.

47

"INFORM 0 POLLED 0 44 COMPLETED SUCCESS STATUS 1177724790 1 45 RUNNING_MISSION HEALTH_OK 88 70 FALSE GPS GOTO 5 OVERT 0 345 1900 0.150000 43.964798 77.901237 3 1 3 5 0 0 0 0 0" Report on platform core status polled from agent (group ID 0, host ID 44). "INFORM 0 POLLED 0 44 COMPLETED SUCCESS STATUS 1177724790 1 45 RUNNING_MISSION HEALTH_OK 88 70 FALSE GPS GOTO 5 OVERT 0 345 1900 0.150000 43.964798 77.901237 3 1 3 5 0 0 0 0 2 CONDUCTIVITY 3400 FLUORESCENCE 5654" Report on platform status polled from agent (group ID 0, host ID 44), which includes snapshot data for the conductivity and fluorescence mission sensors. Setting the ‘verbose’ flag true in the deserialCCLstr() produces a column-oriented display with appropriate units, such as shown in the following example output: INFORM 0 POLLED by Group ID: 0, Agent ID: 44 COMPLETED SUCCESS STATUS Time: Fri Apr 27 21:46:30 2007 Group ID: 1 Agent ID: 45 Platform Mode: RUNNING_MISSION Health: HEALTH_OK Heading: 88 deg Speed: 70 cm/s Avoiding Obstacle: FALSE Navigation: GPS Maneuver Type: GOTO Maneuver Index: 5 Ops Mode: OVERT Path Segment: 0 Altitude: 345 cm Available Energy: 1900 WHrs Depth: 0.150 m Latitude: +43.964798 deg Longitude: +77.901237 deg Number of Tasks: 3 TaskID Set: 1 3 5 0 0 0 0 Extended Parameter Count: 2 CONDUCTIVITY = 3400 uS/cm FLUORESCENCE = 5654 ug/l

48

5.3 Monitor System Capabilities Request Request a single polled system capabilities message be sent to the requesting agent, or agent <agent> in group <group>. Agent and group variables use integer identifier values. At this time, only single poll requests are supported. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) group (0…3, 3 is broadcast across groups) agent (0…63, 63 is broadcast within a group)





Serialization uses the following syntax, where thread ID specification, message acknowledgment and report recipient are optional. If this information is omitted, then ‘message thread ID not used’, ‘no acknowledgment requested’ and ‘broadcast report to requesting agent’ are assumed. Note that when de-serializing a request message, the thread information, acknowledgment options and recipient are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] SYSTEM_CAPS [<group> <agent>]" Examples: "REQUEST SYSTEM_CAPS 0 63" Request that a single systems capabilities report be sent to all agents in group 0. "REQUEST MSG_THREAD_USE_ID 88 SYSTEM_CAPS" Request that a single systems capabilities report be sent to the requesting agent, using a message thread ID of 88.

49

5.4 Monitor System Capabilities Inform Provide a system capabilities message with some accompanying context. For a polled message, the agent and group id of the solicitor are included. The thread variable provides a unique conversation thread ID. Note also that capability results are only reported for “completed”, non-acknowledgement type messages. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread (0…8191) group (0…2)

agent (0…62) ack_status_string (CCL_ACK_STATUS_STR)

lang_release (CCL_BOOLEAN_STR) lang_major_rev (0...15) lang_minor_rev (0...2047) name (ACHAR array, 1…15 characters, no whitespace) platform_class (CCL_PLATFORM_CLASS_STR) ops_range (0...16383 km) mission_role (CCL_MISSION_ROLE_STR) ops_mode (CCL_OPERATIONS_MODE_STR) length (0...1023 dm) body_type (CCL_BODY_STR) propulsion_type (CCL_PROPULSION_STR) displacement (0...65535 kg) diameter (0...1023 cm) max_depth (0...16383 m) min_altitude (0...16383 cm) longitudinal_control (CCL_BOOLEAN_STR) lateral_control (CCL_BOOLEAN_STR) vertical_control (CCL_BOOLEAN_STR) heading_control (CCL_BOOLEAN_STR) pitch_control (CCL_BOOLEAN_STR) roll_control (CCL_BOOLEAN_STR) max_roll (0...180 deg) min_turn_radius (0...1023 dm) max_yaw_rate (0...255 deg/s) min_pitch (0...90 deg) max_pitch (0...90 deg) underwater_navigation (CCL_NAVIGATION_STR) surface_navigation (CCL_NAVIGATION_STR) max_speed (0...1023 cm/s) min_speed (0...1023 cm/s) cruise_speed (0...1023 cm/s) obstacle_avoid_ss (CCL_BOOLEAN_STR) available_energy (0...65535 wHrs) reserve_energy (0...65535 wHrs) capacity_energy (0...65535 wHrs) endurance_units (CCL_TIME_INTERVAL_STR) endurance_low_load (0...1023 wHrs) endurance_high_load (0...1023 wHrs) energy_strategy (CCL_ENERGY_MANAGEMENT_STR) solar_energy (CCL_BOOLEAN_STR) fuel_cell_energy (CCL_BOOLEAN_STR) diesel_energy (CCL_BOOLEAN_STR)

50

nuclear_energy (CCL_BOOLEAN_STR) other_energy (CCL_BOOLEAN_STR) data_collect_role (CCL_DATA_COLLECTION_STR) disk_capacity (0...1048575 MB) disk_pct_available (0...100 %) network_protocol (CCL_NETWORK_PROTOCOL_STR) satellite_comms (0...3) acoustic_comms (0...3) rf_comms (0...3) cellular_comms (0...3) other_comms (0...3) cpu_capability (0...255) ctd_sensors (0...3) pressure_sensors (0...3) altimeter_sensors (0...3) temperature_sensors (0...3) salinity_sensors (0...3) conductivity_sensors (0...3) dissolved_oxygen_sensors (0...3) fluorometer_sensors (0...3) turbidity_sensors (0...3) transmissometer_sensors (0...3) optical_backscatter_sensors (0...3) dvl_sensors (0...3) magnetic_flux_sensors (0...3) subbottom_profiler_sensors (0...3) sidescan_sonar_sensors (0...3) multibeam_sonar_sensors (0...3) still_cameras (0...3) video_cameras (0...3) audio_recorders (0...3) other_sensors (0...3)




CCL_BOOLEAN_STR "FALSE" "TRUE"

Affirm or disavow reference quantity.

CCL_PLATFORM_CLASS_STR "PORTABLE" "LIGHT_WEIGHT" "HEAVY_WEIGHT" "LARGE_DISPLACEMENT"

Specify relative size of platform.

CCL_MISSION_ROLE_STR "OTHER" "ISR" "MCM" "ASW" "INSPECT_AND_IDENTIFY" "OCEANOGRAPHY" "CN3" "PAYLOAD_DELIVERY"

Specify the primary mission role for the platform. Based on UUV Master Plan "Sub-Pillars".

51

"INFORMATION_OPERATIONS" "TIME_CRITICAL_STRIKE"

CCL_OPERATIONS_MODE_STR "OVERT" "COVERT"

Specify operational mode capability.

CCL_BODY_STR "OTHER" "TETHERED_BUOY" "DRIFTING_BUOY" "OPEN_SPACE_FRAME" "TORPEDO" "GLIDER" "CRAWLER"

Specify body shape of the platform.

CCL_PROPULSION_STR "NONE" "OTHER" "THRUSTER" "GLIDER"

Specify primary propulsion means of the platform.

CCL_NAVIGATION_STR "OTHER" "DEAD_RECKONING" "ACOUSTIC_LBL" "ACOUSTIC_SBL" "ACOUSTIC_USBL" "ACOUSTIC_MODEM_RANGING" "DOPPLER_SONAR" "INERTIAL" "GPS" "GPS_WAAS" "INTEGRATED" "MAGNETIC_DIPOLE" "GEOPHYSICAL"

Specify the underwater and surface navigation capabilities of the platform.

CCL_TIME_INTERVAL_STR "SECONDS" "MINUTES" "HOURS" "DAYS"

Specify reference units of time.

CCL_ENERGY_MANAGEMENT_STR "OTHER" "MINIMUM_RESERVE" "SURFACE_OPS" "DAY_TRIP" "LONG_ENDURANCE"

Specify energy management strategy in use.

CCL_DATA_COLLECTION_STR "OTHER" "COMMUNICATIONS_INTEL" "ELECTRONIC_INTEL" "IMAGERY_INTEL" "SIGNAL_INTEL" "MEASUREMENT_AND_SIGNATURE_INTEL" "BATHYMETRY_MAPPING" "ACOUSTIC_IMAGERY" "OPTICAL_IMAGERY" "SUBBOTTOM_PROFILING" "WATER_COLUMN_CHARACTERIZATION" "TEMPERATURE_PROFILING" "SALINITY_PROFILING" "WATER_CLARITY" "BIOLUMINESCENCE" "CBN_DETECT_AND_TRACK"

Specify data collection role of mission. Based on UUV Master Plan.

CCL_NETWORK_PROTOCOL_STR "NONE" "OTHER" "SEAWEB"

Specify underwater network protocol in effect.

52

"COFSNET" "AUSNET"

"(INFORM | WARN | URGENT_WARN) <thread> (UNSOLICITED | (POLLED <group> <agent>) | TIMED_EVENT | ACK) (RECEIVED | COMPLETED) <ack_status_string> SYSTEM_CAPS [<lang_release> <lang_major_rev> <lang_minor_rev> <name> <group> <agent> <platform_class> <ops_range> <mission_role> <ops_mode> <length> <body_type> <propulsion_type> <displacement> <diameter> <max_depth> <min_altitude> <longitudinal_control> <lateral_control> <vertical_control> <heading_control> <pitch_control> <roll_control> <max_roll> <min_turn_radius> <max_yaw_rate> <min_pitch> <max_pitch> <underwater_navigation> <surface_navigation> <max_speed> <min_speed> <cruise_speed> <obstacle_avoid_ss> <available_energy> <reserve_energy> <capacity_energy> <endurance_units> <endurance_low_load> <endurance_high_load> <energy_strategy> <solar_energy> <fuel_cell_energy> <diesel_energy> <nuclear_energy> <other_energy> <data_collect_role> <disk_capacity> <disk_pct_available> <network_protocol> <satellite_comms> <acoustic_comms> <rf_comms> <cellular_comms> <other_comms> <cpu_capability> <ctd_sensors> <pressure_sensors> <altimeter_sensors> <temperature_sensors> <salinity_sensors> <conductivity_sensors> <dissolved_oxygen_sensors> <fluorometer_sensors> <turbidity_sensors> <transmissometer_sensors> <optical_backscatter_sensors> <dvl_sensors> <magnetic_flux_sensors> <subbottom_profiler_sensors> <sidescan_sonar_sensors> <multibeam_sonar_sensors> <still_cameras> <video_cameras> <audio_recorders> <other_sensors>]" Examples: "INFORM 1 POLLED 1 55 COMPLETED SUCCESS SYSTEM_CAPS TRUE 2 11 SAUV05 0 5 LIGHT_WEIGHT 150 OCEANOGRAPHY OVERT 52 TORPEDO THRUSTER 200 20 500 300 TRUE FALSE FALSE TRUE TRUE FALSE 0 50 0 5 6 DEAD_RECKONING GPS_WAAS 100 0 70 FALSE 1550 500 2000 DAYS 30 5 LONG_ENDURANCE TRUE FALSE FALSE FALSE FALSE WATER_COLUMN_CHARACTERIZATION 200 55 COFSNET 1 1 1 0 0 33 1 0 1 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0" Report on platform capabilities polled from agent (group ID 1, host ID 55) using message thread ID 1. Setting the ‘verbose’ flag true in the deserialCCLstr() produces a column-oriented display with appropriate units, such as shown in the following example output: INFORM 1 POLLED by Group ID: 1, Agent ID: 55 COMPLETED SUCCESS SYSTEM_CAPS CCL Release Version: TRUE CCL Major Version: 2 CCL Minor Version: 11 Name: SAUV05 Group ID: 0 Agent ID: 5 Platform Class: LIGHT_WEIGHT Ops Range: 150 km Mission Role: OCEANOGRAPHY Ops Mode: OVERT Platform Length: 52 dm Body Type: TORPEDO Propulsion Type: THRUSTER Platform Displacement: 200 kg Platform Diameter: 20 cm Maximum Depth: 500 m Minimum Altitude: 300 cm Longitudinal Control: TRUE Lateral Control: FALSE Vertical Control: FALSE

53

Heading Control: TRUE Pitch Control: TRUE Roll Control: FALSE Maximum Roll Angle: +/-0 deg Minimum Turn Radius: 50 dm Maximum Yaw Rate: 0 deg/s Minimum Pitch Angle: -5 deg/s Maximum Pitch Angle: +6 deg/s Underwater Navigation Strategy: DEAD_RECKONING Surface Navigation Strategy: GPS_WAAS Maximum Speed: 100 cm/s Minimum Speed: 0 cm/s Cruise Speed: 70 cm/s Obstacle Avoidance Capability: FALSE Energy Available: 1550 WHrs Energy Reserve: 500 WHrs Energy Capacity: 2000 WHrs Platform Endurance Units: DAYS Endurance (Low Load): 30 Endurance (High Load): 5 Energy Strategy: LONG_ENDURANCE Solar Energy Capability: TRUE Fuel Cell Capability: FALSE Diesel Energy Capability: FALSE Nuclear Energy Capability: FALSE Other Energy Capability: FALSE Data Collection Role: WATER_COLUMN_CHARACTERIZATION Data Storage Capacity: 200 MB Data Storage Available: 55 % Comms Network Protocol: COFSNET Satellite Interfaces: 1 Acoustic Interfaces: 1 RF Interfaces: 1 Cellular Interfaces: 0 Other Comms Interfaces: 0 CPU Benchmark Index: 33 CTD Sensors: 1 Pressure Sensors: 0 Altimeter Sensors: 1 Temperature Sensors: 0 Salinity Sensors: 0 Conductivity Sensors: 0 DO Sensors: 1 Fluorometer Sensors: 1 Turbidity Sensors: 1 Transmissometer Sensors: 0 Optical Backscatter Sensors: 0 DVL Sensors: 0 Magnetic Flux Sensors: 0 Subbottom Profilers: 0 Sidescan Sonars: 0 Multibeam Sonars: 0 Still Cameras: 0 Video Cameras: 0 Audio Recorders: 0 Other Mission Sensors: 0

54

5.5 Monitor File Request Request a file be sent to the requesting agent, or agent <agent> in group <group>. Agent and group variables use integer identifier values. Filename and directory are ASCII strings containing no whitespaces. If the directory string matches "0", then the default directory is implied, and no directory string will be serialized. At this time, only single poll requests are supported. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) filename (ACHAR array, 1…15 characters) directory (ACHAR array, 1…31 characters, “0” indicates default directory) group (0…3, 3 is broadcast across groups) agent (0…63, 63 is broadcast within a group)





Serialization uses the following syntax, where thread ID specification, message acknowledgment and report recipient are optional. If this information is omitted, then ‘message thread ID not used’, ‘no acknowledgment requested’ and ‘broadcast report to requesting agent’ are assumed. Note that when de-serializing a request message, the thread information, acknowledgment options and recipient are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] FILE <filename> <directory> [<group> <agent>]" Examples: "REQUEST FILE CoopSurvey /mission 0 44" Request that the file ‘CoopSurvey’ located in the ‘/mission’ directory be sent to agent 44 in group 0.

55

5.6 Monitor File Inform Provide a file with some accompanying context. For a polled message, the agent and group id of the solicitor are included. The thread variable provides a unique conversation thread ID. The file bytes are appended to the end of the message only for “completed”, non-acknowledgement type messages. At this time, only the de-serialization functionality is enabled for this message type (e.g. deserialCCLstr()). Attempting to call the serialization function will result in an ‘unsupported message behavior subtype’ error. In the case of de-serialization, the file contents will only be displayed for ‘ASCII’ encoding. For ‘binary’ encoding, a placeholder indicator will be displayed. Variable Legend and Value Ranges:



file_access_status (CCL_FILE_ACCESS_STR) file_size (0...511) filename (ACHAR array, 1-15 B) content_type (CCL_FILE_CONTENT_STR) encoding (CCL_FILE_ENCODING_STR) file (ABYTE array, 0-511 B)




CCL_FILE_ACCESS_STR "ACCESS_ALLOWED" "INADEQUATE_PERMISSIONS" "FILE_TOO_BIG" "FILE_NOT_FOUND"

Indicator of success in accessing a file.

CCL_FILE_CONTENT_STR "OTHER_CONTENT" "LOG_DATA" "DATA_SNIP" "CCL_SET" "AGGREGATE_BEHAVIOR" "PATH"

Specify the contents of the attached file.

CCL_FILE_ENCODING_STR "ASCII" "BINARY"

Specifies how the file is encoded.

"(INFORM | WARN | URGENT_WARN) <thread> (UNSOLICITED | (POLLED <group> <agent>) | TIMED_EVENT | ACK) (RECEIVED | COMPLETED) <ack_status_string> FILE [<file_access_status> <file_size> <filename> <content_type> <encoding> <file>]"

Examples: "INFORM 2 POLLED 0 51 COMPLETED SUCCESS FILE ACCESS_ALLOWED CCL_SET ASCII CoopSurvey 50 This is code to implement a cooperative survey..."

56

Report on file contents which implement behavior of cooperative survey polled from agent (group ID 0, host ID 51) using message thread ID 2. Setting the ‘verbose’ flag true in the deserialCCLstr() produces a column-oriented display with appropriate units, such as shown in the following example output: INFORM 2 POLLED by Group ID: 0, Agent ID: 51 COMPLETED SUCCESS FILE Access Status: ACCESS_ALLOWED Content Type: CCL_SET Encoding Type: ASCII Filename: CoopSurvey Size of File: 50 B ASCII Contents: This is code to implement a cooperative survey...

57

5.7 Monitor Sensor Capabilities Request Request a report on an indicated sensor capability be sent to the requesting agent, or agent <agent> in group <group>. Agent and group variables use integer identifier values. The requested sensor is identified by its type and instance ID. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) type (CCL_MISSION_SENSOR_STR) instance (0…3, 0 is all instances within the requested sensor type) group (0…3, 3 is broadcast across groups) agent (0…63, 63 is broadcast within a group)





CCL_MISSION_SENSOR_STR "ALL" "OTHER" "CTD" "PRESSURE" "ALTIMETER" "TEMPERATURE" "SALINITY" "CONDUCTIVITY" "DISSOLVED_OXYGEN" "FLUOROMETER" "TURBIDITY" "TRANSMISSOMETER" "OPTICAL_BACKSCATTER" "DVL" "MAGNETIC_FLUX" "SUBBOTTOM_PROFILER" "SIDESCAN_SONAR" "MULTIBEAM_SONAR" "STILL_CAMERA" "VIDEO_CAMERA" "AUDIO_RECORDER"

Specify the type of mission sensor.

At this time, only single poll requests are supported. Both serialization and de-serialization functionality are enabled for this message type. Serialization uses the following syntax, where thread ID specification, message acknowledgment and report recipient are optional. If this information is omitted, then ‘message thread ID not used’, ‘no acknowledgment requested’ and ‘broadcast report to requesting agent’ are assumed. Note that when de-serializing a request message, the thread information, acknowledgment options and recipient are made explicit.

58

"REQUEST [<thread_string> [<thread_id>]] [<ack_string>] SENSOR_CAPS <type> <instance> [<group> <agent>]" Examples: "REQUEST MSG_THREAD_USE_ID 3 SENSOR_CAPS ALL 0 1 32" Request that the recipient report on all mission sensor capabilities onboard the platform. Send the report to agent 32 in group 1 using message context ID 3. "REQUEST SENSOR_CAPS TURBIDITY 1 0 62" Request that the recipient report on the capabilities of the first turbidity mission sensor onboard the platform. Send the report to agent 62 in group 0. Don’t worry about the message context ID.

59

5.8 Monitor Sensor Capabilities Inform Provide a report on an indicated sensor or set of sensors. For a polled message, the agent and group id of the solicitor are included. The thread variable provides a unique conversation thread ID. The sensor capabilities information is included only for “completed”, non-acknowledgement type messages. The description field should contain no whitespace, as the parser uses whitespace to delineate between tokens. Both serialization and de-serialization functionality are enabled for this message type. At this time though, only a subset of the fields defined in a sensor capabilities data structure are handled using these ASCII string serialization and de-serialization functions. Variable Legend and Value Ranges:



num_sensors (0...7) description (ACHAR array, 1-15 B)

type (CCL_MISSION_SENSOR_STR) instance (1…3) class (CCL_SENSOR_CLASS_STR) state (CCL_DEVICE_STATE_STR) active (CCL_SENSOR_ACTIVE_STR) directionality (CCL_SENSOR_DIRECTION_STR)




CCL_MISSION_SENSOR_STR "ALL" "OTHER" "CTD" "PRESSURE" "ALTIMETER" "TEMPERATURE" "SALINITY" "CONDUCTIVITY" "DISSOLVED_OXYGEN" "FLUOROMETER" "TURBIDITY" "TRANSMISSOMETER" "OPTICAL_BACKSCATTER" "DVL" "MAGNETIC_FLUX" "SUBBOTTOM_PROFILER" "SIDESCAN_SONAR" "MULTIBEAM_SONAR" "STILL_CAMERA" "VIDEO_CAMERA" "AUDIO_RECORDER"

Specify the type of mission sensor.

60

CCL_SENSOR_CLASS_STR "OTHER" "ACOUSTIC" "PHYSICAL" "OPTICAL"

Specify the class of the sensor.

CCL_DEVICE_STATE_STR "ON" "OFF" "SLEEP" "STANDBY" "FAILURE"

Specifies the current state of the sensor device or interface.

CCL_SENSOR_ACTIVE_STR "TRIGGERED" "FREE_RUNNING" "PASSIVE"

Specify how the sensor is activated.

CCL_SENSOR_DIRECTION_STR "BEAM" "OMNI"

Specify directionality of sensor.

"(INFORM | WARN | URGENT_WARN) <thread> (UNSOLICITED | (POLLED <group> <agent>) | TIMED_EVENT | ACK) (RECEIVED | COMPLETED) <ack_status_string> SENSOR_CAPS [<num_sensors> (<description> <type> <instance> <class> <state> <active> <directionality>)*num_sensors]" Examples: "INFORM 3 POLLED 2 5 COMPLETED SUCCESS SENSOR_CAPS 2 OxyGuard505 DISSOLVED_OXYGEN 1 PHYSICAL ON PASSIVE OMNI WetLABS-FLNTU FLUOROMETER 1 OPTICAL ON PASSIVE OMNI" Report on mission sensor capabilities polled from agent (group ID 2, host ID 5) using message context thread ID 3. Setting the ‘verbose’ flag true in the deserialCCLstr() produces a column-oriented display with appropriate units, such as shown in the following example output: INFORM 3 POLLED by Group ID: 2, Agent ID: 5 COMPLETED SUCCESS SENSOR_CAPS No. of Sensors: 2 Sensor 1: Description: OxyGuard505 Type: DISSOLVED_OXYGEN Instance ID: 1 Class: PHYSICAL State: ON Active State: PASSIVE Directionality: OMNI Sensor 2: Description: WetLABS-FLNTU Type: FLUOROMETER Instance ID: 1 Class: OPTICAL State: ON Active State: PASSIVE Directionality: OMNI

61

5.9 Monitor Communications Interface Capabilities Request Request a report on an indicated communications interface capability be sent to the requesting agent, or agent <agent> in group <group>. Agent and group variables use integer identifier values. The requested interface is identified by its type and instance ID. At this time, only single poll requests are supported. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) type (CCL_COMM_INTERFACE_STR) instance (0…3, 0 is all instances within the requested interface type) group (0…3, 3 is broadcast across groups) agent (0…63, 63 is broadcast within a group)





CCL_COMM_INTERFACE_STR "ALL" "OTHER" "SATELLITE" "ACOUSTIC" "RF" "CELLULAR"

Specifies the communications interface.

Serialization uses the following syntax, where thread ID specification, message acknowledgment and report recipient are optional. If this information is omitted, then ‘message thread ID not used’, ‘no acknowledgment requested’ and ‘broadcast report to requesting agent’ are assumed. Note that when de-serializing a request message, the thread information, acknowledgment options and recipient are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] COMMS_CAPS <type> <instance> [<group> <agent>]" Examples: "REQUEST MSG_THREAD_USE_ID 56 COMMS_CAPS ACOUSTIC 1 2 5" Request that the recipient report on the capabilities of the first acoustic modem interface onboard the platform. Send the report to agent 5 in group 2 using message context ID 56.

62

5.10 Monitor Communications Interface Capabilities Inform Provide a report on an indicated communications interface or set of interfaces. For a polled message, the agent and group id of the solicitor are included. The thread variable provides a unique conversation thread ID. The interface capabilities information is included only for “completed”, non-acknowledgement type messages. The description field should contain no whitespace, as the parser uses whitespace to delineate between tokens. Both serialization and de-serialization functionality are enabled for this message type. At this time though, only a subset of the fields defined in a communications interface capabilities data structure are handled using these ASCII string serialization and de-serialization functions. Variable Legend and Value Ranges:



num_interfaces (0...7) description (ACHAR array, 1-15 B)

type (CCL_COMM_INTERFACE_STR) instance (1…3) state (CCL_DEVICE_STATE_STR)




CCL_COMM_INTERFACE_STR "ALL" "OTHER" "SATELLITE" "ACOUSTIC" "RF" "CELLULAR"

Specifies the communications interface.

CCL_DEVICE_STATE_STR "ON" "OFF" "SLEEP" "STANDBY" "FAILURE"

Specifies the current state of the communications device or interface.

"(INFORM | WARN | URGENT_WARN) <thread> (UNSOLICITED | (POLLED <group> <agent>) | TIMED_EVENT | ACK) (RECEIVED | COMPLETED) <ack_status_string> COMMS_CAPS [<num_interfaces> (<description> <type> <instance> <state>)*num_interfaces]" Examples: "INFORM 56 POLLED 1 34 COMPLETED SUCCESS COMMS_CAPS 1 BenthosATM-885 ACOUSTIC 1 STANDBY"

63

Report on mission sensor capabilities polled from agent (group ID 1, host ID 34) using message context thread ID 56. Setting the ‘verbose’ flag true in the deserialCCLstr() produces a column-oriented display with appropriate units, such as shown in the following example output: INFORM 56 POLLED by Group ID: 1, Agent ID: 34 COMPLETED SUCCESS COMMS_CAPS No. of Interfaces: 1 Interface 1: Description: BenthosATM-885 Type: ACOUSTIC Instance ID: 1 State: STANDBY

64

5.11 Execute Convention System Admin Request The platform is requested to alter the specified system administrative aspects. This includes shutting down and restarting the high-level control applications, and shutting down and restarting the platform. The action takes place immediately, except for the ‘restart platform’ type where the restart time may be specified. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) action (CCL_SYS_ADM_CONTROL_STR) restart (local time string, “YYYY:MM:DD:hh:mm:ss” for restart time, 0 implies begin upon message receipt)





CCL_SYS_ADM_CONTROL_STR "SHUTDOWN_APPS" "SHUTDOWN_PLATFORM" "RESTART_APPS" "RESTART_OS" "RESTART_PLATFORM"

Specifies the system administration command to issue to the platform.

Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] SYSTEM_ADMIN <action> [<restart>]" Examples: "REQUEST MSG_THREAD_USE_ID 5 REQUEST_ACK_RECEIVED SYSTEM_ADMIN RESTART_APPS" Request that the recipient restart the high-level application(s) which control the platform. Send an acknowledgment message upon receipt of this request. "REQUEST MSG_THREAD_USE_ID 27 REQUEST_ACK_RECEIVED SYSTEM_ADMIN RESTART_PLATFORM 2007:06:13:06:00:00" Request that the recipient platform shut down, and then restart at 06:00:00 on 13 June 2007 local time. Send an acknowledgment message upon receipt of this request.

65

5.12 Execute Convention System Admin Inform Provide an acknowledgement that the system admin request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread (0…8191) ack_status_string (CCL_ACK_STATUS_STR)




"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> SYSTEM_ADMIN" Examples: "INFORM 5 ACK RECEIVED SUCCESS SYSTEM_ADMIN" Acknowledge that the platform successfully received a system administration request using message context ID 5. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

66

5.13 Execute Convention Start Mission Request The platform is requested to immediately begin executing the indicated mission. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) mission_name (ACHAR array, 1…15 characters)


"MSG_THREAD_USE_ID" The thread_id provides a unique conversation thread ID for matching a request to a response acknowledgement.



Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] START_MISSION <mission_name>" Examples: "REQUEST REQUEST_ACK_RECEIVED START_MISSION CoBox-3" Request that the recipient platform begin the mission ‘CoBox-3’. Send an acknowledgment message upon receipt of this request.

67

5.14 Execute Convention Start Mission Inform Provide an acknowledgement that the start mission request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> START_MISSION" Examples: "WARN 6 ACK RECEIVED RESOURCE_NOT_FOUND START_MISSION" Acknowledge that the platform received a start mission request using message context ID 6, but that it was not able to find the required mission resource and therefore did not begin the mission. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

68

5.15 Execute Convention Stop Mission Request The platform is requested to immediately stop executing the current mission. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR)





Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] STOP_MISSION" Examples: "REQUEST STOP_MISSION" Request that the recipient platform stop the current mission.

69

5.16 Execute Convention Stop Mission Inform Provide an acknowledgement that the stop mission request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> STOP_MISSION" Examples: "INFORM 7 ACK RECEIVED SUCCESS STOP_MISSION" Acknowledge that the platform successfully received a stop mission request using message context ID 7. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

70

5.17 Execute Convention Abort Mission Request The platform is requested to stop executing the current mission and begin executing either the pre-configured or indicated abort mission. If a mission name is specified, use this as the abort mission to execute. If no name is specified, use the pre-configured abort mission. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) mission_name (ACHAR array, 1…15 characters)





Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] ABORT_MISSION [<mission_name>]" Examples: "REQUEST ABORT_MISSION Abort-02.ccl" Request that the recipient platform abort the current mission and then run the canned mission ‘Abort-02.ccl’. "REQUEST REQUEST_ACK_RECEIVED_AND_COMPLETED ABORT_MISSION" Request that the recipient platform abort the current mission and then run the pre-configured mission. Send an acknowledgment both upon receipt of this request and when the abort mission is complete.

71

5.18 Execute Convention Abort Mission Inform Provide an acknowledgement that the abort mission request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> ABORT_MISSION"

Examples: "INFORM 8 ACK COMPLETED SUCCESS ABORT_MISSION" Acknowledge that the platform successfully received an abort mission request using message context ID 8. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

72

5.19 Execute Convention Start Behavior Request The platform is requested to immediately begin executing the indicated behavior. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) behavior_name (ACHAR array, 1…15 characters)





Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] START_BEHAVIOR <behavior_name>" Examples: "REQUEST START_BEHAVIOR CoBox-01.beh" Request that the recipient platform begin the behavior ‘CoBox-01.beh’.

73

5.20 Execute Convention Start Behavior Inform Provide an acknowledgement that the start behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> START_BEHAVIOR" Examples: "WARN 9 ACK RECEIVED BEYOND_CAPS START_BEHAVIOR" Acknowledge that the platform received a start behavior request using message context ID 9, but was not able to carry it out because it was beyond the capabilities of the platform. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

74

5.21 Execute Convention Stop Behavior Request The platform is requested to immediately stop executing the indicated behavior. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) behavior_name (ACHAR array, 1…15 characters)





Serialization uses the following syntax, where thread ID specification and message acknowledgment are optional. If this information is omitted, then ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed. Note that when de-serializing a request message, the thread information and acknowledgment options are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] STOP_BEHAVIOR <behavior_name>" Examples: "REQUEST REQUEST_ACK_RECEIVED STOP_BEHAVIOR Survey.beh" Request that the recipient platform stop the behavior ‘Survey.beh’. Send an acknowledgment message when this request is received.

75

5.22 Execute Convention Stop Behavior Inform Provide an acknowledgement that the stop behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> STOP_BEHAVIOR" Examples: "INFORM 10 ACK RECEIVED SUCCESS STOP_BEHAVIOR" Acknowledge that the platform received a stop behavior request using message context ID 10. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

76

5.23 Execute Convention Update Behavior Request The platform is requested to immediately modify the indicated behavior. This ASCII string function supports the direct specification of behavior modification through the attached update code. The file and directory means of specifying update code is currently not supported. Note that the update code is limited to 511 B in length and can be in ASCII or binary format. In the case of de-serialization, the update code will only be displayed for encoding set to ‘ASCII’. For ‘binary’ encoding, a placeholder indicator will be displayed. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) behavior_name (ACHAR array, 1…15 characters) code_size (0...511) encoding (CCL_FILE_ENCODING_STR) code (ABYTE array, 0-511 B)





CCL_FILE_ENCODING_STR "ASCII" "BINARY"

Specifies how the file is encoded.

At this time, only the de-serialization functionality is enabled for this message type (e.g. deserialCCLstr()). Serialization must be made using the low-level function calls outlined in Sec 4.4. Attempting to call the serialization function will result in an ‘unsupported message behavior subtype’ error. The de-serialization syntax makes the thread and acknowledgment options explicit. "REQUEST <thread_string> [<thread_id>] <ack_string> UPDATE_BEHAVIOR <behavior_name> <code_size> <encoding> <code>" Examples: "REQUEST MSG_THREAD_USE_ID 11 REQUEST_NO_ACK UPDATE_BEHAVIOR CoBox-177.beh 23 ASCII This is my update code." Request that the recipient platform update the behavior ‘CoBox-177.beh’ using message context ID 11. Do not send an acknowledgment message.

77

5.24 Execute Convention Update Behavior Inform Provide an acknowledgement that the update behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> UPDATE_BEHAVIOR" Examples: "INFORM 11 ACK COMPLETED SUCCESS UPDATE_BEHAVIOR" Acknowledge that the platform successfully received an update behavior request using message context ID 11. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

78

5.25 Maneuver GoTo Waypoint Request The platform is requested to maneuver to the specified latitude, longitude and depth, at the given speed along the shortest path. Transition to the next maneuver behavior occurs when the platform believes it has attained the target destination (within the pre-configured waypoint radius and waypoint depth tolerance settings), when the pre-configured timeout occurs, or if explicitly stopped by some other command. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) lat (-90.0...+90.0 deg) lng (-180.0...+180.0 deg) depth (0.0...11000.0 m) speed (0...65535 cm/s)





Both serialization and de-serialization functionality are enabled for this message type. Serialization uses the following syntax, where the queue/replace, thread ID and message acknowledgment specifications are optional. If omitted, then ‘replace’, ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed, respectively. Note that when de-serializing a request message, the thread information, acknowledgment options and behavior stacking are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] [QUEUE | REPLACE] GOTO <lat> <lng> <depth> <speed>" Examples: "REQUEST REPLACE GOTO 43.246124 -77.135246 11.000000 65" Request that the recipient platform immediately transit to latitude N 43.246124, longitude W 77.135246, depth 11 m at a speed of 65 cm/s.

79

5.26 Maneuver GoTo Waypoint Inform Provide an acknowledgement that the maneuver behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> GOTO" Examples: "INFORM 13 ACK COMPLETED SUCCESS GOTO" Acknowledge that the platform successfully completed a GoTo request using message context ID 13. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

80

5.27 Maneuver Speed and Bearing Request The platform is requested to move at the specified speed and compass bearing for a given duration at the specified depth. Transition to the next maneuver behavior occurs when the duration is complete, or if explicitly stopped. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) bearing (0…3600 tenths of deg) speed (0…65535 cm/s ) depth (0.0...11000.0 m) duration (0…16383 minutes)





Both serialization and de-serialization functionality are enabled for this message type. Serialization uses the following syntax, where the queue/replace, thread ID and message acknowledgment specifications are optional. If omitted, then ‘replace’, ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed, respectively. Note that when de-serializing a request message, the thread information, acknowledgment options and behavior stacking are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] [QUEUE | REPLACE] SPEED_AND_BEARING <bearing> <speed> <depth> <duration>" Examples: "REQUEST REQUEST_ACK_RECEIVED_AND_COMPLETED QUEUE SPEED_AND_BEARING 300 70 10.750000 15" Request that the recipient platform immediately transit along a true bearing of 300 deg at a speed of 70 cm/s to a depth of 10.75 m for a duration of 15 minutes. Send an acknowledgment when the message request is received and upon completion of the maneuver.

81

5.28 Maneuver Speed and Bearing Inform Provide an acknowledgement that the maneuver behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:





"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> SPEED_AND_BEARING" Examples: "INFORM 15 ACK RECEIVED SUCCESS SPEED_AND_BEARING" Acknowledge that the platform successfully received a Speed and Bearing request using message context ID 15. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

82

5.29 Maneuver Station Keep Request The platform is requested to remain within a circle of specified radius and center coordinates. The circle is located on the water surface. If the platform drifts beyond, or begins outside of the circle radius, it will attempt to move back to the circle center at the pre-configured station keep speed. Transition to the next maneuver behavior occurs when the timeout time occurs or the time duration expires, or if explicitly stopped. Behavior stacking is set by the user. The circle center is fixed at the water surface. No restrictions are placed on platform orientation during this maneuver. Variable Legend and Value Ranges:

thread_string (CCL_MSG_THREAD_STR) thread_id (0…8191) ack_string (CCL_REQUEST_ACK_STR) lat (-90.0...+90.0 deg) lng (-180.0...+180.0 deg) radius (0…8191 m) timeout (local time string, “YYYY:MM:DD:hh:mm:ss” for timeout) duration (0…16383 minutes)





Both serialization and de-serialization functionality are enabled for this message type. Serialization uses the following syntax, where the queue/replace, thread ID and message acknowledgment specifications are optional. If omitted, then ‘replace’, ‘message thread ID not used’ and ‘no acknowledgment requested’ are assumed, respectively. Note that when de-serializing a request message, the thread information, acknowledgment options and behavior stacking are made explicit. "REQUEST [<thread_string> [<thread_id>]] [<ack_string>] [QUEUE | REPLACE] STATION_KEEP <lat> <lng> <radius> (ABSOLUTE_TIME <timeout> | RELATIVE_TIME <duration>)" Examples: "REQUEST QUEUE STATION_KEEP 44.333124 -78.000246 50 ABSOLUTE_TIME 2007:07:21:16:40:00" Request that the recipient platform schedule a Station Keep maneuver upon completion of all other executing and queued maneuvers. The maneuver will be centered at latitude N 44. 333124, longitude W 78.000246, and have a radius of 50 m. The maneuver will complete by 21 July 2007, 16:40:00 local time.

83

5.30 Maneuver Station Keep Inform Provide an acknowledgement that the maneuver behavior request message was received and executed, or failed to execute properly. Note that the thread variable provides a unique conversation thread ID for matching an acknowledgment to a request. Both serialization and de-serialization functionality are enabled for this message type. Variable Legend and Value Ranges:



"OTHER_FAILURE" "BEYOND_CAPS" "INSUFFICIENT_INFORMATION""NOT_UNDERSTOOD" "INSUFFICIENT_AUTHORITY" "RESOURCE_NOT_FOUND" "TIMED_OUT"


"(INFORM | WARN | URGENT_WARN) <thread> ACK (RECEIVED | COMPLETED) <ack_status_string> STATION_KEEP" Examples: "INFORM 17 ACK COMPLETED SUCCESS STATION_KEEP" Acknowledge that the platform successfully completed a Station Keep request using message context ID 17. Setting the ‘verbose’ flag true in the deserialCCLstr() currently has no effect for this message type.

84

GNU Free Documentation License GNU Free Documentation License Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

85

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front over must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

86

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: a. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of

previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

b. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications

in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

c. State on the Title page the name of the publisher of the Modified Version, as the publisher. d. Preserve all the copyright notices of the Document. e. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. f. Include, immediately after the copyright notices, a license notice giving the public permission to use the

Modified Version under the terms of this License, in the form shown in the Addendum below. g. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the

Document's license notice. h. Include an unaltered copy of this License. i. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year,

new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

j. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the

Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

k. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve

in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

87

l. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

m. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. n. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant

Section. o. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements". 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

88

7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Common Control Language (CCL) – A Proposed Standard Language · PDF fileAUV Common...

Documents

Transcript of Common Control Language (CCL) – A Proposed Standard Language · PDF fileAUV Common...