# HG changeset patch
# User David Douard <david.douard@logilab.fr>
# Date 1526594694 -7200
# Node ID 1ac1457af83f6fdd31daf0609246d8ad069b2f12
# Parent  b459d4bc07cf64faefd914d61270b78af1d64df3
[readme] write a more meaningful README file

diff -r b459d4bc07cf -r 1ac1457af83f README
--- a/README	Fri May 18 00:04:18 2018 +0200
+++ b/README	Fri May 18 00:04:54 2018 +0200
@@ -1,9 +1,77 @@
-pygpibtoolkit is (c) 2007-2018 David Douard
-and is available under the GNU General Public Licence v2.
+===============
+ pygpibtoolkit
+===============
+
+pygpibtoolkit_ is a pure Python 3 toolkit for managing and controlling test
+equipment via the GPIB_ (aka IEEE-488) bus.
+
+Currently, it only supports Prologix_ compatible GPIB dongles, but support for
+linux-gpib_ is planned.
+
+Installation
+============
+
+The simplest way to install pygpibtoolkit_ is to use pip_. I strongly recommend
+you use virtualenvs_ for this, for example via virtualenvwrapper_ or pew_. Here
+is an example session using virtualenvwrapper_ on a Debian stretch machine:
+
+.. code-block:: bash
+
+   david@host:~$ mkvirtualenv -p /usr/bin/python3 pygpib
+   Already using interpreter /usr/bin/python3
+   Using base prefix '/usr'
+   New python executable in /home/david/.virtualenvs/pygpib/bin/python3
+   Also creating executable in /home/david/.virtualenvs/pygpib/bin/python
+   Installing setuptools, pkg_resources, pip, wheel...done.
+
+   (pygpib) david@host:~$ pip install pygpibtoolkit
+   [...]
+   Installing collected packages: pyserial, numpy, sip, PyQt5, pyqtgraph, pygpibtoolkit
+   Successfully installed PyQt5-5.10.1 numpy-1.14.3 pygpibtoolkit-0.1.0 pyqtgraph-0.10.0 pyserial-3.4 sip-4.19.8
+   (pygpib) david@pavo:~$ pygpib-detect --help
+   usage: A simple tool for detecting connected GPIB devices [-h] [-d DEVICE] [-v]
+
+   optional arguments:
+     -h, --help            show this help message and exit
+	 -d DEVICE, --device DEVICE
+                           Device of connected Prologix GPIB bundle
+                           [/dev/ttyUSB0]
+	 -v, --verbose
+   (pygpib) david@host:~$ python
+   Python 3.5.3 (default, Jan 19 2017, 14:11:04)
+   [GCC 6.3.0 20170118] on linux
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>> from pygpibtoolkit.prologix import GPIB
+   >>> from pygpibtoolkit.gpibcontroller import GPIBController
+   >>> cnx = GPIB(device='/dev/ttyUSB0')
+   >>> ctl = GPIBController(cnx)
+   >>> dvm = c.register_device(24, "HP3456A")
+   >>> dvm.S0F1 # set DVM to DC Voltage mode
+
+
+
+Please refer to the `user manual`_ for more informations on how to use the
+provided tools and how to use the API.
+
+
 
 You can get information on pygpibtoolkit on
+http://pygpibtoolkit.readthedocs.io
+
+The project is hosted at
 https://bitbucket.org/dddouard/pygpibtoolkit
 
-See `doc/introduction.rst` for a quick overview.
+If you have any questions, please mail david.douard@sdfa3.org for support.
+
+pygpibtoolkit_ is (c) 2007-2018 David Douard
+and is available under the GNU General Public Licence v2.
 
-If you have any questions, please mail david.douard@sdfa3.org for support.
+.. _pygpibtoolkit: http://pygpibtoolkit.readthedocs.io
+.. _`user manual`: http://pygpibtoolkit.readthedocs.io
+.. _GPIB: https://en.wikipedia.org/wiki/IEEE-488
+.. _Prologix: http://prologix.biz
+.. _linux-gpib: https://linux-gpib.sourceforge.io
+.. _virtualenvs: https://docs.python.org/dev/library/venv.html
+.. _pip: https://packaging.python.org/key_projects/#pip
+.. _virtualenvwrapper: http://virtualenvwrapper.readthedocs.io
+.. _pew: https://github.com/berdario/pew