casp.py

"""! This module defines all necessary functions to
 
 - start CASP process
 - create a new project or open an existing project
 - set target on which the created model is executed
 - create a model with blocks as per desired logic
   - add blocks to the model
   - adjust each block parameters as required
   - connect the blocks
 - build and compile the model
 - run the model on the target hardware
 - and finally when every thing is done, close the CASP process
 
 All functions in this module uses global object \ref _casp_process.casp_proc from \ref _casp_process.py module.
"""

import importlib
 
import sys
if sys.version_info[:3] < (3,9):
    from typing import List as list
 
from _casp_process import casp_proc, casp_bv_proc
import casp_utils as utils
import casp_defs as defs
import casp_targets as targets
import casp_wtypes as wtypes
import casp_pins as pins
 

def Init(make_visible: bool=False, casp_file: str="CASP-Eval"):
    """! Initializes CASP subprocess. This is the first function to be called before using any other functions in this module.
 
    Arguments:
 
        visible: Set True to make CASP window visible.
 
        casp_file: Set CASP executable file to be invoked. Set this argument only if the executable file version is different from 'CASP-Eval'.
    """
    casp_proc.init(make_visible, casp_file)

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

def BlockViewer():
    """! Invokes BlockViewer process for user to browse CASP blocks, view block parameters, block documentation etc.
    """
    casp_bv_proc.init()
    #response = casp_proc.write("casp.sys.blk.viewer")
    #print(f"CASP: {response.strip()}")

def SerialPorts():
    """! Displays available serial ports on the host. User can use this function before using the \ref ProgrammerPortSet() function.
    """
    response = casp_proc.write("casp.sys.serial.ports")
    print(f"CASP: {response.strip()}")

def Refresh():
    """! Refreshes CASP project. For further details about refreshing CASP project, please refer CASP main documentation \ref Help().
    """
    response = casp_proc.write("casp.sys.refresh")

def SerialTerminal():
    """! Invokes CASP Serial Terminal window.
    """
    response = casp_proc.write("casp.sys.terminal")

def Rtv():
    """! Opens CASP Remote Terminal Viewer (RTV) process. For further details please refer to CASP main documentation \ref Help().
    """
    response = casp_proc.write("casp.sys.rtv")

def BleClient():
    """! Opens CASP Bluetooth Low Energy (BLE) process. For further details please refer to CASP main documentation \ref Help().
    """
    response = casp_proc.write("casp.sys.ble.client")

def Help():
    """! Opens CASP main documentation.
    """
    response = casp_proc.write("casp.sys.help")

def HelpBsp():
    """! Opens CASP board support package (BSP) documentation.
    """
    response = casp_proc.write("casp.sys.help.bsp")

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

def FolderUserData():
    """! Opens 'CASP User Data' directory from user's Documents folder.
    """
    response = casp_proc.write("casp.sys.dir.user_data")
    print(f"CASP: {response.strip()}")

def FolderTargetSupport():
    """! Opens current CASP target support folder.
    """
    response = casp_proc.write("casp.sys.dir.target_support")
    print(f"CASP: {response.strip()}")

def FolderProject():
    """! Opens current CASP project directory.
    """
    response = casp_proc.write("casp.sys.dir.project")
    print(f"CASP: {response.strip()}")

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

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

def ProjectCreate(proj_name: str=None) -> str:
    """! Creates new CASP project and returns the project path.
 
    Arguments:
 
        proj_name: Project name to be created.
 
    Return Value:
 
        Returns project path where the project is created.
    """
    if proj_name:
        response = casp_proc.write("casp.proj.create", [proj_name])
    else:
        response = casp_proc.write("casp.proj.create")
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    pro_path: str = ""
    if len(strs) > 1:
        pro_path = str(strs[1])
    return pro_path

def ProjectOpen(proj_full_path: str=None) -> str:
    """! Opens existing CASP project.
 
    Arguments:
 
        proj_full_path: Project full path (along with project file extension .prj) should be provided as argument. If no argument is provided, CASP opens most recent project created or closed.
 
    Return Value:
 
        Returns project path that was opened.
    """
    if proj_full_path:
        response = casp_proc.write("casp.proj.open", [proj_full_path])
    else:
        response = casp_proc.write("casp.proj.open")
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    pro_path: str = ""
    if len(strs) > 1:
        pro_path = str(strs[1])
    return pro_path

def ProjectOpenDefault() -> str:
    """! This function does a couple of things.
 
    - It creates a temporary project along with a default workspace (.wsp) file.
    - Loads/open the temporary project.
    - Creates two simulation panel windows of type '2D Plotter' and 'Controls/Meters'
 
    Please note that the temporary project files created using this function and further modified using other functions will be available till next CASP process start. Once CASP restarts these files will be deleted.
 
    User is recommended to use this function (in place of above two functions) to quickly create a project and start working on it.
 
    Return Value:
 
        Returns project path that was opened.
    """
    response = casp_proc.write("casp.proj.create")
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    response = casp_proc.write("casp.proj.open")
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    pro_path: str = ""
    if len(strs) > 1:
        pro_path = str(strs[1])
    return pro_path

def WspClear():
    """! Clears default project workspace i.e. deletes all blocks that were created in the workspace. This function is rarely required to be used by the user.
    """
    response = casp_proc.write("casp.proj.wsp.clear")
    print(f"CASP: {response.strip()}")

def ProjectHelp():
    """! Opens project's documentation.
    """
    response = casp_proc.write("casp.sys.help.proj")

def ProjectSave():
    """! Saves current project.
    """
    response = casp_proc.write("casp.proj.save")
    print(f"CASP: {response.strip()}")

def ProjectClose():
    """! Closes current project.
    """
    response = casp_proc.write("casp.proj.close")
    print(f"CASP: {response.strip()}")

def TargetSet(target_name: str):
    """! Set target hardware on which the current model has to execute. It also updates \ref casp_pins.py with the selected target pin variables for later use, and reloads it.
 
    Arguments:
 
        target_name: Target name string from \ref casp_targets.py file.
    """
    response = casp_proc.write("casp.proj.set.target", [target_name])
    importlib.reload(pins) #reload pins module
    print(f"CASP: {response.strip()}")

def TargetIdSet(target_id: str):
    """! Set target ID.
 
    Arguments:
 
        target_id: Target ID string to be set.
    """
    response = casp_proc.write("casp.proj.set.target_id", [target_id])
    print(f"CASP: {response.strip()}")

def ProgrammerSet(programmer: int = defs.PROGRAMMER0):
    """! Set programmer port. In most cases leave it to default.
 
    Arguments:
 
        programmer: Use either \ref casp_defs.PROGRAMMER0 or \ref casp_defs.PROGRAMMER1.
    """
    response = casp_proc.write("casp.proj.set.programmer", [str(programmer)])
    print(f"CASP: {response.strip()}")

def ProgrammerPortSet(serial_port: str):
    """! Set serial port to which the device or development board to be programmed is connected. Use function \ref SerialPorts() to display available serial ports on the host.
 
    Arguments:
 
        serial_port: Set serial port to which the device to be programmed is connected.
    """
    response = casp_proc.write("casp.proj.set.programmer.port", [serial_port])
    print(f"CASP: {response.strip()}")

def RemoteBuildIPSet(ip: str):
    """! Set IP address of remote device supporting CASP Remote Build protocol. Please refer CASP main documentation for details on CASP Remote Build feature.
 
    Arguments:
 
        ip: Set remote device IP.
    """
    response = casp_proc.write("casp.proj.set.rbuild.ip", [ip])
    print(f"CASP: {response.strip()}")

def RemoteBuildRtvEnable(enable: bool = True):
    """! Set enable or disable Remote Terminal Viewer feature on remote build device. Please refer CASP main documentation for details on Remote Terminal Viewer.
 
    Arguments:
 
        enable: Set True to enable and False to disable.
    """
    response = casp_proc.write("casp.proj.set.rbuild.rtv", [str(int(enable))])
    print(f"CASP: {response.strip()}")

def GenPyCode(skip_disabled_blocks: bool = True):
    """! Generates Python code for the current project model. The generated file (.py) will be located in projects directory.
 
    Arguments:
 
        skip_disabled_blocks: Skips disabled blocks in the generated code.
    """
    response = casp_proc.write("casp.proj.gen.py_code", [str(int(skip_disabled_blocks))])
    print(f"CASP: {response.strip()}")

def SimPanelWindowAdd(grp_name: str, wnd_name: str, wnd_type: int):
    """! Adds new sub-window to an existing group. Creates new group if group name is not found.
 
    Arguments:
 
        grp_name: Existing group name to which new sub-window is added.
 
        wnd_name: New sub-window name to be added. It should be unique to existing sub-window names in the group.
 
        wnd_type: Sub-window type. It shall be one of the constants defined in \ref casp_wtypes.py module.
    """
    response = casp_proc.write("casp.sim_panel.subwnd.add", [grp_name, wnd_name, str(wnd_type)])
    print(f"CASP: {response.strip()}")

def SimSetupFiniteTime(set: bool = True):
    """! Sets simulation execution to finite time.
 
    Arguments:
 
        set: Set True to set simulation execution to finite time or False to set simulation execution time to infinite.
    """
    response = casp_proc.write("casp.sim_setup.finite_time", [str(int(set))])
    print(f"CASP: {response.strip()}")

def SimSetupEndTime(time_msec: int = 1000):
    """! Sets simulation end time in milli seconds.
 
    Arguments:
 
        time_msec: Set end time in milli seconds.
    """
    response = casp_proc.write("casp.sim_setup.end_time", [str(time_msec)])
    print(f"CASP: {response.strip()}")

def SimSetupTimeStep(time_usec: int = 1000):
    """! Sets simulation time step in micro seconds.
 
    Arguments:
 
        time_usec: Set time step in micro seconds.
    """
    response = casp_proc.write("casp.sim_setup.time_step", [str(time_usec)])
    print(f"CASP: {response.strip()}")

def SimSetupPlotStep(plot_step: int = 1):
    """! Sets simulation plot step.
 
    Arguments:
 
        plot_step: Set plot step in multiples of simulation time step.
    """
    response = casp_proc.write("casp.sim_setup.plot_step", [str(plot_step)])
    print(f"CASP: {response.strip()}")

def SimSetupPlotSamples(plot_samples: int = 10000):
    """! Sets simulation plot samples. It sets specified fixed plot samples buffer (FIFO buffer) during simulation. Plot samples are pushed into the buffer at each simulation plot step. If the buffer is full the first in sample will be discarded. Higher buffer values demand more memory and CPU resources.
 
    Arguments:
 
        plot_samples: Set number of plot samples.
 
    Example:
 
        For a simulation time step=1msec with plot step=1 and plot samples set to 10000, the FIFO buffer size can hold samples for 10 secs (0.001*1*10000).
    """
    response = casp_proc.write("casp.sim_setup.plot_samples", [str(plot_samples)])
    print(f"CASP: {response.strip()}")

def SimSetupSpeedFactor(sf: float = 1):
    """! Sets simulation speed factor. This value should be non negative.
 
    - Speed factor 0 will run the simulation at full speed.
    - Speed factor 1 will run the simulation in real time.
    - Speed factor between 0 and 1 will run the simulation slower than real time.
    - Speed factor >1 will run the simulation faster than real time.
 
    In case 3 and 4 above the simulation speed is with respective to real time.
 
    Arguments:
 
        sf: Set simulation speed factor.
    """
    response = casp_proc.write("casp.sim_setup.speed_factor", [str(sf)])
    print(f"CASP: {response.strip()}")

def SimSetupPrecision(precision: int = defs.PRECISION_32):
    """! Sets simulation integer and floating point precision to 32-bit, 48-bit (applicable to FPGA) and 64-bit.
 
    Arguments:
 
        precision: Set simulation precision constants as define in module \ref casp_defs.py. Typical values are \ref casp_defs.PRECISION_32, \ref casp_defs.PRECISION_48, \ref casp_defs.PRECISION_64.
    """
    response = casp_proc.write("casp.sim_setup.precision", [str(precision)])
    print(f"CASP: {response.strip()}")

def SimSetupOptLevel(opt_level: int = 1):
    """! Sets compiler optimization level. Typical values are from 0 to 5. Default value is 1.
 
    - 0: No optimization
    - 1 to 3: Increasing optimization level from 1 to 3
    - 4: Optimize for size
    - 5: Optimize for speed
 
    Arguments:
 
        opt_level: Set compiler optimization level from above values.
    """
    response = casp_proc.write("casp.sim_setup.cmp_opt_level", [str(opt_level)])
    print(f"CASP: {response.strip()}")

def SimSetupMaximumModelThreads(max_threads: int = 1):
    """! Sets maximum threads limit that can run in parallel during execution.
 
    Arguments:
 
        max_threads: Set maximum threads limit value. 0 value indicate that the maximum threads are set based on the available CPU cores on the target. The set value will be limited to available CPU cores on the target.
    """
    response = casp_proc.write("casp.sim_setup.limit_model_threads", [str(max_threads)])
    print(f"CASP: {response.strip()}")

def SimSetupMaximumBlockThreads(max_threads: int = 1):
    """! Sets maximum block threads limit that can run in parallel within a block during execution.
 
    Arguments:
 
        max_threads: Set maximum block threads limit value. 0 value indicate that the maximum threads are set based on the available CPU cores on the target. The set value will be limited to available CPU cores on the target.
    """
    response = casp_proc.write("casp.sim_setup.limit_block_threads", [str(max_threads)])
    print(f"CASP: {response.strip()}")

def SimSetupTargetPythonSupport(enable_disable: bool = True):
    """! Enables or disables python support for the current target. Here, python supprt means blocks having embedded python code will be executed during simulation if this feature is enabled otherwise compilation will generate and error. User can enable it only if the target supports embedded python.
 
    Arguments:
 
        enable_disable: Set True to enable or False to disable this feature.
    """
    response = casp_proc.write("casp.sim_setup.enable_target_python", [str(int(enable_disable))])
    print(f"CASP: {response.strip()}")

def SimSetupOpenMpThreads(max_threads: int = 1):
    """! Sets maximum OpenMP threads that can be created for the current target (if this feature is supported by the target).
 
    Arguments:
 
        max_threads: Set maximum threads (1,2,3...). Value 1 means this feature is disabled. 0 means the maximum value is decided based on number of CPU cores available on the target.
    """
    response = casp_proc.write("casp.sim_setup.openmp_threads", [str(max_threads)])
    print(f"CASP: {response.strip()}")

def SimSetupOpenClSupport(platform_index: int = -1, device_index: int = -1):
    """! Configures OpenCL support for current target.
 
    Arguments:
 
        platform_index: Set OpenCL platform index (-1,0,1,2...)
 
        device_index: Set OpenCL device index (-1,0,1,2...)
 
    If both 'platform_index' and 'device_index' arguments are -1 then this feature is disabled.
    """
    text = str(platform_index)+","+str(device_index)
    response = casp_proc.write("casp.sim_setup.opencl", [text])
    print(f"CASP: {response.strip()}")

def SimSetupCudaSupport(device_index: int = -1):
    """! Configures CUDA support for current target.
 
    Arguments:
 
        device_index: Set CUDA device index (-1,0,1,2...). -1 disables CUDA support.
    """
    response = casp_proc.write("casp.sim_setup.cuda", [str(device_index)])
    print(f"CASP: {response.strip()}")

def ModelValidate():
    """! Quickly validates current model for any errors and displays the result of validation in brief. If the validation fails, user can check the log files in project directory for details.
    """
    print("CASP: Validating model...")
    response = casp_proc.write("casp.sim.validate")
    print(f"CASP: {response.strip()}")

def Build():
    """! Builds current model and displays the result of the build process. User should check the log files in the project directory for details if the build fails.
    """
    print("CASP: Build started...")
    response = casp_proc.write("casp.sim.build")
    print(f"CASP: {response.strip()}")

def BuildFresh():
    """! Generally, \ref casp.Build() function skips un-modified code files during build to speed up the build process. However, the BuildFresh() function deletes all the intermediate build files from previous build and freshly rebuilds the model. After the build process is completed, it displays the result of the build process in brief. User should check the log files in the project directory for details if the build process fails.
    """
    print("CASP: Re-Build started...")
    response = casp_proc.write("casp.sim.rebuild")
    print(f"CASP: {response.strip()}")

def BuildCancel():
    """! Cancels current build process.
    """
    print("CASP: Build cancel started...")
    response = casp_proc.write("casp.sim.cancel_build")
    print(f"CASP: {response.strip()}")

def BuildClear():
    """! Clears previous build data including all the intermediate build files.
    """
    print("CASP: Build clear started...")
    response = casp_proc.write("casp.sim.build.clear")
    print(f"CASP: {response.strip()}")

def SimStart():
    """! Starts simulation if the target supports simulation panel. Else it starts to program the target board with generated binary and resets the target board so that the uploaded binary will get executed. This function also builds the model if needed.
    """
    print("CASP: Starting simulation (or target programming)...")
    response = casp_proc.write("casp.sim.start")
    print(f"CASP: {response.strip()}")

def SimStartPrev():
    """! Starts simulation (or target programming) with previous build data. This function does not re-build the model.
    """
    print("CASP: Starting simulation (or target programming)...")
    response = casp_proc.write("casp.sim.start_prev")
    print(f"CASP: {response.strip()}")

def SimStop():
    """! Stops current simulation (or target programming) process.
    """
    print("CASP: Stopping simulation (or target programming)...")
    response = casp_proc.write("casp.sim.stop")
    print(f"CASP: {response.strip()}")

def BlockAdd(blk_path: str, blk_name: str=" ") -> int:
    """! Adds new block to the current model. The module corresponding to the block to be added shall be first imported. These block modules are available in pycasp/blks directory.
 
    Arguments:
 
        blk_path: block path constant from the corresponding block module. Generally, it is in the form of <block module>.path.
 
        blk_name: any meaning full string.
 
    Return Value:
 
        Block Id (of type integer) if the block instance is created and added to the model or else 0. It is better to store the return value as it will be referred in functions related to the block.
    """
    response = casp_proc.write("casp.blk.add", [blk_path, blk_name])
    strs = utils.SplitString(response.strip())
    print(f"CASP: {strs[0]}")
    blk_id:int = 0
    if len(strs) > 1:
        blk_id = int(strs[1])
    return blk_id

def BlockHelp(blk_id: int):
    """! Displays block documentation of specified block Id. The module corresponding to the block Id shall be first imported from pycasp/blks directory.
 
    Argument:
 
        blk_id: It should be the reference block Id (and not the block Id of the created block instance). Generally, it is in the form of <block module>.id.
    """
    response = casp_proc.write("casp.blk.help", [str(blk_id)])
    print(f"CASP: {response.strip()}")

def BlockNameSet(blk_id: int, blk_name: str):
    """! Sets block name of the specified block instance Id.
 
    Argument:
 
        blk_id: block instance Id for which the block name shall be set.
 
        blk_name: a user friendly name to be set.
    """
    response = casp_proc.write("casp.blk.set_name", [str(blk_id), blk_name])
    print(f"CASP: {response.strip()}")

def BlockEnable(blk_id: int, enable: bool=True):
    """! Enable or disable a block in the current model.
 
    Argument:
 
        blk_id: block instance Id
 
        enable: True to enable the block or False to disable it
    """
    response = casp_proc.write("casp.blk.enable", [str(blk_id), str(int(enable))])
    print(f"CASP: {response.strip()}")

def BlockRelocate(blk_id: int):
    """! Auto relocates the block instance in the workspace. This function is useful only when CASP window is visible and user wants to re-locate the block in the workspace.
 
    Argument:
 
        blk_id: block instance Id to re-locate
    """
    response = casp_proc.write("casp.blk.re_locate", [str(blk_id)])
    print(f"CASP: {response.strip()}")

def BlockParaSet(blk_id: int, grp_para_name: str, para_val: str):
    """! Sets block parameter value of the specified block instance Id.
 
    Arguments:
 
        blk_id: block instance Id
 
        grp_para_name: parameter name string of the block parameter. Generally, it is in the form of <block_module_name>.Para.<block_group_constant>.<block_parameter_constant>.name.
 
        para_val: new value of the block parameter. Parameter value can be of absolute value or one of the value from the parameter list. Refer block module help for parameter value list.
    """
    response = casp_proc.write("casp.blk.set_para", [str(blk_id), grp_para_name, para_val])
    print(f"CASP: {response.strip()}")

def BlockInitConditionSet(blk_id: int, grp_para_name: str, para_val: str):
    """! Sets block initial condition value of the specified block instance Id. The function is similar to \ref casp.BlockParaSet() except it sets block initial condition values instead block parameter values. Refer \ref casp.BlockParaSet() for details.
    """
    response = casp_proc.write("casp.blk.set_init", [str(blk_id), grp_para_name, para_val])
    print(f"CASP: {response.strip()}")

def BlockPortsConnect(blk_id1: int, port_name1: str, blk_id2: int, port_name2: str, auto_update_input_port_para: bool=True):
    """! Connects two block ports.
 
    Arguments:
 
        blk_id1: block1 Id
 
        port_name1: port name of block1
 
        blk_id2: block1 Id
 
        port_name2: port name of block2
 
        auto_update_input_port_para: auto updates input port data type and size based on connected output port parameters.
    """
    response = casp_proc.write("casp.blk.connect_ports", [str(blk_id1), port_name1, str(blk_id2), port_name2, str(int(auto_update_input_port_para))])
    print(f"CASP: {response.strip()}")

def BlockDelete(blk_id: int) -> bool:
    """! Deletes specified block Id instance from the model.
 
    Argument:
 
        blk_id: block Id to delete
 
    Returns:
 
        True if successful else False
    """
    response = casp_proc.write("casp.blk.del", [str(blk_id)])
    print(f"CASP: {response.strip()}")
    if "Error" in response.strip():
        return False
    return True