Onboarding
==============================
This is an automated process to connect a data logger to a cloud environment.
**Onboarding** refers to an HTTP GET request to a specified URL, which returns a complete set of configuration settings required for the data logger to connect to an MQTT broker.
.. admonition:: Purpose
- Automates initial connection of new devices to a cloud
- Eliminates the need for manual configuration deployment
- Rotation of TLS certificates
Onboarding Workflow
-------------------
The onboarding process involves the following steps:
1. The data logger sends an HTTP GET request to a cloud configuration server to retrieve a configuration recipe.
The server URL must be specified in the ``Cloud Config URL`` setting.
2. Upon receiving the request, the server must respond with a valid configuration recipe file.
3. The data logger ingests the contents of the configuration recipe, applies the settings, and reboots to accommodate the changes.
4. After rebooting, the data logger attempts to establish an MQTT session with the specified broker.
.. image:: images/onboard_process.png
.. note::
The success of this onboarding process depends heavily on the following:
- The availability and correct configuration of the HTTP configuration server
- The accuracy and completeness of the configuration recipe
- The correct configuration of the MQTT broker (e.g., authentication methods, topic structures)
Onboarding to CampbellCloud
---------------------------
The following process will onboard a data logger to CampbellCloud.
Device Configuration Utility will be used to configure the data logger.
Data Logger Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
1. Confirm the device UID is set.
.. image:: images/device_uid.JPG
2. Confirm the Cloud Config URL is directed to CampbellCloud. [https://iot.campbell-cloud.com/api/v1/libraries/recipes]
.. image:: images/campbellcloud_url.JPG
3. Set:
- MQTT Enable - ``Enable with TLS-Mutual Authentication``
- CampbellCloud Enabled - ``Enabled``
- MQTT Broker URL - Clear/Empty
.. image:: images/onboard_3_settings.JPG
4. Apply settings
Recipe
~~~~~~
5. The data logger will reboot after settings have been applied.
- The Cloud Config URL is using HTTPS and MQTT(S). On reboot the data logger will automatically adjust the Max TLS Server connections = 1 to allocate memory for handling TLS communications. Allocating the memory for TLS will force the logger to reboot.
6. The Data logger will send an HTTP GET request to the Cloud Config URL to retrieve a configuration recipe
Example request:
.. code-block:: http
GET /api/v1/libraries/recipes HTTP/1.1
User-Agent: CR6.14.3.0
Host: api.campbellcloud.xyz
Campbell-Product-UID: ABCD-EFGH-1234
Campbell-Protocol: mqtt
Example response:
.. code-block:: http
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=mqtt_onboard.bin
Content-Type: application/json
Content-Length: 45884
7. The data logger will save the recipe as **CPU:mqtt_onboard.bin**
.. code-block:: json
{
"version": "1.0.1",
"initial_configurations": [
{
"data": {
"MQTTAccountID": "",
"MQTTBaseTopic": "csV2/1111111111111111111112/1111111111111111111112/",
"MQTTCleanSession": "0",
"MQTTClientID": "ABCD-EFGH-1234",
"MQTTEnable": "1",
"MQTTEndpoint": "us-west-2.mqtt.campbell-cloud.com",
"MQTTKeepAlive": "43200",
"MQTTPassword": "",
"MQTTPortNumber": "8883",
"MQTTStateInterval": "0",
"MQTTStatusInterval": "0",
"MQTTUserName": "",
"MQTTWillMessage": "ABCD-EFGH-1234",
"MQTTWillQoS": "0",
"MQTTWillRetain": "0",
"MQTTWillTopic": "csV2/1111111111111111111112/1111111111111111111112/last",
"TLSCertificate":
"-----BEGIN CERTIFICATE-----\n
MIICTzCCAfSgAwIBAgIUXgM1s0lmMRBPhhyeJaAflV3PdfowCgYIKoZIzj0EAwIw\n
GzEZMBcGA1UEAxMQY2FtcGJlbGxjbG91ZC5pbzAeFw0yNTA3MjgxNTQzNDZaFw0y\n
NTA4MTExNTQ0MTZaMBsxGTAXBgNVBAMTEGNhbXBiZWxsY2xvdWQuaW8wWTATBgcq\n
hkjOPQIBBggqhkjOPQMBBwNCAASqAHBIOc+yk/yxl35vAbm6ij7X7VaIx1EgBeVh\n
BYGL+GLUa5purvRqbBzaf/epFsl8lAxnpiDx3acmwgicdj0Go4IBFDCCARAwDgYD\n
VR0PAQH/BAQDAgOoMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNV\n
HQ4EFgQUiPJvqZygJTXkYKNgwZO6/H1MU8YwHwYDVR0jBBgwFoAUPEGTAYBfmgf1\n
G4+j/THukkuALfIwPQYIKwYBBQUHAQEEMTAvMC0GCCsGAQUFBzAChiFodHRwOi8v\n
dmF1bHQudmF1bHQ6ODIwMC92MS9wa2kvY2EwKwYDVR0RBCQwIoIOVDQ4VC1DQlNK\n
LVRERkKCEGNhbXBiZWxsY2xvdWQuaW8wMwYDVR0fBCwwKjAooCagJIYiaHR0cDov\n
L3ZhdWx0LnZhdWx0OjgyMDAvdjEvcGtpL2NybDAKBggqhkjOPQQDAgNJADBGAiEA\n
hto5MoEt4SsQgzV8VhTCWv02BVDoUMKLM9T4SmKyM98CIQCqgXKlYmC8nX81q/L4\n
rw4V+k1Hp3oreFn3PC2a5/dOHQ==\n
-----END CERTIFICATE-----",
"TLSPrivateKey":
"-----BEGIN EC PRIVATE KEY-----\n
MHcCAQEEIK7Hc/snAotxLnwE52dfpa9uFBsLKm5fwOnaie0urJfKoAoGCCqGSM49\n
AwEHoUQDQgAEqgBwSDnPspP8sZd+bwG5uoo+1+1WiMdRIAXlYQWBi/hi1Guabq70\n
amwc2n/3qRbJfJQMZ6Yg8d2nJsIInHY9Bg==\n
-----END EC PRIVATE KEY-----",
"TLSRootCA":
"-----BEGIN CERTIFICATE-----\n
MIIBuTCCAV+gAwIBAgIUKuUUaYKi1Zc5QEZE13dBRURqFRwwCgYIKoZIzj0EAwIw\n
GzEZMBcGA1UEAxMQY2FtcGJlbGxjbG91ZC5pbzAeFw0yNDA5MjUyMTQ3NDdaFw0y\n
OTA5MjQyMTQ4MTdaMBsxGTAXBgNVBAMTEGNhbXBiZWxsY2xvdWQuaW8wWTATBgcq\n
hkjOPQIBBggqhkjOPQMBBwNCAAQ0KR8u0JLhZ44w/GeFEScRIRdwxbCKuhP1Oxn8\n
ddQNZz2Gk9tdUoZ7tOj8TwWHQeoKBSG1wdu+YlaD590lm0Lyo4GAMH4wDgYDVR0P\n
AQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFDxBkwGAX5oH9RuP\n
o/0x7pJLgC3yMB8GA1UdIwQYMBaAFDxBkwGAX5oH9RuPo/0x7pJLgC3yMBsGA1Ud\n
EQQUMBKCEGNhbXBiZWxsY2xvdWQuaW8wCgYIKoZIzj0EAwIDSAAwRQIhAJbpmTXi\n
crig68ws7iBb6UZwBc9kNyh6dUQwi677qdv4AiArQAj8kPywtwQK/eEloJt09bo2\n
YDzU0dSLY9zEhRDceA==\n
-----END CERTIFICATE-----"
},
"name": "setting"
}
],
"metadata": {
"cert_exp_timestamp": "2025-08-11T15:44:16Z"
},
"certificate": {
"issued_epoch": 1753717456611,
"serialNumber": "5e:03:35:b3:49:66:31:10:4f:86:1c:9e:25:a0:1f:95:5d:cf:75:fa",
"expiration": "2025-08-11T15:44:16Z",
"expiration_epoch": 1754927056000
},
"name": "cloud_onboard",
"acl": {
"csV2/1111111111111111111112/1111111111111111111112/cr/7GY3-DZYK-KBWF/#": "w",
"csV2/1111111111111111111112/1111111111111111111112/cc/7GY3-DZYK-KBWF/#": "r"
}
}
8. When the Recipe is received the settings and TLS certificates will be applied and the data logger will reboot again. The data logger may take a few minutes to connect to the cloud.
.. image:: images/onboard_established.JPG
10. After onboarding, the data logger is ready to be claimed as an asset in
`CampbellCloud `_.
If the **base topic** and **last will topic** appear as a sequence of 1's
(e.g., ``csV2/1111111111111111111112/1111111111111111111112/``), this
indicates that the data logger is connected to CampbellCloud but has not
yet been claimed.
Onboarding to Custom Environment
--------------------------------
Onboarding to a custom environment follows the same process as onboarding to
`CampbellCloud `_.
- MQTT is *not* a requirement for onboarding.
When paired with a valid and constructive recipe, the onboarding process can be used to onboard a data logger to any custom environment.
- An HTTP server must be available for the data logger to request the onboarding recipe.
- The ``Cloud Config URL`` setting must point to the server responsible for handling the HTTP GET request.
- The server must respond with a valid recipe that includes any necessary settings and operations for the data logger to execute. see `Recipes `_