Prepare to use automatic communication

# Prepare to use automatic communication

LINE Things Developer Trial will be discontinued

We'd like to inform you that the LINE Things Developer Trial will be discontinued on March 31, 2024. As a result, you won't be able to call the API or connect to your device on and after April 1, 2024.

If you have any questions, please contact us via our inquiry form (opens new window).

We sincerely apologize for any inconvenience this may cause our customers. Thank you for your understanding.

To use automatic communication, you must first register a scenario set on the LINE Platform.

Automatic communication overview

The process of using automatic communication contains these steps:

  1. Register a scenario set on the LINE Platform using the Scenario management API for automatic communication.

  2. Once registered on the LINE Platform, your scenario set will be registered in LINE when an end user pairs the app with your device.

    If the scenario set registered in LINE uses automatic communication, paired devices will be continuously scanned.

  3. When LINE finds a device, it will automatically connect to that device and communicate with it as specified by the scenario set.

  4. The result of running each scenario will be sent to the Webhook URL of your Messaging API channel.

    For more details, see Receiving result events for a LINE Things scenario.

Here we will describe the scenarios and scenario sets that you should register with the LINE Platform.

# Scenarios

A scenario defines the process by which your device will communicate with LINE. Scenarios comprise the following two types of data:

  • Triggers
  • Actions

# Triggers

Any of the following conditions can be used as a trigger. Each of these triggers is the starting point for an action.

  • IMMEDIATE: Perform an action as soon as the device connects to LINE.

  • BLE_NOTIFICATION: Perform an action when receiving a notification with the specified GATT characteristic value.

    The notification payload will be sent to LINE along with the result of running the action.

# Actions

You may specify a series of the following actions, which will be executed in the order they are given.

  • GATT_READ: Read data from the specified GATT characteristic value.

    This data will be included in the scenario results sent to LINE.

  • GATT_WRITE: Write data to the specified GATT characteristic value.

  • SLEEP: Wait for a specified period of time.

# Sample scenarios

A scenario combines a trigger with a series of actions. You can create a number of different scenarios. Here are some examples to get you started:

  • After connecting to a device, immediately read and write data for a GATT characteristic.

    • Trigger: IMMEDIATE
    • Actions: GATT_READ, GATT_WRITE

  • Upon receiving a notification for a specified GATT characteristic, read and write data associated with it.

    • Trigger: BLE_NOTIFICATION
    • Actions: GATT_READ, GATT_WRITE

# Scenario sets

A scenario set combines multiple scenarios into a single data type. This allows you to implement complex communication logic.

You can configure a single scenario set for each product ID. Register scenario sets using the Scenario management API for automatic communication.

Note

You cannot change the content of a scenario set for individual users or devices.

# Configure and update your scenario set

Register a scenario set with your device's product information before end users pair your device with LINE.

The scenario set that you have registered with your product information will be also be registered in LINE when an end user pairs the app with your device.

Paired devices will be continuously scanned once a scenario set that uses automatic communication has been registered in LINE. When LINE finds a device, it automatically connects to that device and communicates with it as specified by the scenario set.

If you update a scenario set after an end user has paired your device with the LINE app, the user will only received that update if both of these conditions are met:

  • The end user has viewed the LINE app's Available devices screen.
  • At least 24 hours have passed since the last time the scenario set was registered in LINE.

# Disconnect from and reconnect to your device (autoClose, suppressionInterval)

Scenario sets contain two parameters related to disconnecting from and reconnecting to your device.

  • autoClose: If true, the device will automatically disconnect from LINE after any scenario in the scenario set finishes running. If false, the device will stay connected.
  • suppressionInterval: If autoClose = true, this specifies how long to wait after disconnecting from a device before attempting to reconnect to it again.

Pay careful attention to the values you set for these parameters. To learn more, see Important notes related to using automatic communication.

# Sample scenario sets

Here we will present some sample scenario sets. See also Scenario management API for automatic communication in the LINE Things API reference.

# Example #1

Wait for a notification with a GATT characteristic value.

  • Parameters: Stay connected to the device after running the scenario set.
  • Scenario 1
    • Trigger: BLE_NOTIFICATION
    • Actions: None. Use only the notification payload.
{
  "autoClose": false,
  "suppressionInterval": 0,
  "scenarios": [
    {
      "trigger": {
        "type": "BLE_NOTIFICATION",
        "serviceUuid": "91E4E176-D0B9-464D-9FE4-52EE3E9F1552",
        "characteristicUuid": "62FBD229-6EDD-4D1A-B554-5C4E1BB29169"
      },
      "actions": [
      ]
    }
  ]
}

# Example #2

Connect to your device, perform an action, then disconnect from the device.

  • Parameters: Automatically disconnect from the device after running the scenario set. Don't try to reconnect to the device for an hour after disconnecting from it.
  • Scenario 1
    • Trigger: IMMEDIATE
    • Actions: Perform the following series of steps.
      1. GATT_READ: Read data from the specified GATT characteristic value.
      2. SLEEP: Wait for 5 seconds.
      3. GATT_WRITE: Write "6AMAAA==" ([0xe8, 0x03, 0x00, 0x00], or 1000 as a 32-bit integer) to the specified GATT characteristic value.
{
  "autoClose": true, 
  "suppressionInterval": 3600000,  
  "scenarios": [
    {
      "trigger": {
        "type": "IMMEDIATE"        
      },                                                      
      "actions": [                                                  
        {
          "type": "GATT_READ",
          "serviceUuid": "7B3D6B30-8F8C-4549-A4F5-66B1F435FA8F",
          "characteristicUuid": "90EC53BA-1DBE-4AE2-B762-7C1FEA00F380"
        },
        {
          "type": "SLEEP",
          "sleepMillis": 5000
        },
        {
          "type": "GATT_WRITE",
          "serviceUuid": "7B3D6B30-8F8C-4549-A4F5-66B1F435FA8F",
          "characteristicUuid": "5486C1A0-0EC2-4073-9C38-755D21EFE090",
          "data": "6AMAAA=="
        }
      ]
    }
  ]
}