OpenMotics Gateway (backend)
This project is the OpenMotics Gateway backend. It provides an API used by the frontend, by the Cloud and by third party applications.
It is the glue between the OpenMotics Master (microcontroller) and the rest of the world.
Running locally
Some parts of the code can be run locally using a dummy master implementation.
Installing NIX
Install NIX by following the instruction on the website https://nixos.org/download.html (use recommended setup)
Installing the requirements
To run localy, the easiest method is via direnv.
sudo apt-get install direnv
Then, add the direnv hooks to your .bashrc in your home (when using bash)
eval "$(direnv hook bash)"
or, when using zsh, add this to .zshrc
eval "$(direnv hook zsh)"
Environment: create .envrc
Next, create the .envrc
file in the gateway root folder which will be used by direnv
dotenv
use nix
layout python python3
This direnv will utilize dotenv to manage the environment, use nix for the python & dependencies (see shell.nix) and will utilize python3 as the default interpreter.
Environment: create .env
The openmotics service loads a config file from $OPENMOTICS_PREFIX/etc
where settings like the platform and ports can be overridden. This means that this environment variable
must be set before starting the service.
Add this to the .env
file in the gateway root folder.
OPENMOTICS_PREFIX=/some/directory/pointing/to/openmotics/gateway
Install requirements
Install the python dependencies the first time:
pip install -r requirements-py3.txt
pip install -e src
Add local fixtures
Copy the configuration/fixture files and generate self-signed certificates:
mkdir -p etc static
cd etc
# copy the example config file, it can be further customized
cp ../example/openmotics.conf .
# Copy the fixtures, they can be further customized
cp ../example/master_fixture.json .
# generate self signed certificate
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout https.key -out https.crt -subj '/CN=om-developer'
in etc/openmotics.conf you will be able to find settings such as ports etc
Dummy master
The local running gateway will use a dummy master. The example master fixtures make a virtual input, relay and 0/1-10V module available for futher configuration.
While it behaves like a Brain(+) master, only a very limited set of features is available. The goal is not to emulate a real device, but give a user at least something to start with. The implemented features:
- Some status calls can be executed (e.g. it will report a version & a time)
- Everything can be configured just as normal (the full configuration space is available)
- It is possible to link an input to an output
- It is possible to turn on/off, toggle & dim outputs
- It is possible to configure group actions. The only supported actions are turning on/off, toggling & dimming outputs
- It is possible to configure an input to execute a group action on press and/or release
The implementation supports a persistent eeprom state (by default only the fixtures will be available when the service is (re)started).
To enable this, add dummy_eeprom_persistence = true
under the OpenMotics
section in openmotics.conf
. When enabled, the configuration
state is stored inside etc/master_eeprom.json
. This is a raw-format file and is not meant for manual manipulation.
On startup, and after the optional eeprom state is restored, he fixtures inside master_fixture.json
are loaded if this file is present.
These fixtures represent the master ORM data format, and are designed to be manually specified.
Local frontend (optional)
Extracting the frontend build to ./static
also gives access to the local portal interface.
Download the latest frontend release (.tgz) manually and put it in the static folder.
tar -xf *.tgz
Type checking (optional)
For type checking during development mypy is used, this requires python3 as well as some extra dependencies in order to function properly:
pip install mypy types-all sqlalchemy-stubs
Now run the type checking test
../gateway$ mypy src
Running the code
Start the necessary services
gw-service
gw-vpn-service # usually not needed
Local user
The gateway locally does not require authentication. However, to log in the frontend, you can use the user admin, pwd admin.
VPN check
When not running the cloud locally, it is necessary to provide the vpn_check_url
in the openmotics.conf
file under the etc
folder.
Otherwise the VPN service will fail because it cannot perform the check.
vpn_check_url = http://127.0.0.1:8000/api/gateway/heartbeat
obscure known problems
- There might be symlink issues when trying to deploy on a mounted drive, deploying on the native drive will fix those issues. In my case the symlink issues caused installed packages to not be found.
Updating the database
We use alembic to manage database migrations, general documentation: https://alembic.sqlalchemy.org/en/latest/tutorial.html#running-our-second-migration
Building the migration after changes in the model:
(run the following commands in the src
folder)
src/ $ alembic revision --autogenerate -m "comment"
Running the migrations:
src/ $ alembic upgrade head
License
This project is licensed under the AGPLv3 License - see the LICENSE.md file for details
Acknowledgments
- Thanks to everybody testing this code and providing feedback.