Metadata-Version: 2.0
Name: pytelemetrycli
Version: 1.0.4
Summary: command-line interface for superior communication with any embedded device.
Home-page: https://github.com/Overdrivr/pytelemetrycli
Author: Rémi Bèges
Author-email: remi.beges@gmail.com
License: MIT
Keywords: cli plot debug lightweight communication protocol embedded telemetry remote program control
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: Communications
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: docopt
Requires-Dist: numpy
Requires-Dist: pyqtgraph
Requires-Dist: pyserial
Requires-Dist: pytelemetry (>1.1.0)
Requires-Dist: sortedcontainers
Provides-Extra: dev
Requires-Dist: check-manifest; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'

|PyPI version| |Join the chat at
https://gitter.im/Overdrivr/pytelemetry| |Stories in Ready|

pytelemetry command line interface
----------------------------------

This tool enables superior communication with any embedded device. It is
for you if:

-  you are using ``printf`` to debug your application
-  you are all the time re-writing custom protocols for the serial port
-  you need a **reliable** and **error-tolerant** communication protocol
-  you want to finely tune your application without loosing time
   compiling & flashing just to tune a parameter
-  you want to **plot** parameters on the device in **real-time**
-  your embedded device has very limited resources and will tolerate
   only a lightweight communication library

overview
--------

pytelemetry-cli is a **command line interface**. It provides a set of
commands to connect to a device, read, plot and write data on it.

.. figure:: https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/overview.png
   :alt: Overview

   Overview

pytelemetry-cli relies on
```pytelemetry`` <https://github.com/Overdrivr/pytelemetry>`__ |PyPI
version| to implement the specific communication protocol.

To communicate with the device, you only need to make your device use
the ```telemetry`` <https://github.com/Overdrivr/pytelemetry>`__
library.

principle
---------

The underlying communication protocol mostly follows the
`PubSub <https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern>`__\ (publish/subscribe)
messaging pattern.

    [..] messages are published to "topics" or named logical channels.
    Subscribers in a topic-based system will receive all messages
    published to the topics to which they subscribe [..]. *Source:
    Wikipedia*

interface and plot widget
-------------------------

Aan example of listing serial ports ``ls -s``, connecting to a device
through COM20 ``serial com20 --bauds 115200``, listing all received
topics ``ls`` and opening a plot on topic touch ``plot touch``

.. figure:: https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/console.png
   :alt: Console example

   Console example

.. figure:: https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/graph.png
   :alt: Plot example

   Plot example

installation
------------

``pytelemetrycli`` requires python 3.5+, PyQt4 and numpy.

Windows
~~~~~~~

It is recommended to download
```numpy`` <http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy>`__ and
```PyQt4`` <http://www.lfd.uci.edu/~gohlke/pythonlibs/#pyqt4>`__ wheels
python packages (courtesy of Christoph Gohlke).

In case you were wondering, **no** you **don't** have to install Qt. The
binary wheel is enough.

Then install with pip the downloaded files

.. code:: bash

    pip install numpy-x.xx.x+vanilla-cp3x-none-winxxx.whl
    pip install PyQt4-x.xx.x-cp3x-none-winxxx.whl

Then, simply install ``pytelemetrycli`` with pip as usual

.. code:: bash

    pip install pytelemetrycli

Mac OS
~~~~~~

The easiest way to install numpy and PyQt4 seem to be using
``homebrew``. lease note that you should also have installed python 3.5
with homebrew for this to work correctly. Also, avoid to have another
python 3.5 distribution on your system otherwise you will face import
issues as well.

.. code:: bash

    brew install python3
    brew install pyqt --with-python3
    pip3 install pytelemetrycli

Linux
~~~~~

?

setup for embedded devices
--------------------------

To setup telemetry on any embedded device, please refer to the
```Telemetry`` <https://github.com/Overdrivr/Telemetry>`__ repository.

If you only wish to test the command-line interface, you can also
directly flash a test firmware from our own `collection <#>`__ *Note: in
process. In the future we will support a variety of devices so you can
quickly start on with the command line.*

List of commands
----------------

The command line interface can be started like this

::

    python3 -m pytelemetrycli.cli

or more simply

::

    pytlm

If everything is installed properly, ``:>`` should welcome you.

::

    pytelemetry terminal started. (type help for a list of commands.)
    :> _

help [command]
~~~~~~~~~~~~~~

Without arguments, you get a list of all available commands. Otherwise
the full ``command`` documentation.

ls
~~

.. code:: bash

    Without options, prints a list of all received topics.
    With the --serial flag, prints a list of all available COM ports

    Usage: ls [options]

    Options:
    -s, --serial     Use this flag to print a list of all available serial ports

serial
~~~~~~

.. code:: bash

    Connects pytelemetry to the serial port.

    Usage: serial <port> [options]

    Options:
    -b X, --bauds X        Connection speed in bauds  [default: 9600]

print
~~~~~

.. code:: bash

    Prints X last received samples from <topic>.

    Usage: print <topic> [options]

    Options:
    -a X, --amount X        Amount of samples to display [default: 1]

pub
~~~

.. code:: bash

    Publishes a (value | string) on <topic>.

    Usage: pub <topic> <value> (--u8 | --u16 | --u32 | --i8 | --i16 | --i32 | --f32 | --s)

plot
~~~~

.. code:: bash

    Plots <topic> in a graph window.

    Usage: plot <topic>

disconnect
~~~~~~~~~~

.. code:: bash

    Disconnects from any open connection.

    Usage: disconnect

quit
~~~~

.. code:: bash

    Exits the terminal application.

    Usage: quit

.. |PyPI version| image:: https://badge.fury.io/py/pytelemetrycli.svg
   :target: https://badge.fury.io/py/pytelemetrycli
.. |Join the chat at https://gitter.im/Overdrivr/pytelemetry| image:: https://badges.gitter.im/Overdrivr/pytelemetry.svg
   :target: https://gitter.im/Overdrivr/pytelemetry?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
.. |Stories in Ready| image:: https://badge.waffle.io/Overdrivr/pytelemetrycli.svg?label=ready&title=Ready
   :target: http://waffle.io/Overdrivr/pytelemetrycli
.. |PyPI version| image:: https://badge.fury.io/py/pytelemetry.svg
   :target: https://badge.fury.io/py/pytelemetry


