signalk-automation-plugin 0.0.1 → 0.0.3

package/README.md

@@ -11,7 +11,8 @@ Not Node-RED. Not a Home Assistant YAML clone. Actions are Signal K PUTs, helper
   - `restore` — survive reboot (save in plugin data, restore on start)
   - `default` — set `default` on every start
   - `none` — do nothing on start
-- Path triggers, `choose`, zones, cron `schedule`
+- Path triggers, `choose`, zones, cron `schedule` (trigger list is **any**; conditions are **all**)
+- Trigger `round:` quantizes numbers (and lat/lon) so 230.1 V and 230.4 V do not both fire
 - Actions: `put`, `helper`, `notify`, `delay`, `run`
 - `run:` executes a file under configured `scriptsDir`. **stdout is the value; any stderr is fail**
 - Webapp: per-automation on/off, last result, last N decision records, live YAML, activate another git commit
@@ -35,7 +36,7 @@ Do not paste automations into the admin form. Runtime state is `~/.signalk/plugi
 
 ## Example
 
-See `examples/automations.yaml`. Copy or point `automationsDir` at a repo of your own; bundled examples are `enabled: false`.
+See `examples/automations.yaml`. Boatnet live YAML is `git@github.com:htool/boatnet_automations.git` (`automationsDir` on the Pi). On/off and Verbose are plugin-data switches, not YAML keys.
 
 ```yaml
 helpers:
@@ -46,18 +47,25 @@ helpers:
     latch_on_external_put: electrical.switches.starlink.state
 
 automations:
-  - id: start_anchorwatch
+  - id: starlink_standby
     trigger:
-      - path: winches.windlass.rode
-        above: 2
-        unit: m
-        for: 10s
+      - schedule: "0 4 * * *"
+    condition:
+      - zone: home_harbour
+      - helper: starlink_manual
+        is: false
     action:
-      - put: navigation.anchor.watch
+      - put: electrical.switches.starlink.state
         value: true
+      - delay: 15m
+      - put: electrical.switches.starlink.state
+        value: false
 ```
 
-Script action:
+```yaml
+- path: electrical.switches.dolphinCharger.voltage
+  round: 1          # nearest volt; 230.1 and 230.4 do not both fire
+```
 
 ```yaml
 - run:

package/examples/automations.yaml

@@ -5,54 +5,69 @@ helpers:
     default: false
     on_start: restore
     latch_on_external_put: electrical.switches.starlink.state
-  charge_hold:
+  depart_prep:
     type: boolean
-    name: Thuis 60–80% laden
-    default: true
-    on_start: default
-
-zones:
-  home_harbour:
-    name: Thuishaven
-    lat: 52.37
-    lon: 5.22
-    radius: 150
+    name: Maak klaar voor vertrek
+    default: false
+    on_start: restore
 
 automations:
-  - id: start_anchorwatch
-    alias: Ketting uit → anchorwatch
-    enabled: false
-    trigger:
-      - path: winches.windlass.rode
-        above: 2
-        unit: m
-        for: 10s
-    action:
-      - put: navigation.anchor.watch
-        value: true
-
   - id: shore_charge
     alias: Walstroom laadbeleid
-    enabled: false
+    zones:
+      home_harbour:
+        name: Thuishaven
+        lat: 52.37
+        lon: 5.22
+        radius: 150
     trigger:
-      - path: electrical.chargers.shore.connected
+      - path: sensors.presence.dolphinshelly
       - path: electrical.batteries.house.capacity.stateOfCharge
-      - path: navigation.position
+        round: 0.01
+      - helper: depart_prep
     choose:
       - alias: onderweg volladen
         conditions:
-          - path: electrical.chargers.shore.connected
+          - path: sensors.presence.dolphinshelly
             is: true
           - not:
               zone: home_harbour
         action:
           - put: electrical.switches.dolphinCharger.state
             value: 1
+      - alias: klaar voor vertrek laden
+        conditions:
+          - path: sensors.presence.dolphinshelly
+            is: true
+          - zone: home_harbour
+          - helper: depart_prep
+            is: true
+          - path: electrical.batteries.house.capacity.stateOfCharge
+            below: 0.98
+        action:
+          - put: electrical.switches.dolphinCharger.state
+            value: 1
+      - alias: klaar voor vertrek vol
+        conditions:
+          - path: sensors.presence.dolphinshelly
+            is: true
+          - zone: home_harbour
+          - helper: depart_prep
+            is: true
+          - path: electrical.batteries.house.capacity.stateOfCharge
+            above: 0.97
+        action:
+          - put: electrical.switches.dolphinCharger.state
+            value: 0
+          - helper: depart_prep
+            value: false
       - alias: thuis onder 60%
         conditions:
-          - path: electrical.chargers.shore.connected
+          - path: sensors.presence.dolphinshelly
             is: true
           - zone: home_harbour
+          - helper: depart_prep
+            is: false
           - path: electrical.batteries.house.capacity.stateOfCharge
             below: 0.6
         action:
@@ -60,7 +75,11 @@ automations:
             value: 1
       - alias: thuis boven 80%
         conditions:
+          - path: sensors.presence.dolphinshelly
+            is: true
           - zone: home_harbour
+          - helper: depart_prep
+            is: false
           - path: electrical.batteries.house.capacity.stateOfCharge
             above: 0.8
         action:
@@ -69,10 +88,11 @@ automations:
 
   - id: starlink_standby
     alias: Starlink standby-update
-    enabled: false
     trigger:
       - schedule: "0 4 * * *"
     condition:
+      # home_harbour is defined on shore_charge (Walstroom laadbeleid).
+      - zone: home_harbour
       - helper: starlink_manual
         is: false
     action:
@@ -81,18 +101,3 @@ automations:
       - delay: 15m
       - put: electrical.switches.starlink.state
         value: false
-
-  - id: harbour_via_script
-    alias: Voorbeeld script-conditie
-    enabled: false
-    trigger:
-      - path: electrical.chargers.shore.connected
-        is: true
-    condition:
-      - run: echo.sh
-        equals: home
-    action:
-      - notify:
-          path: electrical.chargers.shore
-          state: normal
-          message: script said home

package/lib/engine.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { toSi, parseDuration } = require('./units')
-const { inZone } = require('./geo')
+const { inZone, positionLatLon, zoneDistanceM } = require('./geo')
 const { runScript } = require('./scripts')
 const { helperPath } = require('./helpers')
 
@@ -12,7 +12,9 @@ function collectPaths (doc) {
     for (const c of auto.condition || []) addPathsFromClause(paths, c)
     for (const branch of auto.choose || []) {
       for (const c of branch.conditions || []) addPathsFromClause(paths, c)
+      for (const action of branch.action || []) addPathsFromAction(paths, action)
     }
+    for (const action of auto.action || []) addPathsFromAction(paths, action)
     if (auto.latch_on_external_put) paths.add(auto.latch_on_external_put)
   }
   for (const def of Object.values(doc.helpers || {})) {
@@ -31,6 +33,12 @@ function addPathsFromClause (paths, clause) {
   if (Array.isArray(clause.any)) clause.any.forEach((c) => addPathsFromClause(paths, c))
 }
 
+function addPathsFromAction (paths, action) {
+  if (!action || typeof action !== 'object') return
+  if (action.put) paths.add(action.put)
+  if (action.valueFrom) paths.add(action.valueFrom)
+}
+
 function getByPath (values, p) {
   if (Object.prototype.hasOwnProperty.call(values, p)) return values[p]
   return undefined
@@ -81,11 +89,20 @@ function evalClause (clause, ctx) {
   if (clause.zone) {
     const pos = getByPath(ctx.values, 'navigation.position')
     const zone = ctx.zones[clause.zone]
+    const ll = positionLatLon(pos)
+    const distanceM = zone ? zoneDistanceM(pos, zone) : null
     const pass = zone ? inZone(pos, zone) : false
     return {
       pass,
-      error: zone ? null : 'Unknown zone: ' + clause.zone,
-      actual: pos,
+      error: zone ? (ll ? null : 'no GPS position') : 'Unknown zone: ' + clause.zone,
+      actual: ll
+        ? {
+            lat: ll.lat,
+            lon: ll.lon,
+            distance_m: distanceM == null ? null : Math.round(distanceM * 10) / 10,
+            radius_m: zone ? Number(zone.radius) : null
+          }
+        : pos == null ? null : pos,
       path: 'navigation.position',
       expected: clause.zone
     }
@@ -164,16 +181,128 @@ async function evalClauseAsync (clause, ctx) {
   }
 }
 
+function fmtVal (value) {
+  if (value === undefined) return 'unset'
+  try {
+    return JSON.stringify(value)
+  } catch (_) {
+    return String(value)
+  }
+}
+
+function clauseLabel (clause, result) {
+  if (!clause || typeof clause !== 'object') return ''
+  if (clause.not) return 'not ' + clauseLabel(clause.not, result)
+  if (Array.isArray(clause.all)) return 'all'
+  if (Array.isArray(clause.any)) return 'any'
+  if (clause.zone) {
+    const dist = result && result.actual && typeof result.actual === 'object'
+      ? result.actual.distance_m
+      : null
+    return 'zone ' + clause.zone + (dist != null ? ' (' + dist + ' m)' : '')
+  }
+  if (clause.helper) {
+    let s = 'helper ' + clause.helper
+    if (clause.is !== undefined) s += ' is ' + fmtVal(clause.is)
+    if (result && result.actual !== undefined) s += ' (' + fmtVal(result.actual) + ')'
+    return s
+  }
+  if (clause.schedule) return 'schedule ' + clause.schedule
+  if (clause.run) {
+    const file = typeof clause.run === 'string' ? clause.run : clause.run.file
+    return 'run ' + (file || '')
+  }
+  if (clause.path) {
+    let s = clause.path
+    if (clause.above !== undefined) s += ' > ' + clause.above
+    else if (clause.below !== undefined) s += ' < ' + clause.below
+    else if (clause.is !== undefined) s += ' is ' + fmtVal(clause.is)
+    else if (clause.equals !== undefined) s += ' = ' + fmtVal(clause.equals)
+    if (result && result.actual !== undefined && (typeof result.actual !== 'object' || result.actual == null)) {
+      s += ' (' + fmtVal(result.actual) + ')'
+    }
+    return s
+  }
+  return ''
+}
+
+function markPass (r) {
+  if (!r) return '✗'
+  if (r.error) return '✗'
+  return r.pass ? '✓' : '✗'
+}
+
+function withLabel (clause, result) {
+  const row = result && typeof result === 'object' ? result : { pass: false }
+  row.clause = clause
+  row.label = clauseLabel(clause, row)
+  return row
+}
+
+function triggerFiredLabel (trigger) {
+  if (!trigger) return 'evaluated'
+  if (trigger.manual) return 'manual Run'
+  if (trigger.start) return 'plugin start'
+  if (trigger.schedule) return 'schedule ' + trigger.schedule
+  if (trigger.path) return trigger.path + ' = ' + fmtVal(trigger.value)
+  return 'evaluated'
+}
+
+function isBarePathClause (clause) {
+  if (!clause || !clause.path) return false
+  return !['is', 'equals', 'above', 'below', 'to'].some((k) =>
+    Object.prototype.hasOwnProperty.call(clause, k)
+  )
+}
+
+function triggerListMatched (list, results) {
+  if (!(list || []).length) return true
+  return (results || []).some((r) => r.pass && !r.error)
+}
+
 async function evalList (list, ctx) {
   const results = []
   for (const clause of list || []) {
-    const r = await evalClauseAsync(clause, ctx)
+    const r = withLabel(clause, await evalClauseAsync(clause, ctx))
     results.push(r)
     if (!r.pass) return { pass: false, results }
   }
   return { pass: true, results }
 }
 
+async function evalListAll (list, ctx) {
+  const results = []
+  for (const clause of list || []) {
+    results.push(withLabel(clause, await evalClauseAsync(clause, ctx)))
+  }
+  const pass = results.every((r) => r.pass && !r.error)
+  return { pass, results }
+}
+
+function formatVerboseLog (auto, record) {
+  const name = (auto && (auto.alias || auto.id)) || (record && record.id) || 'automation'
+  const result = record.result || 'skipped'
+  const head = name + ' → ' + result + (record.reason ? ' (' + record.reason + ')' : '')
+  const lines = [head]
+  if (record.firedBy) lines.push('  trigger: ' + record.firedBy)
+  for (const r of record.triggerResults || []) {
+    if (isBarePathClause(r.clause)) continue
+    if (!r.label) continue
+    lines.push('  ' + markPass(r) + ' ' + r.label)
+  }
+  for (const r of record.conditions || []) {
+    if (!r.label) continue
+    lines.push('  ' + markPass(r) + ' ' + r.label)
+  }
+  for (const b of record.branches || []) {
+    lines.push('  ' + (b.picked ? '→ ' : '  ') + b.alias + (b.picked ? '' : ''))
+    for (const c of b.conditions || []) {
+      lines.push('    ' + markPass(c) + ' ' + (c.label || ''))
+    }
+  }
+  return lines.join('\n')
+}
+
 function triggerMatchesPath (auto, changedPath) {
   if (!changedPath) return true
   const paths = new Set()
@@ -183,6 +312,44 @@ function triggerMatchesPath (auto, changedPath) {
   return paths.has(changedPath)
 }
 
+function triggerRoundStep (auto, path) {
+  if (!path) return null
+  for (const t of auto.trigger || []) {
+    if (t && t.path === path && t.round != null) return Number(t.round)
+  }
+  return null
+}
+
+function quantizeNumber (n, step) {
+  const q = Math.round(Number(n) / step) * step
+  if (!Number.isFinite(q)) return n
+  return Number(q.toPrecision(12))
+}
+
+function quantizeValue (value, step) {
+  const s = Number(step)
+  if (!Number.isFinite(s) || s <= 0) return value
+  if (typeof value === 'number' && Number.isFinite(value)) return quantizeNumber(value, s)
+  const ll = positionLatLon(value)
+  if (ll) {
+    return {
+      latitude: quantizeNumber(ll.lat, s),
+      longitude: quantizeNumber(ll.lon, s)
+    }
+  }
+  return value
+}
+
+function quantizedUnchanged (store, auto, path, value) {
+  const step = triggerRoundStep(auto, path)
+  if (step == null || !Number.isFinite(step) || step <= 0) return false
+  const key = auto.id + '\0' + path
+  const q = JSON.stringify(quantizeValue(value, step))
+  if (store[key] === q) return true
+  store[key] = q
+  return false
+}
+
 function cronMatch (expr, date) {
   if (!expr) return false
   const parts = String(expr).trim().split(/\s+/)
@@ -216,52 +383,66 @@ function fieldMatch (field, value) {
     })
 }
 
+function finishRecord (auto, record) {
+  record.verboseLog = formatVerboseLog(auto, record)
+  return record
+}
+
 async function evaluateAutomation (auto, ctx) {
   const record = {
     ts: new Date(ctx.now || Date.now()).toISOString(),
     id: auto.id,
     result: 'skipped',
     trigger: ctx.trigger || null,
+    firedBy: triggerFiredLabel(ctx.trigger),
     conditions: [],
+    branches: [],
     choose: null,
     actions: []
   }
   if (!ctx.enabled) {
     record.reason = 'disabled'
-    return record
+    return finishRecord(auto, record)
   }
 
-  const trig = await evalList(auto.trigger || [], ctx)
+  const trig = await evalListAll(auto.trigger || [], ctx)
   record.triggerResults = trig.results
-  if ((auto.trigger || []).length && !trig.pass) {
+  if (!triggerListMatched(auto.trigger, trig.results)) {
     record.reason = 'trigger not matched'
-    return record
+    return finishRecord(auto, record)
   }
 
-  const cond = await evalList(auto.condition || [], ctx)
+  const cond = await evalListAll(auto.condition || [], ctx)
   record.conditions = cond.results
   if ((auto.condition || []).length && !cond.pass) {
     const failed = cond.results.find((r) => r.error)
     record.result = failed ? 'failure' : 'skipped'
     record.reason = failed ? failed.error : 'condition not met'
-    return record
+    return finishRecord(auto, record)
   }
 
   let actions = auto.action || []
   if (auto.choose && auto.choose.length) {
     let picked = null
     for (const branch of auto.choose) {
-      const br = await evalList(branch.conditions || [], ctx)
-      if (br.pass) {
+      const br = await evalListAll(branch.conditions || [], ctx)
+      const row = {
+        alias: branch.alias || branch.id || 'branch',
+        pass: br.pass,
+        picked: false,
+        conditions: br.results
+      }
+      if (!picked && br.pass) {
         picked = branch
-        record.choose = branch.id || branch.alias || 'branch'
+        row.picked = true
+        record.choose = row.alias
         actions = branch.action || []
-        break
       }
+      record.branches.push(row)
     }
     if (!picked) {
       record.reason = 'no matching choose branch'
-      return record
+      return finishRecord(auto, record)
     }
   }
 
@@ -271,11 +452,11 @@ async function evaluateAutomation (auto, ctx) {
     if (!ran.ok) {
       record.result = 'failure'
       record.reason = ran.error
-      return record
+      return finishRecord(auto, record)
     }
   }
   record.result = 'ok'
-  return record
+  return finishRecord(auto, record)
 }
 
 async function runAction (action, ctx) {
@@ -284,15 +465,30 @@ async function runAction (action, ctx) {
   }
   if (action.put) {
     try {
-      await ctx.put(action.put, action.value)
-      return { ok: true, type: 'put', path: action.put, value: action.value }
+      const value = Object.prototype.hasOwnProperty.call(action, 'valueFrom')
+        ? getByPath(ctx.values, action.valueFrom)
+        : action.value
+      if (Object.prototype.hasOwnProperty.call(action, 'valueFrom') && value === undefined) {
+        return { ok: false, type: 'put', path: action.put, error: 'valueFrom missing: ' + action.valueFrom }
+      }
+      const previous = getByPath(ctx.values, action.put)
+      const changed = !sameValue(previous, value)
+      if (changed || ctx.skipUnchanged === false) await ctx.put(action.put, value)
+      return {
+        ok: true,
+        type: 'put',
+        path: action.put,
+        value,
+        previous,
+        changed
+      }
     } catch (err) {
       return { ok: false, type: 'put', path: action.put, error: err.message }
     }
   }
   if (action.helper) {
     try {
-      ctx.setHelper(action.helper, action.value)
+      await ctx.setHelper(action.helper, action.value)
       return { ok: true, type: 'helper', helper: action.helper, value: action.value }
     } catch (err) {
       return { ok: false, type: 'helper', helper: action.helper, error: err.message }
@@ -309,6 +505,7 @@ async function runAction (action, ctx) {
   }
   if (action.delay != null) {
     const ms = parseDuration(action.delay)
+    if (ctx.skipDelay) return { ok: true, type: 'delay', ms, skipped: true }
     await ctx.sleep(ms)
     return { ok: true, type: 'delay', ms }
   }
@@ -326,6 +523,19 @@ async function runAction (action, ctx) {
   return { ok: false, error: 'unknown action' }
 }
 
+function sameValue (a, b) {
+  if (a === b) return true
+  if (a == null || b == null) return a === b
+  if (typeof a === 'object' || typeof b === 'object') {
+    try {
+      return JSON.stringify(a) === JSON.stringify(b)
+    } catch (_) {
+      return false
+    }
+  }
+  return false
+}
+
 function makeRunScript (opts) {
   return function (spec) {
     return runScript({
@@ -343,10 +553,19 @@ module.exports = {
   evalClause,
   evalClauseAsync,
   evalList,
+  evalListAll,
   evaluateAutomation,
   triggerMatchesPath,
+  triggerRoundStep,
+  quantizeValue,
+  quantizedUnchanged,
   cronMatch,
   runAction,
   makeRunScript,
-  parseDuration
+  parseDuration,
+  sameValue,
+  clauseLabel,
+  triggerFiredLabel,
+  triggerListMatched,
+  formatVerboseLog
 }

package/lib/geo.js

@@ -13,15 +13,23 @@ function haversineM (a, b) {
   return 2 * EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)))
 }
 
+function positionLatLon (position) {
+  if (!position || typeof position !== 'object') return null
+  const lat = Number(position.latitude != null ? position.latitude : position.lat)
+  const lon = Number(position.longitude != null ? position.longitude : position.lon)
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null
+  return { lat, lon }
+}
+
+function zoneDistanceM (position, zone) {
+  const pos = positionLatLon(position)
+  if (!pos || !zone) return null
+  return haversineM(pos, { lat: Number(zone.lat), lon: Number(zone.lon) })
+}
+
 function inZone (position, zone) {
-  if (!position || !zone) return false
-  if (!Number.isFinite(position.latitude) || !Number.isFinite(position.longitude)) {
-    return false
-  }
-  const d = haversineM(
-    { lat: position.latitude, lon: position.longitude },
-    { lat: zone.lat, lon: zone.lon }
-  )
+  const d = zoneDistanceM(position, zone)
+  if (d == null || !zone) return false
   return d <= Number(zone.radius)
 }
 
@@ -29,4 +37,4 @@ function toRad (deg) {
   return (Number(deg) * Math.PI) / 180
 }
 
-module.exports = { haversineM, inZone }
+module.exports = { haversineM, inZone, positionLatLon, zoneDistanceM }

package/lib/git.js

@@ -46,6 +46,37 @@ function currentSha (dir) {
   }
 }
 
+function repoRelPath (repoDir) {
+  const root = path.resolve(runGit(['rev-parse', '--show-toplevel'], repoDir))
+  const dir = path.resolve(repoDir)
+  const rel = path.relative(root, dir).replace(/\\/g, '/')
+  if (!rel || rel === '.') return { root, rel: '' }
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('automationsDir is outside the git repository')
+  }
+  return { root, rel }
+}
+
+function diffRange (repoDir, fromSha, toSha) {
+  if (!toSha) throw new Error('Commit sha is required')
+  if (!isGitRepo(repoDir)) throw new Error('automationsDir is not a git repository')
+  runGit(['cat-file', '-t', toSha], repoDir)
+  const from = fromSha || currentSha(repoDir)
+  if (!from || from === toSha) {
+    return { from: from || null, to: toSha, diff: '' }
+  }
+  runGit(['cat-file', '-t', from], repoDir)
+  const { root, rel } = repoRelPath(repoDir)
+  const args = ['diff', '--find-renames', from, toSha]
+  if (rel) args.push('--', rel)
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 2 * 1024 * 1024 })
+  if (r.status !== 0 && r.status !== 1) {
+    const err = (r.stderr || r.stdout || '').trim()
+    throw new Error('git diff failed: ' + err)
+  }
+  return { from, to: toSha, diff: (r.stdout || '').replace(/\s+$/, '') }
+}
+
 function archiveTreeish (repoDir, sha) {
   const root = path.resolve(runGit(['rev-parse', '--show-toplevel'], repoDir))
   const dir = path.resolve(repoDir)
@@ -108,5 +139,6 @@ module.exports = {
   listCommits,
   currentSha,
   archiveTreeish,
-  materializeCommit
+  materializeCommit,
+  diffRange
 }