#545 plc type annotation updates and refactoring

reactor-plc/config/check.lua

@@ -175,7 +175,7 @@ local check = {}
 ---@param main_pane graphics_element
 ---@param settings_cfg plc_config
 ---@param check_sys graphics_element
----@param style table
+---@param style { [string]: cpair }
 function check.create(main_pane, settings_cfg, check_sys, style)
     local bw_fg_bg      = style.bw_fg_bg
     local g_lg_fg_bg    = style.g_lg_fg_bg

reactor-plc/config/system.lua

@@ -62,16 +62,13 @@ local system = {}
 -- create the system configuration view
 ---@param tool_ctl _plc_cfg_tool_ctl
 ---@param main_pane graphics_element
----@param cfg_sys table
+---@param cfg_sys [ plc_config, plc_config, plc_config, table, function ]
----@param divs table
+---@param divs graphics_element[]
----@param style table
+---@param style { [string]: cpair }
 ---@param exit function
 function system.create(tool_ctl, main_pane, cfg_sys, divs, style, exit)
-    ---@type plc_config, plc_config, plc_config, table, function
+    local settings_cfg, ini_cfg, tmp_cfg, fields, load_settings = cfg_sys[1], cfg_sys[2], cfg_sys[3], cfg_sys[4], cfg_sys[5]
-    local settings_cfg, ini_cfg, tmp_cfg, fields, load_settings = table.unpack(cfg_sys)
+    local plc_cfg, net_cfg, log_cfg, clr_cfg, summary = divs[1], divs[2], divs[3], divs[4], divs[5]
-
-    ---@type graphics_element, graphics_element, graphics_element, graphics_element, graphics_element
-    local plc_cfg, net_cfg, log_cfg, clr_cfg, summary = table.unpack(divs)
 
     local bw_fg_bg      = style.bw_fg_bg
     local g_lg_fg_bg    = style.g_lg_fg_bg

reactor-plc/databus.lua

@@ -77,7 +77,7 @@ end
 
 -- transmit RPS data across the bus
 ---@param tripped boolean RPS tripped
----@param status table RPS status
+---@param status boolean[] RPS status
 ---@param emer_cool_active boolean RPS activated the emergency coolant
 function databus.tx_rps(tripped, status, emer_cool_active)
     databus.ps.publish("rps_scram", tripped)

reactor-plc/plc.lua

@@ -110,22 +110,8 @@ end
 ---@param reactor table
 ---@param is_formed boolean
 function plc.rps_init(reactor, is_formed)
-    local state_keys = {
-        high_dmg = 1,
-        high_temp = 2,
-        low_coolant = 3,
-        ex_waste = 4,
-        ex_hcoolant = 5,
-        no_fuel = 6,
-        fault = 7,
-        timeout = 8,
-        manual = 9,
-        automatic = 10,
-        sys_fail = 11,
-        force_disabled = 12
-    }
-
     local self = {
+        ---@type boolean[] check states
         state = { false, false, false, false, false, false, false, false, false, false, false, false },
         reactor_enabled = false,
         enabled_at = 0,
@@ -136,12 +122,27 @@ function plc.rps_init(reactor, is_formed)
         trip_cause = "ok"       ---@type rps_trip_cause
     }
 
+    local CHK = {
+        HIGH_DMG = 1,
+        HIGH_TEMP = 2,
+        LOW_COOLANT = 3,
+        EX_WASTE = 4,
+        EX_HCOOLANT = 5,
+        NO_FUEL = 6,
+        FAULT = 7,
+        TIMEOUT = 8,
+        MANUAL = 9,
+        AUTOMATIC = 10,
+        SYS_FAIL = 11,
+        FORCE_DISABLED = 12
+    }
+
     -- PRIVATE FUNCTIONS --
 
     -- set reactor access fault flag
     local function _set_fault()
         if reactor.__p_last_fault() ~= "Terminated" then
-            self.state[state_keys.fault] = true
+            self.state[CHK.FAULT] = true
         end
     end
 
@@ -203,8 +204,8 @@ function plc.rps_init(reactor, is_formed)
         end
 
         -- always update, since some ppm failures constitute not being formed
-        if not self.state[state_keys.sys_fail] then
+        if not self.state[CHK.SYS_FAIL] then
-            self.state[state_keys.sys_fail] = not self.formed
+            self.state[CHK.SYS_FAIL] = not self.formed
         end
     end
 
@@ -214,8 +215,8 @@ function plc.rps_init(reactor, is_formed)
         if _check_and_handle_ppm_call(disabled) then
             self.force_disabled = disabled
 
-            if not self.state[state_keys.force_disabled] then
+            if not self.state[CHK.FORCE_DISABLED] then
-                self.state[state_keys.force_disabled] = disabled
+                self.state[CHK.FORCE_DISABLED] = disabled
             end
         end
     end
@@ -223,8 +224,8 @@ function plc.rps_init(reactor, is_formed)
     -- check for high damage
     local function _high_damage()
         local damage_percent = reactor.getDamagePercent()
-        if _check_and_handle_ppm_call(damage_percent) and not self.state[state_keys.high_dmg] then
+        if _check_and_handle_ppm_call(damage_percent) and not self.state[CHK.HIGH_DMG] then
-            self.state[state_keys.high_dmg] = damage_percent >= RPS_LIMITS.MAX_DAMAGE_PERCENT
+            self.state[CHK.HIGH_DMG] = damage_percent >= RPS_LIMITS.MAX_DAMAGE_PERCENT
         end
     end
 
@@ -232,40 +233,40 @@ function plc.rps_init(reactor, is_formed)
     local function _high_temp()
         -- mekanism: MAX_DAMAGE_TEMPERATURE = 1200K
         local temp = reactor.getTemperature()
-        if _check_and_handle_ppm_call(temp) and not self.state[state_keys.high_temp] then
+        if _check_and_handle_ppm_call(temp) and not self.state[CHK.HIGH_TEMP] then
-            self.state[state_keys.high_temp] = temp >= RPS_LIMITS.MAX_DAMAGE_TEMPERATURE
+            self.state[CHK.HIGH_TEMP] = temp >= RPS_LIMITS.MAX_DAMAGE_TEMPERATURE
         end
     end
 
     -- check if there is very low coolant
     local function _low_coolant()
         local coolant_filled = reactor.getCoolantFilledPercentage()
-        if _check_and_handle_ppm_call(coolant_filled) and not self.state[state_keys.low_coolant] then
+        if _check_and_handle_ppm_call(coolant_filled) and not self.state[CHK.LOW_COOLANT] then
-            self.state[state_keys.low_coolant] = coolant_filled < RPS_LIMITS.MIN_COOLANT_FILL
+            self.state[CHK.LOW_COOLANT] = coolant_filled < RPS_LIMITS.MIN_COOLANT_FILL
         end
     end
 
     -- check for excess waste (>80% filled)
     local function _excess_waste()
         local w_filled = reactor.getWasteFilledPercentage()
-        if _check_and_handle_ppm_call(w_filled) and not self.state[state_keys.ex_waste] then
+        if _check_and_handle_ppm_call(w_filled) and not self.state[CHK.EX_WASTE] then
-            self.state[state_keys.ex_waste] = w_filled > RPS_LIMITS.MAX_WASTE_FILL
+            self.state[CHK.EX_WASTE] = w_filled > RPS_LIMITS.MAX_WASTE_FILL
         end
     end
 
     -- check for heated coolant backup (>95% filled)
     local function _excess_heated_coolant()
         local hc_filled = reactor.getHeatedCoolantFilledPercentage()
-        if _check_and_handle_ppm_call(hc_filled) and not self.state[state_keys.ex_hcoolant] then
+        if _check_and_handle_ppm_call(hc_filled) and not self.state[CHK.EX_HCOOLANT] then
-            self.state[state_keys.ex_hcoolant] = hc_filled > RPS_LIMITS.MAX_HEATED_COLLANT_FILL
+            self.state[CHK.EX_HCOOLANT] = hc_filled > RPS_LIMITS.MAX_HEATED_COLLANT_FILL
         end
     end
 
     -- check if there is no fuel
     local function _insufficient_fuel()
         local fuel = reactor.getFuelFilledPercentage()
-        if _check_and_handle_ppm_call(fuel) and not self.state[state_keys.no_fuel] then
+        if _check_and_handle_ppm_call(fuel) and not self.state[CHK.NO_FUEL] then
-            self.state[state_keys.no_fuel] = fuel <= RPS_LIMITS.NO_FUEL_FILL
+            self.state[CHK.NO_FUEL] = fuel <= RPS_LIMITS.NO_FUEL_FILL
         end
     end
 
@@ -287,23 +288,23 @@ function plc.rps_init(reactor, is_formed)
 
     -- trip for a PLC comms timeout
     function public.trip_timeout()
-        self.state[state_keys.timeout] = true
+        self.state[CHK.TIMEOUT] = true
     end
 
     -- manually SCRAM the reactor
     function public.trip_manual()
-        self.state[state_keys.manual] = true
+        self.state[CHK.MANUAL] = true
     end
 
     -- automatic SCRAM commanded by supervisor
     function public.trip_auto()
-        self.state[state_keys.automatic] = true
+        self.state[CHK.AUTOMATIC] = true
     end
 
     -- trip for unformed reactor
     function public.trip_sys_fail()
-        self.state[state_keys.fault] = true
+        self.state[CHK.FAULT] = true
-        self.state[state_keys.sys_fail] = true
+        self.state[CHK.SYS_FAIL] = true
     end
 
     -- SCRAM the reactor now<br>
@@ -350,7 +351,7 @@ function plc.rps_init(reactor, is_formed)
     function public.auto_activate()
         -- clear automatic SCRAM if it was the cause
         if self.tripped and self.trip_cause == "automatic" then
-            self.state[state_keys.automatic] = true
+            self.state[CHK.AUTOMATIC] = true
             self.trip_cause = RPS_TRIP_CAUSE.OK
             self.tripped = false
 
@@ -388,40 +389,40 @@ function plc.rps_init(reactor, is_formed)
         -- check system states in order of severity
         if self.tripped then
             status = self.trip_cause
-        elseif self.state[state_keys.sys_fail] then
+        elseif self.state[CHK.SYS_FAIL] then
             log.warning("RPS: system failure, reactor not formed")
             status = RPS_TRIP_CAUSE.SYS_FAIL
-        elseif self.state[state_keys.force_disabled] then
+        elseif self.state[CHK.FORCE_DISABLED] then
             log.warning("RPS: reactor was force disabled")
             status = RPS_TRIP_CAUSE.FORCE_DISABLED
-        elseif self.state[state_keys.high_dmg] then
+        elseif self.state[CHK.HIGH_DMG] then
             log.warning("RPS: high damage")
             status = RPS_TRIP_CAUSE.HIGH_DMG
-        elseif self.state[state_keys.high_temp] then
+        elseif self.state[CHK.HIGH_TEMP] then
             log.warning("RPS: high temperature")
             status = RPS_TRIP_CAUSE.HIGH_TEMP
-        elseif self.state[state_keys.low_coolant] then
+        elseif self.state[CHK.LOW_COOLANT] then
             log.warning("RPS: low coolant")
             status = RPS_TRIP_CAUSE.LOW_COOLANT
-        elseif self.state[state_keys.ex_waste] then
+        elseif self.state[CHK.EX_WASTE] then
             log.warning("RPS: full waste")
             status = RPS_TRIP_CAUSE.EX_WASTE
-        elseif self.state[state_keys.ex_hcoolant] then
+        elseif self.state[CHK.EX_HCOOLANT] then
             log.warning("RPS: heated coolant backup")
             status = RPS_TRIP_CAUSE.EX_HCOOLANT
-        elseif self.state[state_keys.no_fuel] then
+        elseif self.state[CHK.NO_FUEL] then
             log.warning("RPS: no fuel")
             status = RPS_TRIP_CAUSE.NO_FUEL
-        elseif self.state[state_keys.fault] then
+        elseif self.state[CHK.FAULT] then
             log.warning("RPS: reactor access fault")
             status = RPS_TRIP_CAUSE.FAULT
-        elseif self.state[state_keys.timeout] then
+        elseif self.state[CHK.TIMEOUT] then
             log.warning("RPS: supervisor connection timeout")
             status = RPS_TRIP_CAUSE.TIMEOUT
-        elseif self.state[state_keys.manual] then
+        elseif self.state[CHK.MANUAL] then
             log.warning("RPS: manual SCRAM requested")
             status = RPS_TRIP_CAUSE.MANUAL
-        elseif self.state[state_keys.automatic] then
+        elseif self.state[CHK.AUTOMATIC] then
             log.warning("RPS: automatic SCRAM requested")
             status = RPS_TRIP_CAUSE.AUTOMATIC
         else
@@ -449,7 +450,7 @@ function plc.rps_init(reactor, is_formed)
         end
 
         -- update emergency coolant control if configured
-        _set_emer_cool(self.state[state_keys.low_coolant])
+        _set_emer_cool(self.state[CHK.LOW_COOLANT])
 
         -- report RPS status
         databus.tx_rps(self.tripped, self.state, self.emer_cool_active)
@@ -465,7 +466,7 @@ function plc.rps_init(reactor, is_formed)
     ---@nodiscard
     function public.get_trip_cause() return self.trip_cause end
     ---@nodiscard
-    function public.is_low_coolant() return self.states[state_keys.low_coolant] end
+    function public.is_low_coolant() return self.states[CHK.LOW_COOLANT] end
 
     ---@nodiscard
     function public.is_active() return self.reactor_enabled end
@@ -495,16 +496,16 @@ function plc.rps_init(reactor, is_formed)
         self.tripped = false
         self.trip_cause = RPS_TRIP_CAUSE.OK
 
-        self.state[state_keys.fault] = false
+        self.state[CHK.FAULT] = false
-        self.state[state_keys.sys_fail] = false
+        self.state[CHK.SYS_FAIL] = false
 
         log.info("RPS: partial reset on formed")
     end
 
     -- reset the automatic and timeout trip flags, then clear trip if that was the trip cause
     function public.auto_reset()
-        self.state[state_keys.automatic] = false
+        self.state[CHK.AUTOMATIC] = false
-        self.state[state_keys.timeout] = false
+        self.state[CHK.TIMEOUT] = false
 
         if self.trip_cause == RPS_TRIP_CAUSE.AUTOMATIC or self.trip_cause == RPS_TRIP_CAUSE.TIMEOUT then
             self.trip_cause = RPS_TRIP_CAUSE.OK

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.8.8"
+local R_PLC_VERSION = "v1.8.9"
 
 local println = util.println
 local println_ts = util.println_ts

reactor-plc/threads.lua

@@ -628,9 +628,10 @@ function threads.thread__setpoint_control(smem)
             local reactor = plc_dev.reactor
 
             if plc_state.init_ok and (not plc_state.no_reactor) then
+                ---@cast reactor table won't be nil
+
                 -- check if we should start ramping
                 if setpoints.burn_rate_en and (setpoints.burn_rate ~= last_burn_sp) then
----@diagnostic disable-next-line: need-check-nil
                     local cur_burn_rate = reactor.getBurnRate()
 
                     if (type(cur_burn_rate) == "number") and (setpoints.burn_rate ~= cur_burn_rate) and rps.is_active() then
@@ -644,7 +645,6 @@ function threads.thread__setpoint_control(smem)
                             log.debug(util.c("SPCTL: starting burn rate ramp from ", cur_burn_rate, " mB/t to ", setpoints.burn_rate, " mB/t"))
                         else
                             log.debug(util.c("SPCTL: setting burn rate directly to ", setpoints.burn_rate, " mB/t"))
----@diagnostic disable-next-line: need-check-nil
                             reactor.setBurnRate(setpoints.burn_rate)
                         end
                     end
@@ -658,7 +658,6 @@ function threads.thread__setpoint_control(smem)
                     -- adjust burn rate (setpoints.burn_rate)
                     if setpoints.burn_rate_en then
                         if rps.is_active() then
----@diagnostic disable-next-line: need-check-nil
                             local current_burn_rate = reactor.getBurnRate()
 
                             -- we yielded, check enable again
@@ -679,7 +678,6 @@ function threads.thread__setpoint_control(smem)
                                 running = running or (new_burn_rate ~= setpoints.burn_rate)
 
                                 -- set the burn rate
----@diagnostic disable-next-line: need-check-nil
                                 reactor.setBurnRate(new_burn_rate)
                             end
                         else