Permalink
Browse files

Improved documentation

  • Loading branch information...
pyhys committed Jul 18, 2015
1 parent 32d76b9 commit 1657d6d6addc3b776a49ecaa36e6d133840c4016
View
@@ -5,8 +5,9 @@ History
0.7 (2015-0?-??)
---------------------
-* Moved to Github from Sourceforge
-* Reshuffled source files and documentation
+* Moved source to Github from Sourceforge.
+* Moved documentation to Readthedocs.
+* Reshuffled source files and documentation.
* Using project setup by the cookie-cutter tool.
View
@@ -9,15 +9,20 @@ MinimalModbus
:target: https://pypi.python.org/pypi/minimalmodbus
-Easy-to-use Modbus RTU and Modbus ASCII implementation for Python
+Easy-to-use Modbus RTU and Modbus ASCII implementation for Python.
- * Free software: Apache 2.0 license
- * Documentation: https://minimalmodbus.readthedocs.org.
- * Source code on GitHub: https://github.com/pyhys/minimalmodbus
+Web resources:
+
+ * **Documentation**: https://minimalmodbus.readthedocs.org.
+ * Source code on **GitHub**: https://github.com/pyhys/minimalmodbus
* Python package index (PyPI) with download: https://pypi.python.org/pypi/MinimalModbus/
-Other web sites:
+Other web pages:
+
* Readthedocs project page: https://readthedocs.org/projects/minimalmodbus/
+
+Obsolete web pages:
+
* Old Sourceforge documentation page: http://minimalmodbus.sourceforge.net/
* Old Sourceforge project page: http://sourceforge.net/projects/minimalmodbus
* Old Sourceforge repository: http://sourceforge.net/p/minimalmodbus/code/
@@ -33,5 +38,6 @@ The only dependence is the pySerial module (also pure Python).
This software supports the 'Modbus RTU' and 'Modbus ASCII' serial communication versions of the protocol,
and is intended for use on Linux, OS X and Windows platforms.
It is open source, and has the Apache License, Version 2.0.
-Tested with Python2.7 and Python3.2.
+
+Tested with Python2.7 and Python3.2. TODO update versions
View
@@ -1,6 +1,11 @@
+.. _detailedusage:
+
Detailed usage documentation
=============================
-For introductive usage documentation, see the main documentation page.
+For introductive usage documentation, see :ref:`usage`.
+
+
+.. _interactiveusage:
Interactive usage
--------------------------------------------------------------------------------
@@ -213,17 +218,17 @@ You should try this in interactive mode in Python, and to manually re-shuffle th
Suggested work-around:
-* Read the register values directly using the read_registers function.
+* Read the register values directly using the :meth:`.read_registers` function.
* Then reshuffle the bytes
-* Convert it to a float using the internal function _bytestringToFloat.
+* Convert it to a float using the internal function :meth:`._bytestringToFloat`.
Something like::
values = read_registers(3924, numberOfRegisters=2)
registerstring = chr(values[2]) + chr(values[3]) + chr(values[0]) + chr(values[1])
floatvalue = minimalmodbus._bytestringToFloat(registerstring)
-See :meth:`.read_registers` and http://minimalmodbus.sourceforge.net/_modules/minimalmodbus.html#_bytestringToFloat
+See :meth:`.read_registers` and :meth:`._bytestringToFloat`.
@@ -233,7 +238,7 @@ Some users have reported errors due to instruments not fulfilling the Modbus sta
For example can some additional byte be pasted at the end of the response from the instrument.
Here is an example how this can be handled by tweaking the minimalmodbus.py file.
-Add this to _extractPayload function, after the argument validity testing section::
+Add this to :func:`._extractPayload` function, after the argument validity testing section::
# Fix for broken T3-PT10 which outputs extra 0xFE byte after some messages
# Patch by Edwin van den Oetelaar
@@ -247,9 +252,12 @@ Add this to _extractPayload function, after the argument validity testing sectio
except IndexError:
pass
+.. _handlelocalecho:
Handle local echo
-------------------------------------------------------------------------
+TODO This has been implemented in version 0.7.
+
If you cannot disable the local echo of your RS485 adapter, you will receive your
own message before the message from the slave. Luca Di Gregorio has suggested how to solve this issue.
View
@@ -4,7 +4,7 @@ Documentation for dummy_serial (which is a serial port mock)
.. automodule:: dummy_serial
:members:
:undoc-members:
- :noindex:
+
@@ -5,4 +5,4 @@ API for the Eurotherm3500 example driver
:members:
:undoc-members:
:show-inheritance:
- :noindex:
+
@@ -7,7 +7,5 @@ API for MinimalModbus
:members:
:undoc-members:
:show-inheritance:
- :noindex:
-
View
@@ -5,4 +5,3 @@ API for the Omega CN7500 example driver
:members:
:undoc-members:
:show-inheritance:
- :noindex:
View
@@ -2,6 +2,7 @@
Debug mode
==========
+.. _debugmode:
Debug mode
----------
@@ -118,13 +119,13 @@ Special characters
Some ASCII control characters have representations like ``\n``,
and their meanings are described in this table:
-=================== ================= =============== =============== ======================
-``repr()`` shows as Can be written as ASCII hex value ASCII dec value Description
-=================== ================= =============== =============== ======================
-``\t`` ``\x09`` 09 9 Horizontal Tab (TAB)
-``\n`` ``\x0a`` 0a 10 Linefeed (LF)
-``\r`` ``\x0d`` 0d 13 Carriage Return (CR)
-=================== ================= =============== =============== ======================
+=================== ================= ========== ========== ======================
+``repr()`` shows as Can be written as ASCII hex ASCII dec Description
+=================== ================= ========== ========== ======================
+``\t`` ``\x09`` 09 9 Horizontal Tab (TAB)
+``\n`` ``\x0a`` 0a 10 Linefeed (LF)
+``\r`` ``\x0d`` 0d 13 Carriage Return (CR)
+=================== ================= ========== ========== ======================
It is also possible to write for example ASCII Bell (BEL, hex = 07, dec = 7)
as ``\a``, but its ``repr()`` will still print ``\x07``.
View
@@ -618,6 +618,9 @@ Each of these have some additional information below on this page.
SVN
Version control software. See http://subversion.apache.org/
+Git
+ Version control software. See https://git-scm.com/
+
Sphinx
For generating HTML documentation. See http://sphinx-doc.org/
@@ -632,7 +635,7 @@ pep8.py
Subversion (svn) usage
------------------------------------------------------------------------------
+---------------------------
Subversion provides an easy way to share code with each other. You can find all MinimalModbus files on the subversion repository on http://sourceforge.net/p/minimalmodbus/code/ Look in the trunk subfolder.
@@ -717,6 +720,33 @@ Test it using (adapt path to your system)::
python /usr/local/lib/python2.6/dist-packages/minimalmodbus.py
+
+Git usage
+---------------------------
+
+Clone::
+
+ git clone https://github.com/pyhys/minimalmodbus.git
+
+Show details::
+
+ git remote -v
+ git status
+ git branch
+
+Stage changes::
+
+ git add testb.txt
+
+Commit locally::
+
+ git commit -m "test1"
+
+Commit remotely (will ask for Github username and password):
+
+ git push origin
+
+
Sphinx usage
-------------------------------------------------------------------------------
This documentation is generated with the Sphinx tool: http://sphinx-doc.org/
@@ -907,6 +937,6 @@ Maybe:
* Logging instead of _print_out()
* Timing based on time.clock() for Windows
* Change 'message' to 'request' variable names in the source code
- * Developer: signature for hardware testing ???
+
View
@@ -12,20 +12,17 @@ Or, if you have virtualenvwrapper installed::
$ pip install minimalmodbus
-
-
-
Dependencies
------------
Python versions 2.7 and higher are supported (including 3.x).
-Tested with Python2.7 and Python3.2. This module is pure Python.
+Tested with Python2.7 and Python3.2. This module is pure Python. TODO update versions
This module relies on `pySerial <http://pyserial.sourceforge.net/>`_ (also pure Python)
to do the heavy lifting, and it is the only dependency.
You can find it at the Python package index: https://pypi.python.org/pypi/pyserial
-Old text (Download and installation)
+Alternate installation
-------------------------------------
From command line (if you have the *pip installer*, available at https://pypi.python.org/pypi/pip)::
@@ -60,12 +57,18 @@ In that case, first manually install pySerial and then manually install MinimalM
To make sure it is installed properly, print the _getDiagnosticString() message.
-See the support section below for instructions.
+See the :ref:`support` section for instructions.
You can also download the source directly from Linux command line::
wget http://downloads.sourceforge.net/project/minimalmodbus/0.5/MinimalModbus-0.5.tar.gz
wget https://pypi.python.org/packages/source/M/MinimalModbus/MinimalModbus-0.5.tar.gz
+TODO Change download links
+
Change version number to the appropriate value.
+If everything else fails
+-------------------------
+You can download the raw minimalmodbus.py file from GitHub, and put it in the same directory as your other code. Note that you must have pySerial installed.
+
Oops, something went wrong.

0 comments on commit 1657d6d

Please sign in to comment.