Configuration file

A connector is configured by one TOML file per protocol in /etc/tedge/plugins/ot/. This page is generated from config.schema.json, the schema both implementations are tested against. Protocol-specific objects (connection, protocol_address, a point’s address) are described in each connector reference.

Tip

The config workbench fills these in for you and checks the result against the same schema.

[connector]

One per file. Which protocol module runs, and the defaults every device inherits.

Key	Type	Default	Description
protocol (required)	string
service_name	string		Connector service name; defaults to ‘tedge-dot-<protocol>’. It addresses the connector’s management commands (te/device/main/service/<service>/ot/cmd/<verb>/<id>), so it must be unique on the broker and cannot be changed by set-config.
poll_interval	duration	2s	Duration string, e.g. ‘500ms’, ‘2s’, ‘5m’.
sampling_interval	duration		How often the source samples a point delivered by push (§3.1), e.g. an OPC UA monitored item’s sampling interval. Resolved point, then device, then connector; with none set, the point’s effective poll_interval. An explicit sampling_interval at any level wins over every poll_interval. Polled points ignore it. “0” asks for the source’s fastest rate.
operation_timeout	string	30s	Upper bound on a single protocol-module call (read batch, write, connect, subscribe). A module that never returns — what a half-open socket produces: no answer, no error, no reset — would otherwise block the connector’s loop forever, stopping samples, health and link status with nothing logged. The runtime turns the bound into an ordinary transport error, so the usual degraded-link and reconnect handling applies.
stall_timeout	string	120s	How long the connector’s loop may make no progress before it is treated as wedged and restarted (the supervisor cancels and re-runs it; the MQTT last will marks the service down). Must exceed operation_timeout; “0” disables the watchdog.
log_level	error | warn | info | debug | trace	info
point_library_path	array of string		Directories searched for the point libraries devices name in points_from (§3.4), most specific first. REPLACES the default path (/etc/tedge/plugins/ot/points.d then /usr/share/tedge-dot/points.d), so it must name at least one directory; omit the key to use the default. Relative entries resolve against this configuration file’s own directory.
report	report table		Default reporting policy for every point of this connector (§5.3).
output	samples | measurements	samples	What readings are published as (§5.5): one sample envelope each (default), or batched thin-edge measurements published by the runtime, with samples only for the points flows read.
measurement	table		Measurement naming in measurement output (§5.5), as the ot-measurement flow’s parameters of the same names. A point’s meta.measurement.group/series win over group/series.
batch	batch table		Default grouping policy in measurement output for every point of this connector (§5.5).
max_inflight	integer	4	Requests in flight to one endpoint, unless a device sets its own (§5.6).
max_inflight_total	integer	32	Requests in flight across all endpoints (§5.6).

[mqtt]

The thin-edge.io broker the connector publishes to. The read/write CLI ignores it.

Key	Type	Default	Description
host	string	127.0.0.1
port	integer	1883

[connection]

Protocol-specific shared connection defaults. Shape defined by the connector spec.

[[device]]

One per device. The address is protocol-specific; see the connector reference for its shape.

Key	Type	Default	Description
name (required)	string
type	string		The device type this instance is one of (§3.1): what its point list describes, not where it is. Inherited from the first point library named in points_from that declares a [library] type (§3.4) when absent here. It qualifies the device’s parameter set names (§5.2), which are tenant-wide identifiers in the cloud, and is echoed in every sample and on the link status.
protocol_address	table		Protocol-specific device address. Shape defined by the connector spec.
enabled	boolean	true	false takes the device out of the configuration (§3.3): it is not connected, polled, described or answered for, and nothing else about it is read — not even its point libraries. The definition stays in the file (and a management command can switch it back on); its name still counts for uniqueness.
poll_interval	duration		Duration string, e.g. ‘500ms’, ‘2s’, ‘5m’.
sampling_interval	duration		How often the source samples a point delivered by push (§3.1), e.g. an OPC UA monitored item’s sampling interval. Resolved point, then device, then connector; with none set, the point’s effective poll_interval. An explicit sampling_interval at any level wins over every poll_interval. Polled points ignore it. “0” asks for the source’s fastest rate.
default_mode	raw | typed
points_from	array of string		Point libraries this device inherits its points from, in order (§3.4). An entry containing ’/’ or ending in ‘.toml’ is a path (relative ones resolve against this configuration file’s directory); anything else is a name, resolved as <dir>/<protocol>/<name>.toml along the library search path. Libraries are applied in order and then the device’s own inline points, with a repeated id patching what came before: meta and transform merge key by key, every other field replaces.
point	array of point table
report	report table		Default reporting policy for this device’s points (§5.3); merged over [connector] report.
batch	batch table		Default grouping policy in measurement output for this device’s points (§5.5).
max_inflight	integer	4	Requests in flight to this device’s endpoint (§5.6); devices sharing an endpoint use the smallest value among them.

[[device.point]]

One per data point, on a device or in a point library.

Key	Type	Default	Description
id (required)	string
mode	raw | typed
datatype	bool | int8 | uint8 | int16 | uint16 | int32 | uint32 | int64 | uint64 | float32 | float64 | string | bytes
endianness	big | little	big
word_order	big | little	big
poll_interval	duration		Duration string, e.g. ‘500ms’, ‘2s’, ‘5m’.
sampling_interval	duration		How often the source samples a point delivered by push (§3.1), e.g. an OPC UA monitored item’s sampling interval. Resolved point, then device, then connector; with none set, the point’s effective poll_interval. An explicit sampling_interval at any level wins over every poll_interval. Polled points ignore it. “0” asks for the source’s fastest rate.
access	read | write | read_write | call_method	read	What the connector may do with the point (§3.1): read it, write it, both, or call it with the call-method verb (§6.6). Points that cannot be read (write, call_method) are never polled, subscribed or sampled.
unit	string
name	string		Short human-readable label for this signal, for wherever a name is displayed instead of the id — which is a topic segment and a parameter-set key, so it stays a plain identifier. Feeds a parameter’s DTM title and the capability descriptor’s point_labels (§7). Not echoed per sample.
description	string		Longer human-readable explanation of the signal. Feeds a parameter’s DTM description and the capability descriptor’s point_labels (§7). Not echoed per sample; meta.parameter.description overrides it for the parameter UI.
address	table		Protocol-specific point address. Shape defined by the connector spec.
transform	table		Linear engineering transform applied by the connector after decode: (value * multiplier * 10^decimal_shift / divisor) + offset.
report	report table		This point’s reporting policy (§5.3); merged over the device’s and [connector]‘s report.
batch	batch table		This point’s grouping policy in measurement output (§5.5); merged over the device’s and [connector]‘s batch.
map	map table		This point’s value map (§4.3): state codes to labels, ranges with a catch-all, numeric text to numbers. The samples carry the mapped value (and the unmapped one as source_value); writes carry it too and are mapped back.
meta	table		Free-form signal metadata, echoed verbatim as ‘meta’ in every sample envelope for this point. Never interpreted by the connector; flows read it for per-signal behaviour (measurement naming, alarms, events, parameters) and consumers may carry arbitrary descriptive fields. Reporting behaviour (on change, deadband, rate limit, heartbeat) belongs in ‘report’, not here.
subscribe	boolean	true	Set false to keep this point on the polling schedule even when the connector supports push delivery (subscriptions).
sample	boolean		In measurement output (§5.5): true keeps publishing this point’s samples for a consumer other than the flows; false publishes none even when a flow would read them. Unset, the runtime decides (alarm, event and parameter points, and writable points, keep their samples).
enabled	boolean	true	false leaves the point out of the device (§3.3): it is not read, subscribed, written or described. Applied to the resolved point (§3.4), so an inline { id, enabled = false } switches off a point a library supplies, and a later definition can switch it back on. A disabled point need not be complete, but what it declares is still checked for shape.

report (reporting policy)

Reporting policy (report by exception, contract §5.3), applied by the SDK runtime. Merged key by key: [connector] report, then the device’s, then the point’s in a point library, then the point’s in the configuration. A duration of “0”, on_change = false and deadband = 0 switch an inherited setting off.

See Reducing data volume and try it in the config workbench.

Key	Type	Default	Description
on_change	boolean		Publish only when the value differs from the last published one.
deadband	number or string		Minimum change from the last published value needed to publish: an absolute amount in the point’s (transformed) units, or “<p>%” of the last published value’s magnitude. Implies on_change; numeric values only.
min_interval	duration		Publish at most once per interval; a change arriving sooner is held and published when the interval ends.
max_interval	duration		Heartbeat: publish the next fresh reading once this long has passed since the last publish, even if unchanged. Pushed points are read on demand; points that cannot be read on demand (traps, CAN frames) get none. Must exceed min_interval when both are set in the same table.
debounce	duration		Publish a changed value only once it has stayed the same (within the deadband, if set) for this long. Implies on_change.

{
  "on_change": true
}

{
  "deadband": 0.5,
  "min_interval": "10s"
}

{
  "deadband": "2%"
}

{
  "max_interval": "30m"
}

map (value mapping)

Value map (contract §4.3), applied by the SDK runtime after transform on reads and reversed before the inverse transform on writes. The first matching case wins; an unmatched value takes default, else the as conversion, else the sample is bad. Every output (each to, default, the as type) is of one type, the sample’s value_repr. A later definition (§3.4) replaces the whole map; an empty table removes it. Not allowed on raw-mode or bytes points.

See Mapping values.

Key	Type	Default	Description
cases	array of any or any or any		Ordered cases; the first that matches gives the output.
default	number or string or boolean		Catch-all output for a value no case matches. Never writable.
as	number | string | bool		Convert a value no case matches to this type (numeric text to a number, a number to its shortest text, …); reversed on writes. Cannot be combined with default.

{
  "cases": [
    {
      "eq": 0,
      "to": "stopped"
    },
    {
      "eq": [
        1,
        5
      ],
      "to": "running"
    },
    {
      "min": 10,
      "max": 19,
      "to": "warning"
    },
    {
      "min": 20,
      "to": "fault",
      "write": 20
    }
  ],
  "default": "unknown"
}

{
  "as": "number"
}