Skip to content

Latest commit

 

History

History
37 lines (27 loc) · 2.53 KB

REFERENCE.md

File metadata and controls

37 lines (27 loc) · 2.53 KB
Raw

Basic principles

Signal K is a data model, and protocol for data sharing. The internal implementation of Signal K in a device is the developers own choice, and need not follow the Signal K model structure, but the external messages must to ensure interoperability.

Adding to the Signal K schema

  • keys are globally unique.
  • a key always has the same statically defined units. These are the appropriate SI units.
  • key names are camelCase, with lowercase first letter, java style.
  • key names follow a 'more generic>>more specific' model. Hence a key name will be 'bearingActualTrue', rather than trueActualBearing. This allows bearing* or bearingActual*, and better sorting and IDE integration.
  • if there are many bearing* variants, bearing* should become an object tree, eg bearing.actualTrue, for a cleaner model
  • by default keys are optional. Very few keys are required, those are mainly in the topmost structures.
  • adding your own custom keys is acceptable, but unless you publish them here, only you will be able to use them.
  • favour the use of objects over arrays.

Using the Signal K model

  • all data is UTF-8
  • the model is designed so that any incoming message can simply be merged into the currently held model since all keys are unique.
  • each message must start from the root element, but need only contain the keys of interest. eg a given message will be a filtered partial copy of the whole model. It may contain one key, or a whole branch of keys.
  • if a device receives an unknown key it can be ignored by that device.
  • each device may hold a full(eg server) or partial(eg autopilot) copy of the model, or may simply transmit its specific keys. eg(depth).
  • any changes made locally (to a devices local model) need to be transmitted to other interested devices, so that their copies of the model remain synchronised.

Security

Signal K does not define or apply security. Security is the responsibility of the implementation. Developers should be aware that a Signal K implementation may be accessible from the internet, and consider the effect sending misc messages into the system from an external source may have. At a minimum you should:

  • not update your localBoat's critical navigational model with arbitrary data from outside of your vessel, eg on the internet. Trust your own instruments first!
  • you should filter the information you allow onto the internet.
  • you should consider if an external source is trustworthy before relying on their data (eg a waypoint list)