I can convert from SI units to any popular unit. I can not implement and maintain a signalK database at each client just to know what the measurement unit is.

vessel.environment.depth has 5 properties: belowKeel, belowTransducer, belowSurface, surfaceToTransducer, and transducerToKeel.

2 of these are calculated values.

I would expect that, as a skipper, I have to tell the system my surfaceToTransducer distance and my transducerToKeel distance. The transducer will produce the belowTransducer value, and clients will calculate belowKeel and belowSurface only if they want it. The argument could also be made that surfaceToTransducer and transducerToKeel are calculated.

The issue I see with having all 5 values in the spec is that there is a possibility for a conflict of truth.

Tangential thought: I imagine surfaceToTransducer and transducerToKeel will be set once and then forgotten. Does it make sense to have them in the environment, or are the better suited in the design? The latter seems more appropriate to me.

Thoughts?

We have to be careful that consumers (even simple ones) handle data time outs correctly, otherwise a user could be happily thinking that the readings are OK, when in fact a sensor sending the data had failed five minutes ago.

I would like to propose that every sensor data value has a time out value (in seconds) that is set by the gateway or server. Then the consumer can receive this time out value and know when they should time out the data and make some indication of the time out to the user.

"For the most part, we're using SI units for values (meters, seconds, etc.), but angles are represented as degrees in the spec. I think we ought to change this to radians.

[23:39] tim: n2k uses radians and most math library functions which operate on angles also use radians. So right now, we get an angle over n2k in radians, convert it to degrees, then if any math has to be done, we convert back to radians, do the math, then convert back to degrees again.

[23:39] tim: Wouldn't it be simpler and more consistent if we specified radians on the wire and only convert to degrees at the display?"

Add a navigation.lights enum that allows the nav lights status to be set. The options added dont cover all types and sizes of vessels, they assume that the state is correct for the current vessel, eg if the vessel is 6M the motoring lights will be different than a vessel of 14M, but both will be motoring

When we used raw mmsi and self-assigned alphanumeric ids as keys in the vessels array the context in delta was in a format like vessels.12345679, with period as the delimiter, denoting path in the full tree.

Now with more structured identities (uuid, mmsi, url) period as the delimiter is not sufficient, as urls typically contain periods.

I suggest the following

• The branch(the main branch from the root) and the identity of the vessel/other entity are explicitly in separate fields as below.

{
  "branch": "vessels",
  "id": "urn:mrn:imo:mmsi:230099999",
  "updates": [...]
}

• All self delta messages must omit the context, making it possible to distinguish selfmessages by the absence of identity. Saves a few bytes also.
• For non-self messages vessels is the default and should be omitted

This should clear up the delimiter issue, save a few bytes and make things explicit. All paths in the delta message are rooted at the two part path formed by branch and identity from the root.

Comments?

signalk.json specifies that a self property is required and holds the key for "this vessel." What should this refer to if the server is not running on a vessel or applies to several vessels?

For example, consider a SignalK server running in the head office of a company with a fleet, or in the charter base of a charter fleet. Would that server be allocated/invent a URL or UUID and have no or an empty vessel entry?

Should we simply make self optional?

The current spec doesn't include a good place for metadata about data sources, such as N2K devices on the network, 0183-enabled devices, other SK devices, DIY devices (e.g. arduinos) etc. At the moment, there is a "sensor" group which doesn't fit this need at all.

This new place (e.g. a group called sources) should hold device metadata from various N2K PGNs, 0183 sentences (a list will follow) and retrieved from a SK-enabled device via the REST API or web socket. At least the type of device, identity information, capabilities and how to connect to/reach the device should be included.

Possible other properties are the various other fields defined in the PGNs/sentences, priority/weight, user defined information (friendly label, for instance), placement on the vessel (in case of GPS devices, depth transducers), etc.

Track the implementation of the delta format.

https://groups.google.com/forum/#!topic/signalk/zIdHtETUPEw

We should have a place for the common ships data like country of reg, reg number, etc

To support Performance data like polar/target speed or gybe and tack angles, a new json specification has to be defined.

Hi @SignalK/owners & @SignalK/contributors,

I've set up a branch called separated-schemas, which is my first attempt at separating everything. I've also taken out some stuff like ID's in every object (now they're just in the main schema in each file), 'required' (unless it's required) and such. It seemed from the schema spec that they're not necessary, but they can easily be added in later should they be required. For now, it makes everything a bit more readable.

I've made extensive use of $ref, check REFERENCE.md for a structure. I'm not yet fully sure about wether I used it correctly though, and I'm quite sure that it'll take a couple of updates before I've got that right. When that is done, we'll see if we can get docson to work with them.

In the file TODO.md is a todo list with stuff I still need to do. I propose this rough structure:

• I'll finish up the separation
• We'll check if the use of $refs is correct (any help is appreciated, I'll set up a new threat in the mailing list)
• Once the Schema's are correct, double checked and merged back into master, it'll be a lot easier to make changes.

Enums have various formats throughout the spec. For example, waypoint.type is all lower case while navigation.state.value starts with a upper case letter. What is the casing style that is preferred? I'd like to submit a PR with the appropriate changes.

As discussed on Slack and the mailing list, the specification as it stands right now doesn't support all PGNs and sentences we should support in v1. This GH issue is an attempt to collect and list all PGNs + sentences - both supported and unsupported. Supported messages will be crossed off.

How this will work: below is an (initial) list of 0183 sentences and PGNs, based on the list of PGNs decoded by canboat and the 0183 sentences documentation from various online sources. This list is by no means complete. Please post additions to the list in the comments, I'll add them to the list in the OP.

Note: I haven't yet crossed off any PGN and sentence, please provide input on which are supported and which are not, as well as on which PGNs or sentences should not be supported at all.

navigation.current includes source and timestamp fields for each component (drift, setTrue and setMagnetic), but since these values are only meaningful together and always updated together, timestamp and source should be removed from each component and added to current directly

"current": {
  "timestamp": {"$ref": "../defintions.json#/definitions/timestamp"},
  "source": {"$ref": "../definitions.json#/definitions/source"},
  "drift": {
    "type": "number",
    "description": "The speed component of the water current vector in m/s",
    "example": 3.12
  },
  "setTrue": {
    "type": "number",
    "description": "The direction component of the water current vector in decimal degrees referenced to true (geographic) north",
    "example": 123.45
  },
  "setMagnetic": {
    "type": "number",
    "description": "The direction component of the water current vector in decimal degrees referenced to magnetic north",
    "example": 131.22
  }
}

Since there have been a lot of changes to the groups, vessel.json needs checking. It probably needs updating.

Intro

The vessels object at the root of the Signal K object is a key-value store holding information for 1 or more boats. We need to determine exactly what this key should be and what requirements it must fulfill.

This issue is intended to discuss that. Please keep in mind that this is not the same as the identifier for other Signal K hosts on a network (e.g. on a boat with multiple Signal K sources). This is for identifying a single vessel which may be a collection of one or more Signal K devices.

Background

We were originally going to use MMSIs as the unique identifier, but that won't work for a variety of reasons, not the least of which is not everyone has one. MAC address of the SK server device was floated as an option, but that changes whenever the hardware does, so it may not be a good option either. In fact, a boat may have more than one SK gateway and we need to keep the ID the same across devices.

Requirements

• Globally unique
• Easily reproducible
• Portable across devices
• No central agency required to assign them
• Do all of this and protect end users' privacy

These are what I believe the requirements to be. I would like to use this discussion to firstly agree on a set of requirements, vetted against as many use cases as possible, and then float options which satisfy these requirements so that we can agree on something.

Use Cases

• Route sharing
• Fleet management (races, cruising rallies, etc.)
• Crowd sourced marine survey data
• Automated log keeping

In the various discussions that have taken place concerning UUIDs, MMSI, etc. it has highlighted again that in a more complex Signal K network, we could have multiple servers, gateways and sophisticated consumers but no method of synchronising important "Self" Configuration Settings, Meta Data and the UUID.

As it stands at the moment, all of this data would have to be entered in each device, with the possibility of wrong or different values being entered.

I propose that there is a need for a simple method or allocating one device to be the "master" network device and that this device once configured will announce its presence on the network via Bonjour/mDNS as being the master device and all other devices must (if they need it) request the "Self" Configuration Settings, Meta Data and UUID from the "master" and maintain a local record of this data and check it (re-sync) each time they power up and join the network. Slave devices should also maintain a record of who the "master" device is.

Should a device that is set to be a "master" power up and Discover that another "master" already exists on the network or a "slave" powers up and finds that a new "master" now exists on the network, then it should alarm/warn the user that an installation change has occurred and needs to be checked.

If a slave powers up and finds the "master" is not currently present, then it should be able to carry out its normal activity without the need of the "master" using its local record of the "masters" config, meta and UUID data.

An exact definition of what a "Master" device is responsible for needs to be agreed, a format/method for the "Master" to announce its presence via Bonjour/mDNS and further study of the use cases that could occur in a complex network (such as two masters, a new master, etc.) and how these are handled.

Comments please.

My understanding is that a vessel will only have one Call Sign and yet in the Communication Object there are two call sign fields...

• callsignDsc string
• callsignVhf string

Can we have just one call sign for VHF (DSC or non-DSC) but add an IMO number field, so that IMO vessels are supported in Signal K.

roll, pitch and yaw should be grouped together under navigation.attitude and get a single timestamp and source value.

Implement AIS support so that the data sent in AIS messages is available as part of the SignalK model.

AIS information is about other vessels - this means that the context is vessels.MMSI. Both the server and the clients must be able to handle this information a bit differently from self-related messages.

We currently advertise the signalk services via mdns in both the java and node servers, and reference the idea in http://signalk.org/developers/apis_and_conventions.html, but we have no formal service name and message content written yet.

So as a starting point the java server advertises:

Service Type: _signalk-http._tcp
Service Name: signalk-http 
Domain Name: local
Interface: wlan0 IPv4
Address: 10-1-1-64.local/10.1.1.64:8080
TXT vessel_uuid = urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d
TXT server = signalk-server
TXT version = 0.1
TXT vessel_mmsi = 123456789
TXT path = /signalk/v1/api
TXT vessel_name = motu

Service Type: _signalk-ws._tcp
Service Name: signalk-ws
Domain Name: local
Interface: wlan0 IPv4
Address: 10-1-1-64.local/10.1.1.64:3000
TXT vessel_uuid = urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d
TXT server = signalk-server
TXT version = 0.1
TXT vessel_mmsi = 123456789
TXT path = /signalk/v1/stream
TXT vessel_name = motu

Service Type: _signalk-tcp._tcp
Service Name: signalk-tcp
Domain Name: local
Interface: wlan0 IPv4
Address: 10-1-1-64.local/10.1.1.64:55555
TXT vessel_uuid = urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d
TXT server = signalk-server
TXT version = 0.1
TXT vessel_mmsi = 123456789
TXT vessel_name = motu

If this is correct then I will write up some docs etc

In #146 a new signalk service for raw jsom messaging over tcp is added signalk-tcp._tcp. This is pretty simple and easy to define, we just make a tcp connection, and tx/rx signalk messages as json text. There are a couple of issues that need definition:

1. the json text MUST be UTF-8.
2. session handling. Server should assign a session id per connection, implementation specific.
3. security + authentication - should do https, could do certs, what about user/login - how is that managed
4. message delimiter - do we need a message delimiter or is it implicit in the json format. Ive used a state engine in arduino - it tracks where in a streaming message it currently is, so it knows where start and end is. Quite simple and fast. But for a currupted message or poorly formatted json we may need a RESET message?

vessel.json has mixed ways to refer to the subschemas: with id and without id. Let's harmonize on direct reference without the id to change the scope.

Signal K should support objects beyond vessels. Think of marinas, buoys, virtual objects etc. each type of object can have it's own data groups as well as groups other types have.

Things to consider:

• DRY-ness in Schema: we should avoid duplicate data URIs. An option would be to extend the definitions file.
• Categories: there has been some discussion about categories: grouping types by category (mobile, static, virtual, etc) instead of just having all under root.
• Naming

Since "current" is something we measure, I think we should avoid using it to mean "presently in use", so I recommend renaming currentRoute to activeRoute.

There has been a lot of discussion on different forums about server behavior. Lots of aspects to this:

• discovery: how a client can discover the server
• http/rest api behavior
• websocket protocol
  • what happens on initial connection
  • query parameters, if any
• server to server to gateway communication
• mapping and deriving values
• different capabilities
• time series access

We need better specs for these and other functionalities for Signal K to succeed.

I'm opening this issue to pull discussion into one place and branch off topics as they emerge.

There is the manually created, easy to use and localizable file that contains short & long names and unit for Signal K data items.

https://github.com/SignalK/specification/blob/master/i18n/en.json

Now that units are embedded in the schema we should produce this file from the schema automatically. English versions of short & long names should probably be embedded in the schema.

fuelRate is expressed in m3/s which makes sense for diesel and gasoline engines but not for electric drives.

That could be expressed simply as input voltage and current. I've not thought about the implications of a 3-phase drive.

In the root document, a vessel can be identified by its MMSI or an UUID. The vessel.json specifies only a MMSI field. In the event that a vessel is identified by an UUID, what is the correct value of the MMSI field in vessel.json: null, empty string (""), or the UUID?

How should we handle invalid data values in the SK spec? Two examples are;

1. Depth value when the depth has been lost i.e. turbulence hàs caused the depth unit to lose the bottom reading, a depth sounder normally flashes the last reading.
2. GPS unit temporarily loses position and as a result all readings; position, COG, SOG etc. are not valid.

A consumer should be able to tell the server which pieces of the SignalK data model it wants to receive updates for.

There are a large number of available settings within SK and although I am sceptical that your average user would set all of these settings, I think we need to have a Boat Brand field, Model field and YearBuilt field so that standard boat setup files can be created.

For instance a Jeaneau Sun Odyssey 41DS will have a set of dimensions and polars that are the same for every boat and by storing the Boat Brand, Model and YearBuilt data we could encourage the collection and publishing on the SK site of the standard settings file for common boats. This would make it easier for customers as once one customer has gone to the trouble of entering all of the data, it will be available for others to use.

Thinking about this, it would be a good idea to define a standard "Self" settings file that all consumers/servers/gateways used to store this data. The file would have to have a Version Number that was linked to the SK specification version but it could be a useful and social way for SK users to share boat data.

@SignalK/contributors

I've recently merged and closed a lot of (stale) pull requests. Running up to a 1st stable release, we need to review which groups will be included as stable (meaning that we can't just implement major breaking changes on them anymore) and which ones will be experimental. Please contribute your feedback in this thread, it'll serve as documentation.

How should SK cope with AIS targets that are not other Vessels i.e. Base Stations, AtoNs, SAR aircraft, AIS SARTs/MOBs, etc.

I am not comfortable handling these AIS targets as "Other Vessel" and think we should create a new "Mariners Object" (or similar) in the Root Schema for handling any object that is important to navigation but is not a vessel.

I am sure there are other objects that we would want to communicate in the future such as an Iceberg report, the position of Whales, etc. and so a more generic extensible object that could handle these AIS target types and other future objects is desirable.

This should probably be considered outside the scope of 1st release but it needs to be considered at some point.

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.

In the current schema vessel name is a plain string. The self vessel's name doesn't normally appear in the delta stream (it might if it changes?).

AIS vessel names appear in the delta stream when AIS static data messages are received. This puts name in path name under vessel's context root in the delta message.

When deltas are added to full tree there is a pretty simple logic: if the value received for a path is a plain value (number, string) it is inserted into the value property:

"speedOverGround": {
  "value": 3.53,
  "source": {},
  "timestamp": "2014-08-15-19:09:16.334"
}

and if the value is an object its properties will be inserted into the tree:

"position": {
  "longitude": 24.7276789,
  "latitude": 59.7086808,
  "source": {...},
  "timestamp": "2014-08-15-19:09:15.633"
}

There is no mechanism to distinguish the incoming AIS static update's name field to be used as it is and not wrapped without adding total schema awareness to this logic, which I would definitely like to avoid.

I suggest we alter the schema and wrap the name field in the normal value structure.

I guess there are / will be other cases like this.

Copied here from other discussion on slack, for wider feedback

The signalk model currently has allowance for _xxxx names, where the underscore denotes that it should never leave the server, eg stripped out of the messages. That makes them available only within the server.

So in the java server I will just store the config in vessels.self.config in a freeform json to suit myself.
I have a jsonschema for the config data and get a nice screen by using http://jeremydorn.com/json-editor/

The config app reads the config schema, and shows the config data.

So I guess I need some security rules, so that config is only writeable by apps loaded from the same server, but I think that can be handled by the existing security model. Hence an app could bundle a config schema, which could then display using the system config screen. But maybe thats too restrictive.

Maybe /signalk/v1/config/ would be useful though - very easy to restrict access. But I like the idea of storing in the main model, since we inherit all the existing functionality, even history (config auditability).
Plus we can distribute config updates across a big network of signalk devices the same as normal messages

Comments and ideas?

To better promote Signal K we should create a nicely formatted, printable and downloadable version of the specification.

It is quite possible for a key value to come from more than one device. eg position (lat/lon) could come from several gps enabled devices, and multiple depth sounders are not uncommon. We need a consistent way to handle this.

All the incoming values may well be valid in their own context, and it is feasible that all of them may be wanted, for instance, dispalying depth under each hull on a catamaran.

Hence discarding or averaging is not a solution, and since signalk is unable to derive the best way to handle multiple values it must always fall to a default action, with human over-ride when needed.

I propose we should simply store all the options in the tree, and have the main 'source' reference the options?

Then simple rules can apply:

1. If its the first value for the key, it becomes the first option and the default value.
2. If another value with different source arrives, we add to options - if its our preferred source (from persistent config) we auto-switch to it, otherwise we just record it
3. Users can then view the source options for a key and select from list for a specific display. They might select courseOverGroundTrue.options.ttyUSB1 as the source for a specific need or they may select an average/mean/min/max etc. (This facility is not part of the spec, but implementation specific)
4. maybe needs a rule to trim unreferenced options (or all options) on output.

{"vessels":
    {"self":
        {"navigation":
            {"courseOverGroundTrue":
                {
                 "value": 102.29,
                 "source": "options.actisense",
                 "options":
                    {
                    "ttyUSB1":  **just a unique name, have to generate somehow from incoming
                        {  
                            "value": 99.2900009155,
                            "source": "/dev/ttyUSB1"
                            "timestamp": "2014-08-15-16:00:00.081",
                        },
                     "actisense":
                        {
                            "value": 102.29,
                            "source": "/dev/actisense",

                            "timestamp": "2014-08-15-16:00:00.081",
                            "src": "115",
                            "pgn": "128267"
                        }
                    }
                }
            }
        }
    }
}

When recording a value we have a 'source' which includes various info about the values source.

Xavier suggested we may want make, model, even version etc, but this is too verbose for every value.

Hence we should consider having an inventory and just refer to the device when used in 'source'. The inventory also becomes useful for maintenance, insurance, customs, maybe lots of things.

So should we have vessels.[vessel].inventory.*

There are a couple of problems with the current group design: style-wise the different property names aren't in line with the other groups (e.g. loh for length of hull vs speedThroughWater for speed through water). key airHeight sound weird and whilst it does allow for total sail area, there is no way to specify individual sails, etc.

I've created this to start a discussion about what should be in there and naming. Also, we should consider non-sailing boats. I'll cross-post to mailing list for more ideas.

just getting my feet wet with SignalK (no pun intended), so apologies if the question is naive.
The readme in the specification repo refers to the bin/signalk-validate script, though the file is not in the repo. What am I missing? Thanks

It would be very good if a Signal K gateway/server could pass through NMEA2000 Alerts, AIS MOBs, etc. or there was a mechanism for a gateway/server to trigger an alert/alarm. One way would be to create a new object in the Root called Alarms;

• Alarms
  • aismob#12
  • alert#367
  • alarm#490

Each Alarm would reference the Signal K object that the alarm was related to i.e. a sensor, engine, aisSART, etc. so that it would be easy to access the relevant properties of the alarm by calling the object.... signalk/api/v1/vessels/self/propulsion/transmissionOilPressure/value

Obviously there are a lot of things to consider such as resetting/timing out the alarm and it maybe out of scope for V1 but we need to start considering this issue.

When a unit has a Unicode string (for instance \u00b0 for degrees) label this ends up in various places in the model, which might not be readable in all editors.

The 'units' description in definitions.json should contain a map "label": { "display": "\uxxxx" .... }

In a comment on #120, @tkurki wrote:

My suggestion is that

• we continue with the enum typed values for stuff that is naturally enumerable
• make sure the enum values cover most use cases
• write software defensively, eg. even if a field is an enum in the spec the software should not break with the appearence of "illegal" values (remember, somebody might add values to the spec behind your back)

My concern is that a validator like tv4 will report this an error and the application then has to determine which ones it can ignore. If we add an anyOf clause:

"properties": {
  "value": {
    "anyOf": [
      { "enum": ["Forward", "Neutral", "Reverse", "Fault"] },
      { "type": "string" }
    ]
  }
}

the json will validate with other values. The schema calls out the well-known values but specifically says other strings are allowed thereby telling the application developer to be defensive.

https://groups.google.com/d/msg/signalk/XFnlGYweN9Q/ZwqJt9EsCAAJ

Minimal delta doesn't need

• timestamps
• source
• context

Change the schema to make these optional.

It might be a good idea to allow optional validation with all fields mandatory, in case you want to check that you are outputting fully populated delta.

Route information doesn't have source or timestamp fields but probably should since bearingActual, courseRequired and eta are dynamic fields.

In the simple case we generally have plenty of cheap bandwidth these days, but that doesnt mean all likely transport mediums will have the same. Data over HF or even satellite being an excellent example.

Possibly it can be dealt with by adding a "priority" key to the delta format for sending updates, and this could be honoured later by any transport medium that can deal with it. In the case of NMEA2000 it would map to their priority messages, in the case of TCP/IP, map to the native QOS capabilities. Maybe for HF it would filter to only critical data against a whitelist, then prioritise the sending queue.