feat(polymath_msgs): add the capability messages and services

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}
 )

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

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

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

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

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

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

srv/ListCapabilities.srv

@@ -0,0 +1,5 @@
+# ListCapabilities
+#
+# What this robot can do, with the params each capability takes.
+---
+polymath_msgs/CapabilityDescriptor[] capabilities

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

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