MQTT Endpoints

Reference·Audience: API consumer·Use: look up the members, types, defaults, and limits of a configuration object

These objects are sent with config_endpoint and config_events, and returned by get_endpoint_config. Default is the value the reader uses when you omit the member. The operating-mode and post-filter objects are documented on set_operating_mode and set_post_filter.

Endpoint Configuration

cfgEndpointPayload

The epConfig object of config_endpoint.

Field	Type	Required	Default	Limits	Meaning
operation	endpointOperation enum	Yes			add, update, or delete
configuration	object (endpointConfiguration)	Yes			The endpoint configuration

The contract requires the same seven configuration members for every operation: endpointName, epType, protocol, activate, url, verificationType and port. Its own delete example sends only endpointName and epType, and its update example omits verificationType and port, so a validator built strictly from the contract rejects both. See config_endpoint.

endpointConfiguration

The configuration object, as config_endpoint sends it.

Field	Type	Required	Default	Limits	Meaning
endpointName	string	Yes		15 characters	Name of the endpoint. With epType, it selects the endpoint that an update or delete changes.
epType	epType	Yes			The class of traffic the endpoint carries. DATA2 is currently not supported.
protocol	endpointProtocol	Yes			MQTT for plaintext, or MQTT_TLS for TLS
activate	boolean	Yes	false		Whether the reader connects for this endpoint
url	string	Yes			Broker host name or IP address, without a scheme or port
verificationType	verificationType	Yes			How far the reader verifies the broker's TLS certificate
port	integer	Yes			Broker TCP port
qosCommon	integer (mqttQoS)	No			QoS level for the endpoint
tenantId	string	No		max length 48, per its description	First segment of every topic on this endpoint. An overlong value returns code 27.
mqttParams	object (mqttParams)	No			The reader's MQTT client settings and topics for this endpoint
securityParams	object (endpointSecurityParams)	No			Names of the installed certificates and key used for TLS
eventConfiguration	object (cfgEventPayload)	No			Event settings for this endpoint, in the same shape as the config_events payload
batching	object (endpointBatching)	No			Batching of tag-data reports

In a get_endpoint_config read-back, the same object requires epType, protocol, activate, url, verificationType and port, but not endpointName, and its securityParams can also carry algorithm. The reader does not check that protocol and port agree.

mqttParams

Field	Type	Required	Default	Limits	Meaning
keepAlive	integer	No		max 65535	Keep-alive interval, in seconds, while the client is idle
cleanSession	boolean	No	true		Whether the broker discards the reader's previous session when it connects
reconnectDelayMin	integer	No			Shortest wait, in seconds, before reconnecting. Must not exceed reconnectDelayMax.
reconnectDelayMax	integer	No			Longest wait, in seconds, before reconnecting
clientId	string	No			Client identifier in the reader's CONNECT packet
username	string	No			User name in the reader's CONNECT packet, when the broker requires one
password	string	No			Password in the reader's CONNECT packet, when the broker requires one. A secret: mask it.
publishTopics	array of mqttPublishTopicBinding	No			Topics the reader publishes to. The array position selects the traffic. At most 3 (code 25).
subscribeTopics	array of mqttSubscribeTopicBinding	No			The topic the reader subscribes to for commands. At most 1 (code 26).

• reconnectDelayMin must be less than or equal to reconnectDelayMax. The schema can't express this.
• The position of each publishTopics entry decides what the reader publishes on it. See Topic Slots.
• Send one subscribeTopics entry. The schema does not limit the array, and some published read-backs report three entries.

mqttPublishTopicBinding

One entry of publishTopics.

Field	Type	Required	Default	Limits	Meaning
topic	string	Yes			Base topic. The reader adds the tenant ID before it and its serial number after it.
qos	integer (mqttQoS)	Yes			QoS the reader publishes at on this topic
retain	boolean	Yes			Whether the broker retains messages published on this topic

In a get_endpoint_config read-back, topic is not required.

mqttSubscribeTopicBinding

One entry of subscribeTopics.

Field	Type	Required	Default	Limits	Meaning
topic	string	Yes			Base topic filter. The reader adds the tenant ID before it and its serial number after it.
qos	integer (mqttQoS)	Yes			Requested QoS for the subscription. The broker may grant less.
retain	boolean	Yes			Required by the contract, although an MQTT 3.1.1 subscription has no retain flag. The contract's own examples omit it.

endpointSecurityParams

The securityParams object. Each file member names a certificate or key already installed with install_certificate; none carries content.

Field	Type	Required	Default	Limits	Meaning
format	certificateFormat	Yes			Certificate format. Only PEM is currently supported.
algorithm	certificateAlgorithm	No			Reported in read-backs only
caCertificateFile	string	No			Name of the installed CA certificate used to verify the broker
clientCert	string	No			Name of the installed client certificate for mutual TLS
clientKey	string	No			Name of the installed private key that matches clientCert

endpointBatching

The batching object, which controls how tag-data reports are grouped.

Field	Type	Required	Default	Limits	Meaning
reportingInterval	integer	No		1000–60000	Reporting interval in milliseconds. 0 selects the minimum, 1000.
maxPayloadSizePerReport	integer	No		1024–5120	Maximum report size in bytes. 0 selects the minimum, 1024.

• 0 selects the minimum. It does not turn batching off.
• Defaults. The contract declares no default. The reader's default data endpoints use a reportingInterval of 1000 and a maxPayloadSizePerReport of 1024.
• Send the members together. What happens when only one member is set is not specified in the available sources, and neither is which limit applies first when both are reached.