Skip to content

Installation

Jump to bottom
Marc-Olivier Arsenault edited this page Dec 28, 2022 · 17 revisions

Installation

Download, install and run tefnut

  1. Install requirements
#Make sure you have python >3.8 (I suggest using pyenv to configure this)

# Install poetry
curl -sSL https://install.python-poetry.org | python3 -
  1. Install tefnut
git clone git@github.com:marcolivierarsenault/tefnut.git

cd tefnut

# install dependencies
poetry install
  1. Configure config file Configuration 
# run program 
poetry run gunicorn --threads=2  -b 0.0.0.0:5000 main:app

# run the script even if logout of ssh
nohup poetry run gunicorn --threads=2  -b 0.0.0.0:5000 main:app &

Configuration

For Tefnut to work there are essential 3 main component required

  1. RaspberryPi or other physical way to control your humidifier
  2. Access to outdoor temperature
  3. Access to indoor humidity

We need to configure the 3, all of the configuration gets added in the Config File

To create the config file make a copy of the template

cp _template.settings.toml settings.toml

1 RaspberryPi configuration

Information for RaspberryPi can be found HERE,

2 Weather API

In order to do proper Humidity calculation, we need to know the outside temperature. To do so we use OpenWeather API. Simply register for the FREE access to weather data. You will need to add your API key in the configuration file. You also need to get your latitude and longitude value to get the appropriate weather information.

[WEATHER]
api_key = "123123123123123123123123123" # API Key 
lat = "45.50" # Montreal Latitude
lon = "-73.56" # Montreal Longitude

3 Ecobee

To measure internal humidity we use Ecobee smart thermostat. For this you will need to get to perform 2 task

1) Become a dev (if you never done it)

You will need to obtain an API key from ecobee’s developer site to use this integration. To get the key, your thermostat must be registered on ecobee’s website (which you likely would have already done while installing your thermostat). Once you have done that, perform the following steps.

  1. Click on the Become a developer link on the developer site.
  2. Log in with your ecobee credentials. (Make sure multifactor authentication is disabled to meet the developer login form’s limits. If you’ve already enabled MFA, the web portal doesn’t support disabling it. The iOS and Android apps do under Account > Account Security. You can re-enable MFA after becoming a developer.)
  3. Accept the SDK agreement.
  4. Fill in the fields.
  5. Click save.

2) Get an APIKEY.

  • Create a new app
    • Select a Name: e.g. Tefnut
    • Enter descriptions: e.g. Humidity monitoring system
    • Authorization Method, select ecobee PIN
    • Click create
  • You now have access to the APIKey, you will need it for the config file

Open the config file and add your API Key

[ECOBEE]
apikey = "alsjdkasjdaskdjakdndadASKDJIADasdjasde"

3) Configure Ecobee PIN

The first time you will run the application, It will start and output your PIN, but it wont be working, this is normal. This allows us to grab the Ecobee PIN so you can configure it in your account.

Run the app

(tefnut-py3.11) ➜  tefnut git:(poetry) poetry run gunicorn --threads=2  -b 0.0.0.0:5000 main:app                                     
[2022-12-28 08:20:00 -0500] [86712] [INFO] Starting gunicorn 20.1.0
[2022-12-28 08:20:00 -0500] [86712] [INFO] Listening at: http://0.0.0.0:5000 (86712)
[2022-12-28 08:20:00 -0500] [86712] [INFO] Using worker: gthread
[2022-12-28 08:20:00 -0500] [86719] [INFO] Booting worker with pid: 86719
===========Starting up Tefnut=============
2022-12-28 08:20:01,539 -    logging -  INFO - Enabling Loki
2022-12-28 08:20:01,540 -    logging -  INFO - Loki configured
2022-12-28 08:20:01,568 -    logging -  INFO - Enabling Loki
2022-12-28 08:20:01,569 -    logging -  INFO - Loki configured
2022-12-28 08:20:01,593 - webservice -  INFO - Application loaded
2022-12-28 08:20:01,604 - webservice -  INFO - Tefnut version: v0.4.0
2022-12-28 08:20:01,640 - webservice -  INFO - Starting code on git sha: cd4ff8641db08f76ca208eedc7b3c819239660fb
2022-12-28 08:20:01,650 -    control -  INFO - starting ecobee device
2022-12-28 08:20:02,322 -     ecobee - WARNING - Please go congigure your PIN if not done: JHSN-NKTQ
2022-12-28 08:20:03,030 -     ecobee - WARNING - Please go congigure your PIN if not done: JHSN-NKTQ

This give us our Ecobee PIN, in this case JHSN-NKTQ Now go back on Ecobee website, Open the My App section

image

  • Click add aplication
  • Add the PIN you got from the log
  • click next and follow the steps

Now if we run Tefnut, it successfuly connect to Ecobee

(tefnut-py3.11) ➜  tefnut git:(poetry) poetry run gunicorn --threads=2  -b 0.0.0.0:5000 main:app
[2022-12-28 08:22:10 -0500] [86835] [INFO] Starting gunicorn 20.1.0
[2022-12-28 08:22:10 -0500] [86835] [INFO] Listening at: http://0.0.0.0:5000 (86835)
[2022-12-28 08:22:10 -0500] [86835] [INFO] Using worker: gthread
[2022-12-28 08:22:10 -0500] [86838] [INFO] Booting worker with pid: 86838
===========Starting up Tefnut=============
2022-12-28 08:22:11,173 -    logging -  INFO - Enabling Loki
2022-12-28 08:22:11,174 -    logging -  INFO - Loki configured
2022-12-28 08:22:11,201 -    logging -  INFO - Enabling Loki
2022-12-28 08:22:11,202 -    logging -  INFO - Loki configured
2022-12-28 08:22:11,217 - webservice -  INFO - Application loaded
2022-12-28 08:22:11,227 - webservice -  INFO - Tefnut version: v0.4.0
2022-12-28 08:22:11,263 - webservice -  INFO - Starting code on git sha: cd4ff8641db08f76ca208eedc7b3c819239660fb
2022-12-28 08:22:11,273 -    control -  INFO - starting ecobee device
2022-12-28 08:22:11,838 -    control -  INFO - Ecobee device started
2022-12-28 08:22:11,848 -    control -  INFO - Capturing humidity
2022-12-28 08:22:12,058 -    control -  INFO - Capturing temp

This will create a pyecobee_db file to store Ecobee credentials. Do not modify this file

Optional Configurations

Tefnut is designed to instrument and be monitorable remotely. Using Loki (For logs) and InfluxDB (For data points) allow us to configure Grafana to monitor. An example Dashboard is available here.

Remote Logging

Tefnut is configure to be able to work with a remote logging server (given that this is running on a Raspberry pi behind my furnace and I do not enjoy going there physically.)

I you want remote logging, you need a Loki server.

You can then add it to your configuration:

[LOKI]
enable = true
name = "tefnut-dev"
url = "http://127.0.0.1:3100/loki/api/v1/push"

if you do not want any, you can delete all of this section or set it to false

[LOKI]
enable = false

Influx DB

Tefnut has the ability to instrument all the metric and logic using InfluxDB. Configure to add your server details:

[INFLUX]
enable = true
url = "http://127.0.0.1:8086"
org = "tefnut"
token = "your_user_tocken"
bucket = "tefnut"

if you do not want any, you can delete all of this section or set it to false

[INFLUX]
enable = false

Config File

settings.toml need to be in the root of the application

Name Example Possible Value Description
GENERAL
loglevel "DEBUG" ("INFO", "DEBUG", "WARNING", "ERROR") Log level to be shown, Normal python levels
mode "AUTO" ("AUTO", "MANUAL", "OFF") Operating mode, more details
manual_target 40 Int Desired Humidity Level in Manual Mode
emergency_target 30 Int Desired Humidity Level in Auto Mode if we loose Temperature services
auto_delta -2 Int How much lower or higher we want the humidity to be in Automatic mode
deadband 2 Int +- 2% of humidity on the Desired Humidity Level
humidifier "pi" ("stub", "pi") Pi for the raspberry pi implementation, Stub for testing
rpi_pi 26 Int BCM Pin value
LOKI
enable false true\false Enable or Disable Loki logging server
name "tefnut-dev" String Name to use for the logger
url "http://127.0.0.1:3100/loki/api/v1/push" String URL of server
WEATHER
api_key "dshASdase3rf4E33dwq2qdw" String Open Weather API Key
lat "45.54969" String Latitude of your home
lon "-73.19395" String Longitude of your home
INFLUX
enable false true\false Enable or Disable Influx data collection
url "http://127.0.0.1:8086" String URL of server
org "tefnut" String name of org on InfluxDB server
token "asdDsad34reEddasDaa2eddewdWED32" String Api key with write access to the InfluxDB bucket
bucket "tefnut" String name of bucket on InfluxDB server
ECOBEE
apikey "asdDsad34reEddasDaa2eddewdWED32" String Ecobee Api key
WEBUI
username "admin" String username for web admin
password "password" String password for web admin
Clone this wiki locally