#545 rtu gateway type annotation updates

rtu/configure.lua

@@ -88,17 +88,17 @@ local changes = {
     { "v1.10.2", { "Re-organized peripheral configuration UI, resulting in some input fields being re-ordered" } }
 }
 
+---@class rtu_peri_definition
+---@field unit integer|nil
+---@field index integer|nil
+---@field name string
+
 ---@class rtu_rs_definition
 ---@field unit integer|nil
 ---@field port IO_PORT
 ---@field side side
 ---@field color color|nil
 
----@class rtu_peri_definition
----@field unit integer|nil
----@field index integer|nil
----@field name string
-
 local RTU_DEV_TYPES = { "boilerValve", "turbineValve", "dynamicValve", "inductionPort", "spsPort", "solarNeutronActivator", "environmentDetector" }
 local NEEDS_UNIT = { "boilerValve", "turbineValve", "dynamicValve", "solarNeutronActivator", "environmentDetector" }
 
@@ -174,8 +174,8 @@ local tool_ctl = {
 ---@class rtu_config
 local tmp_cfg = {
     SpeakerVolume = 1.0,
-    Peripherals = {},
+    Peripherals = {},   ---@type rtu_peri_definition[]
-    Redstone = {},
+    Redstone = {},      ---@type rtu_rs_definition[]
     SVR_Channel = nil,  ---@type integer
     RTU_Channel = nil,  ---@type integer
     ConnTimeout = nil,  ---@type number
@@ -1296,7 +1296,7 @@ local function config_view(display)
             local ini_unit = tri(for_facility, nil, entry.for_reactor)
 
             local def = { name = entry.name, unit = ini_unit, index = entry.index }
-            local mount = mounts[def.name] ---@type ppm_entry|nil
+            local mount = mounts[def.name]
 
             local status = "  \x13 not connected, please re-config later"
             local color = colors.orange
@@ -1497,7 +1497,7 @@ local function config_view(display)
         peri_list.remove_all()
 
         for i = 1, #cfg.Peripherals do
-            local def = cfg.Peripherals[i]  ---@type rtu_peri_definition
+            local def = cfg.Peripherals[i]
 
             local t = ppm.get_type(def.name)
             local t_str = "<disconnected> (connect to edit)"
@@ -1529,7 +1529,7 @@ local function config_view(display)
     end
 
     local function edit_rs_entry(idx)
-        local def = tmp_cfg.Redstone[idx]   ---@type rtu_rs_definition
+        local def = tmp_cfg.Redstone[idx]
 
         tool_ctl.rs_cfg_shortcut.hide(true)
         tool_ctl.rs_cfg_color.show()

rtu/panel/front_panel.lua

@@ -31,7 +31,7 @@ local UNIT_TYPE_LABELS = { "UNKNOWN", "REDSTONE", "BOILER", "TURBINE", "DYNAMIC
 
 -- create new front panel view
 ---@param panel graphics_element main displaybox
----@param units table unit list
+---@param units rtu_registry_entry[] unit list
 local function init(panel, units)
     local disabled_fg = style.fp.disabled_fg
 
@@ -135,7 +135,7 @@ local function init(panel, units)
 
     -- show hardware statuses
     for i = 1, list_length do
-        local unit = units[i]   ---@type rtu_unit_registry_entry
+        local unit = units[i]
 
         -- hardware status
         local unit_hw = RGBLED{parent=unit_hw_statuses,y=i,label="",colors={colors.red,colors.orange,colors.yellow,colors.green}}

rtu/renderer.lua

@@ -18,7 +18,7 @@ local ui = {
 }
 
 -- try to start the UI
----@param units table RTU units
+---@param units rtu_registry_entry[] RTU entries
 ---@param theme FP_THEME front panel theme
 ---@param color_mode COLOR_MODE color mode
 ---@return boolean success, any error_msg

rtu/rtu.lua

@@ -322,13 +322,13 @@ function rtu.comms(version, nic, conn_watchdog)
 
     -- generate device advertisement table
     ---@nodiscard
-    ---@param units table
+    ---@param units rtu_registry_entry[]
     ---@return table advertisement
     local function _generate_advertisement(units)
         local advertisement = {}
 
         for i = 1, #units do
-            local unit = units[i]   ---@type rtu_unit_registry_entry
+            local unit = units[i]
 
             if unit.type ~= nil then
                 local advert = { unit.type, unit.index, unit.reactor }
@@ -429,9 +429,9 @@ function rtu.comms(version, nic, conn_watchdog)
 
     -- handle a MODBUS/SCADA packet
     ---@param packet modbus_frame|mgmt_frame
-    ---@param units table RTU units
+    ---@param units rtu_registry_entry[] RTU entries
     ---@param rtu_state rtu_state
-    ---@param sounders table speaker alarm sounders
+    ---@param sounders rtu_speaker_sounder[] speaker alarm sounders
     function public.handle_packet(packet, units, rtu_state, sounders)
         -- 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
@@ -467,7 +467,7 @@ function rtu.comms(version, nic, conn_watchdog)
 
                     -- handle MODBUS instruction
                     if packet.unit_id <= #units then
-                        local unit = units[packet.unit_id]  ---@type rtu_unit_registry_entry
+                        local unit = units[packet.unit_id]
                         local unit_dbg_tag = " (unit " .. packet.unit_id .. ")"
 
                         if unit.name == "redstone_io" then
@@ -538,11 +538,9 @@ function rtu.comms(version, nic, conn_watchdog)
                         if (packet.length == 1) and type(packet.data[1] == "table") and (#packet.data[1] == 8) then
                             local states = packet.data[1]
 
+                            -- set tone states
                             for i = 1, #sounders do
-                                local s = sounders[i]   ---@type rtu_speaker_sounder
+                                for id = 1, #states do sounders[i].stream.set_active(id, states[id] == true) end
-
-                                -- set tone states
-                                for id = 1, #states do s.stream.set_active(id, states[id] == true) end
                             end
                         end
                     else

rtu/startup.lua

@@ -109,7 +109,7 @@ local function main()
         -- RTU gateway devices (not RTU units)
         rtu_dev = {
             modem = ppm.get_wireless_modem(),
-            sounders = {}
+            sounders = {}        ---@type rtu_speaker_sounder[]
         },
 
         -- system objects
@@ -117,7 +117,7 @@ local function main()
             nic = nil,           ---@type nic
             rtu_comms = nil,     ---@type rtu_comms
             conn_watchdog = nil, ---@type watchdog
-            units = {}
+            units = {}           ---@type rtu_registry_entry[]
         },
 
         -- message queues
@@ -143,11 +143,11 @@ local function main()
     -- configure RTU gateway based on settings file definitions
     local function sys_config()
         -- redstone interfaces
-        local rs_rtus = {}
+        local rs_rtus = {}  ---@type { rtu: rtu_rs_device, capabilities: IO_PORT[] }[]
 
         -- go through redstone definitions list
         for entry_idx = 1, #rtu_redstone do
-            local entry = rtu_redstone[entry_idx]   ---@type rtu_rs_definition
+            local entry = rtu_redstone[entry_idx]
             local assignment
             local for_reactor = entry.unit
             local iface_name = util.trinary(entry.color ~= nil, util.c(entry.side, "/", rsio.color_name(entry.color)), entry.side)
@@ -227,14 +227,14 @@ local function main()
 
         -- create unit entries for redstone RTUs
         for for_reactor, def in pairs(rs_rtus) do
-            ---@class rtu_unit_registry_entry
+            ---@class rtu_registry_entry
             local unit = {
                 uid = 0,                            ---@type integer
                 name = "redstone_io",               ---@type string
                 type = RTU_UNIT_TYPE.REDSTONE,      ---@type RTU_UNIT_TYPE
                 index = false,                      ---@type integer|false
                 reactor = for_reactor,              ---@type integer
-                device = def.capabilities,          ---@type table use device field for redstone ports
+                device = def.capabilities,          ---@type IO_PORT[] use device field for redstone ports
                 is_multiblock = false,              ---@type boolean
                 formed = nil,                       ---@type boolean|nil
                 hw_state = RTU_UNIT_HW_STATE.OK,    ---@type RTU_UNIT_HW_STATE
@@ -440,14 +440,14 @@ local function main()
                 end
             end
 
-            ---@class rtu_unit_registry_entry
+            ---@class rtu_registry_entry
             local rtu_unit = {
                 uid = 0,                                ---@type integer
                 name = name,                            ---@type string
                 type = rtu_type,                        ---@type RTU_UNIT_TYPE
                 index = index or false,                 ---@type integer|false
                 reactor = for_reactor,                  ---@type integer
-                device = device,                        ---@type table
+                device = device,                        ---@type table peripheral reference
                 is_multiblock = is_multiblock,          ---@type boolean
                 formed = formed,                        ---@type boolean|nil
                 hw_state = RTU_UNIT_HW_STATE.OFFLINE,   ---@type RTU_UNIT_HW_STATE

rtu/threads.lua

@@ -33,7 +33,7 @@ local COMMS_SLEEP = 100 -- (100ms, 2 ticks)
 ---@param iface string
 ---@param type string
 ---@param device table
----@param unit rtu_unit_registry_entry
+---@param unit rtu_registry_entry
 local function handle_unit_mount(smem, println_ts, iface, type, device, unit)
     local sys = smem.rtu_sys
 
@@ -279,7 +279,7 @@ function threads.thread__main(smem)
                             -- find disconnected device
                             if units[i].device == device then
                                 -- will let the PPM prevent crashes, which will indicate failures in MODBUS queries
-                                local unit = units[i]   ---@type rtu_unit_registry_entry
+                                local unit = units[i]
                                 local type_name = types.rtu_type_to_string(unit.type)
 
                                 println_ts(util.c("lost the ", type_name, " on interface ", unit.name))
@@ -332,7 +332,7 @@ function threads.thread__main(smem)
             elseif event == "speaker_audio_empty" then
                 -- handle empty speaker audio buffer
                 for i = 1, #sounders do
-                    local sounder = sounders[i] ---@type rtu_speaker_sounder
+                    local sounder = sounders[i]
                     if sounder.name == param1 then
                         sounder.continue()
                         break
@@ -460,7 +460,7 @@ end
 -- per-unit communications handler thread
 ---@nodiscard
 ---@param smem rtu_shared_memory
----@param unit rtu_unit_registry_entry
+---@param unit rtu_registry_entry
 function threads.thread__unit_comms(smem, unit)
     ---@class parallel_thread
     local public = {}