nausto-signalk 0.1.0 → 0.3.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.1.0.tgz` from your Signal K configuration directory.
16
+ `.tgz` with `npm install /path/to/nausto-signalk-0.3.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,16 +25,55 @@ 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
- Only `vessels.self` is read. Battery voltage, current, state of charge, temperature and water
36
+ Only `vessels.self` is read. Battery voltage, current, power, consumed charge, state of charge,
37
+ time remaining, temperature and water
30
38
  notifications are discovered from standard Signal K paths. Additional own-vessel paths can be mapped
31
39
  in the advanced plugin settings. Unsupported units or source identities are reported in plugin status.
40
+ Explicit advanced mappings also support cumulative energy (J), pressure (Pa), volume (m³),
41
+ volume flow (m³/s), acceleration (m/s²) and nonnegative integer counts. Known units such as
42
+ Wh/kWh, hPa/bar and litres are converted to SI. A percentage is never guessed to be a volume,
43
+ and a dimensionless value becomes a count only through an explicit count mapping.
32
44
  NMEA 2000 source addresses are not device identity: CAN NAME is required. Plugin sources are treated
33
- as virtual sources scoped to this installation. Fixed identities for other non-NMEA providers can be
45
+ as virtual sources scoped to this installation, including Bluetooth sources with a source address.
46
+ Fixed identities for other non-NMEA providers can be
34
47
  configured explicitly; a source name or IP alone is never treated as a physical device identifier.
35
48
 
36
- Numeric values are sampled at most once per minute per channel. State/alarm changes are preserved.
49
+ ## Victron battery monitors
50
+
51
+ Use existing standard Signal K battery data first. BMV-712 Smart data can come from an existing
52
+ VE.Direct collector, or from a compatible Bluetooth Instant Readout collector such as
53
+ [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble).
54
+ That collector is separate from Nausto; follow its supported hardware and Python/Bluetooth requirements.
55
+ Keep the Victron encryption key only in that collector's local configuration. Nausto never needs it.
56
+
57
+ Select the actual battery bank in the collector and confirm the same component in Nausto.
58
+ Positive battery current means charging and negative current means discharging; it is net current,
59
+ not the charger's output current. SOC and time remaining are estimates, power is calculated,
60
+ and consumed charge is stored in coulombs and displayed in Ah. Optional temperature and secondary
61
+ battery voltage appear only when the collector is configured for them and actually publishes them.
62
+ Bluetooth availability alone does not prove Instant Readout support. No GX, VRM or new gateway is required.
63
+
64
+ When another integration supplies the same bank, choose its existing component and explicitly set
65
+ one primary source per quantity in Nausto. A newer secondary reading does not take over automatically.
66
+ Upgrading this package preserves the existing pairing, selections and channel identities.
67
+
68
+ Numeric values use a deadband (for example 0.1 K for temperature and 0.05 V for voltage),
69
+ with at most one ordinary sample per minute. A new source report is forwarded after two minutes
70
+ without a significant change. Re-reading the same timestamped cache never refreshes a reading.
71
+ Actual state/alarm and quality transitions are saved immediately and wake the sender. The first
72
+ value is a baseline and keeps the ordinary minute window. A transition window can be sealed and
73
+ sent before that minute at the next permitted batch attempt. Requests remain at least 30 seconds
74
+ apart; selection checks, queued batches, network failures and server `Retry-After` can delay
75
+ delivery. Transitions coalesce durably while waiting. An explicit server delay also blocks new
76
+ batches, survives restarts and does not change sealed payloads or measurement identities.
37
77
  Original source time, null values and units are retained. A heartbeat never makes an old reading new.
38
78
  An undated cached value is not sent as a fresh measurement after a restart. A batch window starts
39
79
  when its first observation is captured; missing source times use that conservative window time.
@@ -43,6 +83,34 @@ Up to five connection profiles are retained locally. When an old profile or olde
43
83
  the gap is counted. Rejected batches and exhausted retries remain visible and can be retried explicitly.
44
84
  No API or log returns keys, pairing codes, raw batches or private database paths.
45
85
 
86
+ ## Optional boat GNSS source
87
+
88
+ The plugin can announce a GNSS source when both Nausto and the installed plugin support the
89
+ separate position protocol. It sends no coordinates until the boat owner selects that source
90
+ in Nausto. The supported input is a live NMEA 2000 PGN 129029 update containing position,
91
+ GNSS date/time and fix quality together, with a stable CAN NAME. It never joins cached
92
+ coordinates to another clock, uses another vessel's data or substitutes the phone's position.
93
+
94
+ Standard Signal K HDOP/PDOP are not accuracy in metres. Accuracy remains unknown unless an
95
+ explicit advanced `positionAccuracyPath` names a documented metre-valued field from the same
96
+ source and same fix. An unknown accuracy cannot establish a movement-alarm baseline. There
97
+ is no invented default field or conversion from dilution to metres.
98
+
99
+ The private position buffer holds only the newest unsent fix and at most one immutable
100
+ already-attempted message. It stores no historical route. Old fixes that cannot establish a
101
+ fresh baseline are dropped and counted as gaps; retry never refreshes their physical time.
102
+ Source removal, revocation and connection changes clear the position buffer. Two records
103
+ of at most 1,024 bytes reserve 2,048 bytes and two observations inside the existing profile
104
+ budget. The sealed scalar queue therefore has 9,898 observations / 10 MiB minus 64 KiB and
105
+ 2,048 bytes, the open scalar window retains its existing 100 observations / 64 KiB, and GPS
106
+ uses the remaining two records. The combined limits remain 10,000 observations and 10 MiB.
107
+
108
+ The first newly requested fresh fix gets the next permitted send slot, then ordinary GPS
109
+ delivery is limited to one message per two minutes per connection. GPS and scalar messages
110
+ share the same 30-second request guard and `Retry-After`; scalar batches retain their FIFO.
111
+ This is not immediate tracking. Movement notifications can take two to four minutes, and
112
+ arming waits for a qualified fresh baseline.
113
+
46
114
  ## Build and verification
47
115
 
48
116
  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.1.0",
3
+ "version": "0.3.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": [