개발 가이드

IoT Portal 서비스 개발에 필요한 개발 가이드 입니다.

HTTP Server로 개발하기

LoRa 디바이스 제어하기

사용자의 제어 요청은 어떻게 동작할까?

ThingPlug를 통해서 LoRa 디바이스를 제어할 수 있습니다. App/Web 서버가 ThingPlug에 제어 명령을 전달 하게 되면 ThingPlug는 제어 명령을 N/W 서버를 통해 LoRa 디바이스로 전달(Downlink)합니다.
LoRa 디바이스로 전달할 수 있는 제어 명령은 2가지 입니다.

개발가이드 설명
Resource API Type 제어 설명
mgmtCmd-[LTID]_DevReset LoRa 디바이스 리셋
mgmtCmd-[LTID]_extDevMgmt 서비스에 따라 App/Web서버와 LoRa 디바이스간에 정의된 Application 명령 

제어 명령 보내기

1) mgmtCmd-[LTID]_DevReset

LoRa 디바이스를 리셋하기 위한 명령입니다. 이 명령은 오직 디바이스 리셋을 위해 사용하기 때문에 별도의 payload를 함께 보낼 수 없습니다.

개발가이드 설명
Description LoRa 디바이스를 리셋하기 위한 명령
Requirements ukey: 사용자 인증키
<exe>: true로 설정
개발가이드 설명
Request

                                                    
Response

                                                    

2) mgmtCmd-[LTID]_extDevMgmt

서비스에 따라 App/Web서버와 LoRa 디바이스간의 제어 명령을 정의해서 사용할 수 있습니다. 이 명령은 1회에 최대 62bytes의 payload를 함께 디바이스로 전송할 수 있습니다.

개발가이드 설명
Description Application 제어 명령
Requirements ukey: 사용자 인증키
<exe>: true로 설정
<exra>: Application 제어 명령
개발가이드 설명
Request

                                                    
Response

                                                    

62bytes는 Hexa decimal 형태로 입력해야 합니다 만약 <exra>에 “01020304” 데이터를 보낸다면, LoRa 디바이스는 “0x01 0x02 0x03 0x04”로 수신하게 됩니다

개발가이드 설명
LoRa 디바이스 ThingPlug
0x00 00
0x01 01
... ...
0xFE FE
0xFF FF

서비스에 따라 extDevMgmt는 App/Web 서버에 구현하지 않아도 되지만, DevReset은 필수적으로 구현되어야 합니다.

제어 결과 확인

제어 명령의 결과도 데이터 조회와 동일하게 “Polling”과 “Subscription” 방식으로 조회할 수 있습니다

1) Polling으로 제어 결과 조회하기

Polling으로 제어 결과 조회하기

App/Web 서버가 제어 요청을 하게 되면 N/W 서버는 LoRa 디바이스로 제어 명령을 전달(Downlink)하고 성공 여부를 ThingPlug에 저장하게 됩니다. 그 후에 사용자는 해당 제어 명령에 대한 결과를 별도의 요청을 통해 확인할 수 있습니다.

제어 명령의 결과를 조회하기 위해서는 제어 명령의 Resource ID를 우선 확인해야 합니다. 제어 명령의 Resource ID는 제어 요청 시 응답에서 확인할 수 있습니다. <m2m:exin> 하위에 <ri>의 값이 제어 명령에 대한 Resource ID입니다. <m2m:exin> 하위에 <ri>의 값이 제어 명령에 대한 Resource ID입니다.

개발가이드 설명
xml 소스코드 뷰어

                                                

이 ID 값을 가지고 제어 명령 결과 요청 API에 사용하면, 해당 제어 명령의 수행 결과를 응답으로 받을 수 있습니다.
위 예를 보면 <ri>는 EI00000000000000130139 값인 것을 확인 할 수 있으며, 아래 명령설명에서 URI에 execInstance-EI00000000000000130139 와 같이 입력해서 사용합니다.

개발가이드 설명
Description LoRa 디바이스 리셋 명령의 결과 조회
Requirements ukey: 사용자 인증키
execInstance: 제어 명령의 Resource ID
개발가이드 설명
Request

                                                    
Response

                                                    

제어 결과에서 <exs>와 <exr>로 결과를 확인할 수 있습니다.
<exs>는 execute Status의 약자로 제어의 현재 상태를 의미 합니다.
3은 ‘Finished’를 의미하며 제어 명령의 처리가 끝났음을 의미합니다.
<exr>은 execute Result의 약자로 제어 명령의 처리가 끝났을 때의 결과를 의미합니다. 0은 ‘SUCCEED’를 의미합니다.
<exs>와 <exr>의 세부 결과는 아래 표를 참고하세요

2) Subscription으로 제어 결과 Push 받기

제어 결과를 Push 받을 수 있다.

LoRa 디바이스마다 각각 한번씩 Subscription 요청을 해두면 제어 명령(Downlink)의 성공 여부를 App/Web 서버로 Push 받을 수 있습니다.

개발가이드 설명
Description Application 제어 명령의 결과 Subscription
Requirements ukey: 사용자 인증키
X-M2M-NM: Subscription을 구분하기 위한 구분자, 예제에서는 임의의 값 “test_subscription” 사용<rss>: 5(제어 명령 결과)
<nu>: 제어 결과를 Push 받을 서버의 URL
개발가이드 설명
Request

                                                    
Response

                                                    

Subscription에 의해 Push 받은 제어 명령(Downlink)의 결과는 아래와 같습니다.

개발가이드 설명
xml 소스코드 뷰어

                                                

App/Web 서버는 위 데이터 포맷을 수신하고 이전에 보냈던 제어 명령(Downlink)가 성공했는지, 실패했는지 여부를 판단할 수 있습니다.

App/Web 서버가 최초에 제어 명령(Downlink)를 요청한 시간을 <ct> 필드로 확인할 수 있으며, 제어 명령의 결과가 업데이트 된 시간을 <lt> 필드에서 확인할 수 있습니다. 또한, <et> 필드의 시간이 되면 해당 제어 명령은 ThingPlug에서 삭제됩니다. 다시 말해, <ct>에 요청한 제어 명령이 <lt>에 완료되었다는 의미입니다.

제어 명령의 결과는 <exs>와 <exr>로 결과를 확인할 수 있습니다.
<exs>는 execute Status의 약자로 제어의 현재 상태를 의미 합니다. 3은 ‘Finished’를 의미하며 제어 명령의 처리가 끝났음을 의미합니다. <exr>은 execute Result의 약자로 제어 명령의 처리가 끝났을 때의 결과를 의미합니다. 0은 ‘SUCCEED’를 의미합니다.

제어 결과 테이블

exs(execute status) 의미

개발가이드 설명
1 INITIATED
2 PENDING
3 FINISHED
4 CANCELLING
5 CANCELLED
6 STATUS_NON_CANCELLABLE

exr(execute result) 의미

개발가이드 설명
0 STATUS_REQUEST_SUCCEED
1 STATUS_REQUEST_UNSUPPORTED
2 STATUS_REQUEST_DENIED
3 STATUS_CANCELLATION_DENIED
4 STATUS_INTERNAL_ERROR
5 STATUS_INVALID_ARGUMENTS
6 STATUS_RESOURCES_EXCEEDED
7 STATUS_FILE_TRANSFER_FAILED
8 STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE
9 STATUS_UNSUPPORTED_PROTOCOL
10 STATUS_UPLOAD_FAILED
11 STATUS_FILE_TRANSFER_FAILED_MULTICAST_GROUP_UNABLE_JOIN
12 STATUS_FILE_TRANSFER_FAILED_SERVER_CONTACT_FAILED
13 STATUS_FILE_TRANSFER_FAILED_FILE_ACCESS_FAILED
14 STATUS_FILE_TRANSFER_FAILED_DOWNLOAD_INCOMPLETE
15 STATUS_FILE_TRANSFER_FAILED_FILE_CORRUPTED
16 STATUS_FILE_TRANSFER_FILE_AUTHENTICATION_FAILURE
17 STATUS_FILE_TRANSFER_FAILED
18 STATUS_FILE_TRANSFER_SERVER_AUTHENTICATION_FAILURE
19 STATUS_FILE_TRANSFER_WINDOW_EXCEEDED
20 STATUS_INVALID_UUID_FORMAT
21 STATUS_UNKNOWN_EXECUTION_ENVIRONMENT
22 STATUS_DISABLED_EXECUTION_ENVIRONMENT
23 STATUS_EXECUTION_ENVIRONMENT_MISMATCH
24 STATUS_DUPLICATE_DEPLOYMENT_UNIT
25 STATUS_SYSTEM_RESOURCES_EXCEEDED
26 STATUS_UNKNOWN_DEPLOYMENT_UNIT
27 STATUS_INVALID_DEPLOYMENT_UNIT_STATE
28 STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_DOWNGRADE_DISALLOWED
29 STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_UPGRADE_DISALLOWED
30 STATUS_INVALID_DEPLOYMENT_UNIT_UPDATE_VERSION_EXISTS
31 STATUS_DEVICE_MANAGEMENT_TIME_OUT
32 STATUS_NW_SVR_TRANSFER_FAILED

top