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 samples/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 samples/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 samples/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 samples/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 samples/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 samples/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 samples/WhoIsIAm.py --debug __main__ bacpypes.udp:traffic.txt:1048576:100

Caution

The traffic.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 samples/WhoIsIAm.py --ini BAC0.ini

And another one for port 47809:

$ python samples/WhoIsIAm.py --ini BAC1.ini

And I switch back and forth between them.