frugal-iot-server 0.3.7 → 0.3.8

package/scripts/addbridge-pi.zsh

@@ -0,0 +1,164 @@
+#!/usr/bin/env zsh
+#
+# Bridge this Pi's broker to a production Frugal IoT server. RUN THIS ON THE PI.
+#
+# After this, the Pi's readings also appear on the production server, and its nodes can be
+# controlled from there - while the Pi carries on recording and serving on its own whenever the
+# link is down. Readings taken during an outage stay on the Pi: production gets a gap rather than
+# a backlog delivered later with the wrong timestamps. INSTALLATION.md step 11 explains why.
+#
+# The relaying is done by the broker, so the server, the logger and the nodes are untouched.
+#
+# Run the companion script on the production server first - "frugal-iot-addbridge-prod" - which
+# creates the account this needs and tells you the password.
+#
+# Run from the server's own directory, the one holding frugal-iot.db.
+#
+# Usage:
+#   npx --no frugal-iot-addbridge-pi --org <org-id> --host <prod-host> --account <account> [--replace]
+#   scripts/addbridge-pi.zsh --org myfarm --host prod.example.org --account bridge-northfield
+#
+# The password is asked for rather than passed on the command line, so it does not end up in your
+# shell history. Give it with --password only for an unattended run.
+
+set -euo pipefail
+
+SCRIPT_NAME=$0
+
+usage() {
+  echo "Usage: ${SCRIPT_NAME} --org <org-id> --host <prod-host> --account <account> [--port N] [--password PW] [--replace]" >&2
+  echo "Example: ${SCRIPT_NAME} --org myfarm --host prod.example.org --account bridge-northfield" >&2
+  exit 1
+}
+
+ORG_ID=""; PROD_HOST=""; ACCOUNT=""; PASSWORD=""; PROD_PORT=8883; REPLACE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --org)      ORG_ID=${2:-}; shift 2 ;;
+    --host)     PROD_HOST=${2:-}; shift 2 ;;
+    --account)  ACCOUNT=${2:-}; shift 2 ;;
+    --password) PASSWORD=${2:-}; shift 2 ;;
+    --port)     PROD_PORT=${2:-}; shift 2 ;;
+    --replace)  REPLACE=true; shift ;;
+    *) echo "Error: unexpected argument '$1'" >&2; usage ;;
+  esac
+done
+
+[[ -z "$ORG_ID" || -z "$PROD_HOST" || -z "$ACCOUNT" ]] && usage
+
+BRIDGE_CONF=/etc/mosquitto/conf.d/frugal-iot-bridge.conf
+
+# This Pi has to know the organization too, or its own logger will not be recording what it relays.
+if [[ ! -f "config.d/organizations/${ORG_ID}.yaml" ]]; then
+  echo "Error: no config.d/organizations/${ORG_ID}.yaml here." >&2
+  echo "Run this from the server's own directory, and check the organization id matches the one" >&2
+  echo "used on the production server - it is the first element of every topic, so the two ends" >&2
+  echo "must agree exactly." >&2
+  exit 1
+fi
+
+if [[ -e "$BRIDGE_CONF" && "$REPLACE" != true ]]; then
+  echo "Error: ${BRIDGE_CONF} already exists - this Pi is already bridged." >&2
+  echo "Add --replace to overwrite it, or edit it by hand." >&2
+  exit 1
+fi
+
+# The example file ships with the server, so look beside this script rather than guessing a path -
+# that works both for an npm install and for a git checkout.
+EXAMPLE="${SCRIPT_NAME:A:h}/../extras/mosquitto-bridge.conf.example"
+if [[ ! -f "$EXAMPLE" ]]; then
+  echo "Error: cannot find mosquitto-bridge.conf.example (looked at ${EXAMPLE})" >&2
+  exit 1
+fi
+
+if [[ -z "$PASSWORD" ]]; then
+  echo -n "Password for ${ACCOUNT} on ${PROD_HOST} (not echoed): "
+  read -rs PASSWORD
+  echo ""
+  if [[ -z "$PASSWORD" ]]; then
+    echo "Error: no password given" >&2
+    exit 1
+  fi
+fi
+
+# Check the far end is reachable and its certificate checks out, before writing anything. Getting
+# this wrong is the usual reason a bridge silently fails to connect, and the broker's own log is
+# the only place it says so.
+if command -v openssl >/dev/null; then
+  echo "Checking ${PROD_HOST}:${PROD_PORT} ..."
+  if echo | openssl s_client -connect "${PROD_HOST}:${PROD_PORT}" -servername "$PROD_HOST" \
+       -verify_hostname "$PROD_HOST" -verify_return_error >/dev/null 2>&1; then
+    echo "  reachable, and the certificate is valid for that name"
+  else
+    echo "Warning: could not complete a TLS handshake with ${PROD_HOST}:${PROD_PORT}." >&2
+    echo "  Either the port is not open, or the certificate is not valid for that name." >&2
+    echo "  Carrying on - the bridge will keep retrying - but it will not connect until that is fixed." >&2
+  fi
+fi
+
+# Fill in the example. Everything the bridge needs, including why each setting is what it is, is in
+# the comments of that file, so it is copied whole rather than reduced to the active lines.
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+sed -e "s|<prod-host>:8883|${PROD_HOST}:${PROD_PORT}|" \
+    -e "s|<bridge-account>|${ACCOUNT}|g" \
+    -e "s|<bridge-password>|${PASSWORD}|" \
+    -e "s|<org>/|${ORG_ID}/|g" \
+    -e "s|^# Replace <org> in all four lines with the organization id - the first element of every topic, and|# The organization here is \"${ORG_ID}\" - the first element of every topic, and|" \
+    "$EXAMPLE" > "$TMP"
+
+if grep -qE '<(prod-host|bridge-account|bridge-password)>' "$TMP"; then
+  echo "Error: some placeholders were not filled in - not installing. This is a bug in this script" >&2
+  echo "  or in extras/mosquitto-bridge.conf.example." >&2
+  exit 1
+fi
+
+# Mode 600 because it holds the password. Mosquitto reads its configuration as root, before
+# dropping privileges, so it can still read it - unlike the TLS key, which it reads afterwards.
+echo "Writing ${BRIDGE_CONF} ..."
+sudo install -o root -g root -m 600 "$TMP" "$BRIDGE_CONF"
+
+# A restart, not a reload: mosquitto does not pick up bridges on a reload signal. Every node
+# reconnects on its own afterwards.
+echo "Restarting mosquitto (nodes will reconnect on their own) ..."
+sudo systemctl restart mosquitto
+sleep 4
+
+if [[ "$(systemctl is-active mosquitto 2>/dev/null)" != "active" ]]; then
+  echo "Error: mosquitto did not come back up. Its own log says why:" >&2
+  echo "  sudo tail -20 /var/log/mosquitto/mosquitto.log" >&2
+  echo "To undo this: sudo rm ${BRIDGE_CONF} && sudo systemctl restart mosquitto" >&2
+  exit 1
+fi
+
+# Did it actually connect? The bridge publishes a retained 1 or 0 here whenever that changes, so
+# this is the real answer rather than the absence of an error.
+STATE=""
+if command -v mosquitto_sub >/dev/null; then
+  ORG_PW=$(sed -n 's/^mqtt_password:[[:space:]]*//p' "config.d/organizations/${ORG_ID}.yaml" | head -1 | tr -d '"'"'"'') || true
+  for attempt in 1 2 3 4 5; do
+    # "|| true" because mosquitto_sub always exits non-zero when -W times out, and under "set -e"
+    # that ends this script here - silently, after the restart, without ever printing the verdict
+    # below. Likewise "if" rather than "&& break", whose false case is a non-zero last command.
+    STATE=$(mosquitto_sub -h localhost -u "$ORG_ID" -P "$ORG_PW" \
+      -t "\$SYS/broker/connection/${ACCOUNT}/state" -W 3 2>/dev/null | tail -1) || true
+    if [[ "$STATE" == "1" ]]; then break; fi
+    sleep 3
+  done
+fi
+
+echo ""
+if [[ "$STATE" == "1" ]]; then
+  echo "Connected. This Pi is now relaying ${ORG_ID} to ${PROD_HOST}."
+elif [[ -z "$STATE" ]]; then
+  echo "Installed, but this script could not tell whether it connected."
+  echo "Check with:  npx --no frugal-iot-diagnostic"
+else
+  echo "Installed, but not connected yet (state=${STATE})."
+  echo "It keeps retrying, so a wrong password or an unreachable port will show up in the log:"
+  echo "  sudo tail -20 /var/log/mosquitto/mosquitto.log"
+  echo "and the state is reported by:  npx --no frugal-iot-diagnostic"
+fi
+echo ""
+echo "The readings this Pi has already recorded stay here - only new ones are relayed."

package/scripts/addbridge-prod.zsh

@@ -0,0 +1,215 @@
+#!/usr/bin/env zsh
+#
+# Authorize a Raspberry Pi to bridge into this server. RUN THIS ON THE PRODUCTION SERVER.
+#
+# A bridge relays a Pi's readings to this server, so the same nodes appear on a dashboard here and
+# can be controlled from here, while the Pi carries on working on its own when the link is down.
+# This end of it is one broker account and one access-control rule. The Pi end is a configuration
+# file, written by the companion script - "frugal-iot-addbridge-pi", run on the Pi.
+#
+# Each Pi gets its own account rather than sharing the organization's, for two reasons: the
+# organization's broker password is handed to every browser that logs in, so it is not a secret;
+# and a per-Pi account can be confined to one site's topics and revoked without disturbing anyone.
+#
+# Run from the server's own directory, the one holding frugal-iot.db.
+#
+# Usage:
+#   npx --no frugal-iot-addbridge-prod <org-id> <site-name> [password]
+#   scripts/addbridge-prod.zsh <org-id> <site-name> [password]
+# Example:
+#   npx --no frugal-iot-addbridge-prod myfarm northfield
+#
+# The site name only distinguishes one Pi from another within an organization, and becomes part of
+# the account name ("bridge-northfield"). With no password given, a strong one is generated and
+# printed - it is needed once, to type into the Pi.
+#
+# This assumes the server has already been set up to accept bridges at all: a TLS listener on 8883
+# with a certificate. That is a one-off, and INSTALLATION.md step 11 covers it.
+
+set -euo pipefail
+
+SCRIPT_NAME=$0
+
+usage() {
+  echo "Usage: ${SCRIPT_NAME} <org-id> <site-name> [password]" >&2
+  echo "Example: ${SCRIPT_NAME} myfarm northfield" >&2
+  exit 1
+}
+
+if [[ $# -lt 2 || $# -gt 3 ]]; then
+  usage
+fi
+
+ORG_ID=$1
+SITE=$2
+PASSWORD=${3:-}
+
+if [[ ! "$ORG_ID" =~ ^[a-z0-9]{1,10}$ ]]; then
+  echo "Error: org id must be 1-10 lower-case letters/digits, got '${ORG_ID}'" >&2
+  exit 1
+fi
+# The site name ends up in an account name and in an ACL file, so keep it to something that cannot
+# be mistaken for syntax in either
+if [[ ! "$SITE" =~ ^[a-z0-9-]{1,20}$ ]]; then
+  echo "Error: site name must be 1-20 lower-case letters, digits or hyphens, got '${SITE}'" >&2
+  exit 1
+fi
+
+ACCOUNT="bridge-${SITE}"
+CONFIG_FILE="config.d/organizations/${ORG_ID}.yaml"
+
+# The organization has to exist here, or the readings will arrive and nothing will record them:
+# this server's logger subscribes per organization, driven by these files.
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "Error: no ${CONFIG_FILE} - organization '${ORG_ID}' is not configured on this server." >&2
+  echo "Its readings would arrive at the broker and nothing would record them. Add it first:" >&2
+  echo "  npx --no frugal-iot-addorganization ${ORG_ID} \"<name>\" <email> <phone> \"<password>\"" >&2
+  exit 1
+fi
+
+if ! command -v mosquitto_passwd >/dev/null; then
+  echo "Error: mosquitto_passwd not found - is mosquitto installed on this machine?" >&2
+  exit 1
+fi
+
+# Which files the running broker actually uses, rather than where they usually are. Only ".conf"
+# files in conf.d are read, and the last setting wins.
+MOSQ_CONFS=(/etc/mosquitto/mosquitto.conf(N) /etc/mosquitto/conf.d/*.conf(N))
+if (( ${#MOSQ_CONFS} == 0 )); then
+  echo "Error: no mosquitto configuration found in /etc/mosquitto" >&2
+  exit 1
+fi
+# Read one setting out of the broker's configuration. Two things to be careful of: a conf.d file
+# can be root-only (a bridge configuration holds a password, so it should be), which makes grep
+# fail rather than return nothing - and under "set -e" a failing command substitution would end
+# this script silently, before it had printed anything at all. Hence "|| true" and the sudo retry.
+mosq_setting() {
+  local out
+  out=$(grep -hE "^[[:space:]]*$1[[:space:]]" "${MOSQ_CONFS[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
+  if [[ -z "$out" ]] && command -v sudo >/dev/null; then
+    out=$(sudo grep -hE "^[[:space:]]*$1[[:space:]]" "${MOSQ_CONFS[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
+  fi
+  print -r -- "$out"
+}
+PWFILE=$(mosq_setting password_file)
+ACLFILE=$(mosq_setting acl_file)
+
+if [[ -z "$PWFILE" ]]; then
+  echo "Error: no password_file in the mosquitto configuration - this broker is not using accounts." >&2
+  exit 1
+fi
+if [[ ! -e "$PWFILE" ]]; then
+  echo "Error: mosquitto names ${PWFILE} as its password file but it does not exist." >&2
+  exit 1
+fi
+
+# The account names in the password file. Needs the same sudo retry as the settings above: the
+# password file is normally mode 600 owned by the broker's own user, so reading it as anyone else
+# silently returns nothing - which would look exactly like "this account does not exist yet".
+account_exists() {
+  local names
+  names=$(cut -d: -f1 "$PWFILE" 2>/dev/null) || true
+  if [[ -z "$names" ]] && command -v sudo >/dev/null; then
+    names=$(sudo cut -d: -f1 "$PWFILE" 2>/dev/null) || true
+  fi
+  print -r -- "$names" | grep -qx "$1"
+}
+
+# Refuse to rotate the password of a bridge that is presumably working: the Pi holds the old one,
+# and it would stop relaying the moment this changed without anyone touching the Pi.
+if account_exists "$ACCOUNT"; then
+  echo "Error: account '${ACCOUNT}' already exists in ${PWFILE}." >&2
+  echo "If a Pi is already using it, leave it alone. To give it a new password, run" >&2
+  echo "mosquitto_passwd as the owner of that file - as root it rewrites the file owned by root," >&2
+  echo "and the broker, which reads it as the mosquitto user, then will not start:" >&2
+  echo "  sudo -u \"\$(stat -c '%U' ${PWFILE})\" mosquitto_passwd -b ${PWFILE} ${ACCOUNT} '<new password>'" >&2
+  echo "and then update /etc/mosquitto/conf.d/frugal-iot-bridge.conf on that Pi to match." >&2
+  exit 1
+fi
+
+if [[ -z "$PASSWORD" ]]; then
+  # Unlike the organization's broker password, this one is never given to a browser - it lives only
+  # in a root-owned file on the Pi - so it can and should be a real one.
+  # The subshell turns pipefail off: head closes the pipe after 24 characters, tr is killed by
+  # SIGPIPE, and with pipefail on that failure would end this script before it printed anything.
+  # install-pi.sh's randpw does the same for the same reason.
+  PASSWORD=$( set +o pipefail; LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 24 )
+  GENERATED=true
+else
+  GENERATED=false
+fi
+
+# Run mosquitto_passwd as whoever owns the password file, the same way addorganization.zsh does.
+# Running it as root instead rewrites the file owned by root, and mosquitto drops to the mosquitto
+# user *before* reading it - so the broker then cannot read its own password file and refuses to
+# start, with an error that says nothing about ownership. mosquitto_passwd also writes a temporary
+# backup beside the file, so it needs the directory and not only the file.
+MOSQ_PASSWD_CMD=(mosquitto_passwd)
+if [[ ! -w "${PWFILE:h}" || ( -e "$PWFILE" && ! -w "$PWFILE" ) ]]; then
+  if command -v sudo >/dev/null; then
+    # stat's spelling differs between Linux (-c) and BSD/macOS (-f)
+    PWFILE_OWNER=$(stat -c '%U' "$PWFILE" 2>/dev/null || stat -f '%Su' "$PWFILE" 2>/dev/null || true)
+    if [[ -n "$PWFILE_OWNER" && "$PWFILE_OWNER" != "$(id -un)" && "$PWFILE_OWNER" != "root" ]]; then
+      MOSQ_PASSWD_CMD=(sudo -u "$PWFILE_OWNER" mosquitto_passwd)
+    else
+      MOSQ_PASSWD_CMD=(sudo mosquitto_passwd)
+    fi
+  fi
+fi
+
+echo "Creating broker account ${ACCOUNT} in ${PWFILE} ..."
+if ! $MOSQ_PASSWD_CMD -b "$PWFILE" "$ACCOUNT" "$PASSWORD"; then
+  echo "Error: mosquitto_passwd failed - nothing has been changed." >&2
+  exit 1
+fi
+
+# The access control rule. Without one the account can connect and reach nothing at all, because a
+# mosquitto acl_file is deny-by-default.
+if [[ -n "$ACLFILE" ]]; then
+  if [[ ! -e "$ACLFILE" ]]; then
+    echo "Error: mosquitto names ${ACLFILE} as its ACL file but it does not exist." >&2
+    echo "The account has been created but cannot reach anything until that is sorted out." >&2
+    exit 1
+  fi
+  if sudo grep -qE "^[[:space:]]*user[[:space:]]+${ACCOUNT}[[:space:]]*$" "$ACLFILE"; then
+    echo "ACL rule for ${ACCOUNT} is already in ${ACLFILE} - leaving it alone."
+  else
+    echo "Adding ACL rule to ${ACLFILE} ..."
+    sudo tee -a "$ACLFILE" >/dev/null <<EOF
+
+# Pi bridge for site "${SITE}", confined to its organization's topics
+user ${ACCOUNT}
+topic readwrite ${ORG_ID}/#
+EOF
+  fi
+else
+  echo ""
+  echo "NOTE: this broker has no acl_file, so ${ACCOUNT} can reach every topic on it, not just"
+  echo "  ${ORG_ID}/#. That is how the broker already treats every other account, so this is no"
+  echo "  worse than what is there - but see INSTALLATION.md step 11 for restricting it."
+fi
+
+# password_file and acl_file are both re-read on a reload, so nothing needs to be disconnected.
+echo "Reloading mosquitto ..."
+sudo systemctl reload mosquitto || {
+  echo "Warning: reload failed - the account exists but the broker has not re-read the files." >&2
+  echo "  Try: sudo systemctl restart mosquitto" >&2
+}
+
+echo ""
+echo "Done. On the Pi at site '${SITE}', run:"
+echo ""
+echo "  npx --no frugal-iot-addbridge-pi --org ${ORG_ID} --host $(hostname -f 2>/dev/null || hostname) --account ${ACCOUNT}"
+echo ""
+echo "It will ask for this password:"
+echo ""
+echo "  ${PASSWORD}"
+echo ""
+if [[ "$GENERATED" == true ]]; then
+  echo "That was generated just now and is not stored anywhere you can read it back - copy it before"
+  echo "you lose this output. If it does get lost, set a new one with:"
+  echo "  sudo -u \"\$(stat -c '%U' ${PWFILE})\" mosquitto_passwd -b ${PWFILE} ${ACCOUNT} '<new password>'"
+  echo "and use that on the Pi instead."
+fi
+echo "Check the host name above is one the Pi can reach, and that it is the name on the"
+echo "certificate - the Pi verifies it."

package/scripts/check-schema.js

@@ -21,12 +21,25 @@
  *  - A module topic overriding a field that its topic does not define, which is usually a
  *    misspelling.
  *
+ *  - A float or exponential topic with no "width", or one too small to hold its own min..max. Width
+ *    is what decides how many decimals a reading is shown to; without it the UI guesses.
+ *
+ *  - A numeric topic with no "units". Often right - plenty of readings are dimensionless - but
+ *    worth a look, because the UI has nothing to put after the number.
+ *
+ * And, separately, things that are never deliberate and so count as errors:
+ *
+ *  - A devices.yaml entry naming a module, or a leaf within a module, that does not exist. That
+ *    silently loses a row from a card, with nothing to say why.
+ *
  * Usage:
  *   node scripts/check-schema.js                     # checks ./config.d/schema
  *   node scripts/check-schema.js <dir> [<dir> ...]   # each dir holding topics.yaml and modules.yaml
+ *   node scripts/check-schema.js --resolve <otakey>  # which devices.yaml entry that OTA key uses
  *
- * Exits 0 whatever it finds, so it can run from a prerelease script without blocking a release for
- * something that may well be deliberate. Exits 1 only if it could not read a schema at all.
+ * Exits 0 for warnings, so it can run from a prerelease script without blocking a release for
+ * something that may well be deliberate. Exits 1 for an error, or if it could not read a schema.
+ * Both callers guard it with "|| true", so neither blocks on either.
  */
 
 import yaml from 'js-yaml';
@@ -36,6 +49,8 @@ import path from 'path';
 // The types the logger records when a topic does not say - keep in step with shouldLog() in
 // frugal-iot-logger/index.js
 const TYPES_LOGGED_BY_DEFAULT = ['float', 'int', 'bool'];
+// The types with decimals to decide, and so the ones that need a width
+const NUMERIC_TYPES = ['float', 'exponential'];
 
 function loadYaml(file) {
   if (!existsSync(file)) return null;
@@ -48,9 +63,11 @@ function loadYaml(file) {
  */
 function checkSchemaDir(dir) {
   const topics = loadYaml(path.join(dir, 'topics.yaml'));
-  if (topics === null) return [`${dir}/topics.yaml does not exist`];
+  if (topics === null) return { warnings: [`${dir}/topics.yaml does not exist`], errors: [], missing: true };
   const modules = loadYaml(path.join(dir, 'modules.yaml')) || {};
+  const devices = loadYaml(path.join(dir, 'devices.yaml')) || {};
   const warnings = [];
+  const errors = [];
 
   for (const [name, topic] of Object.entries(topics)) {
     if (!topic || (typeof topic !== 'object')) {
@@ -76,6 +93,28 @@ function checkSchemaDir(dir) {
       warnings.push(`topic "${name}" has a "duplicates" rule setting neither significantvalue nor`
         + ` significantdate, so it does nothing`);
     }
+    // Width decides the decimals a reading is shown to, derived as width - intWidth - 1 where
+    // intWidth comes from min..max. Only a float has decimals to decide.
+    const hasDecimals = NUMERIC_TYPES.includes(topic.type);
+    if (hasDecimals && (topic.width === undefined)) {
+      warnings.push(`topic "${name}" is a ${topic.type} with no "width", so the UI has to guess how`
+        + ` many decimals to show. Width counts every character including the sign and the point.`);
+    }
+    if (!hasDecimals && (topic.width !== undefined)) {
+      warnings.push(`topic "${name}" is a ${topic.type}, which has no decimals, so "width" does nothing`);
+    }
+    if (hasDecimals && (topic.width !== undefined)) {
+      const intWidth = Math.max(String(Math.trunc(topic.min ?? 0)).length,
+                                String(Math.trunc(topic.max ?? 0)).length);
+      if (topic.width < intWidth) {
+        warnings.push(`topic "${name}" has width ${topic.width} but its range needs ${intWidth}`
+          + ` characters before any decimal point, so values will overflow it`);
+      }
+    }
+    if (hasDecimals && (topic.units === undefined)) {
+      warnings.push(`topic "${name}" has no "units" - fine if it is dimensionless, but the UI has`
+        + ` nothing to put after the number`);
+    }
   }
 
   // A module topic can override any field of the topic it is built from. A field the topic does not
@@ -98,30 +137,102 @@ function checkSchemaDir(dir) {
       }
     }
   }
-  return warnings;
+  // A device entry picks the rows on a card, by twig (module/leaf) or by bare control module id.
+  // Naming something that does not exist loses a row silently, so these are errors not warnings.
+  for (const [key, device] of Object.entries(devices)) {
+    for (const listName of ['front', 'summary']) {
+      for (const entry of ((device && device[listName]) || [])) {
+        const [moduleName, leaf] = entry.split('/');
+        const module = modules[moduleName];
+        if (!module) {
+          errors.push(`devices "${key}" ${listName} names module "${moduleName}", which is not in modules.yaml`);
+        } else if (leaf !== undefined) {
+          const leaves = ((module.topics) || []).map((t) => t.leaf);
+          if (!leaves.includes(leaf)) {
+            errors.push(`devices "${key}" ${listName} names "${entry}", but module "${moduleName}"`
+              + ` has ${leaves.length ? leaves.join(', ') : 'no leaves'}`);
+          }
+        } else if (!moduleName.startsWith('control')) {
+          warnings.push(`devices "${key}" ${listName} names module "${moduleName}" with no leaf.`
+            + ` Only a control module renders as a whole - did you mean a "${moduleName}/leaf" twig?`);
+        }
+      }
+    }
+    // Longest match wins, so this is not a fault - but it is worth knowing which entry a key lands on
+    const shadowed = Object.keys(devices).filter((k) => (k !== key) && k.startsWith(key));
+    if (shadowed.length) {
+      warnings.push(`devices "${key}" is also a prefix of ${shadowed.join(', ')}; the longest match`
+        + ` wins, so those take precedence for their own keys`);
+    }
+  }
+
+  // summary is opt-out - a module contributes unless it says otherwise
+  for (const [moduleName, module] of Object.entries(modules)) {
+    if (module && (module.summary === true)) {
+      warnings.push(`module "${moduleName}" sets "summary: true", which is already the default -`
+        + ` only "summary: false" does anything`);
+    }
+  }
+
+  return { warnings, errors };
+}
+
+// Which devices.yaml entry an OTA key uses: exact device id, then exact key, then longest prefix.
+function resolveDeviceEntry(devices, otakey) {
+  if (devices[otakey]) return [otakey, 'an exact match'];
+  const prefixes = Object.keys(devices).filter((k) => otakey.startsWith(k));
+  if (!prefixes.length) return [null, 'no match, so the defaults apply'];
+  const longest = prefixes.sort((a, b) => b.length - a.length)[0];
+  return [longest, prefixes.length > 1 ? `the longest of ${prefixes.length} matching prefixes` : 'a prefix'];
 }
 
-const dirs = (process.argv.length > 2) ? process.argv.slice(2) : ['config.d/schema'];
+const argv = process.argv.slice(2);
+const resolveAt = argv.indexOf('--resolve');
+if (resolveAt !== -1) {
+  const otakey = argv[resolveAt + 1];
+  const dir = argv.find((a, i) => !a.startsWith('--') && (i !== resolveAt + 1)) || 'config.d/schema';
+  if (!otakey) {
+    console.error('--resolve needs an OTA key, e.g. --resolve sht30_c3_pico');
+    process.exit(1);
+  }
+  const devices = loadYaml(path.join(dir, 'devices.yaml')) || {};
+  const [entry, how] = resolveDeviceEntry(devices, otakey);
+  console.log(`${otakey} uses ${entry ? `the "${entry}" entry` : 'no entry'} (${how})`);
+  process.exit(0);
+}
+
+const dirs = argv.length ? argv : ['config.d/schema'];
 let unreadable = 0;
-let total = 0;
+let totalWarnings = 0;
+let totalErrors = 0;
 
 for (const dir of dirs) {
-  const warnings = checkSchemaDir(dir);
-  if ((warnings.length === 1) && warnings[0].endsWith('does not exist')) {
+  const { warnings, errors, missing } = checkSchemaDir(dir);
+  if (missing) {
     console.error(`${dir}: ${warnings[0]}`);
     unreadable++;
     continue;
   }
-  if (!warnings.length) {
+  if (!warnings.length && !errors.length) {
     console.log(`${dir}: nothing to report`);
     continue;
   }
-  console.log(`${dir}: ${warnings.length} thing(s) worth a look`);
-  for (const w of warnings) console.log(`  ${w}`);
-  total += warnings.length;
+  if (warnings.length) {
+    console.log(`${dir}: ${warnings.length} thing(s) worth a look`);
+    for (const w of warnings) console.log(`  ${w}`);
+  }
+  if (errors.length) {
+    console.log(`${dir}: ${errors.length} thing(s) that cannot be right`);
+    for (const e of errors) console.log(`  ERROR ${e}`);
+  }
+  totalWarnings += warnings.length;
+  totalErrors += errors.length;
 }
 
-if (total) {
-  console.log(`\n${total} warning(s) - these are for you to decide about, nothing has been changed.`);
+if (totalWarnings) {
+  console.log(`\n${totalWarnings} warning(s) - these are for you to decide about, nothing has been changed.`);
+}
+if (totalErrors) {
+  console.log(`${totalErrors} error(s) - a card will silently lose a row until these are fixed.`);
 }
-process.exit(unreadable ? 1 : 0);
+process.exit((unreadable || totalErrors) ? 1 : 0);