Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Left/Right Instance Discussion #718

Closed
wants to merge 1 commit into from
Closed

Left/Right Instance Discussion #718

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 32 additions & 6 deletions docs-gen/content/rule_set/instances.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,39 @@ quite often there is a need to repeat branches and data entries
branches and data entries in the specification an instance-concept is supported.
Instances remove the need of repeating definitions, by defining at the node itself how often it occurs in
the resulting tree. They are meant as a short-cut in the specification and
interpreted by the tools. As an example is shown below for doors:
interpreted by the tools.

The instance names defined in VSS can be seen as labels
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this makes sense, but I would like to spend some more time thinking this through as to how this would be implemented in practice.

I immediately see two approaches:

  1. Use an overlay to (effectively) delete the entries that are not implemented (that is, replace ["DriverSide", "PassengerSide", "Left", "Right"] by ["Left", "Right"] or ["DriverSide", "PassengerSide"]).
  2. Support them as aliases.

For 1., there are portability issues (an app written to look for DriverSide would not find it on vehicles that use a ["Left", "Right"] definition, and thus would need to be adapted). There is also the argument that if we expect an overlay to be used here, then going with one or the other of ["Left", "Right"] or ["DriverSide", "PassengerSide"] makes some minimal portability guarantee (at least for vehicles that use the definition as it is).

For 2., any code that reports the value for this signal would need to know that it needs to report (or store) this value twice and not just once as it normally does for other signals. Another issue is that

As well, this approach embeds the notion of left-hand vs. right-hand driver side in a bit of an awkward way. Thinking out loud, would it be better for this notion of driver side not to be embedded in this signal, but carried independently, leaving this signal to only have ["Left", "Right"] as instances, with the application relaying on the independent driver position information to cheese between the two instances?

Lastly, where does this leave us with vehicles that do not have a driver side? That is, where the driver is in the middle?

to reference particular instances. There is not necessarily a 1:1 relation between
VSS instance identifiers and physical instances. A typical example could be instance identifiers
for doors, windows and seats. For a left-hand drive vehicle, the driver seat may be referenced both
as `DriverSide` and as `Left`. VSS does not provide any syntax to specify that VSS instance `A`
(for this particular vehicle) actually refers to the same physical instances as `C`.
It is up to the VSS implementation and deployment to manage this relationship, for example
by a configuration file.


As an example is shown below for doors. In VSS four instances of doors are specified for each row,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review phrasing. Not clear what is meant by "As an example is shown below."

"In VSS" -> "In VSS,"

but there are at most two physical doors on each side.
`DriverSide`and `PassengerSide`can be considered as aliases for `Left`and `Right`, or vice versa.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can -> can

as aliases -> aliases

and -> and


<!-- Image source in docs-gen/image_source/instance_tree.puml -->
![Example tree](/vehicle_signal_specification/images/instance_tree.png)

When expanded this corresponds to:

If expanded (for instance by [VSS-tools](https://github.com/COVESA/vss-tools)) this corresponds to:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

) -> ),


<!-- Image source in docs-gen/image_source/instance_tree_expand.puml -->
![Example tree](/vehicle_signal_specification/images/instance_tree_expand.png?width=60pc)
![Example tree expanded](/vehicle_signal_specification/images/instance_tree_expand.png?width=70pc)

## Definition
Note that for example `Vehicle.Cabin.Door.Row1.DriverSide.IsOpen` and `Vehicle.Cabin.Door.Row1.Left.IsOpen` from
a VSS perspective are considered as different signals. It is up to the implementation (for a LHD vehicle) to make
sure that both signal names can be used to control the left door, so that the logical representation corresponds to the image below.

<!-- Image source in docs-gen/image_source/instance_tree_expand_logical.puml -->
![Example tree expanded logical](/vehicle_signal_specification/images/instance_tree_expand_logical.png?width=70pc)

## VSS Syntax

### How can I create instances for my `branch`?

Expand All @@ -38,7 +60,7 @@ When expanded this corresponds to:
and `Position4`. It is in VSS recommended to use `1` as start index for the first row/axle/position/...
4. If multiple instances occur in one node or on the path to a data entry,
the instances get combined, by the order of occurrence. Following the example above,
four position instances will be created for each of the 'DriverSide' and 'PasengerSide' instances,
four position instances will be created for each of the 'DriverSide' and 'PassengerSide' instances,
resulting into a total number of 8 instances.

### How can I exclude child-nodes from instantiation?
Expand All @@ -61,7 +83,7 @@ Door:
type: branch
instances:
- Row[1,2]
- ["DriverSide","PassengerSide"]
- ["DriverSide","PassengerSide", "Left", "Right"]
description: All doors, including windows and switches
#include SingleDoor.vspec Door

Expand Down Expand Up @@ -91,8 +113,12 @@ Results in the following signals:
Vehicle.Cabin.Door.SomeSignal
Vehicle.Cabin.Door.Row1.DriverSide.IsOpen
Vehicle.Cabin.Door.Row1.PassengerSide.IsOpen
Vehicle.Cabin.Door.Row1.Left.IsOpen
Vehicle.Cabin.Door.Row1.Right.IsOpen
Vehicle.Cabin.Door.Row2.DriverSide.IsOpen
Vehicle.Cabin.Door.Row2.PassengerSide.IsOpen
Vehicle.Cabin.Door.Row2.Left.IsOpen
Vehicle.Cabin.Door.Row2.Right.IsOpen
```

## Redefinition
Expand Down
2 changes: 1 addition & 1 deletion docs-gen/image_sources/instance_tree.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
@startuml
card "instances: \n - Row[1,2] \n - ["DriverSide","PassengerSide"]" as C111
card "instances: \n - Row[1,2] \n - ["DriverSide", "PassengerSide", "Left", "Right"]" as C111
usecase Vehicle as N1
usecase Cabin as N11
usecase Door as N111
Expand Down
48 changes: 48 additions & 0 deletions docs-gen/image_sources/instance_tree_expand.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,27 @@ N111-->N111a
usecase Row2 as N111b
N111-->N111b

' Instance Level

usecase DriverSide as N111aa
usecase PassengerSide as N111ab
usecase Left as N111ac
usecase Right as N111ad
N111a-->N111aa
N111a-->N111ab
N111a-->N111ac
N111a-->N111ad

usecase DriverSide as N111ba
usecase PassengerSide as N111bb
usecase Left as N111bc
usecase Right as N111bd
N111b-->N111ba
N111b-->N111bb
N111b-->N111bc
N111b-->N111bd

' Leaf Level

usecase IsOpen as N111aa2
usecase Window as N111aa1
Expand All @@ -35,6 +47,24 @@ N111ab-->N111ab1
N111ab1-->N111ab11
N111ab-->N111ab2

' Left/Right for Row 1


usecase IsOpen as N111ac2
usecase Window as N111ac1
usecase IsOpen as N111ac11
N111ac-->N111ac1
N111ac1-->N111ac11
N111ac-->N111ac2

usecase IsOpen as N111ad2
usecase Window as N111ad1
usecase IsOpen as N111ad11
N111ad-->N111ad1
N111ad1-->N111ad11
N111ad-->N111ad2

' Row 2

usecase IsOpen as N111ba2
usecase Window as N111ba1
Expand All @@ -50,4 +80,22 @@ N111bb-->N111bb1
N111bb1-->N111bb11
N111bb-->N111bb2


' Left/Right for Row 2


usecase IsOpen as N111bc2
usecase Window as N111bc1
usecase IsOpen as N111bc11
N111bc-->N111bc1
N111bc1-->N111bc11
N111bc-->N111bc2

usecase IsOpen as N111bd2
usecase Window as N111bd1
usecase IsOpen as N111bd11
N111bd-->N111bd1
N111bd1-->N111bd11
N111bd-->N111bd2

@enduml
57 changes: 57 additions & 0 deletions docs-gen/image_sources/instance_tree_expand_logical.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
@startuml

usecase Vehicle as N1
usecase Cabin as N11
N1--> N11
usecase Door as N111
N11--> N111

usecase Row1 as N111a
N111-->N111a
usecase Row2 as N111b
N111-->N111b

' Instance Level

usecase "DriverSide/Left" as N111aa
usecase "PassengerSide/Right" as N111ab
N111a-->N111aa
N111a-->N111ab

usecase "DriverSide/Left" as N111ba
usecase "PassengerSide/Right" as N111bb
N111b-->N111ba
N111b-->N111bb

' Leaf Level

usecase IsOpen as N111aa2
usecase Window as N111aa1
usecase IsOpen as N111aa11
N111aa-->N111aa1
N111aa1-->N111aa11
N111aa-->N111aa2

usecase IsOpen as N111ab2
usecase Window as N111ab1
usecase IsOpen as N111ab11
N111ab-->N111ab1
N111ab1-->N111ab11
N111ab-->N111ab2


usecase IsOpen as N111ba2
usecase Window as N111ba1
usecase IsOpen as N111ba11
N111ba-->N111ba1
N111ba1-->N111ba11
N111ba-->N111ba2

usecase IsOpen as N111bb2
usecase Window as N111bb1
usecase IsOpen as N111bb11
N111bb-->N111bb1
N111bb1-->N111bb11
N111bb-->N111bb2

@enduml
Binary file modified docs-gen/static/images/instance_tree.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs-gen/static/images/instance_tree_expand.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs-gen/static/images/instance_tree_expand_logical.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion spec/Body/Body.vspec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ Lights.DirectionIndicator:
##
Mirrors:
type: branch
instances: ["DriverSide", "PassengerSide"]
instances: ["DriverSide", "PassengerSide", "Left", "Right"]
description: All mirrors.
# Include mirrors specification and attach it to the Mirrors branch
#include ExteriorMirrors.vspec Mirrors
Expand Down
10 changes: 7 additions & 3 deletions spec/Cabin/Cabin.vspec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Door:
type: branch
instances:
- Row[1,2]
- ["DriverSide","PassengerSide"]
- ["DriverSide","PassengerSide", "Left", "Right"]
description: All doors, including windows and switches.
#include SingleDoor.vspec Door

Expand Down Expand Up @@ -146,7 +146,7 @@ Seat:
type: branch
instances:
- Row[1,2]
- ["DriverSide","Middle","PassengerSide"]
- ["DriverSide","Middle","PassengerSide", "Left", "Right"]
description: All seats.
#include SingleSeat.vspec Seat

Expand All @@ -158,7 +158,11 @@ DriverPosition:
type: attribute
allowed: ['LEFT', 'MIDDLE', 'RIGHT']
description: The position of the driver seat in row 1.
comment: Some signals use DriverSide and PassengerSide as instances. If this signal specifies that DriverPosition is LEFT or MIDDLE, then DriverSide refers to left side and PassengerSide to right side. If this signal specifies that DriverPosition is RIGHT, then DriverSide refers to right side and PassengerSide to left side.
comment: Some signals use DriverSide and PassengerSide as instances.
If this signal specifies that DriverPosition is LEFT or MIDDLE,
then DriverSide refers to left side and PassengerSide to right side.
If this signal specifies that DriverPosition is RIGHT,
then DriverSide refers to right side and PassengerSide to left side.

SeatRowCount:
datatype: uint8
Expand Down
4 changes: 2 additions & 2 deletions spec/Cabin/InteriorLights.vspec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Spotlight:
type: branch
instances:
- Row[1,4]
- ["DriverSide","PassengerSide"]
- ["DriverSide","PassengerSide", "Left", "Right"]
description: Spotlight for a specific area in the vehicle.
#include SingleConfigurableLight.vspec Spotlight

Expand All @@ -48,7 +48,7 @@ AmbientLight:
type: branch
instances:
- Row[1,2]
- ["DriverSide","PassengerSide"]
- ["DriverSide","PassengerSide", "Left", "Right"]
description: Decorative coloured light inside the cabin, usually mounted on the door, ceiling, etc.
#include SingleConfigurableLight.vspec AmbientLight

Expand Down
Loading