# ¶ Services

Services are what make the CoFyBox useful. They exist as Docker containers, which can run in their own isolated environment, or together in an ensemble as they do in production. Their variety of functions are described on this page. You can view the code for each service in the repository.

Most, but not all, services are written in Python. There is no specific requirement to use Python.

Services can be enabled or disabled as detailed in configuration at runtime.

## ¶ Architecture

## ¶ CoFyBox ecosystem software

This is software that has been developed specifically for use in the CoFyBox.

### ¶ CoFyBoxConfig

This service provides a local web UI to support the installation/commissioning of the cofy-box. It also provides a range of other functionality required for the operation of the CoFyBox including:

- Enables setting things like timezone, language, and community in the UI.
- Creates a CoFyBox device in Home Assistant via MQTT discovery.
- Setting up the networking (mainly the wifi hotspot at the moment).
- Handles provisioning of a CoFyBox to the CoFyCloud.
- Takes posts from the `aggregated_data` MQTT topic and posts these to the CoFyCloud.

### ¶ CoFyCloud API Pull

A service that fetches pricing data from the CoFyCloud, related to the user's energy tariff.

### ¶ Glue

The "glue component" maps MQTT topics and reposts them in the CofyCloud format under the `data` topic, ready for aggregation.

### ¶ Sunspec2MQTT

Takes input from Sunspec devices and posts them to MQTT.

### ¶ debug

A container normally disabled by default which provides debugging capabilities.

### ¶ huawei

A service that interfaces with the Huawei SUN2000 solar inverter and publishes sensor values to MQTT. It detects if the inverter is equipped with a utility meter or a battery. This service runs every minute and only requires the IP of the inverter.

## ¶ Vendored software

This is software that we use which has been primarily/substantially developed by others which is running on the cofy-box and potentially configured/extended by us in various ways.

### ¶ HomeAssistant

Third party component for managing a "Smart Home". Serves as the local UI for users of the Cofybox. We use the official HA docker image and apply a fat configuration specialised to our requirements. See the page for further information.

Docker Hub: https://hub.docker.com/r/homeassistant/home-assistant
Website: https://www.home-assistant.io/

### ¶ mosquitto (MQTT broker)

Mosquitto is a lightweight MQTT 3.1.1/5 broker. We use the official eclipse-mosquitto container image.

Docker Hub: https://hub.docker.com/_/eclipse-mosquitto
Documentation: https://mosquitto.org/documentation/

### ¶ Telegraf

Telegraf is a general purpose telemetry/logging client used to consume a range of input data, transform it, and then output to a range of formats/interfaces. We use it for downsampling data and sending data to InfluxDB (locally or in the cloud).

Docker Hub: https://hub.docker.com/_/telegraf
Documentation: https://docs.influxdata.com/telegraf/v1.20/

### ¶ InfluxDB

InfluxDB is a time-series database. The service runs such a database locally, for storage of information such as energy usage. Preferably, data is sent from the device to InfluxDBCloud, which can be queried remotely and does not require the local database. Thus, this service is only relevant for some installations, such as where the user has chosen not to send their data to the cloud.

Docker Hub: https://hub.docker.com/_/influxdb
Documentation: https://docs.influxdata.com/

### ¶ Nginx Reverse Proxy

Nginx is a reverse proxy and load balancing software. Its latter usage is not implemented in the project; we use its reverse proxy capabilities to route requests to the CoFyBoxes. The container exposes and listens on port 80, then directs requests to the relevant container. As it acts as a web server, Nginx is also useful for the serving of static files.

Docker Hub: https://hub.docker.com/_/nginx
Documentation: https://docs.nginx.com/

## ¶ Data bus and pathways

Data in the Cofybox is, in most cases, moved between components using an MQTT broker. The general path between a device is:

- Device posts data to the MQTT broker running on the Cofybox (either using native MQTT support or with an intermediary such as Sunspec2MQTT)
- The Glue Component will take these inputs and report them in the Cofycloud format, under the `data` topic
- The Telegraf service on the COFYbox will then calculate timed averages of these values and repost them under the `aggregated_data` topic. It may also post the data to InfluxDB, locally or in the cloud.
- The cofybox-config service will take posts from the `aggregated_data` topic and post it to the CofyCloud

# ¶ Legacy or unfinished services

- dynamic2mqtt
- cofycloud
- p1-cookie-parser