S0-Logger for digital powermeters, using a linux-based 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.

C.H.I.P had a really nice ARM based microcontroller for $10 running on Debian.
I used them for many microcontroller projects like this one, but sadly they
went insolvent! So this project runs on C.H.I.P., but I also added a new part
to show how to run it on a Raspberry Zero.

The python app is running as a wsgi application under apache2 and is providing
the s0 data via a simple REST API based on the bottle framwork. As both micro-
controllers support the RPI.GPIO framework, the code does not require too many
changes. See RPi.GPIO at https://sourceforge.net/projects/raspberry-gpio-python

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. The status
is signlaed with the onboard LED on the C.H.I.P, for the Raspberry Pi an
external LED is powered by GPIO27 (pin 13).

---------------------------------------------------------------------------
C.H.I.P

                      5V stabilized power source
                              +
                              |
     CHIP PINs                |                          
     =========                |
     CHG-IN    +--------------+                          Powermeter PINs
                                                         =================
     VCC-3V3   +--------------------------------------+  S0+
       
     XIO-P1    +--------------+-----------------------+  S0-
                              |
                              R    R = 2,2k Ohm
                              |
     GND       +--------------+
                              |
                              |
                              |
                              +
                      GND of power source
       
---------------------------------------------------------------------------
RASPBERRY ZERO
                      5V stabilized power source
                                +
                                |
     RASPI PINs                 |                          
     ==========                 |
     (2) 5V      +--------------+                          Powermeter PINs
                                                           =================
     (1) 3V3     +--------------------------------------+  S0+
       
     (7) GPIO4   +--------------+-----------------------+  S0-
                                |
                                R    R = 2,2k Ohm
                                |
     (13) GPIO27 +----D----R----+    D = LED, R = 470 Ohm
                                |
                                | 
     (9) 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.

Use a stabilized 5V power source for your microcontroller. I use 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.) Basic installation and setup, e.g. apache2 and python

      $ sudo apt-get update
      $ sudo mkdir /var/log/apache2
      $ sudo echo "tmpfs /var/log/apache2 tmpfs defaults,uid=root,gid=adm,mode=0750 0 1" >> /etc/fstab
      $ sudo mount -a
      $ sudo apt install python3 git python3-bottle apache2 
      $ sudo apt install libapache2-mod-wsgi-py3 apache2-dev curl
      $ sudo apt install build-essential python3-dev python3-pip 
      $ sudo apt install python3-smbus flex bison

2a) C.H.I.P. only: Install CHIP_IO library. Many thanks to Robert Wolterman
    for creating this library.

      $ sudo apt install chip-dt-overlays
      $ git clone https://github.com/xtacocorex/CHIP_IO
      $ cd CHIP_IO
      $ sudo python3 setup.py install
      $ cd ..


2b) Raspberry only: Install RPI.GPIO library.

      $ sudo apt install python3-rpi.gpio


3.) 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
      $ ./install_apache2.sh


4a) C.H.I.P. only: 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


4b) Raspberry only: Give apache2 access to gpio (assuming uid is www-data)

      $ sudo adduser www-data gpio


5.) Connect powermeter's S0 port with the controller 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.


6.) 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
           hw = CHIP
           s0pin = XIO-P1
           LEDpin = 13
           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))} 

REST APIs
=========

Access to API via http://<chip-URL>/s0/<API name>

- CONFIG API

    /s0/config?energy=[value in Wh]&debug=[on|off]&simulate=[on|off]&s0blink=[on|off]

    If the API is called without parameters, it opens a web dialog. The parameters
    allow to adjust the current consumption counter in Wh and to toggle the 
    following configuration settings online:

    - DEBUG on/off

        Send debugging messages to log when on

    - HW CHIP/RASPI

        Define which microcontroller is being used

    - SIMULATE on/off

        When SIMULATE is on, s0 triggers can be simulated by API
        /s0/trigger to test without having to be wired to s0 bus

    - s0BLINK on/off

        When soBLINK is on, the CHIP LED will blink whenever a
        s0 trigger is being detected

- VERSION API

    /s0/version

    Return the version of the s0logger software.

- ELECTRICITY API

    /s0/electricity

    Return all current data readings as JSON.

- TRIGGER API

    /s0/trigger

    Simulate a detected hw s0 signal to test the software in simulation mode