From 967290694df358e8f6ee0325392229f0689e4c2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 27 Sep 2023 11:05:50 +0200 Subject: [PATCH 1/5] IoT Cloud Docs --- docs/api.md | 531 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 23 +++ 2 files changed, 554 insertions(+) create mode 100644 docs/api.md create mode 100644 docs/readme.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..913319fa --- /dev/null +++ b/docs/api.md @@ -0,0 +1,531 @@ +## ArduinoCloud Class (Base) + +### `ArduinoCloud (Class)` + +#### Description + +`ArduinoIoTCloud` is a class for interfacing with the Arduino IoT Cloud. It provides an interface for managing IoT Cloud connectivity, updating data, and handling events. + +Depending on what type of connection is used (TCP/LPWAN), either the `ArduinoIoTCloudTCP` or `ArduinoIoTCloudLPWAN` base classes are initialized. This specification is done in the Arduino IoT Cloud's "Thing" interface, and is reflected in the automatically generated `thingProperties.h` file. + +The above classes are inherited from the `ArduinoIoTCloudClass` base class, with methods used depending on what connection is used. + +#### Syntax + +``` +ArduinoCloud.method() +``` + +### `push()` + +#### Description + +Pushes data to the IoT Cloud. + +#### Syntax + +``` +ArduinoCloud.push() +``` + +#### Parameters + +None. + +#### Returns + +Nothing. + +### `setTimestamp()` + +Sets a timestamp for a cloud variable. + +#### Syntax + +``` +ArduinoCloud.setTimestamp(cloudVariable, timestamp) +``` + +#### Parameters + +- `String` - property name +- `unsigned long const` - timestamp + +### `setThingId()` + +Sets the Thing ID. + +#### Syntax + +``` +ArduinoCloud.setThingId(thingId) +``` + +#### Parameters +- `String` - your Thing's ID. Obtainable in the IoT Cloud interface. + +### `String & getThingId()` + +Gets the Thing ID. + +#### Syntax + +#### Parameters + +### `setDeviceId()` + +Sets the Device ID. + +#### Syntax + +``` +ArduinoCloud.setDeviceId(deviceId) +``` + +#### Parameters + +- `String` - Device ID. + +### `getDeviceId()` + +Gets the Device ID. + +#### Syntax + +``` +ArduinoCloud.getDeviceId() +``` + +#### Parameters + +None + +#### Returns + +- `String` - Device ID. + +### `setThingIdOutdatedFlag()` + +Sets a flag indicating that the Thing ID is outdated. + +#### Syntax + +``` +ArduinoCloud.setThingIdOutdatedFlag() +``` + +#### Parameters +None. + +#### Returns +Nothing. + +### `clrThingIdOutdatedFlag()` + +Clears the flag indicating that the Thing ID is outdated. + +#### Syntax + +``` +ArduinoCloud.clrThingIdOutdatedFlag() +``` + +#### Parameters +None. + +#### Returns +Nothing. + +### `getThingIdOutdatedFlag()` + +Gets the flag indicating whether the Thing ID is outdated. + +#### Syntax + +``` +ArduinoCloud.getThingOutdatedFlag() +``` + +#### Parameters +None. + +#### Returns +- Boolean (true/false) + +### `deviceNotAttached()` + +Checks if the device is not attached. + +#### Syntax + +``` +ArduinoCloud.deviceNotAttached() +``` + +#### Parameters +None. + +#### Returns + +- Boolean (true/false) + +### `getConnection()` + +Gets the connection handler used. + +#### Syntax + +``` +ArduinoCloud.getConnection() +``` + +#### Parameters + +### `getInternalTime()` + +Gets the internal time. + +#### Syntax + +``` +ArduinoCloud.getInternalTime() +``` + +#### Parameters +None. + +#### Returns +- `unsigned long` - internal time + +### `getLocalTime()` + +Gets the local time (based on your time zone). + +#### Syntax + +``` +ArduinoCloud.getLocalTime() +``` + +#### Parameters +None + +#### Returns +- `unsigned long` - local time + + +### `updateInternalTimezoneInfo()` + +Updates the internal timezone information. + +#### Syntax + +#### Parameters + +### `addCallback(ArduinoIoTCloudEvent const event, OnCloudEventCallback callback)` + +Adds a callback function for IoT Cloud events. + +#### Syntax + +``` +ArduinoCloud.addCallback(ArduinoIoTCloudEvent::CONNECT, doThisOnConnect); +ArduinoCloud.addCallback(ArduinoIoTCloudEvent::SYNC, doThisOnSync); +ArduinoCloud.addCallback(ArduinoIoTCloudEvent::DISCONNECT, doThisOnDisconnect); +``` + +#### Parameters +- Event (CONNECT, SYNC, DISCONNECT) +- Callback function + +#### Example + +See the [ArduinoIoTCloud-Callbacks](https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/examples/ArduinoIoTCloud-Callbacks/ArduinoIoTCloud-Callbacks.ino) example. + + + +## ArduinoCloud Class (TCP) + +### `begin()` (TCP) + +#### Description + +Initialises the library with the connection handler specified in `thingProperties.h`. This is automatically generated based on the type of device. + +#### Syntax + +``` +ArduinoCloud.begin() +``` + +#### Parameters + +The `ArduinoIoTPreferredConnection` object is created automatically inside a `thingProperties.h` file when configuring a Thing and depends on what type of device you use. The connection handler classes are not part of the Arduino IoT Cloud, but exists inside the [Arduino_ConnectionHandler](https://github.com/arduino-libraries/Arduino_ConnectionHandler) library (listed as a dependency). + +For example, using the `WiFiConnectionHandler`, we use the `SSID`, `PASS` parameters which are defined in the `arduino_secrets.h` file, also generated based on what you input in the Arduino IoT Cloud interface. + +``` +WiFiConnectionHandler ArduinoIoTPreferredConnection(SSID, PASS); +``` + +#### Returns +Nothing. + +### `update()` (TCP) + +#### Description + +**Note:** for LoRa devices, the `update()` function is implemented differently. See + +Responsible for updating the IoT Cloud connection. +- First it feeds a watchdog timer, making sure it is not stuck anywhere, +- then sends variable updates to the IoT Cloud (via MQTT client) +- finally, it checks for new data from the IoT Cloud (via the MQTT client) + +Any IoT Cloud sketch needs to continuously call the `update()` function, as it will otherwise time out and reset. The `update()` is by default placed inside of the `loop()`. + +**Note:** do not use the `delay()` function in the sketch, as the watchdog timer will cause the board to reset and attempt to reconnect. + +#### Syntax + +``` +ArduinoCloud.update() +``` + +#### Parameters +None. + +#### Returns +Nothing. + + +### `connected()` (TCP) + +#### Description + +Checks the connection status and returns an integer the connection status (int). + +#### Syntax + +``` +ArduinoCloud.connected() +``` + +#### Parameters +None. + +#### Returns +- `int` - status of connection + +### `printDebugInfo()` (TCP) + +#### Description + +Print any available debug information. + +#### Parameters +None + +#### Returns +Nothing. + +### `setBoardId()` + +#### Description + +This method is only enabled if you are using an ESP32/ESP8266 board, and sets the board/device id. + +#### Syntax + +``` +ArduinoCloud.setBoardId(DEVICE_LOGIN_NAME); +``` + +### `setSecretDeviceKey()` + +#### Description + +This method is only enabled if you are using an ESP32/ESP8266 based board, and sets the secret device key for the device. The secret key is only obtainable from the Arduino IoT Cloud during device configuration. + +#### Syntax + +``` +ArduinoCloud.setSecretDeviceKey(DEVICE_KEY); +``` + +### `getBrokerAddress()` + +#### Description + +Get the MQTT broker address used. + +#### Syntax + +``` +ArduinoCloud.getBrokerAddress() +``` + +#### Parameters +None. + +#### Return +- `String` - the MQTT broker address. + +### `getBrokerPort()` + +#### Description + +Get the MQTT broker port used. + +#### Syntax + +``` +ArduinoCloud.getBrokerPort() +``` + +#### Parameters +None. + +#### Return +- `int` - the MQTT broker port. + + + +## ArduinoCloud Class (LPWAN) + +### `begin()` (LPWAN) + +### Description +This function initializes the ArduinoIoTCloudLPWAN library with the specified connection handler and retry settings. + +#### Parameters +- `ConnectionHandler` - object containing `APPEUI`, `APPKEY` and frequency band (e.g. `_lora_band::EU868`) +- `bool` - a boolean value that decides whether retry functionality is enabled (`true`) or disabled (`false`) + +#### Returns + +- `int` - returns `1` on successful initialization. + +### `update()` (LPWAN) + +#### Description + +**Note:** for TCP devices, the `update()` function is implemented differently. See [ArduinoCloud Class (TCP)](). + +Responsible for updating the IoT Cloud connection. +- First it feeds a watchdog timer, making sure it is not stuck anywhere, +- then sends variable updates to the IoT Cloud (via MQTT client) +- finally, it checks for new data from the IoT Cloud (via the MQTT client) + +Any IoT Cloud sketch needs to continuously call the `update()` function, as it will otherwise time out and reset. The `update()` is by default placed inside of the `loop()`. + +**Note:** do not use the `delay()` function in the sketch, as the watchdog timer will cause the board to reset and attempt to reconnect. + +#### Syntax + +``` +ArduinoCloud.update() +``` + +#### Parameters +None. + +#### Returns +Nothing. + + +### `connected()` (LPWAN) + +#### Description + +Checks the connection status and returns an integer the connection status (int). + +#### Syntax + +``` +ArduinoCloud.connected() +``` + +#### Parameters +None. + +#### Returns +- `int` - status of connection + +### `printDebugInfo()` (LPWAN) + +#### Description + +Print any available debug information. + +#### Parameters +None. + +#### Returns +Nothing. + +## `isRetryEnabled()` + +#### Description +This method is used to check whether retry functionality is enabled. + +#### Parameters +None. + +#### Returns +- `bool` - returns `true` if retry functionality is enabled, otherwise returns `false`. + + +### `getMaxRetry()` + +#### Description +This method is used to retrieve the maximum number of retry attempts. + +#### Parameters +None. + +#### Returns +- `int` - returns the maximum number of retry attempts as an integer. + +### `getIntervalRetry()` + +#### Description +This method is used to retrieve the interval in milliseconds between the retry attempts. + +#### Parameters +None. + +#### Returns +- `long` - returns the interval between retry attempts in milliseconds. + +### `enableRetry()` + +#### Description +This method is used to enable or disable retry functionality. + +#### Parameters +- `bool` - if `true`, retry functionality is enabled; if `false`, retry functionality is disabled. + +#### Returns +Nothing. + +### `setMaxRetry()` + +Used to set the maximum number of retry attempts. + +#### Parameters +- `int` - the maximum number of retry attempts to set. + +#### Returns +Nothing. + +### `setIntervalRetry()` + +#### Description +Sets the interval in milliseconds between retry attempts. + +#### Parameters +- `long` - the interval between retry attempts in milliseconds to set. + +#### Returns +Nothing. \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 00000000..b4c95612 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,23 @@ +# ArduinoIoTCloud + +The ArduinoIoTCloud library is the central element of the firmware enabling certain Arduino boards to connect to the [Arduino IoT Cloud](https://create.arduino.cc/iot/). + +- To get started, check out the [official documentation](https://docs.arduino.cc/arduino-cloud/) +- For source code, check out the [GitHub repository](https://github.com/arduino-libraries/ArduinoIoTCloud) + + +## TCP / LPWAN + +Depending on what type of connection is used (TCP/LPWAN), either the `ArduinoIoTCloudTCP` or `ArduinoIoTCloudLPWAN` base classes are initialized. This specification is done in the Arduino IoT Cloud's "Thing" interface, and is reflected in the automatically generated `thingProperties.h` file. + +- If a board is configured as a **TCP** device, it will automatically include the `ArduinoIoTCloudTCP.h` file, and methods of the `ArduinoIoTCloudTCP` class will be made available. This is the most common option. +- If a board is configured as an **LPWAN** device, it will instead include the `ArduinoIoTCloudLPWAN.h` file, and methods of the `ArduinoIoTCloudLPWAN` class will be made available. + +As a result, functions such as `begin()`, `update()`, `connected()` and `printDebugInfo()` are documented under each corresponding class. + +## Connection Handler Library + +When the library is initalized via the `begin()` function, it will choose the specified **connection handler**, which is automatically added to your `thingProperties.h` file when configuring a Thing. + +The connection handler is done via another library, [Arduino_ConnectionHandler](https://github.com/arduino-libraries/Arduino_ConnectionHandler), which supports Wi-Fi®, GSM, NB-IoT, LoRa® & Ethernet. + From 9f3cd5a4fba87c278296c135431a0c4c1944abef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 27 Sep 2023 11:08:11 +0200 Subject: [PATCH 2/5] Update readme.md --- docs/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/readme.md b/docs/readme.md index b4c95612..b14ec789 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -17,7 +17,7 @@ As a result, functions such as `begin()`, `update()`, `connected()` and `printDe ## Connection Handler Library -When the library is initalized via the `begin()` function, it will choose the specified **connection handler**, which is automatically added to your `thingProperties.h` file when configuring a Thing. +When the library is initialized via the `begin()` function, it will choose the specified **connection handler**, which is automatically added to your `thingProperties.h` file when configuring a Thing. The connection handler is done via another library, [Arduino_ConnectionHandler](https://github.com/arduino-libraries/Arduino_ConnectionHandler), which supports Wi-Fi®, GSM, NB-IoT, LoRa® & Ethernet. From 0bc469f4ec6c1ecf5030da5d79d9c0b36148fe7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 27 Sep 2023 14:38:33 +0200 Subject: [PATCH 3/5] Added addProperty method --- docs/api.md | 43 ++++++++++++++++++++++++++++++++++++++++++- docs/readme.md | 13 +++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 913319fa..ad4dc29f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -222,7 +222,7 @@ Updates the internal timezone information. #### Parameters -### `addCallback(ArduinoIoTCloudEvent const event, OnCloudEventCallback callback)` +### `addCallback()` Adds a callback function for IoT Cloud events. @@ -329,6 +329,26 @@ None #### Returns Nothing. +### `addProperty()` (TCP) + +#### Description + +Adds a variable/property with a set of parameters. + +#### Syntax +``` +ArduinoCloud.addProperty(cloudVariable, tag, permission, policy, callbackFunction) +``` + +#### Parameters +- `cloudVariable` - name of the variable/property. +- `permission` - can either be `READ` / `WRITE` or `READWRITE` +- `policy` - `ON_CHANGE` (whenever variable data changes) or ` * SECONDS`. `` is specified in the Thing configuration. +- `callBackFunction` - by default, a callback function is added to a variable with **WRITE** permissions. A variable called `test` will automatically be added as `onTestChange` which also is added to your sketch. + +#### Returns +Nothing. + ### `setBoardId()` #### Description @@ -464,6 +484,27 @@ None. #### Returns Nothing. +### `addProperty()` (LPWAN) + +#### Description + +Adds a variable/property with a set of parameters. + +#### Syntax +``` +ArduinoCloud.addProperty(cloudVariable, tag, permission, policy, callbackFunction) +``` + +#### Parameters +- `cloudVariable` - name of the variable/property. +- `permission` - can either be `READ` / `WRITE` or `READWRITE` +- `tag` - matches the cloud and local variables with a number. E.g. adding a second variable will have the tag `2`. +- `policy` - `ON_CHANGE` (whenever variable data changes) or ` * SECONDS`. `` is specified in the Thing configuration. +- `callBackFunction` - by default, a callback function is added to a variable with **WRITE** permissions. A variable called `test` will automatically be added as `onTestChange` which also is added to your sketch. + +#### Returns +Nothing. + ## `isRetryEnabled()` #### Description diff --git a/docs/readme.md b/docs/readme.md index b14ec789..16c3cea7 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -5,6 +5,19 @@ The ArduinoIoTCloud library is the central element of the firmware enabling cert - To get started, check out the [official documentation](https://docs.arduino.cc/arduino-cloud/) - For source code, check out the [GitHub repository](https://github.com/arduino-libraries/ArduinoIoTCloud) +## thingProperties.h + +When you are create and configure a Thing in the [Arduino IoT Cloud interface](https://create.arduino.cc/iot/), the `thingProperties.h` file is generated automatically. + +This file adds all the variable/properties along with its specifications (e.g. update policy, read/write permissions), and the type of connection handler depending on what device you have attached. + +Methods such as `addProperty()` and `setThingId()` are implemented here, so there's no need for manually entering anything. + +We recommend that **you do not edit this file** as it is automatically updating whenever you make changes in the Arduino IoT Cloud. + +### Offline Editing + +If you have set up your sketch in an offline environment, make sure that whatever changes you make are reflected in this file, as it will be updated in the online environment. ## TCP / LPWAN From 732c2d9fbbcae19af72818bab04298a5ee77ec5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 27 Sep 2023 14:55:44 +0200 Subject: [PATCH 4/5] Update based on feedback removed a number of methods that are not going to be public soon, and general revised some of the other methods --- docs/api.md | 57 +++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/api.md b/docs/api.md index ad4dc29f..40aa89f6 100644 --- a/docs/api.md +++ b/docs/api.md @@ -51,26 +51,22 @@ ArduinoCloud.setTimestamp(cloudVariable, timestamp) - `String` - property name - `unsigned long const` - timestamp -### `setThingId()` -Sets the Thing ID. +### `getThingId()` + +Gets the Thing ID. #### Syntax ``` -ArduinoCloud.setThingId(thingId) +ArduinoCloud.getThingId() ``` #### Parameters -- `String` - your Thing's ID. Obtainable in the IoT Cloud interface. - -### `String & getThingId()` - -Gets the Thing ID. - -#### Syntax +None. -#### Parameters +#### Returns +- `String` - Thing ID. ### `setDeviceId()` @@ -214,14 +210,6 @@ None - `unsigned long` - local time -### `updateInternalTimezoneInfo()` - -Updates the internal timezone information. - -#### Syntax - -#### Parameters - ### `addCallback()` Adds a callback function for IoT Cloud events. @@ -355,6 +343,10 @@ Nothing. This method is only enabled if you are using an ESP32/ESP8266 board, and sets the board/device id. +Currently, the following official Arduino boards uses this method: +- [Arduino UNO R4 WiFi](https://store.arduino.cc/products/uno-r4-wifi) +- [Arduino Nano ESP32](https://store.arduino.cc/products/nano-esp32) + #### Syntax ``` @@ -430,16 +422,7 @@ This function initializes the ArduinoIoTCloudLPWAN library with the specified co #### Description -**Note:** for TCP devices, the `update()` function is implemented differently. See [ArduinoCloud Class (TCP)](). - -Responsible for updating the IoT Cloud connection. -- First it feeds a watchdog timer, making sure it is not stuck anywhere, -- then sends variable updates to the IoT Cloud (via MQTT client) -- finally, it checks for new data from the IoT Cloud (via the MQTT client) - -Any IoT Cloud sketch needs to continuously call the `update()` function, as it will otherwise time out and reset. The `update()` is by default placed inside of the `loop()`. - -**Note:** do not use the `delay()` function in the sketch, as the watchdog timer will cause the board to reset and attempt to reconnect. +This method handles the update between the board and the IoT Cloud. #### Syntax @@ -505,7 +488,21 @@ ArduinoCloud.addProperty(cloudVariable, tag, permission, policy, callbackFunctio #### Returns Nothing. -## `isRetryEnabled()` +### `setThingId()` + +Sets the Thing ID. + +#### Syntax + +``` +ArduinoCloud.setThingId(thingId) +``` + +#### Parameters +- `String` - your Thing's ID. Obtainable in the IoT Cloud interface. + + +### `isRetryEnabled()` #### Description This method is used to check whether retry functionality is enabled. From 7e66828df26bcdad2eb0fb0b466ea30526562b6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 27 Sep 2023 15:03:16 +0200 Subject: [PATCH 5/5] Update api.md --- docs/api.md | 65 ----------------------------------------------------- 1 file changed, 65 deletions(-) diff --git a/docs/api.md b/docs/api.md index 40aa89f6..e4825e2d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -100,71 +100,6 @@ None - `String` - Device ID. -### `setThingIdOutdatedFlag()` - -Sets a flag indicating that the Thing ID is outdated. - -#### Syntax - -``` -ArduinoCloud.setThingIdOutdatedFlag() -``` - -#### Parameters -None. - -#### Returns -Nothing. - -### `clrThingIdOutdatedFlag()` - -Clears the flag indicating that the Thing ID is outdated. - -#### Syntax - -``` -ArduinoCloud.clrThingIdOutdatedFlag() -``` - -#### Parameters -None. - -#### Returns -Nothing. - -### `getThingIdOutdatedFlag()` - -Gets the flag indicating whether the Thing ID is outdated. - -#### Syntax - -``` -ArduinoCloud.getThingOutdatedFlag() -``` - -#### Parameters -None. - -#### Returns -- Boolean (true/false) - -### `deviceNotAttached()` - -Checks if the device is not attached. - -#### Syntax - -``` -ArduinoCloud.deviceNotAttached() -``` - -#### Parameters -None. - -#### Returns - -- Boolean (true/false) - ### `getConnection()` Gets the connection handler used.