Function optimize_datasheet_timing

ci/tools/led_timing_conversions.py:224–287

Optimize datasheet timing to be spec-compliant with symmetric cycles. Strategy: 1. Keep measured T0H and T1H (high times are most critical) 2. Minimize T0H (reduce jitter impact - timers never fire early) 3. Adjust T0L and T1L to create symmetric cycles (T0H+T0L = T1H+T1

(
    measured: TimingDatasheet, spec: TimingSpec
)

def optimize_datasheet_timing(
    measured: TimingDatasheet, spec: TimingSpec
) -> TimingDatasheet:
    """Optimize datasheet timing to be spec-compliant with symmetric cycles.

    Strategy:
        1. Keep measured T0H and T1H (high times are most critical)
        2. Minimize T0H (reduce jitter impact - timers never fire early)
        3. Adjust T0L and T1L to create symmetric cycles (T0H+T0L = T1H+T1L)
        4. Ensure all values are within spec ranges

    Args:
        measured: Measured timing values (may be out of spec or asymmetric)
        spec: Datasheet specifications (min/max ranges)

    Returns:
        Optimized spec-compliant symmetric timing

    Example:
        >>> spec = TimingSpec(220, 380, 580, 1000, 580, 1000, 580, 1000)
        >>> measured = TimingDatasheet(264, 920, 640, 552)  # Asymmetric, T1L out of spec
        >>> optimized = optimize_datasheet_timing(measured, spec)
        >>> print(optimized)
        T0H=264ns, T0L=1000ns, T1H=640ns, T1L=624ns (cycle=1264ns)
    """
    # Use measured high times (most critical for signal integrity)
    # KEEP both T0H and T1H from measured values because they're hardware-dependent
    T0H = measured.T0H
    T1H = measured.T1H

    # Clamp high times to spec ranges
    T0H = max(spec.T0H_min, min(T0H, spec.T0H_max))
    T1H = max(spec.T1H_min, min(T1H, spec.T1H_max))

    # For symmetric cycles: T0H + T0L = T1H + T1L
    # We need to find T0L and T1L such that:
    # 1. T0L and T1L are both in spec ranges
    # 2. T0H + T0L = T1H + T1L (symmetric)

    # From symmetry: T0L = T1L + (T1H - T0H)
    # We need: T0L_min <= T1L + (T1H - T0H) <= T0L_max
    #          T1L_min <= T1L <= T1L_max

    # Solving for valid T1L range:
    # T0L_min <= T1L + (T1H - T0H) <= T0L_max
    # T0L_min - (T1H - T0H) <= T1L <= T0L_max - (T1H - T0H)

    delta = T1H - T0H
    T1L_min_constrained = max(spec.T1L_min, spec.T0L_min - delta)
    T1L_max_constrained = min(spec.T1L_max, spec.T0L_max - delta)

    if T1L_min_constrained > T1L_max_constrained:
        # No valid solution - use fallback (maximize T1L to get T0L at max)
        T1L = spec.T1L_max
        T0L = T1L + delta
    else:
        # CRITICAL: Maximize T1L to provide maximum margin above minimum spec
        # This is important because measured T1L is often below spec due to