diff --git a/CMakeLists.txt b/CMakeLists.txt index 33153c0..5cc40cf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -32,6 +32,12 @@ set(dependencies rosidl_generate_interfaces(${PROJECT_NAME} # Messages + "msg/Capability.msg" + "msg/CapabilityDescriptor.msg" + "msg/CapabilityFeedback.msg" + "msg/CapabilityParam.msg" + "msg/CapabilityRecord.msg" + "msg/CapabilityResult.msg" "msg/CortexCommand.msg" "msg/CortexCommandRecord.msg" "msg/CortexFeedback.msg" @@ -53,12 +59,15 @@ rosidl_generate_interfaces(${PROJECT_NAME} # Services "srv/CommandCortexFlow.srv" + "srv/ListCapabilities.srv" "srv/ListPathLogicOptions.srv" "srv/ListReferenceTargets.srv" "srv/ListVehicleOptions.srv" "srv/ModifyCortexQueue.srv" + "srv/QueryCapabilityRecords.srv" "srv/QueryCortexHistory.srv" "srv/QueryCortexQueue.srv" + "srv/QueueCapabilities.srv" "srv/VehicleJointCommand.srv" DEPENDENCIES ${dependencies} ) diff --git a/msg/Capability.msg b/msg/Capability.msg new file mode 100644 index 0000000..82bdc11 --- /dev/null +++ b/msg/Capability.msg @@ -0,0 +1,9 @@ +# Capability +# +# A named capability and the param values to run it with. Names and params are +# listed by ListCapabilities. + +string name + +# Values are plain strings in the unit the capability's descriptor declares. +polymath_msgs/KeyValue[] params diff --git a/msg/CapabilityDescriptor.msg b/msg/CapabilityDescriptor.msg new file mode 100644 index 0000000..abc1922 --- /dev/null +++ b/msg/CapabilityDescriptor.msg @@ -0,0 +1,16 @@ +# CapabilityDescriptor +# +# What a robot can do: a capability's name, description, whether it may run +# alongside other capabilities, and its params. + +# Execution mode (Enum) +# +# PARALLEL: may run alongside other capabilities +# SEQUENTIAL: runs alone and holds back everything queued behind it +uint8 PARALLEL=0 +uint8 SEQUENTIAL=1 + +string name +string description +uint8 execution +polymath_msgs/CapabilityParam[] params diff --git a/msg/CapabilityFeedback.msg b/msg/CapabilityFeedback.msg new file mode 100644 index 0000000..98ed848 --- /dev/null +++ b/msg/CapabilityFeedback.msg @@ -0,0 +1,25 @@ +# CapabilityFeedback +# +# Live status while capabilities run. + +# General Information +builtin_interfaces/Time timestamp_utc + +# Cortex Status +polymath_msgs/CortexStatus cortex_status + +# Identifiers of every active capability. Empty when nothing is active. +unique_identifier_msgs/UUID[] active_capability_ids + +# Number of capabilities waiting to run. +uint32 number_queued + +# Current Pose converted back to GPS post Filters +# Requires localization to be up to return useful data +geographic_msgs/GeoPoseStamped current_pose + +# Navigation Feedback +polymath_msgs/NavigationFeedback navigation_feedback + +# Vehicle Feedback +polymath_msgs/VehicleFeedback vehicle_feedback diff --git a/msg/CapabilityParam.msg b/msg/CapabilityParam.msg new file mode 100644 index 0000000..1be9772 --- /dev/null +++ b/msg/CapabilityParam.msg @@ -0,0 +1,28 @@ +# CapabilityParam +# +# One parameter of a capability, with the limits the robot checks it against. + +uint8 BOOL=0 +uint8 INT=1 +uint8 DOUBLE=2 +uint8 STRING=3 +uint8 UINT=4 + +string name +uint8 type +bool required + +# Limits for numeric params, used only when the matching has_ flag is set. +bool has_min +bool has_max +float64 min_value +float64 max_value + +# Accepted values for string params. Empty accepts any value. +string[] enum_values + +# What the value is measured in, for example deg, rad, m, s, percent. Empty for unitless values. +# Values are sent as plain strings in this unit. There is no conversion. +string units + +string description diff --git a/msg/CapabilityRecord.msg b/msg/CapabilityRecord.msg new file mode 100644 index 0000000..9c7e00c --- /dev/null +++ b/msg/CapabilityRecord.msg @@ -0,0 +1,51 @@ +# CapabilityRecord +# +# Cortex's bookkeeping wrapper around a single Capability. It carries the +# Cortex-assigned identity, lifecycle state, and terminal outcome. + +# Cortex-assigned identifier, unique per queued capability. +unique_identifier_msgs/UUID id + +# The wrapped capability. +polymath_msgs/Capability capability + +# Short human-readable description of the capability (name plus params). +string summary + +# Lifecycle State (Enum) +# +# QUEUED: accepted and waiting to run +# ACTIVE: running +# TERMINAL: finished; see outcome +uint8 QUEUED=0 +uint8 ACTIVE=1 +uint8 TERMINAL=2 +uint8 state + +# Terminal Outcome (Enum) +# +# OUTCOME_UNKNOWN: not yet terminal +# SUCCEEDED: ran to completion +# FAILED: a command of the capability failed +# CANCELED: discarded by a stop +# PREEMPTED: discarded by a preempting request +# REJECTED: never accepted (failed validation) +uint8 OUTCOME_UNKNOWN=0 +uint8 SUCCEEDED=1 +uint8 FAILED=2 +uint8 CANCELED=3 +uint8 PREEMPTED=4 +uint8 REJECTED=5 +uint8 outcome + +# Outcome context, e.g. the validation message for a rejection. +string detail + +# Time the capability was accepted and queued. +builtin_interfaces/Time queued_time + +# Time the capability became active. Zero until started. +builtin_interfaces/Time started_time + +# Time the capability reached a terminal state. Zero until terminal. +builtin_interfaces/Time completed_time diff --git a/msg/CapabilityResult.msg b/msg/CapabilityResult.msg new file mode 100644 index 0000000..7608b8c --- /dev/null +++ b/msg/CapabilityResult.msg @@ -0,0 +1,11 @@ +# CapabilityResult +# +# The answer for one capability of a QueueCapabilities request. + +# Identifier of the capability, used to follow it in QueryCapabilityRecords. +unique_identifier_msgs/UUID id + +bool accepted + +# Why the capability was rejected. Empty when accepted. +string message diff --git a/srv/ListCapabilities.srv b/srv/ListCapabilities.srv new file mode 100644 index 0000000..a01ba07 --- /dev/null +++ b/srv/ListCapabilities.srv @@ -0,0 +1,5 @@ +# ListCapabilities +# +# What this robot can do, with the params each capability takes. +--- +polymath_msgs/CapabilityDescriptor[] capabilities diff --git a/srv/QueryCapabilityRecords.srv b/srv/QueryCapabilityRecords.srv new file mode 100644 index 0000000..ed18ec2 --- /dev/null +++ b/srv/QueryCapabilityRecords.srv @@ -0,0 +1,22 @@ +# QueryCapabilityRecords +# +# Every capability record Cortex knows, queued, active and finished, in one list. +# Newest first by queued time. Each record's `state` and `outcome` say where it is. + +uint8 QUEUED_BIT=1 +uint8 ACTIVE_BIT=2 +uint8 TERMINAL_BIT=4 + +# Which states to return, as a mask of the bits above (bit = 1 << CapabilityRecord.state). 0 returns all. +uint8 states + +# Maximum number of finished records to return. 0 means no limit. Queued and active records are always +# returned. Finished records are also bounded by Cortex's history_depth. +uint32 max_count + +# Only the record with this id. The nil UUID disables. +unique_identifier_msgs/UUID capability_id +--- +bool success +string message +polymath_msgs/CapabilityRecord[] records diff --git a/srv/QueueCapabilities.srv b/srv/QueueCapabilities.srv new file mode 100644 index 0000000..15fb165 --- /dev/null +++ b/srv/QueueCapabilities.srv @@ -0,0 +1,23 @@ +# QueueCapabilities +# +# Deferred: the answer arrives once every capability is queued or rejected, or after a timeout. +# One request is in flight at a time. A request that arrives while another waits is answered +# with success=false and "request already in flight". A PREEMPT request is the exception: it +# rejects the waiting request, preempts, and proceeds. + +# Mode (Enum) +# +# ADD: add to the queue +# PREEMPT: discard what is queued and running, then queue the request +uint8 ADD=0 +uint8 PREEMPT=1 +uint8 mode + +polymath_msgs/Capability[] capabilities +--- +# True when every capability was accepted. +bool success +string message + +# Aligned 1:1 with capabilities. +polymath_msgs/CapabilityResult[] results