Metadata-Version: 2.1
Name: conems
Version: 1.2.0+a5b28903
Summary: Consolinno Energy Managment System interfacing with nymea
Home-page: UNKNOWN
Author: Leonhard Heizinger
Author-email: l.heizinger@consolinno.de
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# ConEMS
`ConEMS` is a prototype version of an Energy Management System (EMS) interfacing with
nymea via JSONRPC. Its goal is to apply an optimized schedule for heating and EV
charging to maximize the utilization of a solar power system.

## Working principle
`ConEMS` connects with a running `nymea:core` daemon using a websocket connection,
usually over port 4444.
In its current state it is designed to work with data provided by the Consolinno Energy
Plugin for nymea.
For example it uses the heating configuration defined by the energy plugin in `nymea`.
This includes parameters like the id of the selected heatpump, house type, etc.
After syncing relevant data with nymea, `ConEMS` uses the Consolinno [`HEMS Optimizer`](https://lash-upstage.services.consolinno.de/docs)
backend and generates a control schedule for the upcoming 24 hours. The schedule is
applied by regulary updating and syncing with `nymea`. For example, the SG Ready state
of the heatpump will be set according to the generated schedule. The schedule will be
refreshed after a given time, for example each 30 minutes.

## Installation
### Requirements
`ConEMS` requires [`pymea`](https://gitlab.consolinno-it.de/leafletfirmware/pymea) which
provides the Python `JSONRPC` bindings to communicate with `nymea:core`. Clone it and
install it using `pip`:
```bash
cd ~ 
git clone git@gitlab.consolinno-it.de:leafletfirmware/pymea.git
cd pymea
sudo pip install .
```
All other dependencies can be installed by using the `requirements.txt` file and  `pip`:
```bash
cd ~ 
git clone git@gitlab.consolinno-it.de:leafletfirmware/conems.git
cd conems
sudo pip install -r requirements.txt
```

### Install using pip
In the cloned `ConEMS` project use `pip` to install:
```bash
cd ~/conems
sudo pip install .
```

### Install using setup.py for development
By using this method the system-wide installation is not copied but linked to the cloned
project. Modifications will be available immediately system-wide. This means there is no
need to reinstall the package using pip after each development step.
```bash
sudo python setup.py develop 
```

### Install to a leaflet using setup.py for development
```bash
./dev_scripts/upload.sh root@1u0022-co-1234.local
```

### Create configuration files
`ConEMS` uses two config files `conems.conf` and `conems_devices.conf`. `ConEMS` will
look for these files in `/etc/conems/` and `~/.conems/` Example files can be found in
this project in the directory `misc`. You have to copy them to the according directory.
Right now the only necessary changes you have to make in the config files is adding
username and password for nymea and the `HEMS Optimizer` endpoint.

## Usage
You can run `ConEMS` using the following command.
```bash
conemsd -n
```
or...
```bash
conemsd -n -d -H localhost -P 4445
```
A `systemd` unit setup is WIP. 

## Development

A starting point for changelog updates can be generated using (here for the 2 newest
commits):

```bash
version=`head debian/changelog -n 1 | grep 'conems \((.+?\))' -Po`
header=`echo $version buster focal jammy UNRELEASED\; urgency=medium`
git log -n 2 --pretty="$header%n%n  * %s%n%n -- %an <%ae> %aD%n" | cat
```

## Tests and Quality

```bash
pip install pytest black pylint mypy --upgrade

# Fix all of those:
pylint -E src test
mypy src test
pytest test --cov=src/conems

# Does reasonable formatting automatically for you:
black .

# Fix as much as you can:
pylint src test
```

## Logging Codes

Error and warning codes in logs help with quick issue identification. The `LOGGING_CODES.md` file 
documents all codes used in the codebase.

```bash
# Generate/update the logging codes documentation
python dev_scripts/generate_logging_codes.py

# Check if documentation is up to date (used in CI)
python dev_scripts/check_logging_codes.py
```
## Docu

### LimitTier

![UML Diagram](docs/architectur_limittier.png)

