View source for Smappee

Documentation for Smappee Lua upload to Domoticz code - https://github.com/steps39/Domoticz_Smappee.

==Introduction==

Smappee is an energy monitor, which logs your energy consumption back to a server.  Smappee have released an api to access the stored energy consumption remotely.

The api is fairly simple, involving authorisation, selection of system for data to be retrieved about, then data retreival and can be accessed from a bash script as here - http://www.domoticz.com/forum/viewtopic.php?f=31&t=7312#p50197

Unfortunately the server does not always return data when it should, in order to avoid loosing data then a more complex Lua script is required, which correctly handles both authorisation and occassions when there is no data or multiple sets of data.

Domoticz incorporates Lua and in principle data could be retrieved from smappee from within Domoticz, but authorisation with the smappee server can take up to 20 seconds, but Domoticz only allows Lua programs to run for 10 seconds in case they get into an infinite loop and makes Domoticz irresponsive.

N.B.
Smappee returns the energy consumed in a 5 minute period, so this is used by smappee.lua to calculate an "average" power used over 5 minutes, so peak power measurements will be lower than those reported in domoticz from more direct energy measurement devices.
The energy reported back from smappee.lua to Domoticz, is logged by Domoticz as the time at which the data is recorded in Domoticz, so if there are any issues with data being returned from Smappee then while the total consumption should be correct, the power will be an averaged figure over different time periods of time.

==Installing smappee==
These instructions are for use on a Raspberry Pi, using Lua 5.2, for other systems you will need to find / compile the necessary Lua libraries yourself.  The current program expects both household energy consumption and solar energy generation, the Smappee hardware is also able to monitor a single phase consumption with solar energy and 3 phase with / without solar energy.

===Installing Lua Libraries===

smappee is a Lua program and requires Lua 5.2 plus https / json ability to interact, (json, socket and ssl libraries).

First install Lua 5.2 if it is not already on your system and git as we will need it later:
<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install lua5.2 git-core
</syntaxhighlight>

Now, you will need to install the necessary libraries for Lua.  I have compiled these and made them availalbe on the forum - [http://www.domoticz.com/forum/viewtopic.php?f=21&t=7279 dtgbot - Domoticz TeleGram BOT].  Download the two tar.gz files to a temporary directory (~/temp).

<syntaxhighlight lang="bash">
sudo mkdir -p /usr/local/share/lua/5.2/ #Only needed if this directory does not exist
cd /usr/local/share/lua/5.2/
sudo tar -xvf ~/temp/usrlocalsharelua52.tar.gz
sudo mkdir -p /usr/local/lib/lua/5.2/ #Only needed if this directory does not exist
cd /usr/local/lib/lua/5.2/
sudo tar -xvf ~/temp/usrlocalliblua52.tar.gz
</syntaxhighlight>

===Customisation File===
In order to avoid accidentally passing system specific information, I have included all the system customisation data in a single shell script.

In order to create this file you need to edit the suggested file below with your email address, your Smappe user name, your Smappee password, your Smappee client id, your Smappee secret and details of your Domoticz set-up.  It is good to have a temporary directory set up for the log file, I would recommend using a ram disk for the temporary directory, have a look here - http://www.domoticz.com/wiki/Setting_up_a_RAM_drive_on_Raspberry_Pi.

Create your customisation file:
 sudo nano /etc/profile.d/DomoticzData.sh
<syntaxhighlight lang="bash">
#!/bin/bash

# Variables to avoid having to set local system information in individual automation scripts

#I can't get the next line to work during start-up so have gone to 127 instead
#export DomoticzIP=$(hostname -I|sed 's/[ ]*$//')
export DomoticzIP="127.0.0.1"
export DomoticzPort="8080"
export DomoticzUsername=""                # Can be left blank if you are not using security 
export DomoticzPassword=""
export TempFileDir="/var/tmp/"            # If you use dtgbot then just add the four lines
export SmappeeClientSecret="xyxydfslsd"   # Request a client_secret by sending an email to support(AT)smappee.com
export SmappeeClientID="YourName"         # Request a client_id by sending an email to support(AT)smappee.com
export SmappeeUsername="username"         # Your Smappee username
export SmappeePassword="password"         # Your Smappee password
export SmappeeHousehold="Household1"      # Domoticz Household Energy Name
export SmappeeSolar="Solar1"              # Domoticz Solar Energy Name
</syntaxhighlight>

And set it to be executable:
 sudo chmod +x /etc/profile.d/DomoticzData.sh

This single file avoids you having to customise the Lua program.

===Setting Up Domoticz for smappee.lua===
Create household and solar energy meters in Domoticz with the names set in the environment variables SmappeeHousehold and SmappeeSolar (even if you only have one meter, you have to create both meters for the script to work).

To create one energy meter - Go to Setup - Hardware - Dummy, and then, on the new dummy energy meter Create Virtual Sensors - Electric (Instant + Counter). The new sensor will added to devices, so go to Setup - Devices - select the new device and give it the correct name to add to the Utility tab.

Then create 4 user string variables all containing the single number one - 1 : Setup - More Options - User Variables : SmappeeAccessToken, SmappeeRefreshToken, SmappeeExpiresAt, SmappeeTimeStamp - these are used by smappee.lua to avoid having to request a new authorisation token every 5 minutes.

===Installing Smappee Program===

The smappee program is now on github, so the program is installed using git, along with a bash script, which is made executable and then added to cron so that data is collected from Smappee every 5 minutes and transferred into Domoticz:
<syntaxhighlight lang="bash">
cd ~
# This will create the domoticz_smappee directory
git clone https://github.com/steps39/domoticz_smappee.git
cd domoticz_smappee
# Make sure the script is executable
sudo chmod +x smappee.sh
# Make the program run every 5 minutes
sudo crontab -e
</syntaxhighlight>

To update the program it should just be necessary to repeat the steps as detailed above.

Add this single line to cron:
 */5  * * * * /home/pi/domoticz_smappee/smappee.sh
Then save this (ctrl o) and exit (ctrl x).

Assuming all the steps have been completed then smappee.lua is now running once every 5 minutes.

==Checking Functioning==

If smappee.lua is running properly, then smappee.log will have been created and data will be uploaded to Domoticz.

Wait 5 minutes and data should have appeared in Domoticz, on at least one of the virtual energy meters.

Check smappee.log which will have been created if smappee.lua has excuted.

If there is a problem with the program, then smappee.log.errors will have been created.

==Controlling Smappee, including confort plugs, through the internal API==

'''''After update of firmware to last update 
Application software version and build nr 1.0.0S buildNr #1185 and Acquisition Software version	4.29 
the rf electrical plugs works with communcation protocol MQTT and the commands below they do not work anymore.'''''

Smappee also allows you to control plugs (actuators) using the 433 Mhz frequency. The brand sells plugs DIO produced by Chacon, but Smappee works also with most other brands which sell plugs and other switches compatible with the Home Easy protocol. Through the Smappee monitor (http://<your smappee ip>/smappee.html, default logon "admin") it is possible to control the plugs and access some other useful information. This allows us also to bypass the external API and control the plugs directly, which regarding the plug control is a clear advantage in terms of speed and reliability. One way to do this is through simple bash scripts.

Smappee internal API has the following commands:

 http://<your smappee ip>/gateway/apipublic/logon
 http://<your smappee ip>/gateway/apipublic/statisticsPublicReport
 http://<your smappee ip>/gateway/apipublic/reportInstantaneousValues
 http://<your smappee ip>/gateway/apipublic/restartEMeter
 http://<your smappee ip>/gateway/apipublic/commandControlPublic

To login on the Smappee local API with curl, just use:

 curl -H "Content-Type: application/json" -X POST -d "<your_logon>" http://<your smappee ip>/gateway/apipublic/logon

Through this API you can easily create a script to turn on an off the plugs. For example to turn on the plug with the ID 8:

 #!/bin/bash
 curl -H "Content-Type: application/json" -X POST -d "<your_logon>" http://<your smappee ip>/gateway/apipublic/logon
 curl -H "Content-Type: application/json" -X POST -d "control,controlId=1|8" http://<your smappee ip>/gateway/apipublic/commandControlPublic

To turn it off, your script just needs to change the first number after the controlID to 0:

 #!/bin/bash
 curl -H "Content-Type: application/json" -X POST -d "<your_logon>" http://<your smappee ip>/gateway/apipublic/logon
 curl -H "Content-Type: application/json" -X POST -d "control,controlId=0|8" http://<your smappee ip>/gateway/apipublic/commandControlPublic

To get a list of your plug IDs for the previous scripts just use:

 curl -H "Content-Type: application/json" -X POST -d "load" http://<your smappee ip>/gateway/apipublic/commandControlPublic

Don't forget to make the files executable, for example:

 sudo chmod +x plug_sofa_off.sh

After you create the scripts, you need also to create virtual plugs on Domoticz and assign the on and off scripts to the "On Action" and "Off Action" fields.

[[File:2015-08-21 12 26 41-Domoticz.png]]

For getting some information about your Smappee just type:

 curl http://<your smappee ip>/gateway/apipublic/statisticsPublicReport

And if you want to access the instantaneous values of your home consumption you could type:

 curl http://<your smappee ip>/gateway/apipublic/reportInstantaneousValues
[[Category:Lua]]
[[Category:Bash]]