#thermeq3 Boiler actor device for ELV/EQ-3 MAX! cube.

thermeq3 features:

• switching DHW/Boiler according to valve position, you can set how many valves must be opened for how many %, or sum of the all valves in house to switch on DHW/Boiler
• profiles to choose right control values based on time or external temperature
• senses open windows and start heating after safe time to eliminate "panic" heating after forced ventilation
• any event on MAX! cube tracked down to log file
• notifies owner about opened windows after defined period, this period is automatically set according to external temperature
• owner can set various intervals for any important value
• autoupdate from github
• simple self diagnostics
• can be remote controlled via standard yún features (http/https)
• daily summary
• simple html status on user selectable port (via uhttpd)

##Installation instructions Plase check sketch (in fritzing) and setup below. First you must upload sketch from yun-sketch to the yun. Then login to yun via ssh. To install thermeq3 please type this command, while logged in:

wget --no-check-certificate --quiet --output-document /root/install.sh https://raw.githubusercontent.com/autopower/thermeq3/master/install/install.sh|chmod +x /root/install.sh

And after that (you can change thermeq3 name to your own):

cd /root
./install.sh thermeq3

Don't forget to edit config.py file! Scroll down below for "In config.py file" chapter.

##Check install/beta directory There's always new code, which seems to work on my development thermeq :)

##What's new? ###2015-Dec-13

• directory structure reorganised
• new install script for all version (old one in one file (nsm.py), new one with libraries)

###2015-Dec-11

• some cleanup on github

###2015-Dec-10

• new librarysed version in betabeat
• new install script for lib version in scripts
• some code overhaul :)

###2015-Dec-04

• betabeat: new RPi version

###2015-Nov-28

• betabeat: bridge routine rewrited, some support for literal processing
• betabeat: ignore intervals corrected
• betabeat: you can ignore valve forever, just edit bridgefile and to ign codeword add valveserial and time since epoch=1924991999, its 31/Dec/2030 :), e.g. {"06ABCD": 1924991999}
• betabeat: new boiler controlling variable, svpnmw (Single Valve Position, No Matter What) in %, if any of valves opened more than svpnmw then heating is on, to turn off just set to 101%

###2015-Nov-27

• betabeat: new weather API used, yahoo YQL and OWM, API key for OWM is from OWM example page, please change it
• just for sure, use "new" bridge python library from https://codeload.github.com/arduino/YunBridge/zip/master

###2015-Nov-26

• new codeword, mode, can be auto or manual, added after request, in auto mode thermeq3 sends H/S commands to arduino part, in manual mode do nothing :)

###2015-Nov-02

• betabeat: some javascript code (based on jquery ui) to control device, ugly, not fully functional, first steps with JS and CSS ;)
• betabeat: code cleanup

###2015-Nov-01

• betabeat: new arduino command A, clears LED
• betabeat: some cleanup, codeword dump removed

###2015-Oct-31

• minor fixes
• new status messages
• JSON formated string in current status

###2015-Oct-21

• some fix in RPi version, please check commented code and uncomment (setblocking)
• if anyone need room names in CSV, uncomment code in exportCSV()
• minor updates

###2015-Oct-10

• minor updates, betabeat and production are the same version
• alpha RPi version, only change is the abstraction code replacing bridgeclient (but as reported from users, it works! :))

###2015-Mar-23

• minor updates

###2015-Mar-15

• updating valve ignore interval according to outer temperature

###2015-Jan-18

• more pythonic code, classes etc.

###2015-Jan-07

• betabeat: yahoo weather and oww interval sampling working
• betabeat: in secondary web folder nice.html file is generated, contains nice formated status (hm, if pre means nice)

###2015-Jan-06

• support for yahoo weather, stay tuned for open window interval auto update by actual weather situation (temperature, humidity), better ventilation 'support'
• resample function
• support directory in betabeat, check code for sampling function, modify to your needs

###2015-Jan-03

• betabeat: if webserver directory not exist, is created
• betabeat: correct response on secondary web server, eg: http://arduino.ip:second_port/cgi-bin/status returns app/json from status.xml file

###2014-Dec-28

• betabeat: open window list and current status separated into secondary web server as xml files, accessible w/o any credentials

###2014-Dec-27

• Simple install script: update opkg, installs openssl for python, create some scripts for nsm.py controlling.

###2014-Dec-26

• Ignoring valve after closing window
• Redesigned rooms/valves listing in log file
• Support for tasker, new bridge values: openwinlist and current_status, please take a look at tasker directory, there's simple example how to list open windows. Usefull especially when leaving house :)
• New CSV file handling, file is generated daily. New column in CSV, after date/time col, you can read 0/1 for heating (0=off, 1=on), so you can analyze when is boiler turned on or off (no more cat log | grep)
• Redesigned bridge functions (load/save), little bit failsafe (nothing extraordinary)
• Implemented support for day table, just enable beta functionality (thermeq3.ip/data/put/beta/yes) and edit table in nsm.py. You can control boiler in different way during day.

##Setup ###You'll need:

• Arduino Yún
• 5V relay
• two or three (or one RGB LED) LED diodes and min 220ohm resistors
• installed and correctly running ELV/EQ-3 MAX! Cube
• boiler with switched heat by wire, via relay
• python-openssl library opkg update; opkg install python-openssl
• credentials for mail server with TLS (or modify code)
• storage space on microSD or USB,

###Wiring:

• 220ohm resitor to pin13, then to code_run LED (in my setup green LED, lit when arduino script is reading messages from python part, this is sign of activity)
• 220ohm resitor to pin8, then to error LED (in my setup red LED, lit when any error)
• 220ohm resitor to pin9, then to status LED (in my setup blue LED, lit when heating is on)
• relay voltage +5V to pin8, or to the power 5V and you must comment RELAY_POWER
• relay in to pin10
• relay GND to GND
• LED diodes to GND
• your DHW/Boiler to com and NO (or NC) pins of relay (check your boiler documentation)

##Code There are two parts of thermeq3:

• python code, upload into /root/ files nsm.py and config.py and then please edit config.py
• arduino code, upload with IDE

##How it works? Arduino sketch runs python script nsm.py located in /root. And then check if it's running. If not, runs it again from start. This script reads status from MAX! Cube and if any of radiator thermostat's valve is opened above valve_pos value, the relay is switched on, thus boiler/DHW is switched on. This is done by saving char into the 'msg' bridge value, which is readable at Arduino side. Heating also can be started if sum of radiator valves positions are geater than num_of_valves * stp.per_switch, where stp.per_switch is value in %. So if you have 10 valves in house and stp.per_switch=8, and sum of these valves positions are 80+, relay is switched on. You can turn on this feature by stp.preference="per" in python code. If you need only simple total value, set stp.preference="total" and setup total_switch variable.

On start LEDs blink 4 times, then remains lit until arduino yun bridge component is initialized. Then blinks 4 times again.

##How to change values? If you want change some values when nsm.py is running, just browse to http://arduino.ip/data/put/interval/<your value> to change 'interval' setting. E.g. if your browse to http://arduino.ip/data/put/valve_pos/<your value> you can change valve_pos value (e.g. how many % must be valve opened).

##What I can change? ###In Python code

• devname = device name
• error = errors since last status reports
• status = status of device (heating, idle, starting, error)
• totalerrs = total errors from start
• valve_pos = see above
• total_switch = sum of valve positions, no matter how many valves are in house
• interval = see above
• heattime = total heat time from start, in seconds
• command = can be:
  • quit quits application
  • mail sends status report via mail
  • init reinits python app
  • uptime updates uptime value
  • log_debug turns on logging on debug level
  • log_info turns on loggin on info level (default)
  • mute mutes warning for some time
  • rebridge reloads bridge file
  • updatetime updates uptime and heat time
  • led turns on or off heating LED (according to current heat status)
  • upgrade checks for upgrade, and if new version is available, upgrades nsm.py

###In config.py file

• stp.max_ip = "192.168.0.10" IP address of MAX! cube
• stp.fromaddr = "devices@foo.local" from, user name
• stp.toaddr = "user@foo.local" to email
• stp.mailserver = "mail.foo.local" via this server
• stp.mailport = 25 on port
• stp.frompwd = "this.is.password" login with this password
• stp.devname = "hellmostat" device name
• stp.timeout = 10 timeout in secods, used in communicating with MAX! Cube and as a sleep time for flushing msg queue, set to similar value as unsigned long interval in arduino sketch
• stp.extport = 29080 external port, this is the port (typically) on firewall where NAT is defined (so you can mute thermeq3 from internet), please setup your firewall/router to such scenario

###In arduino sketch

• #define DEBUG_PRG if you wanna print debug values via serial connection
• #define RELAY_PIN 10 where is the relay pin?
• #define RELAY_POWER 8 where is the power for relay? undef if relay is connected to 5V directly
• #define STATUS_LED 9 status LED pin
• #define ERROR_LED 8 error LED pin
• #define LOOP_LED 13 activity/loop LED pin
• #define BLINK_INTERVAL 150 blink interval in miliseconds
• #define WAIT_UPDATE_SYNC 10000 how many millis wait to rerun upgraded python code
• #define IWANNABESAFE in case of any trouble shutdown relay, undef for stay in last selected mode
• unsigned long interval = 10*1000; loop interval in seconds, arduino'll check for messages every 10 seconds, change 10 to anything you want
• unsigned long app_interval = 10*60000; check for running app interval in minutes, change 10 to anything you want

##Messages for arduino

• H heat!
• S stop heating!
• E error, error LED is lit
• C clear error LED
• A clear all LEDs
• Q fatal error, lit some disco effects on LEDs
• D dead! status LED breathing
• R restart app, eg. after upgrade

##How to debug? Python code produce these files:

• /mnt/sd<x1>/<device_name>.csv, simple comma separated value file with valve positions and temperature readings
• /mnt/sd<x1>/<device_name>.log, log file, really huge on log_debug
• /mnt/sd<x1>/<device_name>_error.log, python stderr redirected, use in case of crash, or send me this file.
• /mnt/sd<x1>/<device_name>.bridge saved bridge client values
• /root/nsm.error low level errors, which cant be written do .log file (e.g. due to lack of mounted storage media). This file is also mailed to recipient on start. Then is truncated to zero size.

Please note, that x1 stands for a1 or b1, so full path will be /mnt/sda1 or /mnt/sdb1.

###Thats all folks. Stay tuned :)