documentate

vendortools/nfutil.py

@@ -99,8 +99,26 @@ MAX_TIMEOUT                     = 0.5
 #        PAD: b'\x00\x00'
 
 
+#-----------------------------------------------------------------------------
+def MkSeq():
+    """Generate a random int for the SEQ parameter, used as a type of CRC."""
+    return random.randint(1, 65535)
+
+
 #-----------------------------------------------------------------------------
 def MkHeader(header, seq, eth_addr):
+    """Generate a network header packet.
+
+    :param header: The header byte that identifies the payload
+    :type header: byte
+    :param seq: The SEQ parameter, used as a simple CRC for the packet.
+    :type seq: int
+    :param eth_addr: The ethernet address (MAC) of the sender.
+    :type eth_addr: bytes
+    :returns: a bytestring representing the header data
+    :rtype: bytes
+    """
+
     return struct.pack(
         HEADER_FMT,
         bytes([NF_MAGIC]),
@@ -112,11 +130,13 @@ def MkHeader(header, seq, eth_addr):
 
 #-----------------------------------------------------------------------------
 def MkIdentify(seq):
+    """Generate an Identify packet."""
     return MkHeader(NF_IDENTIFY, seq, bytes([0xFF]) * 6)
 
 
 #-----------------------------------------------------------------------------
 def MkIdentifyReply(seq, vDev):
+    """Generate an IdentifyReply packet."""
     # header: 12 bytes
     # IdentifyReplyData: 64 bytes
     # header
@@ -161,6 +181,29 @@ def MkIdentifyReply(seq, vDev):
 
 #-----------------------------------------------------------------------------
 def MkAssignment(seq, eth_addr, ip_type, ip_addr, netmask, gateway):
+    """Generate a network configuration packet.
+
+    The network configuration packet will configure the network settings of a
+    Prologix Ethernet GPIB device.
+
+    Parameters
+    ----------
+    eth_addr : bytes
+        The ethernet address (MAC) of the target device to configure
+    ip_type : int
+        The type of IP configuration; either NF_IP_STATIC or NF_IP_DYNAMIC
+    ip_addr : str
+        The static IP address to set on the target device
+    netmask : str
+        The netmask to set on the target device
+    gateway : str
+        The network gateway to set on the target device
+
+    Returns
+    -------
+    bytes
+        A bytestring representing the data packet to send to the target device
+    """
     return MkHeader(NF_ASSIGNMENT, seq, eth_addr) + \
         struct.pack(
             ASSIGNMENT_FMT,