MQTT Settings ====================== Settings to configure and manage MQTT communication to enable reliable data transmission between your data logger and MQTT broker. Device UID ---------- ``Settings.UID`` A unique identifier assigned to the data logger at the factory. A UID can also be obtained using the Device Configuration Utility. The UID is used as part of the topic structure in MQTT communications to uniquely identify the logger in the message hierarchy. The UID is also used in the HTTP Header ``Campbell-Product-UID: ABCD-EFGH-1234`` .. rubric:: Properties - **Type**: String (Length: 14) - **Setting ID Number**: 399 MQTT Enable ----------- ``Settings.MQTTEnable`` Controls whether MQTT is enabled on the data logger and specifies the security mode. .. rubric:: Properties - **Type**: Int 0. Disable MQTT 1. Enable with TLS-Mutual Authentication 2. Enable with TLS 3. Enable MQTT - **Setting ID Number**: 410 CampbellCloud Enabled --------------------- ``Settings.CampbellCloudEnable`` Enables automatic connection to a cloud endpoint to retrieve a configuration file. The endpoint is specified in the Cloud Config URL setting, which by default points to Campbell Cloud. .. rubric:: Properties - **Type**: Int 0. Disabled 1. Enabled - **Setting ID Number**: 430 MQTT State ---------- ``Settings.MQTTState`` Specifies the current operational state of MQTT communication. This is a read-only, auto-refreshing status indicator used for monitoring connection and session progress. .. rubric:: Properties - **Type**: Int 0. Disabled / Off 10. Waiting for an IP network interface 11. Connection retry wait 20. Opening TCP connection 21. TCP Open failed 22. TCP connection opened 24. Closing TCP connection 26. TCP connection closed 30. TLS handshake started 31. TLS handshake failed 32. TLS handshake success 50. MQTT session established 51. Waiting for session start response 52. Publishing 100. Onboard started 101. Onboard retry 102. Onboard processing - **Setting ID Number**: 432 MQTT Broker URL --------------- ``Settings.MQTTEndPoint`` Specifies the server URL for the MQTT broker that the data logger will connect to for publishing and receiving messages. .. rubric:: Properties - **Type**: String (max length: 255) - **Setting ID Number**: 400 MQTT Connection --------------- ``Settings.MQTTCleanSession`` Selects the type of connection used when communicating with the MQTT broker. .. rubric:: Properties - **Type**: Int 0. Persistent — Maintains session state between connections. Subscriptions and undelivered messages are preserved by the broker across reconnects. 1. Clean — Establishes a new session each time the client connects. No session state is stored after disconnection. - **Setting ID Number**: 411 MQTT Auto-Publish Data ----------------------- ``Settings.MQTTAutoPublish`` Enables automatic publishing of eligible Data Tables to the MQTT broker without requiring program modifications. This option simplifies onboarding existing data logger applications to Campbell Cloud. .. rubric:: Properties - **Type**: Int 0. Disabled 1. Enabled - **Setting ID Number**: 434 .. note:: **Auto-Publish Conditions**: - The CRBasic program must **not** contain any `MQTTPublishTable()` instructions. - The Data Table must include the `DataInterval()` instruction. - Data tables with **storage intervals < 1 minute** are excluded. - Data tables with **storage intervals between 1 and 10 minutes** are published **every 10 minutes**. - Data tables with **storage intervals > 10 minutes** are published at their **defined interval**. MQTT Server Port ---------------- ``Settings.MQTTPortNumber`` Specifies the port number used to establish a connection with the MQTT broker. .. rubric:: Properties - **Type**: UInt (2 bytes; range: 0–65535). - Common defaults: - 1883: Standard MQTT (unencrypted) - 8883: MQTT over TLS - **Setting ID Number**: 401 Status Info Publish Interval ---------------------------- ``Settings.MQTTStatusInterval`` Specifies the interval, in **minutes**, between automatic MQTT publications of system status information. A value of `0` disables this feature. `status `_ .. rubric:: Properties - **Type**: UInt (2 bytes; range: 0–1440) - 0: Disabled - 1–1440: Interval in minutes between status info publications - **Setting ID Number**: 395 State Publish Interval ---------------------- ``Settings.MQTTStateInterval`` Specifies the interval, in **minutes**, between periodic MQTT publications of the data logger's online/offline and file transfer state. A value of `0` disables **periodic** updates but does **not** disable publishing when a state change occurs. `state `_ .. rubric:: Properties - **Type**: UInt (2 bytes; range: 0–1440) - 0: Disable periodic updates (state changes are still published) - 1–1440: Interval in minutes between state info publications - **Setting ID Number**: 396 Keep Alive ---------- ``Settings.MQTTKeepAlive`` Defines the interval, in **seconds**, between MQTT ping packets sent from the data logger to the broker. If the broker does not receive a ping within this interval, it will consider the connection lost and disconnect the client. A value of `0` disables the keep-alive mechanism and the broker's timeout enforcement. .. rubric:: Properties - **Type**: UInt (2 bytes; range: 0–65535) - 0: Disable keep-alive and broker timeout - 1–65535: Interval in seconds between MQTT ping packets - **Setting ID Number**: 405 MQTT Client ID -------------- ``Settings.MQTTClientID`` Specifies a unique client identifier used by the data logger, including in certain message payloads such as the state topic. This setting is distinct from the UID, although it can be configured to use the same value. By default, the Client ID is set to _. .. rubric:: Properties - **Type**: String (max length: 63 characters) - **Setting ID Number**: 402 MQTT User Name -------------- ``Settings.MQTTUserName`` Specifies the user name used by the data logger to authenticate with the MQTT broker if configured. This is typically required when the broker enforces client authentication. .. rubric:: Properties - **Type**: String (max length: 255 characters) - **Setting ID Number**: 403 MQTT Password ------------- ``Settings.MQTTPassword`` Specifies the password used by the data logger to authenticate with the MQTT broker if configured. This setting is typically used in conjunction with the MQTT User Name. .. rubric:: Properties - **Type**: String (max length: 255 characters; password-protected) - **Setting ID Number**: 404 MQTT Last Will Topic -------------------- ``Settings.MQTTWillTopic`` Specifies the MQTT topic that the broker will publish to if the data logger disconnects unexpectedly—without sending an MQTT Disconnect command. This is part of the MQTT "Last Will and Testament" feature used to signal ungraceful client disconnections. .. rubric:: Properties - **Type**: String (max length: 63 characters) - **Setting ID Number**: 406 MQTT Last Will Message ---------------------- ``Settings.MQTTWillMessage`` Defines the message that the MQTT broker will publish to the configured Last Will Topic if the data logger disconnects unexpectedly—without issuing an MQTT Disconnect command. This message is used to notify clients or systems of an ungraceful shutdown. .. rubric:: Properties - **Type**: String (max length: 255 characters) - **Setting ID Number**: 407 MQTT Last Will Topic Publish QoS -------------------------------- ``Settings.MQTTWillQoS`` Specifies the Quality of Service (QoS) level used by the MQTT broker when publishing the Last Will Message. QoS determines the guarantee of message delivery. .. rubric:: Properties - **Type**: UInt (1 byte; range: 0–2) 0. no acknowledgment 1. At least once 2. Exactly once - **Setting ID Number**: 408 MQTT Last Will Message Retained by Broker ----------------------------------------- ``Settings.MQTTWillRetain`` Specifies whether the MQTT broker should retain the Last Will Message after it is published. When retained, the message will be delivered to any new subscribers of the topic after it has been published. .. rubric:: Properties - **Type**: Int 0. Do Not Retain — The broker does not store the message after publishing. 1. Retain — The broker retains the message and delivers it to new subscribers. - **Setting ID Number**: 409 MQTT Base Topic --------------- ``Settings.MQTTBaseTopic`` Specifies the base MQTT topic used to publish packets from the data logger. The complete topic structure is determined by the MQTT API implemented on the device. For CampbellCloud accounts, this value is automatically populated according to the cloud application’s requirements. Default Value: cs/v2/ .. rubric:: Properties - **Type**: String (max length: 255 characters) - **Validation**: Must conform to valid MQTT topic syntax; otherwise, an "Invalid MQTT Topic format" error is raised. - **Setting ID Number**: 398 Cloud Config URL ---------------- ``Settings.CloudConfigURL`` Specifies the HTTP or HTTPS URL that the data logger will use to retrieve a configuration file. This setting is only active when **CampbellCloud Enabled** is set to `1`. By default, it points to the URL used to obtain CampbellCloud configuration. .. rubric:: Properties - **Type**: String (max length: 128 characters) - **Setting ID Number**: 431 Max TLS Server Connections -------------------------- ``Settings.TLSConnections`` Controls the number of concurrent secure (TLS) client socket connections the data logger can support. This setting impacts all TLS-enabled services including FTPS, HTTPS, and MQTT (if TLS is used). If MQTT is configured with TLS, this value should be set to at least `2`: one connection for the MQTT broker, and one for the https endpoint for the cloud config url. This setting also affects the available system memory. Each TLS connection requires approximately 40 KB of RAM, reducing the memory available for data and program storage. Changing this value will cause the data logger to recompile its program to reallocate memory. .. rubric:: Properties - **Type**: Int (unit: number of concurrent TLS connections) - **Recommended Minimum**: 2 if MQTT with TLS is enabled - **Memory Impact**: ~40 KB of RAM per connection (~ 80KB Total) - **Program Behavior**: Changing this setting triggers a program recompile TLS Private Key --------------- ``Settings.TLSPrivateKey`` Specifies the private key used by the data logger when establishing a secure connection to a server that requires **TLS with Mutual Authentication**. The private key must be in PEM format and correspond to the public certificate configured in ``Settings.TLSCertificate``. TLS Private Key Password ------------------------ ``Settings.TLSPassword`` Specifies the password used to decrypt the TLS Private Key if it is password-protected. TLS Certificate --------------- ``Settings.TLSCertificate`` Specifies the TLS certificate used by the data logger when establishing a secure connection to a server that requires **TLS with Mutual Authentication**. This certificate must be in PEM format and corresponds to the private key configured in ``Settings.TLSPrivateKey``. It allows the data logger to present a verified identity to the MQTT broker or other TLS-enabled services during the handshake process. TLS Root CA ----------- ``Settings.TLSRootCA`` Specifies the trusted root certificate authority (CA) used to verify the identity of the server during a TLS handshake. The root CA must be in PEM format and is required when using **TLS with Mutual Authentication**. This certificate allows the data logger to validate that the server it is connecting to (e.g., an MQTT broker) presents a certificate signed by a trusted authority. When this setting is set CARoot.pem file will be generated and located on the ``CPU:`` drive. MQTT Table Backfill Mode ------------------------- ``Settings.MQTTBackfillMode`` When the communication link between the data logger and the MQTT broker is intermittent, the data logger tracks the last successfully published record. Upon reconnection to the broker, the data logger will automatically begin publishing any unsent data. This setting defines the mode used for backfilling the data. .. rubric:: Properties - **Type**: Int 0. *All at once* – Starting with the oldest unpublished record, the data logger will attempt to publish all unsent data in sequence. Depending on the volume of data, this may occur over several back-to-back publish events. 1. *Interleave old and new* – The data logger primarily behaves as in mode 0. However, if a new record is generated during backfilling, it will momentarily publish the newest record before resuming the catch-up process. - **Setting ID Number**: 435 MQTTPublishOpt -------------- ``Settings.MQTTPublishOpt`` TODO