RFC 0010: Actions (#442) is proposing a way to put/write values to a Signal K server, primarily to allow the setting of target values, for example a target heading for an autopilot. This is a welcome addition to Signal K and will result in a demand for new Target Keys in the Schema.
This RFC seeks opinion as to how and where these new target values should be placed in the schema, so that when they are added it is done in a consistent and predictable way.
New uses
New targets will be needed in a number of areas eg.:
environmental: target temperature or humidity, in a zone.
tanks:
temperature eg. livewell
level eg. transfer to day tanks, polished fuel, water maker, ballast etc.
design: keel angle/lift
etc
Existing Targets in the Schema
I have found 3 places in the schema where target values have already been included. These relate to Autopilot, Rudder and Battery Charger and they are each implemented differently.
The locations for the Autopilot/heading target are:
We also need to consider \$sources as not only can each measurement have a number of values but each target could have a number of values from differing sources too.
Tricky scenarios
We need to design the schema so that it doesn't break in non trivial installations. eg. a yacht fitted with both Aircon and Heating systems, or one fitted with 2 autopilots.
Where is the target value stored?
The authoritative storage place for the target value in the Signal K network will be at a Signal K server, either the gateway server which is connected to a non Signal K controlling device (eg. Autopilot) or a Signal K server which is itself the controlling device. In either case that server will be the \$source of the target value.
What are the user requirements?
If a user can set a target value for something they would ideally want to see that target value depicted as a 'bug' on the same instrument that displays the underlying value. eg. looking at a temperature display for a cabin they would want to see both the current temperature and the set temperature.
There is no reason, that the 'bug' should not be displayed even when it is inactive. It would be up to the particular display design to decide how to differentiate between an active and inactive bug perhaps by colour (eg. Magenta/Green), or bug design (outline/solid). Display design is not our concern here.
The typical use case for an active bug is so that it can be set before engaging the controlling device eg. set the required heading, then engage the autopilot in heading mode at which point the bug changes colour/presentation.
But what if there are 2 controlling devices (2 autopilots or both aircon and heating)? What must not happen is that the bug for the inactive device is displayed whilst the active device targets a different value not shown to the end user. We should design the schema to help ensure this does not happen.
Proposal
I propose that target be defined as an object value containing both the target value itself and a flag to indicate whether that particular target value is currently being targeted.
eg.
"value": {
"setPoint": 294.5,
"active": true
}
This proposal will ensure that the display device can identify active target values even if there is more than 1 controlling device in the system.
Where to locate the target value in the Schema?
The 3 uses of target value currently in the schema use different approaches, so to get consistency at least 2 of them need to be changed. The current locations are:
(per Autopilot) the target values are located within the schema in the same place as the control device.
Advantages:
any?
Disadvantages:
any display device will require a separate map in order to locate the controlling device(s) for a particular value. eg. if displaying environment.inside.aftCabin.temperature.value it would somehow need to know to look at either eg. electrical.consumers.aircon.target.aftCabin.temperature.value or electrical.consumers.heaters.target.aftCabin.temperature.value (or something similar as consumers haven't been defined yet)
(per Rudder) the target value is on the same branch as the value with "target" postpended to its name:
Advantages:
provided the naming is strictly followed a display device will know where to find associated target values with multiple sources (if applicable) held in the "values" property
Disadvantages:
the display device will need to specifically ask for (or subscribe to) the target value where one is present.
(per Battery Charger) the target value is on the same branch as the value with "setPoint" prepended to the name and the next letter capitalised. This is very similar to 2. but with the additional disadvantage of Capitalising the first letter of the property when prepending "setPoint".
(an alternative) the target value(s) are provided within the same leaf as the underlying value. ie:
the target value is presented with the underlying value making reading the target very easy for display devices.
the location of the target value is completely predictable. ie having decided on a suitable location in the schema for a particular value any associated target value will be in the same place.
only one subscription is required to obtain all information required to display a value.
Disadvantages:
any?
Whatever approach is decided upon, in order to achieve consistency at least 2 of the existing target locations should be moved in the schema. At present there are no Signal K implementations setting targets, so it seems to me timely to make a positive decision about the way forward before 'put' functionality is published.
Introduction
RFC 0010: Actions (#442) is proposing a way to put/write values to a Signal K server, primarily to allow the setting of target values, for example a target heading for an autopilot. This is a welcome addition to Signal K and will result in a demand for new Target Keys in the Schema.
This RFC seeks opinion as to how and where these new target values should be placed in the schema, so that when they are added it is done in a consistent and predictable way.
New uses
New targets will be needed in a number of areas eg.:
Existing Targets in the Schema
I have found 3 places in the schema where target values have already been included. These relate to Autopilot, Rudder and Battery Charger and they are each implemented differently.
The locations for the Autopilot/heading target are:
navigation/headingTrue/value
steering/autopilot/target/headingTrue/valuefor rudder:
steering/rudderAngle/value
steering/rudderAngleTarget/valueand battery charger:
electrical/chargers/charger1/voltage/value
electrical/chargers/charger1/setPointVoltage/valueWe also need to consider \$sources as not only can each measurement have a number of values but each target could have a number of values from differing sources too.
Tricky scenarios
We need to design the schema so that it doesn't break in non trivial installations. eg. a yacht fitted with both Aircon and Heating systems, or one fitted with 2 autopilots.
Where is the target value stored?
The authoritative storage place for the target value in the Signal K network will be at a Signal K server, either the gateway server which is connected to a non Signal K controlling device (eg. Autopilot) or a Signal K server which is itself the controlling device. In either case that server will be the \$source of the target value.
What are the user requirements?
If a user can set a target value for something they would ideally want to see that target value depicted as a 'bug' on the same instrument that displays the underlying value. eg. looking at a temperature display for a cabin they would want to see both the current temperature and the set temperature.
There is no reason, that the 'bug' should not be displayed even when it is inactive. It would be up to the particular display design to decide how to differentiate between an active and inactive bug perhaps by colour (eg. Magenta/Green), or bug design (outline/solid). Display design is not our concern here.
The typical use case for an active bug is so that it can be set before engaging the controlling device eg. set the required heading, then engage the autopilot in heading mode at which point the bug changes colour/presentation.
But what if there are 2 controlling devices (2 autopilots or both aircon and heating)? What must not happen is that the bug for the inactive device is displayed whilst the active device targets a different value not shown to the end user. We should design the schema to help ensure this does not happen.
Proposal
I propose that target be defined as an object value containing both the target value itself and a flag to indicate whether that particular target value is currently being targeted.
eg.
This proposal will ensure that the display device can identify active target values even if there is more than 1 controlling device in the system.
Where to locate the target value in the Schema?
The 3 uses of target value currently in the schema use different approaches, so to get consistency at least 2 of them need to be changed. The current locations are:
(per Autopilot) the target values are located within the schema in the same place as the control device.
Advantages:
Disadvantages:
environment.inside.aftCabin.temperature.valueit would somehow need to know to look at either eg.electrical.consumers.aircon.target.aftCabin.temperature.valueorelectrical.consumers.heaters.target.aftCabin.temperature.value(or something similar as consumers haven't been defined yet)(per Rudder) the target value is on the same branch as the value with "target" postpended to its name:
Advantages:
Disadvantages:
(per Battery Charger) the target value is on the same branch as the value with "setPoint" prepended to the name and the next letter capitalised. This is very similar to 2. but with the additional disadvantage of Capitalising the first letter of the property when prepending "setPoint".
(an alternative) the target value(s) are provided within the same leaf as the underlying value. ie:
environment/inside/mainCabin/temperature/value
environment/inside/mainCabin/temperature/targetAdvantages:
Disadvantages:
Whatever approach is decided upon, in order to achieve consistency at least 2 of the existing target locations should be moved in the schema. At present there are no Signal K implementations setting targets, so it seems to me timely to make a positive decision about the way forward before 'put' functionality is published.