#545 supervisor type annotation updates

supervisor/session/coordinator.lua

@@ -128,7 +128,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
         local unit_builds = {}
 
         for i = 1, #self.units do
-            local unit = self.units[i]  ---@type reactor_unit
+            local unit = self.units[i]
             unit_builds[unit.get_id()] = unit.get_build()
         end
 
@@ -145,7 +145,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
         local builds = {}
 
         for i = 1, #self.units do
-            local unit = self.units[i]  ---@type reactor_unit
+            local unit = self.units[i]
             builds[unit.get_id()] = unit.get_build()
         end
 
@@ -168,7 +168,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
         local status = {}
 
         for i = 1, #self.units do
-            local unit = self.units[i]  ---@type reactor_unit
+            local unit = self.units[i]
 
             status[unit.get_id()] = {
                 unit.get_reactor_status(),
@@ -308,7 +308,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
 
                     -- continue if valid unit id
                     if util.is_int(uid) and uid > 0 and uid <= #self.units then
-                        local unit   = self.units[uid]    ---@type reactor_unit
+                        local unit   = self.units[uid]
                         local manual = facility.get_group(uid) == AUTO_GROUP.MANUAL
 
                         if cmd == UNIT_COMMAND.SCRAM then
@@ -432,8 +432,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
                             local unit_id = cmd.val
                             local builds = {}
 
-                            local unit = self.units[unit_id]    ---@type reactor_unit
-                            builds[unit_id] = unit.get_build(-1)
+                            builds[unit_id] = self.units[unit_id].get_build(-1)
 
                             _send(CRDN_TYPE.UNIT_BUILDS, { builds })
                         elseif cmd.key == CRD_S_DATA.RESEND_RTU_BUILD then
@@ -446,8 +445,7 @@ function coordinator.new_session(id, s_addr, i_seq_num, in_queue, out_queue, tim
 
                                 local builds = {}
 
-                                local unit = self.units[unit_id]    ---@type reactor_unit
-                                builds[unit_id] = unit.get_build(cmd.val.type)
+                                builds[unit_id] = self.units[unit_id].get_build(cmd.val.type)
 
                                 _send(CRDN_TYPE.UNIT_BUILDS, { builds })
                             else

supervisor/session/rtu.lua

@@ -63,7 +63,7 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
             keep_alive = 0,
             alarm_tones = 0
         },
-        units = {}
+        units = {}  ---@type unit_session[]
     }
 
     ---@class rtu_session
@@ -80,13 +80,13 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
         _reset_config()
 
         for i = 1, #self.fac_units do
-            local unit = self.fac_units[i]    ---@type reactor_unit
+            local unit = self.fac_units[i]
             unit.purge_rtu_devices(id)
             facility.purge_rtu_devices(id)
         end
 
         for i = 1, #self.advert do
-            local unit = nil    ---@type unit_session|nil
+            local unit = nil
 
             ---@type rtu_advertisement
             local unit_advert = {
@@ -96,7 +96,7 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
                 rsio = self.advert[i][4]
             }
 
-            local u_type = unit_advert.type ---@type integer|boolean
+            local u_type = unit_advert.type ---@type RTU_UNIT_TYPE|boolean
 
             -- validate unit advertisement
 
@@ -127,7 +127,7 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
                 log.debug(log_tag .. "_handle_advertisement(): advertisement unit validation failure")
             else
                 if unit_advert.reactor > 0 then
-                    local target_unit = self.fac_units[unit_advert.reactor] ---@type reactor_unit
+                    local target_unit = self.fac_units[unit_advert.reactor]
 
                     -- unit RTUs
                     if u_type == RTU_UNIT_TYPE.REDSTONE then
@@ -255,8 +255,7 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
         if pkt.scada_frame.protocol() == PROTOCOL.MODBUS_TCP then
             ---@cast pkt modbus_frame
             if self.units[pkt.unit_id] ~= nil then
-                local unit = self.units[pkt.unit_id]    ---@type unit_session
-                unit.handle_packet(pkt)
+                self.units[pkt.unit_id].handle_packet(pkt)
             end
         elseif pkt.scada_frame.protocol() == PROTOCOL.SCADA_MGMT then
             ---@cast pkt mgmt_frame
@@ -298,8 +297,7 @@ function rtu.new_session(id, s_addr, i_seq_num, in_queue, out_queue, timeout, ad
                 if pkt.length == 1 then
                     local unit_id = pkt.data[1]
                     if self.units[unit_id] ~= nil then
-                        local unit = self.units[unit_id]    ---@type unit_session
-                        unit.invalidate_cache()
+                        self.units[unit_id].invalidate_cache()
                     end
                 else
                     log.debug(log_tag .. "SCADA RTU GW device re-mount packet length mismatch")

supervisor/session/rtu/dynamicv.lua

@@ -84,7 +84,7 @@ function dynamicv.new(session_id, unit_id, advert, out_queue)
             },
             state = {
                 last_update = 0,
-                container_mode = CONTAINER_MODE.BOTH    ---@type container_mode
+                container_mode = CONTAINER_MODE.BOTH ---@type container_mode
             },
             tanks = {
                 last_update = 0,
@@ -224,7 +224,7 @@ function dynamicv.new(session_id, unit_id, advert, out_queue)
                     end
                 elseif msg.qtype == mqueue.TYPE.DATA then
                     -- instruction with body
-                    local cmd = msg.message     ---@type queue_data
+                    local cmd = msg.message ---@type queue_data
                     if cmd.key == DTV_RTU_S_DATA.SET_CONT_MODE then
                         if cmd.val == types.CONTAINER_MODE.BOTH or
                            cmd.val == types.CONTAINER_MODE.FILL or

supervisor/session/rtu/turbinev.lua

@@ -95,7 +95,7 @@ function turbinev.new(session_id, unit_id, advert, out_queue)
                 flow_rate = 0,
                 prod_rate = 0,
                 steam_input_rate = 0,
-                dumping_mode = DUMPING_MODE.IDLE    ---@type dumping_mode
+                dumping_mode = DUMPING_MODE.IDLE ---@type dumping_mode
             },
             tanks = {
                 last_update = 0,
@@ -254,7 +254,7 @@ function turbinev.new(session_id, unit_id, advert, out_queue)
                     end
                 elseif msg.qtype == mqueue.TYPE.DATA then
                     -- instruction with body
-                    local cmd = msg.message     ---@type queue_data
+                    local cmd = msg.message ---@type queue_data
                     if cmd.key == TBV_RTU_S_DATA.SET_DUMP_MODE then
                         if cmd.val == types.DUMPING_MODE.IDLE or
                            cmd.val == types.DUMPING_MODE.DUMPING_EXCESS or

supervisor/session/rtu/txnctrl.lua

@@ -6,7 +6,8 @@ local util = require("scada-common.util")
 
 local txnctrl = {}
 
-local TIMEOUT = 2000    -- 2000ms max wait
+-- 2000ms max wait
+local TIMEOUT = 2000
 
 -- create a new transaction controller
 ---@nodiscard

supervisor/session/rtu/unit_session.lua

@@ -164,7 +164,6 @@ function unit_session.new(session_id, unit_id, advert, out_queue, log_tag, txn_t
     function public.get_cmd_queue() return protected.in_q end
 
     -- close this unit
-    ---@nodiscard
     function public.close() self.connected = false end
     -- check if this unit is connected
     ---@nodiscard

supervisor/session/svsessions.lua

@@ -40,13 +40,26 @@ local SESSION_TYPE = {
 svsessions.SESSION_TYPE = SESSION_TYPE
 
 local self = {
-    nic = nil,          ---@type nic|nil
+    -- references to supervisor state and other data
+    nic = nil,              ---@type nic|nil
     fp_ok = false,
-    config = nil,       ---@type svr_config
-    facility = nil,     ---@type facility|nil
-    sessions = { rtu = {}, plc = {}, crd = {}, pdg = {} },
+    config = nil,           ---@type svr_config
+    facility = nil,         ---@type facility|nil
+    -- lists of connected sessions
+    sessions = {
+        rtu = {},           ---@type rtu_session_struct
+        plc = {},           ---@type plc_session_struct
+        crd = {},           ---@type crd_session_struct
+        pdg = {}            ---@type pdg_session_struct
+    },
+    -- next session IDs
     next_ids = { rtu = 0, plc = 0, crd = 0, pdg = 0 },
-    dev_dbg = { duplicate = {}, out_of_range = {}, connected = {} }
+    -- rtu device tracking and invalid assignment detection
+    dev_dbg = {
+        duplicate = {},     ---@type unit_session
+        out_of_range = {},  ---@type unit_session
+        connected = {}      ---@type { induction: boolean, sps: boolean, tanks: boolean[], units: unit_connections[] }
+    }
 }
 
 ---@alias sv_session_structs plc_session_struct|rtu_session_struct|crd_session_struct|pdg_session_struct
@@ -119,10 +132,10 @@ local function _sv_handle_outq(session)
 end
 
 -- iterate all the given sessions
----@param sessions table
+---@param sessions sv_session_structs[]
 local function _iterate(sessions)
     for i = 1, #sessions do
-        local session = sessions[i] ---@type sv_session_structs
+        local session = sessions[i]
 
         if session.open and session.instance.iterate() then
             _sv_handle_outq(session)
@@ -150,20 +163,20 @@ local function _shutdown(session)
 end
 
 -- close connections
----@param sessions table
+---@param sessions sv_session_structs[]
 local function _close(sessions)
     for i = 1, #sessions do
-        local session = sessions[i]  ---@type sv_session_structs
+        local session = sessions[i]
         if session.open then _shutdown(session) end
     end
 end
 
 -- check if a watchdog timer event matches that of one of the provided sessions
----@param sessions table
+---@param sessions sv_session_structs[]
 ---@param timer_event number
 local function _check_watchdogs(sessions, timer_event)
     for i = 1, #sessions do
-        local session = sessions[i]  ---@type sv_session_structs
+        local session = sessions[i]
         if session.open then
             local triggered = session.instance.check_wd(timer_event)
             if triggered then
@@ -175,8 +188,9 @@ local function _check_watchdogs(sessions, timer_event)
 end
 
 -- delete any closed sessions
----@param sessions table
+---@param sessions sv_session_structs[]
 local function _free_closed(sessions)
+    ---@param session sv_session_structs
     local f = function (session) return session.open end
 
     ---@param session sv_session_structs
@@ -189,7 +203,7 @@ end
 
 -- find a session by computer ID
 ---@nodiscard
----@param list table
+---@param list sv_session_structs[]
 ---@param s_addr integer
 ---@return sv_session_structs|nil
 local function _find_session(list, s_addr)
@@ -366,7 +380,7 @@ function svsessions.init(nic, fp_ok, config, facility)
 
     for i = 1, config.UnitCount do
         local r_cool = cool_conf.r_cool[i]
-        local conns = { boilers = {}, turbines = {}, tanks = {} }
+        local conns = { boilers = {}, turbines = {}, tanks = {} }   ---@type unit_connections
 
         for b = 1, r_cool.BoilerCount do conns.boilers[b] = true end
         for t = 1, r_cool.TurbineCount do conns.turbines[t] = true end