tuning-stale-scan — what notices a device that stopped talking

Install and run

# download it
curl -O https://plantroomlabs.com/tools/tuning-stale-scan.py

# read the tuning machinery in the default install
python3 tuning-stale-scan.py

# or name the installation to read
python3 tuning-stale-scan.py /opt/Niagara/Niagara-4.15.5.22

The default policy, and the branch that reads it

The default tuning policy, read out of the static initialiser:
  minWriteTime   0 ms     (min facet 0 ms)
  maxWriteTime   0 ms     (min facet 0 ms)
  staleTime      0 ms     (min facet 0 ms)
  writeOnStart   true
  writeOnUp      true
  writeOnEnabled true

Tuning.process(), the only code in the framework that notices:
  at offset 160 it loads staleTime, compares it with zero, and on
  less-or-equal jumps to 212 - which is the method's own return.
  The default is 0, so by default this branch is never taken and no
  point in any driver on the station ever goes stale.

  With staleTime set, the rest reads:
    elapsed = now - (mode.isWriteonly() ? writeTicks : readTicks)
    if elapsed > staleTime, call stale()   (the branch is ifle)
  so the threshold is strictly greater than staleTime, and the clock is
  readTicks - which only readOk() ever sets.

stale() is three instructions: get the tunable, call setStale(true, null).
  It is the driver's own BITunable implementation that decides what
  that means for the point's status and value. The framework sets a
  flag and stops.

Where the errors go

Where the errors go. Tuning holds a logger named 'driver.tuning' with
  1 warning call, and 4 printStackTrace() sites.
  The warning says: TuningPolicy not found:
  The stack traces are in:
    void write(javax.baja.sys.Context)
    void readSubscribed()
    void readUnsubscribed()
    void stale()
  Those are the four things the tuning machinery does. Every one of
  them swallows its exception to stderr, where a station's log export
  will not have it.
  The background thread does the same with anything process() throws,
  and nulls a tuning out of its array when process() returns false.

What follows from it

Two consequences worth designing for
----------------------------------------------------------------------
  1. If your device reports unsolicited rather than being polled, a
     dead device is invisible by default. No poll fails, so nothing
     goes fault; staleTime is 0, so nothing goes stale; the last
     value sits there with an ok status for as long as the station runs.
  2. staleTime measures readTicks, and readTicks is set by readOk().
     If a driver calls readOk() when a link or a subscription is
     healthy rather than when a value actually arrives, then even a
     configured staleTime never fires. That is one line in a proxy
     extension and it decides whether the feature works at all.

Three checks one station settles in an afternoon
----------------------------------------------------------------------
  1. Read the default tuning policy on a live network and confirm
     staleTime is 0. If it is, no point under it can go stale.
  2. Set staleTime to a minute on one point, pull the device, and watch
     whether the point goes stale within 20000 ms of the minute.
  3. Set staleTime, leave the device alive but stop its reporting at
     the source, and see whether the point still goes stale. If it does
     not, readOk() is being called for the wrong event.

What it reads, and the limit of what the output is worth

The file you are downloading