nausto-signalk 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,10 +13,11 @@ active crew members can read the selected values and history.
13
13
  ## Connect
14
14
 
15
15
  1. Install `nausto-signalk` through Signal K's AppStore, or install the supplied
16
- `.tgz` with `npm install /path/to/nausto-signalk-0.2.0.tgz` from your Signal K configuration directory.
16
+ `.tgz` with `npm install /path/to/nausto-signalk-0.4.0.tgz` from your Signal K configuration directory.
17
17
  2. Enable **Nausto** in Plugin Config. Open **Nausto** under Webapps and sign in to Signal K as an administrator.
18
18
  3. In Nausto, open Boat → Sensors, create a connection and copy its pairing code, or save its QR image.
19
- 4. Paste the code or import the QR image in the plugin. Return to Nausto, choose the discovered sensors,
19
+ 4. Enter the eight-character code, paste a copied code or import the QR image in the plugin. Older
20
+ pairing codes and QR images still work. Return to Nausto, choose the discovered sensors,
20
21
  confirm their component and primary source, and wait for the first reading.
21
22
 
22
23
  The code is valid for ten minutes. A new pairing uses a new producer key. Re-pair the same
@@ -24,12 +25,28 @@ connection to retain its sensor identities. A different connection has its own i
24
25
  If the Signal K vessel identity changes, create a new Nausto connection for that vessel.
25
26
  Revoke a connection in Nausto to stop its access. Plugin configuration never contains a pairing code or key.
26
27
 
28
+ Eight-character codes use Nausto's pairing endpoint at `https://nausto.no/integrasjoner/sensors/pair`.
29
+ Measurements, older codes and QR pairing keep the existing sensor endpoint. Pairing allows five
30
+ different code/key combinations per network address (IPv6 /64) in ten minutes. A shared network
31
+ shares this allowance; a new code does not reset it. If pairing is rate limited, wait before
32
+ trying again. An identical retry after a lost response does not spend another attempt.
33
+
27
34
  ## Data and limits
28
35
 
29
36
  Only `vessels.self` is read. Battery voltage, current, power, consumed charge, state of charge,
30
37
  time remaining, temperature and water
31
- notifications are discovered from standard Signal K paths. Additional own-vessel paths can be mapped
32
- in the advanced plugin settings. Unsupported units or source identities are reported in plugin status.
38
+ notifications are discovered from standard Signal K paths. So are each engine's total running
39
+ hours, engine speed and coolant temperature (`propulsion.<engine>.runTime`, `.revolutions` and
40
+ `.temperature`), from an engine gateway or an engine monitoring unit on NMEA 2000. The engine's
41
+ label in Signal K names the sensors; give the engine the same name in Nausto, and Nausto suggests
42
+ it under Part of. Fuel used (`propulsion.<engine>.fuel.used`) is not offered automatically, because
43
+ Signal K does not say whether it is measured; map it explicitly as measured volume when it comes
44
+ from a fuel flow meter. Additional own-vessel paths can be mapped in the advanced plugin settings.
45
+ Unsupported units or source identities are reported in plugin status.
46
+ Explicit advanced mappings also support cumulative energy (J), pressure (Pa), volume (m³),
47
+ volume flow (m³/s), acceleration (m/s²) and nonnegative integer counts. Known units such as
48
+ Wh/kWh, hPa/bar and litres are converted to SI. A percentage is never guessed to be a volume,
49
+ and a dimensionless value becomes a count only through an explicit count mapping.
33
50
  NMEA 2000 source addresses are not device identity: CAN NAME is required. Plugin sources are treated
34
51
  as virtual sources scoped to this installation, including Bluetooth sources with a source address.
35
52
  Fixed identities for other non-NMEA providers can be
@@ -54,7 +71,15 @@ When another integration supplies the same bank, choose its existing component a
54
71
  one primary source per quantity in Nausto. A newer secondary reading does not take over automatically.
55
72
  Upgrading this package preserves the existing pairing, selections and channel identities.
56
73
 
57
- Numeric values are sampled at most once per minute per channel. State/alarm changes are preserved.
74
+ Numeric values use a deadband (for example 0.1 K for temperature and 0.05 V for voltage),
75
+ with at most one ordinary sample per minute. A new source report is forwarded after two minutes
76
+ without a significant change. Re-reading the same timestamped cache never refreshes a reading.
77
+ Actual state/alarm and quality transitions are saved immediately and wake the sender. The first
78
+ value is a baseline and keeps the ordinary minute window. A transition window can be sealed and
79
+ sent before that minute at the next permitted batch attempt. Requests remain at least 30 seconds
80
+ apart; selection checks, queued batches, network failures and server `Retry-After` can delay
81
+ delivery. Transitions coalesce durably while waiting. An explicit server delay also blocks new
82
+ batches, survives restarts and does not change sealed payloads or measurement identities.
58
83
  Original source time, null values and units are retained. A heartbeat never makes an old reading new.
59
84
  An undated cached value is not sent as a fresh measurement after a restart. A batch window starts
60
85
  when its first observation is captured; missing source times use that conservative window time.
@@ -64,6 +89,34 @@ Up to five connection profiles are retained locally. When an old profile or olde
64
89
  the gap is counted. Rejected batches and exhausted retries remain visible and can be retried explicitly.
65
90
  No API or log returns keys, pairing codes, raw batches or private database paths.
66
91
 
92
+ ## Optional boat GNSS source
93
+
94
+ The plugin can announce a GNSS source when both Nausto and the installed plugin support the
95
+ separate position protocol. It sends no coordinates until the boat owner selects that source
96
+ in Nausto. The supported input is a live NMEA 2000 PGN 129029 update containing position,
97
+ GNSS date/time and fix quality together, with a stable CAN NAME. It never joins cached
98
+ coordinates to another clock, uses another vessel's data or substitutes the phone's position.
99
+
100
+ Standard Signal K HDOP/PDOP are not accuracy in metres. Accuracy remains unknown unless an
101
+ explicit advanced `positionAccuracyPath` names a documented metre-valued field from the same
102
+ source and same fix. An unknown accuracy cannot establish a movement-alarm baseline. There
103
+ is no invented default field or conversion from dilution to metres.
104
+
105
+ The private position buffer holds only the newest unsent fix and at most one immutable
106
+ already-attempted message. It stores no historical route. Old fixes that cannot establish a
107
+ fresh baseline are dropped and counted as gaps; retry never refreshes their physical time.
108
+ Source removal, revocation and connection changes clear the position buffer. Two records
109
+ of at most 1,024 bytes reserve 2,048 bytes and two observations inside the existing profile
110
+ budget. The sealed scalar queue therefore has 9,898 observations / 10 MiB minus 64 KiB and
111
+ 2,048 bytes, the open scalar window retains its existing 100 observations / 64 KiB, and GPS
112
+ uses the remaining two records. The combined limits remain 10,000 observations and 10 MiB.
113
+
114
+ The first newly requested fresh fix gets the next permitted send slot, then ordinary GPS
115
+ delivery is limited to one message per two minutes per connection. GPS and scalar messages
116
+ share the same 30-second request guard and `Retry-After`; scalar batches retain their FIFO.
117
+ This is not immediate tracking. Movement notifications can take two to four minutes, and
118
+ arming waits for a qualified fresh baseline.
119
+
67
120
  ## Build and verification
68
121
 
69
122
  From the Nausto repository: `npm run build:sensors:signalk`. The output is a self-contained CommonJS
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nausto-signalk",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "Connect selected Signal K boat sensors to Nausto with pairing and durable delivery",
5
5
  "main": "index.cjs",
6
6
  "files": [