frugal-iot-server 0.3.7 → 0.3.9

package/config.d/schema/topics.yaml

@@ -9,6 +9,11 @@
 # name  Capitalized English (and add translation below in 'languages')
 # max   For gauges, slider
 # min   For gauges, slider
+# width Total characters of the rendered number, including any sign and the decimal point and
+#   excluding units - the same meaning the node gives it. Decimals are derived, not declared:
+#   intWidth = max(len(int(min)), len(int(max))) including a '-', then decimals = width-intWidth-1.
+#   Deriving from min/max rather than from the value keeps the decimal count steady as the value
+#   moves. Only float and exponential topics need it; an int has no decimals to decide.
 # color can be a name or a #RRGGBB
 # display One of bar,gauge,text,slider,inputbox
 # slot  if this topic fits into a specific slot in the enclosing module (currently just frugal_iot module)
@@ -21,7 +26,8 @@
 #   no setting at all, any float, int or bool with "rw: r" is recorded, which is easy to be
 #   surprised by. scripts/check-schema.js warns about a topic that does not say.
 # duplicates  when to bother recording a reading: significantvalue is how much it has to have moved
-#   since the last one recorded, significantdate how long (in milliseconds) since that one, and a
+#   since the last one recorded - either an absolute amount e.g. 0.5, or as a percentage of the last
+#   reading e.g. "2%" - significantdate how long (in milliseconds) since that one, and a
 #   reading that meets neither is dropped. Every topic with "log: true" wants a rule here - without
 #   one, every reading is written to the SD card as it arrives, which wears the card out.
 # Note battery gets special cased
@@ -30,10 +36,12 @@ altitude:
   leaf:     altitude
   name:     Altitude
   type:     float
+  units:    m
   display:  text
   min:      -500
   max:      9000
-  color:    black
+  width:    6
+  color:    "#000000"
   log:      true
   duplicates:
     significantdate: 900000
@@ -59,7 +67,7 @@ aqi:
   display:  bar
   min:      0
   max:      5
-  color:    purple
+  color:    "#800080"
   rw:       r
   graphable:  true
   log:      true
@@ -73,7 +81,7 @@ aqi500:
   display:  bar
   min:      0
   max:      500
-  color:    brown
+  color:    "#a52a2a"
   rw:       r
   graphable:  true
   log:      true
@@ -87,7 +95,7 @@ battery:
   display:  text
   min:      3000
   max:      5000
-  color:    green
+  color:    "#008000"
   rw:       r
   graphable:  true
   log:      true
@@ -111,7 +119,8 @@ bus:
   display:  text
   min:      0
   max:      32
-  color:    green
+  width:    5
+  color:    "#008000"
   rw:       r
   log:      true
   units:    V
@@ -125,7 +134,7 @@ button:
   type:     bool
   log:      true
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       r
   # A press changes the value, so it is still recorded - this only drops the repeats in between
   duplicates:
@@ -142,10 +151,11 @@ controlfloat:
   #[leaf, name] should be overridden
   min:      0
   max:      100
+  width:    5
   type:     float
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   wireable: true
   rw:       w
   retain:   true
@@ -156,7 +166,7 @@ controlint:
   type:     int
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   wireable: true
   rw:       w
   retain:   true
@@ -167,7 +177,7 @@ controltext:
   type:     text
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   wireable: true
   rw:       w
   retain:   true
@@ -176,7 +186,7 @@ controlintoggle:
   type:     bool
   log:      false
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       w
   wireable: false
 controlouttoggle:
@@ -184,7 +194,7 @@ controlouttoggle:
   type:     bool
   log:      true
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       r
   wireable: true
   # Read-only bool, so logged by default - match the "out" and "on" topics it stands in for
@@ -198,7 +208,8 @@ course:
   display:  text
   min:      0
   max:      360
-  color:    black
+  width:    5
+  color:    "#000000"
   log:      true
   duplicates:
     significantdate: 900000
@@ -213,7 +224,8 @@ current:
   display:  text
   min:      -3200
   max:      3200
-  color:    red
+  width:    7
+  color:    "#ff0000"
   rw:       r
   log:      true
   units:    mA
@@ -237,7 +249,8 @@ do:
   display:  bar
   min:      0
   max:      20
-  color:    blue
+  width:    5
+  color:    "#0000ff"
   rw:       r
   log:      true
   units:    mg/L
@@ -252,7 +265,7 @@ eco2:
   display:  bar
   min:      300
   max:      900
-  color:    brown
+  color:    "#a52a2a"
   log:      true
   units:    ppm
   duplicates:
@@ -267,7 +280,8 @@ gas:
   display:  text
   min:      0
   max:      500
-  color:    green
+  width:    5
+  color:    "#008000"
   rw:       r
   log:      true
   units:    kOhm
@@ -282,7 +296,8 @@ hdop:
   display:  text
   min:      0
   max:      50
-  color:    black
+  width:    5
+  color:    "#000000"
   log:      false
   duplicates:
     significantdate: 900000
@@ -296,7 +311,8 @@ humidity:
   display:  bar
   min:      0
   max:      100
-  color:    blue
+  width:    5
+  color:    "#0000ff"
   log:      true
   duplicates:
     significantdate: 900000
@@ -325,7 +341,7 @@ language_code:
   type:     text
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   rw:       r
 lastseen:
   leaf:     lastseen
@@ -342,7 +358,8 @@ latitude:
   display:  text
   min:      -90
   max:      +90
-  color:    black
+  width:    9
+  color:    "#000000"
   log:      true
   duplicates:
     significantdate: 900000
@@ -357,7 +374,8 @@ load:
   display:  text
   min:      0
   max:      32
-  color:    green
+  width:    5
+  color:    "#008000"
   rw:       r
   log:      true
   units:    V
@@ -372,7 +390,8 @@ loadcell:
   display:  text
   min:      0
   max:      65000
-  color:    yellow
+  width:    7
+  color:    "#b8860b"
   log:      true
   duplicates:
     significantdate: 900000
@@ -387,7 +406,8 @@ longitude:
   display:  text
   min:      -180
   max:      +180
-  color:    black
+  width:    10
+  color:    "#000000"
   log:      true
   duplicates:
     significantdate: 900000
@@ -402,12 +422,13 @@ lux:
   display:  bar
   min:      0
   max:      65000
-  color:    yellow
+  width:    5
+  color:    "#b8860b"
   log:      true
   rw:       r
   duplicates:
     significantdate: 900000
-    significantvalue: 100
+    significantvalue: 5%
   graphable:  true
   units:    lx
 manual:
@@ -415,7 +436,7 @@ manual:
   name:     Manual
   type:     bool
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       r
   log:      true
   graphable:  true
@@ -431,7 +452,7 @@ message:
   type:     text
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   wireable: true
   rw:       w
   retain:   true
@@ -442,7 +463,8 @@ mm:
   display:  text
   min:      0
   max:      500
-  color:    blue
+  width:    5
+  color:    "#0000ff"
   rw:       r
   log:      true
   duplicates:
@@ -464,7 +486,7 @@ on:
   name:     On
   type:     bool
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       w
   log:      true
   duplicates:
@@ -476,7 +498,7 @@ out:
   name:     Out
   type:     bool
   display:  toggle
-  color:    black
+  color:    "#000000"
   rw:       r
   log:      true
   wireable: true
@@ -484,13 +506,33 @@ out:
   duplicates:
     significantdate: 900000
     significantvalue: 1
+percent:
+  # A 0-100% figure that is worth recording and graphing - state of charge, battery health. Unlike
+  # controlfloat it is read-only and logged, so it needs its own duplicate rule; [name] and the
+  # duplicate thresholds should be overridden per module.
+  leaf:     percent
+  name:     Percent
+  type:     float
+  display:  bar
+  min:      0
+  max:      100
+  width:    3
+  color:    "#008000"
+  rw:       r
+  wireable: false
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 1
+  graphable:  true
+  units:    "%"
 position:
   leaf:     position
   name:     Position
   type:     text
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   rw:       r
 power:
   leaf:     power
@@ -499,7 +541,8 @@ power:
   display:  text
   min:      0
   max:      100000
-  color:    orange
+  width:    8
+  color:    "#ffa500"
   rw:       r
   log:      true
   units:    mW
@@ -512,9 +555,11 @@ pressure:
   name:     Pressure
   type:     float
   display:  bar
-  min:      0
-  max:      99
-  color:    blue
+  min:      300
+  max:      1100
+  width:    6
+  units:    hPa
+  color:    "#0000ff"
   rw:       r
   log:      true
   duplicates:
@@ -528,7 +573,8 @@ rain:
   display:  text
   min:      0
   max:      500
-  color:    blue
+  width:    5
+  color:    "#0000ff"
   rw:       r
   log:      true
   duplicates:
@@ -543,14 +589,15 @@ satellites:
   display:  text
   min:      0
   max:      32
-  color:    black
+  width:    2
+  color:    "#000000"
   log:      false
   duplicates:
     significantdate: 900000
     significantvalue: 1
   rw:       r
   graphable:  false
-  units:    m/s
+  units:    count
 select:
   leaf:     select
   name:     Select
@@ -558,7 +605,7 @@ select:
   log:      false
   min:      0
   display:  text
-  color:    black
+  color:    "#000000"
   wireable: false
   rw:       w
   retain:   true
@@ -569,7 +616,8 @@ shunt:
   display:  text
   min:      -320
   max:      320
-  color:    blue
+  width:    6
+  color:    "#0000ff"
   rw:       r
   log:      true
   units:    mV
@@ -584,7 +632,8 @@ speed:
   display:  text
   min:      0
   max:      999
-  color:    black
+  width:    5
+  color:    "#000000"
   log:      true
   duplicates:
     significantdate: 900000
@@ -599,7 +648,7 @@ soil:
   display:  bar
   min:      0
   max:      100
-  color:    brown
+  color:    "#a52a2a"
   rw:       r
   log:      true
   duplicates:
@@ -607,7 +656,23 @@ soil:
     significantvalue: 1
   graphable:  true
   calibrate:  true
-  units:    "%RH"
+  units:    "%"
+tank:
+  leaf:     tank
+  name:     Water Tank
+  type:     float
+  display:  bar
+  min:      0
+  max:      100
+  width:    5
+  color:    "#0000ff"
+  rw:       r
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 1
+  graphable:  true
+  units:    "%"
 temperature:
   leaf:     temperature
   name:     Temperature
@@ -616,7 +681,8 @@ temperature:
   rw:       r
   min:      0
   max:      50
-  color:    red
+  width:    4
+  color:    "#ff0000"
   wireable: false
   log:      true
   units:    Cel
@@ -629,10 +695,11 @@ timeoff:
   name:     Time Off (s)
   min:      0
   max:      3600
+  width:    4
   type:     float
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   rw:       w
   wireable: true
   units:    s
@@ -641,10 +708,11 @@ timeon:
   name:     Time On (s)
   min:      0
   max:      3600
+  width:    4
   type:     float
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
   rw:       w
   wireable: true
   units:    s
@@ -655,7 +723,7 @@ tvoc:
   display:  bar
   min:      0
   max:      99
-  color:    green
+  color:    "#008000"
   rw:       r
   log:      true
   units:    ppb
@@ -670,7 +738,8 @@ ultrasonic:
   display:  bar
   min:      0
   max:      7500
-  color:    blue
+  width:    4
+  color:    "#0000ff"
   rw:       r
   log:      true
   units:    mm
@@ -685,8 +754,43 @@ utc_time:
   type:     text
   log:      false
   display:  text
-  color:    black
+  color:    "#000000"
+  rw:       r
+voltage:
+  # A DC voltage read through a resistor divider - see Sensor_Voltage in the library. Millivolts,
+  # like `battery`, but without that topic's single-lithium-cell range or its special-casing in
+  # the UX. [name, min, max] should be overridden per module.
+  leaf:     voltage
+  name:     Voltage
+  type:     int
+  display:  text
+  min:      0
+  max:      30000
+  color:    "#800080"
   rw:       r
+  graphable:  true
+  log:      true
+  units:    mV
+  duplicates:
+    significantdate: 900000
+    significantvalue: 100
+volts:
+  leaf:     volts
+  name:     Volts
+  type:     float
+  display:  slider
+  rw:       w
+  min:      0
+  max:      3.3
+  width:    4
+  color:    "#800080"
+  units:    V
+  wireable: true
+  log:      true
+  duplicates:
+    significantdate: 900000
+    significantvalue: 0.05
+  graphable:  true
 wifibars:
   leaf:     wifibars
   name:     WiFi
@@ -695,7 +799,7 @@ wifibars:
   display:  text
   min:      0
   max:      4
-  color:    blue
+  color:    "#0000ff"
   rw:       r
   # Logged, because an int that is read-only is logged unless told otherwise. Only 5 values, so
   # any change is worth recording and nothing else is
@@ -708,5 +812,5 @@ wifissid:
   type:     text
   log:      false
   display:  text
-  color:    blue
+  color:    "#0000ff"
   rw:       r

package/extras/mosquitto-bridge.conf.example

@@ -0,0 +1,130 @@
+# Bridging this Pi's broker to a production Frugal IoT server
+#
+# Optional. Without this file the Pi is self-contained: nodes publish to the broker here, the
+# logger records the readings here, and the dashboard here shows them. Adding it also relays
+# everything to a production server, so the same nodes appear on a dashboard elsewhere and can be
+# controlled from it, while the Pi carries on working on its own whenever the link is down.
+#
+# This is a Mosquitto "bridge" - the broker's own feature for connecting to another broker. The
+# server, the logger and the nodes know nothing about it and need no configuration change.
+#
+# To use it:
+#   sudo cp extras/mosquitto-bridge.conf.example /etc/mosquitto/conf.d/frugal-iot-bridge.conf
+#   sudo nano /etc/mosquitto/conf.d/frugal-iot-bridge.conf     # replace every <...> below
+#   sudo systemctl restart mosquitto
+#
+# It has to be a restart, not a reload: Mosquitto does not pick up bridges on a reload signal.
+# That briefly disconnects every node, which they recover from on their own.
+#
+# The file goes in /etc/mosquitto/conf.d/ rather than in this installation, because it holds a
+# password for the production broker. Everything under config.d/ here is served to any logged-in
+# browser by /config.json, so a credential put there would not stay private.
+
+# ============ The connection ============
+
+# Names the bridge. Anything, but it appears in the log, so make it recognisable.
+connection to-prod
+
+# The production broker's plain-MQTT-over-TLS address. Not the wss:// URL the browsers and the
+# server use - a Mosquitto bridge speaks MQTT or MQTT-over-TLS and cannot use WebSockets, so
+# production needs a listener on 8883 for this. Port 1883 would work on a trusted LAN, but sends
+# the password below in clear, so over the internet use 8883 and keep the TLS lines further down.
+address <prod-host>:8883
+
+# The account this Pi uses on the production broker. Give each Pi its own, rather than sharing the
+# organization's account: the organization password is handed to every browser that logs in, so it
+# is not a secret, and a per-Pi account can be restricted to just this site's topics and revoked
+# on its own.
+remote_username <bridge-account>
+remote_password <bridge-password>
+
+# The client id this Pi presents to production, and the name production uses when it reports the
+# state of this bridge (see "notifications" below). One per Pi, or two Pis will disconnect each
+# other in a loop as each takes over the other's session.
+remote_clientid <bridge-account>
+
+# Verify production's certificate against the system CA store, which is what a Let's Encrypt
+# certificate on production needs - no certificate has to be copied onto this Pi. Delete both
+# lines, and use port 1883 above, only on a network you trust end to end.
+bridge_cafile /etc/ssl/certs/ca-certificates.crt
+bridge_insecure false
+
+# How long to wait before retrying, in seconds, doubling from the first number up to the second.
+# A Pi on a weak or intermittent link keeps retrying for as long as it takes; the cap stops a
+# flapping connection from hammering production.
+restart_timeout 5 60
+
+# Keep production's copy of our subscriptions across a dropped connection. This is the default,
+# and it matters: with "true" instead, Mosquitto re-subscribes on every reconnect and production
+# re-sends every retained message each time, which on a flaky link means a burst of duplicated
+# readings after every blip. Nodes publish nearly everything retained, so that burst is large.
+cleansession false
+
+# Publish a retained "1" or "0" to $SYS/broker/connection/<remote_clientid>/state on both brokers
+# whenever the link comes up or goes down. This is how "npx --no frugal-iot-diagnostic" reports
+# whether the bridge is connected, and it also lets production see which sites are reachable.
+# The default is true; it is written out here because it is useful rather than incidental.
+notifications true
+
+# Uncomment if production refuses the bridge's connection or logs a denied publish to $SYS. Once
+# production has an acl_file, writing to $SYS may not be permitted, and this stops trying: the
+# state is then published only to the broker here, which is all the diagnostic script reads. What
+# is lost is production's view of whether this site is reachable.
+#notifications_local_only true
+
+# Not set, and worth knowing why: local_username / local_password. The broker here requires
+# authentication, but a bridge's local side is internal to the broker and does not go through it.
+# Verified on mosquitto 2.0.21 - an anonymous publish is refused while the bridge still forwards.
+
+# ============ What gets relayed ============
+#
+# Replace <org> in all four lines with the organization id - the first element of every topic, and
+# the name of the file in config.d/organizations/. One set of four lines per organization on this
+# Pi. To relay only some projects, replace "<org>/" with "<org>/<project>/" and add "+/" where a
+# level is now missing, or repeat the block per project.
+#
+# Frugal IoT topics come in five shapes, and each line below picks out one or two of them. "+"
+# matches exactly one level, so counting levels is what separates them:
+#
+#   <org>/<project>                                        the "quick discover" announcement
+#   <org>/<project>/<node>/<module>/<field>                a reading
+#   <org>/<project>/<node>/<module>/<field>/<parameter>    a reading's min, max, colour, wiring
+#   <org>/<project>/<node>/set/<module>/<field>            a control
+#   <org>/<project>/<node>/set/<module>/<field>/<parameter>
+#
+# Readings, at five levels. These are the only topics the logger writes to disk, so this is the
+# one line where a topic must not be matched twice - each extra copy would be another row in the
+# CSV files at the far end.
+#
+# The "0" is the QoS, and it is doing real work. At 0, anything published while production is
+# unreachable is simply dropped: production's history has a gap for the outage and this Pi's is
+# complete. At 1 the broker would instead queue it all up and deliver it on reconnect, where
+# production stamps each reading with the time it arrived - so an outage would come back as a
+# whole day's readings all claiming to have happened at the moment the link returned, which is
+# worse than a gap because it looks like real data. Leave this at 0.
+topic <org>/+/+/+/+ out 0
+
+# The quick discover announcement, so production learns which nodes live here. Sent periodically
+# and not retained, so nothing accumulates while the link is down.
+topic <org>/+ out 0
+
+# Parameters - the min, max, colour and wiring a node announces once at startup. The dashboard
+# needs them to draw a node properly, and the logger never records them.
+topic <org>/+/+/+/+/+ out 0
+
+# Controls, in both directions and at QoS 1. Both directions, because a control can be set from
+# either dashboard and both brokers need to know. QoS 1 because here queueing is exactly what is
+# wanted: a control set on production while this Pi is offline is held and delivered when it comes
+# back, which is the same reason nodes publish these retained.
+#
+# At six levels this overlaps the parameter line above, so some controls reach production twice.
+# That is deliberate - it is the harmless place to put the overlap, since a repeated control
+# carries the same value and the logger discards anything with "set" in it. There is no way to
+# write "six levels but not a control", as MQTT patterns cannot exclude.
+topic <org>/+/+/set/# both 1
+
+# Loop protection is Mosquitto's "try_private", on by default, which tells production that this is
+# a bridge and not an ordinary client so that it never echoes our own messages back at us. Both
+# ends must be Mosquitto for that to hold - it was measured working between 2.0.21 and itself.
+# TODO revisit if production ever moves to a different broker, or if a third broker is ever
+# bridged into the same topics, as neither case is covered by that protection.