First Steps

This guide walks you through the first steps of using the FlexConnect API:

1. Receive instructions via email.
2. Download the development client.
3. Prepare the API credentials file.
4. Control a battery:
   • Obtain the battery state.
   • Obtain the battery control state.
   • Modify the battery control state.

Instructions via Email

Email with Instructions

The FlexHome․Energy cloud team sends you an email containing:

• This guide as a PDF.
• A link to download the FlexConnect — FlexCloudClient API.
• The identifiers of your batteries, which you use to control them.

Email with API Credentials

The FlexHome․Energy cloud team sends you a second email containing values for:

• AWS_ACCESS_KEY
• AWS_SECRET_ACCESS_KEY
• AWS_AUTH_ID

INFO

These values are required for authentication on the FlexCloud platform and must be specified in the .env file of the development client.

Download the Development Client

The development client provides a local HTTP interface for accessing the FlexCloud platform. It is distributed as an executable file for Windows, Linux, and macOS.

1. Create a new folder.
2. Use the link provided in the instructions email to download the software.
3. Save the software to the new folder.

Prepare the API Credentials File

1. Navigate to the folder containing the development client.
2. Create a new text file in that folder.
3. Paste the following content into the file:

# ===== AWS Connection =====
AWS_REGION=eu-central-1
AWS_IOT_ENDPOINT=a81witq9oqwz4-ats.iot.eu-central-1.amazonaws.com
# --- AWS Credentials ---
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_AUTH_ID=

# ===== Settings =====
PORT=8080
HOSTNAME=0.0.0.0

4. Use the values provided in the credentials email for:
   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • AWS_AUTH_ID
5. Save the file as .env.

View and Control a Battery

Launch and View the Development Client

1. Run the development client. It reads the .env file and connects to the FlexCloud platform.

   

2. Open a browser window and navigate to http://localhost:8080. The view shows a number of URIs:

   URI	Description	HTTP Method
   /	The directory list	GET
   /version	The version of the development client	GET
   /doc	Machine-readable JSON documentation	GET
   /swagger	Documentation in the Swagger type	GET
   /scalar	Documentation in the Scalar type	GET
   /ui	Link to /scalar	GET
   /app/v1/*	Requests	POST

   

3. Navigate to the UI at http://localhost:8080/ui:

   • View the available endpoints on the top left.
   • Change the language on the right in Client Libraries to change the examples to different programming languages.
   • Use the built-in functionality to try out the first examples — click Test Request.

   

View the Battery State

Run the BatteryStateRequest using the JSON body below.

1. Run the request on app/v1/BatteryStateRequest.
2. Replace the value of the stringValue element in the deviceId attribute with the identifier of one of your batteries.
3. Additional values such as the header attributes will be addressed during the integration of your software with the FlexCloud API. Request body

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "deviceId": {
    "type": {
      "id": 2
    },
    "stringValue": "90D2A30FA3D2AD48525CD255F469C167ECF8292C"
  }
}

Response body

{
  "header": {
    "reqId": 1234
  },
  "state": {
    "stateOfCharge": {
      "number": 34,
      "scale": 0
    },
    "stateOfHealth": {
      "number": 100,
      "scale": 0
    },
    "stateOfEnergy": {
      "number": 680,
      "scale": 0
    },
    "usableCapacity": {
      "number": 2000,
      "scale": 0
    },
    "stateOfOperation": 1
  }
}

The response attribute state contains the following elements:

Element	Description
stateOfCharge	Current state of charge in percent of the "battery usable capacity".
stateOfHealth	Current state of health in percent of the "battery capacity nominal max".
stateOfEnergy	Remaining energy of the battery in Wh.
usableCapacity	Usable part of the capacity of the battery in Wh.
stateOfOperation	The battery operation state. One of: 1 normal, 2 standby, 3 temporarily not ready, 4 off, 5 failure.

View the Battery Control

Run the BatteryControlRequest using the JSON body below.

1. Run the request on app/v1/BatteryControlRequest.
2. Replace the value of the stringValue element in the deviceId attribute with the identifier of one of your batteries. Request body

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "deviceId": {
    "type": {
      "id": 2
    },
    "stringValue": "90D2A30FA3D2AD48525CD255F469C167ECF8292C"
  }
}

Response body

{
  "header": {
    "reqId": 1234
  },
  "currentControlInstructions": {
    "controlState": 2,
    "controlMode": 1,
    "setpointPower": {
      "number": 0,
      "scale": 0
    },
    "timestamp": 1770819628078
  },
  "desiredControlInstructions": {
    "controlMode": 1,
    "setpointPower": {
      "number": 0,
      "scale": 0
    },
    "timestamp": 1770819595253
  }
}

• currentControlInstructions represents the current state of control.
• desiredControlInstructions represents the state of control that is supposed to be set.

controlState values

Value	Code	Description
1	INIT	The battery is in the initialisation state during startup.
2	POWER	The battery is in the "power" control state.
3	PCC	The battery is in the PCC ("Point of Common Coupling") control state.
4	AUTO_CONTROLLED	The battery is in the auto-controlled state. The power envelope defines the constraints for the current time.
5	AUTO_UNCONTROLLED	The battery is in the auto-uncontrolled state. The power envelope is not defined for the current time.
6	FAILSAFE	The battery is in the failsafe state.

controlMode values

Value	Code	Description
1	POWER	Battery power control mode. The battery power values are controlled by the power setpoint directly.
2	PCC	Battery PCC ("Point of Common Coupling") control mode. The battery power values are calculated by the power setpoint in reference to the measured values of the assigned meter at the PCC.
3	AUTO	Battery auto-controlled mode. The battery power values are calculated by the power setpoint in reference to measured values of the assigned meter at the PCC, taking into account the constraints of the power envelope.

setpointPower

The setpointPower element specifies the current power value in watts.

The value is represented as a scaled number — a number with a scale, where the scale is the exponent of 10. The actual value equals number × 10^scale.

• Positive values represent a charging operation of the battery.
• Negative values represent a discharging operation of the battery.

Modify the Battery Control

Run the BatteryControlModifyRequest using the JSON body below.

Command latency

Commands may take up to a minute to be executed after the request has been processed. The successful application can be viewed in the currentControlInstructions element of BatteryControlRequest.

1. Run the request on app/v1/BatteryControlModifyRequest.
2. Replace the value of the stringValue element in the deviceId attribute with the identifier of one of your batteries. Request body

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "deviceId": {
    "type": {
      "id": 2
    },
    "stringValue": "90D2A30FA3D2AD48525CD255F469C167ECF8292C"
  },
  "controlMode": 1,
  "setpointPower": {
    "number": 0,
    "scale": 0
  }
}

• For controlMode values, see controlMode values above.
• For setpointPower, see setpointPower above.
  • Positive values represent a charging operation of the battery.
  • Negative values represent a discharging operation of the battery. Response body

{
  "header": {
    "reqId": 1234
  }
}

Success

An empty response represents a successful operation.