feat(opcua): support constant datapoints (attributes + one-time telemetry) #1982

palandri · 2025-10-10T18:33:59Z

feat(opcua): support constant datapoints (attributes + one-time telemetry)

Summary

Adds first-class support for constant datapoints in the OPC-UA connector:

Attributes with type: "constant" are sent when a device is created and on every reconnection.
Telemetry with type: "constant" is sent once per device per gateway process (idempotent).
Values are auto-cast (bool/int/float) when possible; otherwise kept as string.
Telemetry is timestamped with the gateway time.
Report strategy is respected at datapoint level via TBUtility.

Motivation

Previously, OPC-UA mapping handled datapoints backed by NodeId or path expressions but ignored constants. This feature enables:

Populating device attributes with fixed metadata (e.g., Customer, Location).
Emitting one-time constant telemetry (e.g., initial setup values) without requiring OPC-UA nodes.

Implementation Details

Parsing/modeling on device side:
- Added in-memory collections (not polled/subscribed from OPC-UA):
  - constant_attributes and constant_timeseries, collected during device config parsing in python.Device.load_values().
Sending pipeline on connector:
- New routine to emit constants: python.OpcUaConnector.__send_constants_for_device().
- Invoked right after device creation in python.OpcUaConnector._create_new_devices().
- Idempotence for constant telemetry via in-memory set created in thingsboard_gateway/connectors/opcua/opcua_connector.py.
- Key building preserves report strategy: python.TBUtility.convert_key_to_datapoint_key().
- Auto type inference for constant values: python.OpcUaConnector.__guess_type_and_cast().
- Telemetry timestamp uses gateway time by default: python.TelemetryEntry.__init__().

Behavior

Attributes (type: "constant")
- Sent on device creation and every reconnection (devices are recreated on reconnect).
Telemetry (type: "constant")
- Sent exactly once per device per process (not re-sent on reconnects).

Configuration Example (new mapping format)

{
  "mapping": [
    {
      "deviceNodePattern": "Root\\.Objects\\.Device1",
      "deviceInfo": {
        "deviceNameExpressionSource": "path",
        "deviceNameExpression": "Device ${Root\\.Objects\\.Device1\\.serialNumber}",
        "deviceProfileExpressionSource": "constant",
        "deviceProfileExpression": "default"
      },
      "attributes": [
        { "key": "Customer", "type": "constant", "value": "ACME Corp" }
      ],
      "timeseries": [
        { "key": "InitialBatchSize", "type": "constant", "value": "12" }
      ]
    }
  ]
}

Casting Rules

"true"/"false" (case-insensitive) → boolean
-123 → integer
45.67 → float
Anything else → string

Backward Compatibility

No breaking changes. Existing path/identifier-based datapoints remain unchanged.
The backward-compatibility adapter continues to set type: "constant" where applicable; the new pipeline now handles those entries.

Tests / Verification

Unit tests (added in this PR):
- tests/unit/connectors/opcua/test_constants.py
  - Validates parsing buckets for constants and idempotent behavior of one-time constant telemetry.
- Fixture config:
  - tests/unit/connectors/opcua/data/constants/opcua_config_constants.json
Blackbox (optional, requires TB test environment):
- Example configuration to validate runtime behavior:
  - tests/blackbox/data/opcua/configs/uplink_configs/constants_config.json
- Integrates with existing OPC-UA blackbox harness. Not executed as part of this PR by default.

Documentation Impact

Update OPC-UA connector mapping docs to include:
- Support for type: "constant" in attributes and timeseries.
- Semantics (attributes on create/reconnect, telemetry one-time).
- Casting rules and gateway timestamp.
- Example mapping similar to the snippet above.

Touched Code

Device parsing and storage:
- thingsboard_gateway/connectors/opcua/device.py
- python.Device.load_values()
Connector logic:
Utilities and entities (used as-is):
- python.TBUtility.convert_key_to_datapoint_key()
- python.TelemetryEntry.__init__()
Tests:

Checklist

Parse/store constant datapoints (no OPC-UA read required)
Send constant attributes on create/reconnect
Send constant telemetry once per device per process
Type inference and gateway timestamp
Datapoint-level report strategy
Unit tests
Blackbox validation on TB test environment
Documentation and CHANGELOG updates

…emetry) Parse/store type: constant datapoints; send constant attributes on device creation and reconnection; send constant telemetry once per device per process; type inference (bool/int/float/string) with gateway timestamp; respect reportStrategy via TBUtility.convert_key_to_datapoint_key; backward compatible path/identifier behavior.

…ime telemetry) Add fixture config and unit test validating parsing buckets and idempotent constant telemetry send.

samson0v · 2025-10-14T07:24:45Z

Hi @palandri, thanks for your contribution! We really appreciate it.
I will take a look at your PR soon.

palandri · 2025-10-18T17:42:44Z

Hello @samson0v. Do not worry, there is no hurry.
I'm looking forward your opinion on this.

Cheers.

samson0v · 2025-11-18T08:37:49Z

Hi @palandri, I am reviewing your PR and have a question about this:

Attributes (type: "constant")
    Sent on device creation and every reconnection (devices are recreated on reconnect).
Telemetry (type: "constant")
    Sent exactly once per device per process (not re-sent on reconnects).

Why did you decide to use different strategies for sending?

samson0v · 2025-11-18T08:41:55Z