Skip to content

Commit 94577f8

Browse files
OverdrivrOverdrivr
committed
Merge pull request #32 from Overdrivr/improved-readme
Improved readme
2 parents 2cf32fa + 755c942 commit 94577f8

3 files changed

Lines changed: 139 additions & 78 deletions

File tree

‎DESCRIPTION.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
Pytelemetry Command Line Interface
2+
====================================
3+
4+
This module is a powerful command line interface for extremely fast debugging and communication with embedded systems.
5+
6+
It allows for plotting embedded device's data on-the-fly, publishing values on any topics, listing serial ports and much more.
7+
8+
The CLI relies on custom protocol, implemented in Python and C languages.
9+
The main strength of this protocol is strong decoupling between communicating devices, simplicity yet flexibility.
10+
11+
For instance, the protocol supports sending standard linear data, but also arrays and sparse arrays in a network-friendly manner.
12+
13+
- `Project page <https://github.com/Overdrivr/pytelemetrycli>`__
14+
15+
.. image:: https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/console.png
16+
17+
.. image:: https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/graph.png
18+
19+
pytelemetry
20+
============
21+
22+
This module is the Python implementation of the communication protocol.
23+
24+
It can be used directly (without the CLI) to script communications with an embedded device.
25+
26+
.. code:: python
27+
28+
from pytelemetry import Pytelemetry
29+
from pytelemetry.transports.serialtransport import SerialTransport
30+
import time
31+
32+
transport = SerialTransport()
33+
tlm = Pytelemetry(transport)
34+
transport.connect({port:'com9',baudrate:'9600'})
35+
36+
# publish once on topic 'throttle' (a named communication channel)
37+
tlm.publish('throttle',0.8,'float32')
38+
39+
def printer(topic, data, opts):
40+
print(topic," : ", data)
41+
42+
# Subscribe a `printer` function called on every frame with topic 'feedback'.
43+
tlm.subscribe("feedback", printer)
44+
45+
# Update during 3 seconds
46+
timeout = time.time() + 3
47+
while True:
48+
tlm.update()
49+
if time.time() > timeout:
50+
break
51+
52+
# disconnect
53+
transport.disconnect()
54+
print("Done.")
55+
56+
Language C implementation
57+
=========================
58+
59+
Telemetry is the same protocol implemented in C language.
60+
61+
- `Project page <https://github.com/Overdrivr/Telemetry>`__
62+
63+
Centralized documentation
64+
=========================
65+
66+
The documentation for all three projects is centralized `here <https://github.com/Overdrivr/Telemetry/wiki>`_.
67+
68+
MIT License, (C) 2015-2016 Rémi Bèges (remi.beges@gmail.com)

‎README.md‎

Lines changed: 65 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,31 @@
1-
[![PyPI version](https://badge.fury.io/py/pytelemetrycli.svg)](https://badge.fury.io/py/pytelemetrycli) [![Join the chat at https://gitter.im/Overdrivr/pytelemetry](https://badges.gitter.im/Overdrivr/pytelemetry.svg)](https://gitter.im/Overdrivr/pytelemetry?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Stories in Ready](https://badge.waffle.io/Overdrivr/pytelemetrycli.svg?label=ready&title=Ready)](http://waffle.io/Overdrivr/pytelemetrycli)
1+
[![PyPI version](https://badge.fury.io/py/pytelemetrycli.svg)](https://badge.fury.io/py/pytelemetrycli)
2+
[![Join the chat at https://gitter.im/Overdrivr/pytelemetry](https://badges.gitter.im/Overdrivr/pytelemetry.svg)](https://gitter.im/Overdrivr/pytelemetry?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
3+
*Windows:* [![Build status](https://ci.appveyor.com/api/projects/status/35jkrkiu03dfav9v/branch/master?svg=true)](https://ci.appveyor.com/project/Overdrivr/pytelemetrycli/branch/master)
4+
*Unix* [![Build Status](https://travis-ci.org/Overdrivr/pytelemetrycli.svg?branch=master)](https://travis-ci.org/Overdrivr/pytelemetrycli)
5+
[![Stories in Ready](https://badge.waffle.io/Overdrivr/pytelemetrycli.svg?label=ready&title=Ready)](http://waffle.io/Overdrivr/pytelemetrycli)
26

37
## pytelemetry command line interface
48

5-
This tool enables superior communication with any embedded device. It is for you if:
9+
This tool is a command-line interface (CLI). It enables superior communication with any embedded device. It was designed for:
610

7-
* you are using `printf` to debug your application
8-
* you are all the time re-writing custom protocols for the serial port
9-
* you need a **reliable** and **error-tolerant** communication protocol
10-
* you want to finely tune your application without loosing time compiling & flashing just to tune a parameter
11-
* you want to **plot** parameters on the device in **real-time**
12-
* your embedded device has very limited resources and will tolerate only a lightweight communication library
11+
* **fast prototyping and debugging**. Set everything up in a few minutes and start debugging any embedded device efficiently. Forget about `printf`. Forever.
12+
* **communication-based applications**. Stop re-writing custom protocols for each new project.
13+
* **real-time update of embedded application parameters**. Tune your application without loosing time compiling & flashing just for parameter tuning.
14+
* **plot** data from the device in real-time. Standard linear data is supported, but also arrays, sparse arrays. In the future, also Matrices, XYZ, and RGB-type codes.
15+
* **Reusability**. The protocol is highly flexible, loosely coupled to your application. It can be used in a wide number of application scenarios.
1316

1417
## overview
15-
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.
18+
This CLI provides a set of commands to connect to a device, read, plot, write data on it, log any received and sent data.
1619

17-
![Overview](https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/overview.png)
20+
*In the future*: export to Excel and CSV and replay command in the CLI for offline inspection.
1821

19-
pytelemetry-cli relies on [`pytelemetry`](https://github.com/Overdrivr/pytelemetry)
20-
[![PyPI version](https://badge.fury.io/py/pytelemetry.svg)](https://badge.fury.io/py/pytelemetry)
21-
to implement the specific communication protocol.
22+
The communication protocol that carry all exchanged information is implemented in Python and C:
23+
* [`pytelemetry`](https://github.com/Overdrivr/pytelemetry)[![PyPI version](https://badge.fury.io/py/pytelemetry.svg)](https://badge.fury.io/py/pytelemetry) for scripting the communication from your PC
24+
* [`telemetry`](https://github.com/Overdrivr/pytelemetry): for enabling communication in the embedded device.
2225

23-
To communicate with the device, you only need to make your device use the [`telemetry`](https://github.com/Overdrivr/pytelemetry)
24-
library.
26+
Officially supported embedded platforms are for now `Arduino` and `Mbed`.
2527

26-
## principle
27-
The underlying communication protocol mostly follows the [PubSub](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern)(publish/subscribe) messaging pattern.
28-
29-
> [..] messages are published to "topics" or named logical channels. Subscribers in a topic-based system will receive all messages published to
30-
> the topics to which they subscribe [..].
31-
> *Source: Wikipedia*
28+
See the [central documentation](https://github.com/Overdrivr/Telemetry/wiki) for installation instructions, tutorials, description of the protocol, etc.
3229

3330
## interface and plot widget
3431
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`
@@ -37,49 +34,6 @@ Aan example of listing serial ports `ls -s`, connecting to a device through COM2
3734

3835
![Plot example](https://raw.githubusercontent.com/Overdrivr/pytelemetrycli/master/graph.png)
3936

40-
41-
## installation
42-
`pytelemetrycli` requires python 3.5+, PyQt4 and numpy.
43-
44-
### Windows
45-
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).
46-
47-
In case you were wondering, **no** you **don't** have to install Qt. The binary wheel is enough.
48-
49-
Then install with pip the downloaded files
50-
51-
```bash
52-
pip install numpy-x.xx.x+vanilla-cp3x-none-winxxx.whl
53-
pip install PyQt4-x.xx.x-cp3x-none-winxxx.whl
54-
```
55-
56-
Then, simply install `pytelemetrycli` with pip as usual
57-
58-
```bash
59-
pip install pytelemetrycli
60-
```
61-
62-
### Mac OS
63-
The easiest way to install numpy and PyQt4 seem to be using `homebrew`.
64-
lease note that you should also have installed python 3.5 with homebrew for this to work correctly.
65-
Also, avoid to have another python 3.5 distribution on your system otherwise you will face import issues as well.
66-
67-
```bash
68-
brew install python3
69-
brew install pyqt --with-python3
70-
pip3 install pytelemetrycli
71-
```
72-
73-
### Linux
74-
75-
?
76-
77-
## setup for embedded devices
78-
To setup telemetry on any embedded device, please refer to the [`Telemetry`](https://github.com/Overdrivr/Telemetry) repository.
79-
80-
If you only wish to test the command-line interface, you can also directly flash a test firmware from our own [collection](#)
81-
*Note: in process. In the future we will support a variety of devices so you can quickly start on with the command line.*
82-
8337
## List of commands
8438
The command line interface can be started like this
8539
```
@@ -129,7 +83,7 @@ Options:
12983
```bash
13084
Publishes a (value | string) on <topic>.
13185

132-
Usage: pub <topic> <value> (--u8 | --u16 | --u32 | --i8 | --i16 | --i32 | --f32 | --s)
86+
Usage: pub (--u8 | --u16 | --u32 | --i8 | --i16 | --i32 | --f32 | --s) <topic> <value>
13387
```
13488

13589
### plot
@@ -152,3 +106,49 @@ Exits the terminal application.
152106

153107
Usage: quit
154108
```
109+
110+
## installation
111+
`pytelemetrycli` requires python 3.3+, PyQt4 and numpy.
112+
113+
### Windows
114+
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).
115+
116+
In case you were wondering, **no** you **don't** have to install Qt. The binary wheel is enough.
117+
118+
Then install with pip the downloaded files
119+
120+
```bash
121+
pip install numpy-x.xx.x+vanilla-cp3x-none-winxxx.whl
122+
pip install PyQt4-x.xx.x-cp3x-none-winxxx.whl
123+
```
124+
125+
Then, simply install `pytelemetrycli` with pip as usual
126+
127+
```bash
128+
pip install pytelemetrycli
129+
```
130+
131+
### Mac OS
132+
The easiest way to install numpy and PyQt4 seem to be using `homebrew`.
133+
lease note that you should also have installed python 3.5 with homebrew for this to work correctly.
134+
Also, avoid to have another python 3.5 distribution on your system otherwise you will face import issues as well.
135+
136+
```bash
137+
brew install python3
138+
brew install pyqt --with-python3
139+
pip3 install pytelemetrycli
140+
```
141+
142+
### Linux
143+
144+
The setup used for testing relies on miniconda.
145+
```
146+
conda install numpy
147+
conda install pyqt
148+
conda install pip
149+
pip install pytelemetrycli
150+
```
151+
However, if you have PyQt4 and numpy already installed in your directory, simply run
152+
```
153+
pip install pytelemetrycli
154+
```

‎setup.py‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,17 @@
22
from codecs import open
33
from os import path
44
from setuptools.dist import Distribution
5-
import pypandoc
6-
7-
try:
8-
long_description = pypandoc.convert('README.md', 'rst')
9-
long_description = long_description.replace("\r","")
10-
except OSError:
11-
print("Pandoc not found. Long_description conversion failure.")
12-
import io
13-
# pandoc is not installed, fallback to using raw contents
14-
with io.open('README.md', encoding="utf-8") as f:
15-
long_description = f.read()
5+
import io
6+
7+
with io.open('DESCRIPTION.rst', encoding="utf-8") as f:
8+
long_description = f.read()
169

1710
setup(
1811
name='pytelemetrycli',
1912

2013
version='1.0.4',
2114

22-
description='command-line interface for superior communication with any embedded device.',
15+
description='command-line interface for superior communication with embedded devices.',
2316
long_description=long_description,
2417

2518
url='https://github.com/Overdrivr/pytelemetrycli',
@@ -61,7 +54,7 @@
6154
# your project is installed. For an analysis of "install_requires" vs pip's
6255
# requirements files see:
6356
# https://packaging.python.org/en/latest/requirements.html
64-
install_requires=['pytelemetry>1.1.0','pyserial>3.0.0','docopt','pyqtgraph','numpy','sortedcontainers',],
57+
install_requires=['pytelemetry>1.1.4','pyserial>3.0.0','docopt','pyqtgraph','numpy','sortedcontainers',],
6558

6659
# List additional groups of dependencies here (e.g. development
6760
# dependencies). You can install these using the following syntax,

0 commit comments

Comments
 (0)