IO documentation

Author: gkpau

doc/api/io.rst

@@ -1,6 +1,9 @@
 IO
 ==
 
+See IOs and pin mapping diagrams `here`_.
+
+.. _here: https://github.com/dspsandbox/Redpitaya-IO-Sync#ios--pin-mapping
 
 Base IO
 -------

doc/index.rst

@@ -6,7 +6,7 @@ Library for synchronous and deterministic control of RedPitaya's digital and ana
 .. toctree::
    :maxdepth: 2
    :caption: Contents
-   
+
    api/device
    api/sequence
    api/frame

driver/src/redpitaya_io_sync/io/analog.py

@@ -5,10 +5,18 @@ class AnalogOutCmd(Enum):
     DUTY_CYCLE = 0x0
 
 class AnalogOut(BaseIo): 
+    """
+    Driver class for low speed analog IOs (PWM + Low Pass Filter).
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)
 
     def duty_cycle(self, val: float):
+        """
+        Define scale of underlying Sigma-Delta Modulator (12-bit resolution).
+
+        :param val: Relative scale in range [0.0, 1.0].
+        """
         DUTY_CYCLE_MIN = 0.0
         DUTY_CYCLE_MAX = 1.0
         MODULATION_DEPTH = 12

driver/src/redpitaya_io_sync/io/base.py

@@ -28,6 +28,9 @@ def __init__(self, addr, clk_freq):
 
 
     def reset(self):
+        """
+        Reset IO instruction cache and time base.
+        """
         self._tlast = 0
         self._tnext = 0
         self._tincr = 1
@@ -91,22 +94,45 @@ def _get_instruction_and_time_list(self):
         return instr_list, t_list  
 
 
-    def get_time(self):
+    def get_time(self) -> int:
+        """
+        Retrieve current IO time (in units of CLK cycles).
+        """
         return self._tnext
 
     def set_time(self, val: int):
+        """
+        Define new IO time (should be larger or equal than current IO time).
+
+        :param val: time (in units of clk cycles).
+
+        """
         if val < self._tnext:
             raise Exception(f"Cannot set time to {val} because it is smaller than current time {self._tnext}.")
         self._tnext = np.uint64(val)
     def set_time_increment(self, val: int):
+        """
+        Define IO instruction time increment, i.e. time between consecutive IO instructions. Default time increment after reset is 1 clk cycle.
+
+        :param val: time increment (in units of clk cycles).
+        """
         if val <= 0:
             raise Exception(f"Time increment must be a positive integer. Got {val} instead.")
         self._tincr = np.uint64(val)
 
-    def get_time_increment(self):
+    def get_time_increment(self) -> int:
+        """
+        Retrieve current IO time increment (in units of clk cycles).
+        """
         return self._tincr
 
     def delay(self, val: int = 0):
+        """
+        Increment current IO time by a specified delay time. Used to retard following IO instruction.
+
+        :param val: Delay time (in units of clk cycles).
+
+        """
         t = self.get_time()
         self.set_time(t + val)
 

driver/src/redpitaya_io_sync/io/digital.py

@@ -6,13 +6,34 @@ class DigitalIoCmd(Enum):
     TRISTATE = 0x1
 
 class DigitalIo(BaseIo):
+    """
+    Driver class for Digital IOs.
+
+    .. note::
+        Ports configured as inputs (high-impedance via :meth:`tristate`) include internal pull-up resistors and will idle high when left undriven.
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)
 
     def output(self, val: int, mask: int = 0xffff):
-        self._add_instruction(cmd=DigitalIoCmd.OUTPUT.value,  data=((mask << 16) | val))
-        
+        """
+        Set output value of masked ports (requires ports to be defined as outputs via :meth:`DigitalIo.tristate`).
+        E.g. ``val=0b0010`` and ``mask=0b1010`` will result in port[0] -> unchanged, port[1] -> 1, port[2] -> unchanged and port[3] -> 0.
+
+        :param val: Output value.
+        :param mask: Bit mask for updating digital ports.
+        """
+        self._add_instruction(cmd=DigitalIoCmd.OUTPUT.value, data=((mask << 16) | val))
+
     def tristate(self, val: int, mask: int = 0xffff):
+        """
+        Set direction (output/tristate) of masked ports.
+        A ``0`` bit configures the corresponding port as a driven output; a ``1`` bit puts it in high-impedance (input) mode.
+        E.g. ``val=0b0010`` and ``mask=0b1010`` will result in port[0] -> unchanged, port[1] -> high-Z (input), port[2] -> unchanged and port[3] -> driven (output).
+
+        :param val: Direction value (0 = driven output, 1 = high-impedance / input).
+        :param mask: Bit mask for updating digital ports.
+        """
         self._add_instruction(cmd=DigitalIoCmd.TRISTATE.value, data=((mask << 16) | val))
 
 

driver/src/redpitaya_io_sync/io/led.py

@@ -5,11 +5,21 @@ class LedCmd(Enum):
     OUTPUT = 0x0
 
 class Led(BaseIo):
+    """
+    Driver class for the onboard LEDs.
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)
 
     def output(self, val: int, mask: int = 0xffff):
-        self._add_instruction(cmd=LedCmd.OUTPUT.value,  data=((mask << 16) | val))
+        """
+        Set the on/off state of masked LEDs.
+        E.g. ``val=0b0010`` and ``mask=0b1010`` will result in LED[0] -> unchanged, LED[1] -> on, LED[2] -> unchanged and LED[3] -> off.
+
+        :param val: LED state value (1 = on, 0 = off).
+        :param mask: Bit mask for selecting which LEDs to update.
+        """
+        self._add_instruction(cmd=LedCmd.OUTPUT.value, data=((mask << 16) | val))
 
 
 

driver/src/redpitaya_io_sync/io/rf.py

@@ -12,52 +12,99 @@ class RfCmd(Enum):
 
 
 class RfBase(BaseIo):
+    """
+    Base driver class for RF IOs (DDS-based signal generation).
+
+    Wraps a direct digital synthesizer (DDS) core and provides control over
+    frequency, phase, and amplitude. The ``update`` flag on each method controls
+    whether the new value is applied immediately (``True``) or staged for a later
+    atomic update (``False``), which allows frequency, phase, and amplitude to be
+    changed simultaneously.
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)
 
-    def frequency(self, val: int, update: bool = True):
+    def frequency(self, val: float, update: bool = True):
+        """
+        Set the output frequency.
+
+        The valid range is ``[-clk_freq/2, clk_freq/2]`` (i.e. ±62.5 MHz for a 125 MHz clock).
+
+        :param val: Frequency in Hz.
+        :param update: If ``True``, apply the new value immediately. Set to ``False`` to stage
+            the change and apply it atomically together with other staged parameters.
+        """
         FREQ_MIN = -self._clk_freq / 2
         FREQ_MAX = self._clk_freq / 2
         if (val < FREQ_MIN) or (val > FREQ_MAX):
             raise Exception(f"Frequency value {val} is out of range [{FREQ_MIN}, {FREQ_MAX}].")
-        cmd = RfCmd.FREQ.value 
-        if update: 
+        cmd = RfCmd.FREQ.value
+        if update:
             cmd |= RfCmd.UPDATE.value
-        data = int(val / self._clk_freq * ((1 << 32) - 1))         
+        data = int(val / self._clk_freq * ((1 << 32) - 1))
         self._add_instruction(cmd=cmd, data=data)
 
-    def phase(self, val: int, update: bool = True):
-        cmd = RfCmd.PHASE.value 
-        if update: 
+    def phase(self, val: float, update: bool = True):
+        """
+        Set the output phase.
+
+        The value is taken modulo 360°, so any value outside ``[0°, 360°)`` wraps around.
+
+        :param val: Phase in degrees.
+        :param update: If ``True``, apply the new value immediately. Set to ``False`` to stage
+            the change and apply it atomically together with other staged parameters.
+        """
+        cmd = RfCmd.PHASE.value
+        if update:
             cmd |= RfCmd.UPDATE.value
-        data = int((val % 360) / 360 * ((1 << 32) - 1)) 
-        self._add_instruction(cmd=cmd,  data=data)
-    
-    def amplitude(self, val: int, update: bool = True):
+        data = int((val % 360) / 360 * ((1 << 32) - 1))
+        self._add_instruction(cmd=cmd, data=data)
+
+    def amplitude(self, val: float, update: bool = True):
+        """
+        Set the output amplitude.
+
+        The valid range is ``[-1, 1]``, where ``±1`` corresponds to full-scale output.
+
+        :param val: Amplitude as a normalized value in ``[-1, 1]``.
+        :param update: If ``True``, apply the new value immediately. Set to ``False`` to stage
+            the change and apply it atomically together with other staged parameters.
+        """
         AMPL_MIN = -1
         AMPL_MAX = 1
         if (val < AMPL_MIN) or (val > AMPL_MAX):
             raise Exception(f"Amplitude value {val} is out of range [{AMPL_MIN}, {AMPL_MAX}].")
-        
         cmd = RfCmd.AMPL.value
-        if update: 
+        if update:
             cmd |= RfCmd.UPDATE.value
-        data = int(val * ((1 << 15) - 1)) 
+        data = int(val * ((1 << 15) - 1))
         self._add_instruction(cmd=cmd, data=data)
 
     def phase_reset(self, update: bool = True):
-        data = 1
-        cmd = RfCmd.PHASE_RST.value 
-        if update: 
+        """
+        Reset the DDS phase accumulator to zero.
+
+        :param update: If ``True``, apply immediately. Set to ``False`` to stage the reset
+            and apply it atomically together with other staged parameters.
+        """
+        cmd = RfCmd.PHASE_RST.value
+        if update:
             cmd |= RfCmd.UPDATE.value
-        self._add_instruction(cmd=cmd, data=data)
+        self._add_instruction(cmd=cmd, data=1)
 
 
 class RfOut(RfBase):
+    """
+    Driver class for RF output channels.
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)
-       
+
+
 class RfIn(RfBase):
+    """
+    Driver class for RF input channels (TODO: missing FPGA backend).
+    """
     def __init__(self, addr, clk_freq):
         super().__init__(addr, clk_freq)