Python digimat.bac0
===================
`digimat.bac0 <https://pypi.org/project/digimat.bac0/>`_ is a Python 3 module basically providing a wrapper around the excellent `BAC0 <https://bac0.readthedocs.io/en/latest/>`_ module,
itself using `BACpypes <https://github.com/JoelBender/bacpypes>`_. This module provide super easy access (browsing, interacting) to BACnet/IP networks. This module can be used interactively or within an application. Install this module with a *pip install -U digimat.bac0* command.
.. code-block:: python
>>> from digimat.bac0 import BAC
>>> bacnet=BAC(network='192.168.0.84/24')
Congratulations ! You just have launched a BACnet/IP node binded to your LAN card (ip 192.168.0.84, netmask 255.255.255.0). This short `Youtube Screencast <https://youtu.be/YUUXk398lh8>`_ shows a small interactive usage of this module. You have to provide the ip ("ip/networkSize") of the card that will be used to send+receive every BACnet UDP messages. Under Linux/MacOS hosts, this can be done automagically if you have installed the `netifaces <https://pypi.org/project/netifaces/>`_ module (install it with *pip install -U netifaces*). If so, you can ommit the *network* parameter (the module will *try* to guess the ip address of your network card)
.. code-block:: python
>>> bacnet=BAC() # return a BAC object
>>> bacnet
<BAC:192.168.0.84/24(0 devices)>
If needed, you can give a `bbmd router <https://www.optigo.net/what-bacnet-broadcast-management-device-bbmd/>`_ ('ipAddress[:port]') to the constructor
.. code-block:: python
>>> bacnet=BAC(router='192.168.2.1')
Now, assuming that your network settings are correct, you can start discovering the BACnet network
.. code-block:: python
>>> bacnet.whois() # return a list of devices detected on the network
[('192.168.0.15', 8015), ('192.168.0.80', 4000)]
>>> bacnet.whois('*:*') # by default, send the request on all networks
>>> bacnet.whois('2001:*') # search devices on the 2001 network only
The *whois()* method returns a list of remote BACnet/address servers detected on the network (address/deviceId). As most of theses BACnet requests are using BAC0/BACpypes requests, you will find additional information in the documentation of theses projects (if really needed). To communicate with BACnet devices (BACnet servers), you can add (declare) to them your node
.. code-block:: python
>>> device=bacnet.declareDevice(8015, '192.168.0.15')
>>> device=bacnet.declareDevice(did=8015, address='192.168.0.15', poll=60) # with polling time specified (default is to poll it every 15s)
In fact, if the device is detected by the whois(), you can declare a node based on it's id or it's address. A whois() request will be triggered to retrieve the associated device missing address/id value. This will create (if not already done) and return the corresponding BACDevice object.
.. code-block:: python
>>> device=bacnet.declareDeviceFromId(8015) # return a BACDevice object
>>> device=bacnet.declareDeviceFromAddress('192.168.0.15') # equivalent
>>> device
<BACDevice:8015:0(Digimat:Digimat3_CPU_Bridge), operational, 66 points)>
If you are super lazy (no you're not), you can even use the .discover() method to auto declare every device discovered by a whois() request. But you can't really predict what will be exactly done, so it's more an helper for interactive sessions.
.. code-block:: python
>>> bacnet.discover() # this will magically declare every device reported by whois()
The underlying BAC0 module has started a thread managing each remote bacnet device (understand remote "BACnet servers") you will declare to your node. Every BAC* object (BAC, BACDevice, BACPoints, BACPoint) has a .dump() method, very useful in interactive sessions
.. code-block:: python
>>> bacnet.dump()
+---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+
| # | name | id | address | vendor | model | status | description | #points |
+---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+
| 0 | s_112_1 | 8015 | 192.168.0.15 | Digimat | Digimat3_CPU_Bridge | operational | S+T | 66 |
+---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+
>>> device.dump()
+-----------------------+--------------+
| property | value |
+-----------------------+--------------+
| ip | 192.168.0.15 |
| address | 8015 |
| name | s_112_1 |
| description | S+T |
| systemStatus | operational |
| vendorName | Digimat |
| vendorIdentifier | 892 |
| points | 66 |
| segmentationSupported | True |
| analogInput | 16 |
| analogOutput | 8 |
| binaryInput | 31 |
| binaryOutput | 11 |
+-----------------------+--------------+
Once a device has been declared, you can retrieve a reference to the corresponding BACDevice object it with bacnet.device(...) or directly with a bacnet[...] array access. You can use either the index (0), the name (s_112_1), the id (8105) or the address (192.168.0.15) to retrieve your device from the BAC object. If you redeclare a device already existing, it will be simply returns the existing one (no duplication). The BAC object is iterable, so you can also use something like "for device in BAC:". requesting a non existant (non declared) device returns None.
You will have to dig a bit into the `BAC <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacnet.py>`_ and `BACDevice <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacdevice.py>`_ objects to find avalaible methods and properties. It's now time to access to the points (variables) of our device, all provided by the device.points property, returning a *BACPoints* object
.. code-block:: python
>>> points=device.points
>>> points
<BACPoints(66 points)>
>>> points.dump()
+----+---------------------+-------------------------------------------------------------------------+-------------------+---------+--------------+-----+-------+-------+
| # | name | description | descriptor | value | label | age | COV | OoS |
+----+---------------------+-------------------------------------------------------------------------+-------------------+---------+--------------+-----+-------+-------+
| 0 | r_112_1_cio_13056_0 | sonde exterieure | analogInput13056 | 25.5573 | C | 4s | False | False |
| 1 | r_112_1_cio_13057_0 | sonde depart chaudiere | analogInput13057 | 25.0004 | C | 4s | False | False |
| 2 | r_112_1_cio_13058_0 | sonde depart radiateurs | analogInput13058 | 29.1211 | C | 4s | False | False |
| 3 | r_112_1_cio_13059_0 | sonde depart chauffage de sol | analogInput13059 | 25.2445 | C | 4s | False | False |
| 4 | r_112_1_cio_13060_0 | pot.physique consigne depart chauffage de sol (-10;+10C) | analogInput13060 | 4.91234 | C | 4s | False | False |
| 5 | r_112_1_cio_13061_0 | pot.physique consigne depart radiateurs (-10;+10C) | analogInput13061 | 2.925 | C | 4s | False | False |
| 6 | r_112_1_cio_13062_0 | sonde ambiance bureau direction rez | analogInput13062 | 24.434 | C | 4s | False | False |
...
>>> device.points.dump('sonde') # output can be filtered (by part of names or descriptions)
+----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+
| # | name | description | descriptor | value | label | age | COV | OoS |
+----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+
| 0 | r_112_1_cio_13056_0 | sonde exterieure | analogInput13056 | 25.572 | C | 11s | False | False |
| 1 | r_112_1_cio_13057_0 | sonde depart chaudiere | analogInput13057 | 25.0248 | C | 11s | False | False |
| 2 | r_112_1_cio_13058_0 | sonde depart radiateurs | analogInput13058 | 29.1211 | C | 11s | False | False |
| 3 | r_112_1_cio_13059_0 | sonde depart chauffage de sol | analogInput13059 | 25.2689 | C | 11s | False | False |
| 6 | r_112_1_cio_13062_0 | sonde ambiance bureau direction rez | analogInput13062 | 24.4437 | C | 11s | False | False |
| 8 | r_112_1_cio_13064_0 | sonde ambiance bureau direction cote hall rez | analogInput13064 | 23.9457 | C | 11s | False | False |
| 10 | r_112_1_cio_13066_0 | sonde ambiance salle de conferences | analogInput13066 | 24.307 | C | 11s | False | False |
| 11 | r_112_1_cio_13067_0 | sonde ambiance temperature bureau comptabilite rez | analogInput13067 | 23.2328 | C | 11s | False | False |
| 12 | r_112_1_cio_13068_0 | sonde ambiance bureau schematique s-sol | analogInput13068 | 22.5492 | C | 11s | False | False |
| 14 | r_112_1_cio_13070_0 | sonde ambiance bureau individuel s-sol | analogInput13070 | 23.4086 | C | 11s | False | False |
+----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+
Using the BACPoints.dump() method ca take some time on slow devices as this implies some read requests. The points.quickDump() provide a minimal dump avoiding some extra requests. Each point of the *BACPoints* object is accessible by it's *index* (pure internal index of a point in it's BACPoints array), *type* or a part of *something belonging* to it
.. code-block:: python
>>> point=points[8]
>>> point
<BACPointAnalogInput(r_112_1_cio_13064_0:analogInput#13064=26.51 degreesCelsius)>
>>> point.dump()
+--------------+-----------------------------------------------+
| property | value |
+--------------+-----------------------------------------------+
| class | BACPointAnalogInput |
| name | r_112_1_cio_13064_0 |
| description | sonde ambiance bureau direction cote hall rez |
| type | analogInput |
| address | 13064 |
| value | 26.57267189025879 |
| state | 26.57 |
| unit | degreesCelsius (C) |
| COV | False |
| OutOfService | False |
| index | 8 |
+--------------+-----------------------------------------------+
>>> point=device.points.analogInput(13064)
>>> point=bacnet[8015].points.analogOuput(18181)
>>> points['sonde hall'] # return the first object matching to this
<BACPointAnalogInput(r_112_1_cio_13064_0:analogInput#13064=26.55 degreesCelsius)>
>>> point=point['r_112_1_cio_13064_0']
>>> point=point['13064']
>>> point=point['analogInput13064']
The BACPoints object offer many helpers to search/access it's points. BACPoints is also iterable. Points are exposed through `BACPoint <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacpoint.py>`_ objects (generic class), derived in BACPointBinaryInput, BACPointBinaryOutput, BACPointAnalogInput, BACPointAnalogOutput, BACPointBinaryValue, BACPointAnalogValue,
BACPointMultiStateInput, BACPointMultiStateOutput, BACPointMultiStateValue objects, each providing specialized BACPoint extensions. You will have to dig a bit into theses objects to learn what helper they provide. Using `bpython <https://bpython-interpreter.org/>`_ interactive interpreter with it's autocompletion feature is a very convenient way to discover thoses object (with the actual lack of documentation)
.. code-block:: python
>>> point.
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ activePriority address bacnetProperty bacnetproperties celciusToFahrenheit cov │
│ covCancel description digDecimals digUnit digUnitStr dump │
│ fahrenheitToCelcius index isAnalog isBinary isCOV isMultiState │
│ isOutOfService isWritable label match name onInit │
│ poll pollStop priority properties read refresh │
│ reloadBacnetProperties state toCelcius type unit unitNumber │
│ value │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
>>> point.value
26.699626922607422
>>> point.unit
'degreesCelsius'
>>> point.value=12.0 # if a point is writable, this will change it's value
>>> point.write(12.0, priority=8)
>>> point.write(12.0, prop='presentValue', priority=8)
# for binary values
>>> point.on()
>>> point.off()
>>> point.toggle()
>>> point.isOn()
>>> point.isOff()
>>> point.label
>>> point.labels
>>> point.value=1
>>> point.value='on'
# for multiState values
>>> point.state
>>> point.label
>>> point.labels
>>> point.value
>>> point.value=2
Refreshing point's values
=========================
A BACDevice automatically refresh it's points every 15s (the device's polling time could be specified at object creation/declaration).
.. code-block:: python
>>> device=b.declareDevice(did=8015, address='192.168.0.15', poll=60)
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ b.declareDevice: (self, did, address=None, poll=15, filterOutOfService=False, objectList=None) │
│ declareDevice declareDeviceFromAddress declareDeviceFromId │
│ declare a remote device specified by it's id (did, i.e 8015) and it's address (i.e 192.168.0.15 or 2001:3) │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
You can stop the polling with device.pollStop() or adjust the polling period (seconds) with device.poll(60). This is the device polling *global* setting. Every point may also be polled individually with point.poll(10) and point.pollStop(). Of course you may wish to set an individual poll for each point of the device with device.points.poll(60). But using the *global* device.poll() mechanism is a lot more efficient way to do it.
Refresh may also be done throug COV (Change Of Value) mechanism. By default, COV is not enabled on a device. You can enable COV subscriptions on a secific point with point.cov(), and disable it with point.covCancel(). This can also be done on each points with device.points.cov() or with it's shortcut device.cov(ttl=300). By default, the COV timeout is set to 300s. The poll and/or COV mechanism ensure the autorefresh of the points values. If needed, a point can be refreshed manually with point.refresh() -- trigggering a read request on the presentValue. As suspected, the device.refresh() or device.points.refresh() does this globally.
Going further
=============
If a *BACPoint* object doesn't expose something that would be useful, either ask it (we will try to add this support) or use the underlying .bac0point object which is the BAC0's `Point object <https://bac0.readthedocs.io/en/latest/BAC0.core.devices.html#BAC0.core.devices.Points.Point>`_ associated to this point.
If a *BACDevice* object doesn't expose something that would be useful, you can use the underlying .bac0device BAC0 `device object <https://github.com/ChristianTremblay/BAC0/blob/master/BAC0/core/devices/Device.py>`_.
If the *BAC* object doesn't expose something that would be useful, you can use the underlying .bac0 BAC0 `application object <https://github.com/ChristianTremblay/BAC0/blob/master/BAC0/scripts/Lite.py>`_.
Integrated Node
===============
The module provide a simple BACnet browser application you can start with "python -i -m digimat.bac0 [--ip "192.168.0.84/24"] [--router x.x.x.x] [--debug]". This will launch the following application
.. code-block:: python
parser=argparse.ArgumentParser(description='BACnet/IP browser')
parser.add_argument('--router', dest='router', type=str, help='BBMD router address')
parser.add_argument('--network', dest='network', type=str, help='optional ip/netsize of the BACnet/IP interface')
parser.add_argument('--discover', dest='discover', action='store_true', help='launch a discover at startup')
parser.add_argument('--debug', dest='debug', action='store_true', help='enable debug/verbose mode')
args=parser.parse_args()
bacnet=BAC(network=args.network, router=args.router)
if args.debug:
bacnet.BAC0LogDebug()
if args.discover:
bacnet.discover():
bacnet.dump()
When launched interactively (python -i -m digimat.bac0), you'll have a working *bacnet* variable (a BAC object) ready to be used in just one command line.
Todo
====
We will try to add objects and methods docstring as soon as possible to help the use of theses objects. Please let us know (fhess@st-sa.ch) is this is useful for someone (for us it is).
Raw data
{
"_id": null,
"home_page": "https://github.com/digimat/digimat-bac0",
"name": "digimat.bac0",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Frederic Hess",
"author_email": "fhess@st-sa.ch",
"download_url": "https://files.pythonhosted.org/packages/5f/fe/da69dddf43be2618f3c9e3393458bf3f0397b435dbd24d82942ba52a6e88/digimat.bac0-0.0.58.tar.gz",
"platform": null,
"description": "Python digimat.bac0\n===================\n\n`digimat.bac0 <https://pypi.org/project/digimat.bac0/>`_ is a Python 3 module basically providing a wrapper around the excellent `BAC0 <https://bac0.readthedocs.io/en/latest/>`_ module, \nitself using `BACpypes <https://github.com/JoelBender/bacpypes>`_. This module provide super easy access (browsing, interacting) to BACnet/IP networks. This module can be used interactively or within an application. Install this module with a *pip install -U digimat.bac0* command.\n\n.. code-block:: python\n\n >>> from digimat.bac0 import BAC\n >>> bacnet=BAC(network='192.168.0.84/24')\n\n\nCongratulations ! You just have launched a BACnet/IP node binded to your LAN card (ip 192.168.0.84, netmask 255.255.255.0). This short `Youtube Screencast <https://youtu.be/YUUXk398lh8>`_ shows a small interactive usage of this module. You have to provide the ip (\"ip/networkSize\") of the card that will be used to send+receive every BACnet UDP messages. Under Linux/MacOS hosts, this can be done automagically if you have installed the `netifaces <https://pypi.org/project/netifaces/>`_ module (install it with *pip install -U netifaces*). If so, you can ommit the *network* parameter (the module will *try* to guess the ip address of your network card)\n\n.. code-block:: python\n\n >>> bacnet=BAC() # return a BAC object\n >>> bacnet\n <BAC:192.168.0.84/24(0 devices)>\n\n\nIf needed, you can give a `bbmd router <https://www.optigo.net/what-bacnet-broadcast-management-device-bbmd/>`_ ('ipAddress[:port]') to the constructor\n\n.. code-block:: python\n\n >>> bacnet=BAC(router='192.168.2.1')\n\n\nNow, assuming that your network settings are correct, you can start discovering the BACnet network\n\n.. code-block:: python\n\n >>> bacnet.whois() # return a list of devices detected on the network\n [('192.168.0.15', 8015), ('192.168.0.80', 4000)]\n\n >>> bacnet.whois('*:*') # by default, send the request on all networks\n >>> bacnet.whois('2001:*') # search devices on the 2001 network only\n\n\nThe *whois()* method returns a list of remote BACnet/address servers detected on the network (address/deviceId). As most of theses BACnet requests are using BAC0/BACpypes requests, you will find additional information in the documentation of theses projects (if really needed). To communicate with BACnet devices (BACnet servers), you can add (declare) to them your node\n\n.. code-block:: python\n\n >>> device=bacnet.declareDevice(8015, '192.168.0.15')\n >>> device=bacnet.declareDevice(did=8015, address='192.168.0.15', poll=60) # with polling time specified (default is to poll it every 15s)\n\n\nIn fact, if the device is detected by the whois(), you can declare a node based on it's id or it's address. A whois() request will be triggered to retrieve the associated device missing address/id value. This will create (if not already done) and return the corresponding BACDevice object.\n\n.. code-block:: python\n\n >>> device=bacnet.declareDeviceFromId(8015) # return a BACDevice object\n >>> device=bacnet.declareDeviceFromAddress('192.168.0.15') # equivalent\n >>> device\n <BACDevice:8015:0(Digimat:Digimat3_CPU_Bridge), operational, 66 points)>\n\nIf you are super lazy (no you're not), you can even use the .discover() method to auto declare every device discovered by a whois() request. But you can't really predict what will be exactly done, so it's more an helper for interactive sessions.\n\n.. code-block:: python\n\n >>> bacnet.discover() # this will magically declare every device reported by whois()\n\n\nThe underlying BAC0 module has started a thread managing each remote bacnet device (understand remote \"BACnet servers\") you will declare to your node. Every BAC* object (BAC, BACDevice, BACPoints, BACPoint) has a .dump() method, very useful in interactive sessions\n\n.. code-block:: python\n\n >>> bacnet.dump()\n +---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+\n | # | name | id | address | vendor | model | status | description | #points |\n +---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+\n | 0 | s_112_1 | 8015 | 192.168.0.15 | Digimat | Digimat3_CPU_Bridge | operational | S+T | 66 |\n +---+---------+------+--------------+---------+---------------------+-------------+-------------+---------+\n\n >>> device.dump()\n +-----------------------+--------------+\n | property | value |\n +-----------------------+--------------+\n | ip | 192.168.0.15 |\n | address | 8015 |\n | name | s_112_1 |\n | description | S+T |\n | systemStatus | operational |\n | vendorName | Digimat |\n | vendorIdentifier | 892 |\n | points | 66 |\n | segmentationSupported | True |\n | analogInput | 16 |\n | analogOutput | 8 |\n | binaryInput | 31 |\n | binaryOutput | 11 |\n +-----------------------+--------------+\n\n\nOnce a device has been declared, you can retrieve a reference to the corresponding BACDevice object it with bacnet.device(...) or directly with a bacnet[...] array access. You can use either the index (0), the name (s_112_1), the id (8105) or the address (192.168.0.15) to retrieve your device from the BAC object. If you redeclare a device already existing, it will be simply returns the existing one (no duplication). The BAC object is iterable, so you can also use something like \"for device in BAC:\". requesting a non existant (non declared) device returns None.\n\nYou will have to dig a bit into the `BAC <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacnet.py>`_ and `BACDevice <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacdevice.py>`_ objects to find avalaible methods and properties. It's now time to access to the points (variables) of our device, all provided by the device.points property, returning a *BACPoints* object\n\n.. code-block:: python\n\n >>> points=device.points\n >>> points\n <BACPoints(66 points)>\n\n >>> points.dump()\n +----+---------------------+-------------------------------------------------------------------------+-------------------+---------+--------------+-----+-------+-------+\n | # | name | description | descriptor | value | label | age | COV | OoS |\n +----+---------------------+-------------------------------------------------------------------------+-------------------+---------+--------------+-----+-------+-------+\n | 0 | r_112_1_cio_13056_0 | sonde exterieure | analogInput13056 | 25.5573 | C | 4s | False | False |\n | 1 | r_112_1_cio_13057_0 | sonde depart chaudiere | analogInput13057 | 25.0004 | C | 4s | False | False |\n | 2 | r_112_1_cio_13058_0 | sonde depart radiateurs | analogInput13058 | 29.1211 | C | 4s | False | False |\n | 3 | r_112_1_cio_13059_0 | sonde depart chauffage de sol | analogInput13059 | 25.2445 | C | 4s | False | False |\n | 4 | r_112_1_cio_13060_0 | pot.physique consigne depart chauffage de sol (-10;+10C) | analogInput13060 | 4.91234 | C | 4s | False | False |\n | 5 | r_112_1_cio_13061_0 | pot.physique consigne depart radiateurs (-10;+10C) | analogInput13061 | 2.925 | C | 4s | False | False |\n | 6 | r_112_1_cio_13062_0 | sonde ambiance bureau direction rez | analogInput13062 | 24.434 | C | 4s | False | False |\n ...\n\n >>> device.points.dump('sonde') # output can be filtered (by part of names or descriptions)\n +----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+\n | # | name | description | descriptor | value | label | age | COV | OoS |\n +----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+\n | 0 | r_112_1_cio_13056_0 | sonde exterieure | analogInput13056 | 25.572 | C | 11s | False | False |\n | 1 | r_112_1_cio_13057_0 | sonde depart chaudiere | analogInput13057 | 25.0248 | C | 11s | False | False |\n | 2 | r_112_1_cio_13058_0 | sonde depart radiateurs | analogInput13058 | 29.1211 | C | 11s | False | False |\n | 3 | r_112_1_cio_13059_0 | sonde depart chauffage de sol | analogInput13059 | 25.2689 | C | 11s | False | False |\n | 6 | r_112_1_cio_13062_0 | sonde ambiance bureau direction rez | analogInput13062 | 24.4437 | C | 11s | False | False |\n | 8 | r_112_1_cio_13064_0 | sonde ambiance bureau direction cote hall rez | analogInput13064 | 23.9457 | C | 11s | False | False |\n | 10 | r_112_1_cio_13066_0 | sonde ambiance salle de conferences | analogInput13066 | 24.307 | C | 11s | False | False |\n | 11 | r_112_1_cio_13067_0 | sonde ambiance temperature bureau comptabilite rez | analogInput13067 | 23.2328 | C | 11s | False | False |\n | 12 | r_112_1_cio_13068_0 | sonde ambiance bureau schematique s-sol | analogInput13068 | 22.5492 | C | 11s | False | False |\n | 14 | r_112_1_cio_13070_0 | sonde ambiance bureau individuel s-sol | analogInput13070 | 23.4086 | C | 11s | False | False |\n +----+---------------------+-----------------------------------------------------+------------------+---------+-------+-----+-------+-------+\n\nUsing the BACPoints.dump() method ca take some time on slow devices as this implies some read requests. The points.quickDump() provide a minimal dump avoiding some extra requests. Each point of the *BACPoints* object is accessible by it's *index* (pure internal index of a point in it's BACPoints array), *type* or a part of *something belonging* to it \n\n.. code-block:: python\n\n >>> point=points[8]\n >>> point\n <BACPointAnalogInput(r_112_1_cio_13064_0:analogInput#13064=26.51 degreesCelsius)>\n\n >>> point.dump()\n +--------------+-----------------------------------------------+\n | property | value |\n +--------------+-----------------------------------------------+\n | class | BACPointAnalogInput |\n | name | r_112_1_cio_13064_0 |\n | description | sonde ambiance bureau direction cote hall rez |\n | type | analogInput |\n | address | 13064 |\n | value | 26.57267189025879 |\n | state | 26.57 |\n | unit | degreesCelsius (C) |\n | COV | False |\n | OutOfService | False |\n | index | 8 |\n +--------------+-----------------------------------------------+\n\n >>> point=device.points.analogInput(13064)\n >>> point=bacnet[8015].points.analogOuput(18181)\n\n >>> points['sonde hall'] # return the first object matching to this\n <BACPointAnalogInput(r_112_1_cio_13064_0:analogInput#13064=26.55 degreesCelsius)>\n\n >>> point=point['r_112_1_cio_13064_0']\n >>> point=point['13064']\n >>> point=point['analogInput13064']\n\n\nThe BACPoints object offer many helpers to search/access it's points. BACPoints is also iterable. Points are exposed through `BACPoint <https://github.com/digimat/digimat-bac0/blob/main/src/digimat/bac0/bacpoint.py>`_ objects (generic class), derived in BACPointBinaryInput, BACPointBinaryOutput, BACPointAnalogInput, BACPointAnalogOutput, BACPointBinaryValue, BACPointAnalogValue, \nBACPointMultiStateInput, BACPointMultiStateOutput, BACPointMultiStateValue objects, each providing specialized BACPoint extensions. You will have to dig a bit into theses objects to learn what helper they provide. Using `bpython <https://bpython-interpreter.org/>`_ interactive interpreter with it's autocompletion feature is a very convenient way to discover thoses object (with the actual lack of documentation)\n\n.. code-block:: python\n\n >>> point.\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 activePriority address bacnetProperty bacnetproperties celciusToFahrenheit cov \u2502\n \u2502 covCancel description digDecimals digUnit digUnitStr dump \u2502\n \u2502 fahrenheitToCelcius index isAnalog isBinary isCOV isMultiState \u2502\n \u2502 isOutOfService isWritable label match name onInit \u2502\n \u2502 poll pollStop priority properties read refresh \u2502\n \u2502 reloadBacnetProperties state toCelcius type unit unitNumber \u2502\n \u2502 value \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n >>> point.value\n 26.699626922607422\n >>> point.unit\n 'degreesCelsius'\n\n >>> point.value=12.0 # if a point is writable, this will change it's value\n >>> point.write(12.0, priority=8)\n >>> point.write(12.0, prop='presentValue', priority=8)\n\n # for binary values\n >>> point.on()\n >>> point.off()\n >>> point.toggle()\n >>> point.isOn()\n >>> point.isOff()\n >>> point.label\n >>> point.labels\n >>> point.value=1\n >>> point.value='on'\n\n # for multiState values\n >>> point.state\n >>> point.label\n >>> point.labels\n >>> point.value\n >>> point.value=2\n\n\nRefreshing point's values\n=========================\n\nA BACDevice automatically refresh it's points every 15s (the device's polling time could be specified at object creation/declaration).\n\n\n.. code-block:: python\n\n >>> device=b.declareDevice(did=8015, address='192.168.0.15', poll=60)\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 b.declareDevice: (self, did, address=None, poll=15, filterOutOfService=False, objectList=None) \u2502\n \u2502 declareDevice declareDeviceFromAddress declareDeviceFromId \u2502\n \u2502 declare a remote device specified by it's id (did, i.e 8015) and it's address (i.e 192.168.0.15 or 2001:3) \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\nYou can stop the polling with device.pollStop() or adjust the polling period (seconds) with device.poll(60). This is the device polling *global* setting. Every point may also be polled individually with point.poll(10) and point.pollStop(). Of course you may wish to set an individual poll for each point of the device with device.points.poll(60). But using the *global* device.poll() mechanism is a lot more efficient way to do it. \n\nRefresh may also be done throug COV (Change Of Value) mechanism. By default, COV is not enabled on a device. You can enable COV subscriptions on a secific point with point.cov(), and disable it with point.covCancel(). This can also be done on each points with device.points.cov() or with it's shortcut device.cov(ttl=300). By default, the COV timeout is set to 300s. The poll and/or COV mechanism ensure the autorefresh of the points values. If needed, a point can be refreshed manually with point.refresh() -- trigggering a read request on the presentValue. As suspected, the device.refresh() or device.points.refresh() does this globally.\n\n\nGoing further\n=============\n\nIf a *BACPoint* object doesn't expose something that would be useful, either ask it (we will try to add this support) or use the underlying .bac0point object which is the BAC0's `Point object <https://bac0.readthedocs.io/en/latest/BAC0.core.devices.html#BAC0.core.devices.Points.Point>`_ associated to this point.\nIf a *BACDevice* object doesn't expose something that would be useful, you can use the underlying .bac0device BAC0 `device object <https://github.com/ChristianTremblay/BAC0/blob/master/BAC0/core/devices/Device.py>`_.\nIf the *BAC* object doesn't expose something that would be useful, you can use the underlying .bac0 BAC0 `application object <https://github.com/ChristianTremblay/BAC0/blob/master/BAC0/scripts/Lite.py>`_.\n\n\nIntegrated Node\n===============\n\nThe module provide a simple BACnet browser application you can start with \"python -i -m digimat.bac0 [--ip \"192.168.0.84/24\"] [--router x.x.x.x] [--debug]\". This will launch the following application\n\n.. code-block:: python\n\n parser=argparse.ArgumentParser(description='BACnet/IP browser')\n parser.add_argument('--router', dest='router', type=str, help='BBMD router address')\n parser.add_argument('--network', dest='network', type=str, help='optional ip/netsize of the BACnet/IP interface')\n parser.add_argument('--discover', dest='discover', action='store_true', help='launch a discover at startup')\n parser.add_argument('--debug', dest='debug', action='store_true', help='enable debug/verbose mode')\n args=parser.parse_args()\n\n bacnet=BAC(network=args.network, router=args.router)\n if args.debug:\n bacnet.BAC0LogDebug()\n\n if args.discover:\n bacnet.discover():\n\n bacnet.dump()\n\n\nWhen launched interactively (python -i -m digimat.bac0), you'll have a working *bacnet* variable (a BAC object) ready to be used in just one command line.\n\n\nTodo\n====\n\nWe will try to add objects and methods docstring as soon as possible to help the use of theses objects. Please let us know (fhess@st-sa.ch) is this is useful for someone (for us it is).\n",
"bugtrack_url": null,
"license": "PSF",
"summary": "Digimat BACnet BAC0 Wrapper",
"version": "0.0.58",
"project_urls": {
"Homepage": "https://github.com/digimat/digimat-bac0"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ffeda69dddf43be2618f3c9e3393458bf3f0397b435dbd24d82942ba52a6e88",
"md5": "6942c220f5684cb8eeaa6e8dd4ad0c17",
"sha256": "14734d2a16b07bf44b83259178b85319d8304bc7959050a6e1bfc17773a569b2"
},
"downloads": -1,
"filename": "digimat.bac0-0.0.58.tar.gz",
"has_sig": false,
"md5_digest": "6942c220f5684cb8eeaa6e8dd4ad0c17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23019,
"upload_time": "2023-08-01T10:28:59",
"upload_time_iso_8601": "2023-08-01T10:28:59.244749Z",
"url": "https://files.pythonhosted.org/packages/5f/fe/da69dddf43be2618f3c9e3393458bf3f0397b435dbd24d82942ba52a6e88/digimat.bac0-0.0.58.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 10:28:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "digimat",
"github_project": "digimat-bac0",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "digimat.bac0"
}
JSON
