Engee documentation

Custom Engee support packages.Integrations

Subsystem Engee.Integrations provides interaction between Engee and external equipment through the client program and support packages.

You can extend the functionality of the Engee subsystem.Integration by developing our own custom support packages. The support package is a Python module that runs in a client program and returns the result in Engee.

So that the Engee subsystem.Integration could use custom packages, Engee automatically generates code for them in the Julia language. This allows you to call your functions directly from command line Engee img 41 1 2 or from blocks.

Technology is at the heart of this mechanism. RPC (Remote Procedure Call). You are calling a function in Julia that passes arguments over the network to the client computer. There, your support package executes the corresponding Python function with these parameters and returns the result back to Engee.

Execution Architecture

It is important to understand how code execution is distributed:

  • Python code is executed directly on the user’s computer during the client program process;

  • Julia code is executed in the subsystem Engee and coordinates the interaction.

For example, when calling:

using Main.EngeeDeviceManager.Devices.EXTDEVICE
device = EXTDEVICE.Extdevice()
device.function()

Julia-the code is executed in Engee, and Python is a function function() — on the client computer, and its result is returned to Engee.

Development of a custom support package

A custom support package can be implemented as:

  • The device (Device) is an arbitrary user—defined class that is not designed to directly perform model simulation Engee and it does not use its internal data for calculations at runtime. It provides custom methods for blocks and scripts. For more information about developing a custom device support package, see Development of a custom device support package.

  • Target (Target) is a custom class that interacts with the model Engee, receives data from it for processing and executes on another platform (a microcontroller, a separate computer, etc.). For more information about the development of targets, see Development of a custom embedded system support package.

Available Python Packages

When developing custom support packages, all standard Python packages are available to you, as well as the following third-party packages:

list of available Python packages
Package Description

aiohttp

Asynchronous HTTP client/server framework (asyncio)

autoflake

Deletes unused imports and variables

bandit

Static Python Code Security Analyzer

beartype

Fast hybrid type checking at runtime

black

An uncompromising code formatter

certifi

Mozilla’s CA Bundle Package

cffi

Interface of external functions for invoking C code from Python

docformatter

Formats documentation strings in accordance with PEP 257

flake8

Modular source Code Checker: pep8, pyflakes and others

gpib-ctypes

GPIB interface for Python, implemented using ctypes

hid

Ctypes bindings for hidapi

httpx

Next-generation HTTP client

intelhex

Python library for manipulating Intel HEX files

isort

Utility/library for sorting Python imports

jinja2

A very fast and expressive template engine

jupyter-client

Jupyter protocol implementation and client libraries

jupyter-core

Jupyter Basic Package

jwcrypto

Implementation of JOSE Web standards

mdurl

Markdown URL Utilities

msgpack

The MessagePack Serializer

multidict

Implementation of multidict

numpy

A fundamental package for computing arrays in Python

ordered-set

An OrderedSet that remembers its order

patchelf

A utility for changing dynamic linker and RPATH ELF executable files

pathspec

A utility for matching file paths in the gitignore style

platformdirs

Identifying suitable platform-specific directories

pydantic

Data validation using Python type hints

pydantic-core

The main functionality for Pydantic validation and serialization

pydantic-settings

Managing settings using Pydantic

pyduinocli

The wrapper around the arduino-cli

pyflakes

Passive Python Program Checker

pymodbus

Full-featured Modbus protocol stack in Python

pyserial

Python Serial Port Extension

pyusb

The USB access module from Python

pyvisa

Python VISA bindings for GPIB, RS232, TCPIP and USB tools

pyvisa-py

Pure Python implementation of the VISA library

pyyaml

YAML Parser and Emitter for Python

pyzmq

Python bindings for 0MQ

redis

Python client for the Redis database and key-value storage

requests

HTTP for people in Python

setuptools

Easily download, build, install, update, and remove Python packages.

toml

Python Library for Tom’s Obvious, Minimal Language

untokenize

Converts tokens to source code (while preserving spaces)

urllib3

HTTP library with thread-safe connection pool, file sending, and other features

For custom RPC classes, it is mandatory to inherit from BaseDevice (if it is a device) or from BaseTarget (if it’s a target).

Data structures must be inherited from BaseModel!

All methods must contain complete type annotations for the parameters and the return value. For example:

# НЕПРАВИЛЬНО - без аннотаций
def __init__(self, param1, param2):
    pass

# ПРАВИЛЬНО - с полными аннотациями
def __init__(self, param1: int, param2: float) -> None:
    pass

def calculate(self, x: float, y: int) -> str:
    return "result"

Without annotations, the system will not be able to correctly generate Julia code and convert data types between Python and Julia.

Methods intended to be called from a block should not start with and _ — such methods will not be available from scripts and blocks.

The embedded system support package (target) should be located in targets/<target_folder>/.

The device support package must be located in devices/<device folder>/.

You can use the built-in logging system to debug the support package. For more information, see Debugging support packages. To add information about the support package to the window «Equipment» implement a static method in the device class. __get_opportunity_list; for more information, see Displaying the support package status in the client program interface.

Uploading a custom package to Engee.Integrations

In the client program Engee.Integrations Follow these steps:

  1. Open the Hardware status window.

  2. Select the tab «Extensions».

    engee integrations custom packages 1 en

  3. Click «Add an extension».

  4. Select the folder with the custom support package that you want to add to the client program.

    engee integrations custom packages 2 en

If the download is successful, a message will appear in the diagnostic window of the client program.:

INFO: Расширение с именем extension было успешно загружено!

To get extended information about the found classes of the support package and its methods in the diagnostic window, run the client program in developer mode.:

engee-device-manager.exe -d

After the support package has been successfully downloaded, additional information will be displayed in the diagnostic window.:

engee integrations custom packages 4 en

Debugging support packages

To debug the support package, use MainLogger — built-in Engee logging system.Integrations:

  1. Launch Engee.Integration in developer mode (engee-device-manager.exe -d) and view the logs in the diagnostic window of the client program.

  2. Send messages via MainLogger from the code of your support package.

    Example:

    logger.info("Connect {}:{}", host, port)
logger.error("Read failed: {}", err)

Available methods of the integrated logging system:

  • logger.debug("message") — debugging information;

  • logger.info ("message") — information messages;

  • logger.warning("message") — Warnings;

  • logger.error("message") — mistakes.

The messages will be displayed in the diagnostic window of the client program. For an example of using the built-in logging system, see the article Development of a custom device support package.

Displaying the support package status in the client program interface

The client program displays installed hardware status: Whether the driver is loaded, whether the device is connected. To add information about the support package to the hardware status window, implement a static method in the device class. __get_opportunity_list.

The principle of operation:

  1. At startup, the client program imports all modules from packages. devices and targets.

  2. A private method is checked for each registered class. __get_opportunity_list.

  3. If the method is found, it is called and returns a list. OpportunityStatus.

  4. The client program polls this list every 3 seconds and displays the information in the hardware status window.

Fields OpportunityStatus:

  • key — the unique identifier of the row. Example: "my_driver"

  • title_key — the title in the interface. Example: "MyDevice driver:"

  • value_key — the status text. Example: "Loaded" / "Not loaded"

  • value_args — arguments for formatting the value. Example: ()

  • color — indicator color: "green", "orange", "red". Example: "green"

  • category — a tab in the hardware status window:

    • "hardware" — «Equipment»

    • "protocols" — «Protocols»

    • "software" — «Software integration» (by default)

    • "embedded" — «Embedded systems»

If no field is specified, the category is determined automatically by the name of the device package.

An example for a custom device support package:

from devices.base_device import BaseDevice

class MyDevice(BaseDevice):

    @staticmethod
    def __get_opportunity_list() -> list[BaseDevice.OpportunityStatus]:
        status = BaseDevice.opportunity_status

        driver_loaded = False
        try:
            import some_library  # замените на вашу зависимость
            driver_loaded = True
        except ImportError:
            pass

        results = []

        if driver_loaded:
            results.append(status(
                key="my_driver",
                title_key="MyDevice driver:",
                value_key="Loaded",
                color="green",
                category="hardware",
            ))
        else:
            results.append(status(
                key="my_driver",
                title_key="MyDevice driver:",
                value_key="Not loaded",
                color="orange",
                category="hardware",
            ))

        results.append(status(
            key="my_device",
            title_key="MyDevice status:",
            value_key="Available",
            color="green",
            category="hardware",
        ))

        return results

After adding this method, the support package will appear on the tab «Equipment» in the Engee client program.Integration.

Synchronization and use of the support package in Engee

For a custom support package to appear in EngeeDeviceManager.Devices. or EngeeDeviceManager.Targets., run on the command line Engee:

using Main.EngeeDeviceManager
using Main.EngeeDeviceManager.UTILS_API

utils = UTILS_API.Utils()
UTILS_API.syncExtensions()

If changes have been made to the method signatures or new methods have been added, call syncExtensions() again. After synchronization, the support package modules become available for use in Engee.

Your support package will be automatically downloaded every time you run the client program. If it is no longer needed, then you can delete it from the startup in the client program.:

engee integrations custom packages 3 en