rsmp 0.48.3 → 0.51.0

data/lib/rsmp/tlc/proxy/control.rb

@@ -6,20 +6,29 @@ module RSMP
       module Control
         # M0001 - Set functional position (NormalControl, YellowFlash, Dark).
         def set_functional_position(status, within:, timeout_minutes: 0)
-          validate_ready 'set functional position'
+          readiness = validate_ready 'set functional position'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           command_list = functional_position_command_list(status, timeout_minutes)
           confirm_status = functional_position_confirm_status(status)
-          collector = send_command_and_collect(command_list, within: within)
-          collector.ok!
-          wait_for_status "functional position #{status}", confirm_status, timeout: within unless confirm_status.empty?
-          { collector: collector }
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            next Result.success(exchange) if confirm_status.empty?
+
+            wait_for_status("functional position #{status}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_functional_position!(...)
+          set_functional_position(...).value!
         end
 
         # M0005 - Set or clear an emergency route.
         def set_emergency_route(route:, active:, within:)
-          validate_ready 'set emergency route'
+          readiness = validate_ready 'set emergency route'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -41,12 +50,18 @@ module RSMP
             'v' => command_value('M0005', 'emergencyroute', route)
           }]
 
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_emergency_route!(...)
+          set_emergency_route(...).value!
         end
 
         # M0007 - Enable or disable fixed-time control.
         def set_fixed_time(status, within:)
-          validate_ready 'set fixed time'
+          readiness = validate_ready 'set fixed time'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -64,13 +79,20 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0009', 'n' => 'status', 's' => [boolean_value(status)] }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status "fixed time #{status}", confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("fixed time #{status}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_fixed_time!(...)
+          set_fixed_time(...).value!
         end
 
         # M0003 - Set traffic situation (activate a specific situation number).
         def set_traffic_situation(situation, within:)
-          validate_ready 'set traffic situation'
+          readiness = validate_ready 'set traffic situation'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -93,13 +115,20 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0015', 'n' => 'status', 's' => integer_value(situation) }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status "traffic situation #{situation}", confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("traffic situation #{situation}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def set_traffic_situation!(...)
+          set_traffic_situation(...).value!
         end
 
         # M0003 - Clear the active traffic situation.
         def unset_traffic_situation(within:)
-          validate_ready 'unset traffic situation'
+          readiness = validate_ready 'unset traffic situation'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -122,8 +151,13 @@ module RSMP
           }]
 
           confirm_status = [{ 'sCI' => 'S0015', 'n' => 'status', 's' => 1 }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status 'traffic situation unset', confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status('traffic situation unset', confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def unset_traffic_situation!(...)
+          unset_traffic_situation(...).value!
         end
 
         private

data/lib/rsmp/tlc/proxy/detectors.rb

@@ -7,7 +7,8 @@ module RSMP
         # M0008 - Force detector logic to a given mode and status.
         # component_id must refer to the detector logic component, not main.
         def force_detector_logic(component_id, status:, mode:, within:)
-          validate_ready 'force detector logic'
+          readiness = validate_ready 'force detector logic'
+          return readiness if readiness.failure?
 
           security_code = security_code_for(2)
 
@@ -27,12 +28,18 @@ module RSMP
             'n' => 'mode',
             'v' => command_value('M0008', 'mode', mode)
           }]
-          send_command_and_collect(command_list, component: component_id, within: within).ok!
+          send_command_and_collect(command_list, component: component_id, within: within)
+        end
+
+        def force_detector_logic!(...)
+          force_detector_logic(...).value!
         end
 
         # M0021 - Set the trigger level for traffic counting.
         def set_trigger_level(status, within:)
-          validate_ready 'set trigger level'
+          readiness = validate_ready 'set trigger level'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -48,7 +55,11 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_trigger_level!(...)
+          set_trigger_level(...).value!
         end
       end
     end

data/lib/rsmp/tlc/proxy/io.rb

@@ -6,7 +6,9 @@ module RSMP
       module IO
         # M0006 - Set a single input to a given status.
         def set_input(input:, status:, within:)
-          validate_ready 'set input'
+          readiness = validate_ready 'set input'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -27,12 +29,18 @@ module RSMP
             'n' => 'input',
             'v' => command_value('M0006', 'input', input)
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_input!(...)
+          set_input(...).value!
         end
 
         # M0013 - Set all inputs via a bit-pattern string.
         def set_inputs(status, within:)
-          validate_ready 'set inputs'
+          readiness = validate_ready 'set inputs'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -48,53 +56,60 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_inputs!(...)
+          set_inputs(...).value!
         end
 
         # M0019 - Force an input to a given value.
         def force_input(input:, status:, value:, within:)
-          validate_ready 'force input'
+          readiness = validate_ready 'force input'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           command_list = force_input_command_list(input, status, value)
           confirm_status = force_input_confirm_status(input, status, value)
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status "force input #{input}", confirm_status, timeout: within
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("force input #{input}", confirm_status, timeout: within).map { exchange }
+          end
+        end
+
+        def force_input!(...)
+          force_input(...).value!
         end
 
         # M0020 - Force an output to a given value.
         def force_output(output:, status:, value:, within:)
-          validate_ready 'force output'
+          readiness = validate_ready 'force output'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
-          security_code = security_code_for(2)
+          send_command_and_collect(force_output_command_list(output, status, value), within: within)
+        end
 
-          command_list = [{
-            'cCI' => 'M0020',
-            'cO' => 'setOutput',
-            'n' => 'status',
-            'v' => command_value('M0020', 'status', status)
-          }, {
-            'cCI' => 'M0020',
-            'cO' => 'setOutput',
-            'n' => 'securityCode',
-            'v' => security_code.to_s
-          }, {
-            'cCI' => 'M0020',
-            'cO' => 'setOutput',
-            'n' => 'output',
-            'v' => command_value('M0020', 'output', output)
-          }, {
-            'cCI' => 'M0020',
-            'cO' => 'setOutput',
-            'n' => 'outputValue',
-            'v' => command_value('M0020', 'outputValue', value)
-          }]
-          send_command_and_collect(command_list, within: within).ok!
+        def force_output!(...)
+          force_output(...).value!
         end
 
         private
 
+        def force_output_command_list(output, status, value)
+          security_code = security_code_for(2)
+          values = { 'status' => status, 'output' => output, 'outputValue' => value }
+          values.map do |name, item|
+            { 'cCI' => 'M0020', 'cO' => 'setOutput', 'n' => name, 'v' => command_value('M0020', name, item) }
+          end.insert(1, {
+                       'cCI' => 'M0020',
+                       'cO' => 'setOutput',
+                       'n' => 'securityCode',
+                       'v' => security_code.to_s
+                     })
+        end
+
         def force_input_command_list(input, status, value)
           security_code = security_code_for(2)
           [

data/lib/rsmp/tlc/proxy/plans.rb

@@ -6,7 +6,9 @@ module RSMP
       module Plans
         # M0014 - Set dynamic bands for a signal plan.
         def set_dynamic_bands(plan:, status:, within:)
-          validate_ready 'set dynamic bands'
+          readiness = validate_ready 'set dynamic bands'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -27,12 +29,14 @@ module RSMP
             'n' => 'plan',
             'v' => command_value('M0014', 'plan', plan)
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
         end
 
         # M0023 - Set timeout for dynamic bands.
         def set_dynamic_bands_timeout(status, within:)
-          validate_ready 'set dynamic bands timeout'
+          readiness = validate_ready 'set dynamic bands timeout'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -48,12 +52,14 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
         end
 
         # M0015 - Set offset for a signal plan.
         def set_offset(plan:, offset:, within:)
-          validate_ready 'set offset'
+          readiness = validate_ready 'set offset'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -74,12 +80,14 @@ module RSMP
             'n' => 'plan',
             'v' => command_value('M0015', 'plan', plan)
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
         end
 
         # Set the timeplan (signal plan) on the remote TLC.
         def set_timeplan(plan_nr, within:)
-          validate_ready 'set timeplan'
+          readiness = validate_ready 'set timeplan'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -101,13 +109,16 @@ module RSMP
             'v' => command_value('M0002', 'timeplan', plan_nr)
           }]
           confirm_status = [{ 'sCI' => 'S0014', 'n' => 'status', 's' => integer_value(plan_nr) }]
-          send_command_and_collect(command_list, within: within).ok!
-          wait_for_status("timeplan #{plan_nr}", confirm_status, timeout: within)
+          send_command_and_collect(command_list, within: within).and_then do |exchange|
+            wait_for_status("timeplan #{plan_nr}", confirm_status, timeout: within).map { exchange }
+          end
         end
 
         # M0016 - Set week table (mapping week days to traffic situations).
         def set_week_table(status, within:)
-          validate_ready 'set week table'
+          readiness = validate_ready 'set week table'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -123,12 +134,14 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within:).ok!
+          send_command_and_collect(command_list, within:)
         end
 
         # M0017 - Set day table (mapping time periods to signal plans).
         def set_day_table(status, within:)
-          validate_ready 'set day table'
+          readiness = validate_ready 'set day table'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -144,12 +157,14 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, within:).ok!
+          send_command_and_collect(command_list, within:)
         end
 
         # M0018 - Set cycle time for a signal plan.
         def set_cycle_time(plan:, cycle_time:, within:)
-          validate_ready 'set cycle time'
+          readiness = validate_ready 'set cycle time'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           security_code = security_code_for(2)
@@ -170,12 +185,13 @@ module RSMP
             'n' => 'plan',
             'v' => command_value('M0018', 'plan', plan)
           }]
-          send_command_and_collect(command_list, within:).ok!
+          send_command_and_collect(command_list, within:)
         end
 
         # M0010 - Order signal start for a signal group component.
         def order_signal_start(component_id, within:)
-          validate_ready 'order signal start'
+          readiness = validate_ready 'order signal start'
+          return readiness if readiness.failure?
 
           security_code = security_code_for(2)
 
@@ -190,12 +206,13 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, component: component_id, within:).ok!
+          send_command_and_collect(command_list, component: component_id, within:)
         end
 
         # M0011 - Order signal stop for a signal group component.
         def order_signal_stop(component_id, within:)
-          validate_ready 'order signal stop'
+          readiness = validate_ready 'order signal stop'
+          return readiness if readiness.failure?
 
           security_code = security_code_for(2)
 
@@ -210,7 +227,7 @@ module RSMP
             'n' => 'securityCode',
             'v' => security_code.to_s
           }]
-          send_command_and_collect(command_list, component: component_id, within:).ok!
+          send_command_and_collect(command_list, component: component_id, within:)
         end
       end
     end

data/lib/rsmp/tlc/proxy/plans_bang.rb

@@ -0,0 +1,44 @@
+module RSMP
+  module TLC
+    module Proxy
+      # Explicit exception-raising variants of finite plan operations.
+      module PlansBang
+        def set_dynamic_bands!(...)
+          set_dynamic_bands(...).value!
+        end
+
+        def set_dynamic_bands_timeout!(...)
+          set_dynamic_bands_timeout(...).value!
+        end
+
+        def set_offset!(...)
+          set_offset(...).value!
+        end
+
+        def set_timeplan!(...)
+          set_timeplan(...).value!
+        end
+
+        def set_week_table!(...)
+          set_week_table(...).value!
+        end
+
+        def set_day_table!(...)
+          set_day_table(...).value!
+        end
+
+        def set_cycle_time!(...)
+          set_cycle_time(...).value!
+        end
+
+        def order_signal_start!(...)
+          order_signal_start(...).value!
+        end
+
+        def order_signal_stop!(...)
+          order_signal_stop(...).value!
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/tlc/proxy/status.rb

@@ -4,25 +4,28 @@ module RSMP
       # Status reading and waiting methods for a remote TLC.
       # Covers status subscriptions, group waits, and plan/band reading.
       module Status
-        # Fetch the current signal plan from the remote TLC.
+        # Fetch the current signal plan from the remote TLC. Returns Result<Hash>.
         def fetch_signal_plan(options: {})
-          validate_ready 'fetch signal plan'
           timeout = options[:timeout] || @timeouts['status_response']
-          collector = request_status_and_collect({ S0014: %i[status source] }, within: timeout)
-          collector.ok!
-          collector.messages.last.attributes['sS'].to_h do |item|
-            [item['n'], item['s']]
+          request_status_and_collect({ S0014: %i[status source] }, within: timeout).map do |exchange|
+            exchange.collection.messages.last.attributes['sS'].to_h do |item|
+              [item['n'], item['s']]
+            end
           end
         end
 
+        def fetch_signal_plan!(...)
+          fetch_signal_plan(...).value!
+        end
+
         # Subscribe to one or more statuses and wait until they match the expected values.
-        # Raises RSMP::TimeoutError if the values don't match within the timeout.
-        #
         # status_list items: { 'sCI' => ..., 'n' => ..., 's' => <expected value or Regexp> }
         # component_id defaults to the main TLC component.
         # timeout defaults to @timeouts['command'].
         def wait_for_status(description, status_list, update_rate: 0, timeout: nil, component_id: nil)
-          validate_ready 'wait for status'
+          readiness = validate_ready 'wait for status'
+          return readiness if readiness.failure?
+
           component_id ||= main.c_id
           timeout ||= @timeouts['command']
 
@@ -35,13 +38,17 @@ module RSMP
           log "Wait for #{description}", level: :debug
 
           begin
-            subscribe_to_status_and_collect(subscribe_list, component: component_id, within: timeout).ok!
+            subscribe_to_status_and_collect(subscribe_list, component: component_id, within: timeout)
           ensure
             unsubscribe_list = status_list.map { |item| item.slice('sCI', 'n') }
             unsubscribe_to_status unsubscribe_list, component: component_id
           end
         end
 
+        def wait_for_status!(...)
+          wait_for_status(...).value!
+        end
+
         # Wait for all signal groups to match state (as regex string, e.g. 'c' for yellow flash).
         def wait_for_groups(state, timeout:)
           regex = /^#{state}+$/
@@ -52,6 +59,10 @@ module RSMP
           )
         end
 
+        def wait_for_groups!(...)
+          wait_for_groups(...).value!
+        end
+
         # Wait for the TLC to return to normal control mode (functional position NormalControl,
         # yellow flash off, startup mode off).
         def wait_for_normal_control(timeout: nil)
@@ -66,36 +77,49 @@ module RSMP
           )
         end
 
+        def wait_for_normal_control!(...)
+          wait_for_normal_control(...).value!
+        end
+
         # Read cycle times for all plans via S0028.
         # Returns a hash of plan_nr (Integer) => cycle_time (Integer, seconds).
         def read_cycle_times(options: {})
-          validate_ready 'read cycle times'
           timeout = options[:timeout] || @timeouts['status_response']
-          collector = request_status_and_collect({ S0028: [:status] }, within: timeout)
-          collector.ok!
-          status_items(collector.messages.first.attributes['sS'].first['s']).to_h do |item|
-            item.split('-').map(&:to_i)
+          request_status_and_collect({ S0028: [:status] }, within: timeout).map do |exchange|
+            status_items(exchange.collection.messages.first.attributes['sS'].first['s']).to_h do |item|
+              item.split('-').map(&:to_i)
+            end
           end
         end
 
+        def read_cycle_times!(...)
+          read_cycle_times(...).value!
+        end
+
         # Read the current signal plan number via S0014.
         # Returns the plan number as an Integer.
         def read_current_plan(options: {})
-          validate_ready 'read current plan'
           timeout = options[:timeout] || @timeouts['status_response']
-          collector = request_status_and_collect({ S0014: [:status] }, within: timeout)
-          collector.ok!
-          collector.messages.first.attributes['sS'].first['s'].to_i
+          request_status_and_collect({ S0014: [:status] }, within: timeout).map do |exchange|
+            exchange.collection.messages.first.attributes['sS'].first['s'].to_i
+          end
+        end
+
+        def read_current_plan!(...)
+          read_current_plan(...).value!
         end
 
         # Read the value of a single dynamic band for a given plan and band index via S0023.
         # Returns the band value as an Integer, or nil if not found.
         def read_dynamic_band(plan:, band:, options: {})
-          validate_ready 'read dynamic band'
           timeout = options[:timeout] || @timeouts['status_response']
-          collector = request_status_and_collect({ S0023: [:status] }, within: timeout)
-          collector.ok!
-          extract_band_value(collector, plan, band)
+          request_status_and_collect({ S0023: [:status] }, within: timeout).map do |exchange|
+            extract_band_value(exchange.collection, plan, band)
+          end
+        end
+
+        def read_dynamic_band!(...)
+          read_dynamic_band(...).value!
         end
 
         private

data/lib/rsmp/tlc/proxy/system.rb

@@ -7,7 +7,9 @@ module RSMP
         # M0103 - Change security code for a given level.
         # Does not use security_code_for since the codes are passed explicitly.
         def set_security_code(level:, old_code:, new_code:, within:)
-          validate_ready 'set security code'
+          readiness = validate_ready 'set security code'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
           command_list = [{
@@ -26,15 +28,25 @@ module RSMP
             'n' => 'newSecurityCode',
             'v' => new_code.to_s
           }]
-          send_command_and_collect(command_list, within: within).ok!
+          send_command_and_collect(command_list, within: within)
+        end
+
+        def set_security_code!(...)
+          set_security_code(...).value!
         end
 
         # M0104 - Set the clock on the remote TLC. clock must respond to year/month/day/hour/min/sec.
         def set_clock(clock, within:)
-          validate_ready 'set clock'
+          readiness = validate_ready 'set clock'
+          return readiness if readiness.failure?
+
           raise 'TLC main component not found' unless main
 
-          send_command_and_collect(clock_command_list(clock), within: within).ok!
+          send_command_and_collect(clock_command_list(clock), within: within)
+        end
+
+        def set_clock!(...)
+          set_clock(...).value!
         end
 
         private