📘 Enapter Device Blueprints
This is a collection of device blueprints for the integration of your energy devices into the Enapter platform. Once integrated, you can monitor and control your devices using the mobile app or Web dashboards. You can also automate your devices' interoperation with Lua scripting.
Go through the tutorial to learn about the blueprint concept and development workflow.
Quick Overview
Top-level directories represent energy and industrial device types. Each directory contains a number of blueprints for specific device models.
The blueprint is an entity containing all aspects pertaining to device integration. It consists of two files:
manifest.yml
describes your device interfaces (telemetry it sends, commands it executes, alerts it raises);firmware.lua
implements these interfaces for the specific piece of hardware using the Lua programming language and high-level platform APIs.
There are two types of hardware that can run your blueprint:
- a physical Enapter UCM that implements communication through RS-485, CAN, and other standards,
- a virtual UCM – a software element of the Enapter Gateway 2.X (runs on an Intel-based server) that implements communication either over a local network (Ethernet) or by using a direct USB connection (serial communication).
Regardless of the underlying hardware, UCMs provide a runtime for Lua execution and expose APIs for Enapter Cloud connection, physical connections and protocols (e.g. 6-channel relay, RS-485 serial communication, Modbus RTU, Modbus TCP, etc).
How To Use These Blueprints
- Select a UCM suitable for communicating with your target device.
- Provision your UCM to the Enapter Cloud using the mobile app or run a new virtual UCM on the Enapter Gateway.
- Follow one of the options below to upload a blueprint to the UCM.
Web IDE
Using- Drag and drop the blueprint files into the IDE or copy and paste its contents.
- Press "Select Device" and choose your UCM
- Press "Upload to" to upload the blueprint.
Enapter CLI
Using- Follow the steps described in the tutorial to get the CLI tool and your API access token.
- Switch the current directory to the desired blueprint.
- Execute the command
enapter-cli devices upload --hardware-id UCMID --blueprint-dir .
. SubstituteUCMID
with your UCM ID.
After uploading the blueprint, your device data will appear on the device page in the Enapter Cloud and the mobile application.
Blueprints Development
We welcome any contributions when it comes to integrating new devices into the system, whether it's development efforts or testing the blueprints on your hardware.
License and Authorship
Blueprints in the marketplace should be licensed under the MIT license. Please add license: MIT
in your manifest.yml
.
Also you can specify authorship and support information via author
, contributors
and support
fields.
Note About Dot-Fields
manifest.yml
is validated against the specification, although not every aspect of the manifest is ready to be fixed in the specification. Some in-progress features are backed by YAML fields that start with a dot (e.g. .cloud
). These fields are not documented and ignored in the manifest validation. When the feature is ready, the field will be moved into the main manifest body, and the blueprints will be updated.
Writing Blueprint README
Please follow this simple checklist for every blueprint README file:
- Level 1 header should contain vendor and full model or product family.
- Intro paragraph should briefly describe the device.
- Make sure that blueprint's use case is clear.
- Some blueprints may require physical connection schematics. You can add it as a picture to the README file or as a link to a PDF file. Place the file into the blueprint directory.
- List the hardware needed for the physical connection. This may be an Enapter UCM model, communication interface converter, etc.
- Device pictures and vendor logos are always welcome, but we ask you to respect the author of said pictures and to follow copyright and licencing guidelines.
- References should be given to the device vendor page, manual, API documentation, etc.
Linters
Blueprint files are validated using yamllint
and luacheck
linters. The configuration can be found in .yamllint.yml
and .luacheckrc
files respectively.
Run the linters locally before creating a pull request:
luacheck .
yamllint .
markdownlint .
Lua Codestyle
- Document with LDoc.
- Use 2 spaces for indentation.
- Use
snake_case
for variables and functions. - Use
CamelCase
for OOP class names. - Use
UPPER_CASE
for constants. Put top-level constants at the beginning of the file. - Use
is_
when naming boolean functions, e.g.is_between()
. - Use single quotes
'
over double"
quotes. Use double quotes when string contains single quotes already. - Use parenthesis in function calls (
local a = myfun('any')
). Though it's ok to omit it forrequire
(local a = require 'rules'
). - No spaces in concatenation operator (
'some'..var..' ok'
). - No spaces around function args declaration (
function hello(a, b)
). - Typecheck in critical places (
assert(type(myvar) == 'string')
).
Some more coding conventions are available in the LuaRocks style guide.