mysTeleinfo - README

 Summary
 =======
 
   What is it
   Input/Outputs
   Features
   Project content
   Notes
     Interruption management
   Interactions
   Known bugs and limitations
     Limitations
     Bugs
   Sources

-----------------------------------------------------------------------
 What is it
 ==========

 mysTeleinfo is a MySensors v2 node
             built on an Arduino Nano
             which decodes EdF Teleinformation thread
             and sends its datas to a Jeedom controller
             via a MySensors v2 serial gateway
             through a NRF24L01 radio communication.

-----------------------------------------------------------------------
 Input/Outputs
 =============

 Input is:
   EdF Teleinformation.

 Outputs are:
   Datas to Jeedom controller
   A thread LED which is on during thread reception
   A HC (resp. HP) LED on during HC (resp. HP) hours.

-----------------------------------------------------------------------
 Features
 ========

 This project features:

 - the interpretation of the EdF Teleinformation thread and its
   transmission to the MySensors gateway

 - a behavior witness via a thread LED which is on during the
   reception of each EdF Teleinformation thread

 - a HC LED which is on during low price hours

 - a HP LED which is on during high prices hours

 - all datas may be retransmitted on request.

-----------------------------------------------------------------------
 Project content
 ===============

 This project includes:

 - docs/: the external documentation used for the project
 - build/: the build resources:
   > Arduino Nano pins layout
   > Kicad electronic scheme
   > the built PCB
 - images/: the .png images used as Jeedom widgets
 - mysTeleinfo.ino: the main Arduino program
 - pwiSoftwareSerial.{h,cpp}: a hacked version of the SoftwareSerial
   library (see NOTES)
 - teleInfo.{h,cpp}: the class used to decode the EdF Teleinformation
   thread
 - teleInfo.dump: a log of the debug output.

-----------------------------------------------------------------------
 Notes
 =====

   Interruption management

   The hardware IRQ0/IRQ1 (D2/D3) are left free.
   Most of the NRF24 radio module makes use of PortB (PCINT0) pins.
   For this reason, we have chosen to use a PortB (PCINT2) pin to use
   as input for teleinformation.
   Input is managed via SoftwareSerial library. We are using an hacked
   version in order to optimize the software interrupt management.

-----------------------------------------------------------------------
 Interactions
 ============

 The MySensors node present one main ID to the controller, to manage global
 actions and request or set global parameters
 (see. also https://www.jeedom.com/forum/viewtopic.php?f=35&t=26867
  on child_id's definitions).

 For each configurable parameter:
 - define a specific ChildId
 - parse a received C_SET command with V_CUSTOM message and payload
 - parse a received C_REQ command
 - send a V_VAR1 message to the controller with the value

 Below interactions are defined from MySensors node point of view.

 - CHILD_ID_ADCO (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_SET
    |   |   |
    |   |   +- V_CUSTOM with payload = '1': reset the EEPROM to its default values.
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last ADCO trame.
    |
    +- Sent to controller
        |
        +- V_VAR1: ADCO identifier.

 - CHILD_ID_OPTARIF (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last OPTARIF trame.
    |
    +- Sent to controller
        |
        +- V_VAR2: OPTARIF pricing option.

 - CHILD_ID_ISOUSC (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last ISOUSC trame.
    |
    +- Sent to controller
        |
        +- V_CURRENT: ISOUSC subscribed intensity.

 - CHILD_ID_PTEC (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last PTEC trame.
    |
    +- Sent to controller
        |
        +- V_VAR3: PTEC current pricing period.

 - CHILD_ID_IINST (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last IINST trame.
    |
    +- Sent to controller
        |
        +- V_CURRENT: IINST current intensity.

 - CHILD_ID_ADPS (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last ADPS trame.
    |
    +- Sent to controller
        |
        +- V_CURRENT: ADPS excess use alert.

 - CHILD_ID_IMAX (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last IMAX trame.
    |
    +- Sent to controller
        |
        +- V_CURRENT: IMAX max used intensity.

 - CHILD_ID_PAPP (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last PAPP trame.
    |
    +- Sent to controller
        |
        +- V_POWER: PAPP current power.

 - CHILD_ID_HC_HC (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last HC_HC trame.
    |
    +- Sent to controller
        |
        +- V_KWH: HC_HC low price index.

 - CHILD_ID_HC_HP (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last HC_HP trame.
    |
    +- Sent to controller
        |
        +- V_KWH: HC_HP high price index.

 - CHILD_ID_HHPHC (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: re-send the last HHPHC trame.
    |
    +- Sent to controller
        |
        +- V_VAR4: HP/HC low/high pricing periods indicator.

 - CHILD_ID_THREAD (S_POWER)
    |
    +- Received from controller
    |   |
    |   +- C_SET
    |       |
    |       +- V_CUSTOM with payload = '1' (resp. '0'): enable (resp. disable) the transmission of brut strings.
    |
    +- Sent to controller
        |
        +- V_VAR1: the last read trame.

 - CHILD_MAINTIMER (S_CUSTOM)
    |
    +- Received from controller
    |   |
    |   +- C_SET
    |   |   |
    |   |   +- V_CUSTOM with payload = '1=<value>': set the main timer period (ms).
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: send the main timer period (ms).
    |
    +- Sent to controller
        |
        +- V_VAR1: the main timer period (ms).

 - CHILD_CHANGEDTIMER (S_CUSTOM)
    |
    +- Received from controller
    |   |
    |   +- C_SET
    |   |   |
    |   |   +- V_CUSTOM with payload = '1=<value>': set the max frequency (ms).
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: send the max frequency (ms).
    |
    +- Sent to controller
        |
        +- V_VAR1: the max frequency (ms).

 - CHILD_UNCHANGEDTIMER (S_CUSTOM)
    |
    +- Received from controller
    |   |
    |   +- C_SET
    |   |   |
    |   |   +- V_CUSTOM with payload = '1=<value>': set the unchanged timeout (ms).
    |   |
    |   +- C_REQ
    |       |
    |       +- <any>: send the unchanged timeout (ms).
    |
    +- Sent to controller
        |
        +- V_VAR1: the unchanged timeout (ms).

-----------------------------------------------------------------------
 Known bugs and limitations
 ==========================

   Cf. TODO

-----------------------------------------------------------------------
 Sources
 =======

 http://lhuet.github.io/blog/2014/01/montage-teleinfo.html
 http://www.magdiblog.fr/gpio/teleinfo-edf-suivi-conso-de-votre-compteur-electrique/
 https://hallard.me/demystifier-la-teleinfo/
 https://www.jeedom.com/doc/documentation/plugins/teleinfo/fr_FR/teleinfo
 https://www.kzenjoy.net/2015/la-teleinformation-sous-jeedom/
 http://playground.arduino.cc/Code/Interrupts
 https://github.com/jaysee/teleInfo
 http://playground.arduino.cc/Main/PinChangeInterrupt
 https://code.google.com/archive/p/arduino-pinchangeint/issues/7

-----------------------------------------------------------------------
 P. Wieser - Created on 2017, mar. 31st
             Last updated on 2017, apr. 2nd