Terminology

Roles / components in relation to VSS

User

A VSS user is a client that uses VSS signals (as described by the VSS & VISS standards).

This includes:

• Reading signals (any signal type)
• Subscribing to signals (any signal type)
• Setting / actuating signals (only for actuator type signals)

In order to avoid confusion around what "setting" a signal means, it can be disambiguated by referring to it as "actuating a signal".

This disambiguation is mostly necessary in contexts where providing a VSS signal is also possible / referred to, but in order to be consistent across the board it can be used everywhere.

How it maps to access rights

Access right	Needed by
read	A client that needs to read and / or subscribe to a signal
actuate	A client that needs to actuate a signal

Provider

A VSS provider is a client that provides VSS signals.

This includes:

• Providing a signal value (for any signal type)
• Providing the actuation (only for actuator type signals)

When there is a need to disambiguate between providers who only provides signal values and providers that only provides the actuation part, these can be referred to as:

• Actuation provider
• Data provider (or Value provider)

How it maps to access rights

Access right	Needed by
provide	A client that needs to provide a VSS signal. This includes both provide:value and provide:actuation
provide:value	A client that needs to provide the value of a VSS signal
provide:actuation	A client that needs to provide the actuation of a VSS signal

Note:
Currently, provide:actuation would simply map to read in terms of access rights needed. The main point of having it, is that it clearly denotes the intent of the access right, which is a prerequisite for being able to map it to the required access rights along with the evolution of the implementation.

Vehicle Signal Specification

Signal

This is the signal in the Vehicle Signal Specification. It's used as an overarching term to refer to the entity identified by a dot-separated string in VSS, i.e. Vehicle.Speed.

A signal can be of different types, for example an Actuator, Sensor or Attribute. The signal will have certain properties associated with it, for example the data type of its value. This is specified in the VSS entry for the signal.

Entry

A VSS entry is an entry in a VSS specification. The entry specifies all the properties of a VSS signal, or put another way, the the metadata of the signal.

A VSS entry will specify the signal type, data type (of the signal values), unit, etc of the signal. The VSS entry can be assembled from multiple input sources and can be generated from templates specified in the .vspec files.

A VSS entry will not contain the value of the signal, as that is something only available at runtime (i.e. something that can be retrieved through an API).

Value

A VSS value is the value of a signal. The data type of the value must match the data type specified in the VSS entry for the signal.

Datapoint

A datapoint is the value of a signal at a specific time (i.e. value + timestamp). This can generally be retrieved through the various API:s used with VSS, i.e. VISS.

Discussion

Feeder vs Provider

Excerpts from chat (5th December):

Let's start with the term feeder. The directionality of the word immediately becomes an issue when trying to apply it to the things we want to have names for in our software.

Feeder
It's feeding something.

To give a common example, you can feed a child or you can feed an animal. If it's your job, then you are an animal feeder. In our case, the feeders are only ever feeding kuksa-val-server or databroker, i.e. they are kuksa.val feeders. So far so good.

So how are we naming things now then? We have a CAN feeder and a GPS feeder. Sounds like something that is feeding CAN and another thing feeding a GPS, i.e. CAN and GPS is the destination.

The same logic applies to a sensor feeder or actuator feeder. It's conveying the wrong direction. And this becomes even more evident when we are actually "feeding" stuff for example in the CAN direction.

So let's compare it to a provider.

Provider
It's providing something.

It can provide us with

• Actuator(s)
• Sensor(s)
• Attribute(s)

It would also make perfect sense for an actuator provider to provide us with a way to actuate it. And it would be equally logical that it would provide use with readings of it's current value (i.e. acting as a sensor provider basically).

Furthermore, it also makes sense to have:

• SOME/IP provider
• CAN provider
• LIN provider

since they are providing us with gateways into these protocols.

They can themselves also act as (VSS) actuator providers and (VSS) sensor providers.

Provider just seems like the the right thing to use.

--

But terminology matters. It will be reflected throughout the software we write and the APIs we create. Confusing terminology leads to confusing software and confusing APIs.

If we get the terminology right, a lot of things will naturally just fall into place. And I think using "providers" or "signal providers" in terms of the VSS model and kuksa.val is one of those cases.

Using terminology like:

• Provider
  A provider is providing a signal (sensor, attribute or actuator) to the VSS tree.
  A provider can also use signals as any other user.

• User
  A user (or client) is using the signals in the VSS tree (without providing any of them itself).

instead of, for example:

• Northbound App
• Southbound Feeder
• Southbound Service

will make it a lot easier to reason about our software and explain it to others.