====================
Command line utility
====================

**ekmdevice** is a command line script that
sends commands to a meter or iostack device using
the **ekmdevice API**.
It is available when the **ekmdevice** package is
installed.

It can be useful for checking connectivity,
trying out commands,
and looking at serial traffic and response data.


Installation
------------

Install the ekmdevice package.

.. code::

    pip install ekmdevice


Usage
-----

To see usage and command line options:

.. code::

    ekmdevice --help


Usage examples
--------------

To get the status data for an iostack device with an address (serial number) of 1:

.. code::

    ekmdevice --port /dev/ttyUSB0 iostack 1 get_status

To see the output as JSON use **--json** option:

.. code::

    ekmdevice --port /dev/ttyUSB0 --json iostack 1 get_status


To see the serial port traffic use **--verbose** option:

.. code::

    ekmdevice --port /dev/ttyUSB0 --verbose iostack 1 get_status


To request the READ data from a v3 Omnimeter with an address of 000000020870::

    ekmdevice --port /dev/ttyUSB0 meter.v3 20870 read_data

Note that if version is left unspecified the default meter version is *v4*::

    ekmdevice --port /dev/ttyUSB0 meter 300001317 read_data


Specifying function arguments
.............................

Specify API function call arguments by adding them at the end of the
comman line. Python kwarg type arguments can be specified using the
Python style <name>=<value> syntax::

    ekmdevice --port /dev/ttyUSB0 iostack 1 read_data include_b=True


API help
........

To get API help for a particular function:

.. code::

    ekmdevice <device-type> help <command>

Example:

.. code::

    ekmdevice meter help read_a


List serial ports
.................

To see a list of available serial ports:

.. code::

    ekmdevice ports



Recover ioStack serial port baudrate
....................................

In case an ioStack device is set to an unknown baudrate this command
attempts to determine what the current baudrate is and reset it to
a specified or default baudrate.


.. code::

    ekmdevice --port /dev/ttyUSB0 iostack 1 recover_baudrate