Enapter Blueprint has the same purpose as a real device blueprint. It tells the platform about device interfaces and capabilities. The platform uses this information to properly show your device in mobile and web applications and to setup device-related logic in an energy system.
You will normally use the same blueprint to setup any device of the same or similar model.
The minimal blueprint consists of two components:
- The Manifest defines your device interface and capabilities. It's always represented as a
- UCM Lua Script implements the logic required for communication with your endpoint device. Usually you'll find it as a
Long story short, you will just create these two files on your computer or in Enapter Web IDE, upload it using CLI or with one-click IDE button to the UCM and the platform, and you are done, ready to explore your device in Enapter Web and mobile applications.
For the purpose of this tutorial we are implementing a simple blueprint for a fictional hydrogen sensor. Let's say it works over the RS-485 communication standard and supports Modbus RTU protocol, so we will be using ENP-RS485 UCM in our examples. Note that you do not necessarily need ENP-RS485, any other Lua-powered UCM will work for the tutorial as well.
The hydrogen sensor provides its serial number and H2 concentration from the Modbus registers. It has a sound alarm for critical H2 levels. For checking purposes it will make the sound if you write into a specific Modbus register.
Blueprint manifest describes your device in a few core concepts:
properties– device metadata which does not change during normal device operation. "Firmware version", "Device model" and "Serial number" fit this well.
telemetry– device sensors data and internal state which must be tracked during device operation. Examples are "Engine temperature" and "Connection status".
alerts– alerts that the device can raise during operation. An example is "Engine overheating".
commands– commands which can be performed on the device. An example is "Turn on engine".
- Web IDE
Create new blueprint in Enapter Cloud, you'll get into an editor with
manifest.yml opened. Substitute the whole file contents with the listing below.
Create an empty directory that will contain blueprint files and add the
manifest.yml file from the listing below (the file name is important).
The file is based on YAML standard which is sensible to lines indentation. We highly recommend using a text editor or an IDE with YAML support.
Read the details about the manifest file below or jump directly to adding the UCM script file.
communication_module section describes a UCMs which should be used for your device integration. For our example we are using the ENP-RS485 communication module which has built-in Modbus RTU support.
One blueprint can also be backed by several UCMs in complex scenarios, but this is out of the scope of this tutorial.
product is a product code of Enapter UCM. The full list of UCM products is available in the handbook.
lua_file references the UCM Lua script which is uploaded to the related UCM once the blueprint is assigned to it. The file should be located in the same directory as the manifest file.
More information about communication module configuration can be found in the communication modules reference.
Properties are device metadata which unlike sensor data (telemetry) does not change during device normal operation. It could be firmware version, device model, serial number, and similar. Property reference names must be used for sending property values from the UCM Lua script.
Property name used for referencing it from Lua implementation and other parts of the blueprint. It must be unique within a single blueprint.
Property value type, one of:
string. The same type must be used for the value of this property in the Lua script.
display_name will be shown as a property name in a user interface.
More information about properties can be found in the properties reference.
telemetry section defines telemetry attributes supported by the device. Usually, it represents sensor readings and internal device state. Every attribute must be sent from the Lua script under the same name as in the manifest.
Telemetry attribute name used for referencing this telemetry attribute from Lua implementation and other parts of the blueprint. It must be unique within a single blueprint.
Attribute value type, one of:
string. The same type must be used for the value of this attribute in the Lua script.
Optional unit of measurement, only applicable to a numeric attribute type.
display_name will be shown as an attribute name in a user interface.
More information about telemetry attributes can be found in the telemetry reference.
Alerts are faulty device states which device sometimes raises during the operation.
Usually, it gets acquired directly from the device over its communication protocol (e.g. by reading it from a Modbus registers similar to normal telemetry). Or it can be calculated in the Lua script as a reaction on some telemetry values (e.g. if H2 concentration is higher than 1%).
Alerts are defined in the
alerts manifest section.
Alert name. Lua script must send this name in the
alerts field inside telemetry data if the device has this alert active at the moment.
Alert severity is used in notification rules, should be one of:
display_name will be shown as an alert name in a user interface.
If device is sending undeclared alert (not defined in the manifest) in
alerts telemetry field, it will be considered as alert of severity
display_name equal to alert reference name.
More information about alerts can be found in the alerts reference.
commands section defines what commands are supported by the device. Every command defined in the manifest must be implemented in the Lua script under the same name as in the manifest.
Command name is used for referencing it from Lua implementation and other parts of the blueprint. It must be unique within a single blueprint.
display_name will be shown as a command name in a user interface.
icon which will be used for the command in a user interface. Must be one from the full list of available icons.
quick_access adds command into quick access list in Enapter mobile app.
Use the remote control button on the device screen in Enapter mobile application to trigger a quick access list.
Blueprint commands also support confirmations and passing user-defined arguments, read more about it in the commands reference.
UCM script implements device interface declared in the manifest file using Lua programming language. Device communication APIs exposed to Lua depend on a UCM model and communication standard it supports. For this example we skip everything related to communication with the connected device and just return sample properties and telemetry.
- Web IDE
Substitute the contents of the
ucm.lua file with the code from the listing below.
Create a file from the listing below in the same directory as your
manifest.yml under the
ucm.lua name (as it is in the manifest).
There are few API calls used for sending device properties and telemetry.
Registers a periodic function execution.
send_telemetry function will be called every
Sends device properties and telemetry,
data is a Lua table (key-value pairs).
When a connected device has some active alert, UCM shall send its identifier in
alerts telemetry attribute along with other attributes.
If you are using alerts mechanism in your blueprint, always send
alerts attribute in telemetry:
- Keep sending alert name in the
alertsarray until the alert is resolved.
- If there are no active alerts, keep sending an empty array.
alerts attribute holds Lua array with alert identifiers that are active at the moment.
To implement commands described in the manifest one has to define the handler function for every command with a call to
Command execution function must accept two parameters.
ctx is a command execution context.
args holds command arguments (passed from user) as a Lua table.
Registers handler for the command named
beep. The name must be equal to the command reference name from the manifest. The function
beep_command passed as a second argument will be executed every time user starts the command from a web, mobile, or an API.
Now we have our blueprint prepared for being uploaded to the UCM.