diff --git a/doc/content/integrations/cloud-integrations/blynk/_index.md b/doc/content/integrations/cloud-integrations/blynk/_index.md new file mode 100644 index 0000000000..1f132e835c --- /dev/null +++ b/doc/content/integrations/cloud-integrations/blynk/_index.md @@ -0,0 +1,15 @@ +--- +title: "Blynk" +description: "The integration guide with the Blynk IoT Platform" +weight: +distributions: ["Cloud", "Enterprise", "Sandbox"] +--- + +**[Blynk](https://blynk.io/)** is a powerful IoT platform that enables businesses to easily connect, monitor, and control devices. It includes secure cloud infrastructure and customizable mobile and web applications, all without the need for coding. + +## Key Benefits of Blynk Integration +- **Bidirectional Device Communication**: Leverage widgets on the [Console Dashboard](https://docs.blynk.io/en/blynk.console/devices/device-profile/dashboard) or [Mobile App](https://blynk.io/no-code-iot-mobile-apps) to both visualize data from devices and send commands to them seamlessly. +- **Enhanced Device Onboarding**: Streamline the onboarding process using LoRaWAN Device Identification QR Codes or [Blynk Static Tokens](https://docs.blynk.io/en/hardware-guides/the-things-stack/automated-device-onboarding#onboard-using-static-tokens) for automatic device registration in both Blynk and The Things Stack applications, via the Blynk App or Console. +- [**Device Lifecycle Management**](https://docs.blynk.io/en/blynk.console/templates/connection-lifecycle): Monitor device status and configurations with real-time in-app notifications and email alerts for efficient lifecycle management. + +**[The Things Stack integration documentation on Blynk](https://docs.blynk.io/en/hardware-guides/the-things-stack)** diff --git a/doc/content/integrations/cloud-integrations/blynk/api-key-permissions-settings.png b/doc/content/integrations/cloud-integrations/blynk/api-key-permissions-settings.png new file mode 100644 index 0000000000..ce5110ac51 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/api-key-permissions-settings.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/automated-device-onboarding.md b/doc/content/integrations/cloud-integrations/blynk/automated-device-onboarding.md new file mode 100644 index 0000000000..cc9a012c96 --- /dev/null +++ b/doc/content/integrations/cloud-integrations/blynk/automated-device-onboarding.md @@ -0,0 +1,103 @@ +--- +title: "Automated Device Onboarding" +description: "Onboard your device using Blynk App or Blynk Console." +weight: 2 +--- + +Once the integration with Blynk is configured, all devices in your The Things Stack application will be automatically imported into Blynk as soon as they transmit any data. + +Additionally, you can manually create devices in Blynk or use the Automated Device Onboarding feature, which offers an optimal user experience for connecting devices. +However, this requires you to configure first the Automated Device Onboarding settings in your Blynk integration. + +## Enabling Automated Device Onboarding +To enable the Automated Device Onboarding feature: +- Open the **Blynk Console** and navigate to **Developer Tools -> Integrations -> The Things Stack**. +- Select the application you wish to configure and access the advanced settings. +- Turn on the **Enable Automated Device Onboarding** switch. +- Specify the LoRaWAN version, Frequency plan, and Regional Parameter Version. If needed, check the Support class B and/or Support class C boxes. +- Enter the addresses of The Things Stack components, which you can find at the bottom of the **Overview** page on your The Things Stack dashboard. +Save the changes. + +{{< figure src="../integration-advanced-settings.png" alt="The advanced settings of the integration on Blynk" >}} + +Additionally, Blynk requires the following permissions: +- **View device keys in application** +- **Create devices in application** +- **Edit device keys in application** + +To grant these permissions, either generate a new API key or edit the existing one that you have been using with Blynk. + +{{< figure src="../api-key-permissions-settings.png" alt="The API key permission settings on The Things Stack" >}} + +Now that the automated device onboarding is enabled and configured, you can onboard your first device. + +{{< note "Sometimes, a device requires a reboot to initiate the onboarding flow. Make sure to restart the device if it doesn't automatically start the onboarding process after following the setup steps. This can help ensure the device properly connects and begins the necessary communication with Blynk and The Things Stack." />}} + +## Manually configure the tokens +This is the easiest, but least scalable way to onboard the device: + +Begin by creating the device from the template on the Blynk Console: **Go to Devices -> + New Device -> From template**, select the template, and assign a meaningful name to the device. Then click **Create**. + +Next, to provision the device on The Things Stack, open **Info & Metadata** and fill out the three metadata fields: *Device EUI*, *App EUI* and *Application Key*. + +{{< figure src="../device-info.png" alt="The device information page on Blynk" >}} + +Once these three metadata fields are specified, Blynk will automatically create the device in The Things Stack application. + +## Onboard using Static Tokens +The preferred method for device provisioning is using [Blynk Static Tokens](https://docs.blynk.io/en/hardware-guides/the-things-stack/automated-device-onboarding#onboard-using-static-tokens). +Here’s how to do it: + +1. Create a CSV file listing the Device EUI, App EUI, and Application Key for each device. +2. Use this CSV file to create static tokens: open the **Blynk Console -> Developer Zone -> Static Tokens -> Generate Static Tokens -> Create From File**. Then select the device template and upload the file. +3. This process will generate a unique QR code for each device. +4. These QR codes can be scanned via the Blynk Mobile application or on the Blynk Console by the end customer. +5. Once a QR code is scanned and the device is created, it will be automatically created in The Things Stack application. + +Here is an example of a CSV file that could be used for creating static tokens: +```csv +Device EUI,App EUI,Application Key +0018B20000000101,70B3D57ED0000010,2B7E151628AED2A6ABF7158809CF4F3C +0018B20000000102,70B3D57ED0000011,3B7E151628AED2A6ABF7158809CF4F3D +0018B20000000103,70B3D57ED0000012,4B7E151628AED2A6ABF7158809CF4F3E +``` + +## Onboard using LoRaWAN QR Code +Blynk also supports [LoRaWAN® Device Identification QR Codes for Automated Onboarding](https://lora-alliance.org/wp-content/uploads/2020/11/TR005_LoRaWAN_Device_Identification_QR_Codes.pdf). +To use them, follow these steps: +1. First, create the static tokens as described in the [Onboard using Static Tokens](#onboard-using-static-tokens) section. +2. Construct the QR code in the LoRaWAN format using the Profile ID specified in the advanced settings of The Things Stack integration application card on Blynk. + +Additionally, you can change the Profile ID used in the QR code body. +To do so, open the application settings on Blynk, locate to the advanced settings and edit the Profile ID field. + +{{< figure src="../profile-id-field.png" alt="The Profile ID field" >}} + +For LoRaWAN QR codes, Blynk requires the following: +- The code must start with `LW:D0`. +- It must contain the App EUI, Device EUI, and the Profile ID. +- Optionally, it may contain a checksum. +- Any other parts of the QR code are ignored. + +Here is an example of how the QR code data should be structured: +``` +LW:D0:::: +``` +Here is an example of the QR code body with App EUI = `70B3D57ED0000010`, Device EUI = `0018B20000000101` and Profile ID = `000AF8BE`: +``` +LW:D0:70B3D57ED0000010:0018B20000000101:000AF8BE +``` +Generate the QR code by inputting this content into any QR code generator tool, such as [QR Code Generator](https://www.urldecoder.org/). +Then this QR code can be scanned by the end customer in the Blynk Mobile application or on the Blynk Console. +Once the device is created, it will be automatically added in The Things Stack application. + +## Re-provisioning +If you've changed your hardware or updated any LoRaWAN connection parameters (such as DevEUI, AppEUI/JoinEUI, or Application Key), you will need to create a new device in The Things Stack. + +To retain the historical data, settings, or any other details for the old device in Blynk, follow these steps: + +1. Navigate to the **Device Information & Metadata** tab for the old device in Blynk. +2. Update the **TheThingsStack Device ID** metafield. +3. Optionally, you can also update other related metafields like **DevEUI**, **JoinEUI**, and **Application Key**. + +{{< warning "If the new device goes online in The Things Stack before updating the metafields in Blynk, it may be automatically imported into Blynk. In case of a **TheThingsStack Device ID** collision (where two devices have the same ID), Blynk will randomly select one device. To resolve this, simply delete the automatically imported device to ensure the correct one is used." />}} diff --git a/doc/content/integrations/cloud-integrations/blynk/connected-application.png b/doc/content/integrations/cloud-integrations/blynk/connected-application.png new file mode 100644 index 0000000000..a5180cbf26 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/connected-application.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/create-integration.png b/doc/content/integrations/cloud-integrations/blynk/create-integration.png new file mode 100644 index 0000000000..f5355173d3 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/create-integration.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/create-tempalte.png b/doc/content/integrations/cloud-integrations/blynk/create-tempalte.png new file mode 100644 index 0000000000..4903de6990 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/create-tempalte.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/device-info.png b/doc/content/integrations/cloud-integrations/blynk/device-info.png new file mode 100644 index 0000000000..750f4b121c Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/device-info.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/device_grouping.md b/doc/content/integrations/cloud-integrations/blynk/device_grouping.md new file mode 100644 index 0000000000..83c5b6733f --- /dev/null +++ b/doc/content/integrations/cloud-integrations/blynk/device_grouping.md @@ -0,0 +1,28 @@ +--- +title: "Device Grouping" +description: "Group your devices correctly to ensure seamless integration and effective device management." +weight: 3 +--- + +To ensure seamless integration and effective device management, follow these principles: + +## Use Separate Applications and Templates for Different Device Types +* **Why:** Each device type typically has unique data structures and behaviors. Using separate templates ensures that Blynk can correctly process and display device-specific telemetry data. +* **How:** Create a dedicated application in The Things Stack for each Blynk template. This alignment allows you to configure a payload formatter at the application level, ensuring consistent data formatting across devices within the same group. + +## Group Devices of the Same Type in the Same Application and Template +* **Why:** Grouping devices of the same type within a single application simplifies management and avoids issues caused by mixing different device types. +* **How:** Use a common payload formatter for all devices within an application. This reduces the risk of errors and ensures consistent behavior across similar devices. + +## Benefits of This Approach +**Consistency in Data Processing** \ +Configuring a shared payload formatter at the application level ensures uniformity, preventing potential bugs caused by incompatible data formats. + +**Simplified Maintenance** \ +Managing devices of the same type in a single application and template makes it easier to update configurations, troubleshoot issues, and scale the solution. + +**Accurate Template Association** \ +By separating applications for different templates, Blynk can correctly associate devices with their respective templates during the import process. + +{{< warning "If multiple Blynk templates are connected to a single The Things Stack application, Device Provisioning from The Things Stack will be disabled for all associated templates. This limitation can lead to challenges in managing device lifecycles and should be avoided." />}} +{{< figure src="../incorrect-device-grouping.png" alt="Incorrect Device Grouping warning" >}} diff --git a/doc/content/integrations/cloud-integrations/blynk/getting-started.md b/doc/content/integrations/cloud-integrations/blynk/getting-started.md new file mode 100644 index 0000000000..eba9913c81 --- /dev/null +++ b/doc/content/integrations/cloud-integrations/blynk/getting-started.md @@ -0,0 +1,92 @@ +--- +title: "Gettings started" +description: "Connect the application to the Blynk, send downlink and uplink." +weight: 1 +--- + +The easiest way to set up a device on Blynk is to use one already connected to The Things Stack. + +## Prerequirements +1. An application on The Things Stack server +2. A [Blynk](https://blynk.io/) account +3. A connected LoRaWAN device to The Things Stack server + +## Connecting your The Things Stack application to Blynk +Start by [creating a Blynk template for your device](https://docs.blynk.io/en/getting-started/template-quick-setup). +Navigate to **Blynk Console -> Developer Zone -> My Template -> + New Template**. +Provide a meaningful name, optionally select your hardware, and add a description. +Click **Done** to complete the setup. + +{{< figure src="../create-tempalte.png" alt="Create the Template on Blynk" >}} + +Now that you have a template, proceed with connecting it to The Things Stack application. +In the **Blynk Console**, go to **Developer Zone -> Integrations -> The Things Stack**. +Click the **+ Add** button and select the template you created earlier. + +{{< figure src="../create-integration.png" alt="Create the Integration on Blynk" >}} + +Next, navigate to your **The Things Stack Application -> Integrations -> MQTT**. +Copy the **Public TLS Address** and paste it into the **MQTT Server** field on Blynk. +Then, copy the **Username** from your The Things Stack Application and paste it into the **Username** field on Blynk. +Finally, click **Generate API Key** on The Things Stack, copy the generated key, and paste it into the **Password** field in Blynk. + +{{< figure src="../mqtt-integration-page.png" alt="MQTT Integration Page on The Things Stack" >}} + +Click the **Connect** button at the bottom of the application card on Blynk. You will see the integration status change to *Connected*. + +{{< figure src="../connected-application.png" alt="Connected Application on Blynk" >}} + +Once this is done, Blynk will automatically create the device connected to The Things Stack as soon as it sends any data. This device will then be available on the [Devices page](https://docs.blynk.io/en/blynk.console/devices). + +## Sending uplink and downlink messages +Once your first device is connected to Blynk, it's time to transfer some data! Start by configuring the Payload formatter on The Things Stack. + +### Uplink +For uplinks, Blynk requires the data to be in key-value pair format, where the key is either the datastream name or pin (such as v1 or a10) and the value is the datastream value. +The value type must match the datastream value type! Also, prefer using only Virtual Pin, Enum and Location datastream types. Here is an example of the decoded uplink: + +```json +{ + "temperature": 24.1, + "humidity": 54, + "location": [-73.935242, 40.730610] +} +``` +In this example, Blynk will set the datastream with the name *temperature* to the value *24.1* and the datastream with the name *humidity* to the value *54* and datastream with name *location* to the longitude *-73.935242* and latitude *40.730610* (longitude goes first). + +{{< note "Since Blynk does not support a boolean datastream value type, you must use either the Integer or Double datastream value type. The value `true` will be represented as `1`, and `false` as `0`." />}} + +To create or edit datastreams, go to **Blynk Console -> Developer Zone -> My Templates -> select your template -> Datastreams**. +Click the **Edit** button in the top right corner to make changes. +The datastreams configuration for this example may look like this: + +{{< figure src="../template-datastreams.png" alt="Template Datastream Settings on Blynk" >}} + +{{< note "Each time Blynk receives an update from the device, it will trigger the Online lifecycle event. Therefore, it is recommended [to configure a meaningful wait time](https://docs.blynk.io/en/blynk.console/templates/connection-lifecycle) to prevent your device from being stuck in the offline state." />}} + +### Downlink +For each datastream update via the web dashboard, mobile application, automation, etc., Blynk will send a separate downlink to the device. +This will trigger the `encodeDownlink` function of your Downlink Payload formatter. +Here is an example of the downlink that Blynk will send to the device, indicating that the datastream with the name *speed* (pin v2) has been updated to the value *3*: + +```json +{ + "name": "speed", + "pin": "v2", + "ts": 1721202415068, + "value": 3 +} +``` +The `ts` field represents the timestamp in Unix milliseconds format when the value was actually updated. + +## Visualizing data and sending commands to the device +After configuring the Payload Formatter on The Things Stack and setting up Datastreams in your Blynk template, you can proceed to visualize data and send commands to your device. +You can do this either from the device dashboard on the Blynk Console or through the Blynk IoT Smartphone App. + +For guidance on configuring widgets for the Device Dashboard and Mobile App, refer to the Blynk documentation: +- [Web Dashboard](https://docs.blynk.io/en/blynk.console/templates/dashboard) +- [Mobile Dashboard](https://docs.blynk.io/en/blynk.apps/constructor) + +Additionally, take advantage of other powerful Blynk features, such as [Automations](https://docs.blynk.io/en/concepts/automations), [WebHooks](https://docs.blynk.io/en/blynk.console/settings/developers/webhooks), and the [Device HTTPS API](https://docs.blynk.io/en/blynk.cloud/device-https-api), to build more advanced workflows. + +Also, check the [System DataStreams](https://docs.blynk.io/en/hardware-guides/the-things-stack/system-datastreams) section to grab more info from your device. diff --git a/doc/content/integrations/cloud-integrations/blynk/incorrect-device-grouping.png b/doc/content/integrations/cloud-integrations/blynk/incorrect-device-grouping.png new file mode 100644 index 0000000000..dd78ef2369 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/incorrect-device-grouping.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/integration-advanced-settings.png b/doc/content/integrations/cloud-integrations/blynk/integration-advanced-settings.png new file mode 100644 index 0000000000..4608210cbb Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/integration-advanced-settings.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/mqtt-integration-page.png b/doc/content/integrations/cloud-integrations/blynk/mqtt-integration-page.png new file mode 100644 index 0000000000..b0935df2d2 Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/mqtt-integration-page.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/profile-id-field.png b/doc/content/integrations/cloud-integrations/blynk/profile-id-field.png new file mode 100644 index 0000000000..9a2e32d82d Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/profile-id-field.png differ diff --git a/doc/content/integrations/cloud-integrations/blynk/template-datastreams.png b/doc/content/integrations/cloud-integrations/blynk/template-datastreams.png new file mode 100644 index 0000000000..3f1426dc0a Binary files /dev/null and b/doc/content/integrations/cloud-integrations/blynk/template-datastreams.png differ