casp_gpio.py

"""! This module defines functions to communicate with target hardware (i.e micro-controller board, SBC etc.) that is programmed with CASP GPIO protocol. Both serial and ethernet communication interfaces are supported. All functions in this module uses global object \ref _casp_process.casp_gpio_proc from \ref _casp_process.py module.
"""

import importlib
from _casp_process import casp_gpio_proc
import casp_utils as utils

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

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

def ConnectSerial(serial_port: str="COM3", enable_dtr: bool=True, send_recv_delay: int=1, baud: int=115200) -> bool:
    """! Initializes CASP GPIO 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.
 
        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), "0", "0"])
    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, tcp: bool=False, send_recv_delay: int=1) -> bool:
    """! Initializes CASP GPIO 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.
 
        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), "0", "0"])
    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 FolderUserData():
    """! Opens 'CASP User Data' directory from user's Documents folder.
    """
    response = casp_gpio_proc.write("casp.dir.user_data")
    print(f"CASP: {response.strip()}")

def FolderTutorials():
    """! Opens CASP tutorials directory.
    """
    response = casp_gpio_proc.write("casp.dir.tutorials")
    print(f"CASP: {response.strip()}")

def FolderExamples():
    """! Opens CASP examples directory.
    """
    response = casp_gpio_proc.write("casp.dir.examples")
    print(f"CASP: {response.strip()}")

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

def Read(pin_name: str) -> int:
    """! Reads target GPIO raw pin value and returns the value as an integer.
 
    Arguments:
 
        pin_name: Pin number/name from the selected module in 'casp_gpio_pins' folder from which the value is to be read.
 
    Return Value:
 
        Returns the pin value received from the target as an integer.
    """
    response = casp_gpio_proc.write("casp.read", [pin_name])
    if len(response) == 0:
        response = "Empty response."
    strs = utils.SplitString(response.strip())
    #print(f"CASP: {strs[0]}")
    val:int = 0
    if len(strs) > 1:
        val = int(strs[1])
    return val

def Write(pin_name: str, value: int) -> bool:
    """! Writes value to the target's GPIO pin and returns whether the write operation is successful or not.
 
    Arguments:
 
        pin_name: Pin number/name from the selected module in 'casp_gpio_pins' folder to which the value is written.
 
        value: Value to write.
 
    Return Value:
 
        Returns whether the write operation is successful or not.
    """
    response = casp_gpio_proc.write("casp.write", [pin_name, str(value)])
    if len(response) == 0:
        response = "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