Skip to main content

Plan-ahead API

tip

The Plan-ahead API is meant for sending schedules ahead of time. For live control, see Live MQTT control instead

What you need​

  1. An API username & password. You can use your Insights account for this, or request an API account by sending an email to support@eniris.be, clearly mentioning your device serial number.
  2. Python development environment (or any other MQTT client). This guide uses a basic example written in Python to get you started with MQTT and sending commands. We recommend to use Python for the ease of use, but any other MQTT client is supported.

First-time Configuration (Starting point for new users)​

1. Find the device IDs of the devices that you want to control​

The device ID (also called nodeId) is an unique identifier for each device in our system and is used when sending commands to devices.

At the moment, the easiest way to get your IDs is by navigating to: http://<CONTROLLER_IP>/debugger

Expand the 'Metadata' box, and note down each nodeId from all devices that you'd like to control. You will need these IDS in a later step.

Image 1

2. Add your devices​

Login to the commissioning interface and make sure the devices are added to the SmartgridOne Controller.

3. Add the API external signal​

Image 1
Image 1
Image 1
Image 1

4. Enter collector token​

Simply enter the SmartgridOne Controller's serial number here, and click submit.

5. Select devices to include​

In this page, you have the option to include/exclude devices for remote control. Ensure to mark all checkboxes of devices you'd like to include.

Image 1

6. Data source was added​

The remote control interface has now been activated on the SmartgridOne Controller. You can now get started to send your commands to the devices.

warning

Don't forget to set a fallback regime on the SmartgridOne Controller! A local control mode needs to be configured besides the external api signals you send. Local control is used as a fallback in case the SmartgridOne Controller loses internet or there are other causes that make that the api signal is not able to reach the SmartgridOne Controller.

Send remote control commands using Python​

Below, there is a Python snippet on how to control solar or battery.

tip

Check out the document Application Guide - Remote Setpoints for a more complete explanation with all the policies.

Required package: pip install eniris

# %% Imports
from eniris import ApiDriver
from eniris.point import Point
from eniris.point.writer import (PointDuplicateFilter, DirectPointToTelemessageWriter)
from eniris.telemessage.writer import PooledTelemessageWriter
from datetime import datetime, timezone

# %% Constants
COMMAND_UNTIL = '2024-04-16T10:26:00+02:00'   # YYYY-MM-DDTHH:MM:SS+00:00
SN = '<REPLACE>'
COMMAND = fields = {'policy': 2, 'powerSetpoint_W': 0.0}  # 0: Default (self-consumption); 2: Follow-setpoint


# %% Start curtailment
curtail_until = datetime.fromisoformat(COMMAND_UNTIL).astimezone(timezone.utc)
print(f'Following command until: {curtail_until}')
apiUsername = "<REPLACE>"
apiPassword = "<REPLACE>"

# Create an API drivers and a point writer with the desired functionality
driver = ApiDriver(apiUsername, apiPassword)
writer = PointDuplicateFilter(
    DirectPointToTelemessageWriter(
        PooledTelemessageWriter(
            authorizationHeaderFunction=driver.accesstoken,
            params={"u": SN},
        )
    )
)
namespace = {'database': 'SGC', 'retentionPolicy': 'rp_one_s'}
tags = {
    "serialNr": SN,
    "nodeId": '<REPLACE>',
}

writer.writePoints([Point(namespace, 'remoteControlSignals', curtail_until, tags, fields)])
writer.flush()
print('Dispatched')

Pay special attention to:

  • The 'COMMAND_UNTIL': This is a timezone-aware timestamp that denotes the end time of your command
  • The 'COMMAND': This should be changed according to which command you would like to execute.
    • E.g.: for batteries, policy 2 with powerSetpoint_W at 1000 will charge the battery at 1 kW.
    • For solar, policy 2 with powerSetpoint_W at 0 will disable solar production.
    • After your command has ended, it will automatically fallback to default control (as configured in the SmartgridOne Controller).
    • (more advanced policies are supported, but not yet added to this guide)
  • The 'tags' variable: This should be changed according to SmartgridOne Controller SN, where nodeId should be set to the device ID that was extracted in an earlier step of this tutorial.
tip

Check out the document Application Guide - Remote Setpoints for a more complete explanation with all the policies.