Enapter Handbook

# Gateway Software

The gateway is an energy site and IoT controller that optimizes energy systems operating either fully or partially off-grid. It manages energy storage, energy consumption, solar PV, and other generators, and performs islanding control during blackouts. Additionally, the gateway autonomously maintains data backup in case of an unstable internet connection and reduces traffic by leveraging telemetry compression.

Gateway Software

# 🔥 What's New

# 🛠️ Features

The gateway software provides the following functions:

  • Internet connectivity issues mitigation for reliable data delivery to Enapter Cloud.
  • Aggregated data from all devices such as UCMs and Electrolysers, and data compression.
  • OPC UA and HTTP API interfaces for 3rd party integrations.
  • Public MQTT for 3rd party integrations.
  • Rule Engine for energy system automation with Lua scripts.

# 📖 Downloads

Note

The latest version of Gateway Software can be found at fw.enapter.com (opens new window).

# ✅ Required Equipment

  1. Intel NUC computer with suitable power supply.
  2. USB flash drive 16 GB minimum.
  3. External Monitor with HDMI cable.
  4. USB Keyboard.
  5. Wi-Fi Router with Ethernet Cable.

Gateway Equipment

# Purchase Intel NUC

The wide range of Intel NUC models is supported, though minimal system requirements are applicable.

Recommended Configuration Minimal Configuration
NUC Model Intel® NUC 10th generation or later Intel® NUC 8
Processor Intel® Core™ i3 or i5, 4 cores Intel® Celeron® 2.4 GHz
Memory, RAM 8 GB 4 GB
Data Storage 250 GB SSD or NVMe M.2 250 GB SSD

Example models:

# 🚀 Installation Guide

# Create Bootable USB Flash

Note

USB Flash with Gateway Software will be constantly attached to the NUC during the gateway operation.

  1. Insert USB Flash to your computer connected to internet.
  2. Download the Gateway Software pack from fw.enapter.com (opens new window) to your computer.
  3. Download and install Balena Etcher (opens new window). It will be used to write the Gateway Software image to the USB flash.
  4. Start Balena Etcher and follow on-screen instructions: select Gateway Software file, select your USD flash drive, run the flashing process. Wait until flashing is successfully finished.
  5. Bootable USB Flash is ready, extract the USB flash from your computer.

# Cable Connections

Gateway Connections

Warning

Make the entire assembly process while the gateway is turned off.

Warning

Make sure you’re using the correct type of DC power supply that is specified in the user manual of your NUC model.

  1. Connect external monitor with HDMI cable.
  2. Insert USB Keyboard into any USB port.
  3. Connect to WiFi Router with Ethernet cable.
  4. Finally, connect Intel NUC to power supply and switch on the gateway. You will see a welcome screen on the connected monitor.

# Disable Secure Boot in Gateway BIOS

Enapter OS will boot from the USB flash. To enable it, Secure Boot must be turned off in BIOS.

To enter the BIOS press F2 button on a keyboard few times right after powering up Intel NUC. If you are facing issues with this step, check this troubleshooting guide (opens new window).

# NUC with Visual BIOS

  • Click Advanced > Boot > Secure Boot tab.
  • Uncheck Secure Boot option.
  • Press F10.
  • Select Yes to save this change.
  • Reboot the system.

# NUC with Aptio V BIOS

  • Click Boot > Secure Boot option
  • Select Disabled option for Secure Boot.
  • Press F10.
  • Select Yes to save this change.
  • Reboot the system.

# Set Up Gateway Software

Gateway Set Up

Note

Computer or mobile phone should be connected to the same network as the gateway.

  1. Make sure gateway is connected to WiFi router via Ethernet cable.
  2. Insert Bootable USB Flash into any USB port in the gateway.
  3. Reboot a the gateway. After reboot you will see Enapter welcome screen on the connected monitor.
  4. To continue setup you need to access Gateway Web Interface. Open a new tab in the browser on your computer mobile phone. Enter ...local into the address bar. If it doesn’t work, use IP address of Gateway instead (To obtain IP address, enter ip command on the initial welcome screen. The error may appear if the network is not yet initialized, please try again in one minute).
  5. Follow the on-screen setup instructions to finish the Gateway installation.

# ⚙️ Operational Modes

Gateway Modes

# Comparison Cloud Mode and Island Mode

Cloud Mode Island Mode
Description On-site devices will be accessible remotely through Enapter Cloud. All data, including device configuration and telemetry, will be stored in the Cloud. Most sites that are located in remote areas where internet connection is not easily accessible or is not stable. Even if the Internet connection is available, it is important for business to keep their equipment operational in isolated setups in case of a power outage.
That is why Enapter offers Island Mode for Gateway that allows to collect and store data from Enapter devices locally.
Historical Data /
Monitoring charts		 Yes
Unlimited free cloud data storage		 Yes
Limited by Gateway’s data drive storage
Commands Yes Yes
Remote access Yes No
Sites amount Unlimited
Cloud supports unlimited setups in any location		 Only 1 site
Gateway supports only one setup
Adding 3rd party energy devices Yes
Any vendor device can be added to an energy management system with UCMs and Blueprints		 No
Only Enapter Electrolysers, Dryers and Water Tanks can be added

# How to Set up Gateway in Island Mode

  1. Connect and power on all Enapter devices.
  2. Connect Intel NUC PC with Gateway 2.X software and network equipment according to technical specifications.
  3. Set up Gateway 2.X software using installation instructions.
  4. Open Enapter App and add Island connection.
  5. Scan QR code of an Enapter device and follow instructions.

# Virtual UCM

If you want to integrate devices connected to an Ethernet or WiFi network and use protocols such as Modbus TCP, HTTP, OPC UA for communication, then you do not need additional hardware modules and all you need is your Enapter Gateway and Enapter vUCM technology.

To integrate devices, you will need to create a device description in YAML format and some Lua code. For more information see our documentation on Enapter Blueprints (opens new window) и vUCM Lua API (opens new window)

# How to Add Virtual UCM

To add Virtual UCM to your Site:

# Rule Engine

Gateway firmware 2.x contains a redesigned Rule Engine that allows you to write rules in the Lua language using a convenient web IDE.

Now the Rule Engine supports not only Enapter devices but also any other devices, thanks to Enapter Blueprints technology.

See our Enapter Blueprints (opens new window) and Enapter Rule Engine (opens new window) programming guide for writing rules in Lua.

Also, be sure to check the Use cases section for examples of rules usage.

# Create Enapter Rule

  • Open your Site in Enapter Cloud (opens new window).
  • Look for Rules on the left sidebar and click on the Manage button.
  • On the next screen, click the New Rule button in the top right corner.

# 🖥️ Command Line Interface

The Enapter CLI can be accessed in two ways:

As both ways using CLI are mostly the same, all instructions in this guide applicable for both cases.

Check our video guide to know how to access the CLI using Web Terminal.

# Command Modes

The are two command modes in Enapter CLI: operational mode and configuration mode.

  • Operational mode provides access to operational commands for showing help information, exiting CLI, showing system information, etc.
  • Configuration provides access to commands for creating, modifying, deleting, committing and showing configuration information, as well as commands for navigating through the configuration hierarchy.

When you log on to the system, the system is in operational mode.

  • To enter configuration mode from operational mode, issue the configure command.
  • To return to operational mode from configuration mode, issue the exit command. If there are uncommitted configuration changes, you must either commit the changes using the commit command, or enter exit to discard the changes.

# Configuration Mode

In configuration mode you can set, delete and show information. Enter configuration mode by typing configure at the command prompt in operational mode.

[enapter] $ configure
[enapter] conf $

[enapter] conf $ exit
[enapter] $

Notice how the command prompt changes to remind you what mode you are in.

# Command Completion

Pressing the <Tab> key provides command completion. You can use the <Tab> to show:

  • All available commands
  • All valid completions for a command partially typed in
  • The next available set of options for a command. You can use the <Tab> key iteratively in this way to discover complete command syntax.

Example 2-1 Use command completion on an unambiguous command

The following example requests command completion for the typed string sh. In this example, the command to be completed is unambiguous.

[enapter] conf $ sh <tab>
[enapter] conf $ show

# List of Possible Commands in Operational Mode

Command Description
exit Exit shell
help Display help message
services Services operations
variables Variables operations
show Show system information
network Network configuration commands
configure Enter configuration mode
factory-reset Factory reset
reboot Reboot server
ping Execute ping command

# 🕸️ Public MQTT API

# Configuration

Before starting integration process MQTT API should be configured. If you are not familiar with how to access and use Enapter Command Line interface please see Enapter Command Line Interface section of this documentation.

To do this - enter configuration mode on gateway shell and set basic parameters.

# Setup MQTT Port and Authentication

Public MQTT port is 9883.

set public-mqtt authentication username "public"
set public-mqtt authentication password "password"
commit
save

# Receiving device telemetry

  1. Connect to mqtt on gateway ip address, specified port, with specified username & password,
  2. Subscribe to telemetry topic.
mosquitto_sub -d -v -p 9883 -h 192.168.1.1 -u public -P password -t "telemetry/v1/<DEVICE_ID>"

# Device Telemetry API

# Device Telemetry

Provides Device telemetry.

Will be published every 1 second.

telemetry/v1/{id}
Payload Field Description
timestamp Message publishing timestamp
... Device-specific fields
# Example

Topic

telemetry/v1/A0B1

Payload

{
  "timestamp": 1514320289,
  "uptime": 2
}

# Device Commands API

# Request Command Execution

commands/v1/{id}/requests
Payload Field Description
id Command execution ID, e.g. UUID
name Command name
arguments Optional, command arguments
expires Optional, command expiration timestamp
# Example

Topic

commands/v1/A0B1/requests

Payload

{
  "id": "ab3e364c-cab2-4cc1-872d-4d554530d587",
  "name": "impulse",
  "arguments": {
    "id": 1,
    "impulse": 300
  }
}

# Command Execution Responses

commands/v1/{id}/responses
Payload Field Description
id Required, command execution ID, e.g. UUID
state Required, command execution state, e.g. started
payload Optional, command state payload
# Example

Topic

commands/v1/A0B1/responses

Payload

{
  "id": "ab3e364c-cab2-4cc1-872d-4d554530d587",
  "name": "finished"
}

# Electrolyser V2.1 Protocol

# Device Telemetry Payload

Field Description
electrolyte_downstream_temperature Downstream Temperature in Celsius
electrolyte_level_high Indicates whether electrolyte level is higher than high level
electrolyte_level_low Indicates whether electrolyte level is higher than low level
electrolyte_level_medium Indicates whether electrolyte level is higher than medium level
electrolyte_level_very_high Indicates whether electrolyte level is higher than very high level
electrolyte_tank_temperature Electrolyte Tank Temperature in Celsius
errors List of electrolyser errors (opens new window)
h2_flow H2 Production in Normal Litre/hour
h2_total Total H2 Produced in Normal Litre
has_errors Indicates whether any device errors boolean
has_warnings Indicates whether any device warnings boolean
is_running Indicates whether device is running boolean
outlet_pressure H2 Outlet Pressure in Bar
production_rate Current electrolyser production rate in percents
stack_amperage H2 Stack Amperage in Ampere
stack_pressure H2 Stack Pressure in Bar
stack_voltage H2 Stack Voltage in Volt
status Electrolyser status string one of maintenance, expert, error, fatal, idle, steady, standby, curve, blowdown
timestamp Message publishing timestamp
warnings List of electrolyser warnings (opens new window)
water_inlet_pressure Water Inlet Pressure in Bar
water_refilling_valve_open Indicates whether water refilling valve is open state
# Example
{
  "electrolyte_downstream_temperature": 24.7,
  "electrolyte_level_high": false,
  "electrolyte_level_low": true,
  "electrolyte_level_medium": true,
  "electrolyte_level_very_high": false,
  "electrolyte_tank_temperature":  38.3,
  "errors": ["FP_01", "FP_03"],
  "h2_flow": 250.0,
  "h2_total": 10000,
  "has_errors":  true,
  "has_warnings": false,
  "is_running":  true,
  "outlet_pressure":  30.0,
  "production_rate": 100,
  "stack_amperage": 12.3,
  "stack_pressure": 30.1,
  "stack_voltage": 38.1,
  "status": "steady",
  "timestamp": 1514320289,
  "warnings": [],
  "water_inlet_pressure": 1.2,
  "water_refilling_valve_open": false
}

# Supported Commands

Command Name Description Arguments
start Start electrolyser
stop Stop electrolyser
reset Reset electrolyser
set_production_rate Set electrolyser production rate (in percents) value (float)
set_waterfill Force electrolyser to perform water refill operation value (boolean) (should be set to true)
set_preheat Start electrolyser pre-heating value (boolean) (should be set to true)

# Enapter Dryer Protocol

# Device Telemetry Payload

Field Description
timestamp Message publishing timestamp
status Dryer status string one of waiting_for_power, waiting_for_pressure, stopped_by_user, starting, standby, waiting_for_pressure, drying_0, cooling_0, switching_0, pressurizing_0, finalizing_0, drying_1, cooling_1, switching_1, pressurizing_1, finalizing_1, leak_input, leak_dryer, error
is_running Indicates whether device is running boolean
has_errors Indicates whether any device errors boolean
errors List of dryer errors (opens new window)
warnings List of dryer warnings (opens new window)
input_pressure H2 Inlet Pressure in Bar
output_pressure H2 Outlet Pressure in Bar
# Example
{
  "timestamp": 1547680704,
  "status": "drying_0",
  "is_running": true,
  "has_errors": true,
  "input_pressure": 30.5,
  "output_pressure": 26.1,
  "errors": ["TT00", "PT00"],
  "warings": []
}

# Supported Commands

Command Name Description
start Start dryer
stop Stop dryer
reset Reset dryer

# 💻 OPC UA

OPC UA (Open Platform Communication Unified Architecture) is a secure OT-IT communication standard mostly for industrial equipment. Known by some as “the global production language”, OPC UA enables improved data communication and interoperability between devices and systems in many industries.

Info

Definition, features and more details about OPC UA can be found at opcfoundation.org (opens new window).

# Required Equipment

You will need a Enapter Gateway Software installed to your Intel NUC computer. It provides telemetry, properties and commands for all connected devices over the OPC UA interface, for easier interoperability with industrial systems.

# Enabling OPC UA on the Gateway

OPC UA - Enabling

The OPC UA server feature has to be enabled on the settings page available in the Gateway web interface. No further configuration is needed in both Island and Cloud modes: connected devices will automatically appear in the OPC UA nodes tree.

  1. Install Gateway Software according to this guide.
  2. Access Web GUI of the Gateway using http://enapter-gateway.local or IP address.
  3. Click on Settings.
  4. Click on the Enable button in the OPC UA Server area.

# Connecting to OPC UA Client

Download a OPC UA client, for example UAExpert (opens new window) from Unified Automation. UAExpert is a free download for testing OPC UA connectivity and data flow.

To Connect UAExpert to the Enapter OPC UA Server follow these steps:

  1. In UAExpert, under Server select Add…. A dialog will appear with the most recently used servers. Under the Custom Discovery branch follow Double Click to Add Server…. In the upcoming dialog enter: opc.tcp://enapter-gateway.local.

OPC UA - Enter URL

Info

You need to make sure that your DNS server is resolving this address correctly or you will not be able to connect. You can use the IP address of the Gateway instead of enapter-gateway.local but you might run in security issues with the certificate of the OPC UA Server which uses enapter-gateway.local as its host-name.

  1. Once the URL is showing in the list under Custom Discovery you can double-click the entry to see the Enapter UA Server. If you double-click on this entry, you can choose an encryption for the connection. Pick the one that is closest to the encryption your OPC UA Client will use. The server will then appear on the left side under Project/Servers.

  2. To connect to the server, right click the server and select “Connect”. The first time you connect you will be prompted to trust the Self-Signed Server Certificate of the OPC UA Server.

OPC UA - Certificate Validation

Click the Trust Server Certificate button to accept the certificate then click on Continue.

Info

Under UA Extensions you see the DNSNames: enapter-gateway.local. Some OPC UA Clients are sensitive that this DNS name matches the URL you picked in Step 1 and will reject certificates if the DNS name does not match. We recommend that you make sure your gateway resolves correctly to enapter-Gateway.local in your network.

  1. You can now see all the Devices managed by the Gateway in the Address Space area under Root/Objects/Enapter.

Each Device is one OPC UA Object. You can navigate the tree to the Properties and Telemetry data of any device. If you drag a Telemetry field to the Data Access View you can see the live value of the field.

All Enapter devices (electrolysers, dryers, water tanks) and any 3rd party device integrated via Enapter Blueprints are exposed the same way in the OPC UA tree.

OPC UA - Connected devices

Note

In future versions of the OPC UA Server, the hierarchy of the object might change.

# 🤖 Creating Enapter Rule (Automation)

# 💼 Enapter Rule Engine Use Cases

Enapter Rule Engine recipes are available in Developers Documentation (opens new window).

Feel free to ask for a help in Discord (opens new window).

Release Notes