Skip to content

Cloud: support for multiple servers

Jump to bottom
Daniel Adam edited this page Apr 15, 2024 · 10 revisions

When provisioning to an OCF Cloud is initiated, the URI of the OCF Cloud is sourced from the cis property of the Cloud Configuration resource. (The identity of the OCF Cloud is stored in the sid property of the resource). Previously, the device could only store a single (URI, ID) pair. A scenario might arise where the primary cloud server is unavailable; in this case, the device detects the loss of the cloud connection and attempts to reconnect at periodic intervals. However, if a backup cloud server is available, we want the device to attempt to connect there if the primary server is down. To address this scenario, support for setting multiple cloud servers and selecting between them was added.

Cloud Configuration Resource

The Cloud Configuration resource has been extended with the x.org.iotivity.servers property, which is a list of available cloud server addresses. Each item in this list is a pair consisting of a URI and an ID. The URIs must be unique, while the IDs may not be.

An example of the JSON representation of the Cloud Configuration resource extended for multiple servers in (retrievable by a GET request):

{
  ...

  "cis": "coap+tcp://127.0.0.1:5683",
  "sid": "00000000-0000-0000-0000-000000000001",
  "x.org.iotivity.servers": [
    {
      "uri": "coap+tcp://127.0.0.1:5683",
      "id": "00000000-0000-0000-0000-000000000001"
    },
    {
      "uri": "coap+tcp://mock.cloud:5683",
      "id": "01020304-0506-0708-090a-0b0c0e0f1000"
    }
  ]

  ...
}

All available cloud server addresses are listed in the x.org.iotivity.servers property. To determine which address is currently selected, examine the cis and sid properties. The cis property contains the URI of the selected server addresses, and the sid property contains the ID of the selected server addresses.

As a minor optimization, when your device contains only a single available server, the x.org.iotivity.servers property is not returned in the response to a GET request on the resource. However, the cis and sid properties are returned and contain the values from the selected server address. This ensures backward compatibility of devices with a single available cloud server address.

Modifying cloud server addresses via C API

A new C API is available to modify the cloud servers in the oc_cloud.h public header.

  • oc_cloud_add_server_address: Adds a server address to the list of available cloud server addresses.
  • oc_cloud_remove_server_address: Removes a server address from the list.
  • oc_cloud_select_server_address: Selects a server address from the list.
  • oc_cloud_selected_server_address: Returns the selected server address.
  • oc_cloud_iterate_server_addresses: Iterates over the list.

Persistence

The list of cloud server addresses and current selection are stored as part of the cloud data in the persistent storage. Each change in the selection of the cloud server address triggers saving of the data to the storage. Therefore, both the list of server addresses and the selection persist after device restart.

oc_cloud_provision_conf_resource

Calling oc_cloud_provision_conf_resource with valid parameters updates the Cloud Resource configuration, and this update also changes the list of available cloud server addresses. The original list of server addresses is replaced with a list containing a single server address, whose properties are set to the values of the parameters provided to the function call.

Modifying cloud server addresses by a POST request

The list of cloud server addresses and the selection can be modified by a POST request. Similar to a call to oc_cloud_provision_conf_resource, such a POST request will replace the original list of cloud servers with a list containing the selected server, whose properties are set to the cis and sid properties and the array of servers defined by the x.org.iotivity.servers property contained in the request payload.

Redirect

If OCF Cloud provides redirecturi property in the response during Device Registration then the currently selected cloud server is replaced by a new server with the same ID, but with the URI contained in the redirecturi property.

Retry

If any of the onboarding steps (except registration) to an OCF cloud fail, or if an onboarded device loses connection to the OCF Cloud, the retry mechanism will kick in. The retry mechanism tries indefinitely to reconnect to the cloud in periodic intervals. The retry loop makes six attempts at increasing time intervals (2s, 4s, 8s, 16s, 32s, 64s; as of version v2.2.5.12). Once the sixth attempt has been made, the retry mechanism is reset and starts again. This functionality has been extended so that whenever a retry loop of six attempts is finished, the system checks if multiple servers are available. If multiple servers are available, the selection changes to the next cloud server. The servers are considered to be in a circular list, so when the last element in the list is reached, the next loop will use the first element in the list. If the behavior of the retry mechanism is customized using oc_cloud_set_schedule_action, automatic selection of the next cloud server will not occur by default. If the change of cloud server selection is desired, the caller can implement it in the oc_cloud_schedule_action_cb_t callback provided to oc_cloud_set_schedule_action.

TODO

  • Extend oc_cloud_provision_conf_resource to allow setting of multiple cloud servers

Clone this wiki locally