autocore_std/

lib.rs

//! # AutoCore Standard Library
//!
//! The standard library for writing AutoCore control programs. This crate provides
//! everything you need to build real-time control applications that integrate with
//! the AutoCore server ecosystem.
//!
//! ## Overview
//!
//! AutoCore control programs run as separate processes that communicate with the
//! autocore-server via shared memory and IPC. This library handles all the low-level
//! details, allowing you to focus on your control logic.
//!
//! ```text
//! ┌─────────────────────────┐     ┌─────────────────────────┐
//! │   autocore-server       │     │   Your Control Program  │
//! │                         │     │                         │
//! │  ┌─────────────────┐    │     │  ┌─────────────────┐    │
//! │  │ Shared Memory   │◄───┼─────┼──│ ControlRunner   │    │
//! │  │ (GlobalMemory)  │    │     │  │                 │    │
//! │  └─────────────────┘    │     │  │ ┌─────────────┐ │    │
//! │                         │     │  │ │ Your Logic  │ │    │
//! │  ┌─────────────────┐    │     │  │ └─────────────┘ │    │
//! │  │ Tick Signal     │────┼─────┼──│                 │    │
//! │  └─────────────────┘    │     │  └─────────────────┘    │
//! └─────────────────────────┘     └─────────────────────────┘
//! ```
//!
//! ## Quick Start
//!
//! 1. Create a new control project using `acctl`:
//!    ```bash
//!    acctl clone <server-ip> <project-name>
//!    ```
//!
//! 2. Implement the [`ControlProgram`] trait:
//!    ```ignore
//!    use autocore_std::{ControlProgram, RTrig};
//!
//!    // GlobalMemory is generated from your project.json
//!    mod gm;
//!    use gm::GlobalMemory;
//!
//!    pub struct MyProgram {
//!        start_button: RTrig,
//!    }
//!
//!    impl MyProgram {
//!        pub fn new() -> Self {
//!            Self {
//!                start_button: RTrig::new(),
//!            }
//!        }
//!    }
//!
//!    impl ControlProgram for MyProgram {
//!        type Memory = GlobalMemory;
//!
//!        fn process_tick(&mut self, mem: &mut GlobalMemory, _cycle: u64) {
//!            // Detect rising edge on start button
//!            if self.start_button.call(mem.inputs.start_button) {
//!                mem.outputs.motor_running = true;
//!                autocore_std::log::info!("Motor started!");
//!            }
//!        }
//!    }
//!    ```
//!
//! 3. Use the [`autocore_main!`] macro for the entry point:
//!    ```ignore
//!    autocore_std::autocore_main!(MyProgram, "my_project_shm", "tick");
//!    ```
//!
//! ## Function Blocks (IEC 61131-3 Inspired)
//!
//! This library includes standard function blocks commonly used in PLC programming:
//!
//! - [`RTrig`] - Rising edge detector (false→true transition)
//! - [`FTrig`] - Falling edge detector (true→false transition)
//! - [`Ton`] - Timer On Delay (output after delay)
//! - [`SimpleTimer`] - Simple one-shot timer (NOT IEC 61131-3, for imperative use)
//! - [`StateMachine`] - State machine helper with automatic timer management
//!
//! ### Example: Edge Detection
//!
//! ```
//! use autocore_std::RTrig;
//!
//! let mut trigger = RTrig::new();
//!
//! // First call with false - no edge
//! assert_eq!(trigger.call(false), false);
//!
//! // Rising edge detected!
//! assert_eq!(trigger.call(true), true);
//!
//! // Still true, but no edge (already high)
//! assert_eq!(trigger.call(true), false);
//!
//! // Back to false
//! assert_eq!(trigger.call(false), false);
//!
//! // Another rising edge
//! assert_eq!(trigger.call(true), true);
//! ```
//!
//! ### Example: Timer
//!
//! ```
//! use autocore_std::Ton;
//! use std::time::Duration;
//!
//! let mut timer = Ton::new();
//! let delay = Duration::from_millis(100);
//!
//! // Timer not enabled - output is false
//! assert_eq!(timer.call(false, delay), false);
//!
//! // Enable timer - starts counting
//! assert_eq!(timer.call(true, delay), false);
//!
//! // Still counting...
//! std::thread::sleep(Duration::from_millis(50));
//! assert_eq!(timer.call(true, delay), false);
//! assert!(timer.et < delay); // Elapsed time < preset
//!
//! // After delay elapsed
//! std::thread::sleep(Duration::from_millis(60));
//! assert_eq!(timer.call(true, delay), true); // Output is now true!
//! ```
//!
//! ## Logging
//!
//! Control programs can send log messages to the autocore-server for display in the
//! web console. Logging is handled automatically when using [`ControlRunner`].
//!
//! ```ignore
//! use autocore_std::log;
//!
//! log::trace!("Detailed trace message");
//! log::debug!("Debug information");
//! log::info!("Normal operation message");
//! log::warn!("Warning condition detected");
//! log::error!("Error occurred!");
//! ```
//!
//! See the [`logger`] module for advanced configuration.
//!
//! ## Memory Synchronization
//!
//! The [`ControlRunner`] handles all shared memory synchronization automatically:
//!
//! 1. **Wait for tick** - Blocks until the server signals a new cycle
//! 2. **Read inputs** - Copies shared memory to local buffer (atomic snapshot)
//! 3. **Execute logic** - Your `process_tick` runs on the local buffer
//! 4. **Write outputs** - Copies local buffer back to shared memory
//!
//! This ensures your control logic always sees a consistent view of the data,
//! even when other processes are modifying shared memory.

#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
#![doc(html_root_url = "https://docs.rs/autocore-std/3.3.0")]

use anyhow::{anyhow, Result};
use futures_util::{SinkExt, StreamExt};
use log::LevelFilter;
use mechutil::ipc::{CommandMessage, MessageType};
use raw_sync::events::{Event, EventInit, EventState};
use raw_sync::Timeout;
use shared_memory::ShmemConf;
use std::collections::HashMap;
use std::sync::atomic::{fence, Ordering, AtomicBool};
use std::sync::Arc;
use std::time::{Duration, Instant};
use tokio_tungstenite::{connect_async, tungstenite::Message};

/// UDP logger for sending log messages to autocore-server.
///
/// This module provides a non-blocking logger implementation that sends log messages
/// via UDP to the autocore-server. Messages are batched and sent asynchronously to
/// avoid impacting the control loop timing.
///
/// # Example
///
/// ```ignore
/// use autocore_std::logger;
/// use log::LevelFilter;
///
/// // Initialize the logger (done automatically by ControlRunner)
/// logger::init_udp_logger("127.0.0.1", 39101, LevelFilter::Info, "control")?;
///
/// // Now you can use the log macros
/// log::info!("System initialized");
/// ```
pub mod logger;

// Re-export log crate for convenience - control programs can use autocore_std::log::info!() etc.
pub use log;

// ============================================================================
// Standard Library Function Blocks (IEC 61131-3 Inspired)
// ============================================================================

/// Rising Edge Trigger (R_TRIG)
///
/// Detects a rising edge (false → true transition) on the input signal.
/// The output `q` is `true` for exactly one cycle when the input `clk`
/// transitions from `false` to `true`.
///
/// This is equivalent to the IEC 61131-3 R_TRIG function block.
///
/// # Example
///
/// ```
/// use autocore_std::RTrig;
///
/// let mut trigger = RTrig::new();
///
/// // No edge yet
/// assert_eq!(trigger.call(false), false);
///
/// // Rising edge detected!
/// assert_eq!(trigger.call(true), true);
///
/// // Signal still high, but edge already passed
/// assert_eq!(trigger.call(true), false);
/// assert_eq!(trigger.call(true), false);
///
/// // Signal goes low
/// assert_eq!(trigger.call(false), false);
///
/// // Another rising edge
/// assert_eq!(trigger.call(true), true);
/// ```
///
/// # Timing Diagram
///
/// ```text
/// clk: _____|‾‾‾‾‾‾‾‾‾|_____|‾‾‾‾‾
///   q: _____|‾|_____________|‾|____
/// ```
///
/// # Use Cases
///
/// - Detecting button presses (trigger on press, not hold)
/// - Counting events (increment counter on each rising edge)
/// - State machine transitions
#[derive(Debug, Clone)]
pub struct RTrig {
    /// Current input value
    pub clk: bool,
    /// Output: true for one cycle on rising edge
    pub q: bool,
    /// Internal memory of previous input state
    m: bool,
}

impl RTrig {
    /// Creates a new rising edge trigger with all values initialized to `false`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::RTrig;
    ///
    /// let trigger = RTrig::new();
    /// assert_eq!(trigger.q, false);
    /// ```
    pub fn new() -> Self {
        Self {
            clk: false,
            q: false,
            m: false,
        }
    }

    /// Executes the rising edge detection logic.
    ///
    /// Call this method once per control cycle with the current input value.
    /// Returns `true` for exactly one cycle when a rising edge is detected.
    ///
    /// # Arguments
    ///
    /// * `clk` - The current state of the input signal
    ///
    /// # Returns
    ///
    /// `true` if a rising edge (false → true transition) was detected, `false` otherwise.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::RTrig;
    ///
    /// let mut trigger = RTrig::new();
    ///
    /// let button_pressed = true;
    /// if trigger.call(button_pressed) {
    ///     println!("Button was just pressed!");
    /// }
    /// ```
    pub fn call(&mut self, clk: bool) -> bool {
        self.clk = clk;
        self.q = self.clk && !self.m;
        self.m = self.clk;
        self.q
    }
}

impl Default for RTrig {
    fn default() -> Self {
        Self::new()
    }
}


/// Falling Edge Trigger (F_TRIG)
///
/// Detects a falling edge (true → false transition) on the input signal.
/// The output `q` is `true` for exactly one cycle when the input `clk`
/// transitions from `true` to `false`.
///
/// This is equivalent to the IEC 61131-3 F_TRIG function block.
///
/// # Example
///
/// ```
/// use autocore_std::FTrig;
///
/// let mut trigger = FTrig::new();
///
/// // Signal starts low
/// assert_eq!(trigger.call(false), false);
///
/// // Signal goes high
/// assert_eq!(trigger.call(true), false);
///
/// // Falling edge detected!
/// assert_eq!(trigger.call(false), true);
///
/// // Signal still low, edge already passed
/// assert_eq!(trigger.call(false), false);
/// ```
///
/// # Timing Diagram
///
/// ```text
/// clk: _____|‾‾‾‾‾‾‾‾‾|_____|‾‾‾‾‾
///   q: _______________|‾|________
/// ```
///
/// # Use Cases
///
/// - Detecting button releases
/// - Detecting signal loss
/// - Triggering actions when a condition ends
#[derive(Debug, Clone)]
pub struct FTrig {
    /// Current input value
    pub clk: bool,
    /// Output: true for one cycle on falling edge
    pub q: bool,
    /// Internal memory of previous input state
    m: bool,
}

impl FTrig {
    /// Creates a new falling edge trigger with all values initialized to `false`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::FTrig;
    ///
    /// let trigger = FTrig::new();
    /// assert_eq!(trigger.q, false);
    /// ```
    pub fn new() -> Self {
        Self {
            clk: false,
            q: false,
            m: false,
        }
    }

    /// Executes the falling edge detection logic.
    ///
    /// Call this method once per control cycle with the current input value.
    /// Returns `true` for exactly one cycle when a falling edge is detected.
    ///
    /// # Arguments
    ///
    /// * `clk` - The current state of the input signal
    ///
    /// # Returns
    ///
    /// `true` if a falling edge (true → false transition) was detected, `false` otherwise.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::FTrig;
    ///
    /// let mut trigger = FTrig::new();
    ///
    /// // Simulate button release
    /// trigger.call(true);  // Button held
    /// if trigger.call(false) {  // Button released
    ///     println!("Button was just released!");
    /// }
    /// ```
    pub fn call(&mut self, clk: bool) -> bool {
        self.clk = clk;
        self.q = !self.clk && self.m;
        self.m = self.clk;
        self.q
    }
}

impl Default for FTrig {
    fn default() -> Self {
        Self::new()
    }
}


/// Timer On Delay (TON)
///
/// A timer that delays turning on the output. The output `q` becomes `true`
/// after the enable input `en` has been continuously `true` for the preset
/// time `pt`. The elapsed time is available in `et`.
///
/// This is equivalent to the IEC 61131-3 TON function block.
///
/// # Behavior
///
/// - When `en` becomes `true`, the timer starts counting from zero
/// - While counting, `et` shows the elapsed time and `q` is `false`
/// - When `et` reaches `pt`, `q` becomes `true` and `et` is clamped to `pt`
/// - When `en` becomes `false`, the timer resets: `q` = `false`, `et` = 0
///
/// # Example
///
/// ```
/// use autocore_std::Ton;
/// use std::time::Duration;
///
/// let mut timer = Ton::new();
/// let delay = Duration::from_secs(5);
///
/// // Timer disabled - output is false
/// assert_eq!(timer.call(false, delay), false);
/// assert_eq!(timer.et, Duration::ZERO);
///
/// // Enable timer - starts counting
/// timer.call(true, delay);
/// assert_eq!(timer.q, false);  // Not done yet
/// // timer.et is now counting up...
///
/// // Disable resets the timer
/// timer.call(false, delay);
/// assert_eq!(timer.et, Duration::ZERO);
/// ```
///
/// # Timing Diagram
///
/// ```text
///  en: _____|‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾|_____
///   q: _____________|‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾|_____
///  et: 0---|++++++++|PT----------------|0----
///          ^        ^                  ^
///          |        |                  |
///      en rises   et=pt             en falls
/// ```
///
/// # Use Cases
///
/// - Motor start delay (allow contactors to engage)
/// - Debouncing switches (ignore brief transitions)
/// - Timeout detection (alarm if condition persists too long)
#[derive(Debug, Clone)]
pub struct Ton {
    /// Input: Enable the timer (true = counting, false = reset)
    pub en: bool,
    /// Input: Preset time (duration before output activates)
    pub pt: Duration,
    /// Output: Timer done (true when elapsed time >= preset time)
    pub q: bool,
    /// Output: Elapsed time since timer was enabled
    pub et: Duration,

    start_time: Option<Instant>,
    active: bool,
}

impl Ton {
    /// Creates a new timer with default values.
    ///
    /// The timer starts in the disabled state with zero elapsed time.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    ///
    /// let timer = Ton::new();
    /// assert_eq!(timer.q, false);
    /// assert_eq!(timer.et, std::time::Duration::ZERO);
    /// ```
    pub fn new() -> Self {
        Self {
            en: false,
            pt: Duration::default(),
            q: false,
            et: Duration::default(),
            start_time: None,
            active: false,
        }
    }

    /// Executes the timer logic.
    ///
    /// Call this method once per control cycle. The timer counts real elapsed
    /// time (not cycles), so the output timing is independent of scan rate.
    ///
    /// # Arguments
    ///
    /// * `en` - Enable input: `true` to run timer, `false` to reset
    /// * `pt` - Preset time: duration before output activates
    ///
    /// # Returns
    ///
    /// The current state of the output `q` (true if timer has elapsed).
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    /// use std::time::Duration;
    ///
    /// let mut timer = Ton::new();
    ///
    /// // Use in a control loop
    /// let motor_request = true;
    /// let start_delay = Duration::from_millis(500);
    ///
    /// let motor_enabled = timer.call(motor_request, start_delay);
    /// // motor_enabled will be true after 500ms of motor_request being true
    /// ```
    pub fn call(&mut self, en: bool, pt: Duration) -> bool {
        self.en = en;
        self.pt = pt;

        if !self.en {
            // Reset
            self.q = false;
            self.et = Duration::ZERO;
            self.start_time = None;
            self.active = false;
        } else {
            if !self.active {
                // Rising edge of EN - start timing
                self.start_time = Some(Instant::now());
                self.active = true;
                self.et = Duration::ZERO;
                self.q = false;
            } else {
                // Timer running
                if let Some(start) = self.start_time {
                    self.et = start.elapsed();
                    if self.et >= self.pt {
                        self.et = self.pt; // Clamp ET to PT
                        self.q = true;
                    }
                }
            }
        }
        self.q
    }

    /// Resets the timer to its initial state.
    ///
    /// This is equivalent to calling `call(false, ...)`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::Ton;
    /// use std::time::Duration;
    ///
    /// let mut timer = Ton::new();
    /// timer.call(true, Duration::from_secs(1));
    /// // ... timer is running ...
    ///
    /// timer.reset();
    /// assert_eq!(timer.q, false);
    /// assert_eq!(timer.et, Duration::ZERO);
    /// ```
    pub fn reset(&mut self) {
        self.q = false;
        self.et = Duration::ZERO;
        self.start_time = None;
        self.active = false;
    }
}

impl Default for Ton {
    fn default() -> Self {
        Self::new()
    }
}


/// Simple One-Shot Timer
///
/// A simple timer for one-shot timing operations. Unlike [`Ton`], this timer
/// does NOT follow the IEC 61131-3 standard and is designed for imperative
/// "start then check" patterns rather than cyclic function block calls.
///
/// **Note:** For standard PLC timer patterns (delay while condition is true),
/// use [`Ton`] instead. `SimpleTimer` is intended for one-shot use cases
/// like "do X, wait, then do Y".
///
/// # Safety
///
/// This timer uses [`Instant`] (monotonic clock) internally, making it immune
/// to system clock adjustments (NTP sync, manual changes, DST). This is
/// critical for reliable timing in industrial control applications.
///
/// # Example
///
/// ```
/// use autocore_std::SimpleTimer;
/// use std::time::Duration;
///
/// let mut timer = SimpleTimer::new(Duration::from_millis(100));
///
/// // Timer hasn't started yet
/// assert_eq!(timer.is_done(), false);
/// assert_eq!(timer.elapsed(), Duration::ZERO);
///
/// // Start the timer
/// timer.start();
///
/// // Check if done (will be false initially)
/// assert_eq!(timer.is_done(), false);
///
/// // After waiting...
/// std::thread::sleep(Duration::from_millis(110));
/// assert_eq!(timer.is_done(), true);
///
/// // Reset for reuse
/// timer.reset();
/// assert_eq!(timer.is_done(), false);
/// ```
///
/// # Use Cases
///
/// - One-shot delays ("wait 500ms then continue")
/// - Tracking time since an event occurred
/// - Non-cyclic async contexts
/// - Simple timeout checks
///
/// # Comparison with Ton
///
/// | Aspect | `Ton` | `SimpleTimer` |
/// |--------|-------|---------------|
/// | IEC 61131-3 | Yes | No |
/// | Pattern | Cyclic `call()` | Imperative `start()`/`is_done()` |
/// | Auto-reset on disable | Yes | No (explicit `reset()`) |
/// | Best for | PLC-style control | One-shot operations |
#[derive(Debug, Clone)]
pub struct SimpleTimer {
    start_time: Option<Instant>,
    preset: Duration,
}

impl SimpleTimer {
    /// Creates a new simple timer with the specified preset duration.
    ///
    /// The timer starts in the stopped state and must be explicitly started
    /// with [`start()`](Self::start).
    ///
    /// # Arguments
    ///
    /// * `preset` - The duration after which [`is_done()`](Self::is_done) returns `true`
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let timer = SimpleTimer::new(Duration::from_secs(5));
    /// assert_eq!(timer.is_done(), false);
    /// ```
    pub fn new(preset: Duration) -> Self {
        Self {
            start_time: None,
            preset,
        }
    }

    /// Starts (or restarts) the timer.
    ///
    /// Records the current time as the start time. If the timer was already
    /// running, this restarts it from zero.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_millis(100));
    /// timer.start();
    /// // Timer is now counting...
    /// ```
    pub fn start(&mut self) {
        self.start_time = Some(Instant::now());
    }

    /// Checks if the preset time has elapsed since the timer was started.
    ///
    /// Returns `false` if the timer hasn't been started yet.
    ///
    /// # Returns
    ///
    /// `true` if the timer was started and the preset duration has elapsed,
    /// `false` otherwise.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_millis(50));
    ///
    /// // Not started yet
    /// assert_eq!(timer.is_done(), false);
    ///
    /// timer.start();
    /// std::thread::sleep(Duration::from_millis(60));
    /// assert_eq!(timer.is_done(), true);
    /// ```
    pub fn is_done(&self) -> bool {
        self.start_time
            .map(|t| t.elapsed() >= self.preset)
            .unwrap_or(false)
    }

    /// Returns the elapsed time since the timer was started.
    ///
    /// Returns [`Duration::ZERO`] if the timer hasn't been started yet.
    ///
    /// # Returns
    ///
    /// The elapsed time since [`start()`](Self::start) was called, or
    /// `Duration::ZERO` if not started.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_secs(10));
    ///
    /// // Not started
    /// assert_eq!(timer.elapsed(), Duration::ZERO);
    ///
    /// timer.start();
    /// std::thread::sleep(Duration::from_millis(50));
    /// assert!(timer.elapsed() >= Duration::from_millis(50));
    /// ```
    pub fn elapsed(&self) -> Duration {
        self.start_time
            .map(|t| t.elapsed())
            .unwrap_or(Duration::ZERO)
    }

    /// Resets the timer to its initial (stopped) state.
    ///
    /// After calling this, [`is_done()`](Self::is_done) will return `false`
    /// and [`elapsed()`](Self::elapsed) will return zero until
    /// [`start()`](Self::start) is called again.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_millis(50));
    /// timer.start();
    /// std::thread::sleep(Duration::from_millis(60));
    /// assert_eq!(timer.is_done(), true);
    ///
    /// timer.reset();
    /// assert_eq!(timer.is_done(), false);
    /// assert_eq!(timer.elapsed(), Duration::ZERO);
    /// ```
    pub fn reset(&mut self) {
        self.start_time = None;
    }

    /// Returns the preset duration for this timer.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let timer = SimpleTimer::new(Duration::from_secs(5));
    /// assert_eq!(timer.preset(), Duration::from_secs(5));
    /// ```
    pub fn preset(&self) -> Duration {
        self.preset
    }

    /// Sets a new preset duration.
    ///
    /// This does not reset or restart the timer. If the timer is running,
    /// the new preset takes effect immediately for [`is_done()`](Self::is_done)
    /// checks.
    ///
    /// # Arguments
    ///
    /// * `preset` - The new duration after which `is_done()` returns `true`
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_secs(5));
    /// timer.set_preset(Duration::from_secs(10));
    /// assert_eq!(timer.preset(), Duration::from_secs(10));
    /// ```
    pub fn set_preset(&mut self, preset: Duration) {
        self.preset = preset;
    }

    /// Returns whether the timer is currently running (has been started but not reset).
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::SimpleTimer;
    /// use std::time::Duration;
    ///
    /// let mut timer = SimpleTimer::new(Duration::from_secs(5));
    /// assert_eq!(timer.is_running(), false);
    ///
    /// timer.start();
    /// assert_eq!(timer.is_running(), true);
    ///
    /// timer.reset();
    /// assert_eq!(timer.is_running(), false);
    /// ```
    pub fn is_running(&self) -> bool {
        self.start_time.is_some()
    }
}

impl Default for SimpleTimer {
    /// Creates a timer with a preset of zero (will be immediately done when started).
    fn default() -> Self {
        Self::new(Duration::ZERO)
    }
}


/// State Machine Helper (FB_StateMachine)
///
/// A state machine helper with automatic timer management and error tracking.
/// Provides two timers that automatically reset when the state index changes:
///
/// - **Timer** (`timer_done()`) - General purpose timer for delays and debouncing
/// - **Timeout** (`timed_out()`) - For detecting stuck states
///
/// This is equivalent to the IEC 61131-3 FB_StateMachine function block.
///
/// # Automatic Timer Reset
///
/// Both timers automatically reset when `index` changes. This eliminates a
/// common source of bugs in state machines where timers are not properly reset.
///
/// The pattern is:
/// 1. Set `timer_preset` (and optionally `timeout_preset`) in state N
/// 2. Change `index` to state N+1 (timers reset and start counting)
/// 3. In state N+1, check `timer_done()` or `timed_out()`
///
/// # Example
///
/// ```
/// use autocore_std::StateMachine;
/// use std::time::Duration;
///
/// let mut state = StateMachine::new();
///
/// // Simulate a control loop
/// loop {
///     match state.index {
///         0 => { // Reset
///             state.clear_error();
///             state.index = 10;
///         }
///         10 => { // Idle - wait for start signal
///             // For demo, just proceed
///             state.timer_preset = Duration::from_millis(100);
///             state.index = 20;
///         }
///         20 => { // Debounce
///             if state.timer_done() {
///                 state.timeout_preset = Duration::from_secs(10);
///                 state.index = 30;
///             }
///         }
///         30 => { // Wait for operation (simulated)
///             // In real code: check operation_complete
///             // For demo, check timeout
///             if state.timed_out() {
///                 state.set_error(30, "Operation timeout");
///                 state.index = 0;
///             }
///             // Exit demo loop
///             break;
///         }
///         _ => { state.index = 0; }
///     }
///
///     state.call(); // Call at end of each scan cycle
///     # break; // Exit for doctest
/// }
/// ```
///
/// # Timer Presets Persist
///
/// Timer presets persist until you change them. This allows setting a preset
/// once and using it across multiple states:
///
/// ```ignore
/// 100 => {
///     state.timer_preset = Duration::from_millis(300);
///     state.index = 110;
/// }
/// 110 => {
///     // Uses 300ms preset set in state 100
///     if some_condition && state.timer_done() {
///         state.index = 120;
///     }
/// }
/// 120 => {
///     // Still uses 300ms preset (timer reset on state change)
///     if state.timer_done() {
///         state.index = 10;
///     }
/// }
/// ```
///
/// # Error Handling Pattern
///
/// ```ignore
/// 200 => {
///     state.timeout_preset = Duration::from_secs(7);
///     start_operation();
///     state.index = 210;
/// }
/// 210 => {
///     if operation_complete {
///         state.index = 1000; // Success
///     } else if state.timed_out() {
///         state.set_error(210, "Operation timed out");
///         state.index = 5000; // Error handler
///     }
/// }
/// 5000 => {
///     // Error recovery
///     state.index = 0;
/// }
/// ```
#[derive(Debug, Clone)]
pub struct StateMachine {
    /// Current state index.
    pub index: i32,

    /// Timer preset. `timer_done()` returns true when time in current state >= this value.
    /// Defaults to `Duration::MAX` (timer never triggers unless you set a preset).
    pub timer_preset: Duration,

    /// Timeout preset. `timed_out()` returns true when time in current state >= this value.
    /// Defaults to `Duration::MAX` (timeout never triggers unless you set a preset).
    pub timeout_preset: Duration,

    /// Error code. A value of 0 indicates no error.
    /// When non-zero, `is_error()` returns true.
    pub error_code: i32,

    /// Status message for UI display. Content does not indicate an error.
    pub message: String,

    /// Error message for UI display. Should only have content when `error_code != 0`.
    pub error_message: String,

    // Internal state
    last_index: Option<i32>,
    state_entered_at: Option<Instant>,
}

impl StateMachine {
    /// Creates a new state machine starting at state 0.
    ///
    /// Timer presets default to `Duration::MAX`, meaning timers won't trigger
    /// until you explicitly set a preset.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    ///
    /// let state = StateMachine::new();
    /// assert_eq!(state.index, 0);
    /// assert_eq!(state.error_code, 0);
    /// assert!(!state.is_error());
    /// ```
    pub fn new() -> Self {
        Self {
            index: 0,
            timer_preset: Duration::MAX,
            timeout_preset: Duration::MAX,
            error_code: 0,
            message: String::new(),
            error_message: String::new(),
            last_index: None,
            state_entered_at: None,
        }
    }

    /// Call once per scan cycle at the END of your state machine logic.
    ///
    /// This method:
    /// - Detects state changes (when `index` differs from the previous call)
    /// - Resets internal timers on state change
    /// - Updates internal tracking for `elapsed()`, `timer_done()`, and `timed_out()`
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    ///
    /// let mut state = StateMachine::new();
    ///
    /// // Your state machine logic here...
    /// match state.index {
    ///     0 => { state.index = 10; }
    ///     _ => {}
    /// }
    ///
    /// state.call(); // Always call at the end
    /// ```
    pub fn call(&mut self) {
        if self.last_index != Some(self.index) {
            self.state_entered_at = Some(Instant::now());
        }
        self.last_index = Some(self.index);
    }

    /// Returns true when time in current state >= `timer_preset`.
    ///
    /// The timer automatically resets when the state index changes.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    /// use std::time::Duration;
    ///
    /// let mut state = StateMachine::new();
    /// state.timer_preset = Duration::from_millis(50);
    /// state.call(); // Start tracking
    ///
    /// assert!(!state.timer_done()); // Not enough time elapsed
    ///
    /// std::thread::sleep(Duration::from_millis(60));
    /// assert!(state.timer_done()); // Now it's done
    /// ```
    pub fn timer_done(&self) -> bool {
        self.elapsed() >= self.timer_preset
    }

    /// Returns true when time in current state >= `timeout_preset`.
    ///
    /// Use this for detecting stuck states. The timeout automatically
    /// resets when the state index changes.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    /// use std::time::Duration;
    ///
    /// let mut state = StateMachine::new();
    /// state.timeout_preset = Duration::from_millis(50);
    /// state.call();
    ///
    /// assert!(!state.timed_out());
    ///
    /// std::thread::sleep(Duration::from_millis(60));
    /// assert!(state.timed_out());
    /// ```
    pub fn timed_out(&self) -> bool {
        self.elapsed() >= self.timeout_preset
    }

    /// Returns elapsed time since entering the current state.
    ///
    /// Returns `Duration::ZERO` if `call()` has never been called.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    /// use std::time::Duration;
    ///
    /// let mut state = StateMachine::new();
    /// state.call();
    ///
    /// std::thread::sleep(Duration::from_millis(10));
    /// assert!(state.elapsed() >= Duration::from_millis(10));
    /// ```
    pub fn elapsed(&self) -> Duration {
        self.state_entered_at
            .map(|t| t.elapsed())
            .unwrap_or(Duration::ZERO)
    }

    /// Returns true if `error_code != 0`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    ///
    /// let mut state = StateMachine::new();
    /// assert!(!state.is_error());
    ///
    /// state.error_code = 100;
    /// assert!(state.is_error());
    /// ```
    pub fn is_error(&self) -> bool {
        self.error_code != 0
    }

    /// Set error state with code and message.
    ///
    /// This is a convenience method equivalent to setting `error_code`
    /// and `error_message` directly.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    ///
    /// let mut state = StateMachine::new();
    /// state.set_error(110, "Failed to home X axis");
    ///
    /// assert_eq!(state.error_code, 110);
    /// assert_eq!(state.error_message, "Failed to home X axis");
    /// assert!(state.is_error());
    /// ```
    pub fn set_error(&mut self, code: i32, message: impl Into<String>) {
        self.error_code = code;
        self.error_message = message.into();
    }

    /// Clear error state.
    ///
    /// Sets `error_code` to 0 and clears `error_message`.
    ///
    /// # Example
    ///
    /// ```
    /// use autocore_std::StateMachine;
    ///
    /// let mut state = StateMachine::new();
    /// state.set_error(100, "Some error");
    /// assert!(state.is_error());
    ///
    /// state.clear_error();
    /// assert!(!state.is_error());
    /// assert_eq!(state.error_code, 0);
    /// assert!(state.error_message.is_empty());
    /// ```
    pub fn clear_error(&mut self) {
        self.error_code = 0;
        self.error_message.clear();
    }

    /// Returns the current state index.
    ///
    /// This is equivalent to reading `state.index` directly but provided
    /// for API consistency.
    pub fn state(&self) -> i32 {
        self.index
    }
}

impl Default for StateMachine {
    fn default() -> Self {
        Self::new()
    }
}


// ============================================================================
// Core Framework
// ============================================================================

/// Marker trait for generated GlobalMemory structs.
///
/// This trait is implemented by the auto-generated `GlobalMemory` struct
/// that represents the shared memory layout. It serves as a marker for
/// type safety in the control framework.
///
/// You don't need to implement this trait yourself - it's automatically
/// implemented by the code generator.
pub trait AutoCoreMemory {}

/// Trait for detecting changes in memory structures.
pub trait ChangeTracker {
    /// Compare self with a previous state and return a list of changed fields.
    /// Returns a vector of (field_name, new_value).
    fn get_changes(&self, prev: &Self) -> Vec<(&'static str, serde_json::Value)>;
}

/// The trait that defines a control program's logic.
///
/// Implement this trait to create your control program. The associated `Memory`
/// type should be the generated `GlobalMemory` struct from your project.
///
/// # Memory Type Requirements
///
/// The `Memory` type must implement `Copy` to allow efficient synchronization
/// between shared memory and local buffers. This is automatically satisfied
/// by the generated `GlobalMemory` struct.
///
/// # Lifecycle
///
/// 1. `initialize` is called once at startup
/// 2. `process_tick` is called repeatedly in the control loop
///
/// # Example
///
/// ```ignore
/// use autocore_std::ControlProgram;
///
/// mod gm;
/// use gm::GlobalMemory;
///
/// pub struct MyController {
///     cycle_counter: u64,
/// }
///
/// impl MyController {
///     pub fn new() -> Self {
///         Self { cycle_counter: 0 }
///     }
/// }
///
/// impl ControlProgram for MyController {
///     type Memory = GlobalMemory;
///
///     fn initialize(&mut self, mem: &mut GlobalMemory) {
///         // Set initial output states
///         mem.outputs.ready = true;
///         log::info!("Controller initialized");
///     }
///
///     fn process_tick(&mut self, mem: &mut GlobalMemory, cycle: u64) {
///         self.cycle_counter = cycle;
///
///         // Your control logic here
///         if mem.inputs.start && !mem.inputs.estop {
///             mem.outputs.running = true;
///         }
///     }
/// }
/// ```
pub trait ControlProgram {
    /// The shared memory structure type (usually the generated `GlobalMemory`).
    ///
    /// Must implement `Copy` to allow efficient memory synchronization.
    type Memory: Copy + ChangeTracker;

    /// Called once when the control program starts.
    ///
    /// Use this to initialize output states, reset counters, or perform
    /// any one-time setup. The default implementation does nothing.
    ///
    /// # Arguments
    ///
    /// * `mem` - Mutable reference to the shared memory. Changes are written
    ///           back to shared memory after this method returns.
    fn initialize(&mut self, _mem: &mut Self::Memory) {}

    /// The main control loop - called once per scan cycle.
    ///
    /// This is where your control logic lives. Read inputs from `mem`,
    /// perform calculations, and write outputs back to `mem`.
    ///
    /// # Arguments
    ///
    /// * `mem` - Mutable reference to a local copy of the shared memory.
    ///           Changes made here are written back to shared memory after
    ///           this method returns.
    /// * `cycle` - The current cycle number (increments each tick, starting at 1).
    ///
    /// # Timing
    ///
    /// This method should complete within the scan cycle time. Long-running
    /// operations will cause cycle overruns.
    fn process_tick(&mut self, mem: &mut Self::Memory, cycle: u64);
}

/// Configuration for the [`ControlRunner`].
///
/// Specifies connection parameters, shared memory names, and logging settings.
/// Use [`Default::default()`] for typical configurations.
///
/// # Example
///
/// ```
/// use autocore_std::RunnerConfig;
/// use log::LevelFilter;
///
/// let config = RunnerConfig {
///     server_host: "192.168.1.100".to_string(),
///     module_name: "my_controller".to_string(),
///     shm_name: "my_project_shm".to_string(),
///     tick_signal_name: "tick".to_string(),
///     busy_signal_name: Some("busy".to_string()),
///     log_level: LevelFilter::Debug,
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct RunnerConfig {
    /// Server host address (default: "127.0.0.1")
    pub server_host: String,
    /// WebSocket port for commands (default: 11969)
    pub ws_port: u16,
    /// Module name for identification (default: "control")
    pub module_name: String,
    /// Shared memory segment name (must match server configuration)
    pub shm_name: String,
    /// Name of the tick signal in shared memory (triggers each scan cycle)
    pub tick_signal_name: String,
    /// Optional name of the busy signal (set when cycle completes)
    pub busy_signal_name: Option<String>,
    /// Minimum log level to send to the server (default: Info)
    pub log_level: LevelFilter,
    /// UDP port for sending logs to the server (default: 39101)
    pub log_udp_port: u16,
}

/// Default WebSocket port for autocore-server
pub const DEFAULT_WS_PORT: u16 = 11969;

impl Default for RunnerConfig {
    fn default() -> Self {
        Self {
            server_host: "127.0.0.1".to_string(),
            ws_port: DEFAULT_WS_PORT,
            module_name: "control".to_string(),
            shm_name: "autocore_cyclic".to_string(),
            tick_signal_name: "tick".to_string(),
            busy_signal_name: None,
            log_level: LevelFilter::Info,
            log_udp_port: logger::DEFAULT_LOG_UDP_PORT,
        }
    }
}


/// The main execution engine for control programs.
///
/// `ControlRunner` handles all the infrastructure required to run a control program:
///
/// - Reading memory layout from the server's layout file
/// - Opening and mapping shared memory
/// - Setting up synchronization signals
/// - Running the real-time control loop
/// - Sending log messages to the server
///
/// # Usage
///
/// ```ignore
/// use autocore_std::{ControlRunner, RunnerConfig};
///
/// let config = RunnerConfig {
///     shm_name: "my_project_shm".to_string(),
///     tick_signal_name: "tick".to_string(),
///     ..Default::default()
/// };
///
/// ControlRunner::new(MyProgram::new())
///     .config(config)
///     .run()?;  // Blocks forever
/// ```
///
/// # Control Loop
///
/// The runner executes a synchronous control loop:
///
/// 1. **Wait** - Blocks until the tick signal is set by the server
/// 2. **Read** - Copies shared memory to a local buffer (acquire barrier)
/// 3. **Execute** - Calls your `process_tick` method
/// 4. **Write** - Copies local buffer back to shared memory (release barrier)
/// 5. **Signal** - Sets the busy signal (if configured) to indicate completion
///
/// This ensures your code always sees a consistent snapshot of the data
/// and that your writes are atomically visible to other processes.
pub struct ControlRunner<P: ControlProgram> {
    config: RunnerConfig,
    program: P,
}

impl<P: ControlProgram> ControlRunner<P> {
    /// Creates a new runner for the given control program.
    ///
    /// Uses default configuration. Call [`.config()`](Self::config) to customize.
    ///
    /// # Arguments
    ///
    /// * `program` - Your control program instance
    ///
    /// # Example
    ///
    /// ```ignore
    /// let runner = ControlRunner::new(MyProgram::new());
    /// ```
    pub fn new(program: P) -> Self {
        Self {
            config: RunnerConfig::default(),
            program,
        }
    }

    /// Sets the configuration for this runner.
    ///
    /// # Arguments
    ///
    /// * `config` - The configuration to use
    ///
    /// # Example
    ///
    /// ```ignore
    /// ControlRunner::new(MyProgram::new())
    ///     .config(RunnerConfig {
    ///         shm_name: "custom_shm".to_string(),
    ///         ..Default::default()
    ///     })
    ///     .run()?;
    /// ```
    pub fn config(mut self, config: RunnerConfig) -> Self {
        self.config = config;
        self
    }

    /// Starts the control loop.
    ///
    /// This method blocks indefinitely, running the control loop until
    /// an error occurs or the process is terminated.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` only if the loop exits cleanly (which typically
    /// doesn't happen). Returns an error if:
    ///
    /// - IPC connection fails
    /// - Shared memory cannot be opened
    /// - Signal offsets cannot be found
    /// - A critical error occurs during execution
    ///
    /// # Example
    ///
    /// ```ignore
    /// fn main() -> anyhow::Result<()> {
    ///     ControlRunner::new(MyProgram::new())
    ///         .config(config)
    ///         .run()
    /// }
    /// ```
    pub fn run(mut self) -> Result<()> {
        // Initialize UDP logger FIRST (before any log statements)
        if let Err(e) = logger::init_udp_logger(
            &self.config.server_host,
            self.config.log_udp_port,
            self.config.log_level,
            "control",
        ) {
            eprintln!("Warning: Failed to initialize UDP logger: {}", e);
            // Continue anyway - logging will just go nowhere
        }

        // We use a dedicated runtime for the setup phase
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()?;

        rt.block_on(async {
            log::info!("AutoCore Control Runner Starting...");

            // 1. Connect to server via WebSocket and get layout
            let ws_url = format!("ws://{}:{}/ws/", self.config.server_host, self.config.ws_port);
            log::info!("Connecting to server at {}", ws_url);

            let (ws_stream, _) = connect_async(&ws_url).await
                .map_err(|e| anyhow!("Failed to connect to server at {}: {}", ws_url, e))?;

            let (mut write, mut read) = ws_stream.split();

            // Send gm.get_layout request
            let request = CommandMessage::request("gm.get_layout", serde_json::Value::Null);
            let transaction_id = request.transaction_id;
            let request_json = serde_json::to_string(&request)?;

            write.send(Message::Text(request_json)).await
                .map_err(|e| anyhow!("Failed to send layout request: {}", e))?;

            // Wait for response with matching transaction_id
            let timeout = Duration::from_secs(10);
            let start = std::time::Instant::now();
            let mut layout: Option<HashMap<String, serde_json::Value>> = None;

            while start.elapsed() < timeout {
                match tokio::time::timeout(Duration::from_secs(1), read.next()).await {
                    Ok(Some(Ok(Message::Text(text)))) => {
                        if let Ok(response) = serde_json::from_str::<CommandMessage>(&text) {
                            if response.transaction_id == transaction_id {
                                if !response.success {
                                    return Err(anyhow!("Server error: {}", response.error_message));
                                }
                                layout = Some(serde_json::from_value(response.data)?);
                                break;
                            }
                            // Skip broadcasts and other messages
                            if response.message_type == MessageType::Broadcast {
                                continue;
                            }
                        }
                    }
                    Ok(Some(Ok(_))) => continue,
                    Ok(Some(Err(e))) => return Err(anyhow!("WebSocket error: {}", e)),
                    Ok(None) => return Err(anyhow!("Server closed connection")),
                    Err(_) => continue, // Timeout on single read, keep trying
                }
            }

            let layout = layout.ok_or_else(|| anyhow!("Timeout waiting for layout response"))?;
            log::info!("Layout received with {} entries.", layout.len());

            // We keep the WebSocket open for sending updates
            // let _ = write.close().await;

            // 2. Find Signal Offsets
            let tick_offset = self.find_offset(&layout, &self.config.tick_signal_name)?;
            let busy_offset = if let Some(name) = &self.config.busy_signal_name {
                Some(self.find_offset(&layout, name)?)
            } else {
                None
            };

            // 4. Open Shared Memory
            let shmem = ShmemConf::new().os_id(&self.config.shm_name).open()?;
            let base_ptr = shmem.as_ptr();
            log::info!("Shared Memory '{}' mapped.", self.config.shm_name);

            // 5. Setup Pointers
            // SAFETY: We trust the server's layout matches the generated GlobalMemory struct.
            let gm = unsafe { &mut *(base_ptr as *mut P::Memory) };

            // Get tick event from shared memory
            log::info!("Setting up tick event at offset {} (base_ptr: {:p})", tick_offset, base_ptr);
            let (tick_event, _) = unsafe {
                Event::from_existing(base_ptr.add(tick_offset))
            }.map_err(|e| anyhow!("Failed to open tick event: {:?}", e))?;
            log::info!("Tick event ready");

            // Busy signal event (optional)
            let busy_event = busy_offset.map(|offset| {
                unsafe { Event::from_existing(base_ptr.add(offset)) }
                    .map(|(event, _)| event)
                    .ok()
            }).flatten();

            // 6. Initialize local memory buffer and user program
            // We use a local copy for the control loop to ensure:
            // - Consistent snapshot of inputs at start of cycle
            // - Atomic commit of outputs at end of cycle
            // - Proper memory barriers for cross-process visibility
            let mut local_mem: P::Memory = unsafe { std::ptr::read_volatile(gm) };
            let mut prev_mem: P::Memory = local_mem; // Snapshot for change detection

            fence(Ordering::Acquire); // Ensure we see all prior writes from other processes

            self.program.initialize(&mut local_mem);

            // Write back any changes from initialize
            fence(Ordering::Release);
            unsafe { std::ptr::write_volatile(gm, local_mem) };

            // Set up signal handler for graceful shutdown
            let running = Arc::new(AtomicBool::new(true));
            let r = running.clone();
            
            // Only set handler if not already set
            if let Err(e) = ctrlc::set_handler(move || {
                r.store(false, Ordering::SeqCst);
            }) {
                log::warn!("Failed to set signal handler: {}", e);
            }

            log::info!("Entering Control Loop - waiting for first tick...");
            let mut cycle_count: u64 = 0;

            while running.load(Ordering::SeqCst) {
                // Wait for Tick - Event-based synchronization
                // Use a timeout (1s) to allow checking the running flag periodically
                match tick_event.wait(Timeout::Val(Duration::from_secs(1))) {
                    Ok(_) => {},
                    Err(e) => {
                        // Check for timeout
                        let err_str = format!("{:?}", e);
                        if err_str.contains("Timeout") {
                            continue;
                        }
                        return Err(anyhow!("Tick wait failed: {:?}", e));
                    }
                }

                if !running.load(Ordering::SeqCst) {
                    log::info!("Shutdown signal received, exiting control loop.");
                    break;
                }

                cycle_count += 1;
                if cycle_count == 1 {
                    log::info!("First tick received!");
                }

                // === INPUT PHASE ===
                // Read all variables from shared memory into local buffer.
                // This gives us a consistent snapshot of inputs for this cycle.
                // Acquire fence ensures we see all writes from other processes (server, modules).
                local_mem = unsafe { std::ptr::read_volatile(gm) };
                
                // Update prev_mem before execution to track changes made IN THIS CYCLE
                // Actually, we want to know what changed in SHM relative to what we last knew,
                // OR what WE changed relative to what we read?
                // The user wants "writes on shared variables" to be broadcast.
                // Typically outputs.
                // If inputs changed (from other source), broadcasting them again is fine too.
                // Let's capture state BEFORE execution (which is what we just read from SHM).
                prev_mem = local_mem;

                fence(Ordering::Acquire);

                // === EXECUTE PHASE ===
                // Execute user logic on the local copy.
                // All reads/writes during process_tick operate on local_mem.
                self.program.process_tick(&mut local_mem, cycle_count);

                // === OUTPUT PHASE ===
                // Write all variables from local buffer back to shared memory.
                // Release fence ensures our writes are visible to other processes.
                fence(Ordering::Release);
                unsafe { std::ptr::write_volatile(gm, local_mem) };

                // === CHANGE DETECTION & NOTIFICATION ===
                let changes = local_mem.get_changes(&prev_mem);
                if !changes.is_empty() {
                    // Construct bulk write message
                    let mut data_map = serde_json::Map::new();
                    for (key, val) in changes {
                        data_map.insert(key.to_string(), val);
                    }
                    
                    let msg = CommandMessage::request("gm.write", serde_json::Value::Object(data_map));
                    let msg_json = serde_json::to_string(&msg).unwrap_or_default();
                    
                    // Send via WebSocket (fire and forget, don't block)
                    // Note: WebSocket send is async. We are in block_on.
                    // We can await it. If it takes too long, it might delay the cycle.
                    // Ideally we should spawn this? But spawn requires 'static or Arc.
                    // For now, let's await with a very short timeout or just await.
                    // write is Sink.
                    if let Err(e) = write.send(Message::Text(msg_json)).await {
                        log::error!("Failed to send updates: {}", e);
                    }
                }

                // Signal Busy/Done event
                if let Some(ref busy_ev) = busy_event {
                    let _ = busy_ev.set(EventState::Signaled);
                }
            }

            Ok(())
        })
    }

    fn find_offset(&self, layout: &HashMap<String, serde_json::Value>, name: &str) -> Result<usize> {
        let info = layout.get(name).ok_or_else(|| anyhow!("Signal '{}' not found in layout", name))?;
        info.get("offset")
            .and_then(|v| v.as_u64())
            .map(|v| v as usize)
            .ok_or_else(|| anyhow!("Invalid offset for '{}'", name))
    }
}

/// Generates the standard `main` function for a control program.
///
/// This macro reduces boilerplate by creating a properly configured `main`
/// function that initializes and runs your control program.
///
/// # Arguments
///
/// * `$prog_type` - The type of your control program (must implement [`ControlProgram`])
/// * `$shm_name` - The shared memory segment name (string literal)
/// * `$tick_signal` - The tick signal name in shared memory (string literal)
///
/// # Example
///
/// ```ignore
/// mod gm;
/// use gm::GlobalMemory;
///
/// pub struct MyProgram;
///
/// impl MyProgram {
///     pub fn new() -> Self { Self }
/// }
///
/// impl autocore_std::ControlProgram for MyProgram {
///     type Memory = GlobalMemory;
///
///     fn process_tick(&mut self, mem: &mut GlobalMemory, _cycle: u64) {
///         // Your logic here
///     }
/// }
///
/// // This generates the main function
/// autocore_std::autocore_main!(MyProgram, "my_project_shm", "tick");
/// ```
///
/// # Generated Code
///
/// The macro expands to:
///
/// ```ignore
/// fn main() -> anyhow::Result<()> {
///     let config = autocore_std::RunnerConfig {
///         server_host: "127.0.0.1".to_string(),
///         ws_port: autocore_std::DEFAULT_WS_PORT,
///         module_name: "control".to_string(),
///         shm_name: "my_project_shm".to_string(),
///         tick_signal_name: "tick".to_string(),
///         busy_signal_name: None,
///         log_level: log::LevelFilter::Info,
///         log_udp_port: autocore_std::logger::DEFAULT_LOG_UDP_PORT,
///     };
///
///     autocore_std::ControlRunner::new(MyProgram::new())
///         .config(config)
///         .run()
/// }
/// ```
#[macro_export]
macro_rules! autocore_main {
    ($prog_type:ty, $shm_name:expr, $tick_signal:expr) => {
        fn main() -> anyhow::Result<()> {
            let config = autocore_std::RunnerConfig {
                server_host: "127.0.0.1".to_string(),
                ws_port: autocore_std::DEFAULT_WS_PORT,
                module_name: "control".to_string(),
                shm_name: $shm_name.to_string(),
                tick_signal_name: $tick_signal.to_string(),
                busy_signal_name: None,
                log_level: log::LevelFilter::Info,
                log_udp_port: autocore_std::logger::DEFAULT_LOG_UDP_PORT,
            };

            autocore_std::ControlRunner::new(<$prog_type>::new())
                .config(config)
                .run()
        }
    };
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_rtrig_rising_edge() {
        let mut trigger = RTrig::new();

        // No edge initially
        assert_eq!(trigger.call(false), false);

        // Rising edge
        assert_eq!(trigger.call(true), true);

        // No edge while high
        assert_eq!(trigger.call(true), false);
        assert_eq!(trigger.call(true), false);

        // No edge on falling
        assert_eq!(trigger.call(false), false);

        // Rising edge again
        assert_eq!(trigger.call(true), true);
    }

    #[test]
    fn test_ftrig_falling_edge() {
        let mut trigger = FTrig::new();

        // No edge initially
        assert_eq!(trigger.call(false), false);

        // No edge on rising
        assert_eq!(trigger.call(true), false);

        // Falling edge
        assert_eq!(trigger.call(false), true);

        // No edge while low
        assert_eq!(trigger.call(false), false);

        // Rising, then falling edge
        assert_eq!(trigger.call(true), false);
        assert_eq!(trigger.call(false), true);
    }

    #[test]
    fn test_ton_basic() {
        let mut timer = Ton::new();
        let pt = Duration::from_millis(50);

        // Disabled
        assert_eq!(timer.call(false, pt), false);
        assert_eq!(timer.et, Duration::ZERO);

        // Enable
        assert_eq!(timer.call(true, pt), false);
        assert!(timer.et < pt);

        // Wait for timer
        std::thread::sleep(Duration::from_millis(60));
        assert_eq!(timer.call(true, pt), true);
        assert_eq!(timer.et, pt);

        // Reset
        timer.reset();
        assert_eq!(timer.q, false);
        assert_eq!(timer.et, Duration::ZERO);
    }

    #[test]
    fn test_simple_timer_basic() {
        let mut timer = SimpleTimer::new(Duration::from_millis(50));

        // Not started yet
        assert_eq!(timer.is_done(), false);
        assert_eq!(timer.is_running(), false);
        assert_eq!(timer.elapsed(), Duration::ZERO);

        // Start
        timer.start();
        assert_eq!(timer.is_running(), true);
        assert_eq!(timer.is_done(), false);

        // Wait for timer
        std::thread::sleep(Duration::from_millis(60));
        assert_eq!(timer.is_done(), true);
        assert!(timer.elapsed() >= Duration::from_millis(50));

        // Reset
        timer.reset();
        assert_eq!(timer.is_done(), false);
        assert_eq!(timer.is_running(), false);
        assert_eq!(timer.elapsed(), Duration::ZERO);
    }

    #[test]
    fn test_simple_timer_restart() {
        let mut timer = SimpleTimer::new(Duration::from_millis(100));

        timer.start();
        std::thread::sleep(Duration::from_millis(30));

        // Restart resets the timer
        timer.start();
        assert!(timer.elapsed() < Duration::from_millis(20));
    }

    #[test]
    fn test_simple_timer_preset() {
        let mut timer = SimpleTimer::new(Duration::from_secs(5));

        assert_eq!(timer.preset(), Duration::from_secs(5));

        timer.set_preset(Duration::from_secs(10));
        assert_eq!(timer.preset(), Duration::from_secs(10));
    }

    #[test]
    fn test_simple_timer_default() {
        let mut timer = SimpleTimer::default();

        // Default preset is zero, so immediately done when started
        assert_eq!(timer.preset(), Duration::ZERO);

        timer.start();
        assert_eq!(timer.is_done(), true);
    }

    #[test]
    fn test_state_machine_basic() {
        let state = StateMachine::new();

        assert_eq!(state.index, 0);
        assert_eq!(state.error_code, 0);
        assert!(!state.is_error());
        assert_eq!(state.timer_preset, Duration::MAX);
        assert_eq!(state.timeout_preset, Duration::MAX);
    }

    #[test]
    fn test_state_machine_timer() {
        let mut state = StateMachine::new();
        state.timer_preset = Duration::from_millis(50);
        state.call();

        // Timer shouldn't be done yet
        assert!(!state.timer_done());

        // Wait for timer
        std::thread::sleep(Duration::from_millis(60));
        assert!(state.timer_done());
        assert!(state.elapsed() >= Duration::from_millis(50));
    }

    #[test]
    fn test_state_machine_timeout() {
        let mut state = StateMachine::new();
        state.timeout_preset = Duration::from_millis(50);
        state.call();

        assert!(!state.timed_out());

        std::thread::sleep(Duration::from_millis(60));
        assert!(state.timed_out());
    }

    #[test]
    fn test_state_machine_timer_reset_on_state_change() {
        let mut state = StateMachine::new();
        state.timer_preset = Duration::from_millis(50);
        state.call();

        // Wait a bit
        std::thread::sleep(Duration::from_millis(30));
        let elapsed_before = state.elapsed();
        assert!(elapsed_before >= Duration::from_millis(30));

        // Change state
        state.index = 10;
        state.call();

        // Timer should have reset
        assert!(state.elapsed() < Duration::from_millis(20));
        assert!(!state.timer_done());
    }

    #[test]
    fn test_state_machine_error_handling() {
        let mut state = StateMachine::new();

        assert!(!state.is_error());

        state.set_error(110, "Failed to home axis");
        assert!(state.is_error());
        assert_eq!(state.error_code, 110);
        assert_eq!(state.error_message, "Failed to home axis");

        state.clear_error();
        assert!(!state.is_error());
        assert_eq!(state.error_code, 0);
        assert!(state.error_message.is_empty());
    }

    #[test]
    fn test_state_machine_preset_persists() {
        let mut state = StateMachine::new();

        // Set preset in state 0
        state.timer_preset = Duration::from_millis(50);
        state.index = 10;
        state.call();

        // Preset should still be 50ms
        assert_eq!(state.timer_preset, Duration::from_millis(50));

        // Change to state 20 without changing preset
        state.index = 20;
        state.call();

        // Preset still 50ms
        assert_eq!(state.timer_preset, Duration::from_millis(50));
    }

    #[test]
    fn test_state_machine_default_presets_never_trigger() {
        let mut state = StateMachine::new();
        state.call();

        // Default presets are Duration::MAX, so timers should never trigger
        std::thread::sleep(Duration::from_millis(10));
        assert!(!state.timer_done());
        assert!(!state.timed_out());
    }
}