signalbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0183b44f559e1894e69e638f2dd97aa215f124a16a97b6237fa78f2ef10b9e70'
+  data.tar.gz: 24e6bc0cac766f39f458a0f6edcc9556ca86abc110ac91f6cbc9c799aa0acb82
+SHA512:
+  metadata.gz: 69b1acbec07598d24e7870aa920170961613f5091343e7100d794973a65e5ebe0120782ecda4020e571f4d70f5e70ee0404ef2761eab0f3b58d07d7098c696db
+  data.tar.gz: d85c9f4b20b85fcb46752139ebb5061644c6102689c832741422b8949f88af4f2ccd0e4d37f591d2e111aa16774c402b952162cc216d4472674994bd1ce3f366

data/README.md

@@ -0,0 +1,24 @@
+# 🚂 Signalbox
+
+A system for operating model trains powered by DCC.
+
+## Installation
+
+`gem install signalbox`
+
+## Layout Setup
+
+See `examples/layouts/`
+
+## Running the server
+
+`signalbox-server`
+
+## Running the conductor TUI
+
+`signalbox-conductor`
+
+## Notes
+
+This project is unrelated to and unaffiliated with Signalbox.io and related 
+British Railway data projects.

data/exe/signalbox-conductor

@@ -0,0 +1,210 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "signalbox"
+require "logger"
+require "optparse"
+require "json"
+require "io/console"
+
+# Parse command line arguments
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: signalbox-conductor [options]"
+
+  opts.on("--version", "Show version") do
+    puts "SignalBox version #{SignalBox::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+end.parse!
+
+host = ARGV[0] || "localhost"
+port = 4040
+
+puts "Connecting to #{host}:#{port}..."
+socket = TCPSocket.new host, port
+puts "Connected!\n"
+
+# ANSI escape codes
+CLEAR_SCREEN = "\e[2J\e[H"
+BOLD = "\e[1m"
+RESET = "\e[0m"
+GREEN = "\e[32m"
+YELLOW = "\e[33m"
+BLUE = "\e[34m"
+CYAN = "\e[36m"
+
+def format_speed(speed)
+  sprintf("%.1f", speed)
+end
+
+def format_cab_status(cab, selected: false)
+  location = cab["location"] ? cab["location"]["name"] : "Unknown"
+  current = format_speed(cab["current_speed"])
+  target = cab["target_speed"]
+  direction = cab["direction_name"]
+
+  status_line = sprintf("%-20s | %-25s | Speed: %5s / %-3d | %s",
+    cab["name"],
+    location,
+    current,
+    target,
+    direction.capitalize
+  )
+
+  # Add selection indicator
+  if selected
+    status_line = "▶ #{status_line}"
+  else
+    status_line = "  #{status_line}"
+  end
+
+  # Color code based on speed status
+  if cab["current_speed"] < cab["target_speed"]
+    "#{GREEN}#{status_line}#{RESET}"
+  elsif cab["current_speed"] > cab["target_speed"]
+    "#{YELLOW}#{status_line}#{RESET}"
+  else
+    status_line
+  end
+end
+
+def read_nonblock_char
+  if IO.select([$stdin], nil, nil, 0)
+    c = $stdin.getch
+
+    # Handle arrow keys (escape sequences)
+    if c == "\e"
+      c2 = $stdin.getch
+      c3 = $stdin.getch
+      if c2 == "["
+        case c3
+        when "A" then return :up
+        when "B" then return :down
+        when "C" then return :right
+        when "D" then return :left
+        end
+      end
+    end
+
+    return c
+  end
+  nil
+end
+
+# Helper to print with proper line endings in raw mode
+def print_line(str = "")
+  print str + "\r\n"
+end
+
+# Set terminal to raw mode for keyboard input
+$stdin.raw!
+$stdin.echo = false
+
+selected_cab_index = 0
+last_status_time = Time.now
+data = nil
+
+begin
+  loop do
+    # Fetch status every second
+    if Time.now - last_status_time >= 1
+      socket.puts "STATUS"
+      response = socket.gets
+      last_status_time = Time.now
+
+      begin
+        data = JSON.parse(response)
+
+        # Clear screen and move cursor to top
+        print CLEAR_SCREEN
+
+        # Header
+        print_line "#{BOLD}#{BLUE}═══════════════════════════════════════════════════════════════════════════#{RESET}"
+        print_line "#{BOLD}#{BLUE}  SignalBox Conductor - Live Status Monitor#{RESET}"
+        print_line "#{BOLD}#{BLUE}═══════════════════════════════════════════════════════════════════════════#{RESET}"
+        print_line
+
+        # Layout info
+        print_line "#{BOLD}Layout:#{RESET} #{data["layout"]["name"]}"
+        print_line
+
+        # Cabs header
+        print_line "#{BOLD}#{CYAN}Cabs:#{RESET}"
+        print_line "#{'-' * 79}"
+
+        if data["cabs"].empty?
+          print_line "  No cabs configured"
+        else
+          # Ensure selected index is valid
+          selected_cab_index = 0 if selected_cab_index >= data["cabs"].length
+          selected_cab_index = data["cabs"].length - 1 if selected_cab_index < 0
+
+          data["cabs"].each_with_index do |cab, idx|
+            print_line format_cab_status(cab, selected: idx == selected_cab_index)
+          end
+        end
+
+        print_line
+        print_line "#{'-' * 79}"
+        print_line "#{GREEN}●#{RESET} Accelerating  #{YELLOW}●#{RESET} Decelerating  ⚪ At target speed"
+        print_line
+        print_line "Controls: ↑/↓ Adjust speed  ←/→ Select cab  X Stop  Q/Ctrl+C Exit"
+
+      rescue JSON::ParserError => e
+        print_line "#{YELLOW}Warning: Failed to parse response#{RESET}"
+      end
+    end
+
+    # Check for keyboard input
+    key = read_nonblock_char
+
+    if key && data && !data["cabs"].empty?
+      selected_cab = data["cabs"][selected_cab_index]
+
+      case key
+      when :up
+        # Increase target speed
+        new_speed = selected_cab["target_speed"] + 1
+        socket.puts "SET_TARGET_SPEED #{selected_cab["address"]} #{new_speed}"
+        socket.gets # Read OK/ERROR response
+
+      when :down
+        # Decrease target speed
+        new_speed = [selected_cab["target_speed"] - 1, 0].max
+        socket.puts "SET_TARGET_SPEED #{selected_cab["address"]} #{new_speed}"
+        socket.gets # Read OK/ERROR response
+
+      when :left
+        # Select previous cab
+        selected_cab_index = (selected_cab_index - 1) % data["cabs"].length
+
+      when :right
+        # Select next cab
+        selected_cab_index = (selected_cab_index + 1) % data["cabs"].length
+
+      when "x", "X"
+        # Stop cab (set target speed to 0)
+        socket.puts "SET_TARGET_SPEED #{selected_cab["address"]} 0"
+        socket.gets # Read OK/ERROR response
+
+      when "\u0003", "q", "Q" # Ctrl+C or 'q'/'Q'
+        break
+      end
+    end
+
+    sleep 0.05 # Small sleep to reduce CPU usage
+  end
+ensure
+  # Restore terminal settings
+  $stdin.cooked!
+  $stdin.echo = true
+  puts "\nExiting..."
+end
+

data/exe/signalbox-server

@@ -0,0 +1,165 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "signalbox"
+require "logger"
+require "optparse"
+
+# Parse command line arguments
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: signalbox-server [options]"
+
+  opts.on("--layout FILE", "Layout file to load (default: main.layout.rb)") do |file|
+    options[:layout] = file
+  end
+
+  opts.on("-l", "--logfile FILE", "Log file path (default: stdout)") do |file|
+    options[:logfile] = file
+  end
+
+  opts.on("--version", "Show version") do
+    puts "SignalBox version #{SignalBox::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+end.parse!
+
+LAYOUT_FILE = options[:layout] || "main.layout.rb"
+
+# Check if layout file exists
+unless File.exist?(LAYOUT_FILE)
+  puts "Error: Layout file '#{LAYOUT_FILE}' not found."
+  puts "Please specify a layout file using --layout option."
+  puts "Example: signalbox-server --layout path/to/layout.rb"
+  exit 1
+end
+
+SENSOR_PORT = ENV.fetch("SENSOR_PORT", "4040").to_i
+
+# Setup logger
+log_output = options[:logfile] ? options[:logfile] : STDOUT
+$logger = Logger.new(log_output)
+$logger.level = Logger::DEBUG
+
+$logger.info ""
+$logger.info "################################"
+$logger.info "SIGNALBOX SERVER STARTING"
+$logger.info "Version: #{SignalBox::VERSION}"
+
+# Load layout definition
+layout = SignalBox::LayoutLoader.load(LAYOUT_FILE, logger: $logger)
+
+# Get DCC connection from layout
+unless layout.dcc
+  $logger.error "Layout does not define a DCC controller."
+  $logger.error "Please add a 'dcc' block to your layout file."
+  puts "Error: Layout file must include a 'dcc' block defining the DCC controller."
+  puts "Example:"
+  puts "  dcc do"
+  puts "    host '192.168.0.22'"
+  puts "    port 2560"
+  puts "  end"
+  exit 1
+end
+
+dcc = layout.dcc
+
+# Mutex for thread-safe layout controller access
+layout_controller_mutex = Mutex.new
+
+layout_controller = SignalBox::LayoutController.new(
+  layout: layout,
+  dcc: dcc,
+  mutex: layout_controller_mutex,
+  logger: $logger
+)
+
+layout_controller.start
+
+# Initialize variables for shutdown handler
+control_loop_thread = nil
+server = nil
+
+# Graceful shutdown handler
+def shutdown(control_loop_thread, layout_controller, dcc, server, logger)
+  logger.info ""
+  logger.info "################################"
+  logger.info "SIGNALBOX SERVER SHUTTING DOWN"
+  logger.info "################################"
+
+  # Stop control loop
+  if control_loop_thread && control_loop_thread.alive?
+    logger.info "[SHUTDOWN] Stopping control loop..."
+    control_loop_thread.kill
+  end
+
+  # Emergency stop (turns off track power)
+  logger.info "[SHUTDOWN] Turning off track power..."
+  layout_controller.emergency_stop
+
+  # Close DCC connection
+  logger.info "[SHUTDOWN] Closing DCC connection..."
+  dcc.close
+
+  # Close TCP server
+  if server && !server.closed?
+    logger.info "[SHUTDOWN] Closing sensor server..."
+    server.close
+  end
+
+  logger.info "[SHUTDOWN] Shutdown complete"
+end
+
+# Set up signal trap to raise Interrupt
+Signal.trap("INT") { Thread.main.raise(Interrupt) }
+Signal.trap("TERM") { Thread.main.raise(Interrupt) }
+
+# 10 Hz control loop
+control_loop_thread = Thread.new do
+  last_tick_time = Time.now
+  $logger.info "[CONTROL LOOP] Starting 10 Hz control loop"
+
+  loop do
+    sleep(0.1)  # 10 Hz = 100ms interval
+
+    current_time = Time.now
+    elapsed_time = current_time - last_tick_time
+    last_tick_time = current_time
+
+    layout_controller_mutex.synchronize do
+      layout_controller.tick(elapsed_time)
+    end
+  end
+end
+control_loop_thread.abort_on_exception = true
+$logger.info "[CONTROL LOOP] Control loop thread started"
+
+HOST = "0.0.0.0"
+
+# Create sensor client handler
+sensor_handler = SignalBox::SensorClientHandler.new(
+  layout_controller: layout_controller,
+  mutex: layout_controller_mutex,
+  logger: $logger
+)
+
+server = TCPServer.new(HOST, SENSOR_PORT)
+$logger.info "Sensor server listening on #{HOST}:#{SENSOR_PORT}"
+
+begin
+  loop do
+    sock = server.accept
+
+    Thread.new(sock) do |client|
+      sensor_handler.handle_client(client)
+    end
+  end
+rescue Interrupt, SystemExit
+  shutdown(control_loop_thread, layout_controller, dcc, server, $logger)
+end

data/lib/signalbox/cab.rb

@@ -0,0 +1,27 @@
+module SignalBox
+  class Cab
+    attr_reader :name, :address, :logger
+
+    attr_accessor :current_speed, :target_speed, :acceleration, :location, :direction
+
+    # param name [String] the name of the cab
+    # param address [String] the DCC address of the cab
+    # param current_speed [Integer] the current speed of the cab
+    # param target_speed [Integer] the target speed of the cab
+    # param acceleration [Integer] the acceleration of the cab, in units per second squared, absolute value
+    # param direction [Integer] the direction of the cab (0 = reverse, 1 = forward)
+    # param location [LayoutSector, nil] the current location of the cab
+    # param logger [Logger] the logger to use
+    def initialize(name: "", address: "", current_speed: 0, target_speed: 0, acceleration: 5, direction: 1, location: nil, logger: Logger.new(STDOUT))
+      @name = name
+      @address = address
+      @current_speed = current_speed
+      @target_speed = target_speed
+      @acceleration = acceleration
+      @direction = direction
+      @location = location
+      @logger = logger
+    end
+
+  end
+end

data/lib/signalbox/config_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module SignalBox
+  class ConfigStore
+    DEFAULT_CONFIG = {
+      "trigger_delta" => 200,
+      "release_delta" => 120,
+      "debounce_ms"   => 80
+    }.freeze
+
+    def initialize(path)
+      @path = path
+      @mutex = Mutex.new
+      @configs = load_file
+    end
+
+    def get(sensor_id)
+      @mutex.synchronize do
+        DEFAULT_CONFIG.merge(@configs.fetch(sensor_id, {}))
+      end
+    end
+
+    def set(sensor_id, hash)
+      @mutex.synchronize do
+        @configs[sensor_id] ||= {}
+        @configs[sensor_id].merge!(hash)
+        save_file
+      end
+    end
+
+    private
+
+    def load_file
+      return {} unless File.exist?(@path)
+      YAML.load_file(@path) || {}
+    rescue => e
+      $logger.warn "Failed to load #{@path}: #{e}"
+      {}
+    end
+
+    def save_file
+      File.write(@path, YAML.dump(@configs))
+    end
+  end
+end

data/lib/signalbox/dcc/client.rb

@@ -0,0 +1,180 @@
+require 'socket'
+
+module SignalBox
+  module DCC
+    class Client
+      def initialize(host, port, logger:)
+        @host = host
+        @port = port
+        @logger = logger
+        @socket = nil
+      end
+
+      def connect
+        ensure_connected!
+      end
+
+      def close
+        safe_close
+      rescue => e
+        @logger.warn "[DCC] close failed (#{e.class}: #{e.message})"
+      end
+
+      def send(cmd)
+        ensure_connected!
+        @socket.puts(cmd)
+      rescue => e
+        @logger.warn "[DCC] send failed (#{e.class}: #{e.message}); reconnecting"
+        safe_close
+        ensure_connected!
+        @socket.puts(cmd)
+      end
+
+      # Track power control
+      def track_power_on!(track = "MAIN")
+        @logger.debug "[DCC] Track power ON: #{track}"
+        send("<1 #{track}>")
+      end
+
+      def track_power_off!(track = "MAIN")
+        @logger.debug "[DCC] Track power OFF: #{track}"
+        send("<0 #{track}>")
+      end
+
+      # Legacy aliases
+      def track_power_main!
+        track_power_on!("MAIN")
+      end
+
+
+      def set_speed(addr:, speed:, dir: 1)
+        @logger.debug "[DCC] Set speed addr=#{addr} speed=#{speed} dir=#{dir}"
+        speed = [[speed, 0].max, 127].min
+        send("<t #{addr} #{speed} #{dir}>")
+      end
+
+      # Request cab status and parse the broadcast response
+      # Returns a hash with: { cab:, reg:, speed:, direction:, speed_byte:, funct_map: }
+      # speed: 0-127 (bits 0-6 of speed_byte)
+      # direction: 0 (reverse) or 1 (forward) (bit 7 of speed_byte)
+      # or nil if no response received
+      def get_cab_status(cab)
+        @logger.debug "[DCC] Getting status for cab #{cab}"
+        response = send_and_receive("<t #{cab}>", timeout: 2.0)
+
+        if response && response =~ /<l\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)>/
+          speed_byte = $3.to_i
+
+          {
+            cab: $1.to_i,
+            reg: $2.to_i,
+            speed: speed_byte & 0x7F,
+            direction: (speed_byte & 0x80) >> 7,
+            speed_byte: speed_byte,
+            funct_map: $4.to_i
+          }
+        else
+          @logger.warn "[DCC] No valid response for cab #{cab} status request"
+          nil
+        end
+      end
+
+      # Emergency stop - halts all locomotives immediately
+      def emergency_stop!
+        @logger.warn "[DCC] EMERGENCY STOP"
+        send("<!>")
+      end
+
+      # Function control (lights, sound, etc.)
+      # funct: 0-68 (F0-F68)
+      # state: 1=on, 0=off
+      def set_function(cab:, funct:, state:)
+        @logger.debug "[DCC] Set function cab=#{cab} F#{funct}=#{state}"
+        send("<F #{cab} #{funct} #{state}>")
+      end
+
+      # Convenience methods for common functions
+      def set_light(cab:, state:)
+        set_function(cab: cab, funct: 0, state: state)
+      end
+
+      def light_on(cab:)
+        set_light(cab: cab, state: 1)
+      end
+
+      def light_off(cab:)
+        set_light(cab: cab, state: 0)
+      end
+
+      # Turnout/point control
+      # id: turnout ID
+      # state: 1/"T"=throw, 0/"C"=close, "X"=examine
+      def set_turnout(id:, state:)
+        @logger.debug "[DCC] Set turnout #{id} to #{state}"
+        send("<T #{id} #{state}>")
+      end
+
+      def throw_turnout(id:)
+        set_turnout(id: id, state: 1)
+      end
+
+      def close_turnout(id:)
+        set_turnout(id: id, state: 0)
+      end
+
+      # List all defined turnouts
+      # Returns array of responses, each formatted as <H id state>
+      def list_turnouts
+        @logger.debug "[DCC] Requesting turnout list"
+        # This requires reading multiple responses, so we'll just send the command
+        send("<T>")
+        # Note: Response handling would need enhancement for multi-line responses
+      end
+
+      # Accessory decoder control
+      # Using address/subaddress format (addr: 0-511, subaddr: 0-3)
+      def set_accessory(addr:, subaddr:, activate:)
+        @logger.debug "[DCC] Accessory addr=#{addr} subaddr=#{subaddr} activate=#{activate}"
+        send("<a #{addr} #{subaddr} #{activate}>")
+      end
+
+      # Using linear address format (1-2044)
+      def set_accessory_linear(addr:, activate:)
+        @logger.debug "[DCC] Accessory linear addr=#{addr} activate=#{activate}"
+        send("<a #{addr} #{activate}>")
+      end
+
+
+      private
+
+      def send_and_receive(cmd, timeout: 2.0)
+        ensure_connected!
+        @socket.puts(cmd)
+
+        # Wait for response with timeout
+        if IO.select([@socket], nil, nil, timeout)
+          @socket.gets&.chomp
+        else
+          nil
+        end
+      rescue => e
+        @logger.warn "[DCC] send_and_receive failed (#{e.class}: #{e.message})"
+        nil
+      end
+
+      def ensure_connected!
+        return if @socket && !@socket.closed?
+        @socket = TCPSocket.new(@host, @port)
+      end
+
+      def safe_close
+        @socket&.close
+      rescue
+        nil
+      ensure
+        @socket = nil
+      end
+
+    end
+  end
+end

data/lib/signalbox/layout.rb

@@ -0,0 +1,41 @@
+module SignalBox
+  class Layout
+    attr_reader :name, :cabs, :sectors, :proximity_sensors, :dcc
+
+    def initialize(name:)
+      @name = name
+      @cabs = []
+      @sectors = []
+      @proximity_sensors = []
+      @dcc = nil
+    end
+
+    def add_cab(cab)
+      @cabs << cab
+    end
+
+    def add_sector(sector)
+      @sectors << sector
+    end
+
+    def add_proximity_sensor(sensor)
+      @proximity_sensors << sensor
+    end
+
+    def set_dcc(dcc)
+      @dcc = dcc
+    end
+
+    def find_sector(id)
+      @sectors.find { |s| s.id == id }
+    end
+
+    def find_sensor(id)
+      @proximity_sensors.find { |s| s.id == id }
+    end
+
+    def to_s
+      "Layout(name: #{@name}, cabs: #{@cabs.count}, sectors: #{@sectors.count}, sensors: #{@proximity_sensors.count})"
+    end
+  end
+end

data/lib/signalbox/layout_controller.rb

@@ -0,0 +1,204 @@
+require 'forwardable'
+
+module SignalBox
+  class LayoutController
+  extend Forwardable
+
+  attr_reader :dcc, :layout, :logger
+
+  # Delegate layout-related methods to the layout object
+  def_delegators :@layout, :cabs, :sectors, :proximity_sensors, :find_sector, :find_sensor
+
+  def initialize(dcc:, layout:, mutex:, logger: Logger.new(STDOUT))
+    @dcc = dcc
+    @layout = layout
+    @mutex = mutex
+    @logger = logger
+  end
+
+  def start
+    dcc.track_power_main!
+
+    # Fetch current status for all cabs from DCC controller
+    cabs.each do |cab|
+      @logger.info "[LAYOUT] Fetching status for cab: #{cab.name} (address: #{cab.address})"
+
+      status = dcc.get_cab_status(cab.address)
+
+      if status
+        cab.current_speed = status[:speed]
+        cab.target_speed = status[:speed]
+        cab.direction = status[:direction]
+
+        @logger.info "[LAYOUT] Cab #{cab.name}: speed=#{status[:speed]}, direction=#{status[:direction] == 1 ? 'forward' : 'reverse'}"
+      else
+        @logger.warn "[LAYOUT] Could not fetch status for cab #{cab.name}, using defaults"
+      end
+    end
+  end
+
+  def emergency_stop
+    dcc.track_power_off!
+  end
+
+  # Returns a hash with the complete system status
+  # @return [Hash] Status information including cabs, sectors, sensors, and layout info
+  def status
+    {
+      layout: {
+        name: layout.name
+      },
+      cabs: cabs.map do |cab|
+        {
+          name: cab.name,
+          address: cab.address,
+          current_speed: cab.current_speed.round(2),
+          target_speed: cab.target_speed,
+          direction: cab.direction,
+          direction_name: cab.direction == 1 ? "forward" : "reverse",
+          acceleration: cab.acceleration,
+          location: cab.location ? {
+            id: cab.location.id,
+            name: cab.location.name,
+            speed_limit: cab.location.speed_limit
+          } : nil
+        }
+      end,
+      sectors: sectors.map do |sector|
+        {
+          id: sector.id,
+          name: sector.name,
+          speed_limit: sector.speed_limit
+        }
+      end,
+      sensors: proximity_sensors.map do |sensor|
+        {
+          id: sensor.id,
+          sector_id: sensor.sector_id
+        }
+      end
+    }
+  end
+
+  # Called periodically by control loop
+  # @param elapsed_time [Float] seconds since last tick
+  def tick(elapsed_time)
+    cabs.each do |cab|
+      # Skip if already at target
+      next if cab.current_speed == cab.target_speed
+
+      # Calculate maximum speed change for this tick
+      max_delta = cab.acceleration * elapsed_time
+
+      if cab.current_speed < cab.target_speed
+        # Accelerating
+        new_speed = [cab.current_speed + max_delta, cab.target_speed].min
+      else
+        # Decelerating
+        new_speed = [cab.current_speed - max_delta, cab.target_speed].max
+      end
+
+      # Update cab state
+      cab.current_speed = new_speed
+
+      # Send to DCC system (rounds to integer)
+      @dcc.set_speed(addr: cab.address, speed: new_speed.round, dir: cab.direction)
+
+      @logger.debug "[TICK] Cab #{cab.name} speed: #{cab.current_speed.round(2)} -> #{cab.target_speed}"
+    end
+  end
+
+  # @return [Cab] the primary cab
+  def primary_cab
+    cabs.first
+  end
+
+  # Set target speed for a cab
+  # @param cab_address [Integer] the DCC address of the cab
+  # @param speed [Integer] the target speed (0-127)
+  # @return [Boolean] true if successful, false if cab not found
+  def set_target_speed(cab_address:, speed:)
+    cab = cabs.find { |c| c.address == cab_address }
+
+    unless cab
+      @logger.warn "[CAB] Cannot set target speed: Cab with address #{cab_address} not found"
+      return false
+    end
+
+    # Clamp speed to valid range
+    speed = [[speed, 0].max, 127].min
+
+    @logger.info "[CAB] Setting target speed for #{cab.name} (#{cab_address}): #{cab.target_speed} -> #{speed}"
+    cab.target_speed = speed
+    true
+  end
+
+  # @param cab [Cab] the cab to handle, defaults to primary cab
+  # @param sector [LayoutSector] the sector that triggered the sensor
+  def sector_proximity_sensor_triggered(cab: nil, sensor_id:)
+    cab ||= primary_cab
+
+    sensor = find_sensor(sensor_id)
+    sector = find_sector(sensor.sector_id)
+
+    @logger.debug "[CAB] Proximity sensor (#{sensor_id}) triggered for sector: #{sector}"
+
+    unless sectors.include?(sector)
+      @logger.warn "Unknown sector triggered: #{sector&.id}"
+      return
+    end
+
+    if cab.location.nil?
+      # First sector assignment
+      cab.location = sector
+      @logger.debug "Initial sector assignment: #{sector&.id}"
+      return
+    end
+
+    if cab.location == sector
+      # Already in this sector, no action needed
+      @logger.debug "Already in sector #{sector&.id}, no action taken"
+      return
+    end
+
+    sa = sector_after(cab.location)
+
+    if sector != sa
+      @logger.warn "Invalid sector transition attempted: #{cab.location&.id} -> #{sector&.id}. Expected #{sa&.id}."
+      return
+    end
+
+    # Update location
+    cab.location = sector
+
+    if sector.speed_limit
+      @logger.info "[CAB] Cab #{cab.name} entered sector #{sector.id}, setting target speed to #{sector.speed_limit}"
+      cab.target_speed = sector.speed_limit
+    end
+
+  end
+
+  private
+
+  def sector_index_for(sector_id)
+    @logger.debug "sector_index_for #{sector_id}"
+    return nil if sector_id.nil?
+
+    sectors.find_index { |s| s.id == sector_id }
+  end
+
+  # Returns the sector object after the given sector, wrapping around to the first sector if needed
+  # @param sector [LayoutSector,nil] the sector
+  # @return [LayoutSector, nil] the next sector or nil if sector_id not found
+  def sector_after(sector)
+    @logger.debug "sector_after #{sector}"
+
+    index = sector_index_for(sector&.id)
+    return nil if index.nil?
+
+    next_index = (index + 1) % sectors.length
+    sectors[next_index]
+  end
+
+  end
+end

data/lib/signalbox/layout_dsl.rb

@@ -0,0 +1,143 @@
+require_relative 'layout'
+require_relative 'cab'
+require_relative 'layout_sector'
+require_relative 'proximity_sensor'
+require_relative 'dcc/client'
+require 'logger'
+
+module SignalBox
+  module LayoutDSL
+  # Builder for cab blocks
+  class CabBuilder
+    attr_reader :cab_name, :cab_address, :cab_acceleration
+
+    def name(value)
+      @cab_name = value
+    end
+
+    def address(value)
+      @cab_address = value
+    end
+
+    def acceleration(value)
+      @cab_acceleration = value
+    end
+
+    def build(logger:)
+      Cab.new(
+        name: @cab_name || "",
+        address: @cab_address || 0,
+        acceleration: @cab_acceleration || 5,
+        logger: logger
+      )
+    end
+  end
+
+  # Builder for sector blocks
+  class SectorBuilder
+    attr_reader :sector_id, :sector_name, :sector_speed_limit
+
+    def id(value)
+      @sector_id = value
+    end
+
+    def name(value)
+      @sector_name = value
+    end
+
+    def speed_limit(value)
+      @sector_speed_limit = value
+    end
+
+    def build
+      LayoutSector.new(
+        id: @sector_id,
+        name: @sector_name || "",
+        speed_limit: @sector_speed_limit || 10
+      )
+    end
+  end
+
+  # Builder for proximity_sensor blocks
+  class ProximitySensorBuilder
+    attr_reader :sensor_id, :sensor_sector_id
+
+    def id(value)
+      @sensor_id = value
+    end
+
+    def sector_id(value)
+      @sensor_sector_id = value
+    end
+
+    def build
+      ProximitySensor.new(
+        id: @sensor_id,
+        sector_id: @sensor_sector_id
+      )
+    end
+  end
+
+  # Builder for dcc blocks
+  class DCCBuilder
+    attr_reader :dcc_host, :dcc_port
+
+    def host(value)
+      @dcc_host = value
+    end
+
+    def port(value)
+      @dcc_port = value
+    end
+
+    def build(logger:)
+      DCC::Client.new(
+        @dcc_host,
+        @dcc_port,
+        logger: logger
+      )
+    end
+  end
+
+  # Main layout builder
+  class LayoutBuilder
+    attr_reader :layout
+
+    def initialize(name:, logger: Logger.new(STDOUT))
+      @layout = Layout.new(name: name)
+      @logger = logger
+    end
+
+    def cab(&block)
+      builder = CabBuilder.new
+      builder.instance_eval(&block)
+      @layout.add_cab(builder.build(logger: @logger))
+    end
+
+    def sector(&block)
+      builder = SectorBuilder.new
+      builder.instance_eval(&block)
+      @layout.add_sector(builder.build)
+    end
+
+    def proximity_sensor(&block)
+      builder = ProximitySensorBuilder.new
+      builder.instance_eval(&block)
+      @layout.add_proximity_sensor(builder.build)
+    end
+
+    def dcc(&block)
+      builder = DCCBuilder.new
+      builder.instance_eval(&block)
+      @layout.set_dcc(builder.build(logger: @logger))
+    end
+  end
+
+  # Top-level DSL method
+  def layout(name:, logger: Logger.new(STDOUT), &block)
+    builder = LayoutBuilder.new(name: name, logger: logger)
+    builder.instance_eval(&block)
+    builder.layout
+  end
+  end
+end

data/lib/signalbox/layout_loader.rb

@@ -0,0 +1,31 @@
+require_relative 'layout_dsl'
+
+module SignalBox
+  class LayoutLoader
+  extend LayoutDSL
+
+  # Load a layout file and return the Layout object
+  # @param file_path [String] Path to the layout definition file
+  # @param logger [Logger] Logger instance to use
+  # @return [Layout] The loaded layout
+  def self.load(file_path, logger: Logger.new(STDOUT))
+    unless File.exist?(file_path)
+      raise "Layout file not found: #{file_path}"
+    end
+
+    logger.info "[LAYOUT] Loading layout from #{file_path}"
+
+    # Read and evaluate the layout file in the context of this class
+    # This makes the `layout` method available
+    content = File.read(file_path)
+    layout_obj = self.instance_eval(content, file_path)
+
+    logger.info "[LAYOUT] Loaded: #{layout_obj}"
+    logger.info "[LAYOUT]   Cabs: #{layout_obj.cabs.map(&:name).join(', ')}"
+    logger.info "[LAYOUT]   Sectors: #{layout_obj.sectors.map(&:name).join(', ')}"
+    logger.info "[LAYOUT]   Sensors: #{layout_obj.proximity_sensors.map(&:id).join(', ')}"
+
+    layout_obj
+  end
+  end
+end

data/lib/signalbox/layout_sector.rb

@@ -0,0 +1,20 @@
+module SignalBox
+  class LayoutSector
+    attr_reader :name, :id, :speed_limit
+
+    def initialize(name: "", id: "", speed_limit: 10)
+      @speed_limit = speed_limit
+      @name = name
+      @id = id
+    end
+
+    def == (other)
+      other.is_a?(LayoutSector) && other.id == @id
+    end
+
+    def to_s
+      "Sector(name: #{@name}, id: #{@id})"
+    end
+
+  end
+end

data/lib/signalbox/proximity_sensor.rb

@@ -0,0 +1,18 @@
+module SignalBox
+  class ProximitySensor
+    attr_reader :id, :sector_id
+
+    def initialize(id:, sector_id:)
+      @id = id
+      @sector_id = sector_id
+    end
+
+    def ==(other)
+      other.is_a?(ProximitySensor) && other.id == @id
+    end
+
+    def to_s
+      "ProximitySensor(id: #{@id}, sector_id: #{@sector_id})"
+    end
+  end
+end

data/lib/signalbox/sensor_client_handler.rb

@@ -0,0 +1,107 @@
+require 'json'
+
+module SignalBox
+  class SensorClientHandler
+    DETECTION_THRESHOLD = 1500
+
+    def initialize(layout_controller:, mutex:, logger:)
+      @layout_controller = layout_controller
+      @mutex = mutex
+      @logger = logger
+    end
+
+    def handle_client(client)
+      begin
+        client.sync = true
+        peer = client.peeraddr
+        @logger.info "Client connected from #{peer[2]}:#{peer[1]}"
+
+        sensor_id = nil
+
+        while (line = client.gets)
+          line = line.strip
+          next if line.empty?
+
+          @logger.debug "Raw line: #{line}"
+
+          parts = line.split(" ")
+          cmd = parts.shift
+
+          case cmd
+          when "HELLO"
+            handle_hello(parts)
+
+          when "READING"
+            sensor_id = parts.shift
+            handle_reading(sensor_id, parts)
+
+          when "MANUAL_SECTOR_ADVANCE"
+            handle_manual_sector_advance(client)
+
+          when "STATUS"
+            handle_status(client)
+
+          when "SET_TARGET_SPEED"
+            cab_address = parts.shift.to_i
+            speed = parts.shift.to_i
+            handle_set_target_speed(client, cab_address, speed)
+
+          else
+            @logger.warn "[WARN] Unknown cmd: #{line}"
+          end
+        end
+      rescue => e
+        @logger.warn "Client thread error: #{e}\n#{e.backtrace.join("\n")}"
+      ensure
+        client.close rescue nil
+        @logger.debug "Client disconnected"
+      end
+    end
+
+    private
+
+    def handle_hello(parts)
+      esp32_id = parts[0] || "unknown"
+      fw = parts[1] || "?"
+      @logger.info "[HELLO] ESP32 connected: id=#{esp32_id} fw=#{fw}"
+    end
+
+    def handle_reading(sensor_id, parts)
+      kv = parts.reject(&:empty?).filter_map { |p| p.split("=", 2) if p.include?("=") }.to_h
+      avg = kv["avg"].to_i
+
+      @logger.info "[READING] id=#{sensor_id} avg=#{avg}"
+
+      # Detect train passage (rising edge detection)
+      @mutex.synchronize do
+        if avg < DETECTION_THRESHOLD
+          @layout_controller.sector_proximity_sensor_triggered(sensor_id: sensor_id)
+        end
+      end
+    end
+
+    def handle_manual_sector_advance(client)
+      @logger.info "[MANUAL] Manual sector advance requested"
+      @mutex.synchronize do
+        @layout_controller.advance_sector
+        client.puts "OK"
+      end
+    end
+
+    def handle_status(client)
+      @logger.info "[STATUS] Status request received"
+      @mutex.synchronize do
+        status = @layout_controller.status
+        client.puts JSON.generate(status)
+      end
+    end
+
+    def handle_set_target_speed(client, cab_address, speed)
+      @logger.info "[SET_TARGET_SPEED] Cab #{cab_address} -> #{speed}"
+      @mutex.synchronize do
+        success = @layout_controller.set_target_speed(cab_address: cab_address, speed: speed)
+        client.puts success ? "OK" : "ERROR"
+      end
+    end
+  end
+end

data/lib/signalbox/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SignalBox
+  VERSION = "0.1.0"
+end

data/lib/signalbox.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Add lib directory to load path
+$LOAD_PATH.unshift(__dir__) unless $LOAD_PATH.include?(__dir__)
+
+require "signalbox/version"
+
+# Core classes
+require "signalbox/cab"
+require "signalbox/layout"
+require "signalbox/layout_sector"
+require "signalbox/proximity_sensor"
+
+# DCC communication
+require "signalbox/dcc/client"
+
+# Controllers
+require "signalbox/layout_controller"
+
+# DSL and loaders
+require "signalbox/layout_dsl"
+require "signalbox/layout_loader"
+
+# Server components
+require "signalbox/sensor_client_handler"
+require "signalbox/config_store"
+
+module SignalBox
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: signalbox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff McFadden
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: SignalBox is a distributed control system for DCC model railroads. It
+  provides a Ruby-based server that receives sensor events from ESP32 nodes, applies
+  control logic, and sends DCC-EX commands to control trains.
+email:
+- ''
+executables:
+- signalbox-conductor
+- signalbox-server
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/signalbox-conductor
+- exe/signalbox-server
+- lib/signalbox.rb
+- lib/signalbox/cab.rb
+- lib/signalbox/config_store.rb
+- lib/signalbox/dcc/client.rb
+- lib/signalbox/layout.rb
+- lib/signalbox/layout_controller.rb
+- lib/signalbox/layout_dsl.rb
+- lib/signalbox/layout_loader.rb
+- lib/signalbox/layout_sector.rb
+- lib/signalbox/proximity_sensor.rb
+- lib/signalbox/sensor_client_handler.rb
+- lib/signalbox/version.rb
+homepage: https://github.com/jeffmcfadden/signalbox
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: DCC model railroad automation framework with sensor-driven control
+test_files: []