Getting Started¶

ecoControl is based on open-source tools and frameworks such as Django and PostgreSQL which makes it easy to deploy. In order to be able to start ecoControl, all requirements need to be installed and a server needs to be configured.

REST API Documentation¶

The ecoControl server communicates through a REST-API only.

/api

GET /api HTTP/1.1

{

}

/api/export

POST /api/export

curl

Models¶

class Configuration(*args, **kwargs)[source]¶

Configuration(id, key, value, value_type, unit, internal)

BOOL = 4¶

DATE = 3¶

exception DoesNotExist¶

Configuration.FLOAT = 2¶

Configuration.INT = 1¶

exception Configuration.MultipleObjectsReturned¶

Configuration.STR = 0¶

Configuration.TYPES = ((0, 'str'), (1, 'int'), (2, 'float'), (3, 'date'), (4, 'bool'))¶

Configuration.get_value_type_display(*moreargs, **morekwargs)¶

Configuration.objects = <django.db.models.manager.Manager object at 0x7ffec804db50>¶

class Device(*args, **kwargs)[source]¶

Device(id, name, device_type)

CU = 2¶

DEVICE_TYPES = ((0, 'HeatStorage'), (1, 'PowerMeter'), (2, 'CogenerationUnit'), (3, 'PeakLoadBoiler'), (4, 'ThermalConsumer'), (5, 'ElectricalConsumer'))¶

exception DoesNotExist¶

Device.EC = 5¶

Device.HS = 0¶

exception Device.MultipleObjectsReturned¶

Device.PLB = 3¶

Device.PM = 1¶

Device.TC = 4¶

Device.deviceconfiguration_set¶

Device.get_device_type_display(*moreargs, **morekwargs)¶

Device.objects = <django.db.models.manager.Manager object at 0x7ffec804d6d0>¶

Device.sensor_set¶

class DeviceConfiguration(*args, **kwargs)[source]¶

Does not inherit from Configuration because of bulk creation

BOOL = 4¶

DATE = 3¶

exception DoesNotExist¶

DeviceConfiguration.FLOAT = 2¶

DeviceConfiguration.INT = 1¶

exception DeviceConfiguration.MultipleObjectsReturned¶

DeviceConfiguration.STR = 0¶

DeviceConfiguration.TYPES = ((0, 'str'), (1, 'int'), (2, 'float'), (3, 'date'), (4, 'bool'))¶

DeviceConfiguration.device¶

DeviceConfiguration.get_value_type_display(*moreargs, **morekwargs)¶

DeviceConfiguration.objects = <django.db.models.manager.Manager object at 0x7ffec8060150>¶

class Notification(*args, **kwargs)[source]¶

Notification(id, threshold_id, sensor_value_id, target, read)

exception DoesNotExist¶

exception Notification.MultipleObjectsReturned¶

Notification.objects = <django.db.models.manager.Manager object at 0x7ffec7ffaf90>¶

Notification.sensor_value¶

Notification.threshold¶

class RealWeatherValue(*args, **kwargs)[source]¶

RealWeatherValue(id, temperature, timestamp)

exception DoesNotExist¶

exception RealWeatherValue.MultipleObjectsReturned¶

RealWeatherValue.get_next_by_timestamp(*moreargs, **morekwargs)¶

RealWeatherValue.get_previous_by_timestamp(*moreargs, **morekwargs)¶

RealWeatherValue.objects = <django.db.models.manager.Manager object at 0x7ffec806b310>¶

class Sensor(*args, **kwargs)[source]¶

Sensor(id, device_id, name, key, setter, unit, in_diagram, aggregate_sum, aggregate_avg)

exception DoesNotExist¶

exception Sensor.MultipleObjectsReturned¶

Sensor.device¶

Sensor.objects = <django.db.models.manager.Manager object at 0x7ffec8060790>¶

Sensor.sensorvalue_set¶

Sensor.sensorvaluedaily_set¶

Sensor.sensorvaluehourly_set¶

Sensor.sensorvaluemonthlyavg_set¶

Sensor.sensorvaluemonthlysum_set¶

Sensor.threshold_set¶

class SensorValue(*args, **kwargs)[source]¶

SensorValue(id, sensor_id, value, timestamp)

exception DoesNotExist¶

exception SensorValue.MultipleObjectsReturned¶

SensorValue.get_next_by_timestamp(*moreargs, **morekwargs)¶

SensorValue.get_previous_by_timestamp(*moreargs, **morekwargs)¶

SensorValue.notification_set¶

SensorValue.objects = <django.db.models.manager.Manager object at 0x7ffec8060c10>¶

SensorValue.sensor¶

class SensorValueDaily(*args, **kwargs)[source]¶

SensorValueDaily(id, sensor_id, timestamp, value)

exception DoesNotExist¶

exception SensorValueDaily.MultipleObjectsReturned¶

SensorValueDaily.get_next_by_timestamp(*moreargs, **morekwargs)¶

SensorValueDaily.get_previous_by_timestamp(*moreargs, **morekwargs)¶

SensorValueDaily.objects = <django.db.models.manager.Manager object at 0x7ffec806bbd0>¶

SensorValueDaily.sensor¶

class SensorValueHourly(*args, **kwargs)[source]¶

SensorValueHourly(id, sensor_id, timestamp, value)

exception DoesNotExist¶

exception SensorValueHourly.MultipleObjectsReturned¶

SensorValueHourly.get_next_by_timestamp(*moreargs, **morekwargs)¶

SensorValueHourly.get_previous_by_timestamp(*moreargs, **morekwargs)¶

SensorValueHourly.objects = <django.db.models.manager.Manager object at 0x7ffec806b790>¶

SensorValueHourly.sensor¶

class SensorValueMonthlyAvg(*args, **kwargs)[source]¶

SensorValueMonthlyAvg(id, sensor_id, timestamp, avg)

exception DoesNotExist¶

exception SensorValueMonthlyAvg.MultipleObjectsReturned¶

SensorValueMonthlyAvg.get_next_by_timestamp(*moreargs, **morekwargs)¶

SensorValueMonthlyAvg.get_previous_by_timestamp(*moreargs, **morekwargs)¶

SensorValueMonthlyAvg.objects = <django.db.models.manager.Manager object at 0x7ffec7ffa510>¶

SensorValueMonthlyAvg.sensor¶

class SensorValueMonthlySum(*args, **kwargs)[source]¶

SensorValueMonthlySum(id, sensor_id, timestamp, sum)

exception DoesNotExist¶

exception SensorValueMonthlySum.MultipleObjectsReturned¶

SensorValueMonthlySum.get_next_by_timestamp(*moreargs, **morekwargs)¶

SensorValueMonthlySum.get_previous_by_timestamp(*moreargs, **morekwargs)¶

SensorValueMonthlySum.objects = <django.db.models.manager.Manager object at 0x7ffec7ffa090>¶

SensorValueMonthlySum.sensor¶

class Threshold(*args, **kwargs)[source]¶

Threshold(id, sensor_id, name, category, show_manager, min_value, max_value)

Danger = 5¶

Default = 0¶

exception DoesNotExist¶

Threshold.Info = 3¶

exception Threshold.MultipleObjectsReturned¶

Threshold.Primary = 1¶

Threshold.Success = 2¶

Threshold.TYPES = ((0, 'Default'), (1, 'Primary'), (2, 'Success'), (3, 'Info'), (4, 'Warning'), (5, 'Danger'))¶

Threshold.Warning = 4¶

Threshold.get_category_display(*moreargs, **morekwargs)¶

Threshold.notification_set¶

Threshold.objects = <django.db.models.manager.Manager object at 0x7ffec7ffaa50>¶

Threshold.sensor¶

class WeatherValue(*args, **kwargs)[source]¶

WeatherValue(id, temperature, timestamp, target_time)

exception DoesNotExist¶

exception WeatherValue.MultipleObjectsReturned¶

WeatherValue.get_next_by_target_time(*moreargs, **morekwargs)¶

WeatherValue.get_next_by_timestamp(*moreargs, **morekwargs)¶

WeatherValue.get_previous_by_target_time(*moreargs, **morekwargs)¶

WeatherValue.get_previous_by_timestamp(*moreargs, **morekwargs)¶

WeatherValue.objects = <django.db.models.manager.Manager object at 0x7ffec8060fd0>¶

Devices¶

This module represents the energy systems.

The hardware interface should orient at the base classes of the devices. The simulation in server.forecasting.systems is also based on these classes.

class BaseDevice(device_id, env)[source]¶

Represents a general interface to the energy-systems.

class BaseEnvironment(initial_time=None, step_size=120, demomode=False, forecast=False)[source]¶

This class manages the environment of the devices holds the simulated time as well as the mode, the devices are running in. All connected devices share one BaseEnvironment

demo_mode = None¶

↓ forecast | demo_mode →	True	False
True	forecast of simulated devices	forecast of real devices
False	demo simulation	real device (env not defined)

forecast = None¶

see demo_mode

get_day_of_year()[source]¶

Returns an int value of the current simulated day of the year

initial_date = None¶

a unix timestamp representing the start of simulation if initial_time is None the current time is used

is_demo_simulation()[source]¶

Returns, if this is the demo_simulation

step_size = None¶

int value of seconds how often the simulated devices calculate their state

class CogenerationUnit(device_id, env)[source]¶

Represents a basic interface to a cogeneration unit. The configuration is read from the database and can be set from the frontend. The following parameters are available:

Parameters:

max_gas_input (float) – in kW thermal_efficiency (float) – in percent between 0 and 1 calculated by the maximal thermal power and gas input electrical_efficiency (float) – in percent between 0 and 1 calculated by the maximal electrical power and gas input minimal_workload (float) – in percent between 0 and 1 used for modulation minimal_off_time (float) – minimal time between to power-ons in seconds purchase_price (float) – in Euro purchase_date (date) – to calculate armotization maintenance_interval_hours (int) – operating hours until maintenance is necessary maintenance_interval_powerons (int) – maximal power-ons until maintenance is necessary

connected()[source]¶

The device needs a PowerMeter and a HeatStorage to operate properly.

current_electrical_production = None¶

kW

current_gas_consumption = None¶

kW

current_thermal_production = None¶

kWh

gas_costs = None¶

default 0.0655 Euro per kWh

get_operating_costs()[source]¶

Calculated by the consumed gas and maintenance costs (0.05 Euro per electric produced kWh).

total_electrical_production = None¶

kWh

total_gas_consumption = None¶

kWh

total_thermal_production = None¶

kWh

workload(workload=None)[source]¶

Getter and setter for the workload.

Parameters:	workload (float) – between 0-100, if None nothing is set
Returns:	current workload in percent [0,100]

class PeakLoadBoiler(device_id, env)[source]¶

Represents a basic interface to a cogeneration unit. The configuration is read from the database and can be set from the frontend. The following parameters are available:

Parameters:	max_gas_input (float) – in kW thermal_efficiency (float) – in percent between 0 and 1 calculated by the maximal thermal power and gas input

connected()[source]¶

The device needs a HeatStorage to operate properly.

current_gas_consumption = None¶

kW

current_thermal_production = None¶

kWh

gas_costs = None¶

default 0.0655 Euro

get_operating_costs()[source]¶

Calculated by the consumed gas.

total_gas_consumption = None¶

kWh

total_thermal_production = None¶

kWh

workload_percent(workload=None)[source]¶

Getter and setter for the workload.

Parameters:	workload (float) – between 0-100, if None nothing is set
Returns:	current workload in [0,100]

class CogenerationUnit(device_id, env)[source]

Represents a basic interface to a cogeneration unit. The configuration is read from the database and can be set from the frontend. The following parameters are available:

Parameters:

max_gas_input (float) – in kW thermal_efficiency (float) – in percent between 0 and 1 calculated by the maximal thermal power and gas input electrical_efficiency (float) – in percent between 0 and 1 calculated by the maximal electrical power and gas input minimal_workload (float) – in percent between 0 and 1 used for modulation minimal_off_time (float) – minimal time between to power-ons in seconds purchase_price (float) – in Euro purchase_date (date) – to calculate armotization maintenance_interval_hours (int) – operating hours until maintenance is necessary maintenance_interval_powerons (int) – maximal power-ons until maintenance is necessary

connected()[source]

The device needs a PowerMeter and a HeatStorage to operate properly.

current_electrical_production = None

kW

current_gas_consumption = None

kW

current_thermal_production = None

kWh

gas_costs = None

default 0.0655 Euro per kWh

get_operating_costs()[source]

Calculated by the consumed gas and maintenance costs (0.05 Euro per electric produced kWh).

total_electrical_production = None

kWh

total_gas_consumption = None

kWh

total_thermal_production = None

kWh

workload(workload=None)[source]

Getter and setter for the workload.

Parameters:	workload (float) – between 0-100, if None nothing is set
Returns:	current workload in percent [0,100]

class PeakLoadBoiler(device_id, env)[source]

Represents a basic interface to a cogeneration unit. The configuration is read from the database and can be set from the frontend. The following parameters are available:

Parameters:	max_gas_input (float) – in kW thermal_efficiency (float) – in percent between 0 and 1 calculated by the maximal thermal power and gas input

connected()[source]

The device needs a HeatStorage to operate properly.

current_gas_consumption = None

kW

current_thermal_production = None

kWh

gas_costs = None

default 0.0655 Euro

get_operating_costs()[source]

Calculated by the consumed gas.

total_gas_consumption = None

kWh

total_thermal_production = None

kWh

workload_percent(workload=None)[source]

Getter and setter for the workload.

Parameters:	workload (float) – between 0-100, if None nothing is set
Returns:	current workload in [0,100]

class ThermalConsumer(device_id, env)[source]¶

This class represents the thermal consume of the house. The demand is calculated by the necessary heating power and the required warm water. The house parameters are read from the database and can be set from the frontend. The following parameters are available:

Parameters:

apartments (int) – number of apartments in the house avg_rooms_per_apartment (int) – average number of rooms avg_windows_per_room (int) – average number of windows type_of_windows (int) – isolation value between MISSING total_living_area (int) – in square meters type_of_housing (int) – isolation value between MISSING residents (int) – type_of_residents (int) – used to classify thermal demand MISSING RANGE target_temperature (int) – requested temperature of the rooms in degree Celsius avg_thermal_consumption (int) – in kWh

connected()[source]¶

The device needs a HeatStorage to operate properly.

daily_demand = None¶

list of 24 values representing target_temperature per hour

room_height = None¶

constant room height

temperature_warmwater = None¶

temperature of warm water 40 degrees Celsius by default

class ElectricalConsumer(device_id, env)[source]¶

This class represents the electrical consume of the house. The demand is calculated by the forecasting in :mod:server.forecasting.forecasting The house parameters are read from the database and can be set from the frontend. The following parameters are available:

Parameters:	apartments (int) – number of apartments in the house residents (int) – type_of_residents (int) – used to classify thermal demand MISSING RANGE avg_electrical_consumption (int) – in kWh

connected()[source]¶

The device needs a PowerMeter to operate properly.

class HeatStorage(device_id, env)[source]¶

Represents a heat storage necessary to supply heating and warm water demand. The temperatures of the storage are as average and measured in degree Celsius. The configuration is read from the database and can be set from the frontend. The following parameters are available:

Parameters:	capacity (int) – in liters min_temperature (float) – below this temperature the PeakLoadBoiler will turn on target_temperature (float) – the HS schould always have this temperature critical_temperature (float) – above this temperature all production devices are turned off

base_temperature = None¶

assume no lower temperature

specific_heat_capacity = None¶

specific heat capacity of water 4.19 J/(g*K)

class PowerMeter(device_id, env)[source]¶

Represents the power meter of the whole building. Measures the purchased and fed in electricity in kWh

add_energy(energy)[source]¶

This counts up the produced energy.

Parameters:	energy (float) – in kWh

consume_energy(energy)[source]¶

This counts up the consumed energy.

Parameters:	energy (float) – in kWh

electrical_costs = None¶

costs in Euro to purchase 1 kW/h from external supplier (default 0.283)

energy_consumed = None¶

set by consumer devices with consume_energy

energy_produced = None¶

set by producer devices with add_energy

fed_in_electricity = None¶

since last step

feed_in_reward = None¶

reward in Euro for feed in 1 kW/h to public grid (default 0.0917)

get_costs()[source]¶

Calculated by overall purchased electricity and default costs of 0.283 Euro per kWh

get_reward()[source]¶

Calculated by overall fed in electricity and the default reward of 0.0917 Euro per kWh. Sale to tenants is not considered here.

purchased = None¶

since last step

get_initialized_scenario()[source]¶

The function returns a list of energy systems based on the configuration in the database

Returns:	list of objects from server.forecasting.systems

get_user_function(devices, code=None)[source]¶

Builds a method with the users code from the programming-interface.

Parameters:	systems – list of devices from :func:get_initialized_scenario: code – string with the user-code
Returns:	callable user-function expecting a pointer to a systems list as argument

perform_configuration(data)[source]¶

Saves a systems configuration to the database.

Parameters:	data – json with configuration values for energy systems

Forecasting¶

This package contains the simulation and methods for creating forecasts. They are split into statistical forecasts and weather forecast.

Auto-Optimization¶

This module contains the algorithm for optimizing the costs of energy systems.

DEFAULT_FORECAST_INTERVAL = 3600.0¶

The interval for how long one auto_optimize will forecast and for how long one specific workload is set. Note, that this constant also represents a compromise: Shorter intervals can adjust to quick changes, f.e. electricity demands changes, while longer intervals can incorporate more forecasts, but wont be able to adjust quickly. The interval of one hour lead to good results in our tests.

auto_optimize(forecast)[source]¶

Tries to optimize the cost and sets the cu.overwrite_workload

The method forecasts from env.now with different cu workloads and finds the one with the lowest cost. The length of the forecast is DEFAULT_FORECAST_INTERVAL.

Parameters:	forecast – the forecast to be optimized

find_optimal_config(initial_time, forecast)[source]¶

Internal Method Main method, which optimizes the costs by running a global approximation for the best configuration and then running a local minimization method on this approximation

estimate_cost(params, *args)[source]¶

Internal Method copies the devices and environment, forwards it and returns the costs.

Parameters:	params (list) – parameter to be optimized (CU.workload for now) args – (initial_time, forecast, prices, rewards)

simplified_forecast(env, initial_time, devices)[source]¶

runs the forward loop only executing the step function

total_costs(devices, prices, rewards)[source]¶

Internal Method Returns the cost of a forecast run. The function uses the prices which are stored in the db deviceconfiguration. It is also constrained by boundaries, f.e. the heatstorage should never go below min temperature.

Parameters:	devices – The devices after the forecast prices, rewards (dict) – Cached prices and rewards

class BilanceResult(cost, params)[source]¶

wrapper for storing a optimization result

Front End¶

The front end has been developed independently from the ecoControl server and communicates exclusively through the REST-API. It is based on jQuery and Twitter’s Bootstrap which provides an easy to use grid system and enables a responsive design. For all diagrams, the front end is using Highcharts and Highstock. The programming interface is based on Ace.