diff --git a/managed-services/iot-hub/api-cli/connecting-twins-to-grafana-cloud.mdx b/managed-services/iot-hub/api-cli/connecting-twins-to-grafana-cloud.mdx deleted file mode 100644 index 58a7898ee0..0000000000 --- a/managed-services/iot-hub/api-cli/connecting-twins-to-grafana-cloud.mdx +++ /dev/null @@ -1,233 +0,0 @@ ---- -meta: - title: How to connect IoT Cloud Twins to Grafana Cloud - description: This tutorial shows how to connect Cloud Twins to a graphite instance on Grafana Cloud. -content: - h1: How to connect IoT Cloud Twins to Grafana Cloud - paragraph: This tutorial shows how to connect Cloud Twins to a graphite instance on Grafana Cloud. -totalTime: PT15M -tags: iot iot-hub mqtt twins cloud-twins grafana grafana-cloud graphite -categories: - - managed-services ---- - - - - -This tutorial will show how to connect Cloud Twins to a Graphite instance on Grafana Cloud. This allows you to monitor and view events on your Cloud Twin (updates or modifications of its document's values). - - - The twins feature is currently in **beta** status. - - - - - You have an account and are logged into [the Scaleway console](https://console.scaleway.com) - - You have installed [curl](https://curl.se/) and [`jq` (JSON parsing tool)](https://stedolan.github.io/jq/) on your local computer - - You have [created an IoT Hub](/managed-services/iot-hub/how-to/create-hub/) - - You have [added a device](/managed-services/iot-hub/how-to/add-device/) - - You have [created a Grafana Cloud account](https://grafana.com/products/cloud/) - - Your Device allows insecure connections - - - - When designing a production system, you should `Deny Insecure` connections to have the highest level of security. - - -Configure the following variables from a terminal on your local computer: - -```bash -IOT_API="https://api.scaleway.com/iot/v1/regions/fr-par" -SCW_SECRET_KEY="" -SCW_PROJECT="" -HUB_ID="" -DEVICE_ID="" -``` - -## Connect your hub to Grafana Cloud - -1. Recover your username under `user identifier` on the Grafana [credentials page](https://grafana.com/orgs/user-identifier/api-keys). -2. Generate a MetricsPublisher key and store the returned token (`GRAPHITE_TOKEN`). - - See [Create a Grafana Cloud API key](https://grafana.com/docs/grafana-cloud/reference/create-api-key/) for details. - -3. Go to your Grafana instance: `https://user-identifier.grafana.net/`, where `user-identifier` is your username. -4. Go to the graphite configuration panel: - - Select **Configuration**, then **Data sources** in the menu (A) - - Select Graphite on the list (B) - - -5. Get the following information from the Graphite configuration panel: - - In the `HTTP` box, find the `URL` value and note the host part (`GRAPHITE_HOST`, `graphite-us-central1.grafana.net` in the example) (A) - - In the `Auth` box, find the `Basic Auth Details` and note the user (a number as your `GRAPHITE_USERID`) (B) - - -6. Construct the `push_uri` as follows: - ``` - https://GRAPHITE_USERID:GRAPHITE_TOKEN@GRAPHITE_HOST/metrics - ``` - - So it should look like: - ``` - https://12345:SecReTApiKEyVaLuE@graphite-us-central1.grafana.net/metrics - ``` -7. Set the graphite `push_uri` in your hub's configuration: - - This beta feature is only available in [the API](https://www.scaleway.com/en/developers/api/iot/). - - - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PATCH $IOT_API/hubs/$HUB_ID -d '{ - "twins_graphite_config": { - "push_uri": "https://'$GRAPHITE_USERID':'$GRAPHITE_TOKEN'@'$GRAPHITE_HOST'/metrics" - } - }' - ``` - -The Hub is now connected to Grafana cloud. - -## Using the Twin with Grafana - -Now, we will consider our Cloud Twin itself. We'll look at its document format, create a config file, and make several modifications to the document store, so that we can then see how these are logged in Grafana. - -In our example the Cloud Twin's document format is as follows: - -```json -{ - "state": { - "enable": true, - "value": 12.5, - "text": "ignored" - }, - "data": { - "value": 7.5, - "in error": false - } -} -``` - -### Set the configuration document - -In this example we want to trace: -- any write on the `state` (even when setting the same value twice) -- changes on the `data` part of the document -We therefore add a tag to those values in order to recover them easily in Grafana. - -The `_config` document will be: -```json -{ - "documents": { - "current": { - "state": {"_tsdb_trigger": "on-update"}, - "data": {"_tsdb_trigger": "on-change"}, - "_tags": { - "source": "graphite-tutorial" - } - } - } -} -``` - -Set the config document to the required format using the API as follows: - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PUT $IOT_API/twins/$DEVICE_ID/documents/_config -d '{ - "data": { - "documents": { - "current": { - "state": {"_tsdb_trigger": "on-update"}, - "data": {"_tsdb_trigger": "on-change"}, - "_tags": { - "source": "graphite-tutorial" - } - } - } - } - }' | jq - ``` - -### Simulate some events -1. Create the twin document - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PUT $IOT_API/twins/$DEVICE_ID/documents/current -d '{ - "data": { - "state": { - "enable": false, - "text": "ignored" - } - } - }' | jq - ``` -2. Change it - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PUT $IOT_API/twins/$DEVICE_ID/documents/current -d '{ - "data": { - "state": { - "enable": true, - "value": 12.5, - "text": "ignored" - }, - "data": { - "value": 7.5, - "in error": false - } - } - }' | jq - ``` -3. Update only the `data` section using patch - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PATCH $IOT_API/twins/$DEVICE_ID/documents/current -d '{ - "data": { - "data": { - "value": 12.5 - } - } - }' | jq - ``` -4. Set the whole document again, without changing anything - ```bash - curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -X PUT $IOT_API/twins/$DEVICE_ID/documents/current -d '{ - "data": { - "state": { - "enable": true, - "value": 12.5, - "text": "ignored" - }, - "data": { - "value": 12.5, - "in error": false - } - } - }' | jq - ``` - -### Show the event in Grafana -We can now return to Grafana to see how all the modifications to our twin have been logged. - -1. Go to your Grafana instance explore panel - - select Explore (A) - - ensure the graphite source is selected (B) - - click on the pen to switch to the query editor (C) - -2. View your data - - enter the query (A) - ``` - groupByTags(seriesByTag('source=graphite-tutorial'), 'last', 'json_path', 'name') - ``` - - adjust the time range if needed (B) - - see your data (C) - -3. If you prefer lines to dots, you can use the `keepLastValue` graphite function. - - Replace the query with: - ``` - groupByTags(keepLastValue(seriesByTag('source=graphite-tutorial'), inf), 'last', 'json_path', 'name') - ``` - - - You can create a dashboard in Grafana and use similar queries in your panel. - - - - - Using Cloud Twins - Migrating from Scaleway IoT Hub API v1beta1 - diff --git a/managed-services/iot-hub/api-cli/using-twins.mdx b/managed-services/iot-hub/api-cli/using-twins.mdx deleted file mode 100644 index 6bc8698dc1..0000000000 --- a/managed-services/iot-hub/api-cli/using-twins.mdx +++ /dev/null @@ -1,262 +0,0 @@ ---- -meta: - title: Using IoT Cloud Twins - description: This page shows you how to use the Cloud Twins through both REST and inband MQTT API. -content: - h1: Using IoT Cloud Twins - paragraph: This page shows you how to use the Cloud Twins through both REST and inband MQTT API. -totalTime: PT15M -tags: iot iot-hub mqtt cloud-twins cloud twins rest -categories: - - managed-services ---- - -This page shows you how to use [Cloud Twins](/managed-services/iot-hub/concepts/#twins) through both REST and inband MQTT API. We will use the example of a Device consisting of an internet-enabled alarm control panel with a siren and door sensor, managed by a smartphone application. We show: - - how to use a Cloud Twin to store information when a user arms (activates) the alarm from their smartphone - - how the Device can use the same Cloud Twin to store information about whether its door sensor has detected an open door and whether its siren is ringing in a 'current state' document - - how the Device can send requests to read the 'desired' documents in its Cloud Twin, compute new states for itself based on the information it receives and collects, and write new updated data to the 'current' Cloud Twin document. - - - - - - You have an account and are logged into [the Scaleway console](https://console.scaleway.com) - - You have installed [curl](https://curl.se/) and [`jq` (JSON parsing tool)](https://stedolan.github.io/jq/) on your local computer - - You have [created an IoT Hub](/managed-services/iot-hub/how-to/create-hub) - - You have [added a device](/managed-services/iot-hub/how-to/add-device) - - Your device allows insecure connections - - - - For more information, refer to [our documentation about Cloud Twins](/managed-services/iot-hub/reference-content/twins/). - - - - The Cloud Twins feature is currently in **beta** status. - - -## Understanding Cloud Twins - -### Internet Alarm Control Panel - -In the following example, you have an internet-enabled alarm control panel with a door sensor and a siren. - -Be aware that: - -- The siren will sound when the door is opened only if the system is armed. -- If the power is cut and restored, the system should be armed/disarmed as previously set. -- The app on your smartphone should be able to display if your door is open. If your alarm system is not reachable, the app should display the last known state and the last time this state was updated. - -The control panel is one device and uses the inband MQTT API to communicate with its twin. - -The smartphone application uses the REST API to access directly the control panel twin. - -### Cloud Twin Documents - -The twin represents the panel's current state and the desired states using two documents: - -- The `desired` document: represents the wanted state as controlled from the application to arm/disarm the alarm. It is written by the application and read by the device. - -**Example** - -```json -{ - "alarm_armed": true -} -``` - -- The `current` document: represents the actual state of the alarm panel including its door sensor and siren. It is written by the device and read by the application. - -**Example** - -```json -{ - "last_update": "