MQTT

Nubison IoT MQTT 표준규약입니다.

Nubison IoT 플랫폼에 MQTT 프로토콜을 이용하는 디바이스를 연결하기 위한 가이드입니다.

아래 과정을 진행하기 전에, 시작하기에 적힌 과정들이 반드시 선행되어야 합니다.

서버 연결

Nubison IoT 플랫폼의 MQTT 메세지 브로커에 연결하기 위한 정보입니다.

• 서버 URL: 연동 진행시 안내

• Username: 인증 키 발급 시 만든 인증 키의 클라이언트 ID

• Password: 인증 키 발급 시 만든 인증 키의 클라이언트 시크릿

토픽 구독

디바이스가 MQTT/S 연결에 성공하면, 다음 토픽을 구독하여 Nubison IoT 플랫폼 서버와 통신을 주고받을 수 있게 합니다.

{deivceKey}/#

토픽 목록

용어

토픽 목록에서 이용되는 용어들에 대한 설명입니다.

deviceKey (디바이스 키)

시작하기 > 디바이스 키 구성 섹션에서 설명된 디바이스 키를 의미합니다.

sessionId (세션ID)

Nubison IoT 플랫폼 서버에서 디바이스와의 트랜잭션들을 식별하기 위해 발급되는 임시 값입니다.

디바이스와 Nubison IoT 서버 간 요청과 응답이 오가는 경우에 이용합니다.

디바이스 → NUBISON IoT 플랫폼

디바이스가 발행(Publish), Nubison IoT 플랫폼 서버가 구독(Subscribe)하는 토픽들입니다.

(1) connect/{deviceKey}

디바이스를 Nubison IoT 플랫폼 서버에 연결합니다.

(2) data/{deviceKey}

디바이스의 데이터를 Nubison IoT 플랫폼 서버에 전송합니다.

(3) heartbeat/{deviceKey}

디바이스의 연결 상태를 주기적으로 업데이트 할 때 발행합니다.

(4) res/{deviceKey} 또는 res/{sessionId}/{deviceKey}

서버로부터 요청을 받았을 경우 응답을 전송할 때 발행합니다.

제어에 대한 응답 처리 시에는 전달받은 sessionId를 토픽에 같이 보내주셔야 합니다.

(5) disconnect/{deviceKey}

디바이스가 Nubison IoT 플랫폼으로부터 연결 해제할 때 발행합니다.

Nubison IoT 플랫폼 → 디바이스

Nubison IoT 플랫폼 서버가 발행(Publish), 디바이스가 구독(Subscribe)하는 토픽들입니다.

(1) {deviceKey}/{sessionId}/command

Nubison IoT 플랫폼 서버가 디바이스에게 명령어를 전송하는 경우 발행됩니다.

케이스	기능	페이로드
연결 확인	Nubison IoT 플랫폼 서버가 디바이스에게 연결 상태를 직접 물어보는 경우 발행됩니다.
제어 전송	Nubison IoT 플랫폼 서버가 디바이스에 제어 명령을 보낼 때 발행됩니다. 디바이스에서는 res/{deviceKey} 토픽으로 ack를 회신해야 합니다.	control|${유닛번호}|${제어값}
최신 데이터 요청	Nubison IoT 플랫폼 서버가 디바이스의 최신 데이터를 전송하도록 요청할 때 발행됩니다. 디바이스에서는 res/{deviceKey} 토픽으로 데이터를 회신해야 합니다.

(2) {deviceKey}/res

디바이스로부터 요청을 받아 응답을 전송하는 경우 발행됩니다.

Nubison IoT 플랫폼 서버가 디바이스에게 Ack를 보내는 경우 성공 시 "플랫폼으로 보냈던 토픽 타입" + "|1", 실패 시 "플랫폼으로 보냈던 토픽 타입" + "|0"을 전송합니다.

예를 들어, data/{deviceKey} 토픽에 대한 응답은 "data|1" 또는 "data|0"으로 리턴됩니다.

자동 드라이버 이용 시 기본 데이터 규격

자동드라이버를 이용하시는 경우 다음과 같이 데이터를 구성하시면 됩니다.

• "|" 로 구분하여 일련의 문자열로 전송합니다. (자동 생성된 드라이버를 이용하는 경우, 디바이스가 보낸 데이터를 Nubison IoT 플랫폼 서버에서 "|" 로 데이터를 자른 후 유닛 번호 순서대로 데이터를 넣어 저장하게 됩니다.)

• 숫자, 위치 데이터는 숫자 포맷으로,

• 문자 데이터는 문자 포맷으로,

• 숫자 배열 데이터는 ","로 연접한 숫자

• 문자 배열 데이터는 ","로 연접한 문자

• 이미지는 base64로 인코딩한 스트링

예를 들어, 제품모델의 유닛을 다음과 같이 설정하고

0번: 온도 (숫자)
1번: 습도 (숫자)
2번: 모드 (문자)
3번: 위도 (위치)
4번: 경도 (위치)
5번: 온도 데이터 배열 (숫자 배열)
6번: 모드 데이터 배열 (문자 배열)
7번: 촬영 이미지 (이미지)

데이터를 다음과 같이 보낸다면

0번 유닛 "온도" 데이터 값: 32
1번 유닛 "습도" 데이터 값: 46
2번 유닛 "모드" 데이터 값: "default"
3번 유닛 "위도" 데이터 값: 38.23
4번 유닛 "경도" 데이터 값: 128.34
5번 유닛 "온도 데이터 배열" 데이터 값: [27,28,24,23,25]
6번 유닛 "모드 데이터 배열" 데이터 값: ["default", "sleep", "mood"]
7번 유닛 "이미지" 데이터 값: /9j/4AAQSkZJRgABAQAAAQABAAD/2w...

페이로드는 다음과 같이 보내면 됩니다.

payload =  "32|46|default|38.23|128.34|27,28,24,23,25|default,sleep,mood|/9j/4AAQSkZJRgABAQAAAQABAAD/2w..."

사용자 시나리오

아래 예시에서 deviceKey는

ABCDEF_123:AB:123

로 놓고 설명하겠습니다.

디바이스 연결 (타임라인 기록)

1. connect/ABCDEF_123:AB:123 토픽을 디바이스에서 발행합니다.

2. 서버로부터 다음과 같이 전송받으면 디바이스 연결 토픽 처리가 성공적으로 완료된 것입니다. - 토픽: ABCDEF_123:AB:123/res - 페이로드: 1

디바이스 연결 해제 (타임라인 기록)

1. disconnect/ABCDEF_123:AB:123 토픽을 디바이스에서 발행합니다.

2. 서버로부터 다음과 같이 전송받으면 디바이스 연결 해제 토픽 처리가 성공적으로 완료된 것입니다. - 토픽: ABCDEF_123:AB:123/res - 페이로드: 1

데이터 전송

1. data/ABCDEF_123:AB:123 토픽을 발행하고 payload에 데이터를 규격에 맞게 전송합니다.

MQTT 프로토콜을 이용하는 디바이스의 경우 디바이스 연결, 디바이스 연결 해제 상태 관리를 하지 않습니다. 따라서 데이터 전송 전후로 디바이스 연결 / 연결 해제 토픽 발행을 반드시 하실 필요는 없습니다.

디바이스 연결 / 연결 해제 토픽의 경우 Nubison IoT 플랫폼에서 타임라인 기록을 남겨 추적하고 싶으신 경우에 발행해주세요.

제어 처리

1. 누비즌 웹 화면에서 제어 유닛을 만들고 명령어를 보내면, 다음과 같이 데이터가 전송됩니다. - 토픽: deviceKey/세션ID/command - 페이로드: control|유닛번호|제어명령값 앞서 예시로 든 ABCDEF_123:12:123 디바이스에

   0번 유닛이 있고, “전원” 값을 제어한다고 가정해봅시다.

   OFF을 보내면 전원 OFF, ON을 보내면 전원 ON이 된다고 생각하고,

   전원 ON를 하기 위해 ON을 보낸다고 하면 다음과 같이 갑니다. (세션ID는 00eeffaa라고 가정) - 토픽: ABCDEF_123:AB:123/00eeffaa/command - 페이로드: control|0|ON

2. 디바이스에서는 해당 내용으로 원하는 동작을 하게끔 처리해주시고, 서버에는 다음과 같이 리턴합니다. - 토픽: res/00eeffaa/ABCDEF_123:AB:123 - 페이로드: 1

디바이스에 연결 확인

디바이스가 브로커에 연결되어 메세지를 송수신할 수 있는 상태인지 확인하는 방법입니다.

서비스 화면 > 디바이스 관리 > 디바이스를 클릭해서 나오는 다음 아이콘을 클릭하면

Nubison IoT 플랫폼 서버가 디바이스에 다음과 같이 연결 확인 토픽을 보냅니다. (세션ID는 00eeffaa라고 가정)

• 토픽: ABCDEF_123:AB:123/00eeffaa/connect

• 패이로드: 없음

디바이스에서는 위 토픽을 받으면 다음과 같이 응답하도록 작업해주시면 됩니다.

(세션ID는 00eeffaa라고 가정)

• 토픽: res/00eeffaa/ABCDEF_123:AB:123

• 페이로드: 없음