Пользовательские пакеты поддержки Engee.Интеграции

Подсистема Engee.Интеграции обеспечивает взаимодействие между Engee и внешним оборудованием через клиентскую программу и пакеты поддержки.

Вы можете расширять функциональность подсистемы Engee.Интеграции, разрабатывая собственные пользовательские пакеты поддержки. Пакет поддержки представляет собой модуль на языке Python, который выполняется в клиентской программе и возвращает результат в Engee.

Чтобы подсистема Engee.Интеграции могла использовать пользовательские пакеты, Engee автоматически генерирует для них код на языке Julia. Это позволяет вызывать ваши функции прямо из командной строки Engee img 41 1 2 или из блоков.

В основе этого механизма лежит технология RPC (Remote Procedure Call — удаленный вызов процедур). Вы вызываете функцию в Julia, которая передает аргументы по сети на клиентский компьютер. Там ваш пакет поддержки выполняет соответствующую Python-функцию с этими параметрами и возвращает результат обратно в Engee.

Архитектура выполнения

Важно понимать, как распределяется выполнение кода:

Код на Python выполняется непосредственно на компьютере пользователя в процессе клиентской программы;
Код на Julia выполняется в подсистеме Engee и координирует взаимодействие.

Например, при вызове:

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

Julia-код выполняется в Engee, а Python-функция function() — на клиентском компьютере, и ее результат возвращается в Engee.

Разработка пользовательского пакета поддержки

Пользовательский пакет поддержки может быть реализован как:

Устройство (Device) — это произвольный пользовательский класс, который не предназначен для непосредственного выполнения симуляции модели Engee и не использует ее внутренние данные для расчетов во время выполнения. Он предоставляет пользовательские методы для блоков и скриптов. Подробнее о разработке пользовательского пакета поддержки устройства см. в разделе Разработка пользовательского пакета поддержки устройства.

Таргет (Target) — это пользовательский класс, который взаимодействует с моделью Engee, получает из нее данные для обработки и исполняется на другой платформе (микроконтроллере, отдельном компьютере и т.д.). Подробнее о разработке таргетов см. в разделе Разработка пользовательского пакета поддержки встраиваемой системы.

Доступные пакеты Python

При разработке пользовательских пакетов поддержки вам доступны все стандартные пакеты Python, а также следующие сторонние пакеты:

Список доступных пакетов Python

Пакет	Описание
aiohttp	Асинхронный HTTP клиент/сервер фреймворк (asyncio)
autoflake	Удаляет неиспользуемые импорты и переменные
bandit	Статический анализатор безопасности кода на Python
beartype	Быстрая гибридная проверка типов во время выполнения
black	Бескомпромиссный форматировщик кода
certifi	Пакет для предоставления Mozilla’s CA Bundle
cffi	Интерфейс внешних функций для вызова Си-кода из Python
docformatter	Форматирует строки документации в соответствии с PEP 257
flake8	Модульный проверщик исходного кода: pep8, pyflakes и другие
gpib-ctypes	Интерфейс GPIB для Python, реализованный с использованием ctypes
hid	Привязки ctypes для hidapi
httpx	HTTP-клиент следующего поколения
intelhex	Библиотека Python для манипуляций с файлами Intel HEX
isort	Утилита/библиотека для сортировки импортов Python
jinja2	Очень быстрый и выразительный шаблонизатор
jupyter-client	Реализация протокола Jupyter и клиентские библиотеки
jupyter-core	Основной пакет Jupyter
jwcrypto	Реализация стандартов JOSE Web
mdurl	Утилиты для URL Markdown
msgpack	Сериализатор MessagePack
multidict	Реализация multidict
numpy	Фундаментальный пакет для вычислений с массивами в Python
ordered-set	OrderedSet, который запоминает свой порядок
patchelf	Утилита для изменения динамического linker и RPATH ELF исполняемых файлов
pathspec	Утилита для сопоставления путей файлов в стиле gitignore
platformdirs	Определение подходящих директорий, специфичных для платформы
pydantic	Валидация данных с использованием подсказок типов Python
pydantic-core	Основная функциональность для валидации и сериализации Pydantic
pydantic-settings	Управление настройками с использованием Pydantic
pyduinocli	Обертка вокруг arduino-cli
pyflakes	Пассивный проверщик Python-программ
pymodbus	Полнофункциональный стек протокола Modbus на Python
pyserial	Расширение для последовательного порта Python
pyusb	Модуль доступа к USB из Python
pyvisa	Привязки Python VISA для инструментов GPIB, RS232, TCPIP и USB
pyvisa-py	Чистая Python-реализация библиотеки VISA
pyyaml	Парсер и эмиттер YAML для Python
pyzmq	Привязки Python для 0MQ
redis	Python-клиент для базы данных Redis и хранилища key-value
requests	HTTP для людей на Python
setuptools	Легко загружайте, собирайте, устанавливайте, обновляйте и удаляйте пакеты Python
toml	Библиотека Python для Tom’s Obvious, Minimal Language
untokenize	Преобразует токены в исходный код (с сохранением пробелов)
urllib3	HTTP-библиотека с потокобезопасным пулом соединений, отправкой файлов и прочими возможностями

Пакет

Описание

aiohttp

Асинхронный HTTP клиент/сервер фреймворк (asyncio)

autoflake

Удаляет неиспользуемые импорты и переменные

bandit

Статический анализатор безопасности кода на Python

beartype

Быстрая гибридная проверка типов во время выполнения

black

Бескомпромиссный форматировщик кода

certifi

Пакет для предоставления Mozilla’s CA Bundle

cffi

Интерфейс внешних функций для вызова Си-кода из Python

docformatter

Форматирует строки документации в соответствии с PEP 257

flake8

Модульный проверщик исходного кода: pep8, pyflakes и другие

gpib-ctypes

Интерфейс GPIB для Python, реализованный с использованием ctypes

hid

Привязки ctypes для hidapi

httpx

HTTP-клиент следующего поколения

intelhex

Библиотека Python для манипуляций с файлами Intel HEX

isort

Утилита/библиотека для сортировки импортов Python

jinja2

Очень быстрый и выразительный шаблонизатор

jupyter-client

Реализация протокола Jupyter и клиентские библиотеки

jupyter-core

Основной пакет Jupyter

jwcrypto

Реализация стандартов JOSE Web

mdurl

Утилиты для URL Markdown

msgpack

Сериализатор MessagePack

multidict

Реализация multidict

numpy

Фундаментальный пакет для вычислений с массивами в Python

ordered-set

OrderedSet, который запоминает свой порядок

patchelf

Утилита для изменения динамического linker и RPATH ELF исполняемых файлов

pathspec

Утилита для сопоставления путей файлов в стиле gitignore

platformdirs

Определение подходящих директорий, специфичных для платформы

pydantic

Валидация данных с использованием подсказок типов Python

pydantic-core

Основная функциональность для валидации и сериализации Pydantic

pydantic-settings

Управление настройками с использованием Pydantic

pyduinocli

Обертка вокруг arduino-cli

pyflakes

Пассивный проверщик Python-программ

pymodbus

Полнофункциональный стек протокола Modbus на Python

pyserial

Расширение для последовательного порта Python

pyusb

Модуль доступа к USB из Python

pyvisa

Привязки Python VISA для инструментов GPIB, RS232, TCPIP и USB

pyvisa-py

Чистая Python-реализация библиотеки VISA

pyyaml

Парсер и эмиттер YAML для Python

pyzmq

Привязки Python для 0MQ

redis

Python-клиент для базы данных Redis и хранилища key-value

requests

HTTP для людей на Python

setuptools

Легко загружайте, собирайте, устанавливайте, обновляйте и удаляйте пакеты Python

toml

Библиотека Python для Tom’s Obvious, Minimal Language

untokenize

Преобразует токены в исходный код (с сохранением пробелов)

urllib3

HTTP-библиотека с потокобезопасным пулом соединений, отправкой файлов и прочими возможностями

Для пользовательских RPC-классов обязательно наследование от BaseDevice (если это устройство) или от BaseTarget (если это таргет).

Для структур данных обязательно наследование от BaseModel!

Все методы должны содержать полные аннотации типов для параметров и возвращаемого значения. Например:

# НЕПРАВИЛЬНО - без аннотаций
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"

Без аннотаций система не сможет корректно сгенерировать Julia-код и преобразовать типы данных между Python и Julia.

Методы, предназначенные для вызова из блока, не должны начинаться с _ и __ — такие методы не будут доступны из скриптов и блоков.

Пакет поддержки встраиваемой системы (таргет) должен располагаться в targets/<папка_таргета>/.

Пакет поддержки устройства должен располагаться в devices/<папка_устройства>/.

Для отладки пакета поддержки можно использовать встроенную систему логирования, подробнее см. в разделе Отладка пакетов поддержки. Для добавления информации о пакете поддержки в окно «Оборудование» реализуйте в классе устройства статический метод __get_opportunity_list; подробнее см. в разделе Отображение статуса пакета поддержки в интерфейсе клиентской программы.

Загрузка пользовательского пакета в Engee.Интеграции

В клиентской программе Engee.Интеграции выполните следующие шаги:

Откройте окно статусов оборудования.
Выберите вкладку «Расширения».
Нажмите «Добавить расширение».
Выберите папку с пользовательским пакетом поддержки, который хотите добавить в клиентскую программу.

В случае успешной загрузки в окне диагностики клиентской программы появится сообщение:

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

Чтобы получить в окне диагностики расширенную информацию о найденных классах пакета поддержки и его методах, запустите клиентскую программу в режиме разработчика:

engee-device-manager.exe -d

После успешной загрузки пакета поддержки в окне диагностики отобразится дополнительная информация:

engee integrations custom packages 4 ru

Отладка пакетов поддержки

Для отладки пакета поддержки используйте MainLogger — встроенную систему логирования Engee.Интеграции:

Запустите Engee.Интеграции в режиме разработчика (engee-device-manager.exe -d) и просматривайте логи в окне диагностики клиентской программы.
Отправляйте сообщения через MainLogger из кода вашего пакета поддержки.

Пример:
```
logger.info("Connect {}:{}", host, port)
logger.error("Read failed: {}", err)
```

Доступные методы встроенной системы логирования:

logger.debug("сообщение") — отладочная информация;
logger.info("сообщение") — информационные сообщения;
logger.warning("сообщение") — предупреждения;
logger.error("сообщение") — ошибки.

Сообщения будут отображаться в окне диагностики клиентской программы. Пример использования встроенной системы логирования см. в статье Разработка пользовательского пакета поддержки устройства.

Отображение статуса пакета поддержки в интерфейсе клиентской программы

Клиентская программа отображает статус установленного оборудования: загружен ли драйвер, подключено ли устройство. Для добавления информации о пакете поддержки в окно статусов оборудования реализуйте в классе устройства статический метод __get_opportunity_list.

Принцип работы:

При запуске клиентская программа импортирует все модули из пакетов devices и targets.
Для каждого зарегистрированного класса проверяется наличие приватного метода __get_opportunity_list.
Если метод найден, он вызывается и возвращает список OpportunityStatus.
Клиентская программа опрашивает этот список каждые 3 секунды и отображает информацию в окне статусов оборудования.

Поля OpportunityStatus:

key — уникальный идентификатор строки. Пример: "my_driver"
title_key — заголовок в интерфейсе. Пример: "MyDevice driver:"
value_key — текст статуса. Пример: "Loaded" / "Not loaded"
value_args — аргументы для форматирования значения. Пример: ()
color — цвет индикатора: "green", "orange", "red". Пример: "green"
category — вкладка в окне статусов оборудования:
- "hardware" — «Оборудование»
- "protocols" — «Протоколы»
- "software" — «Интеграции с ПО» (по умолчанию)
- "embedded" — «Встраиваемые системы»

Если поле не указано, категория определяется автоматически по имени пакета устройства.

Пример для пользовательского пакета поддержки устройства:

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

После добавления этого метода пакет поддержки появится на вкладке «Оборудование» в клиентской программе Engee.Интеграции.

Синхронизация и использование пакета поддержки в Engee

Чтобы пользовательский пакет поддержки появился в EngeeDeviceManager.Devices.* или EngeeDeviceManager.Targets.*, выполните в командной строке Engee:

using Main.EngeeDeviceManager
using Main.EngeeDeviceManager.UTILS_API

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

Если были внесены изменения в сигнатуры методов или добавлены новые методы, вызовите syncExtensions() повторно. После синхронизации модули пакетов поддержки становятся доступны для использования в Engee.

Ваш пакет поддержки будет автоматически загружаться при каждом запуске клиентской программы. Если он больше не нужен, то его можно удалить из автозагрузки в клиентской программе:

engee integrations custom packages 3 ru