# rftools/calculators/protocol.py
# AUTO-GENERATED by scripts/generate_stubs.py — DO NOT EDIT
# Regenerate with: python scripts/generate_stubs.py --frontend-dir /path/to/frontend
"""
Typed stubs for the 'protocol' category (11 calculators).

Functions:
    uart_baud_rate(...) -> CalculatorResult
    i2c_pullup(...) -> CalculatorResult
    clock_jitter(...) -> CalculatorResult
    spi_timing(...) -> CalculatorResult
    can_bus_timing(...) -> CalculatorResult
    usb_termination(...) -> CalculatorResult
    rs485_termination(...) -> CalculatorResult
    i2s_timing(...) -> CalculatorResult
    lin_bus_timing(...) -> CalculatorResult
    modbus_frame_timing(...) -> CalculatorResult
    ethernet_cable(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


def _client() -> _rftools.Client:
    return _rftools._get_default_client()


def uart_baud_rate(baudRate: float = 115200.0, dataBits: float = 8.0, stopBits: float = 1.0, parity: float = 0.0, clockFreq: float = 16.0) -> CalculatorResult:
    """
    UART Baud Rate & Frame Timing Calculator

    Category: protocol

    Calculate UART frame timing, throughput, and USART BRR register divisor from baud rate, data format, and MCU clock frequency. Identify baud rate error for reliable serial communication.

    Parameters
    ----------
    baudRate : float
        Baud Rate (bps) (default: 115200.0)
    dataBits : float
        Data Bits (bits) (default: 8.0)
    stopBits : float
        Stop Bits (bits) (default: 1.0)
    parity : float
        Parity Bits (bits) (default: 0.0)
    clockFreq : float
        MCU Clock Frequency (MHz) (default: 16.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'frameBits', 'bitPeriod_us', 'framePeriod_us', 'framesPerSecond', 'throughputKbps', 'brrDivisor', 'actualBaudRate', 'baudRateError_pct'
    """
    inputs = {"baudRate": baudRate, "dataBits": dataBits, "stopBits": stopBits, "parity": parity, "clockFreq": clockFreq}
    return _client().calculate('uart-baud-rate', inputs)


def i2c_pullup(vdd: float = 3.3, speedMode: float = 1.0, busCap: float = 100.0, numDevices: float = 2.0) -> CalculatorResult:
    """
    I2C Pull-Up Resistor Calculator

    Category: protocol

    Calculate I2C pull-up resistor values for Standard (100 kHz), Fast (400 kHz), and Fast-Plus (1 MHz) modes. Derives minimum, maximum, and recommended resistance from supply voltage and bus capacitance per NXP UM10204.

    Parameters
    ----------
    vdd : float
        Supply Voltage (V) (default: 3.3)
    speedMode : float
        Speed Mode (default: 1.0)
    busCap : float
        Bus Capacitance (pF) (default: 100.0)
    numDevices : float
        Number of Devices (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'R_max_ohm', 'R_min_ohm', 'R_recommended_ohm', 'current_ma', 'powerPerLine_mw', 'riseTimeTarget_ns'
    """
    inputs = {"vdd": vdd, "speedMode": speedMode, "busCap": busCap, "numDevices": numDevices}
    return _client().calculate('i2c-pullup', inputs)


def clock_jitter(clockFreqMHz: float = 200.0, setupTime_ps: float = 80.0, holdTime_ps: float = 40.0, refJitter_ps: float = 50.0, pllJitter_ps: float = 100.0, bufferJitter_ps: float = 25.0, bufferStages: float = 2.0, traceDelay_ps: float = 20.0) -> CalculatorResult:
    """
    Clock Tree Jitter Budget Calculator

    Category: protocol

    Calculate clock tree timing budget for FPGA and SoC designs. Enter reference oscillator jitter, PLL noise floor, buffer stages, and target clock frequency to compute setup margin.

    Parameters
    ----------
    clockFreqMHz : float
        Clock Frequency (MHz) (default: 200.0)
    setupTime_ps : float
        Register Setup Time (ps) (default: 80.0)
    holdTime_ps : float
        Register Hold Time (ps) (default: 40.0)
    refJitter_ps : float
        Reference Oscillator Jitter (ps) (default: 50.0)
    pllJitter_ps : float
        PLL Added Jitter (ps) (default: 100.0)
    bufferJitter_ps : float
        Clock Buffer Jitter (ps) (default: 25.0)
    bufferStages : float
        Buffer Stages (default: 2.0)
    traceDelay_ps : float
        PCB Trace Skew (ps) (default: 20.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'setupMargin_ps', 'totalJitter_ps', 'budgetUsed_pct', 'availableBudget_ps', 'periodPs'
    """
    inputs = {"clockFreqMHz": clockFreqMHz, "setupTime_ps": setupTime_ps, "holdTime_ps": holdTime_ps, "refJitter_ps": refJitter_ps, "pllJitter_ps": pllJitter_ps, "bufferJitter_ps": bufferJitter_ps, "bufferStages": bufferStages, "traceDelay_ps": traceDelay_ps}
    return _client().calculate('clock-jitter', inputs)


def spi_timing(clockFreq: float = 10.0, dataWidth: float = 8.0, traceCapacitance: float = 20.0, driveStrength: float = 4.0) -> CalculatorResult:
    """
    SPI Timing & Signal Integrity Calculator

    Category: protocol

    Calculate SPI bus timing parameters including bit period, frame time, maximum clock frequency limited by trace capacitance, and signal slew rate

    Parameters
    ----------
    clockFreq : float
        SPI Clock Frequency (MHz) (default: 10.0)
    dataWidth : float
        Data Word Width (bits) (default: 8.0)
    traceCapacitance : float
        Trace Capacitance (pF) (default: 20.0)
    driveStrength : float
        Drive Strength (mA) (default: 4.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'bitPeriod', 'framePeriod', 'maxFreqCapacitive', 'slewRate', 'dataRate'
    """
    inputs = {"clockFreq": clockFreq, "dataWidth": dataWidth, "traceCapacitance": traceCapacitance, "driveStrength": driveStrength}
    return _client().calculate('spi-timing', inputs)


def can_bus_timing(clockFreq: float = 48.0, baudRate: float = 500.0, samplePoint: float = 87.5) -> CalculatorResult:
    """
    CAN Bus Bit Timing Calculator

    Category: protocol

    Calculate CAN bus bit timing parameters including prescaler, time quanta, sync segment, propagation segment, and phase buffer segments for a given baud rate and sample point

    Parameters
    ----------
    clockFreq : float
        System Clock Frequency (MHz) (default: 48.0)
    baudRate : float
        CAN Baud Rate (kbps) (default: 500.0)
    samplePoint : float
        Sample Point (%) (default: 87.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'tq', 'nominalBitTime', 'syncSeg', 'propSeg', 'phase1', 'phase2', 'prescaler'
    """
    inputs = {"clockFreq": clockFreq, "baudRate": baudRate, "samplePoint": samplePoint}
    return _client().calculate('can-bus-timing', inputs)


def usb_termination(usbVersion: float = 0.0, lineImpedance: float = 90.0, cableLength: float = 2.0) -> CalculatorResult:
    """
    USB Termination & Signal Integrity Calculator

    Category: protocol

    Calculate USB bus termination resistor values, differential impedance, cable propagation delay, signal rise time, and eye opening for USB 2.0 and USB 3.0

    Parameters
    ----------
    usbVersion : float
        USB Version (default: 0.0)
    lineImpedance : float
        Line Impedance (Ω) (default: 90.0)
    cableLength : float
        Cable Length (m) (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'terminationResistor', 'differentialImpedance', 'propagationDelay', 'signalRiseTime', 'eyeOpening'
    """
    inputs = {"usbVersion": usbVersion, "lineImpedance": lineImpedance, "cableLength": cableLength}
    return _client().calculate('usb-termination', inputs)


def rs485_termination(baudRate: float = 115.2, cableLength: float = 100.0, numNodes: float = 10.0, supplyVoltage: float = 5.0) -> CalculatorResult:
    """
    RS-485 Termination & Bias Resistor Calculator

    Category: protocol

    Calculate RS-485 bus termination resistors, bias resistors, maximum baud rate for cable length, propagation delay, and bias current consumption

    Parameters
    ----------
    baudRate : float
        Baud Rate (kbps) (default: 115.2)
    cableLength : float
        Total Cable Length (m) (default: 100.0)
    numNodes : float
        Number of Nodes (default: 10.0)
    supplyVoltage : float
        Supply Voltage (V) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'terminationResistor', 'biasResistor', 'maxBaudRate', 'propagationDelay', 'loadCurrent'
    """
    inputs = {"baudRate": baudRate, "cableLength": cableLength, "numNodes": numNodes, "supplyVoltage": supplyVoltage}
    return _client().calculate('rs485-termination', inputs)


def i2s_timing(sampleRate: float = 44.1, bitDepth: float = 24.0, channels: float = 2.0) -> CalculatorResult:
    """
    I2S Audio Interface Timing Calculator

    Category: protocol

    Calculate I2S bit clock (BCLK), word clock (LRCLK/WCLK), and data rate for audio interfaces at any sample rate, bit depth, and channel count.

    Parameters
    ----------
    sampleRate : float
        Sample Rate (kHz) (default: 44.1)
    bitDepth : float
        Bit Depth (bits) (default: 24.0)
    channels : float
        Channels (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'bclk', 'wclk', 'bclkPeriod', 'dataRate'
    """
    inputs = {"sampleRate": sampleRate, "bitDepth": bitDepth, "channels": channels}
    return _client().calculate('i2s-timing', inputs)


def lin_bus_timing(baudRate: float = 19.2, dataBytes: float = 8.0) -> CalculatorResult:
    """
    LIN Bus Timing Calculator

    Category: protocol

    Calculate LIN bus bit time, break field length, frame time, and maximum frame rate for automotive LIN network design.

    Parameters
    ----------
    baudRate : float
        Baud Rate (kbps) (default: 19.2)
    dataBytes : float
        Data Bytes (bytes) (default: 8.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'bitTime', 'breakLength', 'frameTime', 'framesPerSec', 'busLoad'
    """
    inputs = {"baudRate": baudRate, "dataBytes": dataBytes}
    return _client().calculate('lin-bus-timing', inputs)


def modbus_frame_timing(baudRate: float = 9600.0, dataBytes: float = 8.0, parityBits: float = 1.0, stopBits: float = 1.0) -> CalculatorResult:
    """
    Modbus RTU Frame Timing Calculator

    Category: protocol

    Calculate Modbus RTU character time, 3.5-character inter-frame gap, total frame duration, and maximum frame rate.

    Parameters
    ----------
    baudRate : float
        Baud Rate (bps) (default: 9600.0)
    dataBytes : float
        Data Bytes (bytes) (default: 8.0)
    parityBits : float
        Parity Bits (bits) (default: 1.0)
    stopBits : float
        Stop Bits (bits) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'charTime', 't35', 'frameTime', 'maxFrameRate'
    """
    inputs = {"baudRate": baudRate, "dataBytes": dataBytes, "parityBits": parityBits, "stopBits": stopBits}
    return _client().calculate('modbus-frame-timing', inputs)


def ethernet_cable(cableType: float = 2.0, length: float = 50.0, speed: float = 2.0) -> CalculatorResult:
    """
    Ethernet Cable Length & Attenuation Calculator

    Category: protocol

    Calculate Ethernet cable attenuation, maximum cable length, and pass/fail for Cat5e, Cat6, Cat6a, and Cat8 at 100Mbps, 1Gbps, and 10Gbps.

    Parameters
    ----------
    cableType : float
        Cable Category (default: 2.0)
    length : float
        Cable Length (m) (default: 50.0)
    speed : float
        Network Speed (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'attenuation', 'maxLength', 'headroom', 'passOrFail'
    """
    inputs = {"cableType": cableType, "length": length, "speed": speed}
    return _client().calculate('ethernet-cable', inputs)

