feat: support controller predicates in conditions and sequences (#153)

aica-technology · Apr 24, 2024 · 40ed43f · 40ed43f
1 parent 84031d8
commit 40ed43f
Show file tree

Hide file tree

Showing 5 changed files with 132 additions and 19 deletions.
diff --git a/docs/docs/reference/02-yaml-syntax.md b/docs/docs/reference/02-yaml-syntax.md
@@ -145,6 +145,15 @@ call_service:
   component: <component_name>
 ```
 
+Call a service on a controller.
+
+```yaml
+call_service:
+  service: <service_name>
+  controller: <controller_name>
+  hardware: <hardware>
+```
+
 Call a service with a string payload.
 
 ```yaml
@@ -578,6 +587,9 @@ The `parameters` field then refers to configurable parameters for the given cont
 The `inputs` and `outputs` fields define the ROS2 topics to which each signal of the controller should be connected.
 See also [Component Inputs and Outputs](#inputs-and-outputs).
 
+Predicates can be used to trigger [events](#events) by adding the named predicate and corresponding events
+under the `events` field of a controller definition. See also [Predicate Events](#predicate-events).
+
 Optionally, the `position` field can be used to specify an X, Y location for rendering the hardware interface
 as a node in the AICA interactive graph editor. See also [Component Position](#position).
 
@@ -599,6 +611,10 @@ robot:
         command: /motion_generator/command_output
       outputs:
         state: /recorder/state_input
+      events:
+        my_predicate_name:
+          set: ...
+          call_service: ...
 ```
 
 ## Conditions
@@ -623,6 +639,13 @@ conditions:
       ...
 
   condition_2:
+    controller: ...
+    hardware: ...
+    predicate: ...
+    events:
+      ...
+
+  condition_3:
     <conditional_operator>: ...  # not, all, any, one_of
     events:
       ...
@@ -631,14 +654,21 @@ conditions:
 
 ### Simple conditions
 
-A simple condition evaluates just a single component predicate and triggers the listed events when it is true.
+A simple condition evaluates just a single component or controller predicate and triggers the listed events when it is
+true.
 
 ```yaml
 condition_1:
   component: my_component
   predicate: some_component_predicate
   events:
     ...
+condition_2:
+  controller: my_controller
+  hardware: my_hardware
+  predicate: some_controller_predicate
+  events:
+    ...
 ```
 
 ### Conditional operators
@@ -729,7 +759,7 @@ Similar to [conditions](#conditions), sequences are listed under a top-level fie
 must be unique, and should generally follow the `lower_camel_case` naming convention.
 
 After sequences are defined in the yaml, they can be managed using [sequence state events](#manage-sequences); component
-predicates, conditions and even sequences can also start, restart or abort a sequence.
+or controller predicates, conditions and even sequences can also start, restart or abort a sequence.
 
 The example below uses a combination of standard event steps and conditional blocks; it asserts that a component is
 active, sets a parameter on that component, waits 10 seconds, and then activates a controller.
@@ -757,7 +787,7 @@ The `assert` keyword is an assertion step to check if a condition or predicate i
 the sequence continues to the next step. If the assertion fails, the sequence is automatically aborted.
 Optionally, assertion failure can be used to trigger breakout events as a form of error handling.
 
-The following examples show the syntax to check either a condition or component predicate respectively.
+The following examples show the syntax to check either a condition or predicate respectively.
 
 ```yaml
 assert:
@@ -770,6 +800,13 @@ assert:
   predicate: some_predicate
 ```
 
+```yaml
+assert:
+  controller: my_controller
+  hardware: my_hardware
+  predicate: some_predicate
+```
+
 The `else` keyword is optionally used to define breakout events if the assertion fails. The following example would
 unload a component if condition `my_condition` is not true and then abort the sequence.
 
@@ -783,7 +820,7 @@ assert:
 
 ### Sequence wait
 
-The `wait` keyword is used to wait for either a fixed time interval or for a condition or component predicate to be
+The `wait` keyword is used to wait for either a fixed time interval or for a condition or predicate to be
 true.
 
 #### Waiting for a specified time interval
@@ -797,7 +834,7 @@ wait:
 
 #### Waiting for a condition or predicate
 
-The following examples show the syntax to wait for either a condition or component predicate state respectively.
+The following examples show the syntax to wait for either a condition or predicate state respectively.
 
 ```yaml
 wait:
@@ -810,6 +847,13 @@ wait:
   predicate: some_predicate
 ```
 
+```yaml
+wait:
+  controller: my_controller
+  hardware: my_hardware
+  predicate: some_predicate
+```
+
 Compared to the simple fixed-time wait, a conditional wait step could block the sequence indefinitely. The `timeout`
 field can be used when waiting for a condition or predicate to set a maximum time limit. The time limit is defined in
 seconds with the `seconds` field.
@@ -914,7 +958,7 @@ my_button:
 
 ## Validating a YAML application
 
-The [YAML application schema](https://docs.aica.tech/schemas/1-4-0/application.schema.json) defines the structural rules
+The [YAML application schema](https://docs.aica.tech/schemas/1-4-1/application.schema.json) defines the structural rules
 of an AICA application and effectively distinguishes between valid and invalid syntax.
 
 Many modern IDEs and code editors can be configured to support custom schemas and provide in-line validation and
@@ -928,5 +972,5 @@ Developers working with Visual Studio Code can validate YAML application files e
 2. Associate a schema with the YAML application by adding the following modeline to the file:
 
 ```yaml
-# yaml-language-server: $schema=https://docs.aica.tech/schemas/1-4-0/application.schema.json
+# yaml-language-server: $schema=https://docs.aica.tech/schemas/1-4-1/application.schema.json
 ```
diff --git a/schemas/applications/CHANGELOG.md b/schemas/applications/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 Release Versions:
 
+- [1-4-1](#141)
 - [1-4-0](#140)
 - [1-3-0](#130)
 - [1-2-0](#120)
@@ -10,6 +11,10 @@ Release Versions:
 - [1-1-0](#110)
 - [1-0-0](#100)
 
+## 1-4-1
+
+Version 1-4-1 adds support for controller predicates in conditions and sequences.
+
 ## 1-4-0
 
 Version 1-4-0 adds support for predicate events on controllers.

diff --git a/schemas/applications/schema/application.schema.json b/schemas/applications/schema/application.schema.json
@@ -1,5 +1,5 @@
 {
-  "$id": "/1-4-0/application.schema.json",
+  "$id": "/1-4-1/application.schema.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "YAML Application Description",
   "description": "An AICA application graph description using YAML syntax.",

diff --git a/schemas/applications/schema/conditions.schema.json b/schemas/applications/schema/conditions.schema.json
@@ -49,6 +49,12 @@
         "component": {
           "$ref": "events/identifiers/component.schema.json"
         },
+        "controller": {
+          "$ref": "events/identifiers/controller.schema.json#/properties/controller"
+        },
+        "hardware": {
+          "$ref": "events/identifiers/hardware.schema.json"
+        },
         "predicate": {
           "$ref": "events/identifiers/predicate.schema.json"
         }
@@ -79,6 +85,13 @@
             "component",
             "predicate"
           ]
+        },
+        {
+          "required": [
+            "controller",
+            "hardware",
+            "predicate"
+          ]
         }
       ]
     }
@@ -167,13 +180,30 @@
         "component": {
           "$ref": "events/identifiers/component.schema.json"
         },
+        "controller": {
+          "$ref": "events/identifiers/controller.schema.json#/properties/controller"
+        },
+        "hardware": {
+          "$ref": "events/identifiers/hardware.schema.json"
+        },
         "predicate": {
           "$ref": "events/identifiers/predicate.schema.json"
         }
       },
-      "required": [
-        "component",
-        "predicate"
+      "oneOf": [
+        {
+          "required": [
+            "component",
+            "predicate"
+          ]
+        },
+        {
+          "required": [
+            "controller",
+            "hardware",
+            "predicate"
+          ]
+        }
       ]
     }
   }

diff --git a/schemas/applications/schema/sequences.schema.json b/schemas/applications/schema/sequences.schema.json
@@ -100,23 +100,40 @@
     },
     "wait_for_predicate": {
       "title": "Wait for Predicate",
-      "description": "Wait until a component predicate is true with an optional timeout to abort the sequence and handle breakout events",
+      "description": "Wait until a predicate is true with an optional timeout to abort the sequence and handle breakout events",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "component": {
           "$ref": "events/identifiers/component.schema.json"
         },
+        "controller": {
+          "$ref": "events/identifiers/controller.schema.json#/properties/controller"
+        },
+        "hardware": {
+          "$ref": "events/identifiers/hardware.schema.json"
+        },
         "predicate": {
           "$ref": "events/identifiers/predicate.schema.json"
         },
         "timeout": {
           "$ref": "#/$defs/timeout"
         }
       },
-      "required": [
-        "component",
-        "predicate"
+      "oneOf": [
+        {
+          "required": [
+            "component",
+            "predicate"
+          ]
+        },
+        {
+          "required": [
+            "controller",
+            "hardware",
+            "predicate"
+          ]
+        }
       ]
     },
     "wait_for_time": {
@@ -153,13 +170,19 @@
     },
     "assert_predicate": {
       "title": "Assert Predicate",
-      "description": "Assert that a component predicate is true or else abort the sequence and handle breakout events",
+      "description": "Assert that a predicate is true or else abort the sequence and handle breakout events",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "component": {
           "$ref": "events/identifiers/component.schema.json"
         },
+        "controller": {
+          "$ref": "events/identifiers/controller.schema.json#/properties/controller"
+        },
+        "hardware": {
+          "$ref": "events/identifiers/hardware.schema.json"
+        },
         "predicate": {
           "$ref": "events/identifiers/predicate.schema.json"
         },
@@ -168,9 +191,20 @@
           "$ref": "events.schema.json"
         }
       },
-      "required": [
-        "component",
-        "predicate"
+      "oneOf": [
+        {
+          "required": [
+            "component",
+            "predicate"
+          ]
+        },
+        {
+          "required": [
+            "controller",
+            "hardware",
+            "predicate"
+          ]
+        }
       ]
     }
   }