Need for change of instance handling

[erikbosch]

Now and then we discuss if the current instance solution is sufficient. We have some issues and pull requests currently opened:

#564 suggests to be able to have instances on individual signals
#375 suggests a more flexible naming mechanism
COVESA/vss-tools#293 has a solution to produce unexpanded output

Instances sometimes also comes up as a topic when discussing ontologies. The intention with this issue is to discuss if we see any changes required in the VSS-syntax to better support ontologies and Vehicle APIs. some ideas follow below:

Idea on how to change syntax

I am thinking if we should change to a different method to represent instances. As I see it instance declarations like stating number of rows in standard tree has limited value as it is vehicle specific and even may change for a specific vehicle, like if you remove some seats from your minivan. That VSS standard catalog states that there shall be two rows of seats with 3 seats in each does not really make sense. An alternative approach would be that VSS just states that a seat has two instance-related const attributes, row and position, of integer and string types. Which instances that exist is deployment related - you could either give it in VSS-specified syntax as a customization or overlay, or let the server handle it dynamically.

So instead of stating that there IS 2 rows we maybe just state that there is a row attribute and a Pos attribute. For Row we do not state any limits, for Pos we give allowed values. This is what a client needs to know to be able to create correct requests. We could even support to both have a Left/Right-approach as well as Driver/Passenger-approach and let the server manage the mapping.

Another reason for changing syntax for defining instances is that the current syntax is not that well defined, vss-tools use patterns to guess if a range or a list is given, so you cannot for example combined list and prefix.

Vehicle.Seat:
  type: branch
  description: Branch A.AA.
  instance:
    definition:
        - id: 'Row' # Id, would typically be used as argument name in API methods, like "getAA(row: uint8, pos: string)"
          datatype: uint8 # Defining type
          prefix: 'Row' # Prefix to use in extended names, like "Row1"
        - id: 'Pos'
          datatype: string
          allowed: ['LEFT','RIGHT','CENTER','DRIVER_SIDE', 'PASSENGER_SIDE']

For a static setup the client and the server needs additional deployment information. That could be defined "VSS-Style" like below. Default values could be defined, to allow to skip instance information in API, like that a call to Vehicle.Seat.IsHeatingOn corresponds to Vehicle.Seat.Row1.Center.IsHeatingOn. Aliases could be defined so that the server knows how Left/Right and DriverSide/PassengerSide is related, so that client can use both methods to address seats. An instance_list attribute could be added to specify exactly which combinations that are valid.

Vehicle.Seat:
  type: branch
  description: Branch A.AA.
  instance:
    definition:
        - id: 'Row' # Id, would typically be used as argument name in API methods, like "getAA(row: uint8, pos: string)"
          datatype: uint8 # Defining type
          min: 1 # max/min/allowed are optional, if not specified any combination can be seen as valid for a request, but server may answer "not found" or similar
          max: 3
          prefix: 'Row' # Prefix to use in extended names, like "Row1"
        - id: 'Pos'
          datatype: string
          allowed: ['LEFT','RIGHT','CENTER','DRIVER_SIDE', 'PASSENGER_SIDE']
          aliases:
             - id: 'LEFT'
               alias: DRIVER_SIDE'
             - id: 'RIGHT'
               alias: 'PASSENGER_SIDE'
                   # Aliases likely doe not make sense in standard catalog, but could be useful in instantiations
                   # so that the server for example knows that a request for "DriverSide" in this particular vehicle
                   # means that it internally shall send the request to the Left seat.
                   # Order matters, if the vehicle internally instead has wiring based on driver-side/passenger-side
                   # then id would be DRIVER_SIDE and alias LEFT
    instance_list: [[1,'CENTER'],[1,'RIGHT'],[2,'LEFT'],[2,'CENTER'],[2,'RIGHT']]
                   # Possibility to specify exactly which instance combinations exist
                   # Would typically not exist in standard catalog
                   # If not specified all combinations are valid in requests

One could support instances on individual signals as well, but also has a syntax to specify instance restriction, if a signal isn't supported for all instances.

A.AA.SignalBB:
  datatype: int8
  type: sensor
  unit: km
  instance-restriction:
    -branch: '.' # Branch designation, Allowed values '.' (current branch) and 'Branch id', like "branch: AA"
     instance_list:  [[1,'LEFT'],[2,'RIGHT']]
  description: Signal with instance restriction

or alternatively, not specifying which branch it concerns

A.AA.BB.CC.SignalDD:
  datatype: int8
  type: sensor
  unit: km
  instance-restriction: [[1,'*','LEFT'], [2,1,'RIGHT']]
  description: Signal with instance restriction
  comment: Three or more instance parameters expected, where 'LEFT' is the one "closest" to the signal
                   Asterisk means any value, i.e. all defined as valid in original branch definition
                   If there are four instance parameters, first param corresponds to [['*',1,'*','LEFT']]

Addressing when using VISS could be left unchanged, there we still need dot notated identifiers. A possible change could be to allow unexpanded identifiers if there is a default instance value, like "Vehicle.Seat.Height" for a motorbike that only has one seat.

[erikbosch]

Instances discussed at AMM. Audience seems to be possible to change instance representation, possibly in the way proposed by Ford but nothing decided

[erikbosch]

See also #639

[erikbosch]

Based on the ideas from Alan - one could think of having a reusable instance declaration node type, similar to area definitions like VehicleAreaDoor in Android.

Vehicle.SeatInstance:
  type: instance
  description: Seat instance model
  instance:
    definition:
        - id: 'Row' # Id, would typically be used as argument name in API methods, like "getAA(row: uint8, pos: string)"
          datatype: uint8 # Defining type
          min: 1 # max/min/allowed are optional, if not specified any combination can be seen as valid for a request, but server may answer "not found" or similar
          max: 3
          prefix: 'Row' # Prefix to use in extended names, like "Row1"
        - id: 'Pos'
          datatype: string
          allowed: ['LEFT','RIGHT','CENTER','DRIVER_SIDE', 'PASSENGER_SIDE']
          aliases:
             - id: 'LEFT'
               alias: DRIVER_SIDE'
             - id: 'RIGHT'
               alias: 'PASSENGER_SIDE'
                   # Aliases likely doe not make sense in standard catalog, but could be useful in instantiations
                   # so that the server for example knows that a request for "DriverSide" in this particular vehicle
                   # means that it internally shall send the request to the Left seat.
                   # Order matters, if the vehicle internally instead has wiring based on driver-side/passenger-side
                   # then id would be DRIVER_SIDE and alias LEFT
    instance_list: [[1,'CENTER'],[1,'RIGHT'],[2,'LEFT'],[2,'CENTER'],[2,'RIGHT']]
                   # Possibility to specify exactly which instance combinations exist
                   # Would typically not exist in standard catalog
                   # If not specified all combinations are valid in requests

And used like this:

Vehicle.Seat:
  type: branch
  description: Branch A.AA.
  instance: Vehicle.SeatInstance

From a vss-tools perspective I see two main alternatives. In "expanded" mode instance_listshall be considered, and alias just appended on every expanded signal:

Vehicle.Seat.Row1.Left.Pos:
  type: actuator
  description: Seat Pos

Vehicle.Seat.Row1.DriverSide.Pos:
  type: actuator
  alias: Vehicle.Seat.Row1.Left.Pos
  description: Seat Pos

I.e. it is up to the backend/server to know that Vehicle.Seat.Row1.DriverSide.Pos is an alias for Vehicle.Seat.Row1.Left.Pos. Alternatively one could "invent" a type alias:

Vehicle.Seat.Row1.DriverSide.Pos:
  type: alias
  alias: Vehicle.Seat.Row1.Left.Pos

In "non-expanded" mode information shall just be kept as is.

[alanmapleburl-au]

Here's an information science (data model, taxonomy, ontology) point of view.

The most flexible concept is that the instance declares the class of which it is an instance. In the example below, it uses an "isA" k/v pair to do so:

Vehicle.Seat.Row1.Left:
  type: branch
  isA: Vehicle.Seat

This has the following benefits:

• It allows anomalies, such as a seat in the center-left position.
• New instances can be added without changing an enumeration
• It retains a mechanism where each instance of a seat inherits the general seat signals.
• The references can be navigated both ways...return the instances of Vehicle.Seat or return the class of Vehicle.Seat.Row1.Left.
• It could be expanded to allow multiple inheritance. (CAUTION!)
• Each instance can be further articulated as in this example:

Vehicle.Seat.Row1.Left:
  type: branch
  isA: Vehicle.Seat
  rowNumber: 1
  lateralPosition: Left
  occupantRole: Driver
  hasTiltMechanism: true

Generally, containers do not have explicit knowledge of their components. They know they have collections (seats, e.g.), but those are eagerly populated at load or lazily populated on use rather than at compile time.