#257 tick supervisor version to force installers to re-pull graphics

2023.06.07 Hotfix

.github/workflows/check.yml

@@ -22,11 +22,10 @@ jobs:
         uses: lunarmodules/luacheck@v1.1.0
         with:
           # Argument Explanations
-          # -a     = Disable warning for unused arguments
           # -i 121 = Setting a read-only global variable
           #    512 = Loop can be executed at most once
           #    542 = An empty if branch
           # --no-max-line-length = Disable warnings for long line lengths
           # --exclude-files ...  = Exclude lockbox library (external) and config files
           # --globals ...        = Override all globals overridden in .vscode/settings.json AND 'os' since CraftOS 'os' differs from Lua's 'os'
-          args: . --no-max-line-length -a -i 121 512 542 --exclude-files ./lockbox/* ./*/config.lua --globals os _HOST bit colors fs http parallel periphemu peripheral read rs settings shell term textutils window
+          args: . --no-max-line-length -i 121 512 542 --exclude-files ./lockbox/* ./*/config.lua --globals os _HOST bit colors fs http parallel periphemu peripheral read rs settings shell term textutils window

.github/workflows/manifest.yml

@@ -0,0 +1,95 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy Installation Manifests and Versions
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - latest
+      - devel
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Setup Python
+        uses: actions/setup-python@v3.1.3
+      # Generate manifest + shields files for main branch
+      - name: Checkout main
+        id: checkout-main
+        uses: actions/checkout@v3
+        with:
+          ref: 'main'
+          clean: false
+      - name: Create outputs folders
+        if: success() || failure()
+        shell: bash
+        run: mkdir deploy; mkdir deploy/manifests; mkdir deploy/manifests/main deploy/manifests/latest deploy/manifests/devel
+      - name: Generate manifest and shields for main branch
+        id: manifest-main
+        if: ${{ (success() || failure()) && steps.checkout-main.outcome == 'success' }}
+        run: python imgen.py shields
+      - name: Save main's manifest
+        if: ${{ (success() || failure()) && steps.manifest-main.outcome == 'success' }}
+        run: mv install_manifest.json deploy/manifests/main
+      # Generate manifest for latest branch
+      - name: Checkout latest
+        id: checkout-latest
+        if: success() || failure()
+        uses: actions/checkout@v3
+        with:
+          ref: 'latest'
+          clean: false
+      - name: Generate manifest for latest
+        id: manifest-latest
+        if: ${{ (success() || failure()) && steps.checkout-latest.outcome == 'success' }}
+        run: python imgen.py
+      - name: Save latest's manifest
+        if: ${{ (success() || failure()) && steps.manifest-latest.outcome == 'success' }}
+        run: mv install_manifest.json deploy/manifests/latest
+      # Generate manifest for devel branch
+      - name: Checkout devel
+        id: checkout-devel
+        if: success() || failure()
+        uses: actions/checkout@v3
+        with:
+          ref: 'devel'
+          clean: false
+      - name: Generate manifest for devel
+        id: manifest-devel
+        if: ${{ (success() || failure()) && steps.checkout-devel.outcome == 'success' }}
+        run: python imgen.py
+      - name: Save devel's manifest
+        if: ${{ (success() || failure()) && steps.manifest-devel.outcome == 'success' }}
+        run: mv install_manifest.json deploy/manifests/devel
+      # All artifacts ready now, upload deploy directory
+      - name: Upload artifacts
+        id: upload-artifacts
+        if: ${{ (success() || failure()) && (steps.manifest-main.outcome == 'success' || steps.manifest-latest.outcome == 'success' || steps.manifest-devel.outcome == 'success') }}
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload manifest JSON
+          path: 'deploy/'
+      - name: Deploy to GitHub Pages
+        if: ${{ (success() || failure()) && steps.upload-artifacts.outcome == 'success' }}
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/shields.yml

@@ -1,47 +0,0 @@
-# Simple workflow for deploying static content to GitHub Pages
-name: Deploy Component Versions
-
-on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  # Single deploy job since we're just deploying
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Pages
-        uses: actions/configure-pages@v3
-      - name: Setup Python
-        uses: actions/setup-python@v3.1.3
-      - run: mkdir shields
-      - run: python imgen.py shields
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
-        with:
-          # Upload shields JSON
-          path: 'shields/'
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v2

README.md

@@ -41,7 +41,7 @@ There was also an apparent bug with boilers disconnecting and reconnecting when
 
 You can install this on a ComputerCraft computer using either:
 * `wget https://raw.githubusercontent.com/MikaylaFischler/cc-mek-scada/main/ccmsi.lua`
-* `pastebin get iUMjgW0C ccmsi.lua`
+* `pastebin get eRz6cUNM ccmsi.lua`
 
 ## [SCADA](https://en.wikipedia.org/wiki/SCADA)
 > Supervisory control and data acquisition (SCADA) is a control system architecture comprising computers, networked data communications and graphical user interfaces for high-level supervision of machines and processes. It also covers sensors and other devices, such as programmable logic controllers, which interface with process plant or machinery.

ccmsi.lua

@@ -20,9 +20,10 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 local function println(message) print(tostring(message)) end
 local function print(message) term.write(tostring(message)) end
 
-local CCMSI_VERSION = "v1.0"
+local CCMSI_VERSION = "v1.2"
 
 local install_dir = "/.install-cache"
+local manifest_path = "https://mikaylafischler.github.io/cc-mek-scada/manifests/"
 local repo_path = "http://raw.githubusercontent.com/MikaylaFischler/cc-mek-scada/"
 
 local opts = { ... }
@@ -122,8 +123,8 @@ if mode == "check" then
     -- GET REMOTE MANIFEST --
     -------------------------
 
-    if opts[2] then repo_path = repo_path .. opts[2] .. "/" else repo_path = repo_path .. "main/" end
-    local install_manifest = repo_path .. "install_manifest.json"
+    if opts[2] then manifest_path = manifest_path .. opts[2] .. "/" else manifest_path = manifest_path .. "main/" end
+    local install_manifest = manifest_path .. "install_manifest.json"
 
     local response, error = http.get(install_manifest)
 
@@ -203,7 +204,8 @@ elseif mode == "install" or mode == "update" then
     -------------------------
 
     if opts[3] then repo_path = repo_path .. opts[3] .. "/" else repo_path = repo_path .. "main/" end
-    local install_manifest = repo_path .. "install_manifest.json"
+    if opts[3] then manifest_path = manifest_path .. opts[3] .. "/" else manifest_path = manifest_path .. "main/" end
+    local install_manifest = manifest_path .. "install_manifest.json"
 
     local response, error = http.get(install_manifest)
 

coordinator/config.lua

@@ -1,11 +1,11 @@
 local config = {}
 
--- port of the SCADA supervisor
-config.SCADA_SV_PORT = 16100
--- port to listen to incoming packets from supervisor
-config.SCADA_SV_CTL_LISTEN = 16101
--- listen port for SCADA coordinator API access
-config.SCADA_API_LISTEN = 16200
+-- supervisor comms channel
+config.SVR_CHANNEL = 16240
+-- coordinator comms channel
+config.CRD_CHANNEL = 16243
+-- pocket comms channel
+config.PKT_CHANNEL = 16244
 -- max trusted modem message distance (0 to disable check)
 config.TRUSTED_RANGE = 0
 -- time in seconds (>= 2) before assuming a remote device is no longer active
@@ -28,5 +28,7 @@ config.LOG_PATH = "/log.txt"
 --  0 = APPEND (adds to existing file on start)
 --  1 = NEW (replaces existing file on start)
 config.LOG_MODE = 0
+-- true to log verbose debug messages
+config.LOG_DEBUG = false
 
 return config

coordinator/coordinator.lua

@@ -213,14 +213,15 @@ end
 ---@nodiscard
 ---@param version string coordinator version
 ---@param modem table modem device
----@param sv_port integer port of configured supervisor
----@param sv_listen integer listening port for supervisor replys
----@param api_listen integer listening port for pocket API
+---@param crd_channel integer port of configured supervisor
+---@param svr_channel integer listening port for supervisor replys
+---@param pkt_channel integer listening port for pocket API
 ---@param range integer trusted device connection range
 ---@param sv_watchdog watchdog
-function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range, sv_watchdog)
+function coordinator.comms(version, modem, crd_channel, svr_channel, pkt_channel, range, sv_watchdog)
     local self = {
         sv_linked = false,
+        sv_addr = comms.BROADCAST,
         sv_seq_num = 0,
         sv_r_seq_num = nil,
         sv_config_err = false,
@@ -236,8 +237,7 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
     -- configure modem channels
     local function _conf_channels()
         modem.closeAll()
-        modem.open(sv_listen)
-        modem.open(api_listen)
+        modem.open(crd_channel)
     end
 
     _conf_channels()
@@ -261,23 +261,24 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
         end
 
         pkt.make(msg_type, msg)
-        s_pkt.make(self.sv_seq_num, protocol, pkt.raw_sendable())
+        s_pkt.make(self.sv_addr, self.sv_seq_num, protocol, pkt.raw_sendable())
 
-        modem.transmit(sv_port, sv_listen, s_pkt.raw_sendable())
+        modem.transmit(svr_channel, crd_channel, s_pkt.raw_sendable())
         self.sv_seq_num = self.sv_seq_num + 1
     end
 
     -- send an API establish request response
-    ---@param dest integer
-    ---@param msg table
-    local function _send_api_establish_ack(seq_id, dest, msg)
+    ---@param packet scada_packet
+    ---@param ack ESTABLISH_ACK
+    local function _send_api_establish_ack(packet, ack)
         local s_pkt = comms.scada_packet()
         local m_pkt = comms.mgmt_packet()
 
-        m_pkt.make(SCADA_MGMT_TYPE.ESTABLISH, msg)
-        s_pkt.make(seq_id, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
+        m_pkt.make(SCADA_MGMT_TYPE.ESTABLISH, { ack })
+        s_pkt.make(packet.src_addr(), packet.seq_num() + 1, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
 
-        modem.transmit(dest, api_listen, s_pkt.raw_sendable())
+        modem.transmit(pkt_channel, crd_channel, s_pkt.raw_sendable())
+        self.last_api_est_acks[packet.src_addr()] = ack
     end
 
     -- attempt connection establishment
@@ -307,7 +308,9 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
     -- close the connection to the server
     function public.close()
         sv_watchdog.cancel()
+        self.sv_addr = comms.BROADCAST
         self.sv_linked = false
+        self.sv_r_seq_num = nil
         _send_sv(PROTOCOL.SCADA_MGMT, SCADA_MGMT_TYPE.CLOSE, {})
     end
 
@@ -335,12 +338,13 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                 tick_dmesg_waiting(math.max(0, timeout_s - (util.time_s() - start)))
                 _send_establish()
                 clock.start()
+            elseif event == "timer" then
+                -- keep checking watchdog timers
+                apisessions.check_all_watchdogs(p1)
             elseif event == "modem_message" then
                 -- handle message
                 local packet = public.parse_packet(p1, p2, p3, p4, p5)
-                if packet ~= nil and packet.type == SCADA_MGMT_TYPE.ESTABLISH then
-                    public.handle_packet(packet)
-                end
+                public.handle_packet(packet)
             elseif event == "terminate" then
                 terminated = true
                 break
@@ -435,15 +439,18 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
     ---@param packet mgmt_frame|crdn_frame|capi_frame|nil
     function public.handle_packet(packet)
         if packet ~= nil then
-            local l_port = packet.scada_frame.local_port()
-            local r_port = packet.scada_frame.remote_port()
+            local l_chan = packet.scada_frame.local_channel()
+            local r_chan = packet.scada_frame.remote_channel()
+            local src_addr = packet.scada_frame.src_addr()
             local protocol = packet.scada_frame.protocol()
 
-            if l_port == api_listen then
+            if l_chan ~= crd_channel then
+                log.debug("received packet on unconfigured channel " .. l_chan, true)
+            elseif r_chan == pkt_channel then
                 if protocol == PROTOCOL.COORD_API then
                     ---@cast packet capi_frame
                     -- look for an associated session
-                    local session = apisessions.find_session(r_port)
+                    local session = apisessions.find_session(src_addr)
 
                     -- API packet
                     if session ~= nil then
@@ -456,7 +463,7 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                 elseif protocol == PROTOCOL.SCADA_MGMT then
                     ---@cast packet mgmt_frame
                     -- look for an associated session
-                    local session = apisessions.find_session(r_port)
+                    local session = apisessions.find_session(src_addr)
 
                     -- SCADA management packet
                     if session ~= nil then
@@ -464,8 +471,6 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                         session.in_queue.push_packet(packet)
                     elseif packet.type == SCADA_MGMT_TYPE.ESTABLISH then
                         -- establish a new session
-                        local next_seq_id = packet.scada_frame.seq_num() + 1
-
                         -- validate packet and continue
                         if packet.length == 3 and type(packet.data[1]) == "string" and type(packet.data[2]) == "string" then
                             local comms_v = packet.data[1]
@@ -473,42 +478,43 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                             local dev_type = packet.data[3]
 
                             if comms_v ~= comms.version then
-                                if self.last_api_est_acks[r_port] ~= ESTABLISH_ACK.BAD_VERSION then
+                                if self.last_api_est_acks[src_addr] ~= ESTABLISH_ACK.BAD_VERSION then
                                     log.info(util.c("dropping API establish packet with incorrect comms version v", comms_v, " (expected v", comms.version, ")"))
-                                    self.last_api_est_acks[r_port] = ESTABLISH_ACK.BAD_VERSION
                                 end
 
-                                _send_api_establish_ack(next_seq_id, r_port, { ESTABLISH_ACK.BAD_VERSION })
+                                _send_api_establish_ack(packet.scada_frame, ESTABLISH_ACK.BAD_VERSION)
                             elseif dev_type == DEVICE_TYPE.PKT then
                                 -- pocket linking request
-                                local id = apisessions.establish_session(l_port, r_port, firmware_v)
-                                println(util.c("API: pocket (", firmware_v, ") [:", r_port, "] connected with session ID ", id))
-                                coordinator.log_comms(util.c("API: pocket (", firmware_v, ") [:", r_port, "] connected with session ID ", id))
+                                local id = apisessions.establish_session(src_addr, firmware_v)
+                                println(util.c("[API] pocket (", firmware_v, ") [@", src_addr, "] \xbb connected"))
+                                coordinator.log_comms(util.c("API_ESTABLISH: pocket (", firmware_v, ") [@", src_addr, "] connected with session ID ", id))
 
-                                _send_api_establish_ack(next_seq_id, r_port, { ESTABLISH_ACK.ALLOW })
-                                self.last_api_est_acks[r_port] = ESTABLISH_ACK.ALLOW
+                                _send_api_establish_ack(packet.scada_frame, ESTABLISH_ACK.ALLOW)
                             else
-                                log.debug(util.c("illegal establish packet for device ", dev_type, " on API listening channel"))
-                                _send_api_establish_ack(next_seq_id, r_port, { ESTABLISH_ACK.DENY })
+                                log.debug(util.c("API_ESTABLISH: illegal establish packet for device ", dev_type, " on pocket channel"))
+                                _send_api_establish_ack(packet.scada_frame, ESTABLISH_ACK.DENY)
                             end
                         else
                             log.debug("invalid establish packet (on API listening channel)")
-                            _send_api_establish_ack(next_seq_id, r_port, { ESTABLISH_ACK.DENY })
+                            _send_api_establish_ack(packet.scada_frame, ESTABLISH_ACK.DENY)
                         end
                     else
                         -- any other packet should be session related, discard it
-                        log.debug(util.c(r_port, "->", l_port, ": discarding SCADA_MGMT packet without a known session"))
+                        log.debug(util.c("discarding pocket SCADA_MGMT packet without a known session from computer ", src_addr))
                     end
                 else
-                    log.debug("illegal packet type " .. protocol .. " on api listening channel", true)
+                    log.debug("illegal packet type " .. protocol .. " on pocket channel", true)
                 end
-            elseif l_port == sv_listen then
+            elseif r_chan == svr_channel then
                 -- check sequence number
                 if self.sv_r_seq_num == nil then
                     self.sv_r_seq_num = packet.scada_frame.seq_num()
                 elseif self.connected and ((self.sv_r_seq_num + 1) ~= packet.scada_frame.seq_num()) then
                     log.warning("sequence out-of-order: last = " .. self.sv_r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
                     return
+                elseif self.sv_linked and src_addr ~= self.sv_addr then
+                    log.debug("received packet from unknown computer " .. src_addr .. " while linked; channel in use by another system?")
+                    return
                 else
                     self.sv_r_seq_num = packet.scada_frame.seq_num()
                 end
@@ -659,6 +665,7 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                                         -- init io controller
                                         iocontrol.init(conf, public)
 
+                                        self.sv_addr = src_addr
                                         self.sv_linked = true
                                         self.sv_config_err = false
                                     else
@@ -704,10 +711,10 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                                 local trip_time = util.time() - timestamp
 
                                 if trip_time > 750 then
-                                    log.warning("coord KEEP_ALIVE trip time > 750ms (" .. trip_time .. "ms)")
+                                    log.warning("coordinator KEEP_ALIVE trip time > 750ms (" .. trip_time .. "ms)")
                                 end
 
-                                -- log.debug("coord RTT = " .. trip_time .. "ms")
+                                -- log.debug("coordinator RTT = " .. trip_time .. "ms")
 
                                 iocontrol.get_db().facility.ps.publish("sv_ping", trip_time)
 
@@ -718,7 +725,9 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                         elseif packet.type == SCADA_MGMT_TYPE.CLOSE then
                             -- handle session close
                             sv_watchdog.cancel()
+                            self.sv_addr = comms.BROADCAST
                             self.sv_linked = false
+                            self.sv_r_seq_num = nil
                             println_ts("server connection closed by remote host")
                             log.info("server connection closed by remote host")
                         else
@@ -731,7 +740,7 @@ function coordinator.comms(version, modem, sv_port, sv_listen, api_listen, range
                     log.debug("illegal packet type " .. protocol .. " on supervisor listening channel", true)
                 end
             else
-                log.debug("received packet on unconfigured channel " .. l_port, true)
+                log.debug("received packet for unknown channel " .. r_chan, true)
             end
         end
     end

coordinator/iocontrol.lua

@@ -18,11 +18,15 @@ local iocontrol = {}
 ---@class ioctl
 local io = {}
 
+-- luacheck: no unused args
+
 -- placeholder acknowledge function for type hinting
 ---@param success boolean
 ---@diagnostic disable-next-line: unused-local
 local function __generic_ack(success) end
 
+-- luacheck: unused args
+
 -- initialize the coordinator IO controller
 ---@param conf facility_conf configuration
 ---@param comms coord_comms comms reference

coordinator/renderer.lua

@@ -138,9 +138,9 @@ function renderer.close_ui()
     -- stop blinking indicators
     flasher.clear()
 
-    -- hide to stop animation callbacks
-    if engine.ui.main_display ~= nil then engine.ui.main_display.hide() end
-    for _, display in ipairs(engine.ui.unit_displays) do display.hide() end
+    -- delete element trees
+    if engine.ui.main_display ~= nil then engine.ui.main_display.delete() end
+    for _, display in ipairs(engine.ui.unit_displays) do display.delete() end
 
     -- report ui as not ready
     engine.ui_ready = false
@@ -163,9 +163,9 @@ end
 function renderer.ui_ready() return engine.ui_ready end
 
 -- handle a touch event
----@param event mouse_interaction
+---@param event mouse_interaction|nil
 function renderer.handle_mouse(event)
-    if engine.ui_ready then
+    if engine.ui_ready and event ~= nil then
         if event.monitor == engine.monitors.primary_name then
             engine.ui.main_display.handle_mouse(event)
         else

coordinator/session/apisessions.lua

@@ -5,7 +5,7 @@ local util   = require("scada-common.util")
 
 local config = require("coordinator.config")
 
-local api    = require("coordinator.session.api")
+local pocket = require("coordinator.session.pocket")
 
 local apisessions = {}
 
@@ -18,7 +18,7 @@ local self = {
 -- PRIVATE FUNCTIONS --
 
 -- handle a session output queue
----@param session api_session_struct
+---@param session pkt_session_struct
 local function _api_handle_outq(session)
     -- record handler start time
     local handle_start = util.time()
@@ -31,7 +31,7 @@ local function _api_handle_outq(session)
         if msg ~= nil then
             if msg.qtype == mqueue.TYPE.PACKET then
                 -- handle a packet to be sent
-                self.modem.transmit(session.r_port, session.l_port, msg.message.raw_sendable())
+                self.modem.transmit(config.PKT_CHANNEL, config.CRD_CHANNEL, msg.message.raw_sendable())
             elseif msg.qtype == mqueue.TYPE.COMMAND then
                 -- handle instruction/notification
             elseif msg.qtype == mqueue.TYPE.DATA then
@@ -41,15 +41,15 @@ local function _api_handle_outq(session)
 
         -- max 100ms spent processing queue
         if util.time() - handle_start > 100 then
-            log.warning("API out queue handler exceeded 100ms queue process limit")
-            log.warning(util.c("offending session: port ", session.r_port))
+            log.warning("[API] out queue handler exceeded 100ms queue process limit")
+            log.warning(util.c("[API] offending session: ", session))
             break
         end
     end
 end
 
 -- cleanly close a session
----@param session api_session_struct
+---@param session pkt_session_struct
 local function _shutdown(session)
     session.open = false
     session.instance.close()
@@ -58,11 +58,11 @@ local function _shutdown(session)
     while session.out_queue.ready() do
         local msg = session.out_queue.pop()
         if msg ~= nil and msg.qtype == mqueue.TYPE.PACKET then
-            self.modem.transmit(session.r_port, session.l_port, msg.message.raw_sendable())
+            self.modem.transmit(config.PKT_CHANNEL, config.CRD_CHANNEL, msg.message.raw_sendable())
         end
     end
 
-    log.debug(util.c("closed API session ", session.instance.get_id(), " on remote port ", session.r_port))
+    log.debug(util.c("[API] closed session ", session))
 end
 
 -- PUBLIC FUNCTIONS --
@@ -81,54 +81,60 @@ end
 
 -- find a session by remote port
 ---@nodiscard
----@param port integer
----@return api_session_struct|nil
-function apisessions.find_session(port)
+---@param source_addr integer
+---@return pkt_session_struct|nil
+function apisessions.find_session(source_addr)
     for i = 1, #self.sessions do
-        if self.sessions[i].r_port == port then return self.sessions[i] end
+        if self.sessions[i].s_addr == source_addr then return self.sessions[i] end
     end
     return nil
 end
 
 -- establish a new API session
 ---@nodiscard
----@param local_port integer
----@param remote_port integer
+---@param source_addr integer
 ---@param version string
 ---@return integer session_id
-function apisessions.establish_session(local_port, remote_port, version)
-    ---@class api_session_struct
-    local api_s = {
+function apisessions.establish_session(source_addr, version)
+    ---@class pkt_session_struct
+    local pkt_s = {
         open = true,
         version = version,
-        l_port = local_port,
-        r_port = remote_port,
+        s_addr = source_addr,
         in_queue = mqueue.new(),
         out_queue = mqueue.new(),
-        instance = nil  ---@type api_session
+        instance = nil  ---@type pkt_session
     }
 
-    api_s.instance = api.new_session(self.next_id, api_s.in_queue, api_s.out_queue, config.API_TIMEOUT)
-    table.insert(self.sessions, api_s)
+    local id = self.next_id
 
-    log.debug(util.c("established new API session to ", remote_port, " with ID ", self.next_id))
+    pkt_s.instance = pocket.new_session(id, source_addr, pkt_s.in_queue, pkt_s.out_queue, config.API_TIMEOUT)
+    table.insert(self.sessions, pkt_s)
 
-    self.next_id = self.next_id + 1
+    local mt = {
+        ---@param s pkt_session_struct
+        __tostring = function (s)  return util.c("PKT [", id, "] (@", s.s_addr, ")") end
+    }
+
+    setmetatable(pkt_s, mt)
+
+    log.debug(util.c("[API] established new session: ", pkt_s))
+
+    self.next_id = id + 1
 
     -- success
-    return api_s.instance.get_id()
+    return pkt_s.instance.get_id()
 end
 
 -- attempt to identify which session's watchdog timer fired
 ---@param timer_event number
 function apisessions.check_all_watchdogs(timer_event)
     for i = 1, #self.sessions do
-        local session = self.sessions[i]  ---@type api_session_struct
+        local session = self.sessions[i]  ---@type pkt_session_struct
         if session.open then
             local triggered = session.instance.check_wd(timer_event)
             if triggered then
-                log.debug(util.c("watchdog closing API session ", session.instance.get_id(),
-                    " on remote port ", session.r_port, "..."))
+                log.debug(util.c("[API] watchdog closing session ", session, "..."))
                 _shutdown(session)
             end
         end
@@ -138,7 +144,7 @@ end
 -- iterate all the API sessions
 function apisessions.iterate_all()
     for i = 1, #self.sessions do
-        local session = self.sessions[i]    ---@type api_session_struct
+        local session = self.sessions[i]    ---@type pkt_session_struct
 
         if session.open and session.instance.iterate() then
             _api_handle_outq(session)
@@ -152,10 +158,9 @@ end
 function apisessions.free_all_closed()
     local f = function (session) return session.open end
 
-    ---@param session api_session_struct
+    ---@param session pkt_session_struct
     local on_delete = function (session)
-        log.debug(util.c("free'ing closed API session ", session.instance.get_id(),
-            " on remote port ", session.r_port))
+        log.debug(util.c("[API] free'ing closed session ", session))
     end
 
     util.filter_table(self.sessions, f, on_delete)
@@ -164,7 +169,7 @@ end
 -- close all open connections
 function apisessions.close_all()
     for i = 1, #self.sessions do
-        local session = self.sessions[i]  ---@type api_session_struct
+        local session = self.sessions[i]  ---@type pkt_session_struct
         if session.open then _shutdown(session) end
     end
 

coordinator/session/pocket.lua

@@ -3,7 +3,7 @@ local log    = require("scada-common.log")
 local mqueue = require("scada-common.mqueue")
 local util   = require("scada-common.util")
 
-local api = {}
+local pocket = {}
 
 local PROTOCOL = comms.PROTOCOL
 -- local CAPI_TYPE = comms.CAPI_TYPE
@@ -21,8 +21,8 @@ local API_S_CMDS = {
 local API_S_DATA = {
 }
 
-api.API_S_CMDS = API_S_CMDS
-api.API_S_DATA = API_S_DATA
+pocket.API_S_CMDS = API_S_CMDS
+pocket.API_S_DATA = API_S_DATA
 
 local PERIODICS = {
     KEEP_ALIVE = 2000
@@ -31,11 +31,12 @@ local PERIODICS = {
 -- pocket API session
 ---@nodiscard
 ---@param id integer session ID
+---@param s_addr integer device source address
 ---@param in_queue mqueue in message queue
 ---@param out_queue mqueue out message queue
 ---@param timeout number communications timeout
-function api.new_session(id, in_queue, out_queue, timeout)
-    local log_header = "api_session(" .. id .. "): "
+function pocket.new_session(id, s_addr, in_queue, out_queue, timeout)
+    local log_header = "pkt_session(" .. id .. "): "
 
     local self = {
         -- connection properties
@@ -61,10 +62,10 @@ function api.new_session(id, in_queue, out_queue, timeout)
         }
     }
 
-    ---@class api_session
+    ---@class pkt_session
     local public = {}
 
-    -- mark this API session as closed, stop watchdog
+    -- mark this pocket session as closed, stop watchdog
     local function _close()
         self.conn_watchdog.cancel()
         self.connected = false
@@ -92,7 +93,7 @@ function api.new_session(id, in_queue, out_queue, timeout)
         local m_pkt = comms.mgmt_packet()
 
         m_pkt.make(msg_type, msg)
-        s_pkt.make(self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
+        s_pkt.make(s_addr, self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
 
         out_queue.push_packet(s_pkt)
         self.seq_num = self.seq_num + 1
@@ -117,8 +118,6 @@ function api.new_session(id, in_queue, out_queue, timeout)
         -- process packet
         if pkt.scada_frame.protocol() == PROTOCOL.COORD_API then
             ---@cast pkt capi_frame
-            -- feed watchdog
-            self.conn_watchdog.feed()
 
             -- handle packet by type
             if pkt.type == nil then
@@ -136,11 +135,11 @@ function api.new_session(id, in_queue, out_queue, timeout)
                     self.last_rtt = srv_now - srv_start
 
                     if self.last_rtt > 750 then
-                        log.warning(log_header .. "API KEEP_ALIVE round trip time > 750ms (" .. self.last_rtt .. "ms)")
+                        log.warning(log_header .. "PKT KEEP_ALIVE round trip time > 750ms (" .. self.last_rtt .. "ms)")
                     end
 
-                    -- log.debug(log_header .. "API RTT = " .. self.last_rtt .. "ms")
-                    -- log.debug(log_header .. "API TT  = " .. (srv_now - api_send) .. "ms")
+                    -- log.debug(log_header .. "PKT RTT = " .. self.last_rtt .. "ms")
+                    -- log.debug(log_header .. "PKT TT  = " .. (srv_now - api_send) .. "ms")
                 else
                     log.debug(log_header .. "SCADA keep alive packet length mismatch")
                 end
@@ -173,7 +172,7 @@ function api.new_session(id, in_queue, out_queue, timeout)
     function public.close()
         _close()
         _send_mgmt(SCADA_MGMT_TYPE.CLOSE, {})
-        println("connection to API session " .. id .. " closed by server")
+        println("connection to pocket session " .. id .. " closed by server")
         log.info(log_header .. "session closed by server")
     end
 
@@ -212,7 +211,7 @@ function api.new_session(id, in_queue, out_queue, timeout)
 
             -- exit if connection was closed
             if not self.connected then
-                println("connection to API session " .. id .. " closed by remote host")
+                println("connection to pocket session " .. id .. " closed by remote host")
                 log.info(log_header .. "session closed by remote host")
                 return self.connected
             end
@@ -248,4 +247,4 @@ function api.new_session(id, in_queue, out_queue, timeout)
     return public
 end
 
-return api
+return pocket

coordinator/startup.lua

@@ -4,23 +4,23 @@
 
 require("/initenv").init_env()
 
-local crash        = require("scada-common.crash")
-local log          = require("scada-common.log")
-local ppm          = require("scada-common.ppm")
-local tcallbackdsp = require("scada-common.tcallbackdsp")
-local util         = require("scada-common.util")
+local crash       = require("scada-common.crash")
+local log         = require("scada-common.log")
+local ppm         = require("scada-common.ppm")
+local tcd         = require("scada-common.tcd")
+local util        = require("scada-common.util")
 
-local core         = require("graphics.core")
+local core        = require("graphics.core")
 
-local config       = require("coordinator.config")
-local coordinator  = require("coordinator.coordinator")
-local iocontrol    = require("coordinator.iocontrol")
-local renderer     = require("coordinator.renderer")
-local sounder      = require("coordinator.sounder")
+local config      = require("coordinator.config")
+local coordinator = require("coordinator.coordinator")
+local iocontrol   = require("coordinator.iocontrol")
+local renderer    = require("coordinator.renderer")
+local sounder     = require("coordinator.sounder")
 
-local apisessions  = require("coordinator.session.apisessions")
+local apisessions = require("coordinator.session.apisessions")
 
-local COORDINATOR_VERSION = "v0.13.8"
+local COORDINATOR_VERSION = "v0.16.1"
 
 local println = util.println
 local println_ts = util.println_ts
@@ -37,9 +37,9 @@ local log_comms_connecting = coordinator.log_comms_connecting
 
 local cfv = util.new_validator()
 
-cfv.assert_port(config.SCADA_SV_PORT)
-cfv.assert_port(config.SCADA_SV_CTL_LISTEN)
-cfv.assert_port(config.SCADA_API_LISTEN)
+cfv.assert_channel(config.SVR_CHANNEL)
+cfv.assert_channel(config.CRD_CHANNEL)
+cfv.assert_channel(config.PKT_CHANNEL)
 cfv.assert_type_int(config.TRUSTED_RANGE)
 cfv.assert_type_num(config.SV_TIMEOUT)
 cfv.assert_min(config.SV_TIMEOUT, 2)
@@ -57,7 +57,7 @@ assert(cfv.valid(), "bad config file: missing/invalid fields")
 -- log init
 ----------------------------------------
 
-log.init(config.LOG_PATH, config.LOG_MODE)
+log.init(config.LOG_PATH, config.LOG_MODE, config.LOG_DEBUG == true)
 
 log.info("========================================")
 log.info("BOOTING coordinator.startup " .. COORDINATOR_VERSION)
@@ -148,8 +148,8 @@ local function main()
     log.debug("startup> conn watchdog created")
 
     -- start comms, open all channels
-    local coord_comms = coordinator.comms(COORDINATOR_VERSION, modem, config.SCADA_SV_PORT, config.SCADA_SV_CTL_LISTEN,
-                                            config.SCADA_API_LISTEN, config.TRUSTED_RANGE, conn_watchdog)
+    local coord_comms = coordinator.comms(COORDINATOR_VERSION, modem, config.CRD_CHANNEL, config.SVR_CHANNEL,
+                                            config.PKT_CHANNEL, config.TRUSTED_RANGE, conn_watchdog)
     log.debug("startup> comms init")
     log_comms("comms initialized")
 
@@ -163,7 +163,7 @@ local function main()
 
     -- attempt to connect to the supervisor or exit
     local function init_connect_sv()
-        local tick_waiting, task_done = log_comms_connecting("attempting to connect to configured supervisor on channel " .. config.SCADA_SV_PORT)
+        local tick_waiting, task_done = log_comms_connecting("attempting to connect to configured supervisor on channel " .. config.SVR_CHANNEL)
 
         -- attempt to establish a connection with the supervisory computer
         if not coord_comms.sv_connect(60, tick_waiting, task_done) then
@@ -334,7 +334,7 @@ local function main()
                 apisessions.check_all_watchdogs(param1)
 
                 -- notify timer callback dispatcher
-                tcallbackdsp.handle(param1)
+                tcd.handle(param1)
             end
         elseif event == "modem_message" then
             -- got a packet
@@ -358,7 +358,7 @@ local function main()
             end
         elseif event == "monitor_touch" then
             -- handle a monitor touch event
-            renderer.handle_mouse(core.events.touch(param1, param2, param3))
+            renderer.handle_mouse(core.events.new_mouse_event(event, param1, param2, param3))
         elseif event == "speaker_audio_empty" then
             -- handle speaker buffer emptied
             sounder.continue()

coordinator/ui/components/boiler.lua

@@ -9,8 +9,8 @@ local DataIndicator  = require("graphics.elements.indicators.data")
 local StateIndicator = require("graphics.elements.indicators.state")
 local VerticalBar    = require("graphics.elements.indicators.vbar")
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 -- new boiler view
 ---@param root graphics_element parent
@@ -27,9 +27,9 @@ local function new_view(root, x, y, ps)
     local temp   = DataIndicator{parent=boiler,x=5,y=3,lu_colors=lu_col,label="Temp:",unit="K",format="%10.2f",value=0,width=22,fg_bg=text_fg_bg}
     local boil_r = DataIndicator{parent=boiler,x=5,y=4,lu_colors=lu_col,label="Boil:",unit="mB/t",format="%10.0f",value=0,commas=true,width=22,fg_bg=text_fg_bg}
 
-    ps.subscribe("computed_status", status.update)
-    ps.subscribe("temperature", temp.update)
-    ps.subscribe("boil_rate", boil_r.update)
+    status.register(ps, "computed_status", status.update)
+    temp.register(ps, "temperature", temp.update)
+    boil_r.register(ps, "boil_rate", boil_r.update)
 
     TextBox{parent=boiler,text="H",x=2,y=5,height=1,width=1,fg_bg=text_fg_bg}
     TextBox{parent=boiler,text="W",x=3,y=5,height=1,width=1,fg_bg=text_fg_bg}
@@ -41,10 +41,10 @@ local function new_view(root, x, y, ps)
     local steam = VerticalBar{parent=boiler,x=27,y=1,fg_bg=cpair(colors.white,colors.gray),height=4,width=1}
     local ccool = VerticalBar{parent=boiler,x=28,y=1,fg_bg=cpair(colors.lightBlue,colors.gray),height=4,width=1}
 
-    ps.subscribe("hcool_fill", hcool.update)
-    ps.subscribe("water_fill", water.update)
-    ps.subscribe("steam_fill", steam.update)
-    ps.subscribe("ccool_fill", ccool.update)
+    hcool.register(ps, "hcool_fill", hcool.update)
+    water.register(ps, "water_fill", water.update)
+    steam.register(ps, "steam_fill", steam.update)
+    ccool.register(ps, "ccool_fill", ccool.update)
 end
 
 return new_view

coordinator/ui/components/imatrix.lua

@@ -13,10 +13,10 @@ local PowerIndicator = require("graphics.elements.indicators.power")
 local StateIndicator = require("graphics.elements.indicators.state")
 local VerticalBar    = require("graphics.elements.indicators.vbar")
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new induction matrix view
 ---@param root graphics_element parent
@@ -50,15 +50,15 @@ local function new_view(root, x, y, data, ps, id)
     local avg_in   = PowerIndicator{parent=rect,x=7,y=9,lu_colors=lu_col,label="Avg. In: ",format="%8.2f",rate=true,value=0,width=26,fg_bg=text_fg_bg}
     local avg_out  = PowerIndicator{parent=rect,x=7,y=10,lu_colors=lu_col,label="Avg. Out:",format="%8.2f",rate=true,value=0,width=26,fg_bg=text_fg_bg}
 
-    ps.subscribe("computed_status", status.update)
-    ps.subscribe("energy", function (val) energy.update(util.joules_to_fe(val)) end)
-    ps.subscribe("max_energy", function (val) capacity.update(util.joules_to_fe(val)) end)
-    ps.subscribe("last_input", function (val) input.update(util.joules_to_fe(val)) end)
-    ps.subscribe("last_output", function (val) output.update(util.joules_to_fe(val)) end)
+    status.register(ps, "computed_status", status.update)
+    energy.register(ps, "energy", function (val) energy.update(util.joules_to_fe(val)) end)
+    capacity.register(ps, "max_energy", function (val) capacity.update(util.joules_to_fe(val)) end)
+    input.register(ps, "last_input", function (val) input.update(util.joules_to_fe(val)) end)
+    output.register(ps, "last_output", function (val) output.update(util.joules_to_fe(val)) end)
 
-    ps.subscribe("avg_charge", avg_chg.update)
-    ps.subscribe("avg_inflow", avg_in.update)
-    ps.subscribe("avg_outflow", avg_out.update)
+    avg_chg.register(ps, "avg_charge", avg_chg.update)
+    avg_in.register(ps, "avg_inflow", avg_in.update)
+    avg_out.register(ps, "avg_outflow", avg_out.update)
 
     local fill      = DataIndicator{parent=rect,x=11,y=12,lu_colors=lu_col,label="Fill:",unit="%",format="%8.2f",value=0,width=18,fg_bg=text_fg_bg}
 
@@ -68,10 +68,10 @@ local function new_view(root, x, y, data, ps, id)
     TextBox{parent=rect,text="Transfer Capacity",x=11,y=17,height=1,width=17,fg_bg=label_fg_bg}
     local trans_cap = PowerIndicator{parent=rect,x=19,y=18,lu_colors=lu_col,label="",format="%5.2f",rate=true,value=0,width=12,fg_bg=text_fg_bg}
 
-    ps.subscribe("cells", cells.update)
-    ps.subscribe("providers", providers.update)
-    ps.subscribe("energy_fill", function (val) fill.update(val * 100) end)
-    ps.subscribe("transfer_cap", function (val) trans_cap.update(util.joules_to_fe(val)) end)
+    cells.register(ps, "cells", cells.update)
+    providers.register(ps, "providers", providers.update)
+    fill.register(ps, "energy_fill", function (val) fill.update(val * 100) end)
+    trans_cap.register(ps, "transfer_cap", function (val) trans_cap.update(util.joules_to_fe(val)) end)
 
     local charge  = VerticalBar{parent=rect,x=2,y=2,fg_bg=cpair(colors.green,colors.gray),height=17,width=4}
     local in_cap  = VerticalBar{parent=rect,x=7,y=12,fg_bg=cpair(colors.red,colors.gray),height=7,width=1}
@@ -88,9 +88,9 @@ local function new_view(root, x, y, data, ps, id)
         end
     end
 
-    ps.subscribe("energy_fill", charge.update)
-    ps.subscribe("last_input", function (val) in_cap.update(calc_saturation(val)) end)
-    ps.subscribe("last_output", function (val) out_cap.update(calc_saturation(val)) end)
+    charge.register(ps, "energy_fill", charge.update)
+    in_cap.register(ps, "last_input", function (val) in_cap.update(calc_saturation(val)) end)
+    out_cap.register(ps, "last_output", function (val) out_cap.update(calc_saturation(val)) end)
 end
 
 return new_view

coordinator/ui/components/processctl.lua

@@ -1,4 +1,4 @@
-local tcd               = require("scada-common.tcallbackdsp")
+local tcd               = require("scada-common.tcd")
 local util              = require("scada-common.util")
 
 local iocontrol         = require("coordinator.iocontrol")
@@ -21,10 +21,10 @@ local HazardButton      = require("graphics.elements.controls.hazard_button")
 local RadioButton       = require("graphics.elements.controls.radio_button")
 local SpinboxNumeric    = require("graphics.elements.controls.spinbox_numeric")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 local period = core.flasher.PERIOD
 
@@ -33,7 +33,7 @@ local period = core.flasher.PERIOD
 ---@param x integer top left x
 ---@param y integer top left y
 local function new_view(root, x, y)
-    assert(root.height() >= (y + 24), "main display not of sufficient vertical resolution (add an additional row of monitors)")
+    assert(root.get_height() >= (y + 24), "main display not of sufficient vertical resolution (add an additional row of monitors)")
 
     local facility = iocontrol.get_db().facility
     local units = iocontrol.get_db().units
@@ -55,9 +55,9 @@ local function new_view(root, x, y)
     local ind_mat = IndicatorLight{parent=main,label="Induction Matrix",colors=cpair(colors.green,colors.gray)}
     local rad_mon = TriIndicatorLight{parent=main,label="Radiation Monitor",c1=colors.gray,c2=colors.yellow,c3=colors.green}
 
-    facility.ps.subscribe("all_sys_ok", all_ok.update)
-    facility.induction_ps_tbl[1].subscribe("computed_status", function (status) ind_mat.update(status > 1) end)
-    facility.ps.subscribe("rad_computed_status", rad_mon.update)
+    all_ok.register(facility.ps, "all_sys_ok", all_ok.update)
+    ind_mat.register(facility.induction_ps_tbl[1], "computed_status", function (status) ind_mat.update(status > 1) end)
+    rad_mon.register(facility.ps, "rad_computed_status", rad_mon.update)
 
     main.line_break()
 
@@ -66,10 +66,10 @@ local function new_view(root, x, y)
     local auto_ramp  = IndicatorLight{parent=main,label="Process Ramping",colors=cpair(colors.white,colors.gray),flash=true,period=period.BLINK_250_MS}
     local auto_sat   = IndicatorLight{parent=main,label="Min/Max Burn Rate",colors=cpair(colors.yellow,colors.gray)}
 
-    facility.ps.subscribe("auto_ready", auto_ready.update)
-    facility.ps.subscribe("auto_active", auto_act.update)
-    facility.ps.subscribe("auto_ramping", auto_ramp.update)
-    facility.ps.subscribe("auto_saturated", auto_sat.update)
+    auto_ready.register(facility.ps, "auto_ready", auto_ready.update)
+    auto_act.register(facility.ps, "auto_active", auto_act.update)
+    auto_ramp.register(facility.ps, "auto_ramping", auto_ramp.update)
+    auto_sat.register(facility.ps, "auto_saturated", auto_sat.update)
 
     main.line_break()
 
@@ -80,20 +80,20 @@ local function new_view(root, x, y)
     local fac_rad_h   = IndicatorLight{parent=main,label="Facility Radiation High",colors=cpair(colors.red,colors.gray),flash=true,period=period.BLINK_250_MS}
     local gen_fault   = IndicatorLight{parent=main,label="Gen. Control Fault",colors=cpair(colors.yellow,colors.gray),flash=true,period=period.BLINK_500_MS}
 
-    facility.ps.subscribe("auto_scram", auto_scram.update)
-    facility.ps.subscribe("as_matrix_dc", matrix_dc.update)
-    facility.ps.subscribe("as_matrix_fill", matrix_fill.update)
-    facility.ps.subscribe("as_crit_alarm", unit_crit.update)
-    facility.ps.subscribe("as_radiation", fac_rad_h.update)
-    facility.ps.subscribe("as_gen_fault", gen_fault.update)
+    auto_scram.register(facility.ps, "auto_scram", auto_scram.update)
+    matrix_dc.register(facility.ps, "as_matrix_dc", matrix_dc.update)
+    matrix_fill.register(facility.ps, "as_matrix_fill", matrix_fill.update)
+    unit_crit.register(facility.ps, "as_crit_alarm", unit_crit.update)
+    fac_rad_h.register(facility.ps, "as_radiation", fac_rad_h.update)
+    gen_fault.register(facility.ps, "as_gen_fault", gen_fault.update)
 
     TextBox{parent=main,y=23,text="Radiation",height=1,width=13,fg_bg=style.label}
     local radiation = RadIndicator{parent=main,label="",format="%9.3f",lu_colors=lu_cpair,width=13,fg_bg=bw_fg_bg}
-    facility.ps.subscribe("radiation", radiation.update)
+    radiation.register(facility.ps, "radiation", radiation.update)
 
     TextBox{parent=main,x=15,y=23,text="Linked RTUs",height=1,width=11,fg_bg=style.label}
     local rtu_count = DataIndicator{parent=main,x=15,y=24,label="",format="%11d",value=0,lu_colors=lu_cpair,width=11,fg_bg=bw_fg_bg}
-    facility.ps.subscribe("rtu_count", rtu_count.update)
+    rtu_count.register(facility.ps, "rtu_count", rtu_count.update)
 
     ---------------------
     -- process control --
@@ -115,8 +115,8 @@ local function new_view(root, x, y)
     TextBox{parent=burn_target,x=18,y=2,text="mB/t"}
     local burn_sum = DataIndicator{parent=targets,x=9,y=4,label="",format="%18.1f",value=0,unit="mB/t",commas=true,lu_colors=cpair(colors.black,colors.black),width=23,fg_bg=cpair(colors.black,colors.brown)}
 
-    facility.ps.subscribe("process_burn_target", b_target.set_value)
-    facility.ps.subscribe("burn_sum", burn_sum.update)
+    b_target.register(facility.ps, "process_burn_target", b_target.set_value)
+    burn_sum.register(facility.ps, "burn_sum", burn_sum.update)
 
     local chg_tag = Div{parent=targets,x=1,y=6,width=8,height=4,fg_bg=cpair(colors.black,colors.purple)}
     TextBox{parent=chg_tag,x=2,y=2,text="Charge Target",width=7,height=2}
@@ -126,8 +126,8 @@ local function new_view(root, x, y)
     TextBox{parent=chg_target,x=18,y=2,text="MFE"}
     local cur_charge = DataIndicator{parent=targets,x=9,y=9,label="",format="%19d",value=0,unit="MFE",commas=true,lu_colors=cpair(colors.black,colors.black),width=23,fg_bg=cpair(colors.black,colors.brown)}
 
-    facility.ps.subscribe("process_charge_target", c_target.set_value)
-    facility.induction_ps_tbl[1].subscribe("energy", function (j) cur_charge.update(util.joules_to_fe(j) / 1000000) end)
+    c_target.register(facility.ps, "process_charge_target", c_target.set_value)
+    cur_charge.register(facility.induction_ps_tbl[1], "energy", function (j) cur_charge.update(util.joules_to_fe(j) / 1000000) end)
 
     local gen_tag = Div{parent=targets,x=1,y=11,width=8,height=4,fg_bg=cpair(colors.black,colors.purple)}
     TextBox{parent=gen_tag,x=2,y=2,text="Gen. Target",width=7,height=2}
@@ -137,8 +137,8 @@ local function new_view(root, x, y)
     TextBox{parent=gen_target,x=18,y=2,text="kFE/t"}
     local cur_gen = DataIndicator{parent=targets,x=9,y=14,label="",format="%17d",value=0,unit="kFE/t",commas=true,lu_colors=cpair(colors.black,colors.black),width=23,fg_bg=cpair(colors.black,colors.brown)}
 
-    facility.ps.subscribe("process_gen_target", g_target.set_value)
-    facility.induction_ps_tbl[1].subscribe("last_input", function (j) cur_gen.update(util.round(util.joules_to_fe(j) / 1000)) end)
+    g_target.register(facility.ps, "process_gen_target", g_target.set_value)
+    cur_gen.register(facility.induction_ps_tbl[1], "last_input", function (j) cur_gen.update(util.round(util.joules_to_fe(j) / 1000)) end)
 
     -----------------
     -- unit limits --
@@ -160,12 +160,12 @@ local function new_view(root, x, y)
         rate_limits[i] = SpinboxNumeric{parent=lim_ctl,x=2,y=1,whole_num_precision=4,fractional_precision=1,min=0.1,arrow_fg_bg=cpair(colors.gray,colors.white),fg_bg=bw_fg_bg}
         TextBox{parent=lim_ctl,x=9,y=2,text="mB/t",width=4,height=1}
 
-        unit.unit_ps.subscribe("max_burn", rate_limits[i].set_max)
-        unit.unit_ps.subscribe("burn_limit", rate_limits[i].set_value)
+        rate_limits[i].register(unit.unit_ps, "max_burn", rate_limits[i].set_max)
+        rate_limits[i].register(unit.unit_ps, "burn_limit", rate_limits[i].set_value)
 
         local cur_burn = DataIndicator{parent=limit_div,x=9,y=_y+3,label="",format="%7.1f",value=0,unit="mB/t",commas=false,lu_colors=cpair(colors.black,colors.black),width=14,fg_bg=cpair(colors.black,colors.brown)}
 
-        unit.unit_ps.subscribe("act_burn_rate", cur_burn.update)
+        cur_burn.register(unit.unit_ps, "act_burn_rate", cur_burn.update)
     end
 
     -------------------
@@ -186,8 +186,8 @@ local function new_view(root, x, y)
         local ready    = IndicatorLight{parent=lights,x=2,y=2,label="Ready",colors=cpair(colors.green,colors.gray)}
         local degraded = IndicatorLight{parent=lights,x=2,y=3,label="Degraded",colors=cpair(colors.red,colors.gray),flash=true,period=period.BLINK_250_MS}
 
-        unit.unit_ps.subscribe("U_AutoReady", ready.update)
-        unit.unit_ps.subscribe("U_AutoDegraded", degraded.update)
+        ready.register(unit.unit_ps, "U_AutoReady", ready.update)
+        degraded.register(unit.unit_ps, "U_AutoDegraded", degraded.update)
     end
 
     -------------------------
@@ -197,14 +197,14 @@ local function new_view(root, x, y)
     local ctl_opts = { "Monitored Max Burn", "Combined Burn Rate", "Charge Level", "Generation Rate" }
     local mode = RadioButton{parent=proc,x=34,y=1,options=ctl_opts,callback=function()end,radio_colors=cpair(colors.purple,colors.black),radio_bg=colors.gray}
 
-    facility.ps.subscribe("process_mode", mode.set_value)
+    mode.register(facility.ps, "process_mode", mode.set_value)
 
     local u_stat = Rectangle{parent=proc,border=border(1,colors.gray,true),thin=true,width=31,height=4,x=1,y=16,fg_bg=bw_fg_bg}
     local stat_line_1 = TextBox{parent=u_stat,x=1,y=1,text="UNKNOWN",width=31,height=1,alignment=TEXT_ALIGN.CENTER,fg_bg=bw_fg_bg}
     local stat_line_2 = TextBox{parent=u_stat,x=1,y=2,text="awaiting data...",width=31,height=1,alignment=TEXT_ALIGN.CENTER,fg_bg=cpair(colors.gray, colors.white)}
 
-    facility.ps.subscribe("status_line_1", stat_line_1.set_value)
-    facility.ps.subscribe("status_line_2", stat_line_2.set_value)
+    stat_line_1.register(facility.ps, "status_line_1", stat_line_1.set_value)
+    stat_line_2.register(facility.ps, "status_line_2", stat_line_2.set_value)
 
     local auto_controls = Div{parent=proc,x=1,y=20,width=31,height=5,fg_bg=cpair(colors.gray,colors.white)}
 
@@ -233,11 +233,14 @@ local function new_view(root, x, y)
         tcd.dispatch(0.2, function () save.on_response(ack) end)
     end
 
-    facility.ps.subscribe("auto_ready", function (ready)
+    start.register(facility.ps, "auto_ready", function (ready)
         if ready and (not facility.auto_active) then start.enable() else start.disable() end
     end)
 
-    facility.ps.subscribe("auto_active", function (active)
+    -- REGISTER_NOTE: for optimization/brevity, due to not deleting anything but the whole element tree when it comes
+    -- to the process control display and coordinator GUI as a whole, child elements will not directly be registered here
+    -- (preventing garbage collection until the parent 'proc' is deleted)
+    proc.register(facility.ps, "auto_active", function (active)
         if active then
             b_target.disable()
             c_target.disable()
@@ -246,9 +249,7 @@ local function new_view(root, x, y)
             mode.disable()
             start.disable()
 
-            for i = 1, #rate_limits do
-                rate_limits[i].disable()
-            end
+            for i = 1, #rate_limits do rate_limits[i].disable() end
         else
             b_target.enable()
             c_target.enable()
@@ -257,9 +258,7 @@ local function new_view(root, x, y)
             mode.enable()
             if facility.auto_ready then start.enable() end
 
-            for i = 1, #rate_limits do
-                rate_limits[i].enable()
-            end
+            for i = 1, #rate_limits do rate_limits[i].enable() end
         end
     end)
 end

coordinator/ui/components/reactor.lua

@@ -11,8 +11,8 @@ local DataIndicator  = require("graphics.elements.indicators.data")
 local HorizontalBar  = require("graphics.elements.indicators.hbar")
 local StateIndicator = require("graphics.elements.indicators.state")
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 -- create new reactor view
 ---@param root graphics_element parent
@@ -30,10 +30,10 @@ local function new_view(root, x, y, ps)
     local burn_r    = DataIndicator{parent=reactor,x=2,y=4,lu_colors=lu_col,label="Burn Rate:",unit="mB/t",format="%10.2f",value=0,width=26,fg_bg=text_fg_bg}
     local heating_r = DataIndicator{parent=reactor,x=2,y=5,lu_colors=lu_col,label="Heating:",unit="mB/t",format="%12.0f",value=0,commas=true,width=26,fg_bg=text_fg_bg}
 
-    ps.subscribe("computed_status", status.update)
-    ps.subscribe("temp", core_temp.update)
-    ps.subscribe("act_burn_rate", burn_r.update)
-    ps.subscribe("heating_rate", heating_r.update)
+    status.register(ps, "computed_status", status.update)
+    core_temp.register(ps, "temp", core_temp.update)
+    burn_r.register(ps, "act_burn_rate", burn_r.update)
+    heating_r.register(ps, "heating_rate", heating_r.update)
 
     local reactor_fills = Rectangle{parent=root,border=border(1, colors.gray, true),width=24,height=7,x=(x + 29),y=y}
 
@@ -47,7 +47,7 @@ local function new_view(root, x, y, ps)
     local hcool = HorizontalBar{parent=reactor_fills,x=8,y=4,show_percent=true,bar_fg_bg=cpair(colors.white,colors.gray),height=1,width=14}
     local waste = HorizontalBar{parent=reactor_fills,x=8,y=5,show_percent=true,bar_fg_bg=cpair(colors.brown,colors.gray),height=1,width=14}
 
-    ps.subscribe("ccool_type", function (type)
+    ccool.register(ps, "ccool_type", function (type)
         if type == types.FLUID.SODIUM then
             ccool.recolor(cpair(colors.lightBlue, colors.gray))
         else
@@ -55,7 +55,7 @@ local function new_view(root, x, y, ps)
         end
     end)
 
-    ps.subscribe("hcool_type", function (type)
+    hcool.register(ps, "hcool_type", function (type)
         if type == types.FLUID.SUPERHEATED_SODIUM then
             hcool.recolor(cpair(colors.orange, colors.gray))
         else
@@ -63,10 +63,10 @@ local function new_view(root, x, y, ps)
         end
     end)
 
-    ps.subscribe("fuel_fill", fuel.update)
-    ps.subscribe("ccool_fill", ccool.update)
-    ps.subscribe("hcool_fill", hcool.update)
-    ps.subscribe("waste_fill", waste.update)
+    fuel.register(ps, "fuel_fill", fuel.update)
+    ccool.register(ps, "ccool_fill", ccool.update)
+    hcool.register(ps, "hcool_fill", hcool.update)
+    waste.register(ps, "waste_fill", waste.update)
 end
 
 return new_view

coordinator/ui/components/turbine.lua

@@ -12,8 +12,8 @@ local PowerIndicator = require("graphics.elements.indicators.power")
 local StateIndicator = require("graphics.elements.indicators.state")
 local VerticalBar    = require("graphics.elements.indicators.vbar")
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 -- new turbine view
 ---@param root graphics_element parent
@@ -30,9 +30,9 @@ local function new_view(root, x, y, ps)
     local prod_rate = PowerIndicator{parent=turbine,x=5,y=3,lu_colors=lu_col,label="",format="%10.2f",value=0,rate=true,width=16,fg_bg=text_fg_bg}
     local flow_rate = DataIndicator{parent=turbine,x=5,y=4,lu_colors=lu_col,label="",unit="mB/t",format="%10.0f",value=0,commas=true,width=16,fg_bg=text_fg_bg}
 
-    ps.subscribe("computed_status", status.update)
-    ps.subscribe("prod_rate", function (val) prod_rate.update(util.joules_to_fe(val)) end)
-    ps.subscribe("flow_rate", flow_rate.update)
+    status.register(ps, "computed_status", status.update)
+    prod_rate.register(ps, "prod_rate", function (val) prod_rate.update(util.joules_to_fe(val)) end)
+    flow_rate.register(ps, "flow_rate", flow_rate.update)
 
     local steam  = VerticalBar{parent=turbine,x=2,y=1,fg_bg=cpair(colors.white,colors.gray),height=4,width=1}
     local energy = VerticalBar{parent=turbine,x=3,y=1,fg_bg=cpair(colors.green,colors.gray),height=4,width=1}
@@ -40,8 +40,8 @@ local function new_view(root, x, y, ps)
     TextBox{parent=turbine,text="S",x=2,y=5,height=1,width=1,fg_bg=text_fg_bg}
     TextBox{parent=turbine,text="E",x=3,y=5,height=1,width=1,fg_bg=text_fg_bg}
 
-    ps.subscribe("steam_fill", steam.update)
-    ps.subscribe("energy_fill", energy.update)
+    steam.register(ps, "steam_fill", steam.update)
+    energy.register(ps, "energy_fill", energy.update)
 end
 
 return new_view

coordinator/ui/components/unit_detail.lua

@@ -26,10 +26,10 @@ local PushButton        = require("graphics.elements.controls.push_button")
 local RadioButton       = require("graphics.elements.controls.radio_button")
 local SpinboxNumeric    = require("graphics.elements.controls.spinbox_numeric")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 local period = core.flasher.PERIOD
 
@@ -79,16 +79,16 @@ local function init(parent, id)
     -----------------------------
 
     local core_map = CoreMap{parent=main,x=2,y=3,reactor_l=18,reactor_w=18}
-    u_ps.subscribe("temp", core_map.update)
-    u_ps.subscribe("size", function (s) core_map.resize(s[1], s[2]) end)
+    core_map.register(u_ps, "temp", core_map.update)
+    core_map.register(u_ps, "size", function (s) core_map.resize(s[1], s[2]) end)
 
     TextBox{parent=main,x=12,y=22,text="Heating Rate",height=1,width=12,fg_bg=style.label}
     local heating_r = DataIndicator{parent=main,x=12,label="",format="%14.0f",value=0,unit="mB/t",commas=true,lu_colors=lu_cpair,width=19,fg_bg=bw_fg_bg}
-    u_ps.subscribe("heating_rate", heating_r.update)
+    heating_r.register(u_ps, "heating_rate", heating_r.update)
 
     TextBox{parent=main,x=12,y=25,text="Commanded Burn Rate",height=1,width=19,fg_bg=style.label}
     local burn_r = DataIndicator{parent=main,x=12,label="",format="%14.2f",value=0,unit="mB/t",lu_colors=lu_cpair,width=19,fg_bg=bw_fg_bg}
-    u_ps.subscribe("burn_rate", burn_r.update)
+    burn_r.register(u_ps, "burn_rate", burn_r.update)
 
     TextBox{parent=main,text="F",x=2,y=22,width=1,height=1,fg_bg=style.label}
     TextBox{parent=main,text="C",x=4,y=22,width=1,height=1,fg_bg=style.label}
@@ -102,12 +102,12 @@ local function init(parent, id)
     local hcool = VerticalBar{parent=main,x=8,y=23,fg_bg=cpair(colors.white,colors.gray),height=4,width=1}
     local waste = VerticalBar{parent=main,x=10,y=23,fg_bg=cpair(colors.brown,colors.gray),height=4,width=1}
 
-    u_ps.subscribe("fuel_fill", fuel.update)
-    u_ps.subscribe("ccool_fill", ccool.update)
-    u_ps.subscribe("hcool_fill", hcool.update)
-    u_ps.subscribe("waste_fill", waste.update)
+    fuel.register(u_ps, "fuel_fill", fuel.update)
+    ccool.register(u_ps, "ccool_fill", ccool.update)
+    hcool.register(u_ps, "hcool_fill", hcool.update)
+    waste.register(u_ps, "waste_fill", waste.update)
 
-    u_ps.subscribe("ccool_type", function (type)
+    ccool.register(u_ps, "ccool_type", function (type)
         if type == "mekanism:sodium" then
             ccool.recolor(cpair(colors.lightBlue, colors.gray))
         else
@@ -115,7 +115,7 @@ local function init(parent, id)
         end
     end)
 
-    u_ps.subscribe("hcool_type", function (type)
+    hcool.register(u_ps, "hcool_type", function (type)
         if type == "mekanism:superheated_sodium" then
             hcool.recolor(cpair(colors.orange, colors.gray))
         else
@@ -125,19 +125,19 @@ local function init(parent, id)
 
     TextBox{parent=main,x=32,y=22,text="Core Temp",height=1,width=9,fg_bg=style.label}
     local core_temp = DataIndicator{parent=main,x=32,label="",format="%11.2f",value=0,unit="K",lu_colors=lu_cpair,width=13,fg_bg=bw_fg_bg}
-    u_ps.subscribe("temp", core_temp.update)
+    core_temp.register(u_ps, "temp", core_temp.update)
 
     TextBox{parent=main,x=32,y=25,text="Burn Rate",height=1,width=9,fg_bg=style.label}
     local act_burn_r = DataIndicator{parent=main,x=32,label="",format="%8.2f",value=0,unit="mB/t",lu_colors=lu_cpair,width=13,fg_bg=bw_fg_bg}
-    u_ps.subscribe("act_burn_rate", act_burn_r.update)
+    act_burn_r.register(u_ps, "act_burn_rate", act_burn_r.update)
 
     TextBox{parent=main,x=32,y=28,text="Damage",height=1,width=6,fg_bg=style.label}
     local damage_p = DataIndicator{parent=main,x=32,label="",format="%11.0f",value=0,unit="%",lu_colors=lu_cpair,width=13,fg_bg=bw_fg_bg}
-    u_ps.subscribe("damage", damage_p.update)
+    damage_p.register(u_ps, "damage", damage_p.update)
 
     TextBox{parent=main,x=32,y=31,text="Radiation",height=1,width=21,fg_bg=style.label}
     local radiation = RadIndicator{parent=main,x=32,label="",format="%9.3f",lu_colors=lu_cpair,width=13,fg_bg=bw_fg_bg}
-    u_ps.subscribe("radiation", radiation.update)
+    radiation.register(u_ps, "radiation", radiation.update)
 
     -------------------
     -- system status --
@@ -147,8 +147,8 @@ local function init(parent, id)
     local stat_line_1 = TextBox{parent=u_stat,x=1,y=1,text="UNKNOWN",width=33,height=1,alignment=TEXT_ALIGN.CENTER,fg_bg=bw_fg_bg}
     local stat_line_2 = TextBox{parent=u_stat,x=1,y=2,text="awaiting data...",width=33,height=1,alignment=TEXT_ALIGN.CENTER,fg_bg=cpair(colors.gray, colors.white)}
 
-    u_ps.subscribe("U_StatusLine1", stat_line_1.set_value)
-    u_ps.subscribe("U_StatusLine2", stat_line_2.set_value)
+    stat_line_1.register(u_ps, "U_StatusLine1", stat_line_1.set_value)
+    stat_line_2.register(u_ps, "U_StatusLine2", stat_line_2.set_value)
 
     -----------------
     -- annunciator --
@@ -163,9 +163,9 @@ local function init(parent, id)
     local plc_hbeat  = IndicatorLight{parent=annunciator,label="PLC Heartbeat",colors=cpair(colors.white,colors.gray)}
     local rad_mon    = TriIndicatorLight{parent=annunciator,label="Radiation Monitor",c1=colors.gray,c2=colors.yellow,c3=colors.green}
 
-    u_ps.subscribe("PLCOnline", plc_online.update)
-    u_ps.subscribe("PLCHeartbeat", plc_hbeat.update)
-    u_ps.subscribe("RadiationMonitor", rad_mon.update)
+    plc_online.register(u_ps, "PLCOnline", plc_online.update)
+    plc_hbeat.register(u_ps, "PLCHeartbeat", plc_hbeat.update)
+    rad_mon.register(u_ps, "RadiationMonitor", rad_mon.update)
 
     annunciator.line_break()
 
@@ -173,8 +173,8 @@ local function init(parent, id)
     local r_active = IndicatorLight{parent=annunciator,label="Active",colors=cpair(colors.green,colors.gray)}
     local r_auto   = IndicatorLight{parent=annunciator,label="Automatic Control",colors=cpair(colors.white,colors.gray)}
 
-    u_ps.subscribe("status", r_active.update)
-    u_ps.subscribe("AutoControl", r_auto.update)
+    r_active.register(u_ps, "status", r_active.update)
+    r_auto.register(u_ps, "AutoControl", r_auto.update)
 
     -- main unit transient/warning annunciator panel
     local r_scram = IndicatorLight{parent=annunciator,label="Reactor SCRAM",colors=cpair(colors.red,colors.gray)}
@@ -190,18 +190,18 @@ local function init(parent, id)
     local r_wloc  = IndicatorLight{parent=annunciator,label="Waste Line Occlusion",colors=cpair(colors.yellow,colors.gray)}
     local r_hsrt  = IndicatorLight{parent=annunciator,label="Startup Rate High",colors=cpair(colors.yellow,colors.gray)}
 
-    u_ps.subscribe("ReactorSCRAM", r_scram.update)
-    u_ps.subscribe("ManualReactorSCRAM", r_mscrm.update)
-    u_ps.subscribe("AutoReactorSCRAM", r_ascrm.update)
-    u_ps.subscribe("RadiationWarning", rad_wrn.update)
-    u_ps.subscribe("RCPTrip", r_rtrip.update)
-    u_ps.subscribe("RCSFlowLow", r_cflow.update)
-    u_ps.subscribe("CoolantLevelLow", r_clow.update)
-    u_ps.subscribe("ReactorTempHigh", r_temp.update)
-    u_ps.subscribe("ReactorHighDeltaT", r_rhdt.update)
-    u_ps.subscribe("FuelInputRateLow", r_firl.update)
-    u_ps.subscribe("WasteLineOcclusion", r_wloc.update)
-    u_ps.subscribe("HighStartupRate", r_hsrt.update)
+    r_scram.register(u_ps, "ReactorSCRAM", r_scram.update)
+    r_mscrm.register(u_ps, "ManualReactorSCRAM", r_mscrm.update)
+    r_ascrm.register(u_ps, "AutoReactorSCRAM", r_ascrm.update)
+    rad_wrn.register(u_ps, "RadiationWarning", rad_wrn.update)
+    r_rtrip.register(u_ps, "RCPTrip", r_rtrip.update)
+    r_cflow.register(u_ps, "RCSFlowLow", r_cflow.update)
+    r_clow.register(u_ps, "CoolantLevelLow", r_clow.update)
+    r_temp.register(u_ps, "ReactorTempHigh", r_temp.update)
+    r_rhdt.register(u_ps, "ReactorHighDeltaT", r_rhdt.update)
+    r_firl.register(u_ps, "FuelInputRateLow", r_firl.update)
+    r_wloc.register(u_ps, "WasteLineOcclusion", r_wloc.update)
+    r_hsrt.register(u_ps, "HighStartupRate", r_hsrt.update)
 
     -- RPS annunciator panel
 
@@ -220,16 +220,16 @@ local function init(parent, id)
     local rps_tmo = IndicatorLight{parent=rps_annunc,label="Connection Timeout",colors=cpair(colors.yellow,colors.gray),flash=true,period=period.BLINK_500_MS}
     local rps_sfl = IndicatorLight{parent=rps_annunc,label="System Failure",colors=cpair(colors.orange,colors.gray),flash=true,period=period.BLINK_500_MS}
 
-    u_ps.subscribe("rps_tripped", rps_trp.update)
-    u_ps.subscribe("high_dmg", rps_dmg.update)
-    u_ps.subscribe("ex_hcool", rps_exh.update)
-    u_ps.subscribe("ex_waste", rps_exw.update)
-    u_ps.subscribe("high_temp", rps_tmp.update)
-    u_ps.subscribe("no_fuel", rps_nof.update)
-    u_ps.subscribe("low_cool", rps_loc.update)
-    u_ps.subscribe("fault", rps_flt.update)
-    u_ps.subscribe("timeout", rps_tmo.update)
-    u_ps.subscribe("sys_fail", rps_sfl.update)
+    rps_trp.register(u_ps, "rps_tripped", rps_trp.update)
+    rps_dmg.register(u_ps, "high_dmg", rps_dmg.update)
+    rps_exh.register(u_ps, "ex_hcool", rps_exh.update)
+    rps_exw.register(u_ps, "ex_waste", rps_exw.update)
+    rps_tmp.register(u_ps, "high_temp", rps_tmp.update)
+    rps_nof.register(u_ps, "no_fuel", rps_nof.update)
+    rps_loc.register(u_ps, "low_cool", rps_loc.update)
+    rps_flt.register(u_ps, "fault", rps_flt.update)
+    rps_tmo.register(u_ps, "timeout", rps_tmo.update)
+    rps_sfl.register(u_ps, "sys_fail", rps_sfl.update)
 
     -- cooling annunciator panel
 
@@ -245,12 +245,12 @@ local function init(parent, id)
     local c_sfm  = IndicatorLight{parent=rcs_annunc,label="Steam Feed Mismatch",colors=cpair(colors.yellow,colors.gray)}
     local c_mwrf = IndicatorLight{parent=rcs_annunc,label="Max Water Return Feed",colors=cpair(colors.yellow,colors.gray)}
 
-    u_ps.subscribe("RCSFault", c_flt.update)
-    u_ps.subscribe("EmergencyCoolant", c_emg.update)
-    u_ps.subscribe("CoolantFeedMismatch", c_cfm.update)
-    u_ps.subscribe("BoilRateMismatch", c_brm.update)
-    u_ps.subscribe("SteamFeedMismatch", c_sfm.update)
-    u_ps.subscribe("MaxWaterReturnFeed", c_mwrf.update)
+    c_flt.register(u_ps, "RCSFault", c_flt.update)
+    c_emg.register(u_ps, "EmergencyCoolant", c_emg.update)
+    c_cfm.register(u_ps, "CoolantFeedMismatch", c_cfm.update)
+    c_brm.register(u_ps, "BoilRateMismatch", c_brm.update)
+    c_sfm.register(u_ps, "SteamFeedMismatch", c_sfm.update)
+    c_mwrf.register(u_ps, "MaxWaterReturnFeed", c_mwrf.update)
 
     local available_space = 16 - (unit.num_boilers * 2 + unit.num_turbines * 4)
 
@@ -267,11 +267,11 @@ local function init(parent, id)
     if unit.num_boilers > 0 then
         TextBox{parent=rcs_tags,x=1,text="B1",width=2,height=1,fg_bg=bw_fg_bg}
         local b1_wll = IndicatorLight{parent=rcs_annunc,label="Water Level Low",colors=cpair(colors.red,colors.gray)}
-        b_ps[1].subscribe("WasterLevelLow", b1_wll.update)
+        b1_wll.register(b_ps[1], "WasterLevelLow", b1_wll.update)
 
         TextBox{parent=rcs_tags,text="B1",width=2,height=1,fg_bg=bw_fg_bg}
         local b1_hr = IndicatorLight{parent=rcs_annunc,label="Heating Rate Low",colors=cpair(colors.yellow,colors.gray)}
-        b_ps[1].subscribe("HeatingRateLow", b1_hr.update)
+        b1_hr.register(b_ps[1], "HeatingRateLow", b1_hr.update)
     end
     if unit.num_boilers > 1 then
         -- note, can't (shouldn't for sure...) have 0 turbines
@@ -283,11 +283,11 @@ local function init(parent, id)
 
         TextBox{parent=rcs_tags,text="B2",width=2,height=1,fg_bg=bw_fg_bg}
         local b2_wll = IndicatorLight{parent=rcs_annunc,label="Water Level Low",colors=cpair(colors.red,colors.gray)}
-        b_ps[2].subscribe("WasterLevelLow", b2_wll.update)
+        b2_wll.register(b_ps[2], "WasterLevelLow", b2_wll.update)
 
         TextBox{parent=rcs_tags,text="B2",width=2,height=1,fg_bg=bw_fg_bg}
         local b2_hr = IndicatorLight{parent=rcs_annunc,label="Heating Rate Low",colors=cpair(colors.yellow,colors.gray)}
-        b_ps[2].subscribe("HeatingRateLow", b2_hr.update)
+        b2_hr.register(b_ps[2], "HeatingRateLow", b2_hr.update)
     end
 
     -- turbine annunciator panels
@@ -296,19 +296,19 @@ local function init(parent, id)
 
     TextBox{parent=rcs_tags,text="T1",width=2,height=1,fg_bg=bw_fg_bg}
     local t1_sdo = TriIndicatorLight{parent=rcs_annunc,label="Steam Relief Valve Open",c1=colors.gray,c2=colors.yellow,c3=colors.red}
-    t_ps[1].subscribe("SteamDumpOpen", t1_sdo.update)
+    t1_sdo.register(t_ps[1], "SteamDumpOpen", t1_sdo.update)
 
     TextBox{parent=rcs_tags,text="T1",width=2,height=1,fg_bg=bw_fg_bg}
     local t1_tos = IndicatorLight{parent=rcs_annunc,label="Turbine Over Speed",colors=cpair(colors.red,colors.gray)}
-    t_ps[1].subscribe("TurbineOverSpeed", t1_tos.update)
+    t1_tos.register(t_ps[1], "TurbineOverSpeed", t1_tos.update)
 
     TextBox{parent=rcs_tags,text="T1",width=2,height=1,fg_bg=bw_fg_bg}
     local t1_gtrp = IndicatorLight{parent=rcs_annunc,label="Generator Trip",colors=cpair(colors.yellow,colors.gray),flash=true,period=period.BLINK_250_MS}
-    t_ps[1].subscribe("GeneratorTrip", t1_gtrp.update)
+    t1_gtrp.register(t_ps[1], "GeneratorTrip", t1_gtrp.update)
 
     TextBox{parent=rcs_tags,text="T1",width=2,height=1,fg_bg=bw_fg_bg}
     local t1_trp = IndicatorLight{parent=rcs_annunc,label="Turbine Trip",colors=cpair(colors.red,colors.gray),flash=true,period=period.BLINK_250_MS}
-    t_ps[1].subscribe("TurbineTrip", t1_trp.update)
+    t1_trp.register(t_ps[1], "TurbineTrip", t1_trp.update)
 
     if unit.num_turbines > 1 then
         if (available_space > 2 and unit.num_turbines == 2) or available_space > 3 then
@@ -317,19 +317,19 @@ local function init(parent, id)
 
         TextBox{parent=rcs_tags,text="T2",width=2,height=1,fg_bg=bw_fg_bg}
         local t2_sdo = TriIndicatorLight{parent=rcs_annunc,label="Steam Relief Valve Open",c1=colors.gray,c2=colors.yellow,c3=colors.red}
-        t_ps[2].subscribe("SteamDumpOpen", t2_sdo.update)
+        t2_sdo.register(t_ps[2], "SteamDumpOpen", t2_sdo.update)
 
         TextBox{parent=rcs_tags,text="T2",width=2,height=1,fg_bg=bw_fg_bg}
         local t2_tos = IndicatorLight{parent=rcs_annunc,label="Turbine Over Speed",colors=cpair(colors.red,colors.gray)}
-        t_ps[2].subscribe("TurbineOverSpeed", t2_tos.update)
+        t2_tos.register(t_ps[2], "TurbineOverSpeed", t2_tos.update)
 
         TextBox{parent=rcs_tags,text="T2",width=2,height=1,fg_bg=bw_fg_bg}
         local t2_gtrp = IndicatorLight{parent=rcs_annunc,label="Generator Trip",colors=cpair(colors.yellow,colors.gray),flash=true,period=period.BLINK_250_MS}
-        t_ps[2].subscribe("GeneratorTrip", t2_gtrp.update)
+        t2_gtrp.register(t_ps[2], "GeneratorTrip", t2_gtrp.update)
 
         TextBox{parent=rcs_tags,text="T2",width=2,height=1,fg_bg=bw_fg_bg}
         local t2_trp = IndicatorLight{parent=rcs_annunc,label="Turbine Trip",colors=cpair(colors.red,colors.gray),flash=true,period=period.BLINK_250_MS}
-        t_ps[2].subscribe("TurbineTrip", t2_trp.update)
+        t2_trp.register(t_ps[2], "TurbineTrip", t2_trp.update)
     end
 
     if unit.num_turbines > 2 then
@@ -337,19 +337,19 @@ local function init(parent, id)
 
         TextBox{parent=rcs_tags,text="T3",width=2,height=1,fg_bg=bw_fg_bg}
         local t3_sdo = TriIndicatorLight{parent=rcs_annunc,label="Steam Relief Valve Open",c1=colors.gray,c2=colors.yellow,c3=colors.red}
-        t_ps[3].subscribe("SteamDumpOpen", t3_sdo.update)
+        t3_sdo.register(t_ps[3], "SteamDumpOpen", t3_sdo.update)
 
         TextBox{parent=rcs_tags,text="T3",width=2,height=1,fg_bg=bw_fg_bg}
         local t3_tos = IndicatorLight{parent=rcs_annunc,label="Turbine Over Speed",colors=cpair(colors.red,colors.gray)}
-        t_ps[3].subscribe("TurbineOverSpeed", t3_tos.update)
+        t3_tos.register(t_ps[3], "TurbineOverSpeed", t3_tos.update)
 
         TextBox{parent=rcs_tags,text="T3",width=2,height=1,fg_bg=bw_fg_bg}
         local t3_gtrp = IndicatorLight{parent=rcs_annunc,label="Generator Trip",colors=cpair(colors.yellow,colors.gray),flash=true,period=period.BLINK_250_MS}
-        t_ps[3].subscribe("GeneratorTrip", t3_gtrp.update)
+        t3_gtrp.register(t_ps[3], "GeneratorTrip", t3_gtrp.update)
 
         TextBox{parent=rcs_tags,text="T3",width=2,height=1,fg_bg=bw_fg_bg}
         local t3_trp = IndicatorLight{parent=rcs_annunc,label="Turbine Trip",colors=cpair(colors.red,colors.gray),flash=true,period=period.BLINK_250_MS}
-        t_ps[3].subscribe("TurbineTrip", t3_trp.update)
+        t3_trp.register(t_ps[3], "TurbineTrip", t3_trp.update)
     end
 
     ----------------------
@@ -365,8 +365,8 @@ local function init(parent, id)
     local set_burn = function () unit.set_burn(burn_rate.get_value()) end
     local set_burn_btn = PushButton{parent=burn_control,x=14,y=2,text="SET",min_width=5,fg_bg=cpair(colors.black,colors.yellow),active_fg_bg=cpair(colors.white,colors.gray),dis_fg_bg=dis_colors,callback=set_burn}
 
-    u_ps.subscribe("burn_rate", burn_rate.set_value)
-    u_ps.subscribe("max_burn", burn_rate.set_max)
+    burn_rate.register(u_ps, "burn_rate", burn_rate.set_value)
+    burn_rate.register(u_ps, "max_burn", burn_rate.set_max)
 
     local start = HazardButton{parent=main,x=2,y=28,text="START",accent=colors.lightBlue,dis_colors=dis_colors,callback=unit.start,fg_bg=hzd_fg_bg}
     local ack_a = HazardButton{parent=main,x=12,y=32,text="ACK \x13",accent=colors.orange,dis_colors=dis_colors,callback=unit.ack_alarms,fg_bg=hzd_fg_bg}
@@ -387,9 +387,12 @@ local function init(parent, id)
         end
     end
 
-    u_ps.subscribe("status", start_button_en_check)
-    u_ps.subscribe("rps_tripped", start_button_en_check)
-    u_ps.subscribe("rps_tripped", function (active) if active then reset.enable() else reset.disable() end end)
+    start.register(u_ps, "status", start_button_en_check)
+    start.register(u_ps, "rps_tripped", start_button_en_check)
+    start.register(u_ps, "auto_group_id", start_button_en_check)
+    start.register(u_ps, "AutoControl", start_button_en_check)
+
+    reset.register(u_ps, "rps_tripped", function (active) if active then reset.enable() else reset.disable() end end)
 
     TextBox{parent=main,text="WASTE PROCESSING",fg_bg=cpair(colors.black,colors.brown),alignment=TEXT_ALIGN.CENTER,width=33,height=1,x=46,y=48}
     local waste_proc = Rectangle{parent=main,border=border(1,colors.brown,true),thin=true,width=33,height=3,x=46,y=49}
@@ -397,7 +400,7 @@ local function init(parent, id)
 
     local waste_mode = MultiButton{parent=waste_div,x=1,y=1,options=waste_opts,callback=unit.set_waste,min_width=6}
 
-    u_ps.subscribe("U_WasteMode", waste_mode.set_value)
+    waste_mode.register(u_ps, "U_WasteMode", waste_mode.set_value)
 
     ----------------------
     -- alarm management --
@@ -420,20 +423,20 @@ local function init(parent, id)
     local a_clt = AlarmLight{parent=alarm_panel,x=6,label="RCS Transient",c1=colors.gray,c2=colors.yellow,c3=colors.green,flash=true,period=period.BLINK_500_MS}
     local a_tbt = AlarmLight{parent=alarm_panel,x=6,label="Turbine Trip",c1=colors.gray,c2=colors.red,c3=colors.green,flash=true,period=period.BLINK_250_MS}
 
-    u_ps.subscribe("Alarm_1", a_brc.update)
-    u_ps.subscribe("Alarm_2", a_rad.update)
-    u_ps.subscribe("Alarm_4", a_dmg.update)
+    a_brc.register(u_ps, "Alarm_1", a_brc.update)
+    a_rad.register(u_ps, "Alarm_2", a_rad.update)
+    a_dmg.register(u_ps, "Alarm_4", a_dmg.update)
 
-    u_ps.subscribe("Alarm_3", a_rcl.update)
-    u_ps.subscribe("Alarm_5", a_rcd.update)
-    u_ps.subscribe("Alarm_6", a_rot.update)
-    u_ps.subscribe("Alarm_7", a_rht.update)
-    u_ps.subscribe("Alarm_8", a_rwl.update)
-    u_ps.subscribe("Alarm_9", a_rwh.update)
+    a_rcl.register(u_ps, "Alarm_3", a_rcl.update)
+    a_rcd.register(u_ps, "Alarm_5", a_rcd.update)
+    a_rot.register(u_ps, "Alarm_6", a_rot.update)
+    a_rht.register(u_ps, "Alarm_7", a_rht.update)
+    a_rwl.register(u_ps, "Alarm_8", a_rwl.update)
+    a_rwh.register(u_ps, "Alarm_9", a_rwh.update)
 
-    u_ps.subscribe("Alarm_10", a_rps.update)
-    u_ps.subscribe("Alarm_11", a_clt.update)
-    u_ps.subscribe("Alarm_12", a_tbt.update)
+    a_rps.register(u_ps, "Alarm_10", a_rps.update)
+    a_clt.register(u_ps, "Alarm_11", a_clt.update)
+    a_tbt.register(u_ps, "Alarm_12", a_tbt.update)
 
     -- ack's and resets
 
@@ -487,7 +490,7 @@ local function init(parent, id)
 
     local group = RadioButton{parent=auto_div,options=ctl_opts,callback=function()end,radio_colors=cpair(colors.blue,colors.white),radio_bg=colors.gray}
 
-    u_ps.subscribe("auto_group_id", function (gid) group.set_value(gid + 1) end)
+    group.register(u_ps, "auto_group_id", function (gid) group.set_value(gid + 1) end)
 
     auto_div.line_break()
 
@@ -499,44 +502,35 @@ local function init(parent, id)
     TextBox{parent=auto_div,text="Prio. Group",height=1,width=11,fg_bg=style.label}
     local auto_grp = TextBox{parent=auto_div,text="Manual",height=1,width=11,fg_bg=bw_fg_bg}
 
-    u_ps.subscribe("auto_group", auto_grp.set_value)
+    auto_grp.register(u_ps, "auto_group", auto_grp.set_value)
 
     auto_div.line_break()
 
     local a_rdy = IndicatorLight{parent=auto_div,label="Ready",x=2,colors=cpair(colors.green,colors.gray)}
     local a_stb = IndicatorLight{parent=auto_div,label="Standby",x=2,colors=cpair(colors.white,colors.gray),flash=true,period=period.BLINK_1000_MS}
 
-    u_ps.subscribe("U_AutoReady", a_rdy.update)
+    a_rdy.register(u_ps, "U_AutoReady", a_rdy.update)
 
     -- update standby indicator
-    u_ps.subscribe("status", function (active)
+    a_stb.register(u_ps, "status", function (active)
         a_stb.update(unit.annunciator.AutoControl and (not active))
     end)
-
-    -- enable and disable controls based on group assignment
-    u_ps.subscribe("auto_group_id", function (gid)
-        start_button_en_check()
-
-        if gid == 0 then
-            burn_rate.enable()
-            set_burn_btn.enable()
-        else
-            burn_rate.disable()
-            set_burn_btn.disable()
-        end
-    end)
-
-    -- enable and disable controls based on auto control state (start button is handled separately)
-    u_ps.subscribe("AutoControl", function (auto_active)
-        start_button_en_check()
-
+    a_stb.register(u_ps, "AutoControl", function (auto_active)
         if auto_active then
             a_stb.update(unit.reactor_data.mek_status.status == false)
         else a_stb.update(false) end
     end)
 
+    -- enable/disable controls based on group assignment (start button is separate)
+    burn_rate.register(u_ps, "auto_group_id", function (gid)
+        if gid == 0 then burn_rate.enable() else burn_rate.disable() end
+    end)
+    set_burn_btn.register(u_ps, "auto_group_id", function (gid)
+        if gid == 0 then set_burn_btn.enable() else set_burn_btn.disable() end
+    end)
+
     -- can't change group if auto is engaged regardless of if this unit is part of auto control
-    f_ps.subscribe("auto_active", function (auto_active)
+    set_grp_btn.register(f_ps, "auto_active", function (auto_active)
         if auto_active then set_grp_btn.disable() else set_grp_btn.enable() end
     end)
 

coordinator/ui/components/unit_overview.lua

@@ -14,9 +14,9 @@ local Div          = require("graphics.elements.div")
 local PipeNetwork  = require("graphics.elements.pipenet")
 local TextBox      = require("graphics.elements.textbox")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local pipe = core.graphics.pipe
+local pipe = core.pipe
 
 -- make a new unit overview window
 ---@param parent graphics_element parent
@@ -38,7 +38,7 @@ local function make(parent, x, y, unit)
         height = 17
     end
 
-    assert(parent.height() >= (y + height), "main display not of sufficient vertical resolution (add an additional row of monitors)")
+    assert(parent.get_height() >= (y + height), "main display not of sufficient vertical resolution (add an additional row of monitors)")
 
     -- bounding box div
     local root = Div{parent=parent,x=x,y=y,width=80,height=height}

coordinator/ui/layout/main_view.lua

@@ -18,9 +18,9 @@ local TextBox       = require("graphics.elements.textbox")
 
 local DataIndicator = require("graphics.elements.indicators.data")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- create new main view
 ---@param main graphics_element main displaybox
@@ -32,10 +32,10 @@ local function init(main)
     local header = TextBox{parent=main,y=1,text="Nuclear Generation Facility SCADA Coordinator",alignment=TEXT_ALIGN.CENTER,height=1,fg_bg=style.header}
     local ping = DataIndicator{parent=main,x=1,y=1,label="SVTT",format="%d",value=0,unit="ms",lu_colors=cpair(colors.lightGray, colors.white),width=12,fg_bg=style.header}
     -- max length example: "01:23:45 AM - Wednesday, September 28 2022"
-    local datetime = TextBox{parent=main,x=(header.width()-42),y=1,text="",alignment=TEXT_ALIGN.RIGHT,width=42,height=1,fg_bg=style.header}
+    local datetime = TextBox{parent=main,x=(header.get_width()-42),y=1,text="",alignment=TEXT_ALIGN.RIGHT,width=42,height=1,fg_bg=style.header}
 
-    facility.ps.subscribe("sv_ping", ping.update)
-    facility.ps.subscribe("date_time", datetime.set_value)
+    ping.register(facility.ps, "sv_ping", ping.update)
+    datetime.register(facility.ps, "date_time", datetime.set_value)
 
     local uo_1, uo_2, uo_3, uo_4    ---@type graphics_element
 
@@ -45,12 +45,12 @@ local function init(main)
     -- unit overviews
     if facility.num_units >= 1 then
         uo_1 = unit_overview(main, 2, 3, units[1])
-        row_1_height = uo_1.height()
+        row_1_height = uo_1.get_height()
     end
 
     if facility.num_units >= 2 then
         uo_2 = unit_overview(main, 84, 3, units[2])
-        row_1_height = math.max(row_1_height, uo_2.height())
+        row_1_height = math.max(row_1_height, uo_2.get_height())
     end
 
     cnc_y_start = cnc_y_start + row_1_height + 1
@@ -60,11 +60,11 @@ local function init(main)
         local row_2_offset = cnc_y_start
 
         uo_3 = unit_overview(main, 2, row_2_offset, units[3])
-        cnc_y_start = row_2_offset + uo_3.height() + 1
+        cnc_y_start = row_2_offset + uo_3.get_height() + 1
 
         if facility.num_units == 4 then
             uo_4 = unit_overview(main, 84, row_2_offset, units[4])
-            cnc_y_start = math.max(cnc_y_start, row_2_offset + uo_4.height() + 1)
+            cnc_y_start = math.max(cnc_y_start, row_2_offset + uo_4.get_height() + 1)
         end
     end
 
@@ -73,11 +73,11 @@ local function init(main)
     cnc_y_start = cnc_y_start
 
     -- induction matrix and process control interfaces are 24 tall + space needed for divider
-    local cnc_bottom_align_start = main.height() - 26
+    local cnc_bottom_align_start = main.get_height() - 26
 
     assert(cnc_bottom_align_start >= cnc_y_start, "main display not of sufficient vertical resolution (add an additional row of monitors)")
 
-    TextBox{parent=main,y=cnc_bottom_align_start,text=util.strrep("\x8c", header.width()),alignment=TEXT_ALIGN.CENTER,height=1,fg_bg=cpair(colors.lightGray,colors.gray)}
+    TextBox{parent=main,y=cnc_bottom_align_start,text=util.strrep("\x8c", header.get_width()),alignment=TEXT_ALIGN.CENTER,height=1,fg_bg=cpair(colors.lightGray,colors.gray)}
 
     cnc_bottom_align_start = cnc_bottom_align_start + 2
 

coordinator/ui/style.lua

@@ -6,7 +6,7 @@ local core = require("graphics.core")
 
 local style = {}
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- GLOBAL --
 

graphics/core.lua

@@ -1,96 +1,19 @@
 --
--- Graphics Core Functions and Objects
+-- Graphics Core Types, Checks, and Constructors
 --
 
+local events  = require("graphics.events")
+local flasher = require("graphics.flasher")
+
 local core = {}
 
-local flasher = require("graphics.flasher")
-
 core.flasher = flasher
-
-local events = {}
-
----@enum click_type
-events.click_type = {
-    VIRTUAL = 0,
-    LEFT_BUTTON = 1,
-    RIGHT_BUTTON = 2,
-    MID_BUTTON = 3
-}
-
----@class mouse_interaction
----@field monitor string
----@field button integer
----@field x integer
----@field y integer
-
--- create a new monitor touch mouse interaction event
----@nodiscard
----@param monitor string
----@param x integer
----@param y integer
----@return mouse_interaction
-function events.touch(monitor, x, y)
-    return {
-        monitor = monitor,
-        button = events.click_type.LEFT_BUTTON,
-        x = x,
-        y = y
-    }
-end
-
--- create a new mouse click mouse interaction event
----@nodiscard
----@param button click_type
----@param x integer
----@param y integer
----@return mouse_interaction
-function events.click(button, x, y)
-    return {
-        monitor = "terminal",
-        button = button,
-        x = x,
-        y = y
-    }
-end
-
--- create a new transposed mouse interaction event using the event's monitor/button fields
----@nodiscard
----@param event mouse_interaction
----@param new_x integer
----@param new_y integer
----@return mouse_interaction
-function events.mouse_transposed(event, new_x, new_y)
-    return {
-        monitor = event.monitor,
-        button = event.button,
-        x = new_x,
-        y = new_y
-    }
-end
-
--- create a new generic mouse interaction event
----@nodiscard
----@param monitor string
----@param button click_type
----@param x integer
----@param y integer
----@return mouse_interaction
-function events.mouse_generic(monitor, button, x, y)
-    return {
-        monitor = monitor,
-        button = button,
-        x = x,
-        y = y
-    }
-end
-
 core.events = events
 
-local graphics = {}
+-- Core Types
 
 ---@enum TEXT_ALIGN
-graphics.TEXT_ALIGN = {
+core.TEXT_ALIGN = {
     LEFT = 1,
     CENTER = 2,
     RIGHT = 3
@@ -109,7 +32,7 @@ graphics.TEXT_ALIGN = {
 ---@param color color border color
 ---@param even? boolean whether to pad width extra to account for rectangular pixels, defaults to false
 ---@return graphics_border
-function graphics.border(width, color, even)
+function core.border(width, color, even)
     return {
         width = width,
         color = color,
@@ -130,7 +53,7 @@ end
 ---@param w integer
 ---@param h integer
 ---@return graphics_frame
-function graphics.gframe(x, y, w, h)
+function core.gframe(x, y, w, h)
     return {
         x = x,
         y = y,
@@ -154,7 +77,7 @@ end
 ---@param a color
 ---@param b color
 ---@return cpair
-function graphics.cpair(a, b)
+function core.cpair(a, b)
     return {
         -- color pairs
         color_a = a,
@@ -191,7 +114,7 @@ end
 ---@param thin? boolean true for 1 subpixel, false (default) for 2
 ---@param align_tr? boolean false to align bottom left (default), true to align top right
 ---@return pipe
-function graphics.pipe(x1, y1, x2, y2, color, thin, align_tr)
+function core.pipe(x1, y1, x2, y2, color, thin, align_tr)
     return {
         x1 = x1,
         y1 = y1,
@@ -205,6 +128,4 @@ function graphics.pipe(x1, y1, x2, y2, color, thin, align_tr)
     }
 end
 
-core.graphics = graphics
-
 return core

graphics/element.lua

@@ -12,12 +12,11 @@ local element = {}
 ---@field id? string element id
 ---@field x? integer 1 if omitted
 ---@field y? integer next line if omitted
----@field offset_x? integer 0 if omitted
----@field offset_y? integer 0 if omitted
 ---@field width? integer parent width if omitted
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 ---@alias graphics_args graphics_args_generic
 ---|waiting_args
@@ -28,6 +27,7 @@ local element = {}
 ---|sidebar_args
 ---|spinbox_args
 ---|switch_button_args
+---|tabbar_args
 ---|alarm_indicator_light
 ---|core_map_args
 ---|data_indicator_args
@@ -45,38 +45,49 @@ local element = {}
 ---|colormap_args
 ---|displaybox_args
 ---|div_args
+---|listbox_args
 ---|multipane_args
 ---|pipenet_args
 ---|rectangle_args
 ---|textbox_args
 ---|tiling_args
 
+---@class element_subscription
+---@field ps psil ps used
+---@field key string data key
+---@field func function callback
+
 -- a base graphics element, should not be created on its own
 ---@nodiscard
 ---@param args graphics_args arguments
-function element.new(args)
+---@param child_offset_x? integer mouse event offset x
+---@param child_offset_y? integer mouse event offset y
+function element.new(args, child_offset_x, child_offset_y)
     local self = {
-        id = -1,
+        id = nil,                                       ---@type element_id|nil
         elem_type = debug.getinfo(2).name,
         define_completed = false,
-        p_window = nil, ---@type table
-        position = { x = 1, y = 1 },
-        child_offset = { x = 0, y = 0 },
-        bounds = { x1 = 1, y1 = 1, x2 = 1, y2 = 1},
+        p_window = nil,                                 ---@type table
+        position = { x = 1, y = 1 },                    ---@type coordinate_2d
+        bounds = { x1 = 1, y1 = 1, x2 = 1, y2 = 1 },    ---@class element_bounds
         next_y = 1,
-        children = {},
+        subscriptions = {},
         mt = {}
     }
 
-    ---@class graphics_template
+    ---@class graphics_base
     local protected = {
         enabled = true,
-        value = nil,    ---@type any
-        window = nil,   ---@type table
-        fg_bg = core.graphics.cpair(colors.white, colors.black),
-        frame = core.graphics.gframe(1, 1, 1, 1)
+        value = nil,            ---@type any
+        window = nil,           ---@type table
+        content_window = nil,   ---@type table|nil
+        fg_bg = core.cpair(colors.white, colors.black),
+        frame = core.gframe(1, 1, 1, 1),
+        children = {}
     }
 
+    local name_brief = "graphics.element{" .. self.elem_type .. "}: "
+
     -- element as string
     function self.mt.__tostring()
         return "graphics.element{" .. self.elem_type .. "} @ " .. tostring(self)
@@ -92,8 +103,8 @@ function element.new(args)
     -------------------------
 
     -- prepare the template
-    ---@param offset_x integer x offset
-    ---@param offset_y integer y offset
+    ---@param offset_x integer x offset for mouse events
+    ---@param offset_y integer y offset for mouse events
     ---@param next_y integer next line if no y was provided
     function protected.prepare_template(offset_x, offset_y, next_y)
         -- get frame coordinates/size
@@ -105,46 +116,28 @@ function element.new(args)
         else
             local w, h = self.p_window.getSize()
             protected.frame.x = args.x or 1
-
-            if args.parent ~= nil then
-                protected.frame.y = args.y or (next_y - offset_y)
-            else
-                protected.frame.y = args.y or next_y
-            end
-
+            protected.frame.y = args.y or next_y
             protected.frame.w = args.width or w
             protected.frame.h = args.height or h
         end
 
-        -- inner offsets
-        if args.offset_x ~= nil then self.child_offset.x = args.offset_x end
-        if args.offset_y ~= nil then self.child_offset.y = args.offset_y end
-
         -- adjust window frame if applicable
         local f = protected.frame
-        local x = f.x
-        local y = f.y
-
-        -- apply offsets
         if args.parent ~= nil then
             -- constrain to parent inner width/height
             local w, h = self.p_window.getSize()
-            f.w = math.min(f.w, w - ((2 * offset_x) + (f.x - 1)))
-            f.h = math.min(f.h, h - ((2 * offset_y) + (f.y - 1)))
-
-            -- offset x/y
-            f.x = x + offset_x
-            f.y = y + offset_y
+            f.w = math.min(f.w, w - (f.x - 1))
+            f.h = math.min(f.h, h - (f.y - 1))
         end
 
         -- check frame
-        assert(f.x >= 1, "graphics.element{" .. self.elem_type .. "}: frame x not >= 1")
-        assert(f.y >= 1, "graphics.element{" .. self.elem_type .. "}: frame y not >= 1")
-        assert(f.w >= 1, "graphics.element{" .. self.elem_type .. "}: frame width not >= 1")
-        assert(f.h >= 1, "graphics.element{" .. self.elem_type .. "}: frame height not >= 1")
+        assert(f.x >= 1, name_brief .. "frame x not >= 1")
+        assert(f.y >= 1, name_brief .. "frame y not >= 1")
+        assert(f.w >= 1, name_brief .. "frame width not >= 1")
+        assert(f.h >= 1, name_brief .. "frame height not >= 1")
 
         -- create window
-        protected.window = window.create(self.p_window, f.x, f.y, f.w, f.h, true)
+        protected.window = window.create(self.p_window, f.x, f.y, f.w, f.h, args.hidden ~= true)
 
         -- init colors
         if args.fg_bg ~= nil then
@@ -161,15 +154,49 @@ function element.new(args)
         -- record position
         self.position.x, self.position.y = protected.window.getPosition()
 
-        -- calculate bounds
+        -- shift per parent child offset
+        self.position.x = self.position.x + offset_x
+        self.position.y = self.position.y + offset_y
+
+        -- calculate mouse event bounds
         self.bounds.x1 = self.position.x
         self.bounds.x2 = self.position.x + f.w - 1
         self.bounds.y1 = self.position.y
         self.bounds.y2 = self.position.y + f.h - 1
     end
 
+    -- check if a coordinate relative to the parent is within the bounds of this element
+    ---@param x integer
+    ---@param y integer
+    function protected.in_window_bounds(x, y)
+        local in_x = x >= self.bounds.x1 and x <= self.bounds.x2
+        local in_y = y >= self.bounds.y1 and y <= self.bounds.y2
+        return in_x and in_y
+    end
+
+    -- check if a coordinate relative to this window is within the bounds of this element
+    ---@param x integer
+    ---@param y integer
+    function protected.in_frame_bounds(x, y)
+        local in_x = x >= 1 and x <= protected.frame.w
+        local in_y = y >= 1 and y <= protected.frame.h
+        return in_x and in_y
+    end
+
+-- luacheck: push ignore
 ---@diagnostic disable: unused-local, unused-vararg
 
+    -- handle a child element having been added
+    ---@param id element_id element identifier
+    ---@param child graphics_element child element
+    function protected.on_added(id, child)
+    end
+
+    -- handle a child element having been removed
+    ---@param id element_id element identifier
+    function protected.on_removed(id)
+    end
+
     -- handle a mouse event
     ---@param event mouse_interaction mouse interaction event
     function protected.handle_mouse(event)
@@ -224,6 +251,7 @@ function element.new(args)
     function protected.resize(...)
     end
 
+-- luacheck: pop
 ---@diagnostic enable: unused-local, unused-vararg
 
     -- start animations
@@ -239,6 +267,14 @@ function element.new(args)
     ---@return graphics_element element, element_id id
     function protected.get() return public, self.id end
 
+    -- report completion of element instantiation and get the public interface
+    ---@nodiscard
+    ---@return graphics_element element, element_id id
+    function protected.complete()
+        if args.parent ~= nil then args.parent.__child_ready(self.id, public) end
+        return public, self.id
+    end
+
     -----------
     -- SETUP --
     -----------
@@ -250,10 +286,11 @@ function element.new(args)
     end
 
     -- check window
-    assert(self.p_window, "graphics.element{" .. self.elem_type .. "}: no parent window provided")
+    assert(self.p_window, name_brief .. "no parent window provided")
 
     -- prepare the template
     if args.parent == nil then
+        self.id = args.id or "__ROOT__"
         protected.prepare_template(0, 0, 1)
     else
         self.id = args.parent.__add_child(args.id, protected)
@@ -265,57 +302,108 @@ function element.new(args)
 
     -- get the window object
     ---@nodiscard
-    function public.window() return protected.window end
+    function public.window() return protected.content_window or protected.window end
 
-    -- CHILD ELEMENTS --
+    -- delete this element (hide and unsubscribe from PSIL)
+    function public.delete()
+        local fg_bg = protected.fg_bg
+
+        if args.parent ~= nil then
+            -- grab parent fg/bg so we can clear cleanly as a child element
+            fg_bg = args.parent.get_fg_bg()
+        end
+
+        -- clear, hide, and stop animations
+        protected.window.setBackgroundColor(fg_bg.bkg)
+        protected.window.setTextColor(fg_bg.fgd)
+        protected.window.clear()
+        public.hide()
+
+        -- unsubscribe from PSIL
+        for i = 1, #self.subscriptions do
+            local s = self.subscriptions[i] ---@type element_subscription
+            s.ps.unsubscribe(s.key, s.func)
+        end
+
+        -- delete all children
+        for k, v in pairs(protected.children) do
+            v.delete()
+            protected.children[k] = nil
+        end
+
+        if args.parent ~= nil then
+            -- remove self from parent
+            args.parent.__remove_child(self.id)
+        end
+    end
+
+    -- ELEMENT TREE --
 
     -- add a child element
     ---@nodiscard
     ---@param key string|nil id
-    ---@param child graphics_template
+    ---@param child graphics_base
     ---@return integer|string key
     function public.__add_child(key, child)
-        -- offset first automatic placement
-        if self.next_y <= self.child_offset.y then
-            self.next_y = self.child_offset.y + 1
-        end
-
-        child.prepare_template(self.child_offset.x, self.child_offset.y, self.next_y)
+        child.prepare_template(child_offset_x or 0, child_offset_y or 0, self.next_y)
 
         self.next_y = child.frame.y + child.frame.h
 
         local child_element = child.get()
 
         if key == nil then
-            table.insert(self.children, child_element)
-            return #self.children
+            table.insert(protected.children, child_element)
+            return #protected.children
         else
-            self.children[key] = child_element
+            protected.children[key] = child_element
             return key
         end
     end
 
+    -- remove a child element
+    ---@param key element_id id
+    function public.__remove_child(key)
+        if protected.children[key] ~= nil then
+            protected.on_removed(key)
+            protected.children[key] = nil
+        end
+    end
+
+    -- actions to take upon a child element becoming ready (initial draw/construction completed)
+    ---@param key element_id id
+    ---@param child graphics_element
+    function public.__child_ready(key, child)
+        protected.on_added(key, child)
+    end
+
     -- get a child element
     ---@nodiscard
+    ---@param id element_id
     ---@return graphics_element
-    function public.get_child(key) return self.children[key] end
+    function public.get_child(id) return protected.children[id] end
 
-    -- remove child
-    ---@param key string|integer
-    function public.remove(key) self.children[key] = nil end
+    -- remove a child element
+    ---@param id element_id
+    function public.remove(id)
+        if protected.children[id] ~= nil then
+            protected.children[id].delete()
+            protected.on_removed(id)
+            protected.children[id] = nil
+        end
+    end
 
     -- attempt to get a child element by ID (does not include this element itself)
     ---@nodiscard
     ---@param id element_id
     ---@return graphics_element|nil element
     function public.get_element_by_id(id)
-        if self.children[id] == nil then
-            for _, child in pairs(self.children) do
+        if protected.children[id] == nil then
+            for _, child in pairs(protected.children) do
                 local elem = child.get_element_by_id(id)
                 if elem ~= nil then return elem end
             end
         else
-            return self.children[id]
+            return protected.children[id]
         end
 
         return nil
@@ -354,14 +442,14 @@ function element.new(args)
     -- get element width
     ---@nodiscard
     ---@return integer width
-    function public.width()
+    function public.get_width()
         return protected.frame.w
     end
 
     -- get element height
     ---@nodiscard
     ---@return integer height
-    function public.height()
+    function public.get_height()
         return protected.frame.h
     end
 
@@ -414,22 +502,29 @@ function element.new(args)
         protected.resize(...)
     end
 
+    -- reposition the element window<br>
+    -- offsets relative to parent frame are where (1, 1) would be on top of the parent's top left corner
+    ---@param x integer x position relative to parent frame
+    ---@param y integer y position relative to parent frame
+    function public.reposition(x, y)
+        protected.window.reposition(x, y)
+    end
+
     -- FUNCTION CALLBACKS --
 
     -- handle a monitor touch or mouse click
     ---@param event mouse_interaction mouse interaction event
     function public.handle_mouse(event)
-        local in_x = event.x >= self.bounds.x1 and event.x <= self.bounds.x2
-        local in_y = event.y >= self.bounds.y1 and event.y <= self.bounds.y2
+        local x_ini, y_ini = event.initial.x, event.initial.y
 
-        if in_x and in_y then
-            local event_T = core.events.mouse_transposed(event, (event.x - self.position.x) + 1, (event.y - self.position.y) + 1)
+        local ini_in = protected.in_window_bounds(x_ini, y_ini)
 
-            -- handle the touch event, transformed into the window frame
+        if ini_in then
+            local event_T = core.events.mouse_transposed(event, self.position.x, self.position.y)
+
+            -- handle the mouse event then pass to children
             protected.handle_mouse(event_T)
-
-            -- pass on touch event to children
-            for _, val in pairs(self.children) do val.handle_mouse(event_T) end
+            for _, child in pairs(protected.children) do child.handle_mouse(event_T) end
         end
     end
 
@@ -445,27 +540,71 @@ function element.new(args)
         protected.response_callback(result)
     end
 
-    -- VISIBILITY --
-
-    -- show the element
-    function public.show()
-        protected.window.setVisible(true)
-        protected.start_anim()
-        for _, child in pairs(self.children) do child.show() end
+    -- register a callback with a PSIL, allowing for automatic unregister on delete<br>
+    -- do not use graphics elements directly with PSIL subscribe()
+    ---@param ps psil PSIL to subscribe to
+    ---@param key string key to subscribe to
+    ---@param func function function to link
+    function public.register(ps, key, func)
+        table.insert(self.subscriptions, { ps = ps, key = key, func = func })
+        ps.subscribe(key, func)
     end
 
-    -- hide the element
+    -- VISIBILITY & ANIMATIONS --
+
+    -- show the element and enables animations by default
+    ---@param animate? boolean true (default) to automatically resume animations
+    function public.show(animate)
+        protected.window.setVisible(true)
+        if animate ~= false then public.animate_all() end
+    end
+
+    -- hide the element and disables animations<br>
+    -- this alone does not cause an element to be fully hidden, it only prevents updates from being shown<br>
+    ---@see graphics_element.content_redraw
     function public.hide()
-        protected.stop_anim()
-        for _, child in pairs(self.children) do child.hide() end
+        public.freeze_all() -- stop animations for efficiency/performance
         protected.window.setVisible(false)
     end
 
+    -- start/resume animation(s)
+    function public.animate()
+        protected.start_anim()
+    end
+
+    -- start/resume animation(s) for this element and all its children<br>
+    -- only animates if a window is visible
+    function public.animate_all()
+        if protected.window.isVisible() then
+            public.animate()
+            for _, child in pairs(protected.children) do child.animate_all() end
+        end
+    end
+
+    -- freeze animation(s)
+    function public.freeze()
+        protected.stop_anim()
+    end
+
+    -- freeze animation(s) for this element and all its children
+    function public.freeze_all()
+        public.freeze()
+        for _, child in pairs(protected.children) do child.freeze_all() end
+    end
+
     -- re-draw the element
     function public.redraw()
         protected.window.redraw()
     end
 
+    -- if a content window is set, clears it then re-draws all children
+    function public.content_redraw()
+        if protected.content_window ~= nil then
+            protected.content_window.clear()
+            for _, child in pairs(protected.children) do child.redraw() end
+        end
+    end
+
     return protected
 end
 

graphics/elements/animations/waiting.lua

@@ -1,6 +1,6 @@
 -- Loading/Waiting Animation Graphics Element
 
-local tcd     = require("scada-common.tcallbackdsp")
+local tcd     = require("scada-common.tcd")
 
 local element = require("graphics.element")
 
@@ -10,6 +10,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new waiting animation element
 ---@param args waiting_args
@@ -102,7 +103,7 @@ local function waiting(args)
 
     e.start_anim()
 
-    return e.get()
+    return e.complete()
 end
 
 return waiting

graphics/elements/colormap.lua

@@ -9,6 +9,7 @@ local element = require("graphics.element")
 ---@field id? string element id
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
+---@field hidden? boolean true to hide on initial draw
 
 -- new color map
 ---@param args colormap_args
@@ -27,7 +28,7 @@ local function colormap(args)
     e.window.setCursorPos(1, 1)
     e.window.blit(spaces, bkg, bkg)
 
-    return e.get()
+    return e.complete()
 end
 
 return colormap

graphics/elements/controls/hazard_button.lua

@@ -1,6 +1,6 @@
 -- Hazard-bordered Button Graphics Element
 
-local tcd     = require("scada-common.tcallbackdsp")
+local tcd     = require("scada-common.tcd")
 local util    = require("scada-common.util")
 
 local core    = require("graphics.core")
@@ -16,6 +16,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new hazard button
 ---@param args hazard_button_args
@@ -142,24 +143,25 @@ local function hazard_button(args)
 
     -- handle mouse interaction
     ---@param event mouse_interaction mouse event
----@diagnostic disable-next-line: unused-local
     function e.handle_mouse(event)
         if e.enabled then
-            -- change text color to indicate clicked
-            e.window.setTextColor(args.accent)
-            e.window.setCursorPos(3, 2)
-            e.window.write(args.text)
+            if core.events.was_clicked(event.type) then
+                -- change text color to indicate clicked
+                e.window.setTextColor(args.accent)
+                e.window.setCursorPos(3, 2)
+                e.window.write(args.text)
 
-            -- abort any other callbacks
-            tcd.abort(on_timeout)
-            tcd.abort(on_success)
-            tcd.abort(on_failure)
+                -- abort any other callbacks
+                tcd.abort(on_timeout)
+                tcd.abort(on_success)
+                tcd.abort(on_failure)
 
-            -- 1.5 second timeout
-            tcd.dispatch(1.5, on_timeout)
+                -- 1.5 second timeout
+                tcd.dispatch(1.5, on_timeout)
 
-            -- call the touch callback
-            args.callback()
+                -- call the touch callback
+                args.callback()
+            end
         end
     end
 
@@ -167,18 +169,13 @@ local function hazard_button(args)
     ---@param result boolean true for success, false for failure
     function e.response_callback(result)
         tcd.abort(on_timeout)
-
-        if result then
-            on_success()
-        else
-            on_failure(0)
-        end
+        if result then on_success() else on_failure(0) end
     end
 
     -- set the value (true simulates pressing the button)
     ---@param val boolean new value
     function e.set_value(val)
-        if val then e.handle_mouse(core.events.mouse_generic("", core.events.click_type.VIRTUAL, 1, 1)) end
+        if val then e.handle_mouse(core.events.mouse_generic(core.events.CLICK_TYPE.UP, 1, 1)) end
     end
 
     -- show the button as disabled
@@ -202,7 +199,7 @@ local function hazard_button(args)
     -- initial draw of border
     draw_border(args.accent)
 
-    return e.get()
+    return e.complete()
 end
 
 return hazard_button

graphics/elements/controls/multi_button.lua

@@ -2,13 +2,13 @@
 
 local util    = require("scada-common.util")
 
+local core    = require("graphics.core")
 local element = require("graphics.element")
 
 ---@class button_option
 ---@field text string
 ---@field fg_bg cpair
 ---@field active_fg_bg cpair
----@field _lpad integer automatically calculated left pad
 ---@field _start_x integer starting touch x range (inclusive)
 ---@field _end_x integer ending touch x range (inclusive)
 
@@ -23,6 +23,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field height? integer parent height if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new multi button (latch selection, exclusively one button at a time)
 ---@param args multi_button_args
@@ -62,9 +63,7 @@ local function multi_button(args)
     local next_x = 2
     for i = 1, #args.options do
         local opt = args.options[i] ---@type button_option
-        local w = string.len(opt.text)
 
-        opt._lpad = math.floor((e.frame.w - w) / 2)
         opt._start_x = next_x
         opt._end_x = next_x + button_width - 1
 
@@ -92,20 +91,32 @@ local function multi_button(args)
         end
     end
 
+    -- check which button a given x is within
+    ---@return integer|nil button index or nil if not within a button
+    local function which_button(x)
+        for i = 1, #args.options do
+            local opt = args.options[i] ---@type button_option
+            if x >= opt._start_x and x <= opt._end_x then return i end
+        end
+
+        return nil
+    end
+
     -- handle mouse interaction
     ---@param event mouse_interaction mouse event
----@diagnostic disable-next-line: unused-local
     function e.handle_mouse(event)
-        -- determine what was pressed
-        if e.enabled and event.y == 1 then
-            for i = 1, #args.options do
-                local opt = args.options[i] ---@type button_option
+        -- if enabled and the button row was pressed...
+        if e.enabled and core.events.was_clicked(event.type) then
+            -- a button may have been pressed, which one was it?
+            local button_ini = which_button(event.initial.x)
+            local button_cur = which_button(event.current.x)
 
-                if event.x >= opt._start_x and event.x <= opt._end_x then
-                    e.value = i
-                    draw()
-                    args.callback(e.value)
-                end
+            -- mouse up must always have started with a mouse down on the same button to count as a click
+            -- tap always has identical coordinates, so this always passes for taps
+            if button_ini == button_cur and button_cur ~= nil then
+                e.value = button_cur
+                draw()
+                args.callback(e.value)
             end
         end
     end
@@ -120,7 +131,7 @@ local function multi_button(args)
     -- initial draw
     draw()
 
-    return e.get()
+    return e.complete()
 end
 
 return multi_button

graphics/elements/controls/push_button.lua

@@ -1,10 +1,12 @@
 -- Button Graphics Element
 
-local tcd     = require("scada-common.tcallbackdsp")
+local tcd     = require("scada-common.tcd")
 
 local core    = require("graphics.core")
 local element = require("graphics.element")
 
+local CLICK_TYPE = core.events.CLICK_TYPE
+
 ---@class push_button_args
 ---@field text string button text
 ---@field callback function function to call on touch
@@ -17,6 +19,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field height? integer parent height if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new push button
 ---@param args push_button_args
@@ -24,6 +27,8 @@ local element = require("graphics.element")
 local function push_button(args)
     assert(type(args.text) == "string", "graphics.elements.controls.push_button: text is a required field")
     assert(type(args.callback) == "function", "graphics.elements.controls.push_button: callback is a required field")
+    assert(type(args.min_width) == "nil" or (type(args.min_width) == "number" and args.min_width > 0),
+        "graphics.elements.controls.push_button: min_width must be nil or a number > 0")
 
     local text_width = string.len(args.text)
 
@@ -47,38 +52,50 @@ local function push_button(args)
         e.window.write(args.text)
     end
 
+    -- draw the button as pressed (if active_fg_bg set)
+    local function show_pressed()
+        if e.enabled and args.active_fg_bg ~= nil then
+            e.value = true
+            e.window.setTextColor(args.active_fg_bg.fgd)
+            e.window.setBackgroundColor(args.active_fg_bg.bkg)
+            draw()
+        end
+    end
+
+    -- draw the button as unpressed (if active_fg_bg set)
+    local function show_unpressed()
+        if e.enabled and args.active_fg_bg ~= nil then
+            e.value = false
+            e.window.setTextColor(e.fg_bg.fgd)
+            e.window.setBackgroundColor(e.fg_bg.bkg)
+            draw()
+        end
+    end
+
     -- handle mouse interaction
     ---@param event mouse_interaction mouse event
----@diagnostic disable-next-line: unused-local
     function e.handle_mouse(event)
         if e.enabled then
-            if args.active_fg_bg ~= nil then
-                -- show as pressed
-                e.value = true
-                e.window.setTextColor(args.active_fg_bg.fgd)
-                e.window.setBackgroundColor(args.active_fg_bg.bkg)
-                draw()
-
+            if event.type == CLICK_TYPE.TAP then
+                show_pressed()
                 -- show as unpressed in 0.25 seconds
-                tcd.dispatch(0.25, function ()
-                    e.value = false
-                    if e.enabled then
-                        e.window.setTextColor(e.fg_bg.fgd)
-                        e.window.setBackgroundColor(e.fg_bg.bkg)
-                    end
-                    draw()
-                end)
+                if args.active_fg_bg ~= nil then tcd.dispatch(0.25, show_unpressed) end
+                args.callback()
+            elseif event.type == CLICK_TYPE.DOWN then
+                show_pressed()
+            elseif event.type == CLICK_TYPE.UP then
+                show_unpressed()
+                if e.in_frame_bounds(event.current.x, event.current.y) then
+                    args.callback()
+                end
             end
-
-            -- call the touch callback
-            args.callback()
         end
     end
 
     -- set the value (true simulates pressing the button)
     ---@param val boolean new value
     function e.set_value(val)
-        if val then e.handle_mouse(core.events.mouse_generic("", core.events.click_type.VIRTUAL, 1, 1)) end
+        if val then e.handle_mouse(core.events.mouse_generic(core.events.CLICK_TYPE.UP, 1, 1)) end
     end
 
     -- show butten as enabled
@@ -104,7 +121,7 @@ local function push_button(args)
     -- initial draw
     draw()
 
-    return e.get()
+    return e.complete()
 end
 
 return push_button

graphics/elements/controls/radio_button.lua

@@ -1,5 +1,6 @@
 -- Radio Button Graphics Element
 
+local core    = require("graphics.core")
 local element = require("graphics.element")
 
 ---@class radio_button_args
@@ -14,6 +15,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new radio button list (latch selection, exclusively one button at a time)
 ---@param args radio_button_args
@@ -82,10 +84,10 @@ local function radio_button(args)
     -- handle mouse interaction
     ---@param event mouse_interaction mouse event
     function e.handle_mouse(event)
-        -- determine what was pressed
-        if e.enabled then
-            if args.options[event.y] ~= nil then
-                e.value = event.y
+        if e.enabled and core.events.was_clicked(event.type) and (event.initial.y == event.current.y) then
+            -- determine what was pressed
+            if args.options[event.current.y] ~= nil then
+                e.value = event.current.y
                 draw()
                 args.callback(e.value)
             end
@@ -102,7 +104,7 @@ local function radio_button(args)
     -- initial draw
     draw()
 
-    return e.get()
+    return e.complete()
 end
 
 return radio_button

graphics/elements/controls/sidebar.lua

@@ -1,9 +1,12 @@
 -- Sidebar Graphics Element
 
-local tcd     = require("scada-common.tcallbackdsp")
+local tcd     = require("scada-common.tcd")
 
+local core    = require("graphics.core")
 local element = require("graphics.element")
 
+local CLICK_TYPE = core.events.CLICK_TYPE
+
 ---@class sidebar_tab
 ---@field char string character identifier
 ---@field color cpair tab colors (fg/bg)
@@ -17,6 +20,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field height? integer parent height if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new sidebar tab selector
 ---@param args sidebar_args
@@ -39,7 +43,10 @@ local function sidebar(args)
 
     -- show the button state
     ---@param pressed boolean if the currently selected tab should appear as actively pressed
-    local function draw(pressed)
+    ---@param pressed_idx? integer optional index to show as held (that is not yet selected)
+    local function draw(pressed, pressed_idx)
+        pressed_idx = pressed_idx or e.value
+
         for i = 1, #args.tabs do
             local tab = args.tabs[i] ---@type sidebar_tab
 
@@ -47,7 +54,7 @@ local function sidebar(args)
 
             e.window.setCursorPos(1, y)
 
-            if pressed and e.value == i then
+            if pressed and i == pressed_idx then
                 e.window.setTextColor(e.fg_bg.fgd)
                 e.window.setBackgroundColor(e.fg_bg.bkg)
             else
@@ -74,16 +81,27 @@ local function sidebar(args)
     function e.handle_mouse(event)
         -- determine what was pressed
         if e.enabled then
-            local idx = math.ceil(event.y / 3)
+            local cur_idx = math.ceil(event.current.y / 3)
+            local ini_idx = math.ceil(event.initial.y / 3)
 
-            if args.tabs[idx] ~= nil then
-                e.value = idx
-                draw(true)
-
-                -- show as unpressed in 0.25 seconds
-                tcd.dispatch(0.25, function () draw(false) end)
-
-                args.callback(e.value)
+            if args.tabs[cur_idx] ~= nil then
+                if event.type == CLICK_TYPE.TAP then
+                    e.value = cur_idx
+                    draw(true)
+                    -- show as unpressed in 0.25 seconds
+                    tcd.dispatch(0.25, function () draw(false) end)
+                    args.callback(e.value)
+                elseif event.type == CLICK_TYPE.DOWN then
+                    draw(true, cur_idx)
+                elseif event.type == CLICK_TYPE.UP then
+                    if cur_idx == ini_idx and e.in_frame_bounds(event.current.x, event.current.y) then
+                        e.value = cur_idx
+                        draw(false)
+                        args.callback(e.value)
+                    else draw(false) end
+                end
+            elseif event.type == CLICK_TYPE.UP then
+                draw(false)
             end
         end
     end
@@ -98,7 +116,7 @@ local function sidebar(args)
     -- initial draw
     draw(false)
 
-    return e.get()
+    return e.complete()
 end
 
 return sidebar

graphics/elements/controls/spinbox_numeric.lua

@@ -2,6 +2,7 @@
 
 local util    = require("scada-common.util")
 
+local core    = require("graphics.core")
 local element = require("graphics.element")
 
 ---@class spinbox_args
@@ -17,6 +18,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new spinbox control (minimum value is 0)
 ---@param args spinbox_args
@@ -130,19 +132,22 @@ local function spinbox(args)
     ---@param event mouse_interaction mouse event
     function e.handle_mouse(event)
         -- only handle if on an increment or decrement arrow
-        if e.enabled and event.x ~= dec_point_x then
-            local idx = util.trinary(event.x > dec_point_x, event.x - 1, event.x)
-            if digits[idx] ~= nil then
-                if event.y == 1 then
-                    -- increment
-                    digits[idx] = digits[idx] + 1
-                elseif event.y == 3 then
-                    -- decrement
-                    digits[idx] = digits[idx] - 1
-                end
+        if e.enabled and core.events.was_clicked(event.type) and
+                (event.current.x ~= dec_point_x) and (event.current.y ~= 2) then
+            if event.current.x == event.initial.x and event.current.y == event.initial.y then
+                local idx = util.trinary(event.current.x > dec_point_x, event.current.x - 1, event.current.x)
+                if digits[idx] ~= nil then
+                    if event.current.y == 1 then
+                        -- increment
+                        digits[idx] = digits[idx] + 1
+                    elseif event.current.y == 3 then
+                        -- decrement
+                        digits[idx] = digits[idx] - 1
+                    end
 
-                update_value()
-                show_num()
+                    update_value()
+                    show_num()
+                end
             end
         end
     end
@@ -184,7 +189,7 @@ local function spinbox(args)
     e.value = 0
     set_digits()
 
-    return e.get()
+    return e.complete()
 end
 
 return spinbox

graphics/elements/controls/switch_button.lua

@@ -1,5 +1,6 @@
 -- Button Graphics Element
 
+local core    = require("graphics.core")
 local element = require("graphics.element")
 
 ---@class switch_button_args
@@ -14,6 +15,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field height? integer parent height if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new switch button (latch high/low)
 ---@param args switch_button_args
@@ -22,13 +24,15 @@ local function switch_button(args)
     assert(type(args.text) == "string", "graphics.elements.controls.switch_button: text is a required field")
     assert(type(args.callback) == "function", "graphics.elements.controls.switch_button: callback is a required field")
     assert(type(args.active_fg_bg) == "table", "graphics.elements.controls.switch_button: active_fg_bg is a required field")
+    assert(type(args.min_width) == "nil" or (type(args.min_width) == "number" and args.min_width > 0),
+        "graphics.elements.controls.switch_button: min_width must be nil or a number > 0")
 
-    -- single line
-    args.height = 1
-
-    -- determine widths
     local text_width = string.len(args.text)
-    args.width = math.max(text_width + 2, args.min_width)
+
+    -- single line height, calculate width
+    args.height = 1
+    args.min_width = args.min_width or 0
+    args.width = math.max(text_width, args.min_width)
 
     -- create new graphics element base object
     local e = element.new(args)
@@ -64,9 +68,8 @@ local function switch_button(args)
 
     -- handle mouse interaction
     ---@param event mouse_interaction mouse event
----@diagnostic disable-next-line: unused-local
     function e.handle_mouse(event)
-        if e.enabled then
+        if e.enabled and core.events.was_clicked(event.type) then
             -- toggle state
             e.value = not e.value
             draw_state()
@@ -84,7 +87,7 @@ local function switch_button(args)
         draw_state()
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return switch_button

graphics/elements/controls/tabbar.lua

@@ -0,0 +1,131 @@
+-- Tab Bar Graphics Element
+
+local util    = require("scada-common.util")
+
+local core    = require("graphics.core")
+local element = require("graphics.element")
+
+---@class tabbar_tab
+---@field name string tab name
+---@field color cpair tab colors (fg/bg)
+---@field _start_x integer starting touch x range (inclusive)
+---@field _end_x integer ending touch x range (inclusive)
+
+---@class tabbar_args
+---@field tabs table tab options
+---@field callback function function to call on tab change
+---@field min_width? integer text length + 2 if omitted
+---@field parent graphics_element
+---@field id? string element id
+---@field x? integer 1 if omitted
+---@field y? integer 1 if omitted
+---@field width? integer parent width if omitted
+---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
+
+-- new tab selector
+---@param args tabbar_args
+---@return graphics_element element, element_id id
+local function tabbar(args)
+    assert(type(args.tabs) == "table", "graphics.elements.controls.tabbar: tabs is a required field")
+    assert(#args.tabs > 0, "graphics.elements.controls.tabbar: at least one tab is required")
+    assert(type(args.callback) == "function", "graphics.elements.controls.tabbar: callback is a required field")
+    assert(type(args.min_width) == "nil" or (type(args.min_width) == "number" and args.min_width > 0),
+        "graphics.elements.controls.tabbar: min_width must be nil or a number > 0")
+
+    -- always 1 tall
+    args.height = 1
+
+    -- determine widths
+    local max_width = 1
+    for i = 1, #args.tabs do
+        local opt = args.tabs[i]    ---@type tabbar_tab
+        if string.len(opt.name) > max_width then
+            max_width = string.len(opt.name)
+        end
+    end
+
+    local button_width = math.max(max_width, args.min_width or 0)
+
+    -- create new graphics element base object
+    local e = element.new(args)
+
+    assert(e.frame.w >= (button_width * #args.tabs), "graphics.elements.controls.tabbar: width insufficent to display all tabs")
+
+    -- default to 1st tab
+    e.value = 1
+
+    -- calculate required tab dimension information
+    local next_x = 1
+    for i = 1, #args.tabs do
+        local tab = args.tabs[i] ---@type tabbar_tab
+
+        tab._start_x = next_x
+        tab._end_x = next_x + button_width - 1
+
+        next_x = next_x + button_width
+    end
+
+    -- show the tab state
+    local function draw()
+        for i = 1, #args.tabs do
+            local tab = args.tabs[i]    ---@type tabbar_tab
+
+            e.window.setCursorPos(tab._start_x, 1)
+
+            if e.value == i then
+                e.window.setTextColor(tab.color.fgd)
+                e.window.setBackgroundColor(tab.color.bkg)
+            else
+                e.window.setTextColor(e.fg_bg.fgd)
+                e.window.setBackgroundColor(e.fg_bg.bkg)
+            end
+
+            e.window.write(util.pad(tab.name, button_width))
+        end
+    end
+
+    -- check which tab a given x is within
+    ---@return integer|nil button index or nil if not within a tab
+    local function which_tab(x)
+        for i = 1, #args.tabs do
+            local tab = args.tabs[i]    ---@type tabbar_tab
+            if x >= tab._start_x and x <= tab._end_x then return i end
+        end
+
+        return nil
+    end
+
+    -- handle mouse interaction
+    ---@param event mouse_interaction mouse event
+    function e.handle_mouse(event)
+        -- determine what was pressed
+        if e.enabled and core.events.was_clicked(event.type) then
+            -- a button may have been pressed, which one was it?
+            local tab_ini = which_tab(event.initial.x)
+            local tab_cur = which_tab(event.current.x)
+
+            -- mouse up must always have started with a mouse down on the same tab to count as a click
+            -- tap always has identical coordinates, so this always passes for taps
+            if tab_ini == tab_cur and tab_cur ~= nil then
+                e.value = tab_cur
+                draw()
+                args.callback(e.value)
+            end
+        end
+    end
+
+    -- set the value
+    ---@param val integer new value
+    function e.set_value(val)
+        e.value = val
+        draw()
+    end
+
+    -- initial draw
+    draw()
+
+    return e.complete()
+end
+
+return tabbar

graphics/elements/displaybox.lua

@@ -4,19 +4,22 @@ local element = require("graphics.element")
 
 ---@class displaybox_args
 ---@field window table
+---@field id? string element id
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field width? integer parent width if omitted
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new root display box
 ---@nodiscard
 ---@param args displaybox_args
+---@return graphics_element element, element_id id
 local function displaybox(args)
     -- create new graphics element base object
-    return element.new(args).get()
+    return element.new(args).complete()
 end
 
 return displaybox

graphics/elements/div.lua

@@ -11,6 +11,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new div element
 ---@nodiscard
@@ -18,7 +19,7 @@ local element = require("graphics.element")
 ---@return graphics_element element, element_id id
 local function div(args)
     -- create new graphics element base object
-    return element.new(args).get()
+    return element.new(args).complete()
 end
 
 return div

graphics/elements/indicators/alight.lua

@@ -18,6 +18,7 @@ local flasher = require("graphics.flasher")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new alarm indicator light
 ---@nodiscard
@@ -108,7 +109,7 @@ local function alarm_indicator_light(args)
     e.on_update(1)
     e.window.write(args.label)
 
-    return e.get()
+    return e.complete()
 end
 
 return alarm_indicator_light

graphics/elements/indicators/coremap.lua

@@ -26,7 +26,7 @@ local function core_map(args)
     args.height = 18
 
     -- inherit only foreground color
-    args.fg_bg = core.graphics.cpair(args.parent.get_fg_bg().fgd, colors.gray)
+    args.fg_bg = core.cpair(args.parent.get_fg_bg().fgd, colors.gray)
 
     -- create new graphics element base object
     local e = element.new(args)
@@ -163,7 +163,7 @@ local function core_map(args)
     -- initial draw
     e.on_update(0)
 
-    return e.get()
+    return e.complete()
 end
 
 return core_map

graphics/elements/indicators/data.lua

@@ -17,6 +17,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field width integer length
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new data indicator
 ---@nodiscard
@@ -43,8 +44,9 @@ local function data(args)
     e.window.setCursorPos(1, 1)
     e.window.write(args.label)
 
-    local label_len = string.len(args.label)
-    local data_start = 1
+    local value_color = e.fg_bg.fgd
+    local label_len   = string.len(args.label)
+    local data_start  = 1
     local clear_width = args.width
 
     if label_len > 0 then
@@ -64,7 +66,7 @@ local function data(args)
         -- write data
         local data_str = util.sprintf(args.format, value)
         e.window.setCursorPos(data_start, 1)
-        e.window.setTextColor(e.fg_bg.fgd)
+        e.window.setTextColor(value_color)
         if args.commas then
             e.window.write(util.comma_format(data_str))
         else
@@ -84,10 +86,17 @@ local function data(args)
     ---@param val any new value
     function e.set_value(val) e.on_update(val) end
 
+    -- change the foreground color of the value, or all text if no label/unit colors provided
+    ---@param c color
+    function e.recolor(c)
+        value_color = c
+        e.on_update(e.value)
+    end
+
     -- initial value draw
     e.on_update(args.value)
 
-    return e.get()
+    return e.complete()
 end
 
 return data

graphics/elements/indicators/hbar.lua

@@ -15,6 +15,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new horizontal bar
 ---@nodiscard
@@ -119,7 +120,7 @@ local function hbar(args)
     -- initialize to 0
     e.on_update(0)
 
-    return e.get()
+    return e.complete()
 end
 
 return hbar

graphics/elements/indicators/icon.lua

@@ -18,6 +18,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new icon indicator
 ---@nodiscard
@@ -68,7 +69,7 @@ local function icon(args)
     -- initial icon draw
     e.on_update(args.value or 1)
 
-    return e.get()
+    return e.complete()
 end
 
 return icon

graphics/elements/indicators/led.lua

@@ -16,6 +16,7 @@ local flasher = require("graphics.flasher")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new indicator LED
 ---@nodiscard
@@ -94,7 +95,7 @@ local function indicator_led(args)
         e.window.write(args.label)
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return indicator_led

graphics/elements/indicators/ledpair.lua

@@ -18,6 +18,7 @@ local flasher = require("graphics.flasher")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new dual LED indicator light
 ---@nodiscard
@@ -108,7 +109,7 @@ local function indicator_led_pair(args)
         e.window.write(args.label)
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return indicator_led_pair

graphics/elements/indicators/ledrgb.lua

@@ -11,6 +11,7 @@ local element = require("graphics.element")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new RGB LED indicator light
 ---@nodiscard
@@ -53,7 +54,7 @@ local function indicator_led_rgb(args)
         e.window.write(args.label)
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return indicator_led_rgb

graphics/elements/indicators/light.lua

@@ -16,6 +16,7 @@ local flasher = require("graphics.flasher")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new indicator light
 ---@nodiscard
@@ -92,7 +93,7 @@ local function indicator_light(args)
     e.window.setCursorPos(3, 1)
     e.window.write(args.label)
 
-    return e.get()
+    return e.complete()
 end
 
 return indicator_light

graphics/elements/indicators/power.lua

@@ -16,6 +16,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field width integer length
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new power indicator
 ---@nodiscard
@@ -79,7 +80,7 @@ local function power(args)
     -- initial value draw
     e.on_update(args.value)
 
-    return e.get()
+    return e.complete()
 end
 
 return power

graphics/elements/indicators/rad.lua

@@ -17,6 +17,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field width integer length
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new radiation indicator
 ---@nodiscard
@@ -84,7 +85,7 @@ local function rad(args)
     -- initial value draw
     e.on_update(types.new_zero_radiation_reading())
 
-    return e.get()
+    return e.complete()
 end
 
 return rad

graphics/elements/indicators/state.lua

@@ -18,6 +18,7 @@ local element = require("graphics.element")
 ---@field y? integer 1 if omitted
 ---@field height? integer 1 if omitted, must be an odd number
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new state indicator
 ---@nodiscard
@@ -74,7 +75,7 @@ local function state_indicator(args)
     -- initial draw
     e.on_update(args.value or 1)
 
-    return e.get()
+    return e.complete()
 end
 
 return state_indicator

graphics/elements/indicators/trilight.lua

@@ -18,6 +18,7 @@ local flasher = require("graphics.flasher")
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new tri-state indicator light
 ---@nodiscard
@@ -105,7 +106,7 @@ local function tristate_indicator_light(args)
     e.on_update(1)
     e.window.write(args.label)
 
-    return e.get()
+    return e.complete()
 end
 
 return tristate_indicator_light

graphics/elements/indicators/vbar.lua

@@ -13,6 +13,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new vertical bar
 ---@nodiscard
@@ -99,7 +100,7 @@ local function vbar(args)
     ---@param val number 0.0 to 1.0
     function e.set_value(val) e.on_update(val) end
 
-    return e.get()
+    return e.complete()
 end
 
 return vbar

graphics/elements/listbox.lua

@@ -0,0 +1,283 @@
+-- Scroll-able List Box Display Graphics Element
+
+local tcd     = require("scada-common.tcd")
+
+local core    = require("graphics.core")
+local element = require("graphics.element")
+
+local CLICK_TYPE = core.events.CLICK_TYPE
+
+---@class listbox_args
+---@field scroll_height integer height of internal scrolling container (must fit all elements vertically tiled)
+---@field item_pad? integer spacing (lines) between items in the list (default 0)
+---@field nav_fg_bg? cpair foreground/background colors for scroll arrows and bar area
+---@field nav_active? cpair active colors for bar held down or arrow held down
+---@field parent graphics_element
+---@field id? string element id
+---@field x? integer 1 if omitted
+---@field y? integer 1 if omitted
+---@field width? integer parent width if omitted
+---@field height? integer parent height if omitted
+---@field gframe? graphics_frame frame instead of x/y/width/height
+---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
+
+---@class listbox_item
+---@field id string|integer element ID
+---@field e graphics_element element
+---@field y integer y position
+---@field h integer element height
+
+-- new listbox element
+---@nodiscard
+---@param args listbox_args
+---@return graphics_element element, element_id id
+local function listbox(args)
+    -- create new graphics element base object
+    local e = element.new(args)
+
+    -- create content window for child elements
+    local scroll_frame = window.create(e.window, 1, 1, e.frame.w - 1, args.scroll_height, false)
+    e.content_window = scroll_frame
+
+    -- item list and scroll management
+    local list            = {}
+    local item_pad        = args.item_pad or 0
+    local scroll_offset   = 0
+    local content_height  = 0
+    local max_down_scroll = 0
+    -- bar control/tracking variables
+    local max_bar_height  = e.frame.h - 2
+    local bar_height      = 0           -- full height of bar
+    local bar_bounds      = { 0, 0 }    -- top and bottom of bar
+    local bar_is_scaled   = false       -- if the scrollbar doesn't have a 1:1 ratio with lines
+    local holding_bar     = false       -- bar is being held by mouse
+    local bar_grip_pos    = 0           -- where the bar was gripped by mouse down
+    local mouse_last_y    = 0           -- last reported y coordinate of drag
+
+    -- draw scroll bar arrows, optionally showing one of them as pressed
+    ---@param pressed_arrow? 1|0|-1 arrow to show as pressed (1 = scroll up, 0 = neither, -1 = scroll down)
+    local function draw_arrows(pressed_arrow)
+        local nav_fg_bg = args.nav_fg_bg or e.fg_bg
+        local active_fg_bg = args.nav_active or nav_fg_bg
+
+        -- draw up/down arrows
+        if pressed_arrow == 1 then
+            e.window.setTextColor(active_fg_bg.fgd)
+            e.window.setBackgroundColor(active_fg_bg.bkg)
+            e.window.setCursorPos(e.frame.w, 1)
+            e.window.write("\x1e")
+            e.window.setTextColor(nav_fg_bg.fgd)
+            e.window.setBackgroundColor(nav_fg_bg.bkg)
+            e.window.setCursorPos(e.frame.w, e.frame.h)
+            e.window.write("\x1f")
+        elseif pressed_arrow == -1 then
+            e.window.setTextColor(nav_fg_bg.fgd)
+            e.window.setBackgroundColor(nav_fg_bg.bkg)
+            e.window.setCursorPos(e.frame.w, 1)
+            e.window.write("\x1e")
+            e.window.setTextColor(active_fg_bg.fgd)
+            e.window.setBackgroundColor(active_fg_bg.bkg)
+            e.window.setCursorPos(e.frame.w, e.frame.h)
+            e.window.write("\x1f")
+        else
+            e.window.setTextColor(nav_fg_bg.fgd)
+            e.window.setBackgroundColor(nav_fg_bg.bkg)
+            e.window.setCursorPos(e.frame.w, 1)
+            e.window.write("\x1e")
+            e.window.setCursorPos(e.frame.w, e.frame.h)
+            e.window.write("\x1f")
+        end
+
+        e.window.setTextColor(e.fg_bg.fgd)
+        e.window.setBackgroundColor(e.fg_bg.bkg)
+    end
+
+    -- render the scroll bar and re-cacluate height & bounds
+    local function draw_bar()
+        local offset = 2 + math.abs(scroll_offset)
+
+        bar_height = math.min(max_bar_height + max_down_scroll, max_bar_height)
+
+        if bar_height < 1 then
+            bar_is_scaled = true
+            -- can't do a 1:1 ratio
+            -- use minimum size bar with scaled offset
+            local scroll_progress = scroll_offset / max_down_scroll
+            offset = 2 + math.floor(scroll_progress * (max_bar_height - 1))
+            bar_height = 1
+        else
+            bar_is_scaled = false
+        end
+
+        bar_bounds = { offset, (bar_height + offset) - 1 }
+
+        for i = 2, e.frame.h - 1 do
+            if (i >= offset and i < (bar_height + offset)) and (bar_height ~= max_bar_height) then
+                if args.nav_fg_bg ~= nil then
+                    e.window.setBackgroundColor(args.nav_fg_bg.fgd)
+                else
+                    e.window.setBackgroundColor(e.fg_bg.fgd)
+                end
+            else
+                if args.nav_fg_bg ~= nil then
+                    e.window.setBackgroundColor(args.nav_fg_bg.bkg)
+                else
+                    e.window.setBackgroundColor(e.fg_bg.bkg)
+                end
+            end
+
+            e.window.setCursorPos(e.frame.w, i)
+            e.window.write(" ")
+        end
+
+        e.window.setBackgroundColor(e.fg_bg.bkg)
+    end
+
+    -- update item y positions and move elements
+    local function update_positions()
+        local next_y = 1
+
+        scroll_frame.setVisible(false)
+        scroll_frame.setBackgroundColor(e.fg_bg.bkg)
+        scroll_frame.setTextColor(e.fg_bg.fgd)
+        scroll_frame.clear()
+
+        for i = 1, #list do
+            local item = list[i]    ---@type listbox_item
+            item.y = next_y
+            next_y = next_y + item.h + item_pad
+            item.e.reposition(1, item.y)
+            item.e.show()
+        end
+
+        content_height = next_y
+        max_down_scroll = math.min(-1 * (content_height - (e.frame.h + 1 + item_pad)), 0)
+        if scroll_offset < max_down_scroll then scroll_offset = max_down_scroll end
+
+        scroll_frame.reposition(1, 1 + scroll_offset)
+        scroll_frame.setVisible(true)
+
+        draw_bar()
+    end
+
+    -- determine where to scroll to based on a scrollbar being dragged without a 1:1 relationship
+    ---@param direction -1|1 negative 1 to scroll up by one, positive 1 to scroll down by one
+    local function scaled_bar_scroll(direction)
+        local scroll_progress = scroll_offset / max_down_scroll
+        local bar_position = math.floor(scroll_progress * (max_bar_height - 1))
+
+        -- check what moving the scroll bar up or down would mean for the scroll progress
+        scroll_progress = (bar_position + direction) / (max_bar_height - 1)
+
+        return math.max(math.floor(scroll_progress * max_down_scroll), max_down_scroll)
+    end
+
+    -- scroll down the list
+    local function scroll_down(scaled)
+        if scroll_offset > max_down_scroll then
+            if scaled then
+                scroll_offset = scaled_bar_scroll(1)
+            else
+                scroll_offset = scroll_offset - 1
+            end
+
+            update_positions()
+        end
+    end
+
+    -- scroll up the list
+    local function scroll_up(scaled)
+        if scroll_offset < 0 then
+            if scaled then
+                scroll_offset = scaled_bar_scroll(-1)
+            else
+                scroll_offset = scroll_offset + 1
+            end
+
+            update_positions()
+        end
+    end
+
+    -- handle a child element having been added to the list
+    ---@param id element_id element identifier
+    ---@param child graphics_element child element
+    function e.on_added(id, child)
+        table.insert(list, { id = id, e = child, y = 0, h = child.get_height() })
+        update_positions()
+    end
+
+    -- handle a child element having been removed from the list
+    ---@param id element_id element identifier
+    function e.on_removed(id)
+        for idx, elem in ipairs(list) do
+            if elem.id == id then
+                table.remove(list, idx)
+                update_positions()
+                return
+            end
+        end
+    end
+
+    -- handle mouse interaction
+    ---@param event mouse_interaction mouse event
+    function e.handle_mouse(event)
+        if e.enabled then
+            if event.type == CLICK_TYPE.TAP then
+                if event.current.x == e.frame.w then
+                    if event.current.y == 1 or event.current.y < bar_bounds[1] then
+                        draw_arrows(1)
+                        scroll_up()
+                        if args.nav_active ~= nil then tcd.dispatch(0.25, function () draw_arrows(0) end) end
+                    elseif event.current.y == e.frame.h or event.current.y > bar_bounds[2] then
+                        draw_arrows(-1)
+                        scroll_down()
+                        if args.nav_active ~= nil then tcd.dispatch(0.25, function () draw_arrows(0) end) end
+                    end
+                end
+            elseif event.type == CLICK_TYPE.DOWN then
+                if event.current.x == e.frame.w then
+                    if event.current.y == 1 or event.current.y < bar_bounds[1] then
+                        draw_arrows(1)
+                        scroll_up()
+                    elseif event.current.y == e.frame.h or event.current.y > bar_bounds[2] then
+                        draw_arrows(-1)
+                        scroll_down()
+                    else
+                        -- clicked on bar
+                        holding_bar = true
+                        bar_grip_pos = event.current.y - bar_bounds[1]
+                        mouse_last_y = event.current.y
+                    end
+                end
+            elseif event.type == CLICK_TYPE.UP then
+                holding_bar = false
+                draw_arrows(0)
+            elseif event.type == CLICK_TYPE.DRAG then
+                if holding_bar then
+                    -- if mouse is within vertical frame, including the grip point
+                    if event.current.y > (1 + bar_grip_pos) and event.current.y <= ((e.frame.h - bar_height) + bar_grip_pos) then
+                        if event.current.y < mouse_last_y then
+                            scroll_up(bar_is_scaled)
+                        elseif event.current.y > mouse_last_y then
+                            scroll_down(bar_is_scaled)
+                        end
+
+                        mouse_last_y = event.current.y
+                    end
+                end
+            elseif event.type == CLICK_TYPE.SCROLL_DOWN then
+                scroll_down()
+            elseif event.type == CLICK_TYPE.SCROLL_UP then
+                scroll_up()
+            end
+        end
+    end
+
+    draw_arrows(0)
+    draw_bar()
+
+    return e.complete()
+end
+
+return listbox

graphics/elements/multipane.lua

@@ -12,6 +12,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new multipane element
 ---@nodiscard
@@ -36,7 +37,7 @@ local function multipane(args)
 
     e.set_value(1)
 
-    return e.get()
+    return e.complete()
 end
 
 return multipane

graphics/elements/pipenet.lua

@@ -12,6 +12,7 @@ local element = require("graphics.element")
 ---@field id? string element id
 ---@field x? integer 1 if omitted
 ---@field y? integer 1 if omitted
+---@field hidden? boolean true to hide on initial draw
 
 -- new pipe network
 ---@param args pipenet_args
@@ -37,7 +38,7 @@ local function pipenet(args)
     args.y = args.y or 1
 
     if args.bg ~= nil then
-        args.fg_bg = core.graphics.cpair(args.bg, args.bg)
+        args.fg_bg = core.cpair(args.bg, args.bg)
     end
 
     -- create new graphics element base object
@@ -55,7 +56,7 @@ local function pipenet(args)
 
         e.window.setCursorPos(x, y)
 
-        local c = core.graphics.cpair(pipe.color, e.fg_bg.bkg)
+        local c = core.cpair(pipe.color, e.fg_bg.bkg)
 
         if pipe.align_tr then
             -- cross width then height
@@ -141,7 +142,7 @@ local function pipenet(args)
 
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return pipenet

graphics/elements/rectangle.lua

@@ -16,6 +16,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new rectangle
 ---@param args rectangle_args
@@ -30,27 +31,35 @@ local function rectangle(args)
     end
 
     -- offset children
+    local offset_x = 0
+    local offset_y = 0
     if args.border ~= nil then
-        args.offset_x = args.border.width
-        args.offset_y = args.border.width
+        offset_x = args.border.width
+        offset_y = args.border.width
 
         -- slightly different y offset if the border is set to even
         if args.border.even then
             local width_x2 = (2 * args.border.width)
-            args.offset_y = math.floor(width_x2 / 3) + util.trinary(width_x2 % 3 > 0, 1, 0)
+            offset_y = math.floor(width_x2 / 3) + util.trinary(width_x2 % 3 > 0, 1, 0)
         end
     end
 
     -- create new graphics element base object
-    local e = element.new(args)
+    local e = element.new(args, offset_x, offset_y)
+
+    -- create content window for child elements
+    e.content_window = window.create(e.window, 1 + offset_x, 1 + offset_y, e.frame.w - (2 * offset_x), e.frame.h - (2 * offset_y))
+    e.content_window.setBackgroundColor(e.fg_bg.bkg)
+    e.content_window.setTextColor(e.fg_bg.fgd)
+    e.content_window.clear()
 
     -- draw bordered box if requested
     -- element constructor will have drawn basic colored rectangle regardless
     if args.border ~= nil then
         e.window.setCursorPos(1, 1)
 
-        local border_width = args.offset_x
-        local border_height = args.offset_y
+        local border_width = offset_x
+        local border_height = offset_y
         local border_blit = colors.toBlit(args.border.color)
         local width_x2 = border_width * 2
         local inner_width = e.frame.w - width_x2
@@ -177,7 +186,7 @@ local function rectangle(args)
         end
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return rectangle

graphics/elements/textbox.lua

@@ -5,7 +5,7 @@ local util    = require("scada-common.util")
 local core    = require("graphics.core")
 local element = require("graphics.element")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 ---@class textbox_args
 ---@field text string text to show
@@ -18,6 +18,7 @@ local TEXT_ALIGN = core.graphics.TEXT_ALIGN
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new text box
 ---@param args textbox_args
@@ -64,7 +65,7 @@ local function textbox(args)
         display_text(val)
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return textbox

graphics/elements/tiling.lua

@@ -16,6 +16,7 @@ local element = require("graphics.element")
 ---@field height? integer parent height if omitted
 ---@field gframe? graphics_frame frame instead of x/y/width/height
 ---@field fg_bg? cpair foreground/background colors
+---@field hidden? boolean true to hide on initial draw
 
 -- new tiling box
 ---@param args tiling_args
@@ -81,7 +82,7 @@ local function tiling(args)
         if inner_width % 2 == 0 then alternator = not alternator end
     end
 
-    return e.get()
+    return e.complete()
 end
 
 return tiling

graphics/events.lua

@@ -0,0 +1,161 @@
+--
+-- Graphics Events and Event Handlers
+--
+
+local util = require("scada-common.util")
+
+local events = {}
+
+---@enum CLICK_BUTTON
+events.CLICK_BUTTON = {
+    GENERIC = 0,
+    LEFT_BUTTON = 1,
+    RIGHT_BUTTON = 2,
+    MID_BUTTON = 3
+}
+
+---@enum CLICK_TYPE
+events.CLICK_TYPE = {
+    TAP = 1,            -- screen tap (complete click)
+    DOWN = 2,           -- button down
+    UP = 3,             -- button up (completed a click)
+    DRAG = 4,           -- mouse dragged
+    SCROLL_DOWN = 5,    -- scroll down
+    SCROLL_UP = 6       -- scroll up
+}
+
+-- create a new 2D coordinate
+---@param x integer
+---@param y integer
+---@return coordinate_2d
+local function _coord2d(x, y) return { x = x, y = y } end
+
+---@class mouse_interaction
+---@field monitor string
+---@field button CLICK_BUTTON
+---@field type CLICK_TYPE
+---@field initial coordinate_2d
+---@field current coordinate_2d
+
+local handler = {
+    -- left, right, middle button down tracking
+    button_down = {
+        _coord2d(0, 0),
+        _coord2d(0, 0),
+        _coord2d(0, 0)
+    }
+}
+
+-- create a new monitor touch mouse interaction event
+---@nodiscard
+---@param monitor string
+---@param x integer
+---@param y integer
+---@return mouse_interaction
+local function _monitor_touch(monitor, x, y)
+    return {
+        monitor = monitor,
+        button = events.CLICK_BUTTON.GENERIC,
+        type = events.CLICK_TYPE.TAP,
+        initial = _coord2d(x, y),
+        current = _coord2d(x, y)
+    }
+end
+
+-- create a new mouse button mouse interaction event
+---@nodiscard
+---@param button CLICK_BUTTON mouse button
+---@param type CLICK_TYPE click type
+---@param x1 integer initial x
+---@param y1 integer initial y
+---@param x2 integer current x
+---@param y2 integer current y
+---@return mouse_interaction
+local function _mouse_event(button, type, x1, y1, x2, y2)
+    return {
+        monitor = "terminal",
+        button = button,
+        type = type,
+        initial = _coord2d(x1, y1),
+        current = _coord2d(x2, y2)
+    }
+end
+
+-- create a new generic mouse interaction event
+---@nodiscard
+---@param type CLICK_TYPE
+---@param x integer
+---@param y integer
+---@return mouse_interaction
+function events.mouse_generic(type, x, y)
+    return {
+        monitor = "",
+        button = events.CLICK_BUTTON.GENERIC,
+        type = type,
+        initial = _coord2d(x, y),
+        current = _coord2d(x, y)
+    }
+end
+
+-- create a new transposed mouse interaction event using the event's monitor/button fields
+---@nodiscard
+---@param event mouse_interaction
+---@param elem_pos_x integer element's x position: new x = (event x - element x) + 1
+---@param elem_pos_y integer element's y position: new y = (event y - element y) + 1
+---@return mouse_interaction
+function events.mouse_transposed(event, elem_pos_x, elem_pos_y)
+    return {
+        monitor = event.monitor,
+        button = event.button,
+        type = event.type,
+        initial = _coord2d((event.initial.x - elem_pos_x) + 1, (event.initial.y - elem_pos_y) + 1),
+        current = _coord2d((event.current.x - elem_pos_x) + 1, (event.current.y - elem_pos_y) + 1)
+    }
+end
+
+-- check if an event qualifies as a click (tap or up)
+---@nodiscard
+---@param t CLICK_TYPE
+function events.was_clicked(t) return t == events.CLICK_TYPE.TAP or t == events.CLICK_TYPE.UP end
+
+-- create a new mouse event to pass onto graphics renderer<br>
+-- supports: mouse_click, mouse_up, mouse_drag, mouse_scroll, and monitor_touch
+---@param event_type os_event OS event to handle
+---@param opt integer|string button, scroll direction, or monitor for monitor touch
+---@param x integer x coordinate
+---@param y integer y coordinate
+---@return mouse_interaction|nil
+function events.new_mouse_event(event_type, opt, x, y)
+    if event_type == "mouse_click" then
+        ---@cast opt 1|2|3
+        handler.button_down[opt] = _coord2d(x, y)
+        return _mouse_event(opt, events.CLICK_TYPE.DOWN, x, y, x, y)
+    elseif event_type == "mouse_up" then
+        ---@cast opt 1|2|3
+        local initial = handler.button_down[opt]    ---@type coordinate_2d
+        return _mouse_event(opt, events.CLICK_TYPE.UP, initial.x, initial.y, x, y)
+    elseif event_type == "monitor_touch" then
+        ---@cast opt string
+        return _monitor_touch(opt, x, y)
+    elseif event_type == "mouse_drag" then
+        ---@cast opt 1|2|3
+        local initial = handler.button_down[opt]    ---@type coordinate_2d
+        return _mouse_event(opt, events.CLICK_TYPE.DRAG, initial.x, initial.y, x, y)
+    elseif event_type == "mouse_scroll" then
+        ---@cast opt 1|-1
+        local scroll_direction = util.trinary(opt == 1, events.CLICK_TYPE.SCROLL_DOWN, events.CLICK_TYPE.SCROLL_UP)
+        return _mouse_event(events.CLICK_BUTTON.GENERIC, scroll_direction, x, y, x, y)
+    end
+end
+
+-- create a new key event to pass onto graphics renderer<br>
+-- supports: char, key, and key_up
+---@param event_type os_event
+function events.new_key_event(event_type)
+    if event_type == "char" then
+    elseif event_type == "key" then
+    elseif event_type == "key_up" then
+    end
+end
+
+return events

graphics/flasher.lua

@@ -2,7 +2,7 @@
 -- Indicator Light Flasher
 --
 
-local tcd = require("scada-common.tcallbackdsp")
+local tcd = require("scada-common.tcd")
 
 local flasher = {}
 

imgen.py

@@ -71,7 +71,7 @@ def make_manifest(size):
         "depends" : {
             "reactor-plc" : [ "system", "common", "graphics" ],
             "rtu" : [ "system", "common", "graphics" ],
-            "supervisor" : [ "system", "common" ],
+            "supervisor" : [ "system", "common", "graphics" ],
             "coordinator" : [ "system", "common", "graphics" ],
             "pocket" : [ "system", "common", "graphics" ]
         },
@@ -111,7 +111,7 @@ f.close()
 if len(sys.argv) > 1 and sys.argv[1] == "shields":
     # write all the JSON files for shields.io
     for key, version in final_manifest["versions"].items():
-        f = open("./shields/" + key + ".json", "w")
+        f = open("./deploy/" + key + ".json", "w")
 
         if version.find("alpha") >= 0:
             color = "yellow"

pocket/config.lua

@@ -1,11 +1,11 @@
 local config = {}
 
--- port of the SCADA supervisor
-config.SCADA_SV_PORT = 16100
--- port for SCADA coordinator API access
-config.SCADA_API_PORT = 16200
--- port to listen to incoming packets FROM servers
-config.LISTEN_PORT = 16201
+-- supervisor comms channel
+config.SVR_CHANNEL = 16240
+-- coordinator comms channel
+config.CRD_CHANNEL = 16243
+-- pocket comms channel
+config.PKT_CHANNEL = 16244
 -- max trusted modem message distance (0 to disable check)
 config.TRUSTED_RANGE = 0
 -- time in seconds (>= 2) before assuming a remote device is no longer active
@@ -17,5 +17,7 @@ config.LOG_PATH = "/log.txt"
 --  0 = APPEND (adds to existing file on start)
 --  1 = NEW (replaces existing file on start)
 config.LOG_MODE = 0
+-- true to log verbose debug messages
+config.LOG_DEBUG = false
 
 return config

pocket/pocket.lua

@@ -18,22 +18,24 @@ local pocket = {}
 ---@nodiscard
 ---@param version string pocket version
 ---@param modem table modem device
----@param local_port integer local pocket port
----@param sv_port integer port of supervisor
----@param api_port integer port of coordinator API
+---@param pkt_channel integer pocket comms channel
+---@param svr_channel integer supervisor access channel
+---@param crd_channel integer coordinator access channel
 ---@param range integer trusted device connection range
 ---@param sv_watchdog watchdog
 ---@param api_watchdog watchdog
-function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_watchdog, api_watchdog)
+function pocket.comms(version, modem, pkt_channel, svr_channel, crd_channel, range, sv_watchdog, api_watchdog)
     local self = {
         sv = {
             linked = false,
+            addr = comms.BROADCAST,
             seq_num = 0,
             r_seq_num = nil,    ---@type nil|integer
             last_est_ack = ESTABLISH_ACK.ALLOW
         },
         api = {
             linked = false,
+            addr = comms.BROADCAST,
             seq_num = 0,
             r_seq_num = nil,    ---@type nil|integer
             last_est_ack = ESTABLISH_ACK.ALLOW
@@ -48,7 +50,7 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
     -- configure modem channels
     local function _conf_channels()
         modem.closeAll()
-        modem.open(local_port)
+        modem.open(pkt_channel)
     end
 
     _conf_channels()
@@ -61,9 +63,9 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
         local pkt = comms.mgmt_packet()
 
         pkt.make(msg_type, msg)
-        s_pkt.make(self.sv.seq_num, PROTOCOL.SCADA_MGMT, pkt.raw_sendable())
+        s_pkt.make(self.sv.addr, self.sv.seq_num, PROTOCOL.SCADA_MGMT, pkt.raw_sendable())
 
-        modem.transmit(sv_port, local_port, s_pkt.raw_sendable())
+        modem.transmit(svr_channel, pkt_channel, s_pkt.raw_sendable())
         self.sv.seq_num = self.sv.seq_num + 1
     end
 
@@ -75,9 +77,9 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
         local pkt = comms.mgmt_packet()
 
         pkt.make(msg_type, msg)
-        s_pkt.make(self.api.seq_num, PROTOCOL.SCADA_MGMT, pkt.raw_sendable())
+        s_pkt.make(self.api.addr, self.api.seq_num, PROTOCOL.SCADA_MGMT, pkt.raw_sendable())
 
-        modem.transmit(api_port, local_port, s_pkt.raw_sendable())
+        modem.transmit(crd_channel, pkt_channel, s_pkt.raw_sendable())
         self.api.seq_num = self.api.seq_num + 1
     end
 
@@ -89,9 +91,9 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
     --     local pkt = comms.capi_packet()
 
     --     pkt.make(msg_type, msg)
-    --     s_pkt.make(self.api.seq_num, PROTOCOL.COORD_API, pkt.raw_sendable())
+    --     s_pkt.make(self.api.addr, self.api.seq_num, PROTOCOL.COORD_API, pkt.raw_sendable())
 
-    --     modem.transmit(api_port, local_port, s_pkt.raw_sendable())
+    --     modem.transmit(crd_channel, pkt_channel, s_pkt.raw_sendable())
     --     self.api.seq_num = self.api.seq_num + 1
     -- end
 
@@ -133,6 +135,8 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
     function public.close_sv()
         sv_watchdog.cancel()
         self.sv.linked = false
+        self.sv.r_seq_num = nil
+        self.sv.addr = comms.BROADCAST
         _send_sv(SCADA_MGMT_TYPE.CLOSE, {})
     end
 
@@ -140,6 +144,8 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
     function public.close_api()
         api_watchdog.cancel()
         self.api.linked = false
+        self.api.r_seq_num = nil
+        self.api.addr = comms.BROADCAST
         _send_crd(SCADA_MGMT_TYPE.CLOSE, {})
     end
 
@@ -214,18 +220,23 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
     ---@param packet mgmt_frame|capi_frame|nil
     function public.handle_packet(packet)
         if packet ~= nil then
-            local l_port = packet.scada_frame.local_port()
-            local r_port = packet.scada_frame.remote_port()
+            local l_chan   = packet.scada_frame.local_channel()
+            local r_chan   = packet.scada_frame.remote_channel()
             local protocol = packet.scada_frame.protocol()
+            local src_addr = packet.scada_frame.src_addr()
 
-            if l_port ~= local_port then
-                log.debug("received packet on unconfigured channel " .. l_port, true)
-            elseif r_port == api_port then
+            if l_chan ~= pkt_channel then
+                log.debug("received packet on unconfigured channel " .. l_chan, true)
+            elseif r_chan == crd_channel then
                 -- check sequence number
                 if self.api.r_seq_num == nil then
                     self.api.r_seq_num = packet.scada_frame.seq_num()
                 elseif self.connected and ((self.api.r_seq_num + 1) ~= packet.scada_frame.seq_num()) then
-                    log.warning("sequence out-of-order: last = " .. self.api.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
+                    log.warning("sequence out-of-order (API): last = " .. self.api.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
+                    return
+                elseif self.api.linked and (src_addr ~= self.api.addr) then
+                    log.debug("received packet from unknown computer " .. src_addr .. " while linked (API expected " .. self.api.addr ..
+                                "); channel in use by another system?")
                     return
                 else
                     self.api.r_seq_num = packet.scada_frame.seq_num()
@@ -247,6 +258,7 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                                 log.info("coordinator connection established")
                                 self.establish_delay_counter = 0
                                 self.api.linked = true
+                                self.api.addr = src_addr
 
                                 if self.sv.linked then
                                     coreio.report_link_state(LINK_STATE.LINKED)
@@ -294,6 +306,8 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                             -- handle session close
                             api_watchdog.cancel()
                             self.api.linked = false
+                            self.api.r_seq_num = nil
+                            self.api.addr = comms.BROADCAST
                             log.info("coordinator server connection closed by remote host")
                         else
                             log.debug("received unknown SCADA_MGMT packet type " .. packet.type .. " from coordinator")
@@ -304,12 +318,16 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                 else
                     log.debug("illegal packet type " .. protocol .. " from coordinator", true)
                 end
-            elseif r_port == sv_port then
+            elseif r_chan == svr_channel then
                 -- check sequence number
                 if self.sv.r_seq_num == nil then
                     self.sv.r_seq_num = packet.scada_frame.seq_num()
                 elseif self.connected and ((self.sv.r_seq_num + 1) ~= packet.scada_frame.seq_num()) then
-                    log.warning("sequence out-of-order: last = " .. self.sv.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
+                    log.warning("sequence out-of-order (SVR): last = " .. self.sv.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
+                    return
+                elseif self.sv.linked and (src_addr ~= self.sv.addr) then
+                    log.debug("received packet from unknown computer " .. src_addr .. " while linked (SVR expected " .. self.sv.addr ..
+                                "); channel in use by another system?")
                     return
                 else
                     self.sv.r_seq_num = packet.scada_frame.seq_num()
@@ -330,6 +348,7 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                                 log.info("supervisor connection established")
                                 self.establish_delay_counter = 0
                                 self.sv.linked = true
+                                self.sv.addr = src_addr
 
                                 if self.api.linked then
                                     coreio.report_link_state(LINK_STATE.LINKED)
@@ -377,6 +396,8 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                             -- handle session close
                             sv_watchdog.cancel()
                             self.sv.linked = false
+                            self.sv.r_seq_num = nil
+                            self.sv.addr = comms.BROADCAST
                             log.info("supervisor server connection closed by remote host")
                         else
                             log.debug("received unknown SCADA_MGMT packet type " .. packet.type .. " from supervisor")
@@ -388,7 +409,7 @@ function pocket.comms(version, modem, local_port, sv_port, api_port, range, sv_w
                     log.debug("illegal packet type " .. protocol .. " from supervisor", true)
                 end
             else
-                log.debug("received packet from unconfigured channel " .. r_port, true)
+                log.debug("received packet from unconfigured channel " .. r_chan, true)
             end
         end
     end

pocket/renderer.lua

@@ -70,9 +70,9 @@ end
 function renderer.ui_ready() return ui.display ~= nil end
 
 -- handle a mouse event
----@param event mouse_interaction
+---@param event mouse_interaction|nil
 function renderer.handle_mouse(event)
-    if ui.display ~= nil then
+    if ui.display ~= nil and event ~= nil then
         ui.display.handle_mouse(event)
     end
 end

pocket/startup.lua

@@ -4,20 +4,20 @@
 
 require("/initenv").init_env()
 
-local crash        = require("scada-common.crash")
-local log          = require("scada-common.log")
-local ppm          = require("scada-common.ppm")
-local tcallbackdsp = require("scada-common.tcallbackdsp")
-local util         = require("scada-common.util")
+local crash    = require("scada-common.crash")
+local log      = require("scada-common.log")
+local ppm      = require("scada-common.ppm")
+local tcd      = require("scada-common.tcd")
+local util     = require("scada-common.util")
 
-local core         = require("graphics.core")
+local core     = require("graphics.core")
 
-local config       = require("pocket.config")
-local coreio       = require("pocket.coreio")
-local pocket       = require("pocket.pocket")
-local renderer     = require("pocket.renderer")
+local config   = require("pocket.config")
+local coreio   = require("pocket.coreio")
+local pocket   = require("pocket.pocket")
+local renderer = require("pocket.renderer")
 
-local POCKET_VERSION = "alpha-v0.2.6"
+local POCKET_VERSION = "alpha-v0.4.5"
 
 local println = util.println
 local println_ts = util.println_ts
@@ -28,9 +28,9 @@ local println_ts = util.println_ts
 
 local cfv = util.new_validator()
 
-cfv.assert_port(config.SCADA_SV_PORT)
-cfv.assert_port(config.SCADA_API_PORT)
-cfv.assert_port(config.LISTEN_PORT)
+cfv.assert_channel(config.SVR_CHANNEL)
+cfv.assert_channel(config.CRD_CHANNEL)
+cfv.assert_channel(config.PKT_CHANNEL)
 cfv.assert_type_int(config.TRUSTED_RANGE)
 cfv.assert_type_num(config.COMMS_TIMEOUT)
 cfv.assert_min(config.COMMS_TIMEOUT, 2)
@@ -43,7 +43,7 @@ assert(cfv.valid(), "bad config file: missing/invalid fields")
 -- log init
 ----------------------------------------
 
-log.init(config.LOG_PATH, config.LOG_MODE)
+log.init(config.LOG_PATH, config.LOG_MODE, config.LOG_DEBUG == true)
 
 log.info("========================================")
 log.info("BOOTING pocket.startup " .. POCKET_VERSION)
@@ -89,8 +89,8 @@ local function main()
     log.debug("startup> conn watchdogs created")
 
     -- start comms, open all channels
-    local pocket_comms = pocket.comms(POCKET_VERSION, modem, config.LISTEN_PORT, config.SCADA_SV_PORT,
-                                        config.SCADA_API_PORT, config.TRUSTED_RANGE, conn_wd.sv, conn_wd.api)
+    local pocket_comms = pocket.comms(POCKET_VERSION, modem, config.PKT_CHANNEL, config.SVR_CHANNEL,
+                                        config.CRD_CHANNEL, config.TRUSTED_RANGE, conn_wd.sv, conn_wd.api)
     log.debug("startup> comms init")
 
     -- base loop clock (2Hz, 10 ticks)
@@ -120,54 +120,54 @@ local function main()
         conn_wd.sv.feed()
         conn_wd.api.feed()
         log.debug("startup> conn watchdog started")
-    end
 
-    -- main event loop
-    while ui_ok do
-        local event, param1, param2, param3, param4, param5 = util.pull_event()
+        -- main event loop
+        while true do
+            local event, param1, param2, param3, param4, param5 = util.pull_event()
 
-        -- handle event
-        if event == "timer" then
-            if loop_clock.is_clock(param1) then
-                -- main loop tick
+            -- handle event
+            if event == "timer" then
+                if loop_clock.is_clock(param1) then
+                    -- main loop tick
 
-                -- relink if necessary
-                pocket_comms.link_update()
+                    -- relink if necessary
+                    pocket_comms.link_update()
 
-                loop_clock.start()
-            elseif conn_wd.sv.is_timer(param1) then
-                -- supervisor watchdog timeout
-                log.info("supervisor server timeout")
-                pocket_comms.close_sv()
-            elseif conn_wd.api.is_timer(param1) then
-                -- coordinator watchdog timeout
-                log.info("coordinator api server timeout")
-                pocket_comms.close_api()
-            else
-                -- a non-clock/main watchdog timer event
-                -- notify timer callback dispatcher
-                tcallbackdsp.handle(param1)
+                    loop_clock.start()
+                elseif conn_wd.sv.is_timer(param1) then
+                    -- supervisor watchdog timeout
+                    log.info("supervisor server timeout")
+                    pocket_comms.close_sv()
+                elseif conn_wd.api.is_timer(param1) then
+                    -- coordinator watchdog timeout
+                    log.info("coordinator api server timeout")
+                    pocket_comms.close_api()
+                else
+                    -- a non-clock/main watchdog timer event
+                    -- notify timer callback dispatcher
+                    tcd.handle(param1)
+                end
+            elseif event == "modem_message" then
+                -- got a packet
+                local packet = pocket_comms.parse_packet(param1, param2, param3, param4, param5)
+                pocket_comms.handle_packet(packet)
+            elseif event == "mouse_click" or event == "mouse_up" or event == "mouse_drag" or event == "mouse_scroll" then
+                -- handle a monitor touch event
+                renderer.handle_mouse(core.events.new_mouse_event(event, param1, param2, param3))
+            end
+
+            -- check for termination request
+            if event == "terminate" or ppm.should_terminate() then
+                log.info("terminate requested, closing server connections...")
+                pocket_comms.close()
+                log.info("connections closed")
+                break
             end
-        elseif event == "modem_message" then
-            -- got a packet
-            local packet = pocket_comms.parse_packet(param1, param2, param3, param4, param5)
-            pocket_comms.handle_packet(packet)
-        elseif event == "mouse_click" then
-            -- handle a monitor touch event
-            renderer.handle_mouse(core.events.touch(param1, param2, param3))
         end
 
-        -- check for termination request
-        if event == "terminate" or ppm.should_terminate() then
-            log.info("terminate requested, closing server connections...")
-            pocket_comms.close()
-            log.info("connections closed")
-            break
-        end
+        renderer.close_ui()
     end
 
-    renderer.close_ui()
-
     println_ts("exited")
     log.info("exited")
 end

pocket/ui/components/conn_waiting.lua

@@ -11,9 +11,9 @@ local TextBox     = require("graphics.elements.textbox")
 
 local WaitingAnim = require("graphics.elements.animations.waiting")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- create a waiting view
 ---@param parent graphics_element parent
@@ -25,7 +25,7 @@ local function init(parent, y, is_api)
     -- bounding box div
     local box = Div{parent=root,x=1,y=y,height=5}
 
-    local waiting_x = math.floor(parent.width() / 2) - 1
+    local waiting_x = math.floor(parent.get_width() / 2) - 1
 
     if is_api then
         WaitingAnim{parent=box,x=waiting_x,y=1,fg_bg=cpair(colors.blue,style.root.bkg)}

pocket/ui/main.lua

@@ -8,11 +8,11 @@ local style        = require("pocket.ui.style")
 
 local conn_waiting = require("pocket.ui.components.conn_waiting")
 
-local home_page    = require("pocket.ui.components.home_page")
-local unit_page    = require("pocket.ui.components.unit_page")
-local reactor_page = require("pocket.ui.components.reactor_page")
-local boiler_page  = require("pocket.ui.components.boiler_page")
-local turbine_page = require("pocket.ui.components.turbine_page")
+local home_page    = require("pocket.ui.pages.home_page")
+local unit_page    = require("pocket.ui.pages.unit_page")
+local reactor_page = require("pocket.ui.pages.reactor_page")
+local boiler_page  = require("pocket.ui.pages.boiler_page")
+local turbine_page = require("pocket.ui.pages.turbine_page")
 
 local core         = require("graphics.core")
 
@@ -22,9 +22,9 @@ local TextBox      = require("graphics.elements.textbox")
 
 local Sidebar      = require("graphics.elements.controls.sidebar")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- create new main view
 ---@param main graphics_element main displaybox
@@ -45,7 +45,7 @@ local function init(main)
 
     local root_pane = MultiPane{parent=root_pane_div,x=1,y=1,panes=root_panes}
 
-    coreio.core_ps().subscribe("link_state", function (state)
+    root_pane.register(coreio.core_ps(), "link_state", function (state)
         if state == coreio.LINK_STATE.UNLINKED or state == coreio.LINK_STATE.API_LINK_ONLY then
             root_pane.set_value(1)
         elseif state == coreio.LINK_STATE.SV_LINK_ONLY then

pocket/ui/pages/boiler_page.lua

@@ -5,9 +5,9 @@ local core    = require("graphics.core")
 local Div     = require("graphics.elements.div")
 local TextBox = require("graphics.elements.textbox")
 
--- local cpair = core.graphics.cpair
+-- local cpair = core.cpair
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new boiler page view
 ---@param root graphics_element parent

pocket/ui/pages/home_page.lua

@@ -5,9 +5,9 @@ local core    = require("graphics.core")
 local Div     = require("graphics.elements.div")
 local TextBox = require("graphics.elements.textbox")
 
--- local cpair = core.graphics.cpair
+-- local cpair = core.cpair
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new home page view
 ---@param root graphics_element parent

pocket/ui/pages/reactor_page.lua

@@ -5,9 +5,9 @@ local core    = require("graphics.core")
 local Div     = require("graphics.elements.div")
 local TextBox = require("graphics.elements.textbox")
 
--- local cpair = core.graphics.cpair
+-- local cpair = core.cpair
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new reactor page view
 ---@param root graphics_element parent

pocket/ui/pages/turbine_page.lua

@@ -5,9 +5,9 @@ local core    = require("graphics.core")
 local Div     = require("graphics.elements.div")
 local TextBox = require("graphics.elements.textbox")
 
--- local cpair = core.graphics.cpair
+-- local cpair = core.cpair
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new turbine page view
 ---@param root graphics_element parent

pocket/ui/pages/unit_page.lua

@@ -5,9 +5,9 @@ local core    = require("graphics.core")
 local Div     = require("graphics.elements.div")
 local TextBox = require("graphics.elements.textbox")
 
--- local cpair = core.graphics.cpair
+-- local cpair = core.cpair
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
 -- new unit page view
 ---@param root graphics_element parent

pocket/ui/style.lua

@@ -6,7 +6,7 @@ local core = require("graphics.core")
 
 local style = {}
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- GLOBAL --
 

reactor-plc/config.lua

@@ -9,10 +9,10 @@ config.REACTOR_ID = 1
 -- when emergency coolant is needed due to low coolant
 -- config.EMERGENCY_COOL = { side = "right", color = nil }
 
--- port to send packets TO server
-config.SERVER_PORT = 16000
--- port to listen to incoming packets FROM server
-config.LISTEN_PORT = 14001
+-- supervisor comms channel
+config.SVR_CHANNEL = 16240
+-- PLC comms channel
+config.PLC_CHANNEL = 16241
 -- max trusted modem message distance (0 to disable check)
 config.TRUSTED_RANGE = 0
 -- time in seconds (>= 2) before assuming a remote device is no longer active
@@ -24,5 +24,7 @@ config.LOG_PATH = "/log.txt"
 --  0 = APPEND (adds to existing file on start)
 --  1 = NEW (replaces existing file on start)
 config.LOG_MODE = 0
+-- true to log verbose debug messages
+config.LOG_DEBUG = false
 
 return config

reactor-plc/databus.lua

@@ -8,14 +8,16 @@ local util = require("scada-common.util")
 
 local databus = {}
 
+-- databus PSIL
+databus.ps = psil.create()
+
 local dbus_iface = {
-    ps = psil.create(),
     rps_scram = function () log.debug("DBUS: unset rps_scram() called") end,
     rps_reset = function () log.debug("DBUS: unset rps_reset() called") end
 }
 
 -- call to toggle heartbeat signal
-function databus.heartbeat() dbus_iface.ps.toggle("heartbeat") end
+function databus.heartbeat() databus.ps.toggle("heartbeat") end
 
 -- link RPS command functions
 ---@param scram function reactor SCRAM function
@@ -35,42 +37,42 @@ function databus.rps_reset() dbus_iface.rps_reset() end
 ---@param plc_v string PLC version
 ---@param comms_v string comms version
 function databus.tx_versions(plc_v, comms_v)
-    dbus_iface.ps.publish("version", plc_v)
-    dbus_iface.ps.publish("comms_version", comms_v)
+    databus.ps.publish("version", plc_v)
+    databus.ps.publish("comms_version", comms_v)
 end
 
 -- transmit unit ID across the bus
 ---@param id integer unit ID
 function databus.tx_id(id)
-    dbus_iface.ps.publish("unit_id", id)
+    databus.ps.publish("unit_id", id)
 end
 
 -- transmit hardware status across the bus
 ---@param plc_state plc_state
 function databus.tx_hw_status(plc_state)
-    dbus_iface.ps.publish("reactor_dev_state", util.trinary(plc_state.no_reactor, 1, util.trinary(plc_state.reactor_formed, 3, 2)))
-    dbus_iface.ps.publish("has_modem", not plc_state.no_modem)
-    dbus_iface.ps.publish("degraded", plc_state.degraded)
-    dbus_iface.ps.publish("init_ok", plc_state.init_ok)
+    databus.ps.publish("reactor_dev_state", util.trinary(plc_state.no_reactor, 1, util.trinary(plc_state.reactor_formed, 3, 2)))
+    databus.ps.publish("has_modem", not plc_state.no_modem)
+    databus.ps.publish("degraded", plc_state.degraded)
+    databus.ps.publish("init_ok", plc_state.init_ok)
 end
 
 -- transmit thread (routine) statuses
 ---@param thread string thread name
 ---@param ok boolean thread state
 function databus.tx_rt_status(thread, ok)
-    dbus_iface.ps.publish(util.c("routine__", thread), ok)
+    databus.ps.publish(util.c("routine__", thread), ok)
 end
 
 -- transmit supervisor link state across the bus
 ---@param state integer
 function databus.tx_link_state(state)
-    dbus_iface.ps.publish("link_state", state)
+    databus.ps.publish("link_state", state)
 end
 
 -- transmit reactor enable state across the bus
 ---@param active boolean reactor active
 function databus.tx_reactor_state(active)
-    dbus_iface.ps.publish("reactor_active", active)
+    databus.ps.publish("reactor_active", active)
 end
 
 -- transmit RPS data across the bus
@@ -78,26 +80,26 @@ end
 ---@param status table RPS status
 ---@param emer_cool_active boolean RPS activated the emergency coolant
 function databus.tx_rps(tripped, status, emer_cool_active)
-    dbus_iface.ps.publish("rps_scram", tripped)
-    dbus_iface.ps.publish("rps_damage", status[1])
-    dbus_iface.ps.publish("rps_high_temp", status[2])
-    dbus_iface.ps.publish("rps_low_ccool", status[3])
-    dbus_iface.ps.publish("rps_high_waste", status[4])
-    dbus_iface.ps.publish("rps_high_hcool", status[5])
-    dbus_iface.ps.publish("rps_no_fuel", status[6])
-    dbus_iface.ps.publish("rps_fault", status[7])
-    dbus_iface.ps.publish("rps_timeout", status[8])
-    dbus_iface.ps.publish("rps_manual", status[9])
-    dbus_iface.ps.publish("rps_automatic", status[10])
-    dbus_iface.ps.publish("rps_sysfail", status[11])
-    dbus_iface.ps.publish("emer_cool", emer_cool_active)
+    databus.ps.publish("rps_scram", tripped)
+    databus.ps.publish("rps_damage", status[1])
+    databus.ps.publish("rps_high_temp", status[2])
+    databus.ps.publish("rps_low_ccool", status[3])
+    databus.ps.publish("rps_high_waste", status[4])
+    databus.ps.publish("rps_high_hcool", status[5])
+    databus.ps.publish("rps_no_fuel", status[6])
+    databus.ps.publish("rps_fault", status[7])
+    databus.ps.publish("rps_timeout", status[8])
+    databus.ps.publish("rps_manual", status[9])
+    databus.ps.publish("rps_automatic", status[10])
+    databus.ps.publish("rps_sysfail", status[11])
+    databus.ps.publish("emer_cool", emer_cool_active)
 end
 
 -- link a function to receive data from the bus
 ---@param field string field name
 ---@param func function function to link
 function databus.rx_field(field, func)
-    dbus_iface.ps.subscribe(field, func)
+    databus.ps.subscribe(field, func)
 end
 
 return databus

reactor-plc/panel/front_panel.lua

@@ -2,6 +2,7 @@
 -- Main SCADA Coordinator GUI
 --
 
+local types      = require("scada-common.types")
 local util       = require("scada-common.util")
 
 local config     = require("reactor-plc.config")
@@ -22,16 +23,16 @@ local LED        = require("graphics.elements.indicators.led")
 local LEDPair    = require("graphics.elements.indicators.ledpair")
 local RGBLED     = require("graphics.elements.indicators.ledrgb")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
-local border = core.graphics.border
+local cpair = core.cpair
+local border = core.border
 
 -- create new main view
 ---@param panel graphics_element main displaybox
 local function init(panel)
     local header = TextBox{parent=panel,y=1,text="REACTOR PLC - UNIT ?",alignment=TEXT_ALIGN.CENTER,height=1,fg_bg=style.header}
-    databus.rx_field("unit_id", function (id) header.set_value(util.c("REACTOR PLC - UNIT ", id)) end)
+    header.register(databus.ps, "unit_id", function (id) header.set_value(util.c("REACTOR PLC - UNIT ", id)) end)
 
     --
     -- system indicators
@@ -43,18 +44,18 @@ local function init(panel)
     local heartbeat = LED{parent=system,label="HEARTBEAT",colors=cpair(colors.green,colors.green_off)}
     system.line_break()
 
-    databus.rx_field("init_ok", init_ok.update)
-    databus.rx_field("heartbeat", heartbeat.update)
+    init_ok.register(databus.ps, "init_ok", init_ok.update)
+    heartbeat.register(databus.ps, "heartbeat", heartbeat.update)
 
     local reactor = LEDPair{parent=system,label="REACTOR",off=colors.red,c1=colors.yellow,c2=colors.green}
     local modem = LED{parent=system,label="MODEM",colors=cpair(colors.green,colors.green_off)}
     local network = RGBLED{parent=system,label="NETWORK",colors={colors.green,colors.red,colors.orange,colors.yellow,colors.gray}}
-    network.update(5)
+    network.update(types.PANEL_LINK_STATE.DISCONNECTED)
     system.line_break()
 
-    databus.rx_field("reactor_dev_state", reactor.update)
-    databus.rx_field("has_modem", modem.update)
-    databus.rx_field("link_state", network.update)
+    reactor.register(databus.ps, "reactor_dev_state", reactor.update)
+    modem.register(databus.ps, "has_modem", modem.update)
+    network.register(databus.ps, "link_state", network.update)
 
     local rt_main = LED{parent=system,label="RT MAIN",colors=cpair(colors.green,colors.green_off)}
     local rt_rps  = LED{parent=system,label="RT RPS",colors=cpair(colors.green,colors.green_off)}
@@ -63,11 +64,15 @@ local function init(panel)
     local rt_sctl = LED{parent=system,label="RT SPCTL",colors=cpair(colors.green,colors.green_off)}
     system.line_break()
 
-    databus.rx_field("routine__main", rt_main.update)
-    databus.rx_field("routine__rps", rt_rps.update)
-    databus.rx_field("routine__comms_tx", rt_cmtx.update)
-    databus.rx_field("routine__comms_rx", rt_cmrx.update)
-    databus.rx_field("routine__spctl", rt_sctl.update)
+    rt_main.register(databus.ps, "routine__main", rt_main.update)
+    rt_rps.register(databus.ps, "routine__rps", rt_rps.update)
+    rt_cmtx.register(databus.ps, "routine__comms_tx", rt_cmtx.update)
+    rt_cmrx.register(databus.ps, "routine__comms_rx", rt_cmrx.update)
+    rt_sctl.register(databus.ps, "routine__spctl", rt_sctl.update)
+
+---@diagnostic disable-next-line: undefined-field
+    local comp_id = util.sprintf("(%d)", os.getComputerID())
+    TextBox{parent=system,x=9,y=5,width=6,height=1,text=comp_id,fg_bg=cpair(colors.lightGray,colors.ivory)}
 
     --
     -- status & controls
@@ -80,7 +85,7 @@ local function init(panel)
     -- only show emergency coolant LED if emergency coolant is configured for this device
     if type(config.EMERGENCY_COOL) == "table" then
         local emer_cool = LED{parent=status,x=2,width=14,label="EMER COOLANT",colors=cpair(colors.yellow,colors.yellow_off)}
-        databus.rx_field("emer_cool", emer_cool.update)
+        emer_cool.register(databus.ps, "emer_cool", emer_cool.update)
     end
 
     local status_trip_rct = Rectangle{parent=status,width=20,height=3,x=1,border=border(1,colors.lightGray,true),even_inner=true,fg_bg=cpair(colors.black,colors.ivory)}
@@ -92,8 +97,8 @@ local function init(panel)
     PushButton{parent=controls,x=1,y=1,min_width=7,text="SCRAM",callback=databus.rps_scram,fg_bg=cpair(colors.black,colors.red),active_fg_bg=cpair(colors.black,colors.red_off)}
     PushButton{parent=controls,x=9,y=1,min_width=7,text="RESET",callback=databus.rps_reset,fg_bg=cpair(colors.black,colors.yellow),active_fg_bg=cpair(colors.black,colors.yellow_off)}
 
-    databus.rx_field("reactor_active", active.update)
-    databus.rx_field("rps_scram", scram.update)
+    active.register(databus.ps, "reactor_active", active.update)
+    scram.register(databus.ps, "rps_scram", scram.update)
 
     --
     -- about footer
@@ -103,8 +108,8 @@ local function init(panel)
     local fw_v    = TextBox{parent=about,x=2,y=1,text="FW: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
     local comms_v = TextBox{parent=about,x=17,y=1,text="NT: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
 
-    databus.rx_field("version", function (version) fw_v.set_value(util.c("FW: ", version)) end)
-    databus.rx_field("comms_version", function (version) comms_v.set_value(util.c("NT: v", version)) end)
+    fw_v.register(databus.ps, "version", function (version) fw_v.set_value(util.c("FW: ", version)) end)
+    comms_v.register(databus.ps, "comms_version", function (version) comms_v.set_value(util.c("NT: v", version)) end)
 
     --
     -- rps list
@@ -126,17 +131,17 @@ local function init(panel)
     local rps_ccl  = LED{parent=rps,label="LO CCOOLANT",colors=cpair(colors.red,colors.red_off)}
     local rps_hcl  = LED{parent=rps,label="HI HCOOLANT",colors=cpair(colors.red,colors.red_off)}
 
-    databus.rx_field("rps_manual", rps_man.update)
-    databus.rx_field("rps_automatic", rps_auto.update)
-    databus.rx_field("rps_timeout", rps_tmo.update)
-    databus.rx_field("rps_fault", rps_flt.update)
-    databus.rx_field("rps_sysfail", rps_fail.update)
-    databus.rx_field("rps_damage", rps_dmg.update)
-    databus.rx_field("rps_high_temp", rps_tmp.update)
-    databus.rx_field("rps_no_fuel", rps_nof.update)
-    databus.rx_field("rps_high_waste", rps_wst.update)
-    databus.rx_field("rps_low_ccool", rps_ccl.update)
-    databus.rx_field("rps_high_hcool", rps_hcl.update)
+    rps_man.register(databus.ps, "rps_manual", rps_man.update)
+    rps_auto.register(databus.ps, "rps_automatic", rps_auto.update)
+    rps_tmo.register(databus.ps, "rps_timeout", rps_tmo.update)
+    rps_flt.register(databus.ps, "rps_fault", rps_flt.update)
+    rps_fail.register(databus.ps, "rps_sysfail", rps_fail.update)
+    rps_dmg.register(databus.ps, "rps_damage", rps_dmg.update)
+    rps_tmp.register(databus.ps, "rps_high_temp", rps_tmp.update)
+    rps_nof.register(databus.ps, "rps_no_fuel", rps_nof.update)
+    rps_wst.register(databus.ps, "rps_high_waste", rps_wst.update)
+    rps_ccl.register(databus.ps, "rps_low_ccool", rps_ccl.update)
+    rps_hcl.register(databus.ps, "rps_high_hcool", rps_hcl.update)
 end
 
 return init

reactor-plc/panel/style.lua

@@ -6,7 +6,7 @@ local core = require("graphics.core")
 
 local style = {}
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- GLOBAL --
 

reactor-plc/plc.lua

@@ -446,14 +446,15 @@ end
 ---@param id integer reactor ID
 ---@param version string PLC version
 ---@param modem table modem device
----@param local_port integer local listening port
----@param server_port integer remote server port
+---@param plc_channel integer PLC comms channel
+---@param svr_channel integer supervisor server channel
 ---@param range integer trusted device connection range
 ---@param reactor table reactor device
 ---@param rps rps RPS reference
 ---@param conn_watchdog watchdog watchdog reference
-function plc.comms(id, version, modem, local_port, server_port, range, reactor, rps, conn_watchdog)
+function plc.comms(id, version, modem, plc_channel, svr_channel, range, reactor, rps, conn_watchdog)
     local self = {
+        sv_addr = comms.BROADCAST,
         seq_num = 0,
         r_seq_num = nil,
         scrammed = false,
@@ -472,7 +473,7 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
     -- configure modem channels
     local function _conf_channels()
         modem.closeAll()
-        modem.open(local_port)
+        modem.open(plc_channel)
     end
 
     _conf_channels()
@@ -485,9 +486,9 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
         local r_pkt = comms.rplc_packet()
 
         r_pkt.make(id, msg_type, msg)
-        s_pkt.make(self.seq_num, PROTOCOL.RPLC, r_pkt.raw_sendable())
+        s_pkt.make(self.sv_addr, self.seq_num, PROTOCOL.RPLC, r_pkt.raw_sendable())
 
-        modem.transmit(server_port, local_port, s_pkt.raw_sendable())
+        modem.transmit(svr_channel, plc_channel, s_pkt.raw_sendable())
         self.seq_num = self.seq_num + 1
     end
 
@@ -499,9 +500,9 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
         local m_pkt = comms.mgmt_packet()
 
         m_pkt.make(msg_type, msg)
-        s_pkt.make(self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
+        s_pkt.make(self.sv_addr, self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
 
-        modem.transmit(server_port, local_port, s_pkt.raw_sendable())
+        modem.transmit(svr_channel, plc_channel, s_pkt.raw_sendable())
         self.seq_num = self.seq_num + 1
     end
 
@@ -667,9 +668,11 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
 
     -- unlink from the server
     function public.unlink()
+        self.sv_addr = comms.BROADCAST
         self.linked = false
         self.r_seq_num = nil
         self.status_cache = nil
+        databus.tx_link_state(types.PANEL_LINK_STATE.DISCONNECTED)
     end
 
     -- close the connection to the server
@@ -731,7 +734,7 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
         end
     end
 
-    -- parse an RPLC packet
+    -- parse a packet
     ---@nodiscard
     ---@param side string
     ---@param sender integer
@@ -760,14 +763,14 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                     pkt = mgmt_pkt.get()
                 end
             else
-                log.debug("illegal packet type " .. s_pkt.protocol(), true)
+                log.debug("unsupported packet type " .. s_pkt.protocol(), true)
             end
         end
 
         return pkt
     end
 
-    -- handle an RPLC packet
+    -- handle RPLC and MGMT packets
     ---@param packet rplc_frame|mgmt_frame packet frame
     ---@param plc_state plc_state PLC state
     ---@param setpoints setpoints setpoint control table
@@ -775,16 +778,22 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
         -- print a log message to the terminal as long as the UI isn't running
         local function println_ts(message) if not plc_state.fp_ok then util.println_ts(message) end end
 
-        local l_port = packet.scada_frame.local_port()
+        local protocol = packet.scada_frame.protocol()
+        local l_chan   = packet.scada_frame.local_channel()
+        local src_addr = packet.scada_frame.src_addr()
 
         -- handle packets now that we have prints setup
-        if l_port == local_port then
+        if l_chan == plc_channel then
             -- check sequence number
             if self.r_seq_num == nil then
                 self.r_seq_num = packet.scada_frame.seq_num()
             elseif self.linked and ((self.r_seq_num + 1) ~= packet.scada_frame.seq_num()) then
                 log.warning("sequence out-of-order: last = " .. self.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
                 return
+            elseif self.linked and (src_addr ~= self.sv_addr) then
+                log.debug("received packet from unknown computer " .. src_addr .. " while linked (expected " .. self.sv_addr ..
+                            "); channel in use by another system?")
+                return
             else
                 self.r_seq_num = packet.scada_frame.seq_num()
             end
@@ -792,11 +801,10 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
             -- feed the watchdog first so it doesn't uhh...eat our packets :)
             conn_watchdog.feed()
 
-            local protocol = packet.scada_frame.protocol()
-
             -- handle packet
             if protocol == PROTOCOL.RPLC then
                 ---@cast packet rplc_frame
+                -- if linked, only accept packets from configured supervisor
                 if self.linked then
                     if packet.type == RPLC_TYPE.STATUS then
                         -- request of full status, clear cache first
@@ -933,6 +941,7 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                 end
             elseif protocol == PROTOCOL.SCADA_MGMT then
                 ---@cast packet mgmt_frame
+                -- if linked, only accept packets from configured supervisor
                 if self.linked then
                     if packet.type == SCADA_MGMT_TYPE.ESTABLISH then
                         -- link request confirmation
@@ -945,22 +954,26 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                                 self.status_cache = nil
                                 _send_struct()
                                 public.send_status(plc_state.no_reactor, plc_state.reactor_formed)
-                                log.debug("re-sent initial status data")
-                            elseif est_ack == ESTABLISH_ACK.DENY then
-                                println_ts("received unsolicited link denial, unlinking")
-                                log.warning("unsolicited establish request denied")
-                            elseif est_ack == ESTABLISH_ACK.COLLISION then
-                                println_ts("received unsolicited link collision, unlinking")
-                                log.warning("unsolicited establish request collision")
-                            elseif est_ack == ESTABLISH_ACK.BAD_VERSION then
-                                println_ts("received unsolicited link version mismatch, unlinking")
-                                log.warning("unsolicited establish request version mismatch")
+                                log.debug("re-sent initial status data due to re-establish")
                             else
-                                println_ts("invalid unsolicited link response")
-                                log.debug("unsolicited unknown establish request response")
-                            end
+                                if est_ack == ESTABLISH_ACK.DENY then
+                                    println_ts("received unsolicited link denial, unlinking")
+                                    log.warning("unsolicited establish request denied")
+                                elseif est_ack == ESTABLISH_ACK.COLLISION then
+                                    println_ts("received unsolicited link collision, unlinking")
+                                    log.warning("unsolicited establish request collision")
+                                elseif est_ack == ESTABLISH_ACK.BAD_VERSION then
+                                    println_ts("received unsolicited link version mismatch, unlinking")
+                                    log.warning("unsolicited establish request version mismatch")
+                                else
+                                    println_ts("invalid unsolicited link response")
+                                    log.debug("unsolicited unknown establish request response")
+                                end
 
-                            self.linked = est_ack == ESTABLISH_ACK.ALLOW
+                                -- unlink
+                                self.sv_addr = comms.BROADCAST
+                                self.linked = false
+                            end
 
                             -- clear this since this is for something that was unsolicited
                             self.last_est_ack = ESTABLISH_ACK.ALLOW
@@ -980,7 +993,7 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                                 log.warning("PLC KEEP_ALIVE trip time > 750ms (" .. trip_time .. "ms)")
                             end
 
-                            -- log.debug("RPLC RTT = " .. trip_time .. "ms")
+                            -- log.debug("PLC RTT = " .. trip_time .. "ms")
 
                             _send_keep_alive_ack(timestamp)
                         else
@@ -1002,9 +1015,11 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
 
                         if est_ack == ESTABLISH_ACK.ALLOW then
                             println_ts("linked!")
-                            log.info("supervisor establish request approved, PLC is linked")
+                            log.info("supervisor establish request approved, linked to SV (CID#" .. src_addr .. ")")
 
-                            -- reset remote sequence number and cache
+                            -- link + reset remote sequence number and cache
+                            self.sv_addr = src_addr
+                            self.linked = true
                             self.r_seq_num = nil
                             self.status_cache = nil
 
@@ -1012,23 +1027,28 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                             public.send_status(plc_state.no_reactor, plc_state.reactor_formed)
 
                             log.debug("sent initial status data")
-                        elseif self.last_est_ack ~= est_ack then
-                            if est_ack == ESTABLISH_ACK.DENY then
-                                println_ts("link request denied, retrying...")
-                                log.info("supervisor establish request denied, retrying")
-                            elseif est_ack == ESTABLISH_ACK.COLLISION then
-                                println_ts("reactor PLC ID collision (check config), retrying...")
-                                log.warning("establish request collision, retrying")
-                            elseif est_ack == ESTABLISH_ACK.BAD_VERSION then
-                                println_ts("supervisor version mismatch (try updating), retrying...")
-                                log.warning("establish request version mismatch, retrying")
-                            else
-                                println_ts("invalid link response, bad channel? retrying...")
-                                log.error("unknown establish request response, retrying")
+                        else
+                            if self.last_est_ack ~= est_ack then
+                                if est_ack == ESTABLISH_ACK.DENY then
+                                    println_ts("link request denied, retrying...")
+                                    log.info("supervisor establish request denied, retrying")
+                                elseif est_ack == ESTABLISH_ACK.COLLISION then
+                                    println_ts("reactor PLC ID collision (check config), retrying...")
+                                    log.warning("establish request collision, retrying")
+                                elseif est_ack == ESTABLISH_ACK.BAD_VERSION then
+                                    println_ts("supervisor version mismatch (try updating), retrying...")
+                                    log.warning("establish request version mismatch, retrying")
+                                else
+                                    println_ts("invalid link response, bad channel? retrying...")
+                                    log.error("unknown establish request response, retrying")
+                                end
                             end
+
+                            -- unlink
+                            self.sv_addr = comms.BROADCAST
+                            self.linked = false
                         end
 
-                        self.linked = est_ack == ESTABLISH_ACK.ALLOW
                         self.last_est_ack = est_ack
 
                         -- report link state
@@ -1044,7 +1064,7 @@ function plc.comms(id, version, modem, local_port, server_port, range, reactor,
                 log.error("illegal packet type " .. protocol, true)
             end
         else
-            log.debug("received packet on unconfigured channel " .. l_port, true)
+            log.debug("received packet on unconfigured channel " .. l_chan, true)
         end
     end
 

reactor-plc/renderer.lua

@@ -44,10 +44,8 @@ function renderer.close_ui()
         -- stop blinking indicators
         flasher.clear()
 
-        -- hide to stop animation callbacks
-        ui.display.hide()
-
-        -- clear root UI elements
+        -- delete element tree
+        ui.display.delete()
         ui.display = nil
 
         -- restore colors
@@ -70,9 +68,9 @@ end
 function renderer.ui_ready() return ui.display ~= nil end
 
 -- handle a mouse event
----@param event mouse_interaction
+---@param event mouse_interaction|nil
 function renderer.handle_mouse(event)
-    if ui.display ~= nil then
+    if ui.display ~= nil and event ~= nil then
         ui.display.handle_mouse(event)
     end
 end

reactor-plc/startup.lua

@@ -18,7 +18,7 @@ local plc      = require("reactor-plc.plc")
 local renderer = require("reactor-plc.renderer")
 local threads  = require("reactor-plc.threads")
 
-local R_PLC_VERSION = "v1.1.17"
+local R_PLC_VERSION = "v1.4.6"
 
 local println = util.println
 local println_ts = util.println_ts
@@ -31,8 +31,8 @@ local cfv = util.new_validator()
 
 cfv.assert_type_bool(config.NETWORKED)
 cfv.assert_type_int(config.REACTOR_ID)
-cfv.assert_port(config.SERVER_PORT)
-cfv.assert_port(config.LISTEN_PORT)
+cfv.assert_channel(config.SVR_CHANNEL)
+cfv.assert_channel(config.PLC_CHANNEL)
 cfv.assert_type_int(config.TRUSTED_RANGE)
 cfv.assert_type_num(config.COMMS_TIMEOUT)
 cfv.assert_min(config.COMMS_TIMEOUT, 2)
@@ -54,7 +54,7 @@ end
 -- log init
 ----------------------------------------
 
-log.init(config.LOG_PATH, config.LOG_MODE)
+log.init(config.LOG_PATH, config.LOG_MODE, config.LOG_DEBUG == true)
 
 log.info("========================================")
 log.info("BOOTING reactor-plc.startup " .. R_PLC_VERSION)
@@ -197,7 +197,7 @@ local function main()
                 log.debug("init> conn watchdog started")
 
                 -- start comms
-                smem_sys.plc_comms = plc.comms(config.REACTOR_ID, R_PLC_VERSION, smem_dev.modem, config.LISTEN_PORT, config.SERVER_PORT,
+                smem_sys.plc_comms = plc.comms(config.REACTOR_ID, R_PLC_VERSION, smem_dev.modem, config.PLC_CHANNEL, config.SVR_CHANNEL,
                                                 config.TRUSTED_RANGE, smem_dev.reactor, smem_sys.rps, smem_sys.conn_watchdog)
                 log.debug("init> comms init")
             else

reactor-plc/threads.lua

@@ -1,13 +1,13 @@
-local log          = require("scada-common.log")
-local mqueue       = require("scada-common.mqueue")
-local ppm          = require("scada-common.ppm")
-local tcallbackdsp = require("scada-common.tcallbackdsp")
-local util         = require("scada-common.util")
+local log      = require("scada-common.log")
+local mqueue   = require("scada-common.mqueue")
+local ppm      = require("scada-common.ppm")
+local tcd      = require("scada-common.tcd")
+local util     = require("scada-common.util")
 
-local databus      = require("reactor-plc.databus")
-local renderer     = require("reactor-plc.renderer")
+local databus  = require("reactor-plc.databus")
+local renderer = require("reactor-plc.renderer")
 
-local core         = require("graphics.core")
+local core     = require("graphics.core")
 
 local threads = {}
 
@@ -157,7 +157,7 @@ function threads.thread__main(smem, init)
                 smem.q.mq_rps.push_command(MQ__RPS_CMD.TRIP_TIMEOUT)
             elseif event == "timer" then
                 -- notify timer callback dispatcher if no other timer case claimed this event
-                tcallbackdsp.handle(param1)
+                tcd.handle(param1)
             elseif event == "peripheral_detach" then
                 -- peripheral disconnect
                 local type, device = ppm.handle_unmount(param1)
@@ -257,9 +257,9 @@ function threads.thread__main(smem, init)
 
                 -- update indicators
                 databus.tx_hw_status(plc_state)
-            elseif event == "mouse_click" then
-                -- handle a monitor touch event
-                renderer.handle_mouse(core.events.click(param1, param2, param3))
+            elseif event == "mouse_click" or event == "mouse_up" or event == "mouse_drag" or event == "mouse_scroll" then
+                -- handle a mouse event
+                renderer.handle_mouse(core.events.new_mouse_event(event, param1, param2, param3))
             elseif event == "clock_start" then
                 -- start loop clock
                 loop_clock.start()

rtu/config.lua

@@ -2,11 +2,11 @@ local rsio = require("scada-common.rsio")
 
 local config = {}
 
--- port to send packets TO server
-config.SERVER_PORT = 16000
--- port to listen to incoming packets FROM server
-config.LISTEN_PORT = 15001
--- max trusted modem message distance (< 1 to disable check)
+-- supervisor comms channel
+config.SVR_CHANNEL = 16240
+-- RTU/MODBUS comms channel
+config.RTU_CHANNEL = 16242
+-- max trusted modem message distance (0 to disable check)
 config.TRUSTED_RANGE = 0
 -- time in seconds (>= 2) before assuming a remote device is no longer active
 config.COMMS_TIMEOUT = 5
@@ -17,6 +17,8 @@ config.LOG_PATH = "/log.txt"
 --  0 = APPEND (adds to existing file on start)
 --  1 = NEW (replaces existing file on start)
 config.LOG_MODE = 0
+-- true to log verbose debug messages
+config.LOG_DEBUG = false
 
 -- RTU peripheral devices (named: side/network device name)
 config.RTU_DEVICES = {

rtu/databus.lua

@@ -7,9 +7,8 @@ local util = require("scada-common.util")
 
 local databus = {}
 
-local dbus_iface = {
-    ps = psil.create()
-}
+-- databus PSIL
+databus.ps = psil.create()
 
 ---@enum RTU_UNIT_HW_STATE
 local RTU_UNIT_HW_STATE = {
@@ -22,54 +21,54 @@ local RTU_UNIT_HW_STATE = {
 databus.RTU_UNIT_HW_STATE = RTU_UNIT_HW_STATE
 
 -- call to toggle heartbeat signal
-function databus.heartbeat() dbus_iface.ps.toggle("heartbeat") end
+function databus.heartbeat() databus.ps.toggle("heartbeat") end
 
 -- transmit firmware versions across the bus
 ---@param rtu_v string RTU version
 ---@param comms_v string comms version
 function databus.tx_versions(rtu_v, comms_v)
-    dbus_iface.ps.publish("version", rtu_v)
-    dbus_iface.ps.publish("comms_version", comms_v)
+    databus.ps.publish("version", rtu_v)
+    databus.ps.publish("comms_version", comms_v)
 end
 
 -- transmit hardware status for modem connection state
 ---@param has_modem boolean
 function databus.tx_hw_modem(has_modem)
-    dbus_iface.ps.publish("has_modem", has_modem)
+    databus.ps.publish("has_modem", has_modem)
 end
 
 -- transmit unit hardware type across the bus
 ---@param uid integer unit ID
 ---@param type RTU_UNIT_TYPE
 function databus.tx_unit_hw_type(uid, type)
-    dbus_iface.ps.publish("unit_type_" .. uid, type)
+    databus.ps.publish("unit_type_" .. uid, type)
 end
 
 -- transmit unit hardware status across the bus
 ---@param uid integer unit ID
 ---@param status RTU_UNIT_HW_STATE
 function databus.tx_unit_hw_status(uid, status)
-    dbus_iface.ps.publish("unit_hw_" .. uid, status)
+    databus.ps.publish("unit_hw_" .. uid, status)
 end
 
 -- transmit thread (routine) statuses
 ---@param thread string thread name
 ---@param ok boolean thread state
 function databus.tx_rt_status(thread, ok)
-    dbus_iface.ps.publish(util.c("routine__", thread), ok)
+    databus.ps.publish(util.c("routine__", thread), ok)
 end
 
 -- transmit supervisor link state across the bus
 ---@param state integer
 function databus.tx_link_state(state)
-    dbus_iface.ps.publish("link_state", state)
+    databus.ps.publish("link_state", state)
 end
 
 -- link a function to receive data from the bus
 ---@param field string field name
 ---@param func function function to link
 function databus.rx_field(field, func)
-    dbus_iface.ps.subscribe(field, func)
+    databus.ps.subscribe(field, func)
 end
 
 return databus

rtu/panel/front_panel.lua

@@ -2,6 +2,7 @@
 -- Main SCADA Coordinator GUI
 --
 
+local types      = require("scada-common.types")
 local util       = require("scada-common.util")
 
 local databus    = require("rtu.databus")
@@ -16,9 +17,9 @@ local TextBox    = require("graphics.elements.textbox")
 local LED        = require("graphics.elements.indicators.led")
 local RGBLED     = require("graphics.elements.indicators.ledrgb")
 
-local TEXT_ALIGN = core.graphics.TEXT_ALIGN
+local TEXT_ALIGN = core.TEXT_ALIGN
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 local UNIT_TYPE_LABELS = {
     "UNKNOWN",
@@ -44,27 +45,31 @@ local function init(panel, units)
 
     local system = Div{parent=panel,width=14,height=18,x=2,y=3}
 
-    local on = LED{parent=system,label="POWER",colors=cpair(colors.green,colors.red)}
+    local on = LED{parent=system,label="STATUS",colors=cpair(colors.green,colors.red)}
     local heartbeat = LED{parent=system,label="HEARTBEAT",colors=cpair(colors.green,colors.green_off)}
     on.update(true)
     system.line_break()
 
-    databus.rx_field("heartbeat", heartbeat.update)
+    heartbeat.register(databus.ps, "heartbeat", heartbeat.update)
 
     local modem = LED{parent=system,label="MODEM",colors=cpair(colors.green,colors.green_off)}
     local network = RGBLED{parent=system,label="NETWORK",colors={colors.green,colors.red,colors.orange,colors.yellow,colors.gray}}
-    network.update(5)
+    network.update(types.PANEL_LINK_STATE.DISCONNECTED)
     system.line_break()
 
-    databus.rx_field("has_modem", modem.update)
-    databus.rx_field("link_state", network.update)
+    modem.register(databus.ps, "has_modem", modem.update)
+    network.register(databus.ps, "link_state", network.update)
 
     local rt_main = LED{parent=system,label="RT MAIN",colors=cpair(colors.green,colors.green_off)}
     local rt_comm = LED{parent=system,label="RT COMMS",colors=cpair(colors.green,colors.green_off)}
     system.line_break()
 
-    databus.rx_field("routine__main", rt_main.update)
-    databus.rx_field("routine__comms", rt_comm.update)
+    rt_main.register(databus.ps, "routine__main", rt_main.update)
+    rt_comm.register(databus.ps, "routine__comms", rt_comm.update)
+
+---@diagnostic disable-next-line: undefined-field
+    local comp_id = util.sprintf("(%d)", os.getComputerID())
+    TextBox{parent=system,x=9,y=4,width=6,height=1,text=comp_id,fg_bg=cpair(colors.lightGray,colors.ivory)}
 
     --
     -- about label
@@ -74,8 +79,8 @@ local function init(panel, units)
     local fw_v    = TextBox{parent=about,x=1,y=1,text="FW: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
     local comms_v = TextBox{parent=about,x=1,y=2,text="NT: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
 
-    databus.rx_field("version", function (version) fw_v.set_value(util.c("FW: ", version)) end)
-    databus.rx_field("comms_version", function (version) comms_v.set_value(util.c("NT: v", version)) end)
+    fw_v.register(databus.ps, "version", function (version) fw_v.set_value(util.c("FW: ", version)) end)
+    comms_v.register(databus.ps, "comms_version", function (version) comms_v.set_value(util.c("NT: v", version)) end)
 
     --
     -- unit status list
@@ -90,7 +95,7 @@ local function init(panel, units)
     for i = 1, list_length do
         TextBox{parent=threads,x=1,y=i,text=util.sprintf("%02d",i),height=1}
         local rt_unit = LED{parent=threads,x=4,y=i,label="RT",colors=cpair(colors.green,colors.green_off)}
-        databus.rx_field("routine__unit_" .. i, rt_unit.update)
+        rt_unit.register(databus.ps, "routine__unit_" .. i, rt_unit.update)
     end
 
     local unit_hw_statuses = Div{parent=panel,height=18,x=25,y=3}
@@ -102,13 +107,13 @@ local function init(panel, units)
         -- hardware status
         local unit_hw = RGBLED{parent=unit_hw_statuses,y=i,label="",colors={colors.red,colors.orange,colors.yellow,colors.green}}
 
-        databus.rx_field("unit_hw_" .. i, unit_hw.update)
+        unit_hw.register(databus.ps, "unit_hw_" .. i, unit_hw.update)
 
         -- unit name identifier (type + index)
         local name = util.c(UNIT_TYPE_LABELS[unit.type + 1], " ", unit.index)
         local name_box = TextBox{parent=unit_hw_statuses,y=i,x=3,text=name,height=1}
 
-        databus.rx_field("unit_type_" .. i, function (t)
+        name_box.register(databus.ps, "unit_type_" .. i, function (t)
             name_box.set_value(util.c(UNIT_TYPE_LABELS[t + 1], " ", unit.index))
         end)
 

rtu/panel/style.lua

@@ -6,7 +6,7 @@ local core = require("graphics.core")
 
 local style = {}
 
-local cpair = core.graphics.cpair
+local cpair = core.cpair
 
 -- GLOBAL --
 

rtu/renderer.lua

@@ -45,10 +45,8 @@ function renderer.close_ui()
         -- stop blinking indicators
         flasher.clear()
 
-        -- hide to stop animation callbacks
-        ui.display.hide()
-
-        -- clear root UI elements
+        -- delete element tree
+        ui.display.delete()
         ui.display = nil
 
         -- restore colors
@@ -71,9 +69,9 @@ end
 function renderer.ui_ready() return ui.display ~= nil end
 
 -- handle a mouse event
----@param event mouse_interaction
+---@param event mouse_interaction|nil
 function renderer.handle_mouse(event)
-    if ui.display ~= nil then
+    if ui.display ~= nil and event ~= nil then
         ui.display.handle_mouse(event)
     end
 end

rtu/rtu.lua

@@ -159,12 +159,13 @@ end
 ---@nodiscard
 ---@param version string RTU version
 ---@param modem table modem device
----@param local_port integer local listening port
----@param server_port integer remote server port
+---@param rtu_channel integer PLC comms channel
+---@param svr_channel integer supervisor server channel
 ---@param range integer trusted device connection range
 ---@param conn_watchdog watchdog watchdog reference
-function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog)
+function rtu.comms(version, modem, rtu_channel, svr_channel, range, conn_watchdog)
     local self = {
+        sv_addr = comms.BROADCAST,
         seq_num = 0,
         r_seq_num = nil,
         txn_id = 0,
@@ -180,7 +181,7 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
     -- configure modem channels
     local function _conf_channels()
         modem.closeAll()
-        modem.open(local_port)
+        modem.open(rtu_channel)
     end
 
     _conf_channels()
@@ -193,9 +194,9 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
         local m_pkt = comms.mgmt_packet()
 
         m_pkt.make(msg_type, msg)
-        s_pkt.make(self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
+        s_pkt.make(self.sv_addr, self.seq_num, PROTOCOL.SCADA_MGMT, m_pkt.raw_sendable())
 
-        modem.transmit(server_port, local_port, s_pkt.raw_sendable())
+        modem.transmit(svr_channel, rtu_channel, s_pkt.raw_sendable())
         self.seq_num = self.seq_num + 1
     end
 
@@ -238,8 +239,8 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
     ---@param m_pkt modbus_packet
     function public.send_modbus(m_pkt)
         local s_pkt = comms.scada_packet()
-        s_pkt.make(self.seq_num, PROTOCOL.MODBUS_TCP, m_pkt.raw_sendable())
-        modem.transmit(server_port, local_port, s_pkt.raw_sendable())
+        s_pkt.make(self.sv_addr, self.seq_num, PROTOCOL.MODBUS_TCP, m_pkt.raw_sendable())
+        modem.transmit(svr_channel, rtu_channel, s_pkt.raw_sendable())
         self.seq_num = self.seq_num + 1
     end
 
@@ -254,7 +255,9 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
     ---@param rtu_state rtu_state
     function public.unlink(rtu_state)
         rtu_state.linked = false
+        self.sv_addr = comms.BROADCAST
         self.r_seq_num = nil
+        databus.tx_link_state(types.PANEL_LINK_STATE.DISCONNECTED)
     end
 
     -- close the connection to the server
@@ -327,13 +330,21 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
         -- print a log message to the terminal as long as the UI isn't running
         local function println_ts(message) if not rtu_state.fp_ok then util.println_ts(message) end end
 
-        if packet.scada_frame.local_port() == local_port then
+        local protocol = packet.scada_frame.protocol()
+        local l_chan   = packet.scada_frame.local_channel()
+        local src_addr = packet.scada_frame.src_addr()
+
+        if l_chan == rtu_channel then
             -- check sequence number
             if self.r_seq_num == nil then
                 self.r_seq_num = packet.scada_frame.seq_num()
             elseif rtu_state.linked and ((self.r_seq_num + 1) ~= packet.scada_frame.seq_num()) then
                 log.warning("sequence out-of-order: last = " .. self.r_seq_num .. ", new = " .. packet.scada_frame.seq_num())
                 return
+            elseif rtu_state.linked and (src_addr ~= self.sv_addr) then
+                log.debug("received packet from unknown computer " .. src_addr .. " while linked (expected " .. self.sv_addr ..
+                            "); channel in use by another system?")
+                return
             else
                 self.r_seq_num = packet.scada_frame.seq_num()
             end
@@ -341,8 +352,7 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
             -- feed watchdog on valid sequence number
             conn_watchdog.feed()
 
-            local protocol = packet.scada_frame.protocol()
-
+            -- handle packet
             if protocol == PROTOCOL.MODBUS_TCP then
                 ---@cast packet modbus_frame
                 if rtu_state.linked then
@@ -398,6 +408,7 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
                         if est_ack == ESTABLISH_ACK.ALLOW then
                             -- establish allowed
                             rtu_state.linked = true
+                            self.sv_addr = packet.scada_frame.src_addr()
                             self.r_seq_num = nil
                             println_ts("supervisor connection established")
                             log.info("supervisor connection established")
@@ -461,6 +472,8 @@ function rtu.comms(version, modem, local_port, server_port, range, conn_watchdog
                 -- should be unreachable assuming packet is from parse_packet()
                 log.error("illegal packet type " .. protocol, true)
             end
+        else
+            log.debug("received packet on unconfigured channel " .. l_chan, true)
         end
     end
 

rtu/startup.lua

@@ -28,7 +28,7 @@ local sna_rtu      = require("rtu.dev.sna_rtu")
 local sps_rtu      = require("rtu.dev.sps_rtu")
 local turbinev_rtu = require("rtu.dev.turbinev_rtu")
 
-local RTU_VERSION = "v1.0.5"
+local RTU_VERSION = "v1.3.6"
 
 local RTU_UNIT_TYPE = types.RTU_UNIT_TYPE
 local RTU_UNIT_HW_STATE = databus.RTU_UNIT_HW_STATE
@@ -42,8 +42,8 @@ local println_ts = util.println_ts
 
 local cfv = util.new_validator()
 
-cfv.assert_port(config.SERVER_PORT)
-cfv.assert_port(config.LISTEN_PORT)
+cfv.assert_channel(config.SVR_CHANNEL)
+cfv.assert_channel(config.RTU_CHANNEL)
 cfv.assert_type_int(config.TRUSTED_RANGE)
 cfv.assert_type_num(config.COMMS_TIMEOUT)
 cfv.assert_min(config.COMMS_TIMEOUT, 2)
@@ -57,7 +57,7 @@ assert(cfv.valid(), "bad config file: missing/invalid fields")
 -- log init
 ----------------------------------------
 
-log.init(config.LOG_PATH, config.LOG_MODE)
+log.init(config.LOG_PATH, config.LOG_MODE, config.LOG_DEBUG == true)
 
 log.info("========================================")
 log.info("BOOTING rtu.startup " .. RTU_VERSION)
@@ -457,9 +457,9 @@ local function main()
         if not rtu_state.fp_ok then
             renderer.close_ui()
             println_ts(util.c("UI error: ", message))
-            println("init> running without front panel")
+            println("startup> running without front panel")
             log.error(util.c("GUI crashed with error ", message))
-            log.info("init> running in headless mode without front panel")
+            log.info("startup> running in headless mode without front panel")
         end
 
         -- start connection watchdog
@@ -467,7 +467,7 @@ local function main()
         log.debug("startup> conn watchdog started")
 
         -- setup comms
-        smem_sys.rtu_comms = rtu.comms(RTU_VERSION, smem_dev.modem, config.LISTEN_PORT, config.SERVER_PORT,
+        smem_sys.rtu_comms = rtu.comms(RTU_VERSION, smem_dev.modem, config.RTU_CHANNEL, config.SVR_CHANNEL,
                                         config.TRUSTED_RANGE, smem_sys.conn_watchdog)
         log.debug("startup> comms init")
 

rtu/threads.lua

@@ -1,6 +1,7 @@
 local log          = require("scada-common.log")
 local mqueue       = require("scada-common.mqueue")
 local ppm          = require("scada-common.ppm")
+local tcd          = require("scada-common.tcd")
 local types        = require("scada-common.types")
 local util         = require("scada-common.util")
 
@@ -82,6 +83,9 @@ function threads.thread__main(smem)
             elseif event == "timer" and conn_watchdog.is_timer(param1) then
                 -- haven't heard from server recently? unlink
                 rtu_comms.unlink(rtu_state)
+            elseif event == "timer" then
+                -- notify timer callback dispatcher if no other timer case claimed this event
+                tcd.handle(param1)
             elseif event == "peripheral_detach" then
                 -- handle loss of a device
                 local type, device = ppm.handle_unmount(param1)
@@ -229,9 +233,9 @@ function threads.thread__main(smem)
                         end
                     end
                 end
-            elseif event == "mouse_click" then
-                -- handle a monitor touch event
-                renderer.handle_mouse(core.events.click(param1, param2, param3))
+            elseif event == "mouse_click" or event == "mouse_up" or event == "mouse_drag" or event == "mouse_scroll" then
+                -- handle a mouse event
+                renderer.handle_mouse(core.events.new_mouse_event(event, param1, param2, param3))
             end
 
             -- check for termination request

scada-common/comms.lua

@@ -4,14 +4,17 @@
 
 local log = require("scada-common.log")
 
+local insert = table.insert
+
+---@diagnostic disable-next-line: undefined-field
+local C_ID = os.getComputerID() ---@type integer computer ID
+
+local max_distance = nil        ---@type number|nil maximum acceptable transmission distance
+
 ---@class comms
 local comms = {}
 
-local insert = table.insert
-
-local max_distance = nil
-
-comms.version = "1.4.1"
+comms.version = "2.0.0"
 
 ---@enum PROTOCOL
 local PROTOCOL = {
@@ -122,27 +125,28 @@ comms.PLC_AUTO_ACK = PLC_AUTO_ACK
 comms.UNIT_COMMAND = UNIT_COMMAND
 comms.FAC_COMMAND = FAC_COMMAND
 
+-- destination broadcast address (to all devices)
+comms.BROADCAST = -1
+
 ---@alias packet scada_packet|modbus_packet|rplc_packet|mgmt_packet|crdn_packet|capi_packet
 ---@alias frame modbus_frame|rplc_frame|mgmt_frame|crdn_frame|capi_frame
 
 -- configure the maximum allowable message receive distance<br>
 -- packets received with distances greater than this will be silently discarded
----@param distance integer max modem message distance (less than 1 disables the limit)
+---@param distance integer max modem message distance (0 disables the limit)
 function comms.set_trusted_range(distance)
-    if distance < 1 then
-        max_distance = nil
-    else
-        max_distance = distance
-    end
+    if distance == 0 then max_distance = nil else max_distance = distance end
 end
 
 -- generic SCADA packet object
 ---@nodiscard
 function comms.scada_packet()
     local self = {
-        modem_msg_in = nil,
+        modem_msg_in = nil, ---@type modem_message|nil
         valid = false,
-        raw = { -1, PROTOCOL.SCADA_MGMT, {} },
+        raw = {},
+        src_addr = comms.BROADCAST,
+        dest_addr = comms.BROADCAST,
         seq_num = -1,
         protocol = PROTOCOL.SCADA_MGMT,
         length = 0,
@@ -153,34 +157,40 @@ function comms.scada_packet()
     local public = {}
 
     -- make a SCADA packet
-    ---@param seq_num integer
+    ---@param dest_addr integer destination computer address (ID)
+    ---@param seq_num integer sequence number
     ---@param protocol PROTOCOL
     ---@param payload table
-    function public.make(seq_num, protocol, payload)
+    function public.make(dest_addr, seq_num, protocol, payload)
         self.valid = true
+---@diagnostic disable-next-line: undefined-field
+        self.src_addr = C_ID
+        self.dest_addr = dest_addr
         self.seq_num = seq_num
         self.protocol = protocol
         self.length = #payload
         self.payload = payload
-        self.raw = { self.seq_num, self.protocol, self.payload }
+        self.raw = { self.src_addr, self.dest_addr, self.seq_num, self.protocol, self.payload }
     end
 
     -- parse in a modem message as a SCADA packet
     ---@param side string modem side
-    ---@param sender integer sender port
-    ---@param reply_to integer reply port
+    ---@param sender integer sender channel
+    ---@param reply_to integer reply channel
     ---@param message any message body
     ---@param distance integer transmission distance
     ---@return boolean valid valid message received
     function public.receive(side, sender, reply_to, message, distance)
+        ---@class modem_message
         self.modem_msg_in = {
             iface = side,
-            s_port = sender,
-            r_port = reply_to,
+            s_channel = sender,
+            r_channel = reply_to,
             msg = message,
             dist = distance
         }
 
+        self.valid = false
         self.raw = self.modem_msg_in.msg
 
         if (type(max_distance) == "number") and (distance > max_distance) then
@@ -188,20 +198,31 @@ function comms.scada_packet()
             -- log.debug("comms.scada_packet.receive(): discarding packet with distance " .. distance .. " outside of trusted range")
         else
             if type(self.raw) == "table" then
-                if #self.raw >= 3 then
-                    self.seq_num = self.raw[1]
-                    self.protocol = self.raw[2]
+                if #self.raw == 5 then
+                    self.src_addr = self.raw[1]
+                    self.dest_addr = self.raw[2]
+                    self.seq_num = self.raw[3]
+                    self.protocol = self.raw[4]
 
-                    -- element 3 must be a table
-                    if type(self.raw[3]) == "table" then
-                        self.length = #self.raw[3]
-                        self.payload = self.raw[3]
+                    -- element 5 must be a table
+                    if type(self.raw[5]) == "table" then
+                        self.length = #self.raw[5]
+                        self.payload = self.raw[5]
                     end
+                else
+                    self.src_addr = nil
+                    self.dest_addr = nil
+                    self.seq_num = nil
+                    self.protocol = nil
+                    self.length = 0
+                    self.payload = {}
                 end
 
-                self.valid = type(self.seq_num) == "number" and
-                             type(self.protocol) == "number" and
-                             type(self.payload) == "table"
+                -- check if this packet is destined for this device
+                local is_destination = (self.dest_addr == comms.BROADCAST) or (self.dest_addr == C_ID)
+
+                self.valid = is_destination and type(self.src_addr) == "number" and type(self.dest_addr) == "number" and
+                             type(self.seq_num) == "number" and type(self.protocol) == "number" and type(self.payload) == "table"
             end
         end
 
@@ -216,13 +237,17 @@ function comms.scada_packet()
     function public.raw_sendable() return self.raw end
 
     ---@nodiscard
-    function public.local_port() return self.modem_msg_in.s_port end
+    function public.local_channel() return self.modem_msg_in.s_channel end
     ---@nodiscard
-    function public.remote_port() return self.modem_msg_in.r_port end
+    function public.remote_channel() return self.modem_msg_in.r_channel end
 
     ---@nodiscard
     function public.is_valid() return self.valid end
 
+    ---@nodiscard
+    function public.src_addr() return self.src_addr end
+    ---@nodiscard
+    function public.dest_addr() return self.dest_addr end
     ---@nodiscard
     function public.seq_num() return self.seq_num end
     ---@nodiscard

scada-common/log.lua

@@ -15,12 +15,10 @@ local MODE = {
 
 log.MODE = MODE
 
--- whether to log debug messages or not
-local LOG_DEBUG = true
-
-local log_sys = {
+local logger = {
     path = "/log.txt",
     mode = MODE.APPEND,
+    debug = false,
     file = nil,
     dmesg_out = nil
 }
@@ -41,8 +39,8 @@ local function _log(msg)
 
     -- attempt to write log
     local status, result = pcall(function ()
-        log_sys.file.writeLine(stamped)
-        log_sys.file.flush()
+        logger.file.writeLine(stamped)
+        logger.file.flush()
     end)
 
     -- if we don't have space, we need to create a new log file
@@ -57,18 +55,18 @@ local function _log(msg)
         end
     end
 
-    if out_of_space or (free_space(log_sys.path) < 100) then
+    if out_of_space or (free_space(logger.path) < 100) then
         -- delete the old log file before opening a new one
-        log_sys.file.close()
-        fs.delete(log_sys.path)
+        logger.file.close()
+        fs.delete(logger.path)
 
         -- re-init logger and pass dmesg_out so that it doesn't change
-        log.init(log_sys.path, log_sys.mode, log_sys.dmesg_out)
+        log.init(logger.path, logger.mode, logger.debug, logger.dmesg_out)
 
         -- leave a message
-        log_sys.file.writeLine(time_stamp .. "recycled log file")
-        log_sys.file.writeLine(stamped)
-        log_sys.file.flush()
+        logger.file.writeLine(time_stamp .. "recycled log file")
+        logger.file.writeLine(stamped)
+        logger.file.flush()
     end
 end
 
@@ -78,33 +76,35 @@ end
 
 -- initialize logger
 ---@param path string file path
----@param write_mode MODE
+---@param write_mode MODE file write mode
+---@param include_debug boolean whether or not to include debug logs
 ---@param dmesg_redirect? table terminal/window to direct dmesg to
-function log.init(path, write_mode, dmesg_redirect)
-    log_sys.path = path
-    log_sys.mode = write_mode
+function log.init(path, write_mode, include_debug, dmesg_redirect)
+    logger.path = path
+    logger.mode = write_mode
+    logger.debug = include_debug
 
-    if log_sys.mode == MODE.APPEND then
-        log_sys.file = fs.open(path, "a")
+    if logger.mode == MODE.APPEND then
+        logger.file = fs.open(path, "a")
     else
-        log_sys.file = fs.open(path, "w")
+        logger.file = fs.open(path, "w")
     end
 
     if dmesg_redirect then
-        log_sys.dmesg_out = dmesg_redirect
+        logger.dmesg_out = dmesg_redirect
     else
-        log_sys.dmesg_out = term.current()
+        logger.dmesg_out = term.current()
     end
 end
 
 -- close the log file handle
 function log.close()
-    log_sys.file.close()
+    logger.file.close()
 end
 
 -- direct dmesg output to a monitor/window
 ---@param window table window or terminal reference
-function log.direct_dmesg(window) log_sys.dmesg_out = window end
+function log.direct_dmesg(window) logger.dmesg_out = window end
 
 -- dmesg style logging for boot because I like linux-y things
 ---@param msg string message
@@ -120,7 +120,7 @@ function log.dmesg(msg, tag, tag_color)
     tag = util.strval(tag)
 
     local t_stamp = string.format("%12.2f", os.clock())
-    local out = log_sys.dmesg_out
+    local out = logger.dmesg_out
 
     if out ~= nil then
         local out_w, out_h = out.getSize()
@@ -216,7 +216,7 @@ end
 function log.dmesg_working(msg, tag, tag_color)
     local ts_coord = log.dmesg(msg, tag, tag_color)
 
-    local out = log_sys.dmesg_out
+    local out = logger.dmesg_out
     local width = (ts_coord.x2 - ts_coord.x1) + 1
 
     if out ~= nil then
@@ -275,7 +275,7 @@ end
 ---@param msg string message
 ---@param trace? boolean include file trace
 function log.debug(msg, trace)
-    if LOG_DEBUG then
+    if logger.debug then
         local dbg_info = ""
 
         if trace then

scada-common/psil.lua

@@ -2,6 +2,8 @@
 -- Publisher-Subscriber Interconnect Layer
 --
 
+local util = require("scada-common.util")
+
 local psil = {}
 
 -- instantiate a new PSI layer
@@ -36,6 +38,15 @@ function psil.create()
         table.insert(self.ic[key].subscribers, { notify = func })
     end
 
+    -- unsubscribe a function from a given key
+    ---@param key string data key
+    ---@param func function function to unsubscribe
+    function public.unsubscribe(key, func)
+        if self.ic[key] ~= nil then
+            util.filter_table(self.ic[key].subscribers, function (s) return s.notify ~= func end)
+        end
+    end
+
     -- publish data to a given key, passing it to all subscribers if it has changed
     ---@param key string data key
     ---@param value any data value
@@ -64,6 +75,9 @@ function psil.create()
         end
     end
 
+    -- clear the contents of the interconnect
+    function public.purge() self.ic = nil end
+
     return public
 end
 

scada-common/tcd.lua

@@ -5,14 +5,14 @@
 local log  = require("scada-common.log")
 local util = require("scada-common.util")
 
-local tcallbackdsp = {}
+local tcd = {}
 
 local registry = {}
 
 -- request a function to be called after the specified time
 ---@param time number seconds
 ---@param f function callback function
-function tcallbackdsp.dispatch(time, f)
+function tcd.dispatch(time, f)
     local timer = util.start_timer(time)
     registry[timer] = {
         callback = f,
@@ -24,7 +24,7 @@ end
 -- request a function to be called after the specified time, aborting any registered instances of that function reference
 ---@param time number seconds
 ---@param f function callback function
-function tcallbackdsp.dispatch_unique(time, f)
+function tcd.dispatch_unique(time, f)
     -- cancel if already registered
     for timer, entry in pairs(registry) do
         if entry.callback == f then
@@ -47,7 +47,7 @@ end
 
 -- abort a requested callback
 ---@param f function callback function
-function tcallbackdsp.abort(f)
+function tcd.abort(f)
     for timer, entry in pairs(registry) do
         if entry.callback == f then
             -- cancel event and remove from registry (even if it fires it won't call)
@@ -59,7 +59,7 @@ end
 
 -- lookup a timer event and execute the callback if found
 ---@param event integer timer event timer ID
-function tcallbackdsp.handle(event)
+function tcd.handle(event)
     if registry[event] ~= nil then
         local callback = registry[event].callback
         -- clear first so that dispatch_unique call from inside callback won't throw a debug message
@@ -70,7 +70,7 @@ end
 
 -- identify any overdo callbacks<br>
 -- prints to log debug output
-function tcallbackdsp.diagnostics()
+function tcd.diagnostics()
     for timer, entry in pairs(registry) do
         if entry.expiry < util.time_s() then
             local overtime = util.time_s() - entry.expiry
@@ -82,4 +82,4 @@ function tcallbackdsp.diagnostics()
     end
 end
 
-return tcallbackdsp
+return tcd

scada-common/types.lua

@@ -39,6 +39,10 @@ function types.new_radiation_reading(r, u) return { radiation = r, unit = u } en
 ---@return radiation_reading
 function types.new_zero_radiation_reading() return { radiation = 0, unit = "nSv" } end
 
+---@class coordinate_2d
+---@field x integer
+---@field y integer
+
 ---@class coordinate
 ---@field x integer
 ---@field y integer
@@ -70,6 +74,15 @@ function types.new_zero_coordinate() return { x = 0, y = 0, z = 0 } end
 -- ENUMERATION TYPES --
 --#region
 
+---@enum PANEL_LINK_STATE
+types.PANEL_LINK_STATE = {
+    LINKED = 1,
+    DENIED = 2,
+    COLLISION = 3,
+    BAD_VERSION = 4,
+    DISCONNECTED = 5
+}
+
 ---@enum RTU_UNIT_TYPE
 types.RTU_UNIT_TYPE = {
     VIRTUAL = 0,        -- virtual device

scada-common/util.lua

@@ -65,7 +65,8 @@ end
 ---@return string
 function util.strval(val)
     local t = type(val)
-    if t == "table" or t == "function" then
+    -- this depends on Lua short-circuiting the or check for metatables (note: metatables won't have metatables)
+    if (t == "table" and (getmetatable(val) == nil or getmetatable(val).__tostring == nil)) or t == "function" then
         return "[" .. tostring(val) .. "]"
     else
         return tostring(val)
@@ -113,10 +114,13 @@ end
 ---@return table lines
 function util.strwrap(str, limit) return cc_strings.wrap(str, limit) end
 
+-- luacheck: no unused args
+
 -- concatenation with built-in to string
 ---@nodiscard
 ---@vararg any
 ---@return string
+---@diagnostic disable-next-line: unused-vararg
 function util.concat(...)
     local str = ""
     for _, v in ipairs(arg) do str = str .. util.strval(v) end
@@ -130,10 +134,13 @@ util.c = util.concat
 ---@nodiscard
 ---@param format string
 ---@vararg any
+---@diagnostic disable-next-line: unused-vararg
 function util.sprintf(format, ...)
     return string.format(format, table.unpack(arg))
 end
 
+-- luacheck: unused args
+
 -- format a number string with commas as the thousands separator<br>
 -- subtracts from spaces at the start if present for each comma used
 ---@nodiscard
@@ -533,7 +540,7 @@ function util.new_validator()
     function public.assert_range(check, min, max) valid = valid and check >= min and check <= max end
     function public.assert_range_ex(check, min, max) valid = valid and check > min and check < max end
 
-    function public.assert_port(port) valid = valid and type(port) == "number" and port >= 0 and port <= 65535 end
+    function public.assert_channel(channel) valid = valid and type(channel) == "number" and channel >= 0 and channel <= 65535 end
 
     -- check if all assertions passed successfully
     ---@nodiscard

supervisor/config.lua

@@ -1,9 +1,15 @@
 local config = {}
 
--- scada network listen for PLC's and RTU's
-config.SCADA_DEV_LISTEN = 16000
--- listen port for SCADA supervisor access
-config.SCADA_SV_CTL_LISTEN = 16100
+-- supervisor comms channel
+config.SVR_CHANNEL = 16240
+-- PLC comms channel
+config.PLC_CHANNEL = 16241
+-- RTU/MODBUS comms channel
+config.RTU_CHANNEL = 16242
+-- coordinator comms channel
+config.CRD_CHANNEL = 16243
+-- pocket comms channel
+config.PKT_CHANNEL = 16244
 -- max trusted modem message distance (0 to disable check)
 config.TRUSTED_RANGE = 0
 -- time in seconds (>= 2) before assuming a remote device is no longer active
@@ -28,5 +34,7 @@ config.LOG_PATH = "/log.txt"
 --  0 = APPEND (adds to existing file on start)
 --  1 = NEW (replaces existing file on start)
 config.LOG_MODE = 0
+-- true to log verbose debug messages
+config.LOG_DEBUG = false
 
 return config

supervisor/databus.lua

@@ -0,0 +1,179 @@
+--
+-- Data Bus - Central Communication Linking for Supervisor Front Panel
+--
+
+local psil = require("scada-common.psil")
+local util = require("scada-common.util")
+
+local pgi  = require("supervisor.panel.pgi")
+
+-- nominal RTT is ping (0ms to 10ms usually) + 150ms for SV main loop tick
+local WARN_RTT = 300    -- 2x as long as expected w/ 0 ping
+local HIGH_RTT = 500    -- 3.33x as long as expected w/ 0 ping
+
+local databus = {}
+
+-- databus PSIL
+databus.ps = psil.create()
+
+-- call to toggle heartbeat signal
+function databus.heartbeat() databus.ps.toggle("heartbeat") end
+
+-- transmit firmware versions across the bus
+---@param sv_v string supervisor version
+---@param comms_v string comms version
+function databus.tx_versions(sv_v, comms_v)
+    databus.ps.publish("version", sv_v)
+    databus.ps.publish("comms_version", comms_v)
+end
+
+-- transmit hardware status for modem connection state
+---@param has_modem boolean
+function databus.tx_hw_modem(has_modem)
+    databus.ps.publish("has_modem", has_modem)
+end
+
+-- transmit PLC firmware version and session connection state
+---@param reactor_id integer reactor unit ID
+---@param fw string firmware version
+---@param s_addr integer PLC computer ID
+function databus.tx_plc_connected(reactor_id, fw, s_addr)
+    databus.ps.publish("plc_" .. reactor_id .. "_fw", fw)
+    databus.ps.publish("plc_" .. reactor_id .. "_conn", true)
+    databus.ps.publish("plc_" .. reactor_id .. "_addr", util.sprintf("@% 4d", s_addr))
+end
+
+-- transmit PLC disconnected
+---@param reactor_id integer reactor unit ID
+function databus.tx_plc_disconnected(reactor_id)
+    databus.ps.publish("plc_" .. reactor_id .. "_fw", " ------- ")
+    databus.ps.publish("plc_" .. reactor_id .. "_conn", false)
+    databus.ps.publish("plc_" .. reactor_id .. "_addr", " --- ")
+    databus.ps.publish("plc_" .. reactor_id .. "_rtt", 0)
+    databus.ps.publish("plc_" .. reactor_id .. "_rtt_color", colors.lightGray)
+end
+
+-- transmit PLC session RTT
+---@param reactor_id integer reactor unit ID
+---@param rtt integer round trip time
+function databus.tx_plc_rtt(reactor_id, rtt)
+    databus.ps.publish("plc_" .. reactor_id .. "_rtt", rtt)
+
+    if rtt > HIGH_RTT then
+        databus.ps.publish("plc_" .. reactor_id .. "_rtt_color", colors.red)
+    elseif rtt > WARN_RTT then
+        databus.ps.publish("plc_" .. reactor_id .. "_rtt_color", colors.yellow_hc)
+    else
+        databus.ps.publish("plc_" .. reactor_id .. "_rtt_color", colors.green)
+    end
+end
+
+-- transmit RTU firmware version and session connection state
+---@param session_id integer RTU session
+---@param fw string firmware version
+---@param s_addr integer RTU computer ID
+function databus.tx_rtu_connected(session_id, fw, s_addr)
+    databus.ps.publish("rtu_" .. session_id .. "_fw", fw)
+    databus.ps.publish("rtu_" .. session_id .. "_addr", util.sprintf("@ C% 3d", s_addr))
+    pgi.create_rtu_entry(session_id)
+end
+
+-- transmit RTU disconnected
+---@param session_id integer RTU session
+function databus.tx_rtu_disconnected(session_id)
+    pgi.delete_rtu_entry(session_id)
+end
+
+-- transmit RTU session RTT
+---@param session_id integer RTU session
+---@param rtt integer round trip time
+function databus.tx_rtu_rtt(session_id, rtt)
+    databus.ps.publish("rtu_" .. session_id .. "_rtt", rtt)
+
+    if rtt > HIGH_RTT then
+        databus.ps.publish("rtu_" .. session_id .. "_rtt_color", colors.red)
+    elseif rtt > WARN_RTT then
+        databus.ps.publish("rtu_" .. session_id .. "_rtt_color", colors.yellow_hc)
+    else
+        databus.ps.publish("rtu_" .. session_id .. "_rtt_color", colors.green)
+    end
+end
+
+-- transmit RTU session unit count
+---@param session_id integer RTU session
+---@param units integer unit count
+function databus.tx_rtu_units(session_id, units)
+    databus.ps.publish("rtu_" .. session_id .. "_units", units)
+end
+
+-- transmit coordinator firmware version and session connection state
+---@param fw string firmware version
+---@param s_addr integer coordinator computer ID
+function databus.tx_crd_connected(fw, s_addr)
+    databus.ps.publish("crd_fw", fw)
+    databus.ps.publish("crd_conn", true)
+    databus.ps.publish("crd_addr", tostring(s_addr))
+end
+
+-- transmit coordinator disconnected
+function databus.tx_crd_disconnected()
+    databus.ps.publish("crd_fw", " ------- ")
+    databus.ps.publish("crd_conn", false)
+    databus.ps.publish("crd_addr", "---")
+    databus.ps.publish("crd_rtt", 0)
+    databus.ps.publish("crd_rtt_color", colors.lightGray)
+end
+
+-- transmit coordinator session RTT
+---@param rtt integer round trip time
+function databus.tx_crd_rtt(rtt)
+    databus.ps.publish("crd_rtt", rtt)
+
+    if rtt > HIGH_RTT then
+        databus.ps.publish("crd_rtt_color", colors.red)
+    elseif rtt > WARN_RTT then
+        databus.ps.publish("crd_rtt_color", colors.yellow_hc)
+    else
+        databus.ps.publish("crd_rtt_color", colors.green)
+    end
+end
+
+-- transmit PKT firmware version and PDG session connection state
+---@param session_id integer PDG session
+---@param fw string firmware version
+---@param s_addr integer PDG computer ID
+function databus.tx_pdg_connected(session_id, fw, s_addr)
+    databus.ps.publish("pdg_" .. session_id .. "_fw", fw)
+    databus.ps.publish("pdg_" .. session_id .. "_addr", util.sprintf("@ C% 3d", s_addr))
+    pgi.create_pdg_entry(session_id)
+end
+
+-- transmit PDG session disconnected
+---@param session_id integer PDG session
+function databus.tx_pdg_disconnected(session_id)
+    pgi.delete_pdg_entry(session_id)
+end
+
+-- transmit PDG session RTT
+---@param session_id integer PDG session
+---@param rtt integer round trip time
+function databus.tx_pdg_rtt(session_id, rtt)
+    databus.ps.publish("pdg_" .. session_id .. "_rtt", rtt)
+
+    if rtt > HIGH_RTT then
+        databus.ps.publish("pdg_" .. session_id .. "_rtt_color", colors.red)
+    elseif rtt > WARN_RTT then
+        databus.ps.publish("pdg_" .. session_id .. "_rtt_color", colors.yellow_hc)
+    else
+        databus.ps.publish("pdg_" .. session_id .. "_rtt_color", colors.green)
+    end
+end
+
+-- link a function to receive data from the bus
+---@param field string field name
+---@param func function function to link
+function databus.rx_field(field, func)
+    databus.ps.subscribe(field, func)
+end
+
+return databus

supervisor/facility.lua

@@ -128,7 +128,7 @@ function facility.new(num_reactors, cooling_conf)
         for i = 1, #self.prio_defs do
             local units = self.prio_defs[i]
             for u = 1, #units do
-                all_ramped = all_ramped and units[u].a_ramp_complete()
+                all_ramped = all_ramped and units[u].auto_ramp_complete()
             end
         end
 
@@ -159,7 +159,7 @@ function facility.new(num_reactors, cooling_conf)
                     local u = units[id] ---@type reactor_unit
 
                     local ctl = u.get_control_inf()
-                    local lim_br100 = u.a_get_effective_limit()
+                    local lim_br100 = u.auto_get_effective_limit()
 
                     if abort_on_fault and (lim_br100 ~= ctl.lim_br100) then
                         -- effective limit differs from set limit, unit is degraded
@@ -183,7 +183,7 @@ function facility.new(num_reactors, cooling_conf)
 
                     unallocated = math.max(0, unallocated - ctl.br100)
 
-                    if last ~= ctl.br100 then u.a_commit_br100(ramp) end
+                    if last ~= ctl.br100 then u.auto_commit_br100(ramp) end
                 end
             end
         end
@@ -320,7 +320,7 @@ function facility.new(num_reactors, cooling_conf)
                             self.start_fail = START_STATUS.BLADE_MISMATCH
                         end
 
-                        if self.start_fail == START_STATUS.OK then u.a_engage() end
+                        if self.start_fail == START_STATUS.OK then u.auto_engage() end
 
                         self.max_burn_combined = self.max_burn_combined + (u.get_control_inf().lim_br100 / 100.0)
                     end
@@ -340,7 +340,7 @@ function facility.new(num_reactors, cooling_conf)
                     -- use manual SCRAM since inactive was requested, and automatic SCRAM trips an alarm
                     for _, u in pairs(self.prio_defs[i]) do
                         u.scram()
-                        u.a_disengage()
+                        u.auto_disengage()
                     end
                 end
 
@@ -601,7 +601,7 @@ function facility.new(num_reactors, cooling_conf)
                 -- SCRAM all units
                 for i = 1, #self.prio_defs do
                     for _, u in pairs(self.prio_defs[i]) do
-                        u.a_scram()
+                        u.auto_scram()
                     end
                 end
 
@@ -653,7 +653,7 @@ function facility.new(num_reactors, cooling_conf)
                 -- reset PLC RPS trips if we should
                 for i = 1, #self.units do
                     local u = self.units[i] ---@type reactor_unit
-                    u.a_cond_rps_reset()
+                    u.auto_cond_rps_reset()
                 end
             end
         end

supervisor/panel/components/pdg_entry.lua

@@ -0,0 +1,46 @@
+--
+-- Pocket Diagnostics Connection Entry
+--
+
+local databus       = require("supervisor.databus")
+
+local core          = require("graphics.core")
+
+local Div           = require("graphics.elements.div")
+local TextBox       = require("graphics.elements.textbox")
+
+local DataIndicator = require("graphics.elements.indicators.data")
+
+local TEXT_ALIGN = core.TEXT_ALIGN
+
+local cpair = core.cpair
+
+-- create a pocket diagnostics list entry
+---@param parent graphics_element parent
+---@param id integer PDG session ID
+local function init(parent, id)
+    -- root div
+    local root = Div{parent=parent,x=2,y=2,height=4,width=parent.get_width()-2,hidden=true}
+    local entry = Div{parent=root,x=2,y=1,height=3,fg_bg=cpair(colors.black,colors.white)}
+
+    local ps_prefix = "pdg_" .. id .. "_"
+
+    TextBox{parent=entry,x=1,y=1,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+    local pdg_addr = TextBox{parent=entry,x=1,y=2,text="@ C ??",alignment=TEXT_ALIGN.CENTER,width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray),nav_active=cpair(colors.gray,colors.black)}
+    TextBox{parent=entry,x=1,y=3,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+    pdg_addr.register(databus.ps, ps_prefix .. "addr", pdg_addr.set_value)
+
+    TextBox{parent=entry,x=10,y=2,text="FW:",width=3,height=1}
+    local pdg_fw_v = TextBox{parent=entry,x=14,y=2,text=" ------- ",width=20,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    pdg_fw_v.register(databus.ps, ps_prefix .. "fw", pdg_fw_v.set_value)
+
+    TextBox{parent=entry,x=35,y=2,text="RTT:",width=4,height=1}
+    local pdg_rtt = DataIndicator{parent=entry,x=40,y=2,label="",unit="",format="%5d",value=0,width=5,fg_bg=cpair(colors.lightGray,colors.white)}
+    TextBox{parent=entry,x=46,y=2,text="ms",width=4,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    pdg_rtt.register(databus.ps, ps_prefix .. "rtt", pdg_rtt.update)
+    pdg_rtt.register(databus.ps, ps_prefix .. "rtt_color", pdg_rtt.recolor)
+
+    return root
+end
+
+return init

supervisor/panel/components/rtu_entry.lua

@@ -0,0 +1,50 @@
+--
+-- RTU Connection Entry
+--
+
+local databus       = require("supervisor.databus")
+
+local core          = require("graphics.core")
+
+local Div           = require("graphics.elements.div")
+local TextBox       = require("graphics.elements.textbox")
+
+local DataIndicator = require("graphics.elements.indicators.data")
+
+local TEXT_ALIGN = core.TEXT_ALIGN
+
+local cpair = core.cpair
+
+-- create an RTU list entry
+---@param parent graphics_element parent
+---@param id integer RTU session ID
+local function init(parent, id)
+    -- root div
+    local root = Div{parent=parent,x=2,y=2,height=4,width=parent.get_width()-2,hidden=true}
+    local entry = Div{parent=root,x=2,y=1,height=3,fg_bg=cpair(colors.black,colors.white)}
+
+    local ps_prefix = "rtu_" .. id .. "_"
+
+    TextBox{parent=entry,x=1,y=1,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+    local rtu_addr = TextBox{parent=entry,x=1,y=2,text="@ C ??",alignment=TEXT_ALIGN.CENTER,width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray),nav_active=cpair(colors.gray,colors.black)}
+    TextBox{parent=entry,x=1,y=3,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+    rtu_addr.register(databus.ps, ps_prefix .. "addr", rtu_addr.set_value)
+
+    TextBox{parent=entry,x=10,y=2,text="UNITS:",width=7,height=1}
+    local unit_count = DataIndicator{parent=entry,x=17,y=2,label="",unit="",format="%2d",value=0,width=2,fg_bg=cpair(colors.gray,colors.white)}
+    unit_count.register(databus.ps, ps_prefix .. "units", unit_count.set_value)
+
+    TextBox{parent=entry,x=21,y=2,text="FW:",width=3,height=1}
+    local rtu_fw_v = TextBox{parent=entry,x=25,y=2,text=" ------- ",width=9,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    rtu_fw_v.register(databus.ps, ps_prefix .. "fw", rtu_fw_v.set_value)
+
+    TextBox{parent=entry,x=36,y=2,text="RTT:",width=4,height=1}
+    local rtu_rtt = DataIndicator{parent=entry,x=40,y=2,label="",unit="",format="%5d",value=0,width=5,fg_bg=cpair(colors.lightGray,colors.white)}
+    TextBox{parent=entry,x=46,y=2,text="ms",width=4,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    rtu_rtt.register(databus.ps, ps_prefix .. "rtt", rtu_rtt.update)
+    rtu_rtt.register(databus.ps, ps_prefix .. "rtt_color", rtu_rtt.recolor)
+
+    return root
+end
+
+return init

supervisor/panel/front_panel.lua

@@ -0,0 +1,164 @@
+--
+-- Main SCADA Coordinator GUI
+--
+
+local util          = require("scada-common.util")
+
+local config        = require("supervisor.config")
+local databus       = require("supervisor.databus")
+
+local pgi           = require("supervisor.panel.pgi")
+local style         = require("supervisor.panel.style")
+
+local pdg_entry     = require("supervisor.panel.components.pdg_entry")
+local rtu_entry     = require("supervisor.panel.components.rtu_entry")
+
+local core          = require("graphics.core")
+
+local Div           = require("graphics.elements.div")
+local ListBox       = require("graphics.elements.listbox")
+local MultiPane     = require("graphics.elements.multipane")
+local TextBox       = require("graphics.elements.textbox")
+
+local TabBar        = require("graphics.elements.controls.tabbar")
+
+local LED           = require("graphics.elements.indicators.led")
+local DataIndicator = require("graphics.elements.indicators.data")
+
+local TEXT_ALIGN = core.TEXT_ALIGN
+
+local cpair = core.cpair
+
+-- create new main view
+---@param panel graphics_element main displaybox
+local function init(panel)
+    TextBox{parent=panel,y=1,text="SCADA SUPERVISOR",alignment=TEXT_ALIGN.CENTER,height=1,fg_bg=style.header}
+
+    local page_div = Div{parent=panel,x=1,y=3}
+
+    --
+    -- system indicators
+    --
+
+    local main_page = Div{parent=page_div,x=1,y=1}
+
+    local system = Div{parent=main_page,width=14,height=17,x=2,y=2}
+
+    local on = LED{parent=system,label="STATUS",colors=cpair(colors.green,colors.red)}
+    local heartbeat = LED{parent=system,label="HEARTBEAT",colors=cpair(colors.green,colors.green_off)}
+    on.update(true)
+    system.line_break()
+
+    heartbeat.register(databus.ps, "heartbeat", heartbeat.update)
+
+    local modem = LED{parent=system,label="MODEM",colors=cpair(colors.green,colors.green_off)}
+    system.line_break()
+
+    modem.register(databus.ps, "has_modem", modem.update)
+
+---@diagnostic disable-next-line: undefined-field
+    local comp_id = util.sprintf("(%d)", os.getComputerID())
+    TextBox{parent=system,x=9,y=4,width=6,height=1,text=comp_id,fg_bg=cpair(colors.lightGray,colors.ivory)}
+
+    --
+    -- about footer
+    --
+
+    local about   = Div{parent=main_page,width=15,height=3,x=1,y=16,fg_bg=cpair(colors.lightGray,colors.ivory)}
+    local fw_v    = TextBox{parent=about,x=1,y=1,text="FW: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
+    local comms_v = TextBox{parent=about,x=1,y=2,text="NT: v00.00.00",alignment=TEXT_ALIGN.LEFT,height=1}
+
+    fw_v.register(databus.ps, "version", function (version) fw_v.set_value(util.c("FW: ", version)) end)
+    comms_v.register(databus.ps, "comms_version", function (version) comms_v.set_value(util.c("NT: v", version)) end)
+
+    --
+    -- page handling
+    --
+
+    -- plc page
+
+    local plc_page = Div{parent=page_div,x=1,y=1,hidden=true}
+    local plc_list = Div{parent=plc_page,x=2,y=2,width=49}
+
+    for i = 1, config.NUM_REACTORS do
+        local ps_prefix = "plc_" .. i .. "_"
+        local plc_entry = Div{parent=plc_list,height=3,fg_bg=cpair(colors.black,colors.white)}
+
+        TextBox{parent=plc_entry,x=1,y=1,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+        TextBox{parent=plc_entry,x=1,y=2,text="UNIT "..i,alignment=TEXT_ALIGN.CENTER,width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+        TextBox{parent=plc_entry,x=1,y=3,text="",width=8,height=1,fg_bg=cpair(colors.black,colors.lightGray)}
+
+        local conn = LED{parent=plc_entry,x=10,y=2,label="LINK",colors=cpair(colors.green,colors.green_off)}
+        conn.register(databus.ps, ps_prefix .. "conn", conn.update)
+
+        local plc_addr = TextBox{parent=plc_entry,x=17,y=2,text=" --- ",width=5,height=1,fg_bg=cpair(colors.gray,colors.white)}
+        plc_addr.register(databus.ps, ps_prefix .. "addr", plc_addr.set_value)
+
+        TextBox{parent=plc_entry,x=23,y=2,text="FW:",width=3,height=1}
+        local plc_fw_v = TextBox{parent=plc_entry,x=27,y=2,text=" ------- ",width=9,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+        plc_fw_v.register(databus.ps, ps_prefix .. "fw", plc_fw_v.set_value)
+
+        TextBox{parent=plc_entry,x=37,y=2,text="RTT:",width=4,height=1}
+        local plc_rtt = DataIndicator{parent=plc_entry,x=42,y=2,label="",unit="",format="%4d",value=0,width=4,fg_bg=cpair(colors.lightGray,colors.white)}
+        TextBox{parent=plc_entry,x=47,y=2,text="ms",width=4,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+        plc_rtt.register(databus.ps, ps_prefix .. "rtt", plc_rtt.update)
+        plc_rtt.register(databus.ps, ps_prefix .. "rtt_color", plc_rtt.recolor)
+
+        plc_list.line_break()
+    end
+
+    -- rtu page
+
+    local rtu_page = Div{parent=page_div,x=1,y=1,hidden=true}
+    local rtu_list = ListBox{parent=rtu_page,x=1,y=1,height=17,width=51,scroll_height=1000,fg_bg=cpair(colors.black,colors.ivory),nav_fg_bg=cpair(colors.gray,colors.lightGray),nav_active=cpair(colors.black,colors.gray)}
+    local _ = Div{parent=rtu_list,height=1,hidden=true} -- padding
+
+    -- coordinator page
+
+    local crd_page = Div{parent=page_div,x=1,y=1,hidden=true}
+    local crd_box = Div{parent=crd_page,x=2,y=2,width=49,height=4,fg_bg=cpair(colors.black,colors.white)}
+
+    local crd_conn = LED{parent=crd_box,x=2,y=2,label="CONNECTION",colors=cpair(colors.green,colors.green_off)}
+    crd_conn.register(databus.ps, "crd_conn", crd_conn.update)
+
+    TextBox{parent=crd_box,x=4,y=3,text="COMPUTER",width=8,height=1,fg_bg=cpair(colors.gray,colors.white)}
+    local crd_addr = TextBox{parent=crd_box,x=13,y=3,text="---",width=5,height=1,fg_bg=cpair(colors.gray,colors.white)}
+    crd_addr.register(databus.ps, "crd_addr", crd_addr.set_value)
+
+    TextBox{parent=crd_box,x=22,y=2,text="FW:",width=3,height=1}
+    local crd_fw_v = TextBox{parent=crd_box,x=26,y=2,text=" ------- ",width=9,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    crd_fw_v.register(databus.ps, "crd_fw", crd_fw_v.set_value)
+
+    TextBox{parent=crd_box,x=36,y=2,text="RTT:",width=4,height=1}
+    local crd_rtt = DataIndicator{parent=crd_box,x=41,y=2,label="",unit="",format="%5d",value=0,width=5,fg_bg=cpair(colors.lightGray,colors.white)}
+    TextBox{parent=crd_box,x=47,y=2,text="ms",width=4,height=1,fg_bg=cpair(colors.lightGray,colors.white)}
+    crd_rtt.register(databus.ps, "crd_rtt", crd_rtt.update)
+    crd_rtt.register(databus.ps, "crd_rtt_color", crd_rtt.recolor)
+
+    -- pocket diagnostics page
+
+    local pkt_page = Div{parent=page_div,x=1,y=1,hidden=true}
+    local pdg_list = ListBox{parent=pkt_page,x=1,y=1,height=17,width=51,scroll_height=1000,fg_bg=cpair(colors.black,colors.ivory),nav_fg_bg=cpair(colors.gray,colors.lightGray),nav_active=cpair(colors.black,colors.gray)}
+    local _ = Div{parent=pdg_list,height=1,hidden=true} -- padding
+
+    -- assemble page panes
+
+    local panes = { main_page, plc_page, rtu_page, crd_page, pkt_page }
+
+    local page_pane = MultiPane{parent=page_div,x=1,y=1,panes=panes}
+
+    local tabs = {
+        { name = "SVR", color = cpair(colors.black, colors.ivory) },
+        { name = "PLC", color = cpair(colors.black, colors.ivory) },
+        { name = "RTU", color = cpair(colors.black, colors.ivory) },
+        { name = "CRD", color = cpair(colors.black, colors.ivory) },
+        { name = "PKT", color = cpair(colors.black, colors.ivory) },
+    }
+
+    TabBar{parent=panel,y=2,tabs=tabs,min_width=9,callback=page_pane.set_value,fg_bg=cpair(colors.black,colors.white)}
+
+    -- link RTU/PDG list management to PGI
+    pgi.link_elements(rtu_list, rtu_entry, pdg_list, pdg_entry)
+end
+
+return init

supervisor/panel/pgi.lua

@@ -0,0 +1,93 @@
+--
+-- Protected Graphics Interface
+--
+
+local log  = require("scada-common.log")
+local util = require("scada-common.util")
+
+local pgi = {}
+
+local data = {
+    rtu_list = nil,     ---@type nil|graphics_element
+    pdg_list = nil,     ---@type nil|graphics_element
+    rtu_entry = nil,    ---@type function
+    pdg_entry = nil,    ---@type function
+    -- session entries
+    s_entries = { rtu = {}, pdg = {} }
+}
+
+-- link list boxes
+---@param rtu_list graphics_element RTU list element
+---@param rtu_entry function RTU entry constructor
+---@param pdg_list graphics_element pocket diagnostics list element
+---@param pdg_entry function pocket diagnostics entry constructor
+function pgi.link_elements(rtu_list, rtu_entry, pdg_list, pdg_entry)
+    data.rtu_list = rtu_list
+    data.pdg_list = pdg_list
+    data.rtu_entry = rtu_entry
+    data.pdg_entry = pdg_entry
+end
+
+-- unlink all fields, disabling the PGI
+function pgi.unlink()
+    data.rtu_list = nil
+    data.pdg_list = nil
+    data.rtu_entry = nil
+    data.pdg_entry = nil
+end
+
+-- add an RTU entry to the RTU list
+---@param session_id integer RTU session
+function pgi.create_rtu_entry(session_id)
+    if data.rtu_list ~= nil and data.rtu_entry ~= nil then
+        local success, result = pcall(data.rtu_entry, data.rtu_list, session_id)
+
+        if success then
+            data.s_entries.rtu[session_id] = result
+        else
+            log.error(util.c("PGI: failed to create RTU entry (", result, ")"), true)
+        end
+    end
+end
+
+-- delete an RTU entry from the RTU list
+---@param session_id integer RTU session
+function pgi.delete_rtu_entry(session_id)
+    if data.s_entries.rtu[session_id] ~= nil then
+        local success, result = pcall(data.s_entries.rtu[session_id].delete)
+        data.s_entries.rtu[session_id] = nil
+
+        if not success then
+            log.error(util.c("PGI: failed to delete RTU entry (", result, ")"), true)
+        end
+    end
+end
+
+-- add a PDG entry to the PDG list
+---@param session_id integer pocket diagnostics session
+function pgi.create_pdg_entry(session_id)
+    if data.pdg_list ~= nil and data.pdg_entry ~= nil then
+        local success, result = pcall(data.pdg_entry, data.pdg_list, session_id)
+
+        if success then
+            data.s_entries.pdg[session_id] = result
+        else
+            log.error(util.c("PGI: failed to create PDG entry (", result, ")"), true)
+        end
+    end
+end
+
+-- delete a PDG entry from the PDG list
+---@param session_id integer pocket diagnostics session
+function pgi.delete_pdg_entry(session_id)
+    if data.s_entries.pdg[session_id] ~= nil then
+        local success, result = pcall(data.s_entries.pdg[session_id].delete)
+        data.s_entries.pdg[session_id] = nil
+
+        if not success then
+            log.error(util.c("PGI: failed to delete PDG entry (", result, ")"), true)
+        end
+    end
+end
+
+return pgi