📘 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.

Using Web IDE

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.

Using Enapter CLI

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 .. Substitute UCMID 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.

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 for require (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.

zmnv / marketplace