IOTOWN Manual

Home How to Use Callback
Introduction
MQTT
Device Boot Device Data Device Ack Gateway Boot Gateway Keepalive Note
HTTP
Device Data Gateway Keepalive Device Ack Note

How to Use Callback

Introduction

Callback은 IOTOWN으로 전송되는 단말 장치의 데이터를 서드파티 시스템으로 전달하는 기능을 말합니다. IOTOWN은 MQTT와 HTTP 프로토콜을 이용하여 callback을 수행합니다.

MQTT

IOTOWN으로 전송되는 단말 장치의 데이터를 서드파티 MQTT 클라이언트에서 수신하고 싶은 경우 서드파티 클라이언트에서 메시지 종류별 topics를 구독하면 됩니다. 해당 topics로 전송되는 데이터는 JSON 포맷입니다.

메시지 종류별 MQTT Topics
메시지 종류 Topic name
Device Boot iotown/rx/{Group ID}/device/{Device ID}/boot
Device Data iotown/rx/{Group ID}/device/{Device ID}/data
Device Ack iotown/rx/{Group ID}/device/{Device ID}/ack
Gateway Boot iotown/rx/{Group ID}/gateway/{Gateway ID}/boot
Gateway Keepalive iotown/rx/{Group ID}/gateway/{Gateway ID}/keepalive
  1. Group ID 확인은 사용자 정보에서 가능합니다.
  2. MQTT 접속시 ID는 사용자 계정, password는 open API token을 사용합니다.
  3. 구독시 Device ID와 Gateway ID 부분은 single level wildcard +를 사용하여야 합니다. multi-level wildcards로 구독하는 경우 메시지를 전달받지 못합니다.
    • Group ID가 G0011223344556677이고, Device Data 메시지를 구독하고자 하는 경우, topic name: iotown/rx/G0011223344556677/device/+/data
  4. 위 topics는 사용자에게 read-only 권한으로 구독 가능합니다. 위 topics로 사용자가 publish를 하는 경우, IOTOWN에 의해 무시됩니다.
  5. Node.js를 이용한 MQTT 클라이언트 예제

Device Boot

단말 장치가 IOTOWN과 통신을 시작한 경우 발행되는 메시지입니다.

{
  "device": {
    "id": "Device ID",
    "type": "Device Type",
    "desc": "Device Description"
            or
            { "key": "value", ... },              // 장치 desc이 "key": "value" pairs로 구성된 경우
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z"
  },
  "timestamp":"2023-06-02T01:37:28.03059Z"
}

Device Data

IOTOWN이 단말 장치로부터 데이터를 받고 성공적으로 DB에 저장을 완료한 경우 발행되는 메시지입니다.

{
  "device": {
    "id": "Device ID",
    "type": "Device Type",
    "desc": "Device Description"
            or
            { "key": "value", ... },              // 장치 desc이 "key": "value" pairs로 구성된 경우
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z"
  },
  "gateway": {
    "id": "Gateway ID",
    "type": "Gateway Type",
    "desc": "Gateway Description"
            or
            { "key": "value", ... },              // 게이트웨이 desc이 "key": "value" pairs로 구성된 경우
    "eui": "Gateway EUI",
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z",
    "recent_act": "2023-06-02T00:00:00.000000Z",
    "keepalive": "2023-06-02T00:00:00.000000Z",
    "latitude": 36.49899,
    "longitude": 127.32881,
    "altitude": 87
  },
  "data": {
    "temperature": 25,
    "humid": 56,
    "dust": 67
  },
  "timestamp":"2023-06-02T01:37:28.03059Z"
}

Device Ack

단말 장치가 IOTOWN이 보낸 명령을 정상적으로 수신한 경우 발행되는 메시지 입니다.

{
  "device": {
    "id": "Device ID",
    "type": "Device Type",
    "desc": "Device Description"
            or
            { "key": "value", ... },              // 장치 desc이 "key": "value" pairs로 구성된 경우
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z"
  },
  "fCnt": 10,                                     //optional for LoRaWAN nodes
  "timestamp":"2023-06-02T01:37:28.03059Z"
}

Gateway Boot

게이트웨이가 IOTOWN과 통신을 시작한 경우 발행되는 메시지 입니다.

게이트웨이에 따라 지원하지 않을 수 있습니다.

{
  "gateway": {
    "id": "Gateway ID",
    "type": "Gateway Type",
    "desc": "Gateway Description"
            or
            { "key": "value", ... },              // 게이트웨이 desc이 "key": "value" pairs로 구성된 경우
    "eui": "Gateway EUI",
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z",
    "recent_act": "2023-06-02T00:00:00.000000Z",
    "keepalive": "2023-06-02T00:00:00.000000Z",
    "latitude": 36.49899,
    "longitude": 127.32881,
    "altitude": 87
  },
  "timestamp":"2023-06-02T01:37:28.03059Z"
}

Gateway Keepalive

IOTOWN이 게이트웨이가 보낸 생존신호를 수신한 경우 발행되는 메시지 입니다.

{
  "gateway": {
    "id": "Gateway ID",
    "type": "Gateway Type",
    "desc": "Gateway Description"
            or
            { "key": "value", ... },
    "eui": "Gateway EUI",
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z",
    "recent_act": "2023-06-02T00:00:00.000000Z",
    "keepalive": "2023-06-02T00:00:00.000000Z",
    "latitude": 36.49899,
    "longitude": 127.32881,
    "altitude": 87
  },
  "data": {
    "lati": 36.49899,                             // decimal degree (optional)
    "long": 127.32881,                            // decimal degree (optional)
    "alti": 87,                                   // unit of meter (optional)
    "systime": "2021-08-12T02:06:12.000Z",        // gateway's system time (optional)
    "ip": "192.168.254.180",                      // local IP (optional)
    "power": "External",                          // power status (optional),
    "temperature": 54.81,                         // unit of celsius degree (optional)
  },
  "timestamp":"2023-06-02T01:37:28.03059Z"
}

Note

  1. IOTOWN은 MQTT와 MQTTS를 모두 지원합니다. MQTT를 사용하는 경우 로그인 정보 및 메시지가 평문으로 노출됩니다. 가급적 MQTTS 사용을 추천합니다.
  2. 설치형 IOTOWN-Biz 사용시 사설망에서의 사용, 또는 도메인 네임을 사용하지 않는 등 이유로 self-signed 인증서를 사용하는 경우가 있습니다. 그런 경우, MQTT 클라이언트 접속시 인증서 검증을 수행하지 않도록 하는 등 별도의 조치를 취하여야 접속이 됩니다.

HTTP

IOTOWN으로 전송되는 단말 장치의 데이터를 서드파티 HTTP 서버에서 실시간으로 수신하고 싶은 경우 서드파티 서버의 URL을 콜백으로 등록하면 됩니다. 서드파티 서버에서는 해당 URL로 HTTP(s) POST request를 수신할 수 있는 HTTP(s) 서버가 구동되고 있어야 합니다. POST request를 통해 전송되는 데이터는 JSON 포맷 (application/json) 입니다.

  1. 서드파티 서버에 HTTP POST URL을 생성합니다.
  2. Open API를 이용하여 IOTOWN 서버에 POST URL을 등록할 수 있습니다. (Open API [PUT] callback 참고)
  3. 데이터가 들어오거나, 게이트웨이 및 단말 장치가 시작되었을 경우 서드파티 서버에서 POST로 다음과 같이 수신된 데이터를 확인할 수 있습니다.
type 값의 의미
type Description
"0" Gateway boot up (게이트웨이에 따라 지원되지 않을 수 있습니다)
"1" Node boot up
"2" Data from node
"3" Gateway Keepalive
"4" Ack from node

Data

Data는 단말 장치에서 보낸 데이터를 의미합니다. 단말 장치에서 보낸 데이터가 IOTOWN에 수신될 때마다 콜백됩니다.

{
  "type": "2",
  "nid":"node's ID",                              // 2023-06-02 이후로 deprecated
  "device": {                                     // 2023-06-02 이후부터 추가됨
    "id": "Device ID",
    "type": "Device Type",
    "desc": "Device Description"
            or
            { "key": "value", ... },              // 장치 desc이 "key": "value" pairs로 구성된 경우
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z"
  },
  "gid":"node's gateway ID",                      // 2023-06-02 이후로 deprecated
  "gateway": {                                    // 2023-06-02 이후부터 추가됨
    "id": "Gateway ID",
    "type": "Gateway Type",
    "desc": "Gateway Description"
            or
            { "key": "value", ... },              // 게이트웨이 desc이 "key": "value" pairs로 구성된 경우
    "eui": "Gateway EUI",
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z",
    "recent_act": "2023-06-02T00:00:00.000000Z",
    "keepalive": "2023-06-02T00:00:00.000000Z",
    "latitude": 36.49899,
    "longitude": 127.32881,
    "altitude": 87
  },
  "data": {
    "temperature": 25,
    "humid": 56,
    "dust": 67
  },
  "timestamp":"2019-04-10T01:37:28.03059Z"        //2019-04-10 이후부터 추가됨
}

Gateway Keepalive

Gateway keepalive는 게이트웨이에서 IOTOWN에 보내는 생존 신호입니다.

{
  "type": "3",
  "gid": "gateway's ID",                          // 2023-06-02 이후로 deprecated
  "gateway": {                                    // 2023-06-02 이후부터 추가됨
    "id": "Gateway ID",
    "type": "Gateway Type",
    "desc": "Gateway Description"
            or
            { "key": "value", ... },
    "eui": "Gateway EUI",
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z",
    "recent_act": "2023-06-02T00:00:00.000000Z",
    "keepalive": "2023-06-02T00:00:00.000000Z",
    "latitude": 36.49899,
    "longitude": 127.32881,
    "altitude": 87
  },
  "data": {
    "lati": 36.49899,                             // decimal degree (optional)
    "long": 127.32881,                            // decimal degree (optional)
    "alti": 87,                                   // unit of meter (optional)
    "systime": "2021-08-12T02:06:12.000Z",        // gateway's system time (optional)
    "ip": "192.168.254.180",                      // local IP (optional)
    "power": "External",                          // power status (optional),
    "temperature": 54.81,                         // unit of celsius degree (optional)
  },
  "timestamp": "2021-08-12T02:06:12.379Z"
}

ACK

ACK는 IOTOWN에서 단말 장치로 보낸 명령에 대해 단말 장치에서 이를 잘 수신했다는 신호를 의미합니다. 이 신호가 IOTOWN에 수신될 때마다 콜백됩니다.

{
  "type": "4",
  "nid":"node's ID",                              // 2023/06/02 이후로 deprecated
  "device": {                                     // 2023/06/02 이후부터 추가됨
    "id": "Device ID",
    "type": "Device Type",
    "desc": "Device Description"
            or
            { "key": "value", ... },              // 장치 desc이 "key": "value" pairs로 구성된 경우
    "created_at": "2023-06-02T00:00:00.000000Z",
    "bootup_time": "2023-06-02T00:00:00.000000Z"
  },
  "fCnt": 10,                                     //optional for LoRaWAN nodes
  "timestamp":"2019-04-10T01:37:22.03049Z"
}

Note

  1. HTTPS를 사용하지 않는 경우 POST request가 평문으로 노출될 수 있습니다. 가급적 HTTPS 사용을 추천합니다.
  2. IOTOWN은 서드파티 서버와 HTTPS로 통신시 별도의 인증서 검증을 수행하지 않습니다.