casp_udio.py

"""! This module defines functions to communicate with target hardware (i.e micro-controller board, SBC etc.) that is programmed with either:
 
- CASP model consisting of communication blocks such as Serial, WiFi or Ethernet blocks that are configured to communicate with host using CASP UDIO protocol
- (or) User C/C++ code that can communicate with host using CASP UDIO protocol through Serial, WiFi or Ethernet communication.
 
All functions in this module uses global object \ref _casp_process.casp_gpio_proc from \ref _casp_process.py module.
 
<b>About CASP UDIO:</b>
 
CASP UDIO (User Data Input Output) is a simple communication protocol to exchange data with remote device or computer. The data exchange format is basically divided into header and payload. The format of header (4 Byte long) is as follows:
 
- Byte index 0: Start byte with value 0x74
- Byte indexes 1 and 2: Payload length (2 byte value)
- Byte index 3: Checksum of payload bytes (sum of all payload bytes)
- Byte index 4 and above: Payload bytes. Payload length should be in multiples of 4.
 
The payload bytes in general can be anything that is understandable between sender and receiver. However, the payload bytes are accessed (read and write) as 4 byte (or 32-bit) integers or floats. As such payload length should be in multiples of 4. This protocol is used mostly to transfer data as a contiguous sequence of 32-bit integers and floats irrespective of whether the underlying data is 32-bit integer or float. i.e. the actual data can of two 16-bit integers or a 64-bit integer or float split into two 32-bit integers at raw byte level.
 
This protocol is generally used within CASP domain to communicate between host and targets with minimum overheard.
 
In Python UDI and UDO is always accessed as 32-bit integer or 32-bit float. Even UDI and UDO indexes that are specified in functions such as ReadI(), ReadF(), WriteI() and WriteF() indicate UDI/UDO index and not byte index.
"""

import importlib
from _casp_process import casp_gpio_proc
import casp_utils as utils

def Init():
    """! Initializes CASP UDIO subprocess. This is the first function to be called before using any other function in this module.
    """
    casp_gpio_proc.init()

def HelpPython():
    """! Opens CASP Python Libraries documentation.
    """
    response = casp_proc.write("casp.help.python")

def Close():
    """! Terminates CASP UDIO subprocess and releases the resources.
    """
    casp_gpio_proc.close()

def ConnectSerial(serial_port: str="COM3", udi_bytes: int=16, udo_bytes: int=16, enable_dtr: bool=True, send_recv_delay: int=1, baud: int=115200) -> bool:
    """! Initializes CASP UDIO connection process with the target over serial port. Performs initial protocol hand shake and keep things ready for data read/write operations.
 
    User can use \ref SerialPorts() to know available serial ports on the device.
 
    Arguments:
 
        serial_port: Set serial port to which device is connected.
 
        udi_bytes: Set 'User Data Input (UDI)' bytes for receiving data from the target. Default value is 16 bytes.
 
        udo_bytes: Set 'User Data Output (UDO)' bytes for sending data from the target. Default value is 16 bytes.
 
        enable_dtr: Set to True when serial data terminal ready (DTR) control signal is to be used. Default value is True. Set to False if device is not detectable (generally on old hardware).
 
        send_recv_delay: Set send receive time delay in milli seconds. Generally set between 1 to 5 msec. Smaller values reduces latency at the cost of increased CPU utilization and vice versa. Default value is 1 msec.
 
        baud: Set baud rate in bits per second. Default value is 115200 bps.
 
    Return Value:
 
        Returns True if connection is successful. Else returns False.
    """
    print(f"CASP: Connecting to serial device...")
    response = casp_gpio_proc.write("casp.connect.serial", [serial_port, str(baud), str(int(enable_dtr)), str(send_recv_delay), str(udi_bytes), str(udo_bytes)])
    if len(response) == 0:
        response = "CASP: Empty response."
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    ack:bool = False
    if len(strs) > 1:
        ack = bool(strs[1])
    return ack

def ConnectEth(ip: str, port: int=42001, udi_bytes: int=16, udo_bytes: int=16, tcp: bool=False, send_recv_delay: int=1) -> bool:
    """! Initializes CASP UDIO connection process with the target over ethernet. Performs initial protocol hand shake and keep things ready for data read/write operations.
 
    Arguments:
 
        ip: Set IP address of the target device. Both IP4 and IP6 are supported.
 
        port: Set port number of the target device. Mostly, better leave it to default.
 
        udi_bytes: Set 'User Data Input (UDI)' bytes for receiving data from the target. Default value is 16 bytes.
 
        udo_bytes: Set 'User Data Output (UDO)' bytes for sending data from the target. Default value is 16 bytes.
 
        tcp: Set to True when TCP protocol is to be used else UDP protocol will be used during communication.
 
        send_recv_delay: Set send receive time delay in milli seconds. Generally set between 1 to 5 msec. Smaller values reduces latency at the cost of increased CPU utilization and vice versa. Default value is 1 msec.
 
    Return Value:
 
        Returns True if connection is successful. Else returns False.
    """
    print(f"CASP: Connecting to ethernet device...")
    response = casp_gpio_proc.write("casp.connect.eth", [ip, str(port), str(int(tcp)), str(send_recv_delay), str(udi_bytes), str(udo_bytes)])
    if len(response) == 0:
        response = "CASP: Empty response."
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    ack:bool = False
    if len(strs) > 1:
        ack = bool(strs[1])
    return ack

def SerialPorts():
    """! Displays available serial ports on the host. User can use this function before using the \ref ConnectSerial() function.
    """
    response = casp_gpio_proc.write("casp.serial.ports")
    if len(response) == 0:
        response = "Empty response."
    print(f"CASP: {response.strip()}")

def ReadI(udi_idx: int) -> int:
    """! Reads User Data Input (UDI) value of type 32-bit integer from the target and returns the value as an integer.
 
    Arguments:
 
        udi_idx: UDI index from which the value is to be read. It should be greater than -1 and less than 'udi_bytes' specified in ConnectSerial() or ConnectEth() functions divided by 4.
 
    Return Value:
 
        Returns the UDI value received from the target as an integer.
    """
    response = casp_gpio_proc.write("casp.udi_read.i", [str(udi_idx)])
    if len(response) == 0:
        response = "Empty response."
    strs = utils.SplitString(response.strip())
    if "Error" in strs[0]:
        print(f"CASP: ReadI({udi_idx}) Failed: {strs[0]}")
    val: int = 0
    if len(strs) > 1:
        val = int(strs[1])
    return val

def ReadF(udi_idx: int) -> float:
    """! Reads User Data Input (UDI) value of type 32-bit float from the target and returns the value as an float.
 
    Arguments:
 
        udi_idx: UDI index from which the value is to be read. It should be greater than -1 and less than 'udi_bytes' specified in ConnectSerial() or ConnectEth() functions divided by 4.
 
    Return Value:
 
        Returns the UDI value received from the target as an float.
    """
    response = casp_gpio_proc.write("casp.udi_read.f", [str(udi_idx)])
    if len(response) == 0:
        response = "Empty response."
    strs = utils.SplitString(response.strip())
    if "Error" in strs[0]:
        print(f"CASP: ReadF({udi_idx}) Failed: {strs[0]}")
    val: float = 0
    if len(strs) > 1:
        val = float(strs[1])
    return val

def WriteI(udo_idx: int, value: int) -> bool:
    """! Writes User Data Output (UDO) value of type 32-bit integer to the target and returns the status of the write operation.
 
    Arguments:
 
        udo_idx: UDO index to which the value is to be written. It should be greater than -1 and less than 'udo_bytes' specified in ConnectSerial() or ConnectEth() functions divided by 4.
 
        value: Value to write.
 
    Return Value:
 
        Returns True if write operation is successful else returns False.
    """
    response = casp_gpio_proc.write("casp.udo_write.i", [str(udo_idx), str(value)])
    if len(response) == 0:
        response = "Empty response."
    strs = utils.SplitString(response.strip())
    ack:bool = False
    if len(strs) > 1:
        ack = bool(strs[1])
    if ack == False:
        print(f"CASP: WriteI({udo_idx}) Failed: {strs[0]}")
    return ack

def WriteF(udo_idx: int, value: float) -> bool:
    """! Writes User Data Output (UDO) value of type 32-bit float to the target and returns the status of the write operation.
 
    Arguments:
 
        udo_idx: UDO index to which the value is to be written. It should be greater than -1 and less than 'udo_bytes' specified in ConnectSerial() or ConnectEth() functions divided by 4.
 
        value: Value to write.
 
    Return Value:
 
        Returns True if write operation is successful else returns False.
    """
    response = casp_gpio_proc.write("casp.udo_write.f", [str(udo_idx), str(value)])
    if len(response) == 0:
        response = "Empty response."
    strs = utils.SplitString(response.strip())
    ack:bool = False
    if len(strs) > 1:
        ack = bool(strs[1])
    if ack == False:
        print(f"CASP: WriteF({udo_idx}) Failed: {strs[0]}")
    return ack