Merge branch 'issue-87' into stage

JoelBender · Dec 1, 2016 · cf33aa1 · cf33aa1
2 parents f95ecc8 + 713ba4f
commit cf33aa1
Show file tree

Hide file tree

Showing 149 changed files with 15,636 additions and 4,451 deletions.
diff --git a/BACpypes~.ini b/BACpypes~.ini
@@ -1,6 +1,6 @@
 [BACpypes]
 objectName: Betelgeuse
-address: 128.253.109.40/24
+address: 192.168.210.64/24
 objectIdentifier: 599
 maxApduLengthAccepted: 1024
 segmentationSupported: segmentedBoth

diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # BACpypes
 
-**Spring Surprise**
-
-Covered in dark, velvety chocolate, when you pop it into your Python path, stainless steel bolts spring out and plunge straight through both cheeks.
-
 BACpypes provides a BACnet application layer and network layer written in Python for daemons, scripting, and graphical interfaces.
+This is the current project, not the one over on SourceForge.
 
 [![Join the chat at https://gitter.im/JoelBender/bacpypes](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JoelBender/bacpypes?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+[![Documentation Status](https://readthedocs.org/projects/bacpypes/badge/?version=latest)](http://bacpypes.readthedocs.io/en/latest/?badge=latest)
+
diff --git a/doc/source/gettingstarted/gettingstarted001.rst b/doc/source/gettingstarted/gettingstarted001.rst
diff --git a/doc/source/gettingstarted/gettingstarted002.rst b/doc/source/gettingstarted/gettingstarted002.rst
@@ -5,26 +5,27 @@ Running BACpypes Applications
 
 All BACpypes sample applications have the same basic set of command line 
 options so it is easy to move between applications, turn debugging on and 
-and using different configurations.  There may be additional options and 
-command parameters than the ones described in this section.
+and use different configurations.  There may be additional options and 
+command parameters than just the ones described in this section.
 
 Getting Help
 ------------
 
 Whatever the command line parameters and additional options might be for
 an application, you can start with help::
 
-    $ python WhoIsIAm.py --help
+    $ python Tutorial/WhoIsIAm.py --help
     usage: WhoIsIAm.py [-h] [--buggers] [--debug [DEBUG [DEBUG ...]]] [--color] [--ini INI]
 
     This application presents a 'console' prompt to the user asking for Who-Is and
-    I-Am commands which create the related APDUs, then lines up the coorresponding
+    I-Am commands which create the related APDUs, then lines up the corresponding
     I-Am for incoming traffic and prints out the contents.
 
     optional arguments:
       -h, --help            show this help message and exit
       --buggers             list the debugging logger names
-      --debug [DEBUG [DEBUG ...]]
+      --debug [DEBUG [ DEBUG ... ]]
+            DEBUG ::= debugger [ : fileName [ : maxBytes [ : backupCount ]]]
                             add console log handler to each debugging logger
       --color               use ANSI CSI color codes
       --ini INI             device object configuration file
@@ -42,7 +43,7 @@ Because BACpypes modules are deeply interconnected, dumping a complete list
 of all of the logger names is a long list.  Start out focusing on the 
 components of the WhoIsIAm.py application::
 
-    $ python WhoIsIAm.py --buggers | grep __main__
+    $ python Tutorial/WhoIsIAm.py --buggers | grep __main__
     __main__
     __main__.WhoIsIAmApplication
     __main__.WhoIsIAmConsoleCmd
@@ -64,25 +65,25 @@ Telling the application to debug a module is simple::
 
 The output is the severity code of the logger (almost always DEBUG), the name 
 of the module, class, or function, then some message about the progress of the 
-application.  From the output above you can see that the application is 
-beginning its initialization, shows the value of a variable called args,
-an instance of the WhoIsIAmApplication class is created with some parameters,
-and then the application starts running.
+application.  From the output above you can see the application initializing, 
+setting the args variable, creating an instance of the WhoIsIAmApplication class 
+(with some parameters), and then declaring itself - running.
+
 
 Debugging a Class
 -----------------
 
 Debugging all of the classes and functions can generate a lot of output,
 so it is useful to focus on a specific function or class::
 
-    $ python WhoIsIAm.py --debug __main__.WhoIsIAmApplication
+    $ python Tutorial/WhoIsIAm.py --debug __main__.WhoIsIAmApplication
     DEBUG:__main__.WhoIsIAmApplication:__init__ (<bacpypes.app.LocalDeviceObject object at 0x9bca8ac>, '128.253.109.40/24:47808')
     > 
 
 The same method is used to debug the activity of a BACpypes module, for 
 example, there is a class called UDPActor in the UDP module::
 
-    $ python WhoIsIAm.py --ini BAC0.ini --debug bacpypes.udp.UDPActor
+    $ python Tutorial/WhoIsIAm.py --ini BAC0.ini --debug bacpypes.udp.UDPActor
     > DEBUG:bacpypes.udp.UDPActor:__init__ <bacpypes.udp.UDPDirector 128.253.109.255:47808 at 0xb6d40d6c> ('128.253.109.254', 47808)
     DEBUG:bacpypes.udp.UDPActor:response <bacpypes.comm.PDU object at 0xb6d433cc>
         <bacpypes.comm.PDU object at 0xb6d433cc>
@@ -92,13 +93,46 @@ example, there is a class called UDPActor in the UDP module::
 In this sample, an instance of a UDPActor is created and then its response 
 function is called with an instance of a PDU as a parameter.  Following 
 the function invocation description, the debugging output continues with the
-contents of the PDU.  Notice that the protocol data is printed as a hex 
-encoded string, and only the first 20 bytes of the message.
+contents of the PDU.  Notice, the protocol data is printed as a hex 
+encoded string (and restricted to just the first 20 bytes of the message).
 
-You can debug a function just as easily, and specify as many different 
-combinations of logger names as necessary.  Note that you cannot debug a 
+You can debug a function just as easily.  Specify as many different 
+combinations of logger names as necessary.  Note, you cannot debug a 
 specific function within a class.
 
+Sending Debug Log to a file
+----------------------------
+
+The current --debug command line option takes a list of named debugging access 
+points and attaches a StreamHandler which sends the output to sys.stderr. 
+There is a way to send the debugging output to a 
+RotatingFileHandler by providing a file name, and optionally maxBytes and 
+backupCount. For example, this invocation sends the main application debugging 
+to standard error and the debugging output of the bacpypes.udp module to the 
+traffic.txt file::
+
+    $ python Tutorial/WhoIsIAm.py --debug __main__ bacpypes.udp:traffic.txt
+
+By default the `maxBytes` is zero so there is no rotating file, but it can be 
+provided, for example this limits the file size to 1MB::
+
+    $ python Tutorial/WhoIsIAm.py --debug __main__ bacpypes.udp:traffic.txt:1048576
+
+If `maxBytes` is provided, then by default the `backupCount` is 10, but it can also 
+be specified, so this limits the output to one hundred files::
+
+    $ python Tutorial/WhoIsIAm.py --debug __main__ bacpypes.udp:traffic.txt:1048576:100
+
+.. caution::
+
+    The traffice.txt file will be saved in the local directory (pwd)
+
+The definition of debug::
+
+    positional arguments:
+        --debug [DEBUG [ DEBUG ... ]]
+            DEBUG ::= debugger [ : fileName [ : maxBytes [ : backupCount ]]]
+
 Changing INI Files
 ------------------
 
@@ -109,11 +143,11 @@ Rather than swapping INI files, you can simply provide the INI file on the
 command line, overriding the default BACpypes.ini file.  For example, I 
 have an INI file for port 47808::
 
-    $ python WhoIsIAm.py --ini BAC0.ini
+    $ python Tutorial/WhoIsIAm.py --ini BAC0.ini
 
 And another one for port 47809::
 
-    $ python WhoIsIAm.py --ini BAC1.ini
+    $ python Tutorial/WhoIsIAm.py --ini BAC1.ini
 
 And I switch back and forth between them.
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -7,25 +7,38 @@ BACpypes library for building BACnet applications using Python.  Installation
 is easy, just::
 
     $ sudo easy_install bacpypes
+    or
+    $ sudo pip install bacpypes
+    
 
-You will be installing the latest released version.  You can also check out
-the latest version from GitHub::
+You will be installing the latest released version from PyPI (the Python Packages Index), 
+located at pypi.python.org
 
-    $ git clone https://github.com/JoelBender/bacpypes.git
+.. note::
 
-And then use the setup utility to install it::
+    You can also check out the latest version from GitHub::
+    
+        $ git clone https://github.com/JoelBender/bacpypes.git
+    
+    And then use the setup utility to install it::
+    
+        $ cd bacpypes
+        $ python setup.py install
 
-    $ cd bacpypes
-    $ python setup.py install
 
-If you would like to participate in its development, please join the
-`developers mailing list
-<https://lists.sourceforge.net/lists/listinfo/bacpypes-developers>`_, join the
-`chat room on Gitter <https://gitter.im/JoelBender/bacpypes>`_, and add the
-`Google+ <https://plus.google.com/100756765082570761221/posts>`_ to your
-circles have have release notifications show up in your stream.
+.. tip::
+
+    If you would like to participate in its development, please join:
+
+    - the `developers mailing list <https://lists.sourceforge.net/lists/listinfo/bacpypes-developers>`_,
+    - the `chat room on Gitter <https://gitter.im/JoelBender/bacpypes>`_, and 
+    - add `Google+ <https://plus.google.com/100756765082570761221/posts>`_ to your circles to have release notifications show up in your stream.
+
+
+**Welcome aboard!**
+
+------
 
-Welcome aboard!
 
 Getting Started
 ---------------
@@ -39,6 +52,8 @@ downloading the sample code and communicating with a test device.
     gettingstarted/gettingstarted001.rst
     gettingstarted/gettingstarted002.rst
 
+
+
 Tutorial
 --------
 
@@ -53,33 +68,39 @@ essential components of a BACpypes application and how the pieces fit together.
     tutorial/tutorial003.rst
     tutorial/tutorial004.rst
     tutorial/tutorial006.rst
+    tutorial/iocb.rst
+    tutorial/capability.rst
 
-Samples
--------
+Migration
+---------
 
-The library has a variety of sample applications, some of them are a framework
-for building larger applications, some of them are standalone analysis tools 
-that don't require a connection to a network.
+If you are upgrading your BACpypes applications to a newer version there are
+guidelines of the types of changes you might need to make.
 
 .. toctree::
     :maxdepth: 1
 
-    samples/sample001.rst
-    samples/sample002.rst
-    samples/sample003.rst
-    samples/sample004.rst
-    samples/sample005.rst
-    samples/sample014.rst
+    migration/migration001.rst
 
-Modules
--------
+Hands-on Lab
+-------------
+
+BACpypes comes with a variety of sample applications.  Some are a framework
+for building larger applications.  Some are standalone analysis tools  
+that don't require a connection to a network. 
 
-This documentation is intended for BACpypes developers.
+The first samples you should have a look too are located inside the 
+`samples/HandsOnLab` folder. Those samples are fully explained in the 
+documentation so you can follow along and get your head around BACpypes.
+
+Other less documented samples are available directly in the `samples`
+folder.
 
 .. toctree::
     :maxdepth: 1
 
-    modules/index.rst
+    samples/sample_index.rst
+
 
 Glossary
 --------
@@ -89,6 +110,7 @@ Glossary
 
     glossary.rst
 
+
 Release Notes
 -------------
 
@@ -97,6 +119,21 @@ Release Notes
 
     releasenotes.rst
 
+------
+
+Modules
+-------
+
+.. tip:: Documentation intended for BACpypes developers.
+
+.. toctree::
+    :maxdepth: 1
+
+    modules/index.rst
+
+-----
+
+
 Indices and tables
 ==================