node-eaf-amr-client

Automated Meter Reading client for STROMDAO Energy Application Framework to allow dynamic electricity tariffs without decicated SmartMeter-Gateway (iMSys).

Demo

Introduction

The transition to dynamic electricity tariffs is a critical step towards a more flexible and efficient energy market, especially as we embrace the dynamic nature of renewable energy sources. In Germany, the adoption of these tariffs requires the deployment of Smart Meter Gateways (iMSyses - intelligentes Messsysteme), which play a pivotal role in accurately capturing household energy consumption in real-time. Unfortunately, the penetration of these Smart Meter Gateways in German households is still low, creating a significant challenge in the widespread implementation of dynamic tariffs.

To address this gap, alternative meter reading equipment (Lesekopf) is often used. While these devices can fill the hardware requirement to some extent, they lack the integrated functions of a Smart Meter Gateway necessary for the proper management and communication of meter readings. These functions include crucial tasks such as cryptographic verification and secure data transmission to the utility or tariff provider.

The node-eaf-amr-client module emerges as the technological solution to this impediment. As part of the STROMDAO Energy Application Framework, it provides a robust implementation of the cryptographic and communication methods similar to those performed by an intelligent metering system. This software library is designed to integrate seamlessly into Energy Management Systems or SmartHome platforms, facilitating dynamic electricity tariffs without requiring dedicated Smart Meter Gateway hardware.

The node-eaf-amr-client encapsulates the complexity associated with authentication, authorization, and cryptographic verification of automated meter readings, hence simulating crucial aspects of what an iMSys does internally. With its two primary methods -- updateReading for transmitting meter readings and retrieveTariff for retrieving forecasted tariffs and cryptographic validation -- it simplifies the interaction between households and utility providers.

By empowering homes with the capability to communicate their meter readings and securely receive information on electricity prices, the node-eaf-amr-client plays an instrumental role in the scalable adoption of dynamic tariffs. This, in turn, allows consumers to make informed decisions about their energy use, adjusting consumption patterns to benefit from fluctuating energy costs, and contributing to a more demand-responsive and resilient energy grid.

Prerequisites

The successful deployment and operation of the node-eaf-amr-client module hinge on meeting certain prerequisites. These requirements ensure that the necessary hardware and software environments are in place for the module to function correctly. Here are the prerequisites for implementing the node-eaf-amr-client:

1. Meter Reading Equipment: At the core of the setup is a meter reading device, commonly referred to as "Lesekopf," which must be properly installed and configured at the electricity meter. This device is responsible for capturing the energy consumption data that will be processed by the node-eaf-amr-client.

2. Runtime Environment: The node-eaf-amr-client is designed to operate on a lightweight computing device that can manage the continuous flow of data. A common choice is an embedded device or a small computer like a Raspberry Pi. These devices offer the necessary computational power as well as network connectivity to support the module’s operations.

3. Home Energy Management System: To integrate seamlessly with the user's energy ecosystem, the node-eaf-amr-client should run within a Home Energy Management System (HEMS). Examples of compatible HEMS platforms include:

   • Home Assistant: an open-source home automation platform that puts local control and privacy first.
   • ioBroker: an integration platform for the Internet of Things, focused on Smart Home, Building Automation, and other applications.
   • IP-Symcon: a software solution that connects and automates devices from different manufacturers into a single system.
   • Node-RED: a flow-based development tool for visual programming developed originally by IBM for wiring together hardware devices, APIs, and online services.

Choosing a suitable HEMS is crucial as it acts as the backbone of your smart home energy management, providing a versatile and user-friendly environment to manage the interactions between the node-eaf-amr-client and other home automation tasks.

Before proceeding with the installation of the node-eaf-amr-client, ensure that:

• The selected meter reading device is compatible with the system and properly installed.
• Your computing device (e.g., Raspberry Pi) is set up with a stable operating system and network connectivity.
• The chosen Home Energy Management System is installed and running smoothly on your device, ready to incorporate the node-eaf-amr-client as one of its components.

Installation

node-eaf-amr-client --version
# or
node-eaf-amr-client --help

The node-eaf-amr-client module is designed to be straightforward to install, whether you're integrating it as part of a Home Energy Management System (HEMS) extension or using it as a standalone command line tool. The module can often be included directly by the plugins or extensions provided by your HEMS, which handle the installation behind the scenes, making it seamless for the end-user. These integrated solutions ensure that the module is correctly configured within the ecosystem of your chosen HEMS platform.

However, if you're working in an environment without a dedicated plugin or looking to perform quick testing, manual installation is also an option. The node-eaf-amr-client has been made available as a package that can be installed globally using popular package managers like npm (Node Package Manager) or Yarn.

To install the node-eaf-amr-client as a global command line tool, you can use the following npm command:

npm install -g node-eaf-amr-client

This will install the module globally, making it accessible from any location in your command line interface. Once installed, you can start using the node-eaf-amr-client to update meter readings or retrieve tariffs directly from the command line.

During installation, the package manager may prompt you for additional permissions, especially if installing globally requires administrative rights on your system. On UNIX-like systems (Linux, macOS), this might necessitate prefixing the command with sudo to grant elevated privileges:

sudo npm install -g node-eaf-amr-client

Follow any instructions provided by the package manager to complete the installation. After the installation is successful, verify it by running a simple command to check the version or help documentation of the node-eaf-amr-client which can ensure the module is installed correctly:

node-eaf-amr-client --version
# or
node-eaf-amr-client --help

Take note that the standalone installation may not have the same ease of integration or may require additional configuration steps that are typically managed by HEMS plugins. Be sure to refer to the module's documentation for any additional setup or configuration instructions.

Configuration

Configuring within a Home Energy Management System (HEMS)

When incorporating the node-eaf-amr-client into a Home Energy Management System, configuration typically takes place within the settings of that system. HEMS platforms usually provide a user-friendly interface or configuration file where parameters can be set up and managed easily. This ensures that the node-eaf-amr-client integrates smoothly with other smart home components and that its settings can be maintained alongside those of the overall system.

It is important to check the documentation for the specific HEMS being used for the correct steps to configure the module within that environment.

Configuring for Standalone or Development Use

For developers or for use as a standalone command line tool, understanding the operation of the node-eaf-amr-client is essential prior to configuration. The module operates in a stateless manner; it does not retain any internal status information between operations. As a result, the configuration must be read at the instance's creation and should be preserved for the duration of the session.

A robust practice involves maintaining a separate configuration object for each meter to be managed, with the object being updated every time a method of the module is called. Here's a sample code snippet demonstrating this approach in JavaScript:

const NEAC = require("node-eaf-amr-client");

// Instantiate with initial configuration
let configuration = {
  // Basic configuration parameters
};
const instance = new NEAC(configuration);

// Perform an update reading
await instance.updateReading(12345);

// Update the configuration object
configuration = instance.toObject();

// Convert to a JSON string representation if needed
const jsonConfigString = instance.toString();

Basic Configuration Settings

The basic configuration parameters for node-eaf-amr-client are as follows:

• baseUrl: The API endpoint provided by the utility, tariff provider, or meter point operator.
• activationSecret: A secret key supplied by the utility or tariff provider necessary for the initial activation process.
• readingToken: The token used for authentication in operational calls, provided after the initial activation.
• meterId: The assigned meter point ID or the physical identifier of the meter.

The Activation Process

The activation process for the node-eaf-amr-client involves using the activationSecret during the first meter reading update and utilizing the readingToken for subsequent calls. Below is sample code illustrating the activation sequence:

// Configuration for the first update
let initialConfiguration = {
  baseUrl: "http://localhost:3001",
  meterId: "1337",
  activationSecret: "12345678"
};

// Instantiate with the initial configuration
const initialInstance = new NEAC(initialConfiguration);

// Perform the first update reading
await initialInstance.updateReading(12345);

// Save the updated active configuration after activation
let activeConfiguration = initialInstance.toObject();

For subsequent updates, you would initialize the node-eaf-amr-client with the activeConfiguration which now contains the readingToken:

// Instantiate with active configuration for following updates
const activeInstance = new NEAC(activeConfiguration);

// Perform subsequent update readings
await activeInstance.updateReading(987654);

// Update the configuration object again
activeConfiguration = activeInstance.toObject();

This outlines the initial activation using the activationSecret and subsequent operations using the readingToken. Be sure to securely manage the configuration details, especially tokens and secrets, to maintain the security of the meter reading process.

Standalone Usage from Command Line

The command-line interface (CLI) or standalone usage of node-eaf-amr-client is particularly useful for testing purposes or in environments where direct integration within a Home Energy Management System (HEMS) is not supported. This mode allows users to quickly test the automated meter reading process and securely transmit meter data to the utility for settlement.

Installation

Begin by installing node-eaf-amr-client globally to make it available as a command-line tool on your system:

npm install -g node-eaf-amr-client

This installation step only needs to be performed once and will enable you to use the node-eaf-amr-client from any location in the command line.

Retrieve Tariff

To retrieve the current tariff for a specific meter point, you can use the following command:

eaf-amr-client --meterId=demo -v=5 --activationSecret="yourSecret" --file=demo.config.json retrieveTariff

Make sure to replace yourSecret with the actual activation secret provided by your utility or meter point operator. Additionally, replace demo with your specific meter point ID that has a dynamic tariff assigned to it.

Update Reading

When you want to update the meter reading, you can use this command:

eaf-amr-client --meterId=demo -v=5 --activationSecret="yourSecret" --file=demo.config.json updateReading 123456790123

Again, replace yourSecret with your actual activation secret. The demo should be replaced with your true meter point ID. The number 123456790123 represents the current meter reading in Watt-Hours (Wh) expressed as a pure integer without any decimal figures.

Configuration File Handling

In both of the above method calls, a configuration file is specified to persist the updated settings and consensus information, which is denoted by --file=demo.config.json in the commands. This approach is particularly advantageous since some utilities may limit the use of the activationSecret to a single instance, and subsequent requests will require the readingToken.

Storing the configuration information in a file ensures that stateful data — such as the readingToken and other relevant consensus information — is maintained between operations. This is critical because once an initial meter reading update is performed using the activation secret, further communication with the utility will rely on the reading token for authentication.

To comply with best practices regarding security, configure the permissions of the configuration file appropriately to prevent unauthorized access. Always handle sensitive information, such as tokens and secrets, with the utmost care to safeguard the integrity of the meter reading transmission process.

License

Distributed under the Apache-2.0 License. See License for more information.

Maintainer / Imprint