signalk-automation-plugin 0.0.4 → 0.0.6

package/README.md

@@ -36,34 +36,34 @@ Do not paste automations into the admin form. Runtime state is `~/.signalk/plugi
 
 ## Example
 
-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.
+See `examples/automations.yaml` (fictional sample). Live YAML is whatever directory you set as `automationsDir` — usually a separate git. On/off and Verbose are plugin-data switches, not YAML keys.
 
 ```yaml
 helpers:
-  starlink_manual:
+  dish_manual:
     type: boolean
     default: false
     on_start: restore   # survive reboot
-    latch_on_external_put: electrical.switches.starlink.state
+    latch_on_external_put: electrical.switches.dish.state
 
 automations:
-  - id: starlink_standby
+  - id: dish_standby
     trigger:
       - schedule: "0 4 * * *"
     condition:
       - zone: home_harbour
-      - helper: starlink_manual
+      - helper: dish_manual
         is: false
     action:
-      - put: electrical.switches.starlink.state
+      - put: electrical.switches.dish.state
         value: true
       - delay: 15m
-      - put: electrical.switches.starlink.state
+      - put: electrical.switches.dish.state
         value: false
 ```
 
 ```yaml
-- path: electrical.switches.dolphinCharger.voltage
+- path: electrical.switches.charger.voltage
   round: 1          # nearest volt; 230.1 and 230.4 do not both fire
 ```
 

package/examples/automations.yaml

@@ -1,103 +1,105 @@
+# Bundled sample only. Site YAML belongs in the git you set as automationsDir,
+# not in this plugin.
+
 helpers:
-  starlink_manual:
+  dish_manual:
     type: boolean
-    name: Starlink handmatig
+    name: Dish manual
     default: false
     on_start: restore
-    latch_on_external_put: electrical.switches.starlink.state
-  depart_prep:
+    latch_on_external_put: electrical.switches.dish.state
+  trip_prep:
     type: boolean
-    name: Maak klaar voor vertrek
+    name: Prepare to leave
     default: false
     on_start: restore
 
 automations:
   - id: shore_charge
-    alias: Walstroom laadbeleid
+    alias: Shore charge
     zones:
       home_harbour:
-        name: Thuishaven
-        lat: 52.37
-        lon: 5.22
+        name: Home harbour
+        lat: 52.1
+        lon: 4.9
         radius: 150
     trigger:
-      - path: sensors.presence.dolphinshelly
+      - path: sensors.presence.shore
       - path: electrical.batteries.house.capacity.stateOfCharge
         round: 0.01
-      - helper: depart_prep
+      - helper: trip_prep
     choose:
-      - alias: onderweg volladen
+      - alias: charge underway
         conditions:
-          - path: sensors.presence.dolphinshelly
+          - path: sensors.presence.shore
             is: true
           - not:
               zone: home_harbour
         action:
-          - put: electrical.switches.dolphinCharger.state
+          - put: electrical.switches.charger.state
             value: 1
-      - alias: klaar voor vertrek laden
+      - alias: charge to leave
         conditions:
-          - path: sensors.presence.dolphinshelly
+          - path: sensors.presence.shore
             is: true
           - zone: home_harbour
-          - helper: depart_prep
+          - helper: trip_prep
             is: true
           - path: electrical.batteries.house.capacity.stateOfCharge
             below: 0.98
         action:
-          - put: electrical.switches.dolphinCharger.state
+          - put: electrical.switches.charger.state
             value: 1
-      - alias: klaar voor vertrek vol
+      - alias: leave charged
         conditions:
-          - path: sensors.presence.dolphinshelly
+          - path: sensors.presence.shore
             is: true
           - zone: home_harbour
-          - helper: depart_prep
+          - helper: trip_prep
             is: true
           - path: electrical.batteries.house.capacity.stateOfCharge
             above: 0.97
         action:
-          - put: electrical.switches.dolphinCharger.state
+          - put: electrical.switches.charger.state
             value: 0
-          - helper: depart_prep
+          - helper: trip_prep
             value: false
-      - alias: thuis onder 60%
+      - alias: home below 60%
         conditions:
-          - path: sensors.presence.dolphinshelly
+          - path: sensors.presence.shore
             is: true
           - zone: home_harbour
-          - helper: depart_prep
+          - helper: trip_prep
             is: false
           - path: electrical.batteries.house.capacity.stateOfCharge
             below: 0.6
         action:
-          - put: electrical.switches.dolphinCharger.state
+          - put: electrical.switches.charger.state
             value: 1
-      - alias: thuis boven 80%
+      - alias: home above 80%
         conditions:
-          - path: sensors.presence.dolphinshelly
+          - path: sensors.presence.shore
             is: true
           - zone: home_harbour
-          - helper: depart_prep
+          - helper: trip_prep
             is: false
           - path: electrical.batteries.house.capacity.stateOfCharge
             above: 0.8
         action:
-          - put: electrical.switches.dolphinCharger.state
+          - put: electrical.switches.charger.state
             value: 0
 
-  - id: starlink_standby
-    alias: Starlink standby-update
+  - id: dish_standby
+    alias: Dish standby update
     trigger:
       - schedule: "0 4 * * *"
     condition:
-      # home_harbour is defined on shore_charge (Walstroom laadbeleid).
       - zone: home_harbour
-      - helper: starlink_manual
+      - helper: dish_manual
         is: false
     action:
-      - put: electrical.switches.starlink.state
+      - put: electrical.switches.dish.state
         value: true
       - delay: 15m
-      - put: electrical.switches.starlink.state
+      - put: electrical.switches.dish.state
         value: false

package/lib/engine.js

@@ -37,6 +37,12 @@ function addPathsFromAction (paths, action) {
   if (!action || typeof action !== 'object') return
   if (action.put) paths.add(action.put)
   if (action.valueFrom) paths.add(action.valueFrom)
+  const gate = action.if
+  if (Array.isArray(gate)) {
+    for (const c of gate) addPathsFromClause(paths, c)
+  } else if (gate) {
+    addPathsFromClause(paths, gate)
+  }
 }
 
 function getByPath (values, p) {
@@ -306,6 +312,31 @@ function resultLabel (result) {
   return result === 'failure' ? 'Failed' : 'OK'
 }
 
+function formatStream (text) {
+  const t = String(text == null ? '' : text).replace(/\s+$/, '')
+  if (!t) return '(empty)'
+  if (!t.includes('\n')) return t
+  return '\n' + t.split('\n').map((line) => '      ' + line).join('\n')
+}
+
+function actionStderr (action) {
+  if (action && action.stderr) return String(action.stderr)
+  const err = action && action.error ? String(action.error) : ''
+  if (err.startsWith('stderr: ')) return err.slice(8)
+  return ''
+}
+
+function appendRunActionLines (lines, action) {
+  const extra = (action.args && action.args.length) ? ' ' + action.args.join(' ') : ''
+  lines.push('  run ' + (action.file || '') + extra)
+  lines.push('    stdout: ' + formatStream(action.stdout))
+  lines.push('    stderr: ' + formatStream(actionStderr(action)))
+  const err = action.error ? String(action.error) : ''
+  if (err && !err.startsWith('stderr: ')) {
+    lines.push('    error: ' + err)
+  }
+}
+
 function formatVerboseLog (auto, record) {
   const name = (auto && (auto.alias || auto.id)) || (record && record.id) || 'automation'
   const result = resultLabel(record.result)
@@ -327,6 +358,9 @@ function formatVerboseLog (auto, record) {
       appendClauseLines(lines, c, '    ')
     }
   }
+  for (const a of record.actions || []) {
+    if (a && a.type === 'run') appendRunActionLines(lines, a)
+  }
   return lines.join('\n')
 }
 
@@ -475,6 +509,11 @@ async function evaluateAutomation (auto, ctx) {
   }
 
   for (const action of actions) {
+    if (ctx.abort && ctx.abort.aborted) {
+      record.result = 'ok'
+      record.reason = 'superseded'
+      return finishRecord(auto, record)
+    }
     const ran = await runAction(action, ctx)
     record.actions.push(ran)
     if (!ran.ok) {
@@ -482,6 +521,7 @@ async function evaluateAutomation (auto, ctx) {
       record.reason = ran.error
       return finishRecord(auto, record)
     }
+    if (ran.stop) break
   }
   record.result = 'ok'
   return finishRecord(auto, record)
@@ -491,6 +531,12 @@ async function runAction (action, ctx) {
   if (!action || typeof action !== 'object') {
     return { ok: false, error: 'empty action' }
   }
+  if (action.if) {
+    const gate = await evalListAll(Array.isArray(action.if) ? action.if : [action.if], ctx)
+    if (!gate.pass) {
+      return { ok: true, skipped: true, reason: 'if not met', if: gate.results }
+    }
+  }
   if (action.put) {
     try {
       const value = Object.prototype.hasOwnProperty.call(action, 'valueFrom')
@@ -533,20 +579,46 @@ 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)
+    if (ctx.skipDelay) return { ok: true, type: 'delay', ms, skipped: true, stop: true }
+    try {
+      await ctx.sleep(ms)
+    } catch (err) {
+      if (err && err.cancelled) {
+        return { ok: true, type: 'delay', ms, cancelled: true, stop: true }
+      }
+      throw err
+    }
+    if (ctx.abort && ctx.abort.aborted) {
+      return { ok: true, type: 'delay', ms, cancelled: true, stop: true }
+    }
     return { ok: true, type: 'delay', ms }
   }
   if (action.run) {
     const spec = typeof action.run === 'string' ? { file: action.run } : action.run
     const ran = await ctx.runScript(spec)
     if (!ran.ok) {
-      return { ok: false, type: 'run', file: spec.file, error: ran.error, stdout: ran.stdout }
+      return {
+        ok: false,
+        type: 'run',
+        file: spec.file,
+        args: spec.args || [],
+        error: ran.error,
+        stdout: ran.stdout,
+        stderr: ran.stderr || ''
+      }
     }
     if (action.as) {
       ctx.setHelper(action.as, ran.value)
     }
-    return { ok: true, type: 'run', file: spec.file, value: ran.value, stdout: ran.stdout }
+    return {
+      ok: true,
+      type: 'run',
+      file: spec.file,
+      args: spec.args || [],
+      value: ran.value,
+      stdout: ran.stdout,
+      stderr: ran.stderr || ''
+    }
   }
   return { ok: false, error: 'unknown action' }
 }

package/lib/runtime.js

@@ -33,6 +33,7 @@ class Runtime {
     this.lastCronMinute = ''
     this.lastQuantized = {}
     this.unsubscribes = []
+    this.inFlight = {}
   }
 
   load () {
@@ -162,16 +163,21 @@ class Runtime {
     const key = d.getFullYear() + '-' + d.getMonth() + '-' + d.getDate() + '-' + d.getHours() + '-' + d.getMinutes()
     if (key === this.lastCronMinute) return
     this.lastCronMinute = key
+    const runs = []
     for (const auto of this.doc.automations) {
       const schedules = (auto.trigger || []).filter((t) => t.schedule)
       if (!schedules.length) continue
       const hit = schedules.some((t) => engine.cronMatch(t.schedule, d))
-      if (hit) await this.maybeRun(auto, { schedule: schedules[0].schedule })
+      if (hit) runs.push(this.maybeRun(auto, { schedule: schedules[0].schedule }))
     }
+    await Promise.all(runs)
   }
 
   async maybeRun (auto, trigger) {
     if (!this.isEnabled(auto)) return
+    const mode = auto.mode || 'parallel'
+    if (mode === 'single' && this.inFlight[auto.id]) return
+    if (mode === 'restart' && this.inFlight[auto.id]) this.inFlight[auto.id].abort()
     const ctx = this.makeCtx(trigger)
     const trig = await engine.evalListAll(auto.trigger || [], ctx)
     const matched = engine.triggerListMatched(auto.trigger, trig.results)
@@ -199,9 +205,15 @@ class Runtime {
     }
 
     this.lastDebounce[auto.id] = this.now()
-    const record = await engine.evaluateAutomation(auto, this.makeCtx(trigger))
-    this.finishRun(auto, record, { forceTrace: false })
-    return record
+    const abort = newAbort()
+    if (mode === 'single' || mode === 'restart') this.inFlight[auto.id] = abort
+    try {
+      const record = await engine.evaluateAutomation(auto, this.makeCtx(trigger, { abort }))
+      this.finishRun(auto, record, { forceTrace: false })
+      return record
+    } finally {
+      if (this.inFlight[auto.id] === abort) delete this.inFlight[auto.id]
+    }
   }
 
   keepTrace (auto, record, extra) {
@@ -237,11 +249,13 @@ class Runtime {
 
   async evaluateOnStart () {
     this.seedFromSelf()
+    const runs = []
     for (const auto of this.doc.automations) {
       if (!this.isEnabled(auto)) continue
       if (this.scheduleOnly(auto)) continue
-      await this.maybeRun(auto, { start: true })
+      runs.push(this.maybeRun(auto, { start: true }))
     }
+    await Promise.all(runs)
   }
 
   seedFromSelf () {
@@ -318,6 +332,24 @@ class Runtime {
 
   makeCtx (trigger, extra) {
     extra = extra || {}
+    const abort = extra.abort
+    const sleep = async (ms) => {
+      if (!abort) return this.sleep(ms)
+      try {
+        await Promise.race([
+          this.sleep(ms),
+          abort.promise
+        ])
+      } catch (err) {
+        if (err && err.cancelled) throw err
+        throw err
+      }
+      if (abort.aborted) {
+        const err = new Error('superseded')
+        err.cancelled = true
+        throw err
+      }
+    }
     return {
       values: this.values,
       zones: this.doc.zones,
@@ -326,10 +358,11 @@ class Runtime {
       now: this.now(),
       skipDelay: !!extra.skipDelay,
       skipUnchanged: extra.skipUnchanged !== false,
+      abort: abort || null,
       put: (p, value) => this.put(p, value),
       notify: (p, state, message) => this.notify(p, state, message),
       setHelper: (id, value) => this.setHelper(id, value, { kick: false }),
-      sleep: this.sleep,
+      sleep,
       runScript: engine.makeRunScript({
         scriptsDir: this.scriptsDir,
         timeoutMs: this.scriptTimeoutMs
@@ -446,6 +479,24 @@ class Runtime {
   }
 }
 
+function newAbort () {
+  const abort = {
+    aborted: false,
+    abort () {
+      if (this.aborted) return
+      this.aborted = true
+      const err = new Error('superseded')
+      err.cancelled = true
+      this._reject(err)
+    }
+  }
+  abort.promise = new Promise((_, reject) => {
+    abort._reject = reject
+  })
+  abort.promise.catch(() => {})
+  return abort
+}
+
 function asSwitch (v) {
   if (v === true || v === 1 || v === '1' || v === 'on' || v === 'ON') return 1
   if (v === false || v === 0 || v === '0' || v === 'off' || v === 'OFF') return 0

package/lib/yaml.js

@@ -172,8 +172,15 @@ function mergeAutomations (result, list, file) {
       action: asArray(raw.action),
       choose: Array.isArray(raw.choose) ? raw.choose : [],
       debounceMs: raw.debounceMs || 0,
-      edge: raw.edge || 'every'
+      edge: raw.edge || 'every',
+      mode: raw.mode || 'parallel'
     })
+    if (raw.mode && ['parallel', 'restart', 'single'].indexOf(raw.mode) === -1) {
+      result.errors.push({
+        file,
+        message: 'Automation ' + raw.id + ': mode must be parallel, restart, or single'
+      })
+    }
     for (const t of asArray(raw.trigger)) {
       if (!t || t.round == null) continue
       const n = Number(t.round)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-automation-plugin",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Home Assistant-like YAML automations for Signal K",
   "main": "plugin/index.js",
   "keywords": [

package/plugin/index.js

@@ -305,15 +305,36 @@ module.exports = function (app) {
     })
   }
 
-  function putPath (p, value) {
-    return new Promise((resolve, reject) => {
-      if (typeof app.putSelfPath !== 'function') {
-        app.handleMessage(PLUGIN_ID, {
-          updates: [{ values: [{ path: p, value }] }]
-        })
-        resolve()
-        return
+  function isMultipleSources (err) {
+    return /multiple sources for the given path/i.test(String((err && err.message) || err || ''))
+  }
+
+  function putSources (p) {
+    const out = []
+    const seen = Object.create(null)
+    const add = (s) => {
+      if (!s) return
+      const id = String(s)
+      if (seen[id] || id.includes(PLUGIN_ID)) return
+      seen[id] = true
+      out.push(id)
+    }
+    const node = typeof app.getSelfPath === 'function' ? app.getSelfPath(p) : null
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      add(node.$source)
+      const vals = node.values
+      if (vals && typeof vals === 'object') {
+        Object.keys(vals)
+          .sort((a, b) => Number(/^mqtt\b/i.test(b)) - Number(/^mqtt\b/i.test(a)))
+          .forEach(add)
       }
+    }
+    if (runtime && runtime.values) add(runtime.values[p + '.$source'])
+    return out
+  }
+
+  function callPutSelf (p, value, source) {
+    return new Promise((resolve, reject) => {
       let settled = false
       const finish = (err) => {
         if (settled) return
@@ -332,7 +353,9 @@ module.exports = function (app) {
         finish(null)
       }
       try {
-        const ret = app.putSelfPath(p, value, fromReply)
+        const ret = source
+          ? app.putSelfPath(p, value, fromReply, source)
+          : app.putSelfPath(p, value, fromReply)
         if (ret && typeof ret.then === 'function') {
           ret.then(fromReply, finish)
         }
@@ -342,6 +365,30 @@ module.exports = function (app) {
     })
   }
 
+  async function putPath (p, value) {
+    if (typeof app.putSelfPath !== 'function') {
+      app.handleMessage(PLUGIN_ID, {
+        updates: [{ values: [{ path: p, value }] }]
+      })
+      return
+    }
+    try {
+      await callPutSelf(p, value)
+    } catch (err) {
+      if (!isMultipleSources(err)) throw err
+      let last = err
+      for (const source of putSources(p)) {
+        try {
+          await callPutSelf(p, value, source)
+          return
+        } catch (e) {
+          last = e
+        }
+      }
+      throw last
+    }
+  }
+
   function notify (p, state, message) {
     const npath = String(p).startsWith('notifications.') ? p : 'notifications.' + p
     app.handleMessage(PLUGIN_ID, {

package/public/app.js

@@ -98,7 +98,10 @@ function fmtActions (t) {
     if (a.type === 'helper') return 'helper ' + a.helper + ' = ' + fmtVal(a.value)
     if (a.type === 'notify') return 'notify ' + (a.path || '') + ' ' + (a.state || '')
     if (a.type === 'delay') return a.skipped ? 'delay skipped (' + a.ms + ' ms)' : 'delay ' + a.ms + ' ms'
-    if (a.type === 'run') return 'run ' + (a.file || '')
+    if (a.type === 'run') {
+      const extra = (a.args && a.args.length) ? ' ' + a.args.join(' ') : ''
+      return 'run ' + (a.file || '') + extra
+    }
     return a.type || 'action'
   }).join('\n')
 }

package/public/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Signal K Automations</title>
     <link rel="icon" href="icon.png" />
-    <link rel="stylesheet" href="style.css?v=20260918ok" />
+    <link rel="stylesheet" href="style.css?v=20260918args" />
   </head>
   <body>
     <header>
@@ -61,6 +61,6 @@
         </div>
       </section>
     </main>
-    <script src="app.js?v=20260918ok"></script>
+    <script src="app.js?v=20260918args"></script>
   </body>
 </html>