0.17.7 notes

Release-Notes.md

@@ -1,12 +1,108 @@
 # Release Notes
 
+## 0.17.7
+
+There is a new way of handling strange topology problems, a `settings` module
+for gathering information from the environment in a more generic way, the
+network layer and router information cache has been overhauled, and lots of
+other smaller improvements along with additional sample applications.
+
+### Route Aware Addresses
+
+Using remote station address like "10:20" implies that the router to network 10
+can be found by doing a local broadcast Who-Is-Router-To-Network.  Occassionally
+there are times when the client is not _really_ on the BACnet network, just
+lurking nearby.  Unicast messages work fine because servers respond to
+the address that sent the request.
+
+This *route aware* address format is extends the usual format with an additional
+suffix, **net:addr@route** where **route** is the address of the router to
+network **net**.  For example, sending a request from 192.168.0.12 to
+"10:20@10.168.0.15" bypasses the request to look for the router to network 10
+and simply sends it on as a unicast message to 10.168.0.15.  When the reply from
+the device is received by the router, the DNET/DLEN/DADR will have the source
+network in it and the router will assume that 192.168.0.12 is an acceptable
+address.
+
+At the application layer of the client, the address will be presented with the
+address of router, which is normally abstracted away in the network layer.  In
+this case the network topology information in the network layer is not updated.
+
+To use this format the **route_aware** setting must be set, from the
+environmental variable BACPYPES\_ROUTE\_AWARE or from some other configuration
+information.
+
+### Settings
+
+There is a new `settings` module that contains the debug and route_aware
+settings for applications.  When applications start up they can provide
+their own initialization information from the built-in `os` module, or can
+come from other sources like an INI or JSON file.
+
+To make the settings names and the environmental variable names more consistent
+with each other the BACPYPES\_DEBUG\_FILE, BACPYPES\_MAX\_BYTES, and
+BACPYPES\_BACKUP\_COUNT have been renamed with underscores.
+
+To take advantage of this new set of configuration options, there is a new
+`JSONArgumentParser` argument parser that mirrors the existing
+`ConfigArgumentParser` but uses a `--json` parameter rather than an `--ini`
+parameter.  JSON files can contain much richer content than INI files.
+
+### Router Info Cache (#213)
+
+The routing information cache which contains the relationship between local
+station addresses and the reachable networks through a router has been
+significantly changed.  It's a small data structure change from a dictionary of
+path information to a cross reference of routers and networks.
+
+The `NetworkServiceElement` now has a startup function that builds a list of
+reachable networks for each adapter and calls `i_am_router_to_network()` to
+send them out.
+
+The function `add_router_references()` changed to `update_router_references()`
+
+For some reason lots in the sands of time, the `BIPNetworkApplication` passed
+a *true* for `noBroacast` which means that applications that were for browsing
+around a network couldn't receive I-Am-Router-To-Network broadcasts. This has
+been changed.
+
+### Other Issues
+
+Issue (#286) supports disabling COV for specific objects.
+
+Issue (#283) fixes a bug handles socket error bindings.
+
+Issue (#273) skips the propertyList property returning all properties for
+a ReadPropertyMultiple request.
+
+Support Python3.7 using the same Python3.4 code base until "bacpypes3" is
+released.  The new library will be based on async/await for Python3.6+ and will
+require Python3.7+ and websockets for BACnet/SC which requires TLS 1.3.
+
+### Sample Applications
+
+* **mini_device.py** is an application that supports many core services that
+  applications need to present data on a BACnet network.  It supports Who-Is
+  and I-Am for device binding, Read and Write Property, Read and Write
+  Property Multiple, and COV subscriptions.
+
+* **OpenWeatherServer.py** is an application that uses the
+  https://openweathermap.org/ service to get weather data and make it available
+  over BACnet.
+
+* **WhoIsIAmVLAN.py** is a router from BACnet/IP to a VLAN with devices that
+  support Who-Is and I-Am.
+
+* **RecurringWriteProperty.py** application demonstrates writing a series of
+  values at a regular interval.
+
 ## 0.17.6
 
 Placeholder.
 
 ## 0.17.5
 
-## Object Identifier Strings
+### Object Identifier Strings
 
 The `ObjectIdentifier` can now be given a string in the form **type:instance**
 where **type** is a name like **analogInput** or an unsigned integer, and
@@ -21,7 +117,7 @@ It now takes commands like this:
 > read 123:45 analogInput:67 presentValue
 ```
 
-## What-Is-Network-Number/Network-Number-Is
+### What-Is-Network-Number/Network-Number-Is
 
 The network layer nows supports these two relatively new NPDUs for discovering
 the local topology.  When a Network Service Access Point is bound to a network
@@ -51,16 +147,16 @@ messages about configured networks (and routers should call this function
 at startup).  If a specific adapter parameter is given, it will send out a
 local broadcast about a "learned" network.
 
-## I-Am-Router-To-Network Helper
+### I-Am-Router-To-Network Helper
 
 There is a new `i_am_router_to_network()` function (and routers should call
 this function at startup) which announces its network topology information.
 
-## COV Period
+### COV Period
 
 The `covPeriod` property is now supported for the `PulseConverterObject`.
 
-## Fixed Size Arrays
+### Fixed Size Arrays
 
 There is now support for fixed length arrays.  The `ArrayOf()` function,
 which returns a class that is a subclass of `Array`, now has two additional