Commit 7a2e62ca authored by Emanuele Aina's avatar Emanuele Aina

sensors: Update to the actual Rhosydd API

Match the API description to the API that has been implemented in Rhosydd.
Signed-off-by: Emanuele Aina's avatarEmanuele Aina <emanuele.aina@collabora.com>
parent 30c8edca
......@@ -1040,76 +1040,62 @@ Types are given in the [D-Bus type system notation].
##### Management API
Exposed on the well-known name org.apertis.VehicleData1, the
/org/apertis/VehicleData1 object must implement both of the following
interfaces.
Exposed on the well-known name `org.apertis.Rhosydd1` from the main daemon,
the `/org/apertis/Rhosydd1` object implements the standard
[`org.freedesktop.DBus.ObjectManager`][D-Bus ObjectManager]
interface to let client discover and get notified about the registered vehicles.
The org.apertis.VehicleManager1 interface is called by backend services
to register or deregister the org.apertis.Vehicle1 D-Bus objects they
expose.
The org.apertis.VehicleZoneManager1 interface is called by backend
services to manage zones within the vehicle.
Vehicles are mapped under `/org/apertis/Rhosydd1/${vehicle_id}` and implement
the `org.apertis.Rhosydd1.Vehicle` interface:
```
interface org.apertis.VehicleManager1 {
/* Each parameter is a list of object paths for the objects being
* added or removed. */
method UpdateVehicleObjects (in ao added, in ao removed)
}
interface org.apertis.VehicleZoneManager1 {
method RegisterZone (in s vehicle_id,
in u parent_zone_id,
in as tags,
out u zone_id)
method DeregisterZone (in s vehicle_id, in u zone_id)
method GetZones (in s vehicle_id,
in u parent_zone_id,
in as tags,
out a(uasu) zones)
interface org.apertis.Rhosydd1.Vehicle {
readonly property s VehicleId;
readonly property as Zones;
method GetAttribute(
in s zone_path,
in s attribute_name,
out x current_time,
out (vdx) value,
out (uu) metadata)
method GetAttributeMetadata (
in s zone_path,
in s attribute_name,
out x current_time,
out (uu) metadata)
method GetAllAttributes (
in s zone_path,
out x current_time,
out a(ss(vdx)(uu)) attributes)
method GetAllAttributesMetadata (
in s zone_path,
out x current_time,
out a(ss(uu)) attributes_metadata)
method SetAttribute (
in s zone_path,
in s attribute_name,
in v value)
method UpdateSubscriptions (
in a(ssa{sv}) subscriptions,
in a(ssa{sv}) unsubscriptions)
signal AttributesChanged (
x current_time,
a(ss(vdx)(uu)) changed_attributes,
a(ss(uu)) invalidated_attributes))
signal AttributesMetadataChanged (
x current_time,
a(ss(uu)) changed_attributes_metadata)
}
```
When handling a call to UpdateVehicleObjects, the vehicle device daemon
must check that each of the objects being added is on the same D-Bus
connection as is making the UpdateVehicleObjects call. (i.e. One backend
service cannot register another backend service’s objects.)
The zone API provides a way of building an abstract map of the layout of
a vehicle, in terms of a hierarchy of tagged zones. Each zone has an
integer identifier (its zone ID), a parent zone, and a (potentially
empty) list of tags to differentiate it from its siblings. There is
always a root zone (ID 0, no tags) which represents the entire vehicle.
Each tree of zones is unique to a particular vehicle. Each zone is
uniquely identified within this tree by its ID, or by the combination of
its parent ID and tag list. Consequently, no two siblings may have the
same tag list. However, they may share entries in their tag lists, which
allows ‘overlapping’ areas in the vehicle to be represented.
A call to RegisterZone with the parent ID and tag list of an
already-existing zone will return the existing zone’s ID and increment a
reference counter in the zone’s private state so that a zone will only
be removed on the last of a series of paired calls to DeregisterZone.
GetZones returns an array of zones (each represented as a tuple of their
parent ID, tag list, and ID) which are immediately below the given
parent zone ID and which contain all of the given tags in their tag
lists. All the descendants of these zones will also be returned.
##### Property API
The property API is implemented by each backend service, which must
expose a separate D-Bus object for each vehicle they wish to output
properties for. Each of these objects must implement the
org.apertis.Vehicle1 interface.
This interface is similar to the standard
[org.freedesktop.DBus.Properties] interface, with the difference
that each property is identified by a zone ID (relative to the vehicle
identified in VehicleId) and a property name, rather than a D-Bus
interface name and a property name. Property names come from the Vehicle
Data specification, for example:
Backends register themselves on the bus with well-known names under the
`org.apertis.Rhosydd1.Backends.` prefix and implement the same interfaces and
the main daemon, which will monitor the owned names on the bus and register
to the object manager signals to multiplex access to the backends.
Each attribute managed via the vehicle attribute API is identified by a zone ID
(relative to the vehicle identified in VehicleId) and a property name.
Property names come from the Vehicle Data specification, for example:
- [drivingMode.mode]
......@@ -1117,40 +1103,41 @@ Data specification, for example:
- com.myoem.fancySeatController.backTemperature (see section 8.9)
Additionally, each property has four values: its value (of type v); its
accuracy (of the same type v); the timestamp when it was last updated
(of type x); and its most specific zone ID (of type u).
Each attribute has three values associated:
* its value (of type v)
* its accuracy (as a standard deviation of type d, set to `0.0` for non-numeric values)
* the timestamp when it was last updated (of type x)
In addition the current time is also returned for comparison to the time the value was last updated.
Values also have two set of metadata (of type u) associated:
* availability enum
* AVAILABLE = 1
* NOT_SUPPORTED = 0
* NOT_SUPPORTED_YET = 2
* NOT_SUPPORTED_SECURITY_POLICY = 3
* NOT_SUPPORTED_BUSINESS_POLICY = 4
* NOT_SUPPORTED_OTHER = 5
* access flags
* NONE = 0
* READABLE = (1 << 0)
* WRITABLE = (1 << 1)
```
interface org.apertis.Vehicle1 {
readonly property s VehicleId;
method Get (in u zone_id, in s property_name, out (vvx) value)
method Set (in u zone_id, in s property_name, in v value)
method GetAll (in u zone_id, out a(usvvx) properties)
signal PropertiesChanged (u zone_id,
a(usvvx) changed_properties,
a(us) invalidated_properties)
}
```
The Get method must return the value of the given property in exactly
The GetAttribute method must return the value of the given property in exactly
the given zone. If no such property exists in that zone, it must return
an error.
In contrast, the GetAll method must return all properties in the given
In contrast, the GetAllAttributes method must return all properties in the given
zone and all zones beneath. So the same property name may be returned in
multiple entries (with a different zone ID each time).
Similarly, the PropertiesChanged signal may be emitted for changes to
properties in zones beneath the indicated one. Each property change is
accompanied by the zone ID and name of the property, plus its new value,
accuracy and timestamp. As with the
org.freedesktop.DBus.Properties.PropertiesChanged signal, properties may
be ‘invalidated’ to indicate that they have changed without providing
their new value. In this case only the zone ID and name of the property
is provided.
To receive notification of attribute changes via the AttributesChanged and
AttributesMetadataChanged signals, clients must first register their
subscription with the UpdateSubscriptions method to specify the kind of
properties for which they have some interest.
A backend service must emit a PropertiesChanged signal when one of the
A backend service must emit an AttributesChanged signal when one of the
properties it exposes changes, but it may wait to combine that signal
with those from other changed properties — the trade-off between latency
and notification frequency should be determined by backend service
......
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