Metadata-Version: 2.0
Name: pytelemetry
Version: 1.1.3
Summary: Lightweight remote monitoring and control of embedded devices
Home-page: https://github.com/Overdrivr/pytelemetry
Author: Rémi Bèges
Author-email: remi.beges@gmail.com
License: MIT
Keywords: 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.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: enum34
Requires-Dist: pyserial
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| |Build
status| # pytelemetry

``pytelemetry`` enables remote monitoring and control of embedded
devices. Specifically, ``pytelemetry`` implements a custom communication
protocol, based on 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*

This communication protocol is also available in a C library called
```telemetry`` <https://github.com/Overdrivr/telemetry>`__ that is
specifically designed to run on all platforms and to be as light as
possible.

.. figure:: https://raw.githubusercontent.com/Overdrivr/pytelemetry/master/simple_overview.png
   :alt: Overview

   Overview

Don't forget to check the
```bonus`` <https://github.com/Overdrivr/pytelemetry#bonus>`__ at the
end.

Usage
-----

Data is published on ``topics``. Topics can be seen as named
communication channels.

First, instanciate one of the available transport class (*Note: so far,
only serial transport is implemented*). Then create a ``Pytelemetry``
object.

.. code:: python

    from pytelemetry.pytelemetry import Pytelemetry
    from pytelemetry.transports.serialtransport import SerialTransport
    import time

    # create a transport (Here based on pyserial)
    transport = SerialTransport()
    tlm = Pytelemetry(transport)

Connect the serial transport to serial port ``COM20`` at ``9600`` bauds.

.. code:: python


    # connection options
    options = dict()
    options['port'] = "COM20"
    options['baudrate'] = 9600

    # connect
    transport.connect(options)

Publish once to topic named ``throttle``, sending effectively the value
``0.8`` of type ``float`` to the embedded device.

.. code:: python


    # publish on a topic
    tlm.publish('throttle',0.8,'float32')

Subscribe a ``printer`` function to all received topics. Basically, this
function will be called everytime a new frame is received.

.. code:: python

    def printer(topic, data):
        print(topic," : ", data)

    # subscribe to a topic. Subscribing to None subscribes to all
    tlm.subscribe(None, printer)

Then, run an update during 3 seconds and disconnect after.

.. code:: python

    # Update during 3 seconds
    timeout = time.time() + 3
    while True:
        tlm.update()
        if time.time() > timeout:
            break

    # disconnect
    transport.disconnect()
    print("Done.")

If the embedded device published regularly on topic ``foo`` with an
incrementing value, you should see in the console:

.. code:: bash

    foo : 34
    foo : 35
    foo : 36
    foo : 37
    Done.

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

Python 3.5 is supported. Support for python 3.4 and 3.3 will be added in
a near future.

.. code:: bash

    pip3 install pytelemetry

Future improvements
-------------------

In the next milestone, it is planned to make topics more meaningful (on
the python-implementation only). \* Publishing to topics like ``foo:2``,
will add indexing data. This will add a nice support for arrays and
sparse arrays. \* Publishing to topics like ``bar\foo``, will add group
data. This will indicate that there is a group called ``bar``, with a
subtopic called ``foo`` \* Combination :
``bar\foobar\foo``,\ ``bar\foobar\foo:2`` \* Multiple instances :
``bar\12\foo`` will be understood as ``foo`` instance number 12 (useful
if you want to have multiple instances under a same topic name)

For both python and C implementations of the protocol, it is also
planned: \* add string compression with Huffman's Algorithm \* replace
the byte stuffing algorithm by a consistent-over byte stuffing algorithm

Both will contribute to reduce overhead and frames size.

Bonus
-----

You should also check the awesome command line interface
```pytelemetrycli`` <https://github.com/Overdrivr/pytelemetrycli>`__\ |PyPI
version|

It makes communicating and debugging your embedded application
effortless. With a few commands, it is possible to open high-performance
graphs and plot your data in real time, list all available data
channels, print samples of channel and much more.

.. |PyPI version| image:: https://badge.fury.io/py/pytelemetry.svg
   :target: https://badge.fury.io/py/pytelemetry
.. |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
.. |Build status| image:: https://ci.appveyor.com/api/projects/status/03jtmphrld6k185v/branch/master?svg=true&passingText=master%20:%20OK&failingText=master%20:%20fail&pendingText=master%20:%20pending
   :target: https://ci.appveyor.com/project/Overdrivr/pytelemetry/branch/master
.. |PyPI version| image:: https://badge.fury.io/py/pytelemetrycli.svg
   :target: https://badge.fury.io/py/pytelemetrycli


