LINE Things automatic communication

Good day to all once more, this is Ukrit again with an exciting new addition to LINE Things.

The long-awaited “Automatic Communication” functionality has finally been released. This new feature will allow Bluetooth LE communication even if the LINE Things app is not launched. LINE Things-compatible IoT devices will be able to work closely with a LINE bot in an instant with this feature.

LINE Things is a platform that allows users to pair and operate Bluetooth LE-compatible IoT devices through LINE app. The platform is open to the public to use for any LINE bot developers for free through our Developer Trial.

As mentioned during LINE Developer Day 2018, the release for “Automatic Communication” on LINE Things will follow the initial release of LINE Things. I am excited to let you know that you can now enjoy the full experience on LINE v9.6.0 onwards.

The ability to communicate between LINE Things-compatible devices and LINE apps through LIFF SDK JavaScript API has previously been released through the Developer Trial (See Trying out LINE’s IoT Platform through LINE Things Developer Trial). From now on, the Developer Trial will include the new automatic communication feature, without any restrictions! For more information, please refer to LINE Things Documentation.

Since the release of LINE Things, there have been multiple hands-on activities, as well as hackathons to introduce the platform to aspiring developers.

We’ve had many requests and feedback for automatic communication within the platform, so I can’t wait to see what you all will be able to create with the release of this feature.

Overview of LINE Things Automatic Communication

Previously, the only way to interact with a LINE Things-compatible device is through a LIFF app. However, by using automatic communication, you no longer need an application to interact with the device. Which means that you can communicate with the device and send contents over to LINE Bot with seamless ease via Messaging API.

The simple example above is created using Puck.js. It is linked with LINE Things via automatic communication. It works as a simple call button. While simple, you can see how small, battery-powered devices can work with a LINE Bot.

An overview of the automatic communication is illustrated above. Automatic communication can connect the device with a LINE Bot in the following flow:

  1. Creators of LINE Things-compatible devices register communication procedures (scenarios) for each product through an API.
  2. Once paired to a LINE Things-compatible device, the LINE app communicates with the device in accordance to the pre-registered scenario.
  3. Once the scenario has been executed, the LINE app sends the execution result through a webhook to the channel to which the device is linked, via the Messaging API.
  4. Based on the scenario execution results, the channel LINE Bot can then freely reply to the user.

Basically, if automatic communication is implemented, a device can notify a user with a message via LINE Bot. Usages of these can be when something triggers a sensor, a button is being pressed, or something that regularly feeds you information.

Implementing automatic communication to LINE Things Starter

Let’s begin with LINE Things Starter and go further by adding in automatic communication.

You can easily get started with LINE Things starter with an ESP32-DevKitCAdafruit Feather nRF52 Bluefruit LE, or Obniz. The rest of this article will explore the the implementation of LINE Things products with a LINE bot. If you have never tried LINE Things Starter before, I highly encourage you to give it a go at LINE Things Developer Trial to get yourself familiarised with the platform.

LINE Things Starter is a simple device with only one button and one LED. We will be creating something similar to the Puck.js example above, such that when a button is pressed, we will get a return response from the LINE Bot.

Creating a scenario

In order for you to have an automatic communication action perform, you first need to register and set a scenario to the LINE Things server prior to usage. One scenario set can be set per product, and multiple scenarios can be configured for each set. For more information, see the LINE Things document, Prepare to use automatic communication.

Similar to the LIFF app, when the button is pressed on the Starter device, Notify sends a value to the GATT characteristic indicating the state of the button. Since I would like an event to be triggered when the button is pressed, I will use BLE_NOTIFICATION as the type of the trigger for the execution of the scenario.

Since BLE_NOTIFICATION is a GATT characteristic, the serviceUuid and characteristicUuid of the BLE_NOTIFICATION characteristic must be specified. The serviceUuid is the generated UUID in the response body when calling the API to create a LINE Things product. For this example, the button notification characteristic UUID is 62FBD229-6EDD-4D1A-B554-5C4E1BB29169. In the following configuration, once connected to the device, LINE app will wait for the specified Notify trigger without forcing a disconnect to the device.

{
  "autoClose": false,
  "suppressionInterval": 0,
  "scenarios": [
    {
      "trigger": {
        "type": "BLE_NOTIFICATION",
        "serviceUuid": "<YOUR SERVICE UUID>",
        "characteristicUuid": "62FBD229-6EDD-4D1A-B554-5C4E1BB29169"
      },
      "actions": [
      ]
    }
  ]
}

We will register this scenario set using the Scenario management API for automatic communication. I will be using the curl command here, but you are free to use any tool of your liking.

Don’t forget to replace <YOUR PRODUCT ID> with the generated product serviceUuid. If you are unsure what your product ID is, you can visit Acquiring trial product information. Since an access token is necessary for the channel, please obtain the token from LINE Developers site.

$ curl -v -X PUT https://api.line.me/things/v1/products/<YOUR PRODUCT ID>/scenario-set \
-H "Authorization: Bearer {channel access token}" \
-H 'Content-Type:application/json' \
-d '
{
  "autoClose": false,
 	"suppressionInterval": 0,
  "scenarios": [{
    "trigger": {	
      "type": "BLE_NOTIFICATION",
      "serviceUuid": "<YOUR SERVICE UUID>",
      "characteristicUuid": "62FBD229-6EDD-4D1A-B554-5C4E1BB29169"
 		},
 		"actions": []
 	}]
}

We now have a scenario set registered on the LINE Things server and distributed to the LINE app. However, if your device has previously been linked prior to the registration of the scenario set, you may need to initiate a device link again at the device link screen in the LINE app (or wait up to 24 hours for the system to automatically update). Now let’s link the device from the Device Link Screen. (This link is accessible only in the regions LINE Things is available, which are Japan, Indonesia, Taiwan and Thailand at the time of posting.) After linking with the device, if the device is powered on, it will be immediately connected.

Webhook events and response

Up to this point, your scenario execution results are ready to be sent via the Messaging API. In order to receive the results, you would need to receive the webhook to the channel. In order to do this, you would need to prepare and publish an HTTPS enabled server, as with all LINE bot development. For the time being, we will be making a simple LINE bot using ngrok. (ngrok is a proxy software. It might be blocked in some network environment. Please use it at your own risk.)

For additional details on Webhook events, please refer to Receiving LINE Things scenario execution events. The trigger type BLE_NOTIFICATION, will send the notified data in bleNotificationPayload as a BASE64 encoded format such as AAAAAA== as an example. For GATT_READ, if an action is specified, the result will be in actionResults in the same BASE64 format.

For now, I have prepared a Python sample code to be sent back by the LINE bot as a response to the LINE Things Webhook event. Please make sure to run this using Python 3. As of April 2019, the LINE Bot SDK is yet to be compatible with LINE Things Webhook events, so please keep an eye out for when we update the SDKs accordingly! (We will add support version to LINE Things Starter’s repository as soon as SDK is supported.)

#-*- coding: utf-8 -*-

from flask import Flask, request, abort
import json
import base64

from linebot import (
    LineBotApi, WebhookParser
)
from linebot.exceptions import (
    InvalidSignatureError
)
from linebot.models import (
    MessageEvent, TextMessage, TextSendMessage,
)

app = Flask(__name__)

ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
CHANNEL_SECRET = "<YOUR_CHANNEL_SECRET>"
line_bot_api = LineBotApi(ACCESS_TOKEN)
parser = WebhookParser(CHANNEL_SECRET)

@app.route("/")
def healthcheck():
    return 'OK'

@app.route("/callback", methods=['POST'])
def callback():
    signature = request.headers['X-Line-Signature']

    # get request body as text
    body = request.get_data(as_text=True)
    app.logger.info("Request body: " + body)

    try:
        # Python SDK doesn't support LINE Things event
        # => Unknown event type. type=things
        for event in parser.parse(body, signature):
            handle_message(event)

        # Parse JSON without SDK for LINE Things event
        events = json.loads(body)
        for event in events["events"]:
            if "things" in event:
                handle_things_event(event)
    except InvalidSignatureError:
        print("Invalid signature. Please check your channel access token/channel secret.")
        abort(400)

    return 'OK'

def handle_things_event(event):
    if event["things"]["type"] != "scenarioResult":
        return
    if event["things"]["result"]["resultCode"] != "success":
        app.logger.warn("Error result: %s", event)
        return

    button_state = int.from_bytes(base64.b64decode(event["things"]["result"]["bleNotificationPayload"]), 'little')
    if button_state > 0:
        line_bot_api.reply_message(event["replyToken"], TextSendMessage(text="ボタンが押されたよ"))

def handle_message(event):
    if event.type == "message" and event.message.type == "text":
        line_bot_api.reply_message(event.reply_token, TextSendMessage(text=event.message.text))

if __name__ == "__main__":
    app.run("0.0.0.0", debug=True)

Set your credentials from the LINE Developers site in the following section.

ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"
CHANNEL_SECRET = "<YOUR_CHANNEL_SECRET>"

Since we are using both Flask and LINE Bot SDK, make sure to install the two before using them.

$ pip3 install flask line-bot-sdk

Start the server to receive the LINE bot’s webhook on the local host as follows By default Flask runs on port 5000:

$ python3 app.py

A detailed guide to getting ngrok up and running will be ommitted here. However, you can proxy the local server as follows:

$ ngrok http 5000

At this point, the URL will be displayed as “Forwarding” in the ngrok display window. Copy this URL and set it as the Webhook URL on the LINE Developers site. Don’t forget to add the /callback route and enable Webhook events.

Forwarding                    http://c2761e26.ngrok.io -> http://localhost:5000
Forwarding                    https://c2761e26.ngrok.io -> http://localhost:5000

After the webhook URL is set, you can test to confirm that everything is working properly by pressing on the button of the LINE Things Starter device. If the webhook has been received, you should receive a message that the button has been pressed.

For Android users, if a connection with a device has been established, the following notification will be displayed. (iOS users will not receive this notification.)

Conclusion

LINE Things Automatic Communication has enhanced the connectivity of IoT devices even further by allowing them to connect to a LINE bot. In the past, Wi-Fi and LTE modules were the only solution to provide a similar experience. But due to high costs as well as high power consumption for the two has made it hard for makers to commit to outdoor installations. With LINE Things, it is now possible to use the inexpensive Bluetooth LE as a solution to these problems.

Please note that while using automatic communication, there are a few fine details to be aware of. For more details, please refer to the following Important notes related to using automatic communication .

Throughout the year, the LINE Things team will be holding multiple hands-on events and hackathons to introduce and share with you some exciting ideas and what you could do with the platform, with a focus on the automatic communication feature. We will be providing a LINE Things development board dedicated to LINE Things, for participants to reduce the amount of development time as well as providing an easier level of entry for those who have little to no experience in hardware development. Please keep an eye out in your local LINE Developers community to see when the events will be happening!

Also, the LINE Things team welcome all comments and suggestions to our platform. For those who what to go beyond the limitations of the Developer Trial and would like to commercialise the product, or if you require any of the following

  • Use your own GATT Service UUID during device search/scan to obtain the PSDI
  • Have the device display as a compatible device without adding it as a friend first
  • Go beyond the limited number of device linkages

Please don’t hesitate to contact us to discuss the details of your product and commercialisation through our LINE Things Partnership Form.

We thank you for your continued support and can’t wait to see with what you can make with LINE’s IoT Platform, LINE Things.

Related Post