S0-Logger for digital powermeters, using a CHIP microcontroller and FHEM

Author: Michael Eitelwein (michael@eitelwein.net)
Source: https://gitlab.eitelwein.net/MEitelwein/S0-Logger

Description
===========
Many digital power meters have a S0 interface to export energy consumption.
Typically they create a trigger signal every x Wh consumed energy. My
meter is sending a 30ms trigger every 1 Wh.

This signal can be read with the GPIO pins of common microcontroller boards 
like RaspberryPi, Arduino or others. As this solution is based on the 
Adafruit GPIO library, it is easy to port to many different 
microcontroller boards.

My favorite microntroller for IoT devices is the C.H.I.P. board of Next Thing Corp 
(https://www.nextthing.co/), which provides full Debian linux, GPIO and WLAN
for about $9 USD (!). It is extremely easy to setup and use and pretty  
compatible to existing RaspberryPI stuff.

The python app on the C.H.I.P is running as a wsgi application under apache2
and is providing the s0 data via a simple REST API based on the bottle framwork.

My smart home is managed by the open source platform FHEM, which is perfectly
configurable and programmable - you just need to love PERL though :-)
FHEM can simply add a new device by parsing the HTML output of IoT devices 
that expose REST APIs. As JSON data can be interpreted directly, it is very 
easy to manage the data transfers. More info about FHEM can be found
at http://fhem.de


Wiring
======
The power meter usually provides a S0- and S0+ port which is internally
connected to an optocoppler. At every trigger it short circuits S0+ and S0-.

Connecting this to the GPIO ports of a microcontroller is simple:

                      5V stabilized power source
                              +
                              |
     CHIP PINs                |                          
     =========                |
     CHG-IN    +--------------+                          Powermeter PINs
                                                         =================
     VCC-3V3   +--------------------------------------+  S0+
       
     XIO-P1    +--------------+-----------------------+  S0-
                              |
                              R pull-down resistor
                              |
     GND       +--------------+
                              |
                              |
                              |
                              +
                      GND of power source
       

The pull-down resistor should have between 2k to 5k Ohm. The value actually
does not matter too much as the pin is pulled to 3V3 only for 30ms to 90 ms 
depending on the design of the powermeter.

As a power source I use a stabilized 5V source like this one
  Mean Well Hutschienennetzteil DR-15-5 , 5V
  http://www.elv.de/mean-well-hutschienennetzteil-dr-15-5-5v.html


Installation and Configuration
==============================

Whith standard Debian running on the CHIP device, just log in as your favorite
user who is equipped with sudo rights.

1.) Install CHIP_IO library for CHIP. Many thanks to Robert Wolterman
    for creating this library.

      $ sudo apt-get update
      $ sudo apt-get install python git python-bottle apache2 
      $ sudo apt-get install libapache2-mod-wsgi apache2-dev curl
      $ sudo apt-get install build-essential python-dev python-pip 
      $ sudo apt-get install python-smbus flex bison chip-dt-overlays
      $ git clone https://github.com/xtacocorex/CHIP_IO
      $ cd CHIP_IO
      $ sudo python setup.py install
      $ cd ..


2.) Install the s0logger scripts (assuming apache runs with group www-data)

      $ git clone https://gitlab.eitelwein.net/MEitelwein/S0-Logger
      $ sudo mv S0-Logger /var/opt
      $ cd /var/opt/S0-Logger
      $ sudo chgrp www-data /var/opt/S0-Logger
      $ sudo chmod g=rx /var/opt/S0-Logger
      $ sudo mkdir /var/www/s0logger /var/www/s0logger/config
      $ sudo chgrp www-data /var/www/s0logger /var/www/s0logger/config
      $ sudo chmod g=rx /var/www/s0logger
      $ sudo chmod g=rwx /var/www/s0logger/config
      $ sudo a2dismod mpm_event
      $ sudo a2enmod  mpm_worker wsgi
      $ sudo a2dissite 000-default.conf
      $ a=$(pwd); sudo ln -s ${a}/s0logger.py /var/www/s0logger
      $ a=$(pwd); sudo ln -s ${a}/s0logger.wsgi /var/www/s0logger
      $ a=$(pwd); sudo ln -s ${a}/request.wsgi /var/www/s0logger
      $ a=$(pwd); sudo ln -s ${a}/config.tpl /var/www/s0logger
      $ a=$(pwd); sudo ln -s ${a}/apache2-conf-s0logger.conf /etc/apache2/conf-enabled/s0logger.conf
      $ a=$(pwd); sudo ln -s ${a}/apache2-sites-s0logger.conf /etc/apache2/sites-enabled/s0logger.conf


3.) Give apache2 access to gpio (assuming uid is www-data)

      $ sudo groupadd gpio
      $ sudo adduser www-data gpio
      $ sudo adduser www-data i2c
      $ sudo cp 98-gpio-group.rules /etc/udev/rules.d/

    Add the following 2 lines to /etc/rc.local
      chgrp -R gpio /sys/class/gpio
      chmod -R g+rw /sys/class/gpio


4.) Connect powermeter's S0 port with the CHIP as explained above and 
    start logging with starting Apache

      $ sudo systemctl restart apache2 

    Check the outoput at http://<CHIP-HOSTNAME>/s0/electricity.
    It should produce a JSON output like the following (all in one line)
    
        { "units": {
            "power": "W", 
            "energy": "Wh", 
            "version": "", 
            "time": "dd.mm.yyyy hh:mm:ss", 
            "S0-ticks": "", 
            "dtime": "s"
            }, 
          "data": {
            "power": 4597897.198538368, 
            "energy": 22228.0, 
            "version": 1.4, 
            "time": "08.11.2017 22:48:26", 
            "S0-ticks": 1, 
            "dtime": 0.0007829666137695312
            }
        }


    If it does not work, use http://<CHIP-HOSTNAME>/s0/config to set DEBUG 
    to True and watch the output in apache2's error log (see section 6).

    Apache2 will call the script request.wsgi at startup because s0logger.wsgi
    will only be loaded when the first http request is done to s0logger's 
    sub-url http://<CHIP-HOSTNAME>/s0.
    Calling s0logger.wsgi per WSGIImportScript would create 2 processes of
    s0logger and mess up access to global variables. May need to find a nicer
    way of securing thread-safeness some time in the future.


5.) The script uses the config file /var/www/s0logger/config/s0logger.conf which 
    it creates automatically. The parameters are self-explaining, it will also
    be used to cache the total energy when the script is not running.
    Here is the default config, you should only change values in [Config]

           [Config]
           simulate = False
           debug = False
           s0pin = XIO-P1
           ticksperkwh = 1000
           port = 8080
           ip = 0.0.0.0
           s0blink = True

           [Cache]
           energy = 0

    Parameters ip and port only impact bottle's debug server. For production,
    change the apache2 settings in the files apache2-*-s0logger.conf .

    Typically, you need to check how many triggers your powermeter 
    creates per kWh of consumed energy. Mine all have 1000 triggers 
    per kWh, but also 2000 per kWh is common.

    There is an API http://<CHIP-HOSTNAME>/s0/config to change the most
    important config parameters at run-time.
    Rereading the config after manual changes to the file requires issuing

      $ sudo systemctl restart apache2


7.) Define a new HTTPMOD device in FHEM and enjoy the result!
    You need to replace <HOSTNAME> with the microcontroller's hostname.
    Polling interval is set to 30s here, any value > 0 is ok.
    
          define powermeter HTTPMOD http://<HOSTNAME>:<PORT>/s0/electricity.html 30
          attr   powermeter getHeader1 Content-Type: application/json
          attr   powermeter getHeader2 Accept: */*
          attr   powermeter icon measure_power_meter
          attr   powermeter reading01Format %.1f
          attr   powermeter reading01JSON data_power
          attr   powermeter reading01Name power
          attr   powermeter reading02Expr $val / 1000
          attr   powermeter reading02Format %.3f
          attr   powermeter reading02JSON data_energy
          attr   powermeter reading02Name energy
          attr   powermeter reading03JSON data_time
          attr   powermeter reading03Name time
          attr   powermeter stateFormat {sprintf("Energy consumed %.3f kWh, Current power %.1f W", ReadingsVal($name,"energy",0), ReadingsVal($name,"power",0))}