Create and Deploy the Building Service via APIv1

This example shows creating and deploying a service via the EnergyView API version 1.

For details about the API, see the online API documentation.

Outline

Create a Control Node
Create several Climate Sensor Nodes
Deply the service on the Control Node
Update the service
Summary

You are going to need to have an API key to be able to interact with the API. You can create an API key in the EnergyView web interface if you have enough privileges. You need to contact your system administrator if you do not have enough privileges.

Each request is performed against https://customer.noda.se/{domain}/api/v1/... where {domain} is the domain name of your EnergyView instance. A customer may have several domains, and a separate database manages each domain. This item is sometimes also referred to as "site".

Step 1: Create a Control Node

The first step is to create a Control Node. This is the Node that will act as a representation of a single heating or cooling system. It will contain all the settings and data required for the algorithms to work.

The Control Node is created by sending a POST request to the /{domain}/api/v1/nodes endpoint.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "uuid": "12345678-1234-1234-1234-123456789012",
  "name": "My Control Node",
  "designation": "building",
  "description": "My Control Node for my building",
  "dataif": "optional string used as an identifier",
  "tags": [
    "operational_state",
    "outdoortemp",
    "outdoortemp_fake",
    "outdoortemp_offset",
    "returntemp_sec",
    "supplytemp_sec",
    "supplytemp_sec_controller_setvalue",
    "supplytemp_sec_offset",
    "meter_effect",
    "meter_heatenergy",
    "meter_primreturntemp",
    "meter_primsupplytemp",
    "meter_volume",
    "meter_volumeflow",
  ],
  "device": "ControlNode",
  "state": "pre-installation"
}

Table of the fields in the request body:

Field	Description
uuid	(optional) The requested UUID of the Node. If not specified, a random UUID will be generated. This can be used to assign a specific UUID to a Node.
name	The name of the Node.
designation	The designation of the Node. If the Node is a building, a heating system, an indoor climate sensor, etc.
description	A description of the Node.
dataif	An optional string that can be used as a secondary way to identify the Node.
tags	A list of tags that can be used to identify the Node. This is the complete list of sensors we want to enable on the Node. The system manages a fixed list of tags for different devices.
device	The device type of the Node.
state	The state of the Node.

The response will be a 201 Created, and the response body will contain the created Node's serial ID and UUID.

{
  "id": 123,
  "uuid": "12345678-1234-1234-1234-123456789012"
}

Keep the serial ID or UUID of the created Node, as they will be used in the next step.

Step 2: Create Climate Sensor Nodes

The next step is to create Climate Sensor Nodes. These are the nodes that will act as a representation of a single indoor climate sensor. Each Climate Sensor Node will be associated with a Control Node.

The Climate Sensor Nodes are created individually by sending a POST request to the /{domain}/api/v1/nodes endpoint.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "uuid": "cafe1234-cafe-cafe-cafe-cafe12345678",
  "name": "My Climate Sensor Node #1",
  "designation": "sensor/indoor",
  "description": "One of several climate sensors",
  "dataif": "optional string used as an identifier",
  "tags": [
    "indoortemp"
  ],
  "parent": "12345678-1234-1234-1234-123456789012",
  "device": "Generic Indoor Sensor",
  "state": "pre-installation"
}

The description of the fields in the request body is the same as for the Control Node. With one exception, the parent is a required field that specifies the serial ID or UUID of the Control Node that the Climate Sensor Node should be associated with.

The response will be a 201 Created, and the response body will contain the created Node's serial ID and UUID.

{
  "id": 124,
  "uuid": "cafe1234-cafe-cafe-cafe-cafe12345678"
}

Repeat the process for each Climate Sensor Node you want to create.

Step 3: Deploy the Service

The last step is to deploy the service on the Control Node. This will enable the algorithms to start running.

The service is deployed by sending a POST request to the /{domain}/api/v1/nodes/{id}/provision endpoint, where {id} is the serial ID of the Control Node.

The format of the request body is JSON, and the following is an example of a valid request body:

{
  "active": true,
  "balance_temperature": 17,
  "idt_wanted": 21,
  "idt_min": 17
}

Table of the fields in the request body:

Field	Description
active	Whether the service should be active or not.
balance_temperature	The balance temperature of the system. This is typically the outdoor temperature after which the pump is turned off.
idt_wanted	The average indoor temperature wanted for the cluster of climate sensors.
idt_min	The minimum allowed indoor temperature on any indoor climate sensor.

The response will be a 204 No Content, and the response body will be empty.

Step 4: Update the Service

A running service can be updated by repeating the same process as in step 3. The service will be updated with the new settings.

Set the active field to false to stop the service.

Summary

You have created a Control Node and Climate Sensor Nodes and deployed the service on the Control Node. The service will start running, and you can send data to the Climate Sensor Nodes via the time series API.

For details about the time series API, look at the API documentation.