TCP/IP

Nubison IoT TCP/IP 표준 규격입니다.

Nubison IoT 플랫폼에 TCP/IP 패킷 데이터를 전송하는 디바이스를 연결하기 위한 가이드입니다.

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

서버 연결

Nubison IoT 플랫폼의 TCP/IP 패킷 통신 소켓에 연결하기 위한 정보입니다.

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

패킷 사이즈는 최소 9 bytes 이상이어야 합니다. 그 이하 패킷은 처리하지 않습니다.

인코딩 포맷은 UTF-8입니다.

패킷 종류 (Packet Type)

Nubison IoT 클라우드로 디바이스가 패킷 데이터를 보낼 때,

패킷 데이터 첫번째 바이트에 패킷 종류를 넣어 보내시면 디바이스가 보낸 요청이 어떤 요청인지를 판별하여 전송받은 데이터를 그에 맞게 처리합니다.

Nubison IoT에서 이용하는 패킷 종류는 다음과 같습니다.

종류	설명
L	로그인. Nubison IoT 클라우드에 디바이스가 접속하여 토큰을 발급받습니다.
O	로그아웃. Nubison IoT 클라우드로부터 디바이스가 로그아웃합니다.
D	데이터 전송 Nubison IoT 클라우드로 데이터를 전송합니다.Nubison IoT 클라우드로 데이터를 전송합니다.
C	제어명령 전송 Nubison IoT 클라우드에서 디바이스로 제어 명령을 보냅니다.
H	하트비트 Nubison IoT 클라우드에 하트비트(연결 유지용 패킷)를 전송합니다.
R	응답 디바이스 -> Nubison IoT 클라우드, 또는 Nubison IoT 클라우드 -> 디바이스로 응답 데이터를 전송할 때 이용합니다. 이 때 세션 ID는 앞서 전달받았던 세션 ID와 동일하게 가져가야 합니다.

용어 설명

• 세션 ID: 세션 ID는 각 트랜잭션을 구분하기 위한 값으로 요청을 보내는 쪽에서 랜덤으로 발생시킨 문자열이며 응답하는 쪽에서 그대로 반환하여 트랜잭션을 구분합니다.

• Access Token: 디바이스가 Nubison IoT 클라우드로 로그인 요청 시 발급하는 액세스 토큰. 데이터 전송 등의 요청 이전에 반드시 로그인 패킷을 보내야 합니다. 그리고 이후 모든 요청 전송 시 패킷 데이터에 발급받은 액세스 토큰을 포함시켜야 정상 처리가 됩니다.

• 클라이언트 ID & 클라이언트 시크릿: 시작하기 섹션 > 인증키 발급 파트에서 발급하신 클라이언트 ID, 클라이언트 시크릿 문자열입니다.

• 제품코드: 시작하기 섹션 > 제품모델 생성 파트에서 생성한 제품모델에 발급된 코드 문자열입니다.

• 디바이스 식별키: 시작하기 섹션 > 디바이스 추가 파트에서 생성한 디바이스의 식별키입니다.

로그인

[ 디바이스 -> Nubison IoT 클라우드 ]

1 byte	8 bytes	20 bytes	20 bytes	8 bytes	1 byte	any
string	string	string	string	string	int8	string
"L"	세션 ID	클라이언트 ID	클라이언트 시크릿	제품코드	디바이스 식별키 길이	디바이스 식별키

[ Nubison IoT 클라우드 -> 디바이스 ]

1. 성공 응답

1 byte	8 bytes	1 byte	24 bytes	1 byte (optional)	any (optional)
string	string	byte	string	int8	string
"R"	세션 ID	0x01	Access Token	Encryption Key Length	Encryption Key

1. 실패 응답

1 byte	8 bytes	1 byte	2 bytes
string	string	byte	byte
"R"	세션 ID	0x00	에러코드

로그아웃

[ 디바이스 -> Nubison IoT 클라우드 ]

1 byte	8 bytes	24 bytes
string	string	string
"O"	세션 ID	Access Token

[ Nubison IoT 클라우드 -> 디바이스 ]

1. 성공 응답

1 byte	8 bytes	1 byte
string	string	byte
"R"	세션 ID	0x01

데이터 전송

[ 디바이스 -> Nubison IoT 클라우드 ]

1 byte	8 bytes	24 bytes	2 bytes	any
string	string	string	UInt16BE	any
"D"	세션 ID	Access Token	페이로드 전체 길이	페이로드

기본 페이로드 규격

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

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

0번: 온도
1번: 습도
2번: 가속도

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

0번 유닛 "온도" 데이터 값: 32
1번 유닛 "습도" 데이터 값: 84
2번 유닛 "가속도" 데이터 값: 43

페이로드를 다음과 같이 구성해주시면 됩니다.

payload =  "32|84|43"

드라이버 자동생성에 대한 자세한 내용은 드라이버 생성을 참조해주세요. 보다 더 섬세한 데이터 페이로드 협의 및 구성이 필요하신 경우 문의 부탁드립니다.

[ Nubison IoT 클라우드 -> 디바이스 ]

1. 성공 응답

1 byte	8 bytes	1 byte
string	string	byte
"R"	세션 ID	0x01

1. 실패 응답

1 byte	8 bytes	1 byte	2 bytes
string	string	byte	byte
"R"	세션 ID	0x00	에러코드

제어명령 전송

[Nubison IoT 클라우드 -> 디바이스]

1 byte	8 bytes	24 bytes	2 bytes	any
string	string	string	UInt16BE	any
"C"	세션 ID	Access Token	페이로드 전체 길이	페이로드

[디바이스 -> Nubison IoT 클라우드]

1. 성공 응답

   1 byte	8 bytes	1 byte
   string	string	Int8
   "R"	세션 ID	1

2. 실패 응답

   1 byte	8 bytes	1 byte
   string	string	Int8
   "R"	세션 ID	1 이외의 숫자

하트비트

[ 디바이스 -> Nubison IoT 클라우드 ]

1 byte	8 bytes	24 bytes
string	string	string
"H"	세션 ID	Access Token

[ Nubison IoT 클라우드 -> 디바이스 ]

1. 성공 응답

1 byte	8 bytes	1 byte
string	string	byte
R	세션 ID	0x01

1. 실패 응답

1 byte	8 bytes	1 byte	2 bytes
string	string	byte	byte
R	세션 ID	0x00	에러코드

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

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

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

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

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

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

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

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

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

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

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

페이로드는 다음과 같이 구성한 후, 이를 패킷으로 보내주시면 됩니다.

payload =  "32|46|default|38.23|128.34|27,28,24,23,25|default,sleep,mood";
Buffer.from(payload)

Appendix A: 에러코드

Error Code	Description	Note
0x0001	Packet Type is not valid.	유효하지 않은 Packet Type입니다. 본 문서를 참조하여 주십시오.
0x0002	Packet structure is not valid.	Packet Type에 따른 패킷 구조가 유효하지 않습니다.
0x0003	Client ID or Client Secret is not valid.	NUBISON IoT 클라우드에서 다시 확인하십시오.
0x0004	Device is not registered.	NUBISON IoT 클라우드에서 디바이스를 먼저 등록 후 연결하시기 바랍니다.
0x0005	Access Token is not valid.	Access Token이 유효하지 않습니다.
0x0006	Payload structure is not valid.	Payload 구조가 NUBISON IoT 클라우드에 등록된 디바이스 드라이버와 다릅니다.
0x9999	Server Error	서버 오류입니다. 담당자에게 문의하여 주십시오.