seats-service.yml

# 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 to 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_arguments: # 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