diff --git a/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/alternative-responses-addresses.md b/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/alternative-responses-addresses.md index 167365449b..8ca4fe886f 100644 --- a/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/alternative-responses-addresses.md +++ b/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/alternative-responses-addresses.md @@ -1,14 +1,58 @@ -Let's review more examples of alternative responses addresses. +Alternative response addresses field allows you to specify an alternative IP address for device responses. +It is especially useful when the gateway and the BACnet device are located in different networks. -This field allows you to specify an alternative address for responses from the device. -It is useful when the gateway and BACnet device are located in different networks. +For example, consider the following network setup: + +![image](/images/gateway/bacnet-connector/examples/alternative-responses-addresses-network-setup.png) + +In this setup, the gateway runs inside a Docker container and the BACnet device is located on a local network with IP +address `192.168.1.200:45606` and is not directly accessible from the Docker container. BACPypes sends APDUs to the +gateway without including the port number, making it impossible for the connector to determine whether a response came +from an allowed device. When you configure an alternative response address, the connector uses this IP to correctly +recognize and validate the device. + +To configure the alternative response address, you need to add the `altResponsesAddresses` field to the device +configuration. Here is an example configuration snippet: -For example, if gateway running via the docker container and the BACnet device is located in the local network under -192.168.1.200:45606, you can specify the IP address of the BACnet device in the alternative responses addresses field. ```json -"altResponsesAddresses": ["192.168.1.200"] +{ + "application": { + "objectName": "TB_gateway", + "host": "0.0.0.0", + "port": 47808, + "mask": 24, + "objectIdentifier": 599, + "maxApduLengthAccepted": 1476, + "segmentationSupported": "segmentedBoth", + "vendorIdentifier": 15, + "deviceDiscoveryTimeoutInSec": 5, + "devicesDiscoverPeriodSeconds": 30 + }, + "devices": [ + { + "deviceInfo": { + "deviceNameExpressionSource": "expression", + "deviceNameExpression": "BACnet Device ${objectName}", + "deviceProfileExpressionSource": "constant", + "deviceProfileExpression": "default" + }, + "host": "192.168.1.200", + "port": 45606, + "altResponsesAddresses": ["192.168.1.200"], + "pollPeriod": 10000, + "attributes": [], + "timeseries": "*", + "attributeUpdates": [], + "serverSideRpc": [] + } + ] +} ``` +{:.copy-code} + +After applying this configuration, the connector will use the specified alternative response address +`192.168.1.200:45606` to recognize and validate responses from the BACnet device. This ensures that the connector can +communicate effectively with the device even when they are located in different networks. As a result, you should see +created device in ThingsBoard: -This is important because bacpypes provide APDU to the gateway without port number, so the connector can't determine if -it is an allowed device. In this case, the connector will use the alternative address to determine that it is an allowed -device. +![image](/images/gateway/bacnet-connector/examples/alternative-responses-addresses-overview.png) diff --git a/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/dynamic-device-name-and-profile.md b/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/dynamic-device-name-and-profile.md index 5ca6546f00..eea4b46327 100644 --- a/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/dynamic-device-name-and-profile.md +++ b/_includes/templates/iot-gateway/bacnet-connector/examples/time-series-and-attributes/dynamic-device-name-and-profile.md @@ -1,22 +1,63 @@ -Let’s review more examples of device name expression and device profile expression fields. - -These fields allow for the dynamic construction of a formatted device name/profile using values extracted from a JSON object. -You can specify variables to access the relevant fields in the JSON. - -You can use the following variables to extract specific device information: -- **objectName** - extracts the device's object name (e.g., "Main Controller"); -- **vendorId** - extracts the device's vendor ID, typically a numeric identifier representing the manufacturer (e.g., "1234"); -- **objectId** - extracts the device's unique object identifier (e.g., "999"); -- **address** - extracts the device's network address (e.g., "192.168.1.1"). - -**Examples:** -- "**Device ${objectName}**" If the objectName variable exists and contains "**objectName": "Main Controller**", - the device on platform will have the following name: **Device Main Controller**; -- "**Vendor: ${vendorId}**" If the vendorId variable exists and contains **"vendorId": 1234**, the device on platform - will have the following name: **Vendor: 1234**; -- "**Device ID: ${objectId} at ${address}**" If the objectId variable exists and contains **"vendorId": 999** and - address variable exists and contains **"address": "192.168.1.1"**, the device on platform will have the following - name: **Device ID: 999 at 192.168.1.1**. +BACnet connector allows you to set dynamic device names and profiles using expressions. This is especially useful when +you have multiple devices with similar configurations and want to differentiate them based on their properties. +In this example, we will configure a BACnet device to have a dynamic device name based on its `objectName` and `address` +properties and a dynamic device profile based on its `vendorId` property. +Here is an example configuration snippet for a BACnet device with dynamic device name and profile: + +```json +{ + "application": { + "objectName": "TB_gateway", + "host": "YOUR_HOST", + "port": 47808, + "mask": 24, + "objectIdentifier": 599, + "maxApduLengthAccepted": 1476, + "segmentationSupported": "segmentedBoth", + "vendorIdentifier": 15, + "deviceDiscoveryTimeoutInSec": 5, + "devicesDiscoverPeriodSeconds": 30 + }, + "devices": [ + { + "host": "*", + "port": "*", + "pollPeriod": 10000, + "deviceInfo": { + "deviceNameExpressionSource": "expression", + "deviceNameExpression": "${objectName} at ${address}", + "deviceProfileExpressionSource": "expression", + "deviceProfileExpression": "${vendorId}_profile" + }, + "attributes": [], + "timeseries": "*", + "attributeUpdates": [], + "serverSideRpc": [] + } + ] +} +``` +{:.copy-code} + +In this configuration: +- The `deviceNameExpression` is set to `${objectName} at ${address}`, which will create a device name that includes the + device's object name and address. +- The `deviceProfileExpression` is set to `${vendorId}_profile`, which will create a device profile name based on the vendor ID of the device. + +After applying this configuration, the device will be created with a name and profile that reflect its specific +properties. The screenshot below shows how the device appears in ThingsBoard with the dynamic name and profile: + +![image](/images/gateway/bacnet-connector/examples/dynamic-device-name-and-profile-overview.png) + +As you can see, the device name is generated based on the `objectName` and `address`, and the device profile is based +on the `vendorId`. + +Device name/profile dynamic expressions provide flexibility in managing multiple BACnet devices with varying +configurations and can help in organizing devices effectively within ThingsBoard. + +{% capture dynamicDeviceNameProfileExample %} You can find full list of available variables in the [Advanced configuration](/docs/iot-gateway/config/bacnet/#available-variables-for-device-nameprofile-expressions) section. +{% endcapture %} +{% include templates/info-banner.md content=dynamicDeviceNameProfileExample %} diff --git a/images/gateway/bacnet-connector/examples/alternative-responses-addresses-network-setup.png b/images/gateway/bacnet-connector/examples/alternative-responses-addresses-network-setup.png new file mode 100644 index 0000000000..3d551c3952 Binary files /dev/null and b/images/gateway/bacnet-connector/examples/alternative-responses-addresses-network-setup.png differ diff --git a/images/gateway/bacnet-connector/examples/alternative-responses-addresses-overview.png b/images/gateway/bacnet-connector/examples/alternative-responses-addresses-overview.png new file mode 100644 index 0000000000..3e665f6852 Binary files /dev/null and b/images/gateway/bacnet-connector/examples/alternative-responses-addresses-overview.png differ diff --git a/images/gateway/bacnet-connector/examples/dynamic-device-name-and-profile-overview.png b/images/gateway/bacnet-connector/examples/dynamic-device-name-and-profile-overview.png new file mode 100644 index 0000000000..5e478a2c93 Binary files /dev/null and b/images/gateway/bacnet-connector/examples/dynamic-device-name-and-profile-overview.png differ