Commit 2369599e authored by Luis Araujo's avatar Luis Araujo

Update the Sensors and Actuators document

This commit updates the sensors and actuators document with a new
section describing the current state of the vehicle SDK API and
describing the required changes to align this API with the latest
W3C specifications.
Signed-off-by: Luis Araujo's avatarLuis Araujo <luis.araujo@collabora.co.uk>
parent 3fff8285
......@@ -1987,6 +1987,111 @@ As discussed in the above sections, we recommend:
new properties or device types to be supported by the vehicle device
daemon’s API.
# Sensors and Actuators API
This sections aims to compare the current status of the Vehicle device daemon for
the sensors and actuators SDK API ([Rhosydd]) with the latest W3C specifications:
the [Vehicle Information Service Specification] API and the
[Vehicle Signal Specification] data model.
It will also explain the required changes to align [Rhosydd] to the new W3C
specifications.
## Rhosydd API Current State
The current [Rhosydd API] is stable and usable implementing the
[Vehicle Information Access API] and using the data model specified by the
[Vehicle Data Specification].
Nevetherless, it is no longer strictly aligned with the W3C API since the W3C
working group chose to write two different specifications rather than extending the
existing one. Rhosydd would need a moderate refactoring in order to support the new
[Vehicle Information Service Specification] API and the new data model of the
[Vehicle Signal Specification].
## Considerations to align Rhosydd to the new VISS API
1) The original Vehicle API and the Rhosydd API don't exactly match 1:1 as the
latter has been adapted to follow the inter-process D-Bus constraints and
best-practice, which are somewhat different than the ones for a in-process
JavaScript API.
2) The new VISS API and its data model is largely different than the original
Vehicle API and data model upon which Rhosydd is based.
## New vs Old Specification
1) Rhosydd follows the [Vehicle Data specification] data model using attributes
(data) and interface objects, where VISS uses the [Vehicle Signal Specification]
data model which is based on a signal tree structure containing different
entities types (branches, rbranches, signals, attributes, and elements).
2) The [Vehicle Information Service Specification] API objects are defined as JSON
objects that will be passed between the client and the VIS Server, where Rhosydd
is currently based on accessing attributes values using interface objects.
3) VISS defines a set of **Request Objects** and **Response Objects** (defined as
JSON schemas), where the client must pass request messages to the server and
they should be any of the defined request objects, in the same way, the message
returned by the server must be one of the defined response objects.
4) The request and response parameters contain a number of attributes, among them
the Action attribute which specify the type of action requested by the client
or delivered by the server.
5) VISS lists well defined actions for client requests: authorize, getMetadata,
get, set, subscribe, subscription, unsubscribe, unsubscribeAll.
6) The [Vehicle Signal Specification] introduces the concept of **signals**. They
are just named entities with a producer (or publisher) that can change its
value over time and have a type and optionally a unit type defined.
7) The [Vehicle Signal Specification] data model introduces a signal specification
format. This specification is a YAML list in a single file called **vspec**
file. This file can also be generated in other formats (JSON, FrancaIDL), and
basically defines the signal and data structure tree.
8) The Vehicle Signal Specification introduces the concept of signal ID databases.
These are generated from the vspec files, and they basically map signal names to
ID's that can be used for easy indexing of signals without the need of providing
the entire qualified signal name.
## Rhosydd Required Changes
- The [Vehicle Information Service Specification] API defines the Request and
Response Objects using a JSON schema format. The [Rhosydd API] (both the
application-facing and backend-facing ones) need to be updated to provide a
similar API based on idiomatic DBus methods and types.
- Map the different VISS Server actions to handle client requests to their
respective DBus methods in Rhosydd.
- The internal Rhosydd data model needs to be updated to support all the element
types defined in the [Vehicle Signal Specification].
- It might also be required to add support to process signal ID databases in order
for Rhosydd to recognize signals specified by the Vehicle Signal Specification.
## Advantages
- The new VISS spec is based on a WebSocket API, and it resembles more closely the
inter-process mechanism based on D-Bus in Rhosydd rather than the previous
JavaScript in-process mechanism defined by the previous specification.
## Conclusion
The main effort will be about updating the internal Rhosydd data model to reflect
the changes introduced in the [Vehicle Signal Specification] data model, with the
extended types and metadata.
The DBus APIs, both on the application and backend sides, will need to be updated
to map to the new data model. From a high-level point of view the old and new APIs
are relatively similar, but a non-trivial amount of changes is expected to map the
new concepts and to align to the new terminology.
The [Rhosydd] client APIs for applications (librhosydd) and backends (libcroesor)
will need to be updated to reflect the changes in the underlying DBus APIs.
## Appendix: W3C API
For the purposes of completeness, the [W3C Vehicle Information Access
......@@ -2078,6 +2183,14 @@ enum Availability {
};
```
[Rhosydd]: https://docs.apertis.org/rhosydd/index.html
[Rhosydd API]: https://docs.apertis.org/rhosydd/index.html
[Vehicle Information Service Specification]: https://www.w3.org/TR/vehicle-information-service/
[Vehicle Signal Specification]: https://github.com/GENIVI/vehicle_signal_specification
[Vehicle Information Access API]: http://www.w3.org/2014/automotive/vehicle_spec.html
[Vehicle Data specification]: http://www.w3.org/2014/automotive/data_spec.html
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment