Initial commit of sample seat service to be used as basis for design discussion

seats-service.yml

@@ -0,0 +1,299 @@
+#
+# Copyright 2020, Jaguar Land Rover,
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# 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: 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: | 
+            The position of the entire seat
+          members:
+            - name: base
+              type: movement.movement_t
+              description: |
+                The position of the base 0 front, 1000 back
+            - name: cushion
+              type: movement.movement_t
+              description: |
+                The position of the cushion 0 short, 1000 long
+            - name: lumbar
+              type: movement.movement_t
+              description: |
+                The position of the lumbar support
+            - name: side_bolster
+              type: movement.movement_t
+              description: |
+                The position of the side bolster
+            - name: head_restraint
+              type: movement.movement_t
+              description: |
+                The position of the head restraint 0 down, 1000 up
+        - name: seat_location_t
+          type: struct
+          description: |
+            The location of the seat in the vehicle
+          members:
+            - name: row
+              type: uint8_t
+              description: |
+                The row, front 0 and +1 toward rear
+            - name: index
+              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: enumeration   # RESOLUTION: was enum. Ok to rename enumeration.
+
+          enum_type: uint8_t
+          options:
+            - name: base
+              value: 0
+            - name: cushion
+              value: 1
+            - name: lumbar
+              value: 2
+            - name: side_bolster
+              value: 3
+            - name: head_restraint
+              value: 4 
+
+        - name: seat_t
+          type: struct
+          description: |
+            The structure used to describe the seat's position in the vehicle
+          members:
+            - name: location
+              type: movement.seat_location_t
+              description: |
+                The location of the seat in the vehicle
+            - name: position
+              type: movement.position_t
+              description: |
+                The various positions of the seat              
+
+  # 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
+    #
+    #  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