nausto-signalk 0.4.0 → 0.6.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
@@ -1,8 +1,10 @@
1
1
  # Nausto for Signal K
2
2
 
3
- A Signal K plugin for sharing selected own-vessel sensors with your boat in Nausto.
4
- It runs on the Signal K server, uses outgoing HTTPS, and keeps a bounded durable queue during
5
- network interruptions. It never changes boat equipment, relays, calibration or maintenance history.
3
+ A Signal K plugin for sharing selected own-vessel sensors with your boat in Nausto, and for
4
+ switching the on/off circuits Signal K reports as controllable. It runs on the Signal K server,
5
+ uses outgoing HTTPS, and keeps a bounded durable queue during network interruptions. It never
6
+ controls steering, propulsion, navigation or notifications, and never changes calibration or
7
+ maintenance history.
6
8
 
7
9
  ## Requirements
8
10
 
@@ -13,7 +15,7 @@ active crew members can read the selected values and history.
13
15
  ## Connect
14
16
 
15
17
  1. Install `nausto-signalk` through Signal K's AppStore, or install the supplied
16
- `.tgz` with `npm install /path/to/nausto-signalk-0.4.0.tgz` from your Signal K configuration directory.
18
+ `.tgz` with `npm install /path/to/nausto-signalk-0.6.0.tgz` from your Signal K configuration directory.
17
19
  2. Enable **Nausto** in Plugin Config. Open **Nausto** under Webapps and sign in to Signal K as an administrator.
18
20
  3. In Nausto, open Boat → Sensors, create a connection and copy its pairing code, or save its QR image.
19
21
  4. Enter the eight-character code, paste a copied code or import the QR image in the plugin. Older
@@ -33,20 +35,31 @@ trying again. An identical retry after a lost response does not spend another at
33
35
 
34
36
  ## Data and limits
35
37
 
36
- Only `vessels.self` is read. Battery voltage, current, power, consumed charge, state of charge,
37
- time remaining, temperature and water
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.
38
+ Only `vessels.self` is read; navigation, position (also coordinates under another plugin's own
39
+ root), the vessel's fixed design data and other vessels are never offered. Every numeric or on/off
40
+ reading under the vessel is offered to Nausto, also under another plugin's own root such as
41
+ `boatHub.devices`, with the name and unit from the Signal K metadata.
42
+
43
+ Readings on standard Signal K paths are suggested in Nausto: battery voltage, current, power,
44
+ consumed charge, state of charge, time remaining and temperature, inside, outside and water
45
+ temperature, water notifications, and each engine's total running hours, engine speed and
46
+ coolant temperature (`propulsion.<engine>.runTime`, `.revolutions` and `.temperature`), from an
47
+ engine gateway or an engine monitoring unit on NMEA 2000. The engine's label in Signal K names the
48
+ sensors; give the engine the same name in Nausto, and Nausto suggests it under Part of.
49
+
50
+ Other readings are offered unselected, as derived values, and the owner chooses them in Nausto.
51
+ The unit comes from the metadata: V, A, W, J/Wh/kWh, C/Ah, K/°C, Pa/hPa/bar, m³/L, m³/s/L/min,
52
+ m/s², ratio/%, s/min/h, rad/deg, m/s/kn and lux are known; a reading with an unknown unit is not
53
+ offered. A percentage is never guessed to be a volume, and a dimensionless value becomes a count
54
+ only through an explicit count mapping. Fuel used (`propulsion.<engine>.fuel.used`) is offered
55
+ the same way, so it never becomes the engine's measured fuel; map it explicitly as measured volume
56
+ when it comes from a fuel flow meter. Additional own-vessel paths and a known origin can be mapped
57
+ in the advanced plugin settings.
58
+
59
+ Nausto takes at most 64 readings per boat and 16 sources per connection. Known readings come
60
+ first, and the plugin status lists the readings that did not fit, as well as unsupported units or
61
+ source identities.
62
+
50
63
  NMEA 2000 source addresses are not device identity: CAN NAME is required. Plugin sources are treated
51
64
  as virtual sources scoped to this installation, including Bluetooth sources with a source address.
52
65
  Fixed identities for other non-NMEA providers can be
@@ -76,7 +89,7 @@ with at most one ordinary sample per minute. A new source report is forwarded af
76
89
  without a significant change. Re-reading the same timestamped cache never refreshes a reading.
77
90
  Actual state/alarm and quality transitions are saved immediately and wake the sender. The first
78
91
  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
92
+ sent before that minute at the next permitted batch attempt. Requests remain at least 31 seconds
80
93
  apart; selection checks, queued batches, network failures and server `Retry-After` can delay
81
94
  delivery. Transitions coalesce durably while waiting. An explicit server delay also blocks new
82
95
  batches, survives restarts and does not change sealed payloads or measurement identities.
@@ -89,6 +102,38 @@ Up to five connection profiles are retained locally. When an old profile or olde
89
102
  the gap is counted. Rejected batches and exhausted retries remain visible and can be retried explicitly.
90
103
  No API or log returns keys, pairing codes, raw batches or private database paths.
91
104
 
105
+ ## Switching circuits
106
+
107
+ A path Signal K reports as controllable (`supportsPut`), with an on/off value (true/false, or 1/0
108
+ on a `.state` path) from a single source, is offered to Nausto as a circuit. It belongs to the same
109
+ source as the sensors from that Signal K source. Paths under `steering`, `propulsion`, `navigation`
110
+ and `notifications` are never offered. There is no activation step and no on-board choice: a boat
111
+ owner can switch the circuit in Nausto right away, give active crew members the right to switch
112
+ it, or turn off control for a circuit. At most 16 circuits are offered, those already offered
113
+ first, and the plugin's Details list them.
114
+
115
+ A circuit named or identified as a bilge pump or an alarm (such as `bilge`, `lensepumpe` or
116
+ `alarm`) is protected and is never switched off. The plugin reads every name Signal K has for the
117
+ path and its parent, and the path itself, checks this before every call, and a later name change
118
+ never lowers the protection.
119
+
120
+ A circuit named or identified as an anchor windlass, a winch or a propeller or thruster (such as
121
+ `ankerspill`, `windlass`, `vinsj`, `winch`, `propell` or `thruster`, also inside compound words) is
122
+ never offered and never switched, because Nausto cannot tell whether anyone is on board when it
123
+ starts. `anchor` alone does not count, so an anchor light can still be switched. The plugin checks
124
+ the same names at every offer and right before every call, so an offered circuit that gets such a
125
+ name is not called and leaves the next offer.
126
+
127
+ Each command is stored before one Signal K PUT to the handler that owns the path, and a lost
128
+ response or a restart never repeats it. Commands live at most 60 seconds. Right before the call
129
+ the plugin checks the path again: still controllable, same source and same type. Status 200 is
130
+ done, 405 not supported, another 4xx declined, and 5xx, an error or no answer within 20 seconds
131
+ unknown. Only a new report from the source confirms the new state. A change is reported at once
132
+ and an unchanged circuit at least every few minutes. A quiet connection with circuits checks for
133
+ commands every 40 seconds. Requests are at least 31 seconds apart, so the plugin sends at most 117
134
+ in an hour and never pauses near the end of the hour. If Nausto declines a control
135
+ message, readings continue and switching waits until you choose Retry in the plugin's Details.
136
+
92
137
  ## Optional boat GNSS source
93
138
 
94
139
  The plugin can announce a GNSS source when both Nausto and the installed plugin support the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nausto-signalk",
3
- "version": "0.4.0",
3
+ "version": "0.6.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": [