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.
ArduinoCloud.method()
Pushes data to the IoT Cloud.
ArduinoCloud.push()
None.
Nothing.
Sets a timestamp for a cloud variable.
ArduinoCloud.setTimestamp(cloudVariable, timestamp)
String- property nameunsigned long const- timestamp
Gets the Thing ID.
ArduinoCloud.getThingId()
None.
String- Thing ID.
Sets the Device ID.
ArduinoCloud.setDeviceId(deviceId)
String- Device ID.
Gets the Device ID.
ArduinoCloud.getDeviceId()
None
String- Device ID.
Gets the connection handler used.
ArduinoCloud.getConnection()
Gets the internal time.
ArduinoCloud.getInternalTime()
None.
unsigned long- internal time
Gets the local time (based on your time zone).
ArduinoCloud.getLocalTime()
None
unsigned long- local time
Adds a callback function for IoT Cloud events.
ArduinoCloud.addCallback(ArduinoIoTCloudEvent::CONNECT, doThisOnConnect);
ArduinoCloud.addCallback(ArduinoIoTCloudEvent::SYNC, doThisOnSync);
ArduinoCloud.addCallback(ArduinoIoTCloudEvent::DISCONNECT, doThisOnDisconnect);
- Event (CONNECT, SYNC, DISCONNECT)
- Callback function
See the ArduinoIoTCloud-Callbacks example.
Initialises the library with the connection handler specified in thingProperties.h. This is automatically generated based on the type of device.
ArduinoCloud.begin()
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 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);
Nothing.
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.
ArduinoCloud.update()
None.
Nothing.
Checks the connection status and returns an integer the connection status (int).
ArduinoCloud.connected()
None.
int- status of connection
Print any available debug information.
None
Nothing.
Adds a variable/property with a set of parameters.
ArduinoCloud.addProperty(cloudVariable, tag, permission, policy, callbackFunction)
cloudVariable- name of the variable/property.permission- can either beREAD/WRITEorREADWRITEpolicy-ON_CHANGE(whenever variable data changes) or<seconds> * SECONDS.<seconds>is specified in the Thing configuration.callBackFunction- by default, a callback function is added to a variable with WRITE permissions. A variable calledtestwill automatically be added asonTestChangewhich also is added to your sketch.
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:
ArduinoCloud.setBoardId(DEVICE_LOGIN_NAME);
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.
ArduinoCloud.setSecretDeviceKey(DEVICE_KEY);
Get the MQTT broker address used.
ArduinoCloud.getBrokerAddress()
None.
String- the MQTT broker address.
Get the MQTT broker port used.
ArduinoCloud.getBrokerPort()
None.
int- the MQTT broker port.
This function initializes the ArduinoIoTCloudLPWAN library with the specified connection handler and retry settings.
ConnectionHandler- object containingAPPEUI,APPKEYand frequency band (e.g._lora_band::EU868)bool- a boolean value that decides whether retry functionality is enabled (true) or disabled (false)
int- returns1on successful initialization.
This method handles the update between the board and the IoT Cloud.
ArduinoCloud.update()
None.
Nothing.
Checks the connection status and returns an integer the connection status (int).
ArduinoCloud.connected()
None.
int- status of connection
Print any available debug information.
None.
Nothing.
Adds a variable/property with a set of parameters.
ArduinoCloud.addProperty(cloudVariable, tag, permission, policy, callbackFunction)
cloudVariable- name of the variable/property.permission- can either beREAD/WRITEorREADWRITEtag- matches the cloud and local variables with a number. E.g. adding a second variable will have the tag2.policy-ON_CHANGE(whenever variable data changes) or<seconds> * SECONDS.<seconds>is specified in the Thing configuration.callBackFunction- by default, a callback function is added to a variable with WRITE permissions. A variable calledtestwill automatically be added asonTestChangewhich also is added to your sketch.
Nothing.
Sets the Thing ID.
ArduinoCloud.setThingId(thingId)
String- your Thing's ID. Obtainable in the IoT Cloud interface.
This method is used to check whether retry functionality is enabled.
None.
bool- returnstrueif retry functionality is enabled, otherwise returnsfalse.
This method is used to retrieve the maximum number of retry attempts.
None.
int- returns the maximum number of retry attempts as an integer.
This method is used to retrieve the interval in milliseconds between the retry attempts.
None.
long- returns the interval between retry attempts in milliseconds.
This method is used to enable or disable retry functionality.
bool- iftrue, retry functionality is enabled; iffalse, retry functionality is disabled.
Nothing.
Used to set the maximum number of retry attempts.
int- the maximum number of retry attempts to set.
Nothing.
Sets the interval in milliseconds between retry attempts.
long- the interval between retry attempts in milliseconds to set.
Nothing.