|
| 1 | +--- |
| 2 | +title: 'IoT Cloud Event & Callbacks' |
| 3 | +description: 'Learn how to subscribe to events and add callback functions.' |
| 4 | +tags: [IoT Cloud, Events, Callbacks] |
| 5 | +author: 'Karl Söderby' |
| 6 | +--- |
| 7 | + |
| 8 | +The [Arduino IoT Cloud](https://create.arduino.cc/iot/) has support for events and callbacks. This can be used to trigger specific functionalities depending on what state your device is in. |
| 9 | + |
| 10 | +You can for example trigger a specific block of code whenever the board is in a **connecting**, **synchronized** or **disconnected** state. In this document, we will explore how to set it up, using an example from the [ArduinoIoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/examples/ArduinoIoTCloud-Callbacks/ArduinoIoTCloud-Callbacks.ino) library. |
| 11 | + |
| 12 | +## Events |
| 13 | + |
| 14 | +The `ArduinoIoTCloudEvent` enumeration class has three possible events: |
| 15 | +- `CONNECT` (0) - Board successfully connects to IoT Cloud. |
| 16 | +- `SYNC` (1) - Data is successfully synced between Board and IoT Cloud. |
| 17 | +- `DISCONNECT` (2) - Board has lost connection to IoT Cloud. |
| 18 | + |
| 19 | +The `CONNECT` and `DISCONNECT` events can occur even though no variable is created inside the Thing. However, `SYNC` requires a variable to be created, as this triggers whenever data is synchronized between the board and cloud. |
| 20 | + |
| 21 | +These events can be subscribed to using the `addCallback()` function, which is documented in the next section. |
| 22 | + |
| 23 | +## Callbacks |
| 24 | + |
| 25 | +Callbacks can be added for each event, and essentially triggers a custom function whenever the event occurs. |
| 26 | + |
| 27 | +Callbacks are added via the `addCallback()` method from the `ArduinoIoTCloud` class, where the **event** and **custom function** are added as parameters. |
| 28 | + |
| 29 | +```arduino |
| 30 | +ArduinoCloud.addCallback(ArduinoIoTCloudEvent::CONNECT, doThisOnConnect); |
| 31 | +``` |
| 32 | + |
| 33 | +The above code will trigger the `doThisOnConnect()` |
| 34 | +function whenever the `CONNECT` event occurs. |
| 35 | + |
| 36 | +***Please note that callback functions should be added inside the `setup()` of your sketch.*** |
| 37 | + |
| 38 | +## Full Example |
| 39 | + |
| 40 | +The example below demonstrates how to use events & callbacks in the IoT Cloud. |
| 41 | + |
| 42 | +<CodeBlock url="https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/examples/ArduinoIoTCloud-Callbacks/ArduinoIoTCloud-Callbacks.ino" className="arduino"/> |
0 commit comments