============
API examples
============


Setting things up
-----------------

To get the example code, clone the ekmdevice `repository <https://github.com/ekmmetering/ekmdevice>`_:

.. code::

    git clone https://github.com/ekmmetering/ekmdevice.git

Install the **ekmdevice** Python package. 
It is highly recommended you create a `virtualenv <https://docs.python.org/3/tutorial/venv.html>`_.

.. code::

    cd ekmdevice
    python -m venv venv
    . venv/bin/activate
    python -m pip install .

Example code is in the **ekmdevice/examples** directory:

.. code::

    cd examples

Connect one or more meters and iostacks to your computer using a
`USB-rs485 adapter <https://www.ekmmetering.com/collections/all-products/products/ekm-blink-rs-485-to-usb-converter>`_.

Once the adapter is plugged in, determine the name of the serial port.

These articles may be helpful:

- `COM/Serial port name <https://learn.adafruit.com/ftdi-friend/com-slash-serial-port-name>`_
- `How to Install an Omnimeter <https://help.ekmmetering.com/support/solutions/articles/6000129981-how-to-install-an-omnimeter-video->`_
- `Remote water, gas and electricity metering <https://help.ekmmetering.com/support/solutions/articles/6000081681-electricity-and-or-water-and-or-gas-metering>`_


Meter examples
--------------

In these examples the serial port will be **/dev/ttyUSB0**
and the meter is a **v4** Omnimeter with address **30001**.

Note that meter version and address can be specified as a number or a string.
So **v4** can be **4**, **"4"**, or **"v4"**, and address can be
**30001**, **"30001"**, or **"000000030001"**.


Example: Read A and B meter data
..............................................

**v4** meters have both A and B data which must be read
separately. The :func:`read_data()` function performs 
both if *include_b* is *True*.

**meter_read.py**

.. literalinclude:: ../examples/meter_read.py
    :language: python

If you have a heterogenous collection of devices connected to the
RS-485 bus then it's generally a good idea to end the read session
by setting *end_session=True*. This will ensure the meter is no longer
listening for command messages until the next read, which lessens
the chance that serial traffic to/from other devices will confuse
the meter:

.. code-block:: python

    data = ekmmeter.read_data(sp, 4, 300001285, include_b=True, end_session=True)


Run the code:

.. code::

    $ python meter_read.py
    {
      "Model": "1024",
      "Firmware": "45",
      "Meter_Address": "000000030001",
      "kWh_Tot": 2692.0,
      "Reactive_Energy_Tot": 1139.0,
      "Rev_kWh_Tot": 0.0,
      "kWh_Ln_1": 2693.0,
      "kWh_Ln_2": 0.0,
      "kWh_Ln_3": 0.0,
      "Rev_kWh_Ln_1": 0.0,
      "Rev_kWh_Ln_2": 0.0,
      "Rev_kWh_Ln_3": 0.0,
      "kWh_Rst": 0.0884,
      "Rev_kWh_Rst": 0.0,
      "RMS_Volts_Ln_1": 123.5,
      "RMS_Volts_Ln_2": 0.0,
      "RMS_Volts_Ln_3": 0.0,
      "Amps_Ln_1": 4.0,
      "Amps_Ln_2": 0.0,
      "Amps_Ln_3": 0.0,
      "RMS_Watts_Ln_1": 340,
      "RMS_Watts_Ln_2": 0,
      "RMS_Watts_Ln_3": 0,
      "RMS_Watts_Tot": 340,
      "Cos_Theta_Ln_1": "C087",
      "Cos_Theta_Ln_2": "C000",
      "Cos_Theta_Ln_3": "C000",
      "Reactive_Pwr_Ln_1": 180,
      "Reactive_Pwr_Ln_2": 0,
      "Reactive_Pwr_Ln_3": 0,
      "Reactive_Pwr_Tot": 180,
      "Line_Freq": 60.06,
      "Pulse_Cnt_1": 4851608,
      "Pulse_Cnt_2": 0,
      "Pulse_Cnt_3": 0,
      "State_Inputs": 4,
      "State_Watts_Dir": 1,
      "State_Out": 1,
      "kWh_Scale": 4,
      "Meter_Time": "24052904112724",
      "Request_Type": 1,
      "kWh_Tariff_1": 148.0,
      "kWh_Tariff_2": 481.0,
      "kWh_Tariff_3": 175.0,
      "kWh_Tariff_4": 1887.0,
      "Rev_kWh_Tariff_1": 0.0,
      "Rev_kWh_Tariff_2": 0.0,
      "Rev_kWh_Tariff_3": 0.0,
      "Rev_kWh_Tariff_4": 0.0,
      "RMS_Watts_Max_Demand": 170.0,
      "Max_Demand_Period": 4,
      "Pulse_Ratio_1": 1,
      "Pulse_Ratio_2": 1,
      "Pulse_Ratio_3": 1,
      "CT_Ratio": 2000,
      "Max_Demand_Rst": 4,
      "CF_Ratio": 5,
      "Meter_Status_Code_A": "00",
      "Meter_Status_Code_B": "01",
      "Meter_Status_Code_C": "00"
    }


Example: Set meter relay
........................

This example will close relay 1 for one second.

**meter_set_relay.py**

.. literalinclude:: ../examples/meter_set_relay.py
    :language: python

Run the code:

.. code::

    python meter_set_relay.py


Note that meter commands require a read before sending a command message.
The :func:`start_cmd_session` function will perform a read without
unpacking the data which uses slightly less resources than :func:`read_data`.

If you would like to use the read data you can substitute :func:`read_data`
for :func:`start_cmd_session`:

**meter_set_relay2.py**

.. literalinclude:: ../examples/meter_set_relay2.py
    :language: python


ioStack examples
----------------

In these examples the serial port will be **/dev/ttyUSB0**
and the ioStack will have the address **10001**.

ioStacks use a different serial protocol than what meters
use, so the serial port must be reconfigured if meters are
used on the same serial port.


Example: Get ioStack status
...........................

Getting the status using :func:`get_status()`:

**iostack_get_status.py**

.. literalinclude:: ../examples/iostack_get_status.py
    :language: python

Run the code:

.. code::

    $ python iostack_get_status.py
    {
      "hw_type": 133,
      "model": 1,
      "version_major": 1,
      "version_minor": 2,
      "lifetime_ms": 10139455050,
      "chip_id": "0009ffffffffffff4e4553157009000e",
      "rtc_period": 60,
      "rtc_offset": 1,
      "device_time": "2024-05-28T18:52:10"
    }

Example: Read ioStack data
..........................

Reading data using the :func:`read_a()` API function.

**iostack_read_a.py**

.. literalinclude:: ../examples/iostack_read_a.py
    :language: python

Run the code:

.. code::

    $ python iostack_read_a.py
    {
      "hw_type": 133,
      "model": 1,
      "version_major": 99,
      "version_minor": 2,
      "device_time": "2024-05-28T18:46:54",
      "lifetime_ms": 10139138540,
      "ai_count": 4,
      "ai_values": [
        2405,
        1095,
        905,
        856
      ],
      "ai_watch": [
        0,
        0,
        0,
        0
      ],
      "di_count": 4,
      "di_levels": 0,
      "di_cwatch": [
        0,
        0,
        0,
        0
      ],
      "di_lwatch": [
        0,
        0,
        0,
        0
      ],
      "di_rwatch": [
        0,
        0,
        0,
        0
      ],
      "do_count": 4,
      "do_levels": 1,
      "do_owner": [
        16,
        0,
        0,
        0
      ],
      "ow_dio_count": 0,
      "ow_dio": [],
      "ow_thl_count": 4,
      "ow_thl": [
        {
          "slot": 1,
          "temp": 180,
          "humidity": 255,
          "lux": 65535
        },
        {
          "slot": 17,
          "temp": 186,
          "humidity": 255,
          "lux": 65535
        },
        {
          "slot": 33,
          "temp": 185,
          "humidity": 255,
          "lux": 65535
        },
        {
          "slot": 49,
          "temp": 185,
          "humidity": 255,
          "lux": 65535
        }
      ]
    }

Example: Read ioStack data A and B with EKM field names
.......................................................

Read data using :func:`read_data()` which performs both
:func:`read_a()` and :func:`read_b()`,
and translates data to a flat dictionary of EKM field names/values
that matches the `EKM REST API <https://api.ekmapi.com>`_.

EKM field name information for ioStacks can be found
`here <https://api.ekmpush.com/help/iostackfields.html>`_.

**iostack_read_data.py**

.. literalinclude:: ../examples/iostack_read_data.py
    :language: python

Run the code:

.. code::

    $ python iostack_read_data.py
    {
      "Firmware": "99.2",
      "Hardware_Type": 133,
      "Model": 1,
      "Device_Time": "2024-05-28T18:35:05",
      "State_Inputs": 0,
      "State_Out": 1,
      "Analog_In_1": 2406,
      "Analog_In_2": 1249,
      "Analog_In_3": 948,
      "Analog_In_4": 836,
      "Pulse_Hold_ms_1": 8733567548,
      "Pulse_Hold_ms_2": 8733567548,
      "Pulse_Hold_ms_3": 8733567548,
      "Pulse_Hold_ms_4": 8733567548,
      "Pulse_Hi_Prev_ms_1": 0,
      "Pulse_Hi_Prev_ms_2": 0,
      "Pulse_Hi_Prev_ms_3": 0,
      "Pulse_Hi_Prev_ms_4": 0,
      "Pulse_Lo_Prev_ms_1": 0,
      "Pulse_Lo_Prev_ms_2": 0,
      "Pulse_Lo_Prev_ms_3": 0,
      "Pulse_Lo_Prev_ms_4": 0,
      "Pulse_Cnt_Rst_1": 0,
      "Pulse_Cnt_Rst_2": 0,
      "Pulse_Cnt_Rst_3": 0,
      "Pulse_Cnt_Rst_4": 0,
      "Pulse_Cnt_1": 0,
      "Pulse_Cnt_2": 0,
      "Pulse_Cnt_3": 0,
      "Pulse_Cnt_4": 0,
      "Pulse_Hi_Total_sec_1": 0,
      "Pulse_Hi_Total_sec_2": 0,
      "Pulse_Hi_Total_sec_3": 0,
      "Pulse_Hi_Total_sec_4": 0,
      "Pulse_Lo_Total_sec_1": 10138429,
      "Pulse_Lo_Total_sec_2": 10138429,
      "Pulse_Lo_Total_sec_3": 10138429,
      "Pulse_Lo_Total_sec_4": 10138429,
      "OW_1_1_degC": 18.0,
      "OW_1_1_Humidity": 255,
      "OW_1_1_Lux": 65535,
      "OW_2_1_degC": 18.6,
      "OW_2_1_Humidity": 255,
      "OW_2_1_Lux": 65535,
      "OW_3_1_degC": 18.4,
      "OW_3_1_Humidity": 255,
      "OW_3_1_Lux": 65535,
      "OW_4_1_degC": 18.5,
      "OW_4_1_Humidity": 255,
      "OW_4_1_Lux": 65535
    }


Reading multiple devices and storing data
-----------------------------------------

When multiple devices are connected to a single RS485 serial
bus.

Read loop
.........

This example program continuously reads a set of devices (meters/iostacks)
and stores the data in a SQL database (SQLite in this case).
You can specify the serial port and list of devices in
a `TOML <https://toml.io>`_ configuration file.

To run the program you will need to have installed the ekmdevice package already.
To exit the program press Ctrl-C.

.. code::

    python readloop.py

An example configuration **examples/readloop.toml**:

.. literalinclude:: ../examples/readloop.toml
    :language: toml

Source code:

**readloop.py**

.. literalinclude:: ../examples/readloop.py
    :language: python


Getting stored data
...................

If you have `SQLite <https://www.sqlite.org/download.html>`_ installed,
start a SQLite session with the file path name of the database
created by **readloop.py**::

    $ sqlite3 ekmdata.db
    SQLite version 3.37.2 2022-01-06 13:25:41
    Enter ".help" for usage hints.
    sqlite>

Set the output mode::

    sqlite> .mode column

Try the following query to get the most recent value of the meter field
**kWh_Tot** for meter 300001317 (use your own meter address)::

    sqlite> select datetime(timestamp/1000, 'unixepoch', 'localtime') as time, json_extract(data, '$.kWh_Tot') as kWh from meter_data where address = '000300001317' order by timestamp desc limit 1;
    time                 kWh
    -------------------  ------
    2024-06-02 14:06:26  1724.0


A simple web form
.................

This is a very simple web server that will query the SQL database created
by **readloop.py** and displays the last stored value
of a device field (a meter "kWh_Tot" field by default).

To run:

.. code::

    cd examples
    python readserv.py

Open a web browser and type this url in the address bar (or just click on the link): http://localhost:8000

.. figure:: /_images/readserv-browser.png
    :class: with-border
    :alt: Screenshot of browser showing example form.

    What you should see when navigating to http://localhost:8000

Enter your device type, address, and field name in the displayed form.
Then click on the **Query** button.

.. figure:: /_images/readserv-browser2.png
    :class: with-border
    :alt: Screenshot of browser showing example form and results.

    Example of what you should see after filling in meter address and clicking on "Query".

Source code:

**readserv.py**

.. literalinclude:: ../examples/readserv.py
    :language: python