mirror of
https://github.com/JoelBender/bacpypes
synced 2025-10-05 22:18:16 +08:00
ebe2ba5abe
When the tutorial is over, the reader will continue with HandsOnLab which contains Samples1,2,3,4 Samples 5 and 14 were removed from the official table of content as they are not completed yet. All code is tested, files were moved from samples to their folder. Signed-off-by: Christian Tremblay <christian.tremblay@servisys.com>
154 lines
6.2 KiB
ReStructuredText
154 lines
6.2 KiB
ReStructuredText
.. BACpypes Getting Started 1
|
|
|
|
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 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 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 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 ::= debugger [ : fileName [ : maxBytes [ : backupCount ]]]
|
|
add console log handler to each debugging logger
|
|
--color use ANSI CSI color codes
|
|
--ini INI device object configuration file
|
|
|
|
Listing Debugging Loggers
|
|
-------------------------
|
|
|
|
The BACpypes library and sample applications make extensive use of the
|
|
built-in *logging* module in Python. Every module in the library, along
|
|
with every class and exported function, has a logging object associated
|
|
with it. By attaching a log handler to a logger, the log handler is given
|
|
a chance to output the progress of the application.
|
|
|
|
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 Tutorial/WhoIsIAm.py --buggers | grep __main__
|
|
__main__
|
|
__main__.WhoIsIAmApplication
|
|
__main__.WhoIsIAmConsoleCmd
|
|
|
|
In this sample, the entire application is called __main__ and it defines
|
|
two classes.
|
|
|
|
Debugging a Module
|
|
------------------
|
|
|
|
Telling the application to debug a module is simple::
|
|
|
|
$ python WhoIsIAm.py --debug __main__
|
|
DEBUG:__main__:initialization
|
|
DEBUG:__main__: - args: Namespace(buggers=False, debug=['__main__'], ini=<class 'bacpypes.consolelogging.ini'>)
|
|
DEBUG:__main__.WhoIsIAmApplication:__init__ (<bacpypes.app.LocalDeviceObject object at 0xb6dd98cc>, '128.253.109.40/24:47808')
|
|
DEBUG:__main__:running
|
|
>
|
|
|
|
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 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 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 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>
|
|
pduSource = ('128.253.109.254', 47808)
|
|
pduData = x'81.04.00.37.0A.10.6D.45.BA.C0.01.28.FF.FF.00.00.B6.01.05.FD...'
|
|
|
|
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, 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. 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
|
|
------------------
|
|
|
|
It is not unusual to have a variety of different INI files specifying
|
|
different port numbers or other BACnet communications paramters.
|
|
|
|
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 Tutorial/WhoIsIAm.py --ini BAC0.ini
|
|
|
|
And another one for port 47809::
|
|
|
|
$ python Tutorial/WhoIsIAm.py --ini BAC1.ini
|
|
|
|
And I switch back and forth between them.
|
|
|