Interacting with Hardware
The Enapter EMS Toolkit supports a variety of hardware and connection topologies. The Enapter Lua API is designed to
- be hardware-agnostic, enabling the same code to run on different devices and topologies without modification,
- support running multiple blueprints simultaneously on a single piece of hardware.
Connection URI
Communication with hardware is managed through generic clients, which offer a consistent interface across all supported devices. Each client is initialized with a connection URI that specifies how and where to connect:
local serial_client = serial.new("port://rs232")
local modbus_client = modbus.new("tcp://192.168.1.42:5678")
This means you can switch between physical connections by simply changing the client constructor argument — no other code changes required.
Connection URIs are strings that follow RFC 3986:
<scheme>://<target>[?<parameters>]
The scheme specifies the communication method, and the target specifies the communication endpoint — in other words, the schemes defines how to connect, while the target defines where to connect.
For example, Modbus communication can work over serial port, over TCP, or over Generic IO. A connection URI for a Modbus client might look like this:
| Connection URI | Description |
|---|---|
port://rs485 | Modbus RTU over hardware port named rs485 |
tcp://192.168.1.42:5678 | Modbus TCP with server at 192.168.1.42:5678 |
gio://dev/serial | Modbus over Generic IO with hardware port serial on device dev |
List of the supported connection options for each IO client is provided on its reference pages.
Hardware Ports
All hardware is accessed through uniquely identified hardware ports, which are used for the underlying hardware configuration. This approach enables resource sharing between blueprints and prevents connection errors caused by concurrent misconfigurations.
Each Enapter hardware UCM comes with a predefined set of hardware ports. For example, the ENP-CAN module provides a single port for connecting to the CAN bus, the ENP-RL6 module offers six digital output ports, and the ENP-AI4 module provides four analog input ports.
To use a hardware port, set port as the schema and the port name as the target in the connection URI, for example: port://can or port://do-1.
Some ports must be configured before use in Lua scripts — for instance, the CAN port requires setting the bus baud rate. These requirements are mentioned in the Lua API reference.
Hardware Configuration
You can view and configure available ports on your devices through the Enapter EMS Web UI. To do this, open the communication device page, navigate to Settings → Hardware Ports, enter the desired port settings, and click Update.
Hardware Ports Settings for ENP-RS232
Virtual UCM Ports
Virtual UCM enables easy integration of devices using any protocol running over TCP/IP, but also, if the hardware is officially supported, can work directly with the built-in hardware of used computer. To make hardware ports available for Virtual UCM, open Gateway Settings → Hardware Settings, select your computer model, choose the hardware you have installed, and click Update.
Gateway Hardware Settings
Once updated, the selected ports are exposed as hardware ports for the Virtual UCM.
Generic IO Interface
Generic IO connection schema is available only for Virtual UCMs.
Generic IO (GIO) is a protocol for UCM-to-UCM communication. It allows one UCM to use the hardware ports of another, which can be useful if you want to control multiple hardware devices and present their data and controls as a single device in the Enapter EMS.
The name "Generic IO" comes from the idea that one UCM provides a generic input/output interface for controlling its hardware. Thus, the target hardware device must implement this interface — create a Lua device with one of GIO blueprints from the Enapter Marketplace for this purpose.
To use a device via GIO, set gio as the schema and specify the device and its port name, separated by a slash, as the target in the connection URI — for example: gio://dev1/port1 (use port port1 on device dev1, where dev1 can be either the device ID or device slug). Currently, only Virtual UCMs can be used to control other devices — one hardware UCM cannot control another hardware UCM.