Sync to GitHub

Author: CI

lib/bacnet/protocol/object_types/device.ex

@@ -8,6 +8,28 @@ defmodule BACnet.Protocol.ObjectTypes.Device do
   but is also unique throughout the BACnet internetwork.
 
   (ASHRAE 135 - Clause 12.11)
+
+  For the following properties the BACnet device server needs to
+  take special care of when other BACnet user read or write to them:
+  - `active_cov_subscriptions`
+  - `apdu_timeout` (propagation on write)
+  - `auto_slave_discovery`
+  - `device_address_binding`
+  - `manual_slave_address_binding`
+  - `max_info_frames` (marked as "readonly" and "default" value should be `1`)
+    Propagation to the MS/TP Transport must be done by the BACnet device server
+    or user of the library, if not implemented in the device server.
+  - `max_master` (marked as "readonly" and "default" value should be `127`)
+    Propagation to the MS/TP Transport must be done by the BACnet device server
+    or user of the library, if not implemented in the device server.
+  - `number_of_apdu_retries` (propagation on write)
+  - `object_list`
+  - `slave_address_binding`
+  - `slave_proxy_enable`
+  - `structured_object_list`
+  - `utc_offset` (when handling UTC Time Synchronization)
+  - All properties related to Backup/Restore
+  - All properties related to (UTC) Time Synchronization
   """
 
   # TODO: Docs
@@ -136,13 +158,27 @@ defmodule BACnet.Protocol.ObjectTypes.Device do
     )
 
     # Properties for when the device is capable of tracking date and time
-    field(:local_date, BACnetDate.t(), readonly: true, init_fun: &BACnetDate.utc_today/0)
-    field(:local_time, BACnetTime.t(), readonly: true, init_fun: &BACnetTime.utc_now/0)
+    field(:local_date, BACnetDate.t(),
+      readonly: true,
+      init_fun: &BACnetDate.utc_today/0,
+      annotation: [on_read_function: &update_property(&1, :local_date, BACnetDate.utc_today())]
+    )
+
+    field(:local_time, BACnetTime.t(),
+      readonly: true,
+      init_fun: &BACnetTime.utc_now/0,
+      annotation: [on_read_function: &update_property(&1, :local_time, BACnetTime.utc_now())]
+    )
 
     # Properties for COV reporting service
     field(:active_cov_subscriptions, [CovSubscription.t()], readonly: true, default: [])
 
     # Properties for (Utc)TimeSynchronization service
+    field(:time_synchronization_interval, non_neg_integer(),
+      default: 0,
+      implicit_relationship: :interval_offset
+    )
+
     field(:time_synchronization_recipients, [Recipient.t()],
       default: [],
       implicit_relationship: :interval_offset
@@ -242,7 +278,10 @@ defmodule BACnet.Protocol.ObjectTypes.Device do
       bac_type: {:with_validator, :unsigned_integer, &(&1 >= 1 and &1 <= 127)}
     )
 
-    field(:max_info_frames, non_neg_integer(), readonly: true)
+    field(:max_info_frames, pos_integer(),
+      readonly: true,
+      bac_type: {:with_validator, :unsigned_integer, &(&1 >= 1)}
+    )
 
     # Virtual Terminal properties (not supported by this bacstack)
     # :vt_classes_supported, [BACnetVtClass.t()]

lib/bacnet/protocol/objects_macro.ex

@@ -10,10 +10,19 @@ defmodule BACnet.Protocol.ObjectsMacro do
   Mix project, you will need to recompile bacstack with `mix deps.compile bacstack --force`.
 
   The following has to be taken care of when trying decode/encode properties:
-  - Check the annotations for decoder/encoder functions (single argument - the plain value (no tag encoding))
+  - Check the annotations for decoder/encoder functions (single argument - decoding: `Encoding` struct)
   - Check the annotations for `encode_as` primitive type declaration (i.e. used to declare enumerated booleans)
   - Check the properties types map - 99% should be covered by this (1% is covered by annotations)
   - Custom decoding/encoding by hand for special properties (not yet supported properties/objects)
+
+  BACnet device server implementations need to make sure to support `on_read_function` annotation,
+  which should always be called (single arity - the object itself and returns an ok-tuple object),
+  when another BACnet user is reading the property with such an annotation before returning
+  property value. Use cases are for example the BACnet device local time,
+  which should always be returned up to date and not a stale value.
+
+  Some properties need to be handled in a special way in the BACnet device server
+  for both reading and writing the property, no such annotation exists though.
   """
 
   alias BACnet.BeamTypes

lib/bacnet/stack/client.ex

@@ -10,7 +10,7 @@ defmodule BACnet.Stack.Client do
   a Reject APDU with reason `:other` to the remote BACnet device,
   the application won't be informed in any way.
 
-  BACnet BVLL and BACnet NPDU are directly forwarded to the application, without any processing.
+  BACnet BVLL, BACnet NPDU and proprietary are directly forwarded to the application, without any processing.
 
   For  BACnet BVLL, the following message is sent:
   ```elixir
@@ -74,6 +74,9 @@ defmodule BACnet.Stack.Client do
   Outgoing service request APDUs validation can be explicitely disabled by configuring
   application environment `:bacstack` key `:client_prod_compilation` to `true`.
   If this is a dependency of your project, don't forget to `mix deps.compile --force bacstack`.
+
+  If this library is a dependency in a project, Mix always compiles dependencies in `:prod`.
+  To override this behaviour, see `mix help deps`.
   """
 
   alias BACnet.Protocol

test/protocol/object_types/device_test.exs

@@ -0,0 +1,50 @@
+defmodule BACnet.Test.Protocol.ObjectTypes.DeviceTest do
+  alias BACnet.Protocol.BACnetDate
+  alias BACnet.Protocol.BACnetTime
+  alias BACnet.Protocol.ObjectTypes.Device
+
+  use ExUnit.Case, async: true
+
+  @moduletag :object_test
+  @moduletag :bacnet_object
+  @moduletag :bacnet_object_device
+
+  # This test suite only extends the basic and utility test suite to
+  # cover additional implemented functionality
+
+  test "Property local_date has on_read_function and works" do
+    annotations = Device.get_annotation(:local_date)
+    assert Keyword.keyword?(annotations)
+
+    fun = Keyword.fetch!(annotations, :on_read_function)
+    assert is_function(fun, 1)
+
+    assert {:ok, %Device{} = dev} =
+             Device.create(1, "Dev", %{
+               local_date: BACnetDate.from_date(Date.add(Date.utc_today(), -1))
+             })
+
+    assert {:ok, %Device{} = dev2} = fun.(dev)
+
+    # Dev2 date must be newer
+    assert BACnetDate.compare(dev.local_date, dev2.local_date) == :lt
+  end
+
+  test "Property local_time has on_read_function and works" do
+    annotations = Device.get_annotation(:local_time)
+    assert Keyword.keyword?(annotations)
+
+    fun = Keyword.fetch!(annotations, :on_read_function)
+    assert is_function(fun, 1)
+
+    assert {:ok, %Device{} = dev} =
+             Device.create(1, "Dev", %{
+               local_time: BACnetTime.from_time(Time.add(Time.utc_now(), -1))
+             })
+
+    assert {:ok, %Device{} = dev2} = fun.(dev)
+
+    # Dev2 time must be newer
+    assert BACnetTime.compare(dev.local_time, dev2.local_time) == :lt
+  end
+end