Integrated all decisions made with Gunnar A and local PDX architectur…

…e team

seats-service.yml

@@ -5,20 +5,73 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
 #
+
+
+# Service
+#
+#  A service is a collection of interfaces.
+#  In addition to the interfaces themselves, the service
+#  defines data types and enums used by the interfaces hosted by
+#  the service.
+#
+# Examples:
+#  Comfort service - hosts interfaces for HVAC, seats, and ambient lighting.
+#  Media services - hosts interfaces for Sirius XM, FM, AM, DAB, Spotify, etc.
+#
+# TODO:
+# + Define additional semantics for a service, if needed.
+#
+# + How do we map namespaces to FrancaIDL (packages?)
+#   Multiple namespaces in a single service file does not map
+#   to single FrancaIDL package name.
+#
 service:
-  name: seats
-  description: Seats API
+
+  name: comfort
+  description: A collection of interfaces pertaining tso cabin comfort.
+
+  # Datatypes
+  #
+  #  Datatypes are global for all interfaces under the given service (comfort)
+  #
+  # TODO:
+  # + How do we import datatypes from other service files?  Importing
+  #   datatypes used by multiple services make sense, but it will put
+  #   a strain on the build pipeline since we now will have to seach
+  #   for and assemble a library of interdependent services.
+  #
+  # + Decide if datatypes can be placed at lower levels (interfaces,
+  #   commands, etc) in order to create scope-local datatypes. Also
+  #   decide if we can have global data types (above service level),
+  #   which ties into the issue above.
+  #
   datatypes:
+    # Namespaces
+    # 
+    # Name spaces are used to separate out data types with the same name
+    # popping up in different interfaces.
+    # 
     - namespace: movement
       description: |
         The units used to describe movement of the seats
       types:
+        # Typedefs
+        #
+        # Standard redefinition of native types are supported.
+        # Min/max intervals can be optionally specified
+        #
         - name: movement_t
           type: uint16_t
           min: 0
           max: 1000
           description: |
             The movement of a seat component
+
+        # Structs
+        #
+        # Standard structs can be defind, using either native types, tyepdefs,
+        # or other (nested) structs.
+        # 
         - name: position_t
           type: struct
           description: | 
@@ -57,8 +110,20 @@ service:
               type: uint8_t
               description: |
                 The index within the row, 0 left most, +1 toward right
+              
+        # Enums
+        #
+        #  TODO:
+        #  + Decide if we need to move enum_type (uint8_t) to a separate deployment
+        #    file, one per target (python, C++, etc).
+        #    The upside is a cleaner, more service-oriented catalog.
+        #    The downside is it inter-target operability is harder to
+        #    define an over-the-wire payload format since one target
+        #    can define uint16_t while another has uint8_t.
+        #
         - name: seat_component_t
-          type: enum
+          type: enumeration   # RESOLUTION: was enum. Ok to rename enumeration.
+
           enum_type: uint8_t
           options:
             - name: base
@@ -71,6 +136,7 @@ service:
               value: 3
             - name: head_restraint
               value: 4 
+
         - name: seat_t
           type: struct
           description: |
@@ -84,84 +150,150 @@ service:
               type: movement.position_t
               description: |
                 The various positions of the seat              
-  commands:
-    - name: move
-      description: |
-        Set the desired seat position
-      arguments:
-        - name: seat
-          description: |
-            The desired seat position
-          type: movement.seat_t
-    - name: move_component
-      description: |
-        Set a seat component position
-      arguments:
-        - name: seat
-          description: |
-            The seat location to change
-          type: movement.seat_location_t
-        - name: component
-          description: |
-            The component position to change
-          type: movement.seat_component_t
-        - name: position
-          description: | 
-            The desired position to move the component to
-          type: movement.movement_t
-  requests:
-    - name: current_position
-      description: |
-        Get the current position of the seat
-      arguments:
-        - name: row
-          description: |
-            The desired seat to row query
-          type: uint8_t
-        - name: index
-          description: |
-            The desired seat index to query
-          type: uint8_t
-      reply:
-        arguments:
+
+  # Interface
+  #
+  #  An interface is a collection of commands, methods, and events.
+  #
+  #  A command is a single sender -> single receiver request
+  #  with no return value.
+  #
+  #  A method is a single sender -> single receiver request
+  #  with a return value.
+  # 
+  #  An event is a single sender -> multiple receiver request
+  #  with no return value.
+  #
+
+  interfaces: # ok with JLR.
+    # TODO
+    # + Add HVAC and ambient lighting to complete the comfort service.
+    #
+    # + Define include directives.
+    #   Example:- include: "hvac.yml"
+    #   Research if we can use YAML's anchor mechanism to get built-in
+    #   include support.
+    #   We need to figure out how data types spanning multiple interfaces
+    #   are handled in this case.
+    #
+    # + Do we specify delivery effort level here?
+    #   UDP vs. TCP-level effort for commands, methodsm and events?
+    #
+  - include-interface: "xxx.yml" 
+
+  - name: seats
+    description: Seats API
+
+    # Commands
+    #
+    # A command invokes a function for a given service with no return
+    # value being sent back.
+    # 
+    commands:
+      - name: move
+        description: |
+          Set the desired seat position
+
+        in_argument: # TODO FYI: Gunnar
+          - name: seat
+            description: |
+              The desired seat position
+              type: movement.seat_t
+
+      - name: move_component
+        description: |
+          Set a seat component position
+
+        # Arguments
+        #
+        #  Argument can be of any native type, enum, struct, or typedef.
+        #  
+        in_arguments:
+          - name: seat
+            description: |
+              The seat location to change
+            type: movement.seat_location_t
+          - name: component
+            description: |
+              The component position to change
+            type: movement.seat_component_t
+          - name: position
+            description: | 
+              The desired position to move the component to
+              type: movement.movement_t
+
+    # Method
+    #
+    # A method invokes a function for a given service with a return
+    # value being sent back.
+    # 
+    methods: #
+      - name: current_position
+        description: |
+          Get the current position of the seat
+
+        in_arguments:
+          - name: row
+            description: |
+              The desired seat to row query
+            type: uint8_t
+          - name: index
+            description: |
+              The desired seat index to query
+            type: uint8_t
+
+        out_arguments:
           - name: seat
             description: |
               The seat state that was requested
-            type: movement.seat_t
-  events:
-    - name: seat_moving
-      description: |
-        The event of a seat beginning movement
-      arguments:
-        - name: status
-          description: |
-            The movement status, moving (1), not moving (0)
-          type: uint8_t
-        - name: row
-          description: |
-            The row of the seat
-          type: uint8_t
-        - name: index
-          description: |
-            The index of the seat position in the row
-          type: uint8_t
-        - name: component
-          description: |
-            The seat component that is moving
-          type: movement.seat_component_t
-    - name: passenger_present
-      description: |
-        When the seat passenger status changes
-      arguments:
-        - name: status
-          description: |
-            The status of seat passenger, passenger (1), no passenger (0)
-          type: uint8_t
-        - name: row
-          description: |
-            The row of the seat
-          type: uint8_t
-        - name: index
-          description: |
-            The index of the seat position in the row
-          type: uint8_t
+              type: movement.seat_t
+
+    # Events
+    #
+    #  Events are non-returning commands with multiple subscribers,
+    #  much like SOME/IP events.
+    #  Unlike signals an event retains no state (value) after it has
+    #  been called; once it has been sent it is forgotten.
+    #
+    # TODO:
+    # + FrancaIDL may lack semantics to cover this. We need to
+    #   create apropriate transformation rules.
+    # 
+    events:
+      - name: seat_moving
+        description: |
+          The event of a seat beginning movement
+        in_arguments:
+          - name: status
+            description: |
+              The movement status, moving (1), not moving (0)
+            type: uint8_t
+          - name: row
+            description: |
+              The row of the seat
+            type: uint8_t
+          - name: index
+            description: |
+              The index of the seat position in the row
+            type: uint8_t
+          - name: component
+            description: |
+              The seat component that is moving
+            type: movement.seat_component_t
+
+      - name: passenger_present
+        description: |
+          When the seat passenger status changes
+        in_arguments:
+          - name: status
+            description: |
+              The status of seat passenger, passenger (1), no passenger (0)
+            type: uint8_t
+          - name: row
+            description: |
+              The row of the seat
+            type: uint8_t
+          - name: index
+            description: |
+              The index of the seat position in the row
+            type: uint8_t