This page is a work in progress and anything here may be changed in the future.
The information here is an attempt of documentation driven development and may not be actually implemented in code yet
Balena makes extensive use of Environment and Service variables to manage a fleet of devices.
Environment variables apply to the whole device. Service variables apply just to one service.
Variables can be applied per device or across the whole fleet of devices.
Variables can be set using docker-compose files, through the Balena Cloud web interface or using the python SDK.
Read the Balena Environment Variable Documentation before going further.
The system has a number of different services running in seperate containers - for example - sunspec, huawei, etc.
Some of these services will not be needed by all CoFyBox users and should be specifically enabled.
COFYBOX_ENABLE_SERVICE
Each service can be turned on or off using the correct service variables. Service variables only apply to on a per service level.
A service will run when an environment variable COFYBOX_ENABLE_SERVICE is set to true for that service.
It is not recommended to use this to turn off some 'essential' services in this way: mosquitto, homeassistant, glue, telegraf, configurator and nginx-reverse-proxy. If you wish to be able to turn these off, you will first need to change their restart policies in docker-compose to restart: on-failure.
Environment variables can be altered in the Balena cloud by going to Fleets > Cofybox-production > the device in question > "Device Variables"
Only a suggestion - not implemented
The CoFyBox connects to the CoFyCloud for provisioning. At this stage it downloads a set of configuration variables.
These configuraton variables are applied to the device using the Balena SDK.
The format of the settings payload coming from the API could look something like this:
{
"blocks_enabled": [
{ "cofycloud": true },
{ "homeassistant": true },
{ "mosquitto": true },
{ "wifi-hotspot": true },
{ "telegraf": true },
{ "glue-component": true },
{ "sunspec": false },
]
}
Some services require a complex set of configuration options. The environment variables method is probably not appropriate.
For the current state of development, a configuration yaml file is useful to store configuration settings for each block. The settings format will likely need to change often, so a user friendly interface is not necessary at this point of development.
Instead, a new block - configurator - is used to edit these yaml files.
The block runs a modified version of hass-configurator - a program designed to edit Home Assistant configuration files.
A shared volume called cofybox-config is mounted into all blocks that require settings configuration.
This volume is also mounted into the configurator block.
Configuration .yaml files are stored in this volume. When a block initially starts, it copies a default configuration file into this volume, if one is not already present.
Details of each configuration file should be documented as part of the Services documentation.
To access the configurator interface, go to http://<Address of CoFyBox>/configurator (or http://<IP of CoFyBox>:3218).
When you have finished editing files you must restart the CoFyBox. This can be done with the Balena front end, CLI, ssh connection to the Host OS, or via the Cofycloud. It may be possible to enable this to be done from the configurator interface (HC_HASS_API is currently set to None, so it is not currently possible).
To read about steps towards developing a GUI and other more user-friendly features for editing settings, see Configuration via MQTT