A fully open source, CSIP-Aus compliant utility server initially developed by the Battery Storage and Grid Integration Program at the Australian National University. Implements the following standards:

• 2030.5: Smart Energy Profile (2030.5-2018)
• CSIP: Common Smart Inverter Profile
• CSIP-Aus: Common Smart Inverter Profile (Australia)

It's a docker containerised fastapi server, backed by postgresql for interacting with "smart devices" implementing the CSIP-AUS standard.

All client model definitions for this server can be found in envoy-schema project (a dependency of envoy)

envoy has a full demo server for quickly evaluating its capabilities. See the demo/ directory for more info

To install envoy for local development, clone this repository and then run:

pip install -e .[dev,test]

To ensure everything is setup correctly, tests can be run with:

pytest

envoy uses the following linting/formatting tools:

• black
• flake8
• mypy
• bandit

Contributions via a pull request are welcome but will be validated using the above tools.

Top level directories define multiple apps that use a common codebase/shared models.

• demo/: A fully containerised demonstration of all services in this project
• src/envoy/: root package directory
• src/envoy/admin/: Used for internal API endpoints for administering the server/injecting calculated entities
• src/envoy/server/: primary implementation of the public API's - eg 2030.5 etc
• src/envoy/notification : Used for handling all notification server tasks/workers for supporting 2030.5 pub/sub
• tests/: root tests directory

docstrings on __init__.py should describe the structure in greater detail

Envoy has a number of configuration settings that turn on/off optional functionality. It should run fine out of the box but the below table will detail the additional options.

Typically settings are set by setting an environment variable with the same name (case insensitive).

Common Settings

Additional Utility Server Settings (server)

Additional Admin Server Settings (admin)

Envoy can be run in a Azure tenant on a VM with a managed identity where this identity can be used to validate incoming/outgoing connections in addition to the normal 2030.5 cert auth.

Enabling this auth will ensure that all incoming requests must include an Authorization: bearer <AzureADToken> header in addition to the "normal" auth headers. This token will be validated against the configured Azure AD tenant/client/issuer.

To enable - set the config for azure_ad_tenant_id/azure_ad_client_id/azure_ad_valid_issuer

If updating any of the crud models - you will need to update the alembic migrations:

1. Ensure any new models are being imported at src/envoy/server/model/__init__.py (this is where the alembic env.py imports all models)
2. Create updated migration:

cd src/envoy/server
alembic revision --autogenerate -m "MY_SUMMARY_OF_CHANGES"

3. Check the newly created migration file in src/envoy/server/alembic/versions (make sure it has what you've changed)

To run Envoy locally as a development environment you'll need to setup a local postgresql database and python. This guide will assume that you have python 3.10+ and postgresql 14+ installed.

1. Install dependencies for main server + tests

pip install -e .[test,dev]

2. Create an "envoy" database

sudo -u postgres psql
postgres=# create database envoydb;
postgres=# create user envoyuser with encrypted password 'mypass';
postgres=# grant all privileges on database envoydb to envoyuser;

Note: for postgres>=15, create privileges on the public schema are no longer created by default. To enable table creation with the envoyuser, grant ownership of the database (local development only)

postgres=# ALTER DATABASE envoydb OWNER TO envoyuser;

3. Create .env file

Envoy is is dependent on a number of environment variables (see the section on settings above). For a minimal local installation, you'll want to set the following:

We recommend adding these to a .env file in the root directory so that they are accessible by both fastapi and docker.

4. Apply alembic migrations to the database schema

ln -s $PWD/.env $PWD/src/envoy/server/.env
cd src/envoy/server/
alembic upgrade head
cd -

5. You may want to put some aggregators along with their associated lFDIs into the database created in Step 3. We can use the base config from the testing environment for this purpose:

sudo -u postgres psql -d envoydb -a -f tests/data/sql/base_config.sql

The Postman collection in postman/envoy.postman_collection.json uses certificate 1 (tests/data/certificates/certificate1.py) to make its requests and will require the database to be populated with this base config.

6. (Optional) Start notification server worker

The notification server will require workers to handle executing the async tasks. This is handled by taskiq and a worker can be initialised with:

taskiq worker envoy.notification.main:broker envoy.notification.task

7. Start server

uvicorn envoy.server.main:app --host 0.0.0.0 --reload