Use semantic names to describe values in the model

[jboynes]

Based on discussion in #112, this is a proposal to describe measurements using semantic names that provide more information about what is being measured than just the raw unit. I pushed a strawman as a starter for discussion.

The quantities file defines all SI base and derived quantities and their units. It then adds qualified measures (ones with . in the name) that indicates the usage of that unit. This provides an indication to a client on how a value should be presented. If a client does not have a definition for a qualified name, it can remove suffixes until it gets back to the unqualified SI types.

This avoids the need for a client to select a mapping based on individual keys, especially when multiple keys use the same data type (for example, the voltage for each phase in the AC supply). Instead the presentation can be based on the type of the data, ensuring consistency for all usages in the model.

When used with the meta property, this also provides enhanced type information for open content i.e. nodes added to the tree that are not formally defined by the schema (for example, from new sensors or online data sources).

I don't think this is ready to merge yet but would like feedback on the approach and on the qualifiers used. For example, I found SI's plane angle cumbersome but it does clearly distinguish from solid angle - for our application a simple angle might be sufficient.

[rob42]

I think this works for the display units, eg the display units defined with in .meta. So depth => length.depth => fathoms.

But the signalk keys themselves have an absolute unit type, in the case of depth its meters. So the submarines hypothetical navigation.position.depth would be provided in meters. If it included or was provided with a navigation.position.depth.meta with quantity: length.depth, it would then show as fathoms.

[jboynes]

@rob42 yes

I think it might be clear to separate the quantities into base units (which define the values that can appear in the model) and classified units which contain the additional information needed for display. Which isn't very clear in text so I'll up date the PR to show what I mean.

[tkurki]

While not totally DRY I think an easier way forward and easier from a user's standpoint would be to add a sibling property to all units in the schema named quantity. For example add "quantity": "distance" at https://github.com/SignalK/specification/blob/master/schemas/groups/navigation.json#L471 and "quantity": "depth" at https://github.com/SignalK/specification/blob/master/schemas/groups/environment.json#L137.

I know both quantity and unit is a bit superfluous, but I think both should be available independently in documentation and as part of meta via http.

The strawman linked above provides a great starting point. Anybody up for this? @bkp7 is this relevant to your application of SK?

[sumps]

[sumps]

A light hearted set of "Old English Sea Dog" Units would be:

Boatspeed - Knots Distance - Cables Temperature - Fahrenheit Wind Speed - Beaufort Depth - Fathoms Engine Pressure - What engine ? Altitude - always sea level Air Pressure - Rising or Falling

[rob42]

I wonder if we use the same structure as $source?, So SI units: "m", or "$units": "depth". That triggers a lookup to resources.units.depth which has SI unit m. That allows a very flexible way to map out preferences on a vessel by vessel basis. Works for other things too probably

[rob42]

Oh, and we could add regional static entries resources.units.en.nz.depth. Get internationalization for free, just load the regional branch structure?

[tkurki]

Updating this issue to say that for front end apps unit handling having the type of data /measurement available is a valid approach.

[bkp7]

Taking a step back we have the server (or servers, but considered the master/gateway server) and displays. The functionality required I think is:

• When installing a new display the gauges should have the same units/limits etc as other displays already installed.
• If connecting a new portable device to the ship it should also have the same units/limits etc as other displays (this is really the same as the first point)
• If someone comes on board with their own device with their own preferences setup (eg. charterer or pilot) their device should show gauges with ship limits but their own preferred units as set on their device.

The above is I believe at least part of the objective of the meta section.

I would suggest that in the meta section an additional property be added being displayUnits.

The discussion above about linking preferred units to measurement types seems to me an implementation issue for the server rather than a messaging issue (for SignalK). The actual way the preferred units are stored/implemented is down to the server designer, as long as the meta for each gauge has the capability to include that preferred displayUnit data.

If this approach is taken there needs to be consistency in identifying non SI units and to that end I would suggest an additional definition of displayUnits: `

"displayUnits": {
  "type": "string",
  "description": "Allowed units of physical quantities used for display purposes. Units can be SI or non SI.",
  "properties": {
    "m": {
      "display": "m",
      "siUnit": "m",
      "description": "meter"
    },
    "Nm": {
      "display": "Nm",
      "siUnit": "m",
      "description": "Nautical Mile, 1852 meters"
    },
    "ft": {
      "display": "ft",
      "siUnit": "m",
      "description": "Foot, 0.3048 meters"
    }
}

`

As things stand the user needs to set display units up on each display they install which can be very onerous, hence this proposal.