MYPAGE LOGIN
개요 데이터 모델 백본 네트워크 I/F 로컬 조명 네트워크 I/F 기술지원 / Q&A

1. 개요
2. GW B-SLP API 규격
3. 코드 정의
1. 개요
1.1 개요

 본 문서는 스마트 조명 통합 게이트웨이의 B-SLP(Backbone – Smart Lighting Profile) API(Application Programming Interface)에 대한 규격서이다. 이 규격서는 REST 형태로 작성 되었다.

1.2 관련 문서

1. 스마트 조명 시스템 – 제1부 일반 요구사항, KSC7751-1
2. 스마트 조명 시스템 – 제2부 시스템 구조, KSC7751-2
3. 스마트 조명 시스템 – 제3부 주소체계, KSC7751-3
4. 스마트 조명 관제서버 B-SLP REST API 규격서
5. 스마트 조명 유지보수고장진단 서비스서버 B-SLP REST API 규격서
6. 스마트 조명 게이트웨이 B-SLP MQTT API 규격서
7. 스마트 조명 조명/센서 L-SLP CoAP API 규격서 (Plain Text)
8. 스마트 조명 조명/센서 L-SLP CoAP API 규격서 (Octet Stream)
9. 스마트 조명 게이트웨이 L-SLP CoAP API 규격서 (Plain Text)

1.3 적용 범위
본 REST기반 B-SLP API 규격서는 다음과 같은 분야를 포함한다.
GW-MS 연동
GW-UD3 연동
GW-TS3 연동
 
위에서 정의한 분야별 B-SLP API에 대해 각각 다음과 같은 사항에 대하여 기술한다.
REST기반 API 이름 및 정의
요청/응답 메시지 포맷 및 파라미터
결과 코드 정의
1.4 약어

번호

약어

설명

1

GW

Gateway

2

BPV

B-SLP Profile Version

3

B-SLP

Backbone - Smart Lighting Profile

4

CID

Controller IDentification

5

CPID

Controller Physical IDentification

6

CoAP

Contrained Application Protocol

7

DID

Device IDentification

8

DPID

Device Physical IDentification

9

GID

Group IDentification

10

GWID

Gateway IDentification

11

GWPID

Gateway Physical IDentification

12

LD

Lighting Device

13

LID

Location IDentification

14

LPV

L-SLP Profile Version

15

L-SLP

Local - Smart Lighting Profile

16

MS

Management Server

17

PC

Produce Code

18

PID

Physical IDentification

19

SCID

Scene IDentification

20

SD

Sensor Device

21

SN

Serial Number

22

SSDP

Simple Service Discovery Protocol

23

TID

Tester IDentification

24

TPID

Test Device Physical IDentification

25

TS

Test Device

26

UD

User input Device

27

URL

Uniform Resource Locator

2. GW B-SLP API 규격
2.1 API 기본 정보
 게이트웨이 B-SLP는 REST기반으로 Base URL은 다음과 같이 정의한다. gw_ip는 게이트웨이의 IP 주소이고, gw_port는 TCP 포트번호로 HTTPS의 디폴트 포트번호인 443이다.  도메인 주소도 사용이 가능하다.
Base URL: https://{gw_ip}:{gw_port}/gw
Base URL : https://{domain}/gw
 
 게이트웨이 B-SLP의 항목은 다음과 같은 조건(Constraint, C)을 가진다.
M (Mandatory, 필수): 필수로 포함되는 항목
O (Optional, 선택): 선택적으로 포함되는 항목
CM (Conditionaly Mandatory, 조건부 필수): 선행 항목의 값에따라 필수로 포함되는 항목
2.2 API 기능 확장

 URL에는 쿼리스트링(query string)을 사용하여 사용자 입력 데이터를 전달할 수 있다. 이러한 쿼리스트링을 통하여 API의 기능을 다양하게 확장할 수 있다.

 

2.2.1 쿼리스트링 형식
 
 API의 엔드 포인드(end point) 주소에 "?"를 붙여 쿼리스트링의 시작을 알리고, 파라미터(parameter)와 값(value)로 구성된 파라미터 값을 추가하여 표시한다. 또한 "&"를 붙여 파라미터 값을 추가할 수 있다.
{base_url}/endpoint?parameter=value
{base_url}/endpoint?parameter1=value1&parameter2=value2
 
2.2.2 범위 제한
 
 B-SLP 사용자는 URL-Path에 쿼리 파라미터로 논리주소를 제공하여 요청 범위를 제한하여 선택적으로 요청할 수 있다.
 
모듈 논리주소로 제한
{base_url}/endpoint?mid={mid}
(ex) PATCH, {base_url}/light?mid=2 : mid=2인 모듈의 조명 상태정보 제어
 
 
2.2.3 속성 필터
 B-SLP 사용자는 URL-Path에 특정 속성을 포함한 쿼리스트링을 추가함으로써 요청 범위를 제한하여 선택적으로 요청할 수 있다. 속성 타입이 String, Int8/16/32, Float 등 단일 속성은 "attr" 파라미터를 사용하여 필터링할 수 있다. Object와 같은 다수의 단일 속성으로 구성된 객체 속성은 "attrs" 파라미터를 사용하여 필터링할 수 있다. 
 
단일 속성 필터링
{base_url}/endpoint?attr={attribute}
(ex) GET, {base_url}/devices/{did}/dinfo?attr=lid : 디바이스 기본정보중 위치정보만 요청
객체 속성 필터링 
{base_url}/endpoint?attrs={attribute set}
(ex) GET, {base_url}/device?attrs=dinfo: 디바이스 정보중 dinfo 정보만 요청
 
2.2.4 속성 제한
 B-SLP 사용자는 URL-Path에 세부 속성의 특정 값을 포함한 쿼리스트링을 추가함으로써 요청 범위를 제한하여 선택적으로 요청할 수 있다.
 
특정 값 제한
{base_url}/endpoint?{attribute}={value}
(ex) GET, {base_url}/module/minfo?mclass=l : mclass가 l(조명)인 모듈들만의 모듈정보(minfo)
2.3 API 목록

2.3.1 자원별 API 목록

 

구분

API명

URL

Method

게이트웨이

게이트웨이 탐색 - REST

{base_url}/discovery

GET

게이트웨이 전체정보 조회

{base_url}

GET

게이트웨이 기본정보 조회

{base_url}/gwinfo

GET

게이트웨이 기본정보 변경

{base_url}/gwinfo

PATCH

게이트웨이 수용능력 조회

{base_url}/cap

GET

게이트웨이 자원 동기화 버전 조회

{base_url}/sync

GET

게이트웨이 재시작

{base_url}/restart

POST

게이트웨이 공장초기화

{base_url}/reset

POST

게이트웨이 부속장치 전체 정보 조회

{base_url}/units

GET

게이트웨이 부속장치 목록 조회

{base_url}/units?attr=unid&attr=utype&attr=did_list

GET

게이트웨이 부속장치 개별 정보 조회

{base_url}/units/{unid}

GET

게이트웨이 부속장치 설정정보 변경

{base_url}/units/{unid}

PUT/

PATCH

게이트웨이 부속장치 전체 릴레이 제어

{base_url}/units?utype=2

PATCH

사용자 입력장치

사용자 입력장치 전체정보 조회

{base_url}/controllers

GET

사용자 입력장치 정보 생성

{base_url}/controllers

POST

사용자 입력장치 연결

{base_url}/controllers/connect

POST

사용자 입력장치 기본정보 조회

{base_url}/controllers/{cid}/cinfo

GET

사용자 입력장치 기본정보 변경

{base_url}/controllers/{cid}/cinfo

PATCH

사용자 입력장치 삭제

{base_url}/controllers/{cid}?cpid={cpid}&lid={lid}

DELETE

설치시험기

설치시험기 전체정보 조회

{base_url}/testers

GET

설치시험기 정보 생성

{base_url}/testers

POST

설치시험기 연결

{base_url}/testers/connect

POST

설치시험기 기본정보 조회

{base_url}/testers/{tid}/tinfo

GET

설치시험기 기본정보 변경

{base_url}/testers/{tid}/tinfo

PATCH

설치시험기 삭제

{base_url}/testers/{tid}?tpid={tpid}&lid={lid}

DELETE

디바이스

공통

전체 디바이스 목록 조회

- 디바이스 전체정보 목록 조회

{base_url}/devices

GET

- 디바이스 객체속성 목록 조회

{base_url}/devices/{attributes}

GET

- 디바이스 논리주소 목록 조회

{base_url}/devices?attr=did

GET

- 위치주소 미할당 디바이스 논리주소 목록 조회

{base_url}/devices?attr=did&lid=0

GET

디바이스 식별

- 디바이스 식별

{base_url}/devices/{did}/identify

PUT/

PATCH

- 디바이스 모듈 식별

{base_url}/devices/{did}/identify?mid={mid}

PUT/

PATCH

- 디바이스 그룹 식별

{base_url}/devices/65535/identify?gid={gid}

PUT/

PATCH

디바이스 전체정보 조회

{base_url}/devices/{did}

GET

디바이스 기본정보 조회

{base_url}/devices/{did}/dinfo

GET

디바이스 기본정보 변경

{base_url}/devices/{did}/dinfo

PATCH

디바이스 수용능력 조회

{base_url}/devices/{did}/cap

GET

디바이스 전체 모듈 전체정보 조회

{base_url}/devices/{did}/modules

GET

디바이스 전체 모듈 기본정보 목록 조회

{base_url}/devices/{did}/modules/minfo

GET

디바이스 개별 모듈 전체정보 조회

{base_url}/devices/{did}/modules/{mid}

GET

디바이스 개별 모듈 기본정보 조회

{base_url}/devices/{did}/modules/{mid}/minfo

GET

디바이스 삭제

{base_url}/devices/{did}?dpid={dpid}

DELETE

디바이스 재시작

{base_url}/devices/{did}/restart

POST

디바이스 공장초기화

{base_url}/devices/{did}/reset

POST

조명

디바이스 조명 상태정보 조회

- 전체 조명 모듈 조회

{base_url}/devices/{did}/light

GET

- 개별 조명 모듈 조회

{base_url}/devices/{did}/modules/{mid}/light

GET

디바이스 조명 상태정보 변경 (조명 제어)

- 전체 조명 모듈 동일 제어

{base_url}/devices/{did}/light

PATCH

- 전체 조명 모듈 개별 제어

{base_url}/devices/{did}/light

PATCH

- 개별 조명 모듈 제어

{base_url}/devices/{did}/modules/{mid}/light

PATCH

디바이스 조명 설정정보 조회

- 전체 조명 모듈 조회

{base_url}/devices/{did}/lightconfig

GET

- 개별 조명 모듈 조회

{base_url}/devices/{did}/modules/{mid}/lightconfig

GET

디바이스 조명 설정정보 변경

- 전체 조명 모듈 동일 변경

{base_url}/devices/{did}/lightconfig

 

PUT/

PATCH

- 전체 조명 모듈 개별 변경

{base_url}/devices/{did}/lightconfig

 

PUT/

PATCH

- 개별 조명 모듈 변경

{base_url}/devices/{did}/modules/{mid}/lightconfig

PUT/

PATCH

디바이스 조명 점등 상태정보 조회

- 전체 조명 모듈 조회

{base_url}/devices/{did}/onconfig

GET

- 개별 조명 모듈 조회

{base_url}/devices/{did}/modules/{mid}/onconfig

GET

디바이스 조명 점등 상태정보 변경

- 전체 조명 모듈 동일 변경

{base_url}/devices/{did}/onconfig

PUT/

PATCH

- 전체 조명 모듈 개별 변경

{base_url}/devices/{did}/onconfig

PUT/

PATCH

- 개별 조명 모듈 변경

{base_url}/devices/{did}/modules/{mid}/onconfig

PUT/

PATCH

디바이스 현재 조명상태의 점등 상태정보 저장

- 전체 조명 모듈 저장

{base_url}/devices/{did}/onconfig

PUT

- 개별 조명 모듈 저장

{base_url}/devices/{did}/modules/{mid}/onconfig

PUT

센서

디바이스 센서 공통 설정정보 조회

- 전체 센서 모듈 조회

{base_url}/devices/{did}/sensor

GET

- 특정 센서타입 조회

{base_url}/devices/{did}/sensor?mtype={mtype}

GET

디바이스 센서 개별 설정정보 조회

{base_url}/devices/{did}/modules/{mid}/sensor

GET

디바이스 센서 공통 설정정보 변경

- 전체 센서 모듈 동일 변경

{base_url}/devices/{did}/sensor

PATCH

- 특정 센서타입 동일 변경

{base_url}/devices/{did}/sensor?mtype={mtype}

PATCH

디바이스 센서 개별 설정정보 변경

{base_url}/devices/{did}/modules/{mid}/sensor

PATCH

그룹

그룹 생성

{base_url}/groups

POST

그룹 등록

{base_url}/groups

PUT

그룹 목록 조회

- 그룹 전체정보 목록 조회

{base_url}/groups

GET

- 그룹 논리주소 목록 조회

{base_url}/groups?attr=gid

GET

그룹 구성정보 조회

{base_url}/groups/{gid}

GET

그룹 구성정보 변경

{base_url}/groups/{gid}

PATCH

그룹 삭제

- 개별 그룹 삭제

{base_url}/groups/{gid}

DELETE

- 전체 그룹 삭제

{base_url}/groups/65535

DELETE

그룹 조명 상태정보 변경

(그룹 조명제어)

{base_url}/groups/{gid}/light

PATCH

그룹 조명 설정정보 변경

{base_url}/groups/{gid}/lightconfig

PATCH

그룹 센서 설정정보 변경

- 전체 그룹 동일 변경

{base_url}/groups/{gid}/sensor

PATCH

- 특정 센서타입 그룹 설정

{base_url}/groups/{gid}/sensor?mtype={mtype}

PATCH

그룹 하위 디바이스 조회

- 그룹 하위 디바이스 전체정보 목록 조회

{base_url}/groups/{gid}/devices

GET

- 그룹 하위 디바이스 객체속성 목록 조회

{base_url}/groups/{gid}/devices/{attrs}

GET

장면

(Scene)

장면 생성

{base_url}/scenes

POST

장면 등록

{base_url}/scenes

PUT

현재상태 장면 생성

{base_url}/scenes

POST

현재상태 장면 등록

{base_url}/scenes

PUT

장면 목록 조회

- 장면 전체정보 목록 조회

{base_url}/scenes

GET

- 장면 논리주소 목록 조회

{base_url}/scenes?attr=scid

GET

장면 설정정보 조회

{base_url}/scenes/{scid}

GET

장면 설정정보 변경

{base_url}/scenes/{scid}

PATCH

장면 호출

{base_url}/scenes/{scid}/goto

POST

장면 삭제

- 개별 장면 삭제

{base_url}/scenes/{scid}

DELETE

- 전체 장면 삭제

{base_url}/scenes/65535

DELETE

장면 하위 디바이스 조회

- 장면 하위 디바이스 전체정보 목록 조회

{base_url}/scenes/{scid}/devices

GET

- 장면 하위 디바이스 객체속성 목록 조회

{base_url}/scenes/{scid}/devices/{attrs}

GET

고장

디바이스 고장정보 조회

{base_url}/faults

GET

2.4 사용자 정의 헤더
2.4.1 Operator 정보
 
 모든 Request 메시지의 헤더에는 매개변수로 요청자 정보(x-operator)를 제공하여야 한다. 게이트웨이는 수신된 Request 메시지에 대한 처리의 결과로 MQTT 메시지를 발행하는 경우 해당 MQTT 메시지에 요청자 정보를 포함하여야 한다.
 
x-operator: user.{cid}, tester.{tid}, actuator.{did}.{mid}/actuator.{did}, lms.{ip}, ai.{ip}, iwf.{ip}
 
 요청자 정보에는 요청자 종류와 요청자 논리주소로 구성된다. 요청자 종류에는 사용자(user), 설치시험기(tester), 관제서버(lms), 인공지능서버(ai), 작동장치(actuator)가 있다. 사용자(user)의 요청자 논리주소는 사용자가 사용한 사용자 입력장치(앱, 스위치 등)의 논리주소(cid)를 사용한다.  사용자가 아닌 센서 등과 같은 작동장치(actuator)의 요청자 논리주소는 게이트웨이에 등록된 디바이스 논리주소(did)와 모듈 논리주소(mid)의 조합 또는 디바이스 논리주소(did) 단독으로 사용한다.  논리주소를 할당받지 않는 관제서버(lms), 인공지능서버(ai), 이종 네트워크 연동(iwf) 서버 또는 게이트웨이 등의 요청자 논리주소는 요청자의 IP 주소를 사용한다.
2.5 게이트웨이 API

 본 절에서는 스마트 조명 게이트웨이의 자원에 대한 B-SLP API를 제시한다.

 

2.5.1 게이트웨이 탐색 (GW Discovery) – SSDP


 네트워크 내에 연결 가능한 게이트웨이를 찾기위한 방법으로 SSDP(Simple Service Discovery Protocol)를 이용하는 방법을 제시한다. 
 SSDP는 HTTP를 사용하고 Advertisement와 Search 두 개의 타입이 있다. Advertisement 메시지는 디바이스가 자신을 알리기 위해 사용하는 메시지이고, Search 메시지는 디바이스를 찾기위해 사용하는 메시지이다. 타입은 메시지 첫줄에 명시한다. 스마트 조명 게이트웨이에 연결을 원하는 디바이스는 스마트 조명 게이트웨이를 찾기 위해서 SSDP의 Search 타입을 이용한다. SSDP를 이용한 게이트웨이 검색을 수행하며 사용하는포트는 UDP 1900이며 IP 멀티캐스트(multicast) 주소를 이용한다. IPv4에서 멀티캐스트 주소는 "239.255.255.250"를 사용하고, IPv6에서는 "ff0x::c"를 사용한다. 

 

2.5.1.1 미확인 게이트웨이 탐색
 
 연결을 원하는 스마트 조명 게이트웨이의 UUID를 모르는 경우 스마트 조명 게이트웨이 공통 URN을 이용하여 탐색할 수 있다.
스마트 조명 게이트웨이를 탐색하기 위하여 ST(Serarch Target)에는 공통 URN을 다음과 같은 형식으로 정의하고, 버전(version)은 1로 한다.
 
- urn:schemas-upnp-org:device:smartlight-gateway:
 
HTTP Request
 

Header

M-SEARCH * HTTP/1.1

Host: {multicast IP}:{port}

ST: urn:schemas-upnp-org:device:smartlight-gateway:1

MAN:"ssdp:discover"

MX: 3

 
HTTP Response
 

Header

HTTP/1.1 200 OK

ST: urn:schemas-upnp-org:device:smartlight-gateway:1

USN: uuid:smartlight-{gwpid}::urn:schemas-upnp-org:device:smartlight-gateway:1

LOCATION: https://{gw_ip}:{gw_port}/gw/discovery

 
Response의 LOCATION 정보를 이용하여 Gateway Discovery REST API를 수행한다.
 
 
2.5.1.2 확인 게이트웨이 탐색

 연결을 원하는 스마트 조명 게이트웨이의 UUID를 알고 있는 경우 스마트 조명 게이트웨이 UUID를 이용하여 탐색할 수 있다.
 
 
HTTP Request
 

Header

M-SEARCH * HTTP/1.1

Host: {multicast IP}:{port}

ST: uuid:smartlight-{gwpid}

MAN:"ssdp:discover"

MX: 3

 
HTTP Response
 

Header

HTTP/1.1 200 OK

ST: uuid:smartlight-{gwpid}

USN: uuid:smartlight-{gwpid}

LOCATION: https://{gw_ip}:{gw_port}/gw/discovery

 
Response의 LOCATION 정보를 이용하여 Gateway Discovery REST API를 수행한다.
 
2.5.2 게이트웨이 탐색 (GW Discovery) - REST

 네트워크 내에 연결 가능한 게이트웨이를 찾기위한 방법으로 HTTP/REST를 이용하는 방법을 제시한다. 
 
HTTP Request
 

URI

{base_url}/discovery

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

gwid

Uint16

O

게이트웨이 논리주소

gwpid

Hex(18)

M

게이트웨이 물리주소

pc

Hex(62)

O

게이트웨이 제품 코드

sn

String(10)

O

게이트웨이 일련번호

lid

Hex(28)

O

게이트웨이 위치주소

ip

String

M

게이트웨이 B-SLP 접속 IP 주소

tport

Uint16

O

게이트웨이 B-SLP 접속 포트번호

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

       "gwid": 8,

"gwpid":"1234567890AABBCCDD",

"pc":"03EF010300FF…",

       "sn":"1609123456",

       "lid":"010000040A0000002F000000ED",

"ip":"192.168.2.97",

"tport":8080

}

}

 

비고

 

 

2.5.3 게이트웨이 전체정보 조회


 게이트웨이 전체정보 조회 API는 게이트웨이의 기본정보, 버전정보 수용능력 정보를 조회하기 위한 API이다.

 

HTTP Request
 

URI

{base_url}

Method

GET

Header

Content-Type: application/json

비고

 

 
 
HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

gwid

UInt16

M

게이트웨이 논리주소

gwinfo

Object

M

게이트웨이 기본 정보

gwpid

Hex(18)

M

게이트웨이 물리주소

pc

Hex(62)

O

제품 코드

sn

String(10)

O

일련번호

lid

Hex(28)

O

위치주소

ip

String

O

IP 주소

tport

Uint16

O

B-SLP TCP 포트번호

uport

Uint16

O

L-SLP UDP 포트번호

ms_addr

String

O

관제서버 IP 주소 또는 도메인

ms_port

UInt16

O

관제서버 포트 번호

bk_addr

String

O

MQTT 브로커 IP 주소 또는 도메인

bk_port

Uint16

O

MQTT 브로커 포트 번호

mqtt_report

Uint32

O

MQTT Report 주기

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

mqtt_ua_enable

String

O

MQTT Units Alarm 활성화 여부

mqtt_ua_list

Uint8 Arrary

O

MQTT Units Alarm 활성화 목록

version

Object

O

게이트웨이 버전 정보

hwv

String

O

Hardware 버전

osv

String

O

OS 버전

fwv

String

O

Firmware 버전

bpv

String

O

B-SLP 프로파일 버전

lpv

String

O

L-SLP 프로파일 버전

cap

Object

O

게이트웨이 수용능력 정보

dcap

Object

O

디바이스 수용능력 정보 객체

maxd

Uint16

M

연결 가능한 디바이스 개수

connd

Uint16

O

연결중인 디바이스 개수

gcap

Object

O

그룹 수용능력 정보 객체

maxg

Uint16

M

지원 가능한 그룹 개수

usedg

Uint16

O

사용중인 그룹 개수

scap

Object

O

장면 수용능력 정보 객체

maxs

Uint16

M

지원 가능한 장면 개수

useds

Uint16

O

사용중인 장면 개수

sync

Object

M

게이트웨이 동기화 버전 정보

units_sync

String(20)

CM

게이트웨이 부속장치 동기화 버전 정보

- 조건: 부속장치가 있는 경우

devices_sync

String(20)

M

디바이스 동기화 버전 정보

groups_sync

String(20)

M

그룹 동기화 버전 정보

scenes_sync

String(20)

M

장면 동기화 버전 정보

   units

Object Array

CM

게이트웨이 부속장치 목록

- 조건: 부속장치가 있는 경우

unid

Uint16

M

부속장치 논리주소

utype

Uint8

M

부속장치 종류

active

String

M

부속장치 동작 여부

event_value

Uint8

M

부속장치 상태 정보

mqtt_ue_enable

String

M

MQTT 부속장치 Event 활성화 여부

relay_onoff

String

CM

릴레이 상태정보

- 조건: utype=2(릴레이)

did_list

Uint16 Array

CM

릴레이에 연결된 디바이스 논리주소 목록

- 조건: utype=2(릴레이)

gid_list

Uint16 Array

CM

릴레이에 연결된 그룹 논리주소 목록

- 조건: utype=2(릴레이)

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"gwid":12,

"gwinfo": {

"gwpid":"1234567890AABBCCDD",

"pc":"03EF0103ABCDEFGH123456ABC…",

"sn":"1609123456",

"lid":"010000040A0000002F000000ED",

"ip":"192.168.2.97",

"tport": 8080,

"mqtt_report": 300,

"mqtt_df_enable":"enable"

},

"version": {

"hwv":"1.1.3",

"osv":"1.1.2",

"fwv":"1.1.2",

"bpv":"2.0.0",

"lpv":"2.0.0"

},

"cap": {

"dcap": {

"maxd": 1024,

"connd": 200

},

"gcap": {

"maxg": 256,

"usedg":12

},

"scap": {

"maxs": 256,

"useds": 4

}

},

"sync": {

"units_sync":"2023-01-17T17:13:40Z",

"devices_sync":"2023-01-17T17:13:40Z ",

"groups_sync":"2023-01-17T17:13:40Z ",

"scenes_sync":"2023-01-17T17:13:40Z "

        },

"units": [

{

"unid": 0,

"utype": 0,

"active":"enable",

"event_value": 0,

"mqtt_ue_enable":"enable"

},

{

"unid": 1,

"utype": 2,

"active":"enable",

"event_value": 0,

"mqtt_ue_enable":"enable",

"relay_onoff":"on",

"did_list": [1, 2, 3, 4, 5],

"gid_list":[]

}

]

}

}

 

비고

 

 
2.5.4 게이트웨이 기본정보 조회

 게이트웨이 기본정보 조회 API는 게이트웨이의 위치정보, 게이트웨이가 접속할 관제서버 접속정보, 게이트웨가 관리하는 디바이스의 위치정보 등을 조회하기 위한 API이다.
 
 
HTTP Request
 

URI

{base_url}/gwinfo

Method

GET

Header

Content-Type: application/json

비고

 

 
 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

gwpid

Hex(18)

M

게이트웨이 물리주소

pc

Hex(62)

O

제품 코드

sn

String(10)

O

일련번호

lid

Hex(28)

O

위치주소

ip

String

O

IP 주소

tport

Uint16

O

B-SLP TCP 포트번호

uport

Uint16

O

L-SLP UDP 포트번호

ms_addr

String

O

관제서버 IP 주소 또는 도메인

ms_port

UInt16

O

관제서버 포트 번호

bk_addr

String

O

MQTT 브로커 IP 주소 또는 도메인

bk_port

Uint16

O

MQTT 브로커 포트 번호

mqtt_report

Uint32

O

MQTT Report 주기

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

mqtt_ua_enable

String

O

MQTT Units Alarm 활성화 여부

mqtt_ua_list

Uint8 Arrary

O

MQTT Units Alarm 활성화 목록

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"gwpid":"1234567890AABBCCDD",

"pc":"03EF0103ABCDEFGH123456ABC…",

"sn":"1609123456",

"lid":"010000040A0000002F000000ED",

"ip":"192.168.2.97",

"tport": 8080,

"mqtt_report": 300,

"mqtt_df_enable":"enable"

}

}

 

비고

 

 

2.5.5 게이트웨이 기본정보 변경


 게이트웨이의 위치정보와 게이트웨이가 접속할 관제서버 접속정보, 게이트웨이가 관리하는 디바이스의 위치정보를 설정하기 위한 API이다.
관제서버 정보(MS IP, Port)를 제공하지 못하는 경우에는 디바이스 정보 목록 속성을 제공하여야 한다.

HTTP Request
 

URI

{base_url}/gwinfo

Method

PATCH

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

lid

Hex(28)

M

게이트웨이 위치주소

ms_addr

String

O

관제서버 IP 주소 또는 도메인

ms_port

UInt16

O

관제서버 포트 번호

bk_addr

String

O

MQTT 브로커 IP 주소 또는 도메인

bk_port

Uint16

O

MQTT 브로커 포트 번호

mqtt_report

Uint32

O

MQTT Report 주기

mqtt_df_enable

String(6~7)

O

게이트웨이 MQTT 오류 알림 활성화 여부

- 하위 디바이스 전체

mqtt_ua_enable

String(6~7)

O

MQTT 부속장치 알림 활성화 여부

mqtt_ua_list

Uint8 Array

O

MQTT 부속장치 알림 활성화 목록

Example

{

    "lid":"010000040A0000002F000000ED",

"ms_addr":"192.168.2.97",

"ms_port": 8080,

"mqtt_report": 300,

"bk_addr":"192.168.2.87",

"bk_port":8883,

"mqtt_df_enable":"enable",

"mqtt_ua_enable":"enable",

"mqtt_ua_list":[1,2,3]

}

 

비고

 

 
 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

"result_msg":"Changed"

}

 

비고

 

 

2.5.6 게이트웨이 수용능력 조회

 게이트웨이의 수용능력(cap) 정보를 조회하기 위한 API이다.
 게이트웨이 수용능력 정보에는 디바이스 수용능력(dcap), 그룹 수용능력(gcap), 장면 수용능력(scap)이 있다.

 

 
HTTP Request
 

URI

{base_url}/cap

Method

GET

Header

Content-Type: application/json

비고

- 객체 속성 필터 사용시: {base_url}?attrs=cap

 
 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

dcap

Object

M

디바이스 수용능력 정보 객체

maxd

Uint16

M

연결 가능한 디바이스 개수

connd

Uint16

M

연결중인 디바이스 개수

gcap

Object

M

그룹 수용능력 정보 객체

maxg

Uint16

M

지원 가능한 그룹 개수

usedg

Uint16

M

사용중인 그룹 개수

scap

Object

M

장면 수용능력 정보 객체

maxs

Uint16

M

지원 가능한 장면 개수

useds

Uint16

M

사용중인 장면 개수

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

         "dcap": {

"maxd": 1024,

"connd": 200

},

"gcap": {

"maxg": 256,

"usedg":12

},

"scap": {

"maxs": 256,

"useds": 4

}

}

}

 

비고

 

 
2.5.7 게이트웨이 자원 동기화 버전 조회

 게이트웨이의 부속장치(units), 디바이스(devices), 그룹(groups), 장면(scenes)에 대한 동기화 버전(sync)을 조회하는 API이다.
 
 동기화 버전 정보는 각 자원(units, devices, groups, scenes)의 생성, 등록 또는 삭제되는 경우에만 업데이트 된다. 즉, 부속장치, 디바이스, 그룹, 장면의 개별 설정 정보가 변경되는 경우에는 업데이트 되지 않는다.
 
HTTP Request
 

URI

{base_url}/sync

Method

GET

Header

Content-Type: application/json

비고

- 객체 속성 필터 사용시: {base_url}?attrs=sync

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

units_sync

String(20)

CM

게이트웨이 부속장치 동기화 버전 정보

- 조건: 부속장치가 있는 경우

devices_sync

String(20)

M

디바이스 동기화 버전 정보

groups_sync

String(20)

M

그룹 동기화 버전 정보

scenes_sync

String(20)

M

장면 동기화 버전 정보

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"units_sync":"2023-01-17T17:13:40Z",

"devices_sync":"2023-01-17T17:13:40Z ",

"groups_sync":"2023-01-17T17:13:40Z ",

"scenes_sync":"2023-01-17T17:13:40Z "

}

}

 

비고

 

 
2.5.8 게이트웨이 재시작

 게이트웨이 재시작 API는 사용자 입력장치(UD3), 설치시험기(TS3) 또는 관제서버(MS)가 게이트웨이를 재시작 하기위한 게이트웨이 API이다.
 
HTTP Request
 

URI

{base_url}/restart

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

delay

Uint16

O

게이트웨이 재시작 지연 시간(s)

Example

{

"delay": 1

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

"result_msg":"Success"

}

   

 

비고

 

 
 

2.5.9 게이트웨이 공장초기화


 게이트웨이 공장초기화 API는 게이트웨이를 모든 설정을 공장초기화 하기위한 게이트웨이 API이다. 


 공장초기화가 수행되면 게이트웨이의 모든 속성은 기본값으로 변경되거나 삭제되며 저장된 사용자 입력장치, 설치시험기, 디바이스, 그룹, 장면 정보등이 삭제된다. 게이트웨이 재설정이 가능한 사용자 입력장치(UD3) 또는 설치시험기(TS3)에 의해서만 사용되어야하며 MS에 의해 사용될 경우 관제서버(MS)와의 연결이 끊어질 수 있다.

 

HTTP Request

 

URI

{base_url}/reset

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

gwpid

Hex(18)

M

게이트웨이 물리주소

delay

Uint16

O

게이트웨이 재시작 지연 시간

Example

{

"gwpid":"1234567890AABBCCDD",

"delay": 1

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

비고

 

 
2.5.10 게이트웨이 부속장치 전체 정보 조회

 게이트웨이 부속장치 전체 정보 조회 API는 게이트웨이에 연결된 부속장치(분전함 문, 분전함 전원, 릴레이 등)에 대한 전체 정보를 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/units

Method

GET

비고

 

 
 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

게이트웨이 부속장치 동기화 버전

units

Object Array

M

게이트웨이 부속장치 목록

unid

Uint16

M

부속장치 논리주소

utype

Uint8

M

부속장치 종류

active

String

M

부속장치 동작 여부

event_value

Uint8

M

부속장치 상태 정보

mqtt_ue_enable

String

M

MQTT 부속장치 Event 활성화 여부

relay_onoff

String

CM

릴레이 상태정보

- 조건: utype=2(릴레이)

did_list

Uint16 Array

CM

릴레이에 연결된 디바이스 논리주소 목록

- 조건: utype=2(릴레이)

gid_list

Uint16 Array

CM

릴레이에 연결된 그룹 논리주소 목록

- 조건: utype=2(릴레이)

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":"2023-01-17T17:13:40Z",

"units": [

{

"unid": 0,

"utype": 0,

"active":"enable",

"event_value": 0,

"mqtt_ue_enable":"enable"

        },

{

"unid": 1,

"utype": 2,

"active":"enable",

"event_value": 0,

"mqtt_ue_enable":"enable"

"relay_onoff":"on",

"did_list": [1, 2, 3, 4, 5],

"gid_list":[]

        }

]

}

}

 

비고

 

 
2.5.11 게이트웨이 부속장치 목록 조회

 게이트웨이의 부속장치(분전함 문, 분전함 전원, 릴레이 등) 목록을 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/units?attr=unid&attr=utype

Method

GET

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

게이트웨이 부속장치 동기화 버전

units

Object Array

M

게이트웨이 부속장치 목록

unid

Uint16

M

부속장치 논리주소

utype

Uint8

M

부속장치 종류

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":"2023-01-17T17:13:40Z",

"units": [

{

"unid": 0,

"utype": 0

        },

{

"unid": 1,

"utype": 2

        }

]

}

}

 

비고

 

 
 
2.5.12 게이트웨이 부속장치 개별 정보 조회

 게이트웨이의 특정 부속장치(분전함 문, 분전함 전원, 릴레이 등)를 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/units/{unid}

Method

GET

URI Path

Parameter

항목

타입(길이)

내용

unid

Uint

부속장치 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

unid

Uint

M

부속장치 논리주소

utype

Uint8

M

부속장치 종류

active

String(6~7)

M

부속장치 동작 여부

event_value

Uint8

M

부속장치 상태 정보

mqtt_ue_enable

String

M

MQTT Units Event 활성화 여부

relay_onoff

String

CM

릴레이 상태정보 (event_value로 조회)

- 조건: utype=2(릴레이)

did_list

Uint16 Array

CM

릴레이에 연결된 디바이스 논리주소 목록

- 조건: utype=2(릴레이)

gid_list

Uint16 Array

CM

릴레이에 연결된 그룹 논리주소 목록

- 조건: utype=2(릴레이)

Example 1

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"unid": 0,

"utype": 0,

"active":"enable",

"event_value": 0,

"mqtt_ue_enable":"enable"

}

}

 

Example 2

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"unid": 2,

"utype": 2,

"active":"enable",

"event_value": 1,

"mqtt_ue_enable":"enable",

"relay_onoff":"on",

"did_list": [1, 2],

"gid_list":[]

}

}

utype 이 2인 경우(relay장치)

비고

 

 
2.5.13 게이트웨이 부속장치 설정정보 변경

 게이트웨이의 특정 부속장치(분전함 문, 분전함 전원, 릴레이 등)를 설정정보를 변경하는 API이다.
 
HTTP Request
 

URI

{base_url}/units/{unid}

Method

PUT/PATCH

Header

Content-Type: application/json

URI Path

Parameter

항목

타입(길이)

내용

unid

Uint

부속장치 논리주소

Body

항목

타입(길이)

C

내용

active

String(6~7)

O

부속장치 동작 여부

mqtt_ue_enable

String

O

MQTT Units Event 활성화 여부

Example 1

{

"active":"enable",

"mqtt_ue_enable":"enable"

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 
2.5.14 게이트웨이 부속장치 전체 릴레이 제어

 게이트웨이에 연결된 모든 릴레이 부속장치를 제어하는 API이다.
 릴레이 부속장치 개별 제어는 게이트웨이 부속장치 설정정보 변경 API를 사용한다.
 
HTTP Request
 

URI

{base_url}/units?utype=2

Method

PATCH

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

relay_onoff

String

M

릴레이 상태정보

Example 1

{

"relay_onoff":"on"

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

 

 

 

 

2.6 사용자 입력장치 API

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3)를 위해 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.


 UD3 사용자 입력장치에는 게이트웨이로부터 디바이스, 그룹, 장면 등의 정보를 조회하여 대부분의 제어 기능을 제공할 수 있는 스마트폰, 스마트패드, 월패드 등의 스마트 조명 제어 앱과 디바이스, 그룹, 장면 등의 정보 설정이 필요한 스마트 스위치 등이 있다. 사용자 입력장치 API는 스마트 조명 제어 앱을 위한 API이다.

 

2.6.1 사용자 입력장치 전체정보 조회


사용자 입력장치 전체정보 조회 API는 게이트웨이로부터 게이트웨이에 등록된 사용자 입력장치 전체 정보를 조회하는 API이다.

 

HTTP Request
 

URI

{base_url}/controllers

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

controllers

Object Array

M

사용자 입력장치 정보 목록

cid

Uint16

M

사용자 입력장치 논리주소

cinfo

Object

M

사용자 입력장치 기본정보 객체

cpid

Hex(18)

M

사용자 입력장치 물리주소

pc

Hex(62)

M

사용자 입력장치 제품 코드

sn

String(10)

M

사용자 입력장치 일련번호

lid

Hex(28)

M

사용자 입력장치 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String(7)

O

사용자 입력장치 이름

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"controllers": [

{

"cid": 1,

"cinfo": {

"cpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0",

"lpv":"1.0.0"

}

},

{

"cid": 2,

"cinfo": {

"cpid":"1234567890AABBCCDE",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123457",

"lid":"0001000000000000000000",

"lpv":"1.0.0"

}

}

]

}

}

 

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 
2.6.2 사용자 입력장치 정보 생성

 사용자 입력장치 정보 생성 API는 게이트웨이에 연결을 원하는 사용자 입력장치가 자신의 기본정보로 게이트웨이에 사용자 입력장치 자원 생성을 요청하고 사용자 입력장치 논리주소(CID)를 발급받는 API이다.
 
 사용자 입력장치 정보 생성 요청을 받은 게이트웨이는 사용자 입력장치 논리주소(CID)를 중복없이 발급하여야 한다. 사용자 입력장치 생성 메시지의 사용자 입력장치 논리주소(CID)는 미할당(0)이어야 한다.
 

 

HTTP Request
 

URI

{base_url}/controllers

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

cid

Uint16

M

사용자 입력장치 논리주소

cinfo

Object

M

사용자 입력장치 기본정보

cpid

Hex(18)

M

사용자 입력장치 물리주소

pc

Hex(62)

M

사용자 입력장치 제품 코드

sn

String(10)

M

사용자 입력장치 일련번호

lid

Hex(28)

M

사용자 입력장치 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String

O

사용자 입력장치 이름

Example

{

"cid": 0,

"cinfo": {

"cpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0",

"lpv":"1.0.0"

}

}

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

cid

Uint16

M

사용자 입력장치 논리주소

Example

{

    "result_code":"2001",

    "result_msg":"Created",

    "result_data": {

"cid":4

}

}

 

비고

 

 
2.6.3 사용자 입력장치 연결

 사용자 입력장치 연결 API는 컨트롤로 논리주소를 할당받은 사용자 입력장치(UD3)가 게이트웨이에 연결을 요청하는 API이다. 게이트웨이는 연결 요청하는 사용자 입력장치의 CID, PID 및 LID를 바탕으로 연결 수락 또는 거절할 수 있다.
 
HTTP Request
 

URI

{base_url}/controllers/connect

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

cid

Uint16

M

사용자 입력장치 논리주소

cpid

Hex(18)

M

사용자 입력장치 물리주소

lid

Hex(28)

M

사용자 입력장치 위치주소

Example

{

"cid":4,

"cpid":"1234567890AABBCCDD",

    "lid":"0000000000000000000000000000"

}

연결 수락 응답

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

Example

{

    "result_code":"5104",

    "result_msg":"요청이 거절되었습니다."

}

연결 거절 응답

비고

 

 

2.6.4 사용자 입력장치 기본정보 조회


 사용자 입력장치 기본정보 조회 API는 사용자 입력장치의 기본정보 조회를 요청하기위한 API이다.

 

HTTP Request
 

URI

{base_url}/controllers/{cid}/cinfo

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

cid

Uint16

사용자 입력장치 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

cid

Uint16

M

사용자 입력장치 논리주소

cpid

Hex(18)

M

사용자 입력장치 물리주소

pc

Hex(62)

M

사용자 입력장치 제품 코드

sn

String(10)

M

사용자 입력장치 일련번호

lid

Hex(28)

M

사용자 입력장치 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String

O

사용자 입력장치 이름

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"cid": 2,

"cpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE0000…",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0",

"lpv":"1.0.0"

}

}

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 

2.6.5 사용자 입력장치 기본정보 변경

 

 사용자 입력장치 기본정보 변경 API는 사용자 입력장치가 게이트웨이에 사용자 입력장치의 기본정보 변경을 요청하기위한 API이다.

 

 사용자 입력장치 기본정보에는 사용자 입력장치 물리주소(cpid), 제품코드(pc), 일련번호(sn), 프로파일 버전(bpv, lpv) 정보가 있다.  변경 가능한 기본정보에는 스마트 게이트웨이, 사용자 입력장치, 관제서버 등을 통하여 설정되는 논리주소(cid), 위치주소(lid), 이름(name)이 있다.


 요청 메시지에 포함된 사용자 입력장치의 물리주소(cpid)는 요청 메시지를 수신한 사용자 입력장치가 수신자(변경 대상)가 자신인지 확인용으로만 사용되며 변경할 수 없는 속성이다.

 
 
HTTP Request
 

URI

{base_url}/controllers/{cid}/cinfo

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

cid

Uint16

사용자 입력장치 논리주소

Body

항목

타입(길이)

C

내용

cpid

Hex(18)

M

사용자 입력장치 물리주소

cid

Uint16

O

사용자 입력장치 논리주소

lid

Hex(28)

O

사용자 입력장치 위치주소

name

String

O

사용자 입력장치 이름

Example

{

"cpid":"1234567890AABBCCDD",

"lid":"010000040A0000002F000000ED"

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 
2.6.6 사용자 입력장치 삭제

 사용자 입력장치 삭제 API는 게이트웨이에 연결된 사용자 입력장치 정보 삭제를 요청하기위한 API이다.
 
HTTP Request
 

URI

{base_url}/controllers/{cid}?cpid={cpid}&lid={lid}

Method

DELETE

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

cid

Uint16

사용자 입력장치 논리주소

cpid

Hex(18)

사용자 입력장치 물리주소

lid

Hex(28)

사용자 입력장치 위치주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2002",

    "result_msg":"Deleted"

}

 

비고

 

 

 

2.7 설치시험기 API

 본 절에서는 B-SLP를 지원하는 설치시험기(TS3)를 위해 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 TS3 설치시험기는 디바이스의 위치를 확인하여 디바이스의 위치주소를 할당하거나 게이트웨이연결에 필요한 정보를 제공하는 등 디바이스 설치를 위한 기능과 조명 제어, 그룹 제어, 장면 제어 등을 통하여 조명의 기능을 시험하는 등의 기능을 제공하는 장치이다.

 

2.7.1 설치시험기 전체정보 조회


 게이트웨이로부터 게이트웨이에 등록된 설치시험기 전체 정보를 조회하는 API이다.

 

HTTP Request
 

URI

{base_url}/testers

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

testers

Object Array

M

설치시험기 정보 목록

tid

Uint16

M

설치시험기 논리주소

tinfo

Object

M

설치시험기 기본정보 객체

tpid

Hex(18)

M

설치시험기 물리주소

pc

Hex(62)

M

설치시험기 제품 코드

sn

String(10)

M

설치시험기 일련번호

lid

Hex(28)

M

설치시험기 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String(7)

O

설치시험기 이름

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"testers": [

{

"tid": 1,

"tinfo": {

"tpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0"

}

},

{

"tid": 2,

"tinfo": {

"tpid":"1234567890AABBCCDE",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123457",

"lid":"0001000000000000000000",

"bpv":"1.0.0"

}

}

]

}

}

 

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 
2.7.2 설치시험기 정보 생성

 게이트웨이에 연결을 원하는 설치시험기가 자신의 기본정보로 게이트웨이에 설치시험기 자원 생성을 요청하고 설치시험기 논리주소(TID)를 발급받는 API이다.
 
 설치시험기 정보 생성 요청을 받은 게이트웨이는 설치시험기 논리주소(TID)를 중복없이 발급하여야 한다. 설치시험기 생성 메시지의 설치시험기 논리주소(TID)는 미할당(0)이어야 한다.
 
HTTP Request
 

URI

{base_url}/testers

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

tid

Uint16

M

설치시험기 논리주소

tinfo

Object

M

설치시험기 기본정보

tpid

Hex(18)

M

설치시험기 물리주소

pc

Hex(62)

M

설치시험기 제품 코드

sn

String(10)

M

설치시험기 일련번호

lid

Hex(28)

M

설치시험기 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String

O

설치시험기 이름

Example

{

"tid": 0,

"tinfo": {

"tpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000320032000A2A02C02B41040018 0889000003050000",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0"

}

}

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

tid

Uint16

M

설치시험기 논리주소

Example

{

    "result_code":"2001",

    "result_msg":"Created",

    "result_data": {

"tid":4

}

}

 

비고

 

 
2.7.3 설치시험기 연결

 설치시험기 연결 API는 설치시험기 논리주소를 할당받은 설치시험기(TS3)가 게이트웨이에 연결을 요청하는 API이다. 게이트웨이는 연결 요청하는 설치시험기의 CID, PID 및 LID를 바탕으로 연결 수락 또는 거절할 수 있다.
 
HTTP Request
 

URI

{base_url}/testers/connect

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

tid

Uint16

M

설치시험기 논리주소

tpid

Hex(18)

M

설치시험기 물리주소

lid

Hex(28)

M

설치시험기 위치주소

Example

{

"tid":4,

"tpid":"1234567890AABBCCDD",

    "lid":"0000000000000000000000000000"

}

 

비고

 

 
HTTP Response
 
 

 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

연결 수락 응답

Example

{

    "result_code":"5104",

    "result_msg":"요청이 거절되었습니다."

}

연결 거절 응답

비고

 

 
2.7.4 설치시험기 기본정보 조회

 설치시험기 기본정보 조회 API는 설치시험기의 기본정보 조회를 요청하기위한 API이다.
 
HTTP Request
 

URI

{base_url}/testers/{tid}/tinfo

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

tid

Uint16

설치시험기 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

tid

Uint16

M

설치시험기 논리주소

tpid

Hex(18)

M

설치시험기 물리주소

pc

Hex(62)

M

설치시험기 제품 코드

sn

String(10)

M

설치시험기 일련번호

lid

Hex(28)

M

설치시험기 위치주소

bpv

String

CM

B-SLP 프로파일 버전

- 조건: B-SLP를 지원하는 경우

lpv

String

CM

L-SLP 버전

- 조건: L-SLP를 지원하는 경우

name

String

O

설치시험기 이름

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"tid": 2,

"tpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000320032000A2A02C02B4104001808890000030500 00",

"sn":"1609123456",

"lid":"0001000000000000000000",

"bpv":"1.0.0"

}

}

 

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 

2.7.5 설치시험기 기본정보 변경


 설치시험기 기본정보 변경 API는 설치시험기가 게이트웨이에 설치시험기의 기본정보 변경을 요청하기위한 API이다.

 설치시험기 기본정보에는 설치시험기 물리주소(tpid), 제품코드(pc), 일련번호(sn), 프로파일 버전(bpv, lpv) 정보가 있다.

 변경 가능한 기본정보에는 스마트 게이트웨이, 사용자 입력장치, 관제서버 등을 통하여 설정되는 논리주소(tid), 위치주소(lid), 이름(name)이 있다.

요청 메시지에 포함된 설치시험기의 물리주소(tpid)는 요청 메시지를 수신한 사용자 입력장치가 수신자(변경 대상)가 자신인지 확인용으로만 사용되며 변경할 수 없는 속성이다.

 

 

HTTP Request
 

URI

{base_url}/testers/{tid}/tinfo

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

tid

Uint16

설치시험기 논리주소

Body

항목

타입(길이)

C

내용

tpid

Hex(18)

M

설치시험기 물리주소

tid

Uint16

O

설치시험기 논리주소

lid

Hex(28)

O

설치시험기 위치주소

name

String

O

설치시험기 이름

Example

{

"tpid":"1234567890AABBCCDD",

    "lid":"010000040A0000002F000000ED"

}

LID 변경

비고

- B-SLP와 L-SLP 프로파일중 최소 하나 이상을 제공하여야 함

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 
2.7.6 설치시험기 삭제

 설치시험기 삭제 API는 게이트웨이에 연결된 설치시험기 정보 삭제를 요청하기위한 API이다.
 
HTTP Request
 

URI

{base_url}/testers/{tid}?tpid={tpid}&lid={lid}

Method

DELETE

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

tid

Uint16

설치시험기 논리주소

tpid

Hex(18)

설치시험기 물리주소

lid

Hex(28)

설치시험기 위치주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2002",

    "result_msg":"Deleted"

}

 

비고

 

2.8 디바이스 공통 API

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3), 설치시험기(TS3), 관제서버(MS) 등을 위해 게이트웨이에 소속된 조명/센서 디바이스의 공통 자원에 대한 정보 제공 및 설정을 위하여 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 

2.8.1 전체 디바이스 목록 조회


 전체 디바이스 목록 조회 API는 게이트웨이에 등록된 모든 디바이스의 목록 정보를 조회하는 API이다.

 

2.8.1.1 디바이스 전체정보 목록 조회


 디바이스 전체정보 목록 조회 API는 게이트웨이에 등록된 모든 디바이스의 모든 정보를 포함하는 목록 정보를 조회하는 API이다.

 

HTTP Request
 

URI

{base_url}/devices

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

dinfo

Object

M

디바이스 기본정보 객체

dpid

Hex(18)

M

디바이스 물리주소

pc

Hex(62)

M

제품 코드

sn

String(10)

O

일련번호

lid

Hex(28)

M

위치주소

lpv

String

O

L-SLP 프로파일 버전

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ip

String

O

IP 주소

uport

Uint16

O

L-SLP UDP 포트번호

ct

String(2)

O

디바이스 지원 Content Format

name

String

O

디바이스 이름

dfault

Uint8

CM

디바이스 상태 정보

- 조건: 정상 상태(0)가 아닌 경우

fslist

Object Array

CM

디바이스 세부 기기장애 정보

- 조건: 디바이스 상태 정보(dfault)를 제공하고 그 값이 기기장애(2), 통신불능&기기장애(3)인 경우

mid

Uint8

M

모듈 논리주소

- 모듈 논리주소가 없는 경우: 0

fcode

Hex(8)

M

세부장애 비트 표시 정보

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

cap

Object

M

디바이스 수용능력 객체

mcap

Object

M

모듈 수용능력 정보

in_maxm

Uint8

CM

디바이스 내부 연결 가능 모듈 개수

- 조건: 내부 모듈 기능이 있는 경우

in_usedm

Uint8

CM

디바이스 내부 연결 사용중인 모듈 개수

- 조건: 내부 연결 모듈이 있는 경우

ex_maxm

Uint8

CM

디바이스 외부 연결 가능 모듈 개수

- 조건: 외부 모듈 기능이 있는 경우

ex_usedm

Uint8

CM

디바이스 외부 연결 사용중인 모듈 개수

- 조건: 외부 연결 모듈이 있는 경우

gcap

Object

M

그룹 수용능력 정보

maxg

Uint8

M

지원 가능한 그룹 개수

usedg

Uint8

M

사용중인 그룹 개수

scap

Object

M

장면 수용능력 정보

maxs

Uint8

M

지원 가능한 장면 개수

useds

Uint8

M

사용중인 장면 개수

modules

Object Array

M

디바이스의 모듈정보 객체 목록

- 조명, 센서 모듈만 포함

- 통신 모듈(mid=1) 정보는 개별 조회

mid

Uint8

M

모듈 논리주소

minfo

Object

M

모듈 기본정보

mclass

String(1)

M

모듈 종류

mtype

Uint8

M

모듈 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

light

Object

CM

조명 상태정보

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 조명(l)인 경우

onoff

String

M

조명 점소등 상태

level

Uint8

CM

디밍 레벨

- 조건: 조명이 점등(on) 상태인 경우

- 소등(off) 상태인 경우 "0"이어야 함

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

lightconfig

Object

CM

조명 설정정보

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 조명(l)인 경우

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

on_dtime

Uint16

O

점등대기시간

off_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

소등(off) 소등되는 레벨

level_rate

Uint8

M

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

M

점등시 마지막 조명 상태정보 복구

onconfig

Object

M

조명 점등 상태정보 객체

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

sensor

Object

CM

센서 기본정보

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 센서(s)인 경우

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype value}

M

현재 센서 출력 데이터

gid_list

Uint16 Array

CM

그룹 논리주소 목록

scid_list

Uint16 Array

CM

장면 논리주소 목록

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"sync":"2023-01-17T17:13:40Z"

"devices": [

{

"did": 2,

"dinfo": {

"dpid":"1234567890AABBCCDD",

"pc":"03EF01…",

"sn":"1609123456",

"lid":"0000000000000000000000000000",

"dfault": 0,

"mqtt_df_enable":"enable"

},

"cap": {

"mcap": {

    "in_maxm": 1,

    "in_usedm": 1

},

"gcap": {

    "maxg": 1,

    "usedg": 1

},

"scap": {

    "maxg": 1,

    "usedg": 1

}

},

"modules": [

 {

"mid": 2,

"minfo":{

"mclass":"l"

"mtype": 3,

"form":"in"

},

"light": {

"onoff":"on",

"level":100

},

"lightconfig": {

"onoff_tt":60,

"level_rate":80,

"last_light":”enable”,

"onconfig":{

"onlevel":90

}

}

 }

],

"gid_list":[1,2,4,7],

"scid_list":[2,4,5]

}

{

"did": 3,

"dinfo": {

"dpid":"1234567890AABBCCDD",

"pc":"03EF01….",

"sn":"1609123457",

"lid":"0000000000000000000000000000",

"dfault": 2,

"fslist": [

{

"mid":2,

"fcode":"40000000"

}

] ,

"mqtt_df_enable":"disable"

},

"cap": {

"mcap": {

    "in_maxm": 1,

    "in_usedm": 1

},

"gcap": {

    "maxg": 1,

    "usedg": 1

},

"scap": {

    "maxg": 1,

    "usedg": 1

}

},

"modules": [

 {

"mid": 2,

"minfo":{

"mclass":"s"

"mtype": 5,

"form":"in"

},

"sensor": {

"active":"enable",

"opmode":100,

"mperiod":1,

"rperiod":50,

"vtype":"string",

"value":"n"

}

 }

],

"gid_list":[3],

"scid_list":[]

      ]

}

}

 

 

2.8.1.2 디바이스 객체속성 목록 조회


 디바이스 객체속성 목록 조회 API는 디바이스 전체정보 목록 조회 API는 게이트웨이에 등록된 모든 디바이스의 전체 디바이스 전체정보중 URI Path에 하위 속성의 객체를 포함하는 Filtering을 통하여 하위 속성 객체만을 조회하는 API이다.

 {attributes}에는 디바이스 기본정보(dinfo), 수용능력(cap), 모듈정보(modules) 객체가 올수 있다. 지정된 객체 하위에 소속된 속성과 객체는 속성 필터(attr)와 객체 필터(attrs)를 추가로 사용할 수 있다.

 

HTTP Request
 

URI

{base_url}/devices/{attributes}

Method

GET

Header

Content-Type: application/json

비고

- 디바이스 전체정보 목록 조회 API에서 속성 필터 사용으로 동일한 호출 가능

: {base_url}/device?attrs={attributes}

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

{attribues}

-

-

attributes 객체

{attributes member}

-

-

attributes 객체의 멤버 속성

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"devices": [

{

"did": 2,

"{attributes}" {

"{attributes member}":{value},

}

},

{

"did": 3,

"{attributes}" {

"{attributes member}":{value},

}

}

]

}

}

 

 

비고

 

 
 아래는 게이트웨이에 등록된 디바이스의 정보 중에서 기본정보(dinfo)만을 요청하기 위한 디바이스 객체속성 목록 조회의 요청 메시지와 응답 메시지의 예이다.
 
HTTP Request Example
 

URI

{base_url}/devices/dinfo

Method

GET

Header

Content-Type: application/json

비고

- 디바이스 전체정보 목록 조회 API에서 "dinfo" 쿼리 사용으로 동일한 호출 가능

: {base_url}/device?attrs=dinfo

 
HTTP Response Example
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

dinfo

Object

CM

디바이스 기본정보 객체

dpid

Hex(18)

M

디바이스 물리주소

pc

Hex(62)

M

제품 코드

sn

String(10)

M

일련번호

lid

Hex(28)

M

위치주소

lpv

String

M

L-SLP 프로파일 버전

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ip

String

O

IP 주소

uport

Uint16

O

L-SLP UDP 포트번호

name

String

O

디바이스 이름

dfault

Uint8

O

디바이스 상태 정보

fslist

Object Array

CM

디바이스 세부 기기장애 정보

- 조건: 디바이스 상태 정보(dfault)를 제공하고 그 값이 기기장애(2), 통신불능&기기장애(3)인 경우

mid

Uint8

M

모듈 논리주소

- 모듈 논리주소가 없는 경우: 0

fcode

Hex(8)

M

세부장애 비트 표시 정보

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"devices": [{

"did": 2,

"dinfo" {

"dpid":"1234567890AABBCCDD",

"pc":"03EF01100…",

"sn":"1609123456",

"lid":"000200003CFE00006734000012C0",

"lpv":"1.0.0",

"dfault": 0,

"mqtt_df_enable":"enable"

}

},

{

"did": 3,

"dinfo" {

"dpid":"1234567890AABBCCDD",

"pc":"03EF011000…",

"sn":"1609123457",

"lid":"0000000000000000000000000000",

"lpv":"1.0.0",

"dfault": 2,

"fslist": [

{

"mid":2,

"fcode":"80000000"

}

] ,

"mqtt_df_enable":"disable"

}

},

    …

    ]

  }

}

 

비고

 

 
 아래는 디바이스의 기본정보(dinfo)중에서 위치주소(lid)가 미할당(0)인 디바이스 목록을 접근하기 위한 예시이다. 설치시험기는 위치주소가 미할당된 디바이스 목록만 조회하여 위치주소를 할당하는데 활용할 수 있다.
 
HTTP Request Example
 

URI

{base_url}/devices/dinfo?lid=0

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response Example
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

dinfo

Object

CM

디바이스 기본정보 객체

dpid

Hex(18)

M

디바이스 물리주소

pc

Hex(62)

M

제품 코드

sn

String(10)

M

일련번호

lid

Hex(28)

M

위치주소

lpv

String

M

L-SLP 프로파일 버전

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ip

String

O

IP 주소

uport

Uint16

O

L-SLP UDP 포트번호

name

String

O

디바이스 이름

dfault

Uint8

O

디바이스 상태 정보

fslist

Object Array

CM

디바이스 세부 기기장애 정보

- 조건: 디바이스 상태 정보(dfault)를 제공하고 그 값이 기기장애(2), 통신불능&기기장애(3)인 경우

mid

Uint8

M

모듈 논리주소

- 모듈 논리주소가 없는 경우: 0

fcode

Hex(8)

M

세부장애 비트 표시 정보

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"devices": [

{

"did": 3,

"dinfo" {

"dpid":"1234567890AABBCCDD",

"pc":"03EF011000…",

"sn":"1609123457",

"lid":"0000000000000000000000000000",

"lpv":"1.0.0",

"dfault": 2,

"fslist": [

{

"mid":2,

"fcode":"80000000"

}

] ,

"mqtt_df_enable":"disable"

}

},

    …

    ]

  }

}

 

비고

 

 
2.8.1.3 디바이스 논리주소 목록 조회

 디바이스 논리주소 목록 조회 API는 게이트웨이에 등록된 모든 디바이스의 전체 디바이스 논리주소만의 목록을 조회하는 API이다. 
 
HTTP Request
 

URI

{base_url}/devices?attr=did

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response

 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

did_list

Uint16 Array

M

디바이스 논리주소 목록

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"did_list": [1,2,3,4,5,6,7,8,9,10]

  }

}

 

비고

 

 
2.8.1.4 위치주소 미할당 디바이스 논리주소 목록 조회

 위치주소 미할당 디바이스 논리주소 목록 조회 API는 전체 디바이스 중에서 위치주소(LID)가 미할당(0) 상태인 디바이스의 논리주소만의 목록을 조회하는 API이다. 
 
HTTP Request
 

URI

{base_url}/devices?attr=did&lid=0

Method

GET

Header

Content-Type: application/json

비고

 

 
HTTP Response

 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

디바이스 동기화 버전

did_list

Uint16 Array

M

디바이스 논리주소 목록

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"did_list": [9,10]

  }

}

 

비고

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

2.8.2 디바이스 식별


 게이트웨이에 연결된 조명 및 센서 디바이스의 위치를 확인하는 API이다. 


 사용자(UD3, TS3)는 특정 디바이스에 본 API를 호출하여 해당 디바이스의 조명 또는 동작표시용 LED를 점멸하도록 요청할 수 있다.

 

HTTP Request
 

URI

{base_url}/devices/{did}/identify

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

blink

Uint8(1~3)

M

점멸 횟수

Example

{

"blink":5

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

비고

 

 
2.8.2.2 디바이스 모듈 식별

 디바이스의 모듈 단위의 식별을 위해 점멸을 요청하는 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/identify?mid={mid}

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

blink

Uint8(1~3)

M

점멸 횟수

Example

{

"blink":5

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

비고

 

 
2.8.2.3 디바이스 그룹 식별

 디바이스 그룹 단위의 식별을 위해 점멸을 요청하는 API이다. 해당 그룹에 소속된 모든 디바이스는 점멸하여야 한다.
 
HTTP Request
 

URI

{broad_url}/devices/65535/identify?gid={gid}

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

Body

항목

타입(길이)

C

내용

blink

Uint8(1~3)

M

점멸 횟수

Example

{

"blink":5

}

 

비고

 

 
HTTP Response

 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

 
2.8.3 디바이스 전체 정보 조회

 게이트웨이로부터 특정 디바이스의 기본/모듈/센서(인지, 조도, 온도)에 대한 전체정보를 한번에조회하는 API이다.
 
 UD, TS에 대한 정보는 제공하지 않는다.
 
HTTP Request
 

URI

{base_url}/devices/{did}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint

디바이스 논리주소

비고

 

 

 
HTTP Response

 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

did

Uint16

M

디바이스 논리주소

dinfo

Object

M

디바이스 기본정보 객체

dpid

Hex(18)

M

디바이스 물리주소

pc

Hex(62)

M

제품 코드

sn

String(10)

O

일련번호

lid

Hex(28)

M

위치주소

lpv

String

O

L-SLP 프로파일 버전

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ip

String

O

IP 주소

uport

Uint16

O

L-SLP UDP 포트번호

ct

String(2)

O

디바이스 지원 Content Format

name

String

O

디바이스 이름

dfault

Uint8

O

디바이스 상태 정보

fslist

Object Array

CM

디바이스 세부 기기장애 정보

- 조건: 디바이스 상태 정보(dfault)를 제공하고 그 값이 기기장애(2), 통신불능&기기장애(3)인 경우

mid

Uint8

M

모듈 논리주소

- 모듈 논리주소가 없는 경우: 0

fcode

Hex(8)

M

세부장애 비트 표시 정보

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

cap

Object

M

디바이스 수용능력 객체

{cap attributes}

-

-

디바이스 수용능력 객체 속성

modules

Object Array

CM

디바이스의 모듈정보 객체 목록

- 조명, 센서 모듈만 포함

- 통신 모듈(mid=1) 정보는 개별 조회

mid

Uint8

M

모듈 논리주소

minfo

Object

M

모듈 기본정보

mclass

String(1)

M

모듈 종류

mtype

Uint8

M

모듈 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

light

Object

CM

조명 상태정보 객체

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 조명(l)인 경우

{light attributes}

-

-

조명 상태정보 객체 속성

lightconfig

Object

CM

조명 설정정보 객체

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 조명(l)인 경우

{lightconfig attributes}

-

-

조명 설정정보 객체 속성

sensor

Object

CM

센서 기본정보

- 조건: 모듈 기본정보(minfo)의 모듈 종류(mclass)가 센서(s)인 경우

{sensor attributes}

-

-

센서 기본정보 객체 속성

gid_list

Uint16 Array

CM

그룹 논리주소 목록

scid_list

Uint16 Array

CM

장면 논리주소 목록

Example

{

"result_code":"2000",

"result_msg":"Success",

"result_data": {

"sync":"2023-01-17T17:13:40Z"

"dinfo": {

"did": 2,

"dpid":"1234567890AABBCCDD",

"pc":"03EF011000FFFE000000…",

"sn":"1609123456",

"lid":"0000000001000000000000000000",

"dfault": 0,

"mqtt_df_enable":"enable"

},

"cap": {

"gcap": {

  "maxg": 1,

  "usedg": 1

},

"scap": {

  "maxg": 1,

  "usedg": 1

}

},

"modules": [

{

"mid":2,

"minfo":{

"mclass":"l",

"mtype": 0,

"form":"in",

}

"light": {

"onoff":"on",

"level":100

}

"lightconfig": {

"onoff_tt":100,

"off_level":0

"onconfig": {

"onlevel":100

}

}

},

{

"mid": 3,

"minfo":{

"mclass":"s",

"mtype": 5,

"form":"in"

},

"sensor": {

"active":"enable",

"opmode":100,

"mperiod":1,

"rperiod":50,

"vtype":"string",

"value":"n"

}

],

gid_list":[1,2,3],

scid_list:[1]

}

}

 

비고

 

 
 
 
2.8.4 디바이스 기본정보 조회
 
HTTP Request
 

URI

{base_url}/devices/{did}/dinfo

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint

디바이스 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

dpid

Hex(18)

M

디바이스 물리주소

pc

Hex(62)

M

디바이스 제품 코드

sn

String(10)

O

디바이스 일련번호

lid

Hex(28)

M

디바이스 위치주소

lpv

String

O

L-SLP 프로파일 버전

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ip

String

O

IP 주소

uport

Uint16

O

L-SLP UDP 포트번호

ct

String(2)

O

디바이스 지원 Content Format

name

String

O

디바이스 이름

dfault

Uint8

O

디바이스 상태 정보

fslist

Object Array

CM

디바이스 세부 기기장애 정보

- 조건: 디바이스 상태 정보(dfault)를 제공하고 그 값이 기기장애(2), 통신불능&기기장애(3)인 경우

mid

Uint8

M

모듈 논리주소

- 모듈 논리주소가 없는 경우: 0

fcode

Hex(8)

M

세부장애 비트 표시 정보

mqtt_df_enable

String

O

게이트웨이 MQTT Fault Alarm 활성화 여부

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"dpid":"1234567890AABBCCDD",

"pc":"03EF0110…",

"sn":"1609123456",

"lid":"0001000000000000000000000000",

"dfault": 0,

"mqtt_df_enable":"enable",

}

}

 

비고

 

 

2.8.5 디바이스 기본정보 변경

 디바이스 개별 모듈 기본정보 설정 API는 디바이스의 기본정보중 변경 가능한 정보를 설정하는 API이다.

 디바이스 기본정보에는 디바이스 물리주소(dpid), 제품코드(pc), 일련번호(sn), 프로파일 버전(bpv, lpv) 정보가 있다.

 변경 가능한 기본정보에는 스마트 게이트웨이, 사용자 입력장치, 관제서버 등을 통하여 설정되는 논리주소(did), 위치주소(lid), 지연시간(delay)이 있다.

 요청 메시지에 포함된 디바이스의 물리주소(dpid)는 요청 메시지를 수신한 디바이스가 수신자(변경 대상)가 자신인지 확인용으로만 사용되며 변경할 수 없는 속성이다.

 

HTTP Request
 

URI

{base_url}/devices/{did}/dinfo

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint

디바이스 논리주소

Body

항목

타입(길이)

C

내용

did

Uint

O

디바이스 논리주소

dpid

Hex(18)

M

디바이스 물리주소

lid

Hex(28)

O

디바이스 위치주소

delay

Uint16

O

디바이스 재시작 또는 공장초기화 지연 시간

ct

String(2)

O

디바이스 지원 Content Format

name

String

O

디바이스 이름

Example 1

{

"did": 2,

"dpid":"1234567890AABBCCDD"

}

디바이스 논리주소 변경

Example 2

{

"dpid":"1234567890AABBCCDD",

"lid":"0001000000000000000000000000"

}

디바이스 위치주소 변경

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example 1

{

    "result_code":"2004",

    "result_msg":"Changed"

}

디바이스 변경 확인

Example 2

{

    "result_code":"2004",

    "result_msg":"Changed"

}

디바이스 변경 확인

비고

 

 
2.8.6 디바이스 수용능력 조회
 
HTTP Request
 

URI

{base_url}/devices/{did}/cap

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint

디바이스 논리주소

비고

 

 
HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

mcap

Object

M

모듈 수용능력 정보

in_maxm

Uint8

O

디바이스 내부 연결 가능 모듈 개수

in_usedm

Uint8

CM

디바이스 내부 연결 사용중인 모듈 개수

- 조건: 내부 연결 모듈이 있는 경우

ex_maxm

Uint8

O

디바이스 외부 연결 가능 모듈 개수

ex_usedm

Uint8

CM

디바이스 외부 연결 사용중인 모듈 개수

- 조건: 외부 연결 모듈이 있는 경우

gcap

Object

O

그룹 수용능력 정보

maxg

Uint8

M

지원 가능한 그룹 개수

usedg

Uint8

M

사용중인 그룹 개수

scap

Object

O

장면 수용능력 정보

maxs

Uint8

M

지원 가능한 장면 개수

useds

Uint8

M

사용중인 장면 개수

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"mcap": {

     "in_maxm": 5,

     "in_used_cap": 3,

     "ex_maxm": 5,

     "ex_used_cap": 0

},

"gcap": {

    "maxg": 1,

    "usedg": 1

},

"scap": {

    "maxg": 1,

    "usedg": 1

}

}

}

 

비교

-

 

 
2.8.7 디바이스 전체 모듈 전체정보 조회

 디바이스 전체 모듈 전체정보 조회 API는 디바이스의 모든 모듈에 대한 전체정보를 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/modules

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

modules

Object Array

M

모듈 정보

- 조명, 센서 모듈만 포함

- 통신 모듈(mid=1) 정보는 개별 조회

mid

Uint8

M

모듈 논리주소

minfo

Object

M

모듈 기본정보

mclass

String(1)

M

모듈 종류

mtype

Uint8

M

모듈 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

light

Object

CM

조명 상태정보

- 조건: 모듈 종류(mclass)가 조명(l)인 경우

onoff

String

M

조명 점등(on)/소등(off) 상태

level

Uint8

CM

디밍 레벨

- 조건: 조명이 점등(on) 상태인 경우

- 소등(off) 상태인 경우 "0"이어야 함

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

lightconfig

Object

CM

조명 설정정보 객체

- 조건: 모듈 종류(mclass)가 조명(l)인 경우

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

off_dtime

Uint16

O

점등대기시간

on_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

Off 이름령어 시 점등되는 레벨

level_rate

Uint8

M

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

M

점등시 마지막 조명 상태정보 복구

onconfig

Object

M

조명 점등 상태정보 객체

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

sensor

Object

CM

센서 공통정보 객체

- 조건: 모듈 종류(mclass)가 센서(s)인 경우

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype value}

M

현재 센서 출력 데이터

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

  "modules": [

{

"mid":2,

"minfo":{

"mclass":"l",

"mtype": 0,

"form":"in",

}

"light": {

"onoff":"on",

"level":100

}

"lightconfig": {

"onoff_tt":100,

"off_level":0,

"level_rate":80,

"last_light":”enable”,

"onconfig":{

"onlevel":90

}

}

},

{

"mid": 3,

"minfo":{

"mclass":"s",

"mtype": 5,

"form":"in"

},

"sensor": {

"active":"enable",

"opmode":100,

"mperiod":1,

"rperiod":50,

"vtype":"string",

"value":"n"

}

]

}

}

 

비고

 

 
 
2.8.8 디바이스 전체 모듈 기본정보 목록 조회

 디바이스의 모든 모듈에 대한 기본정보를 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/modules/minfo

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

modules

Object Array

M

모듈 객체 목록

- 조명, 센서 모듈만 포함

- 통신 모듈(mid=1) 정보는 개별 조회

mid

Uint8

M

모듈 논리주소

minfo

Object

M

모듈 기본정보 객체

mclass

String(1)

M

모듈의 종류

mtype

Uint8

M

모듈의 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

Example 1

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

"modules": [

{

"mid": 2,

"minfo": {

"mclass":"l"

"mtype": 3,

"form":"in"

}

},

{

"mid": 3,

"minfo": {

"mclass":"s"

"mtype": 1,

"form":"ex"

}

}

       ]

}

}

{base_url}/devices/{did}/modules/minfo

Example 2

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

" modules": [

{

"mid": 2,

"minfo": {

"mclass":"l"

"mtype": 3,

"form":"in"

}

}

       ]

}

}

{base_url}/devices/{did}/modules/minfo?mclass=l

Example 3

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

" modules": [

{

"mid": 3,

"minfo": {

"mclass":"s"

"mtype": 1,

"form":"ex"

}

}

       ]

}

}

{base_url}/devices/{did}/modules/minfo?mclass=s

비고

 

 
2.8.9 디바이스 개별 모듈 전체정보 조회

 디바이스 개별 모듈 전체정보 조회 API는 디바이스의 모듈단위로 전체정보를 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/modules/{mid}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint16

모듈 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

mid

Uint8

M

모듈 논리주소

minfo

Object

M

모듈 기본정보

mclass

String(1)

M

모듈 종류

mtype

Uint8

M

모듈 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

light

Object

CM

조명 상태정보

- 조건: 모듈 종류(mclass)가 조명(l)인 경우

onoff

String

M

조명 점등(on)/소등(off) 상태

level

Uint8

CM

디밍 레벨

- 조건: 조명이 점등(on) 상태인 경우

- 소등(off) 상태인 경우 "0"이어야 함

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

tt

Uint16

O

동작소요시간(ms)

lightconfig

Object

CM

조명 설정정보

- 조건: 모듈 종류(mclass)가 조명(l)인 경우

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

off_dtime

Uint16

O

점등대기시간

on_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

Off 이름령어 시 점등되는 레벨

level_rate

Uint8

M

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

M

점등시 마지막 조명 상태정보 복구

onconfig

Object

M

조명 점등 상태정보

{onconfig attributes}

-

-

조명 점등 상태정보 객체 하위 속성

sensor

Object

CM

센서 공통

- 조건: 모듈 종류(mclass)가 센서(s)인 경우

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 상태정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

Object

M

센서별 Value형식의 속성

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

"mid": 2,

"minfo":{

"mclass":"l",

"mtype": 3,

"form":"in"

},

"light": {

        "onoff":"on"

};

"lightconfig": {

"level_rate":100,

"last_light":"enable",

"onconfig": {

"onlevel":100

}

}

}

}

 

비고

 

 
2.8.10 디바이스 개별 모듈 기본정보 조회

 디바이스 개별 모듈 기본정보 조회 API는 디바이스의 모듈단위로 기본정보만을 조회하는 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/modules/{mid}/minfo

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

mid

Uint8

M

모듈 논리주소

mclass

String(1)

M

모듈의 종류

mtype

Uint8

M

모듈의 상세 종류

form

String(2)

O

모듈 장착 방식

mqtt_mf_enable

String

O

모듈단위 MQTT Fault Alarm 활성화 여부

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {  

"mid": 2,

   "mclass":"l"

   "mtype": 3,

   "form":"in",

}

}

 

비고

 

 
 

2.8.11 디바이스 삭제


 디바이스 삭제 API는 게이트웨이에 연결된 특정 디바이스의 모든 정보를 게이트웨이에서삭제를 요청하는 API이다.


 본 API를 요청받은 게이트웨이는 해당 디바이스의 모든 정보를 삭제한다. 해당 디바이스가 작동중인 경우에는 게이트웨이 연결 정보가 유지되므로 해당 디바이스의 요청이 계속 올수 있으며 이에 대해서 게이트웨이는 오류를 응답한다. 작동중인 디바이스에 대한 삭제의 경우 디바이스 공장초기화와 병행하는 것을 권장한다.


 본 API는 운용중이지 않는 디바이스에 대한 삭제를 위하여 사용할 것을 권장한다.


 디바이스 삭제에 성공한 게이트웨이는 디바이스가 삭제된 시간으로 수정된 새로운 디바이스 동기화 버전 정보를 응답 메시지에 제공하여야 한다.

 

HTTP Request
 

URI

{base_url}/devices/{did}?dpid={dpid}

Method

DELETE

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

dpid

Hex(18)

디바이스 물리주소

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 디바이스 동기화 버전

Example

{

    "result_code":"2002",

    "result_msg":"Deleted",

    "result_data": {

"sync":"2023-01-17T17:13:40Z"

}

}

 

비고

 

 
2.8.12 디바이스 재시작

 게이트웨이를 통하여 디바이스를 재시작 하기위한 게이트웨이 API이다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/restart

Method

POST

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

delay

Uint16

O

디바이스 재시작 지연 시간

Example

{

"delay": 1

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

비고

 

 
2.8.13 디바이스 공장초기화

 게이트웨이를 통하여 디바이스를 초기설정값(공장설정값)으로 되돌리기 위한 게이트웨이 API이다. 

 디바이스 공장초기화를 요청받은 게이트웨이는 해당 디바이스에도 디바이스 L-SLP API의 디바이스 공장초기화를 요청하여야 한다. 디바이스 공장초기화 요청 후 해당 디바이스의 모든 정보를 삭제할 수 있다.

 디바이스 재설정이 가능한 경우에만 사용되어야하며 그렇지 않을 경우 게이트웨이와 디바이이스간 연결이 끊어져 재연결이 안될 수 있다.
 
HTTP Request
 

URI

{base_url}/devices/{did}/reset

Method

POST

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

dpid

Hex(18)

M

디바이스 물리주소

delay

Uint16

O

디바이스 재시작 지연 시간

Example

{

"dpid":"1234567890AABBCCDD",

"delay":10

}

 

비고

 

 
HTTP Response
 

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2000",

    "result_msg":"Success"

}

 

비고

 

 

 

2.9 조명 디바이스 API

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3), 설치시험기(TS3), 관제서버(MS) 등을 위해 게이트웨이에 소속된 조명 디바이스의 자원에 대한 정보 제공 및 제어를 위하여 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 

2.9.1 조명 상태정보 조회

 

디바이스 조명 상태정보 조회 API는 게이트웨이를 통하여 디바이스의 조명 상태정보를 조회하는 API이다.

 

2.9.1.1 전체 조명 모듈

 

디바이스의 모든 조명 모듈의 상태정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/light

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

light_list

Object Array

M

조명 상태정보

mid

Uint8

M

모듈 논리주소

onoff

Uint8

M

조명기기의 현재 점등(on)/소등(off) 상태 정보

level

Uint16

M

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint8

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Float(3,2)

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Uint8

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"light_list": [

{

     "mid":2,

"onoff":"on",

    "level": 100,

    "colortemp": 5000

},

{

     "mid":3,

"onoff":"off",

"level": 0

}

]

}

}

 

비고

- 소등상태(off)일 때 조명 밝기(level)은 0"이어야 함

 

디바이스 조명 상태정보 조회 API는 게이트웨이를 통하여 디바이스의 조명 상태정보를 조회하는 API이다.

 

2.9.1.2 개별 조명 모듈

 

디바이스의 모든 조명 모듈의 상태정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/light

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

light_list

Object Array

M

조명 상태정보

mid

Uint8

M

모듈 논리주소

onoff

Uint8

M

조명기기의 현재 점등(on)/소등(off) 상태 정보

level

Uint16

M

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint8

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Float(3,2)

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Uint8

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"light_list": [

{

     "mid":2,

"onoff":"on",

    "level": 100,

    "colortemp": 5000

},

{

     "mid":3,

"onoff":"off",

"level": 0

}

]

}

}

 

비고

- 소등상태(off)일 때 조명 밝기(level)은 0"이어야 함

 

2.9.2 조명 상태정보 변경(조명제어)

조명 상태정보 변경 API는 제어 기능을 제공하는 디바이스에서 게이트웨이를 통하여 조명의 상태정보를 변경하기위한 API이다.

 

2.9.2.1 전체 조명 모듈 동일 제어

 디바이스의 모든 조명 모듈을 동일한 상태로 변경을 요청하는 API이다.

 

 조명 점등/소등 상태(onoff)가 소등(off)인 경우 동작변환시간(tt)을 제외한 속성들은 포함되지 않아야 한다.

 

 조명 밝기(디밍 레벨) 제어 범위가 0~100인 사용자 입력장치에서 밝기를 0으로 제어한 경우에는 onoff=off로 요청하여야 한다.

 

 동작소요시간(tt)은 "onoff"가 포함된 경우에는 "onoff_tt"로 동작하고, 색상이 변경될때는 "color_tt"로 동작하는 등 메시지에 포함된 속성의 동작에 소요되는 시간을 나타낸다. 단독으로 사용할 수 없으며 onoff, level, colortemp, color 관련 명령이 포함되어 있어야 한다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/light

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

onoff

String

O

조명 점등(on)/소등(off) 상태

level

Uint8

O

조명 밝기(디밍 레벨)

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

tt

Uint16

O

동작소요시간(ms)

Example 1

{

"onoff":"on",

"colortemp": 5000,

"tt": 100

}

 

Example 2

{

"onoff":"on",

"hue": 359,

"sat": 100,

"bright": 100,

"tt": 100

}

 

Example 3

{

"level": 80,

"x": 0.22,

"y": 0.48

}

 

Example 4

{

"onoff":"off"

}

 

비고

 

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

2.9.2.2 전체 조명 모듈 개별 제어

 

디바이스의 모든 조명 모듈의 개별 상태정보를 변경하는 API이다.

 

 조명 점등/소등 상태(onoff)가 소등(off)인 경우 동작변환시간(tt)을 제외한 속성들은 포함되지 않아야 한다.

 

 조명 밝기(디밍 레벨) 제어 범위가 0~100인 사용자 입력장치에서 밝기를 0으로 제어한 경우에는 onoff=off로 요청하여야 한다.

 

 동작소요시간(tt)은 "onoff"가 포함된 경우에는 "onoff_tt"로 동작하고, 색상이 변경될때는 "color_tt"로 동작하는 등 메시지에 포함된 속성의 동작에 소요되는 시간을 나타낸다. 단독으로 사용할 수 없으며 onoff, level, colortemp, color 관련 명령이 포함되어 있어야 한다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/light

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

light_list

Object Array

M

조명 상태정보

mid

Uint8

M

모듈 논리주소

onoff

String

O

조명 점등(on)/소등(off)  상태

level

Uint8

O

디밍 레벨

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

tt

Uint16

O

동작소요시간(ms)

Example 1

{

"light_list": [

{

"mid":2,

"onoff":"on",

"colortemp": 5000,

"tt": 100

},

{

"mid":3,

"onoff":"off",

"tt": 100

}

 

]

}

 

Example 2

{

"light_list": [

{

"mid":2,

"onoff":"on",

"hue": 359,

"sat": 100,

"bright": 100,

"tt": 100

},

{

"mid":3,

"level": 50,

"hue": 359,

"sat": 100,

"bright": 100,

"tt": 100

}

 

]

}

 

Example 3

{

"light_list": [

{

"mid":2,

"onoff":"on",

"x": 0.22,

"y": 0.48

},

{

"mid":3,

"level": 50,

"x": 0.32,

"y": 0.58

},

]

}

 

Example 4

{

"light_list": [

{

"mid":2,

"onoff":"on",

"colortemp": 5000,

"tt": 100

},

{

"mid":3,

"onoff":"off"

}

]

}

 

비고

 

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 
 

2.9.2.3 개별 조명 모듈 제어

 

디바이스의 개별 조명 모듈에 대한 상태정보를 변경하는 API이다.

 

 조명 점등/소등 상태(onoff)가 소등(off)인 경우 동작변환시간(tt)을 제외한 속성들은 포함되지 않아야 한다.

조명 밝기(디밍 레벨) 제어 범위가 0~100인 사용자 입력장치에서 밝기를 0으로 제어한 경우에는 onoff=off로 요청하여야 한다.

 

 동작소요시간(tt)은 "onoff"가 포함된 경우에는 "onoff_tt"로 동작하고, 색상이 변경될때는 "color_tt"로 동작하는 등 메시지에 포함된 속성의 동작에 소요되는 시간을 나타낸다. 단독으로 사용할 수 없으며 onoff, level, colortemp, color 관련 명령이 포함되어 있어야 한다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/light

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

onoff

Uint8

O

조명기기의 현재 점등(on)/소등(off)  상태 정보

level

Uint16

O

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint8

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Float(3,2)

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Uint8

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

tt

Uint16

O

동작소요시간(ms)

Example 1

{

"onoff":"on",

"colortemp": 5000,

"tt": 100

}

 

Example 2

{

"onoff":"on",

"hue": 359,

"sat": 100,

"bright": 100,

"tt": 100

}

 

Example 3

{

"level": 80,

"x": 0.22,

"y": 0.48

}

 

Example 4

{

"onoff":"off"

}

 

비고

 

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

2.9.3 조명 설정정보 조회

 조명 설정정보 조회 API는 게이트웨이를 통하여 디바이스의 조명 설정정보를 조회하는 API이다.

 

 조명 설정정보 조회 API에서는 하위의 조명 점등 상태정보(onconfig) 객체는 제외한다. 조명 점등 상태정보(onconfig) 조회는 별도의 API를 사용한다.

 

2.9.3.1 전체 조명 모듈

디바이스의 모든 조명 모듈의 설정정보를 조회하는 API이다.
 
  • HTTP Request

URI

{base_url}/devices/{did}/lightconfig

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

lightconfig_list

Object Array

M

조명 설정정보

mid

Uint8

M

모듈 논리주소

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간(on hold time)

off_htime

Uint16

O

소등유지시간(off hold time)

on_dtime

Uint16

O

점등대기시간(on delay time)

off_dtime

Uint16

O

소등대기시간(off delay time)

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

소등(off) 명령 시 소등되는 밝기

level_rate

Uint8

M

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

M

점등시 마지막 조명 상태정보 복구

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

   "lightconfig_list": [

{

"mid":2,

"onoff_tt": 0,

"dimup_tt": 0,

"dimdn_tt": 0,

"on_htime": 65535,

"off_htime": 65535,

"on_dtime": 0,

"off_dtime": 0,

"color_tt": 0,

"offlevel": 20,

"level_rate":80,

"rperiod":60,

"last_light":"enable"

},

{

"mid":3,

"onoff_tt": 10,

"dimup_tt": 10,

"dimdn_tt": 10,

"on_htime": 65535,

"off_htime": 65535,

"on_dtime": 0,

"off_dtime": 0,

"color_tt": 0,

"offlevel": 20,

"level_rate":80,

"rperiod":60,

"last_light":"enable"

}

}

]

}

}

 

비고

 

 

2.9.3.2 개별 조명 모듈


디바이스의 개별 조명 모듈에 대한 설정정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/lightconfig

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

비고

 

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

mid

Uint8

M

모듈 논리주소

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간(on hold time)

off_htime

Uint16

O

소등유지시간(off hold time)

on_dtime

Uint16

O

점등대기시간(on delay time)

off_dtime

Uint16

O

소등대기시간(off delay time)

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

소등(off) 명령 시 소등되는 밝기

level_rate

Uint8

M

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

M

점등시 마지막 조명 상태정보 복구

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

   "mid":2,

"onoff_tt": 0,

"dimup_tt": 0,

"dimdn_tt": 0,

"on_htime": 65535,

"off_htime": 65535,

"on_dtime": 0,

"off_dtime": 0,

"color_tt": 0,

"offlevel": 20,

"level_rate":80,

"rperiod":60,

"last_light":"enable"

}

}

 

비고

 

 

2.9.4.1 전체 조명 모듈 동일 변경


 디바이스의 모든 조명 모듈을 동일한 설정으로 변경을 요청하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/lightconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간(on hold time)

off_htime

Uint16

O

소등유지시간(off hold time)

on_dtime

Uint16

O

점등대기시간(on delay time)

off_dtime

Uint16

O

소등대기시간(off delay time)

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

소등(off) 명령 시 소등되는 밝기

level_rate

Uint8

O

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

O

점등시 마지막 조명 상태정보 복구

Example

{

"onoff_tt": 10,

"dimup_tt": 0,

"dimdn_tt": 0,

"on_htime": 65535,

"off_htime": 65535,

"on_dtime": 0,

"off_dtime": 0,

"level_rate":80,

"last_light":"enable"

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

 

결과 코드

result_msg

String

 

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

2.9.4.2 전체 조명 모듈 개별 변경


 디바이스의 모든 조명 모듈의 개별 설정정보를 변경하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/lightconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

lightconfig_list

Object Array

CM

조명 설정 정보

mid

Uint8

CM

모듈 논리주소

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

on_dtime

Uint16

O

점등대기시간

off_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

소등(off) 명령 시 소등되는 밝기

level_rate

Uint8

O

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

O

점등시 마지막 조명 상태정보 복구

Example

{

"lightconfig_list": [

{

"mid":2,

"level_rate":90

},

{

"mid":3,

"level_rate":80

}

]

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

 

결과 코드

result_msg

String

 

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

 

2.9.4.3 개별 조명 모듈 변경


 디바이스의 개별 조명 모듈에 대한 설정정보를 변경하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/lightconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

on_dtime

Uint16

O

점등대기시간

off_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

Off 이름령어 시 점등되는 레벨

level_rate

Uint8

O

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

O

점등시 마지막 조명 상태정보 복구

Example

{

"onoff_tt": 10,

"offlevel": 20,

"level_rate":80,

"rperiod":60,

"last_light":"disable"

 

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

 

결과 코드

result_msg

String

 

결과 메시지

Example

{

    "result_code":"2004",

    "result_msg":"Changed"

}

 

비고

 

 

 

2.9.5 조명 점등 상태정보 조회


 조명 점등 상태정보 조회 API는 조명 기능을 제공하는 디바이스가 전원 공급에 의해 점등되거나 또는 마지막 조명 설정정보의 조명 상태정보 복구(lightconfig/last_light) 속성이 비활성화인 상태에서 조명 점등 명령을 받은 경우에 조명이 제공해야하는 점등 조명상태(onconfig) 속성을 조회하는 API이다. 

 

2.9.5.1 전체 조명 모듈


 디바이스의 모든 조명 모듈의 점등 상태정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/onconfig

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

비고

 

         
 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

onconfig_list

Object Array

M

조명 설정정보 목록

mid

Uint8

M

모듈 논리주소

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

CM

점등시 조명 상관 색온도

hue

Uint16

CM

점등시 조명 색상(HSB)의 색상

sat

Uint8

CM

점등시 조명 색상(HSB)의 채도

bright

Uint8

CM

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

CM

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

CM

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

CM

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"result_code":"2000",

"result_msg":"Success"

"result_data": {

"onconfig_list":[{

"mid": 2,

"onlevel":100,

"colortemp": 5000

},

{

"mid": 3,

"onlevel":80,

"colortemp": 5000

}

]

}

}

 

Example 2

{

"result_code":"2000",

"result_msg":"Success"

"result_data":  {

"onconfig_list":[{

"mid": 2,

"onlevel":100,

"r": 255,

"g": 255,

"b": 255

},

{

"mid": 3,

"onlevel":0

}

]

}

}

 

Example 3

{

"result_code":"2000",

"result_msg":"Success"

"result_data": {

"onconfig_list":[{

"mid": 2,

"onlevel":100,

"x": 0.22,

"y": 0.48

},

{

"mid": 3,

"onlevel":0

}

]

}

 

}

 

비고

 

 

 

 

2.9.5.2 개별 조명 모듈


 디바이스의 개별 조명 모듈에 대한 점등 상태정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/onconfig

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

비고

 

         
 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"result_code":"2000",

"result_msg":"Success"

"result_data": {

"onlevel":90,

"colortemp": 5000

}

}

 

Example 2

{

"result_code":"2000",

"result_msg":"Success"

"result_data": {

"onlevel":90,

"r": 255,

"g": 255,

"b": 255

}

}

 

Example 3

{

"result_code":"2000",

"result_msg":"Success"

"result_data": {

"onlevel":90,

"x": 0.22,

"y": 0.48

}

}

 

비고

 

 

2.9.6 조명 점등 상태정보 변경

 조명 점등 상태정보 조회 API는 조명 기능을 제공하는 디바이스의 조명의 전원에 의한 점등시 조명이 제공해야하는 점등 조명상태(onconfig) 속성을 변경하는 API이다.


 조명 점등 상태정보 변경 API는 PUT과 PATCH 메소드 모두를 사용할 수있다. PUT 메소드를 사용하는 경우 메시지에는 모든 속성을 포함하여야 한다. 포함되지 않은 속성이 있는 경우 해당 속성은 기본값으로 설정하여야 한다. PATCH 메소드를 사용하는 경우 메시지에 포함된 속성만 변경하여야 한다.

 

2.9.6.1 전체 조명 모듈 동일 변경


 디바이스의 전체 조명 모듈에 대한 점등 상태정보를 동일하게 변경하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/onconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

onlevel

Uint8

O

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"onlevel": 80

}

 

Example 2

{

"colortemp": 5000

}

 

Example 3

{

"r": 255,

"g": 255,

"b": 255

}

 

Example 4

{

"x": 0.22,

"y": 0.48

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

비고

 

 
2.9.6.2 전체 조명 모듈 개별 변경

 디바이스의 전체 조명 모듈에 대한 점등 상태정보를 개별로 변경하는 API이다.
 
  • HTTP Request

URI

{base_url}/devices/{did}/onconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

onconfig_list

Object Array

M

조명 상태정보

mid

Uint8

M

모듈 논리주소

onlevel

Uint8

O

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"onconfig_list": [

{

"mid":2,

"onlevel":80,

"colortemp": 5000

},

{

"mid":3,

"onlevel":100,

"colortemp": 6000

}

]

}

 

Example 2

{

"onconfig_list": [

{

"mid":2,

"r": 255,

"g": 0,

"b": 0

},

{

"mid":3,

"r": 0,

"g": 255,

"b": 0

}

]}

 

Example 3

{

"onconfig_list": [

{

"mid":2,

"x": 0.22,

"y": 0.38

},

{

"mid":3,

"x": 0.22,

"y": 0.58

}

]

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

비고

 

 

2.9.6.3 개별 조명 모듈 변경


 디바이스의 개별 조명 모듈에 대한 점등 상태정보를 변경하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/onconfig

Method

PUT/PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

onlevel

Uint8

O

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

O

점등시 조명 상관 색온도

hue

Uint16

O

점등시 조명 색상(HSB)의 색상

sat

Uint8

O

점등시 조명 색상(HSB)의 채도

bright

Uint8

O

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

 

"onlevel":80,

"colortemp": 5000

}

 

Example 2

{

"r": 255,

"g": 255,

"b": 255

}

 

Example 3

{

"x": 0.22,

"y": 0.48

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

비고

 

 

2.9.7 현재 조명상태의 점등 상태정보 저장


 디바이스 현재 조명상태의 점등 상태정보 저장 API는 조명 기능을 제공하는 디바이스의 조명의 전원에 의한 점등시 조명이 제공해야하는 점등 조명상태(onconfig) 속성을 현재의 조명상태로 저장할 것을 요청하는 API이다.

 

2.9.7.1 전체 조명 모듈 저장


 디바이스의 전체 조명 모듈에 대한 점등 상태정보를 현재 상태로 변경하는 API이다. 지원하는 모든 점등 상태정보 속성에 대하여 응답하여야 한다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/onconfig

Method

PUT

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

onconfig_list

Object Array

M

조명 상태정보

mid

Uint8

M

모듈 논리주소

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

CM

점등시 조명 상관 색온도

hue

Uint16

CM

점등시 조명 색상(HSB)의 색상

sat

Uint8

CM

점등시 조명 색상(HSB)의 채도

bright

Uint8

CM

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

CM

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

CM

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

CM

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"result_code":"2004",

"result_msg":"Changed",

"result_data": {

"onconfig_list":[

{

"mid": 2,

"onlevel":80,

"colortemp": 5000

},

{

"mid": 3,

"onlevel":80,

"colortemp": 5000

}

]

}

}

상관 색온도를 지원하는 조명 디바이스의 응답

비고

 

 
2.9.7.2 개별 조명 모듈 저장

 디바이스의 개별 조명 모듈에 대한 점등 상태정보를 모듈의 현재 상태로 변경하는 API이다. 지원하는 모든 점등 상태정보 속성에 대하여 응답하여야 한다.
 
  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/onconfig

Method

PUT

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

onlevel

Uint8

M

점등시 조명 밝기(디밍 레벨)

colortemp

Uint16

CM

점등시 조명 상관 색온도

hue

Uint16

CM

점등시 조명 색상(HSB)의 색상

sat

Uint8

CM

점등시 조명 색상(HSB)의 채도

bright

Uint8

CM

점등시 조명 색상(HSB)의 휘도

x

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

CM

점등시 조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

CM

점등시 조명 색상(R, G, B)의 적색(Red)

g

Uint8

CM

점등시 조명 색상(R, G, B)의 녹색(Green)

b

Uint8

CM

점등시 조명 색상(R, G, B)의 청색(Blue)

Example 1

{

"result_code":"2004",

"result_msg":"Changed",

"result_data": {

"onlevel":80,

"colortemp": 5000

}

}

상관 색온도를 지원하는 조명 디바이스 모듈의 응답

비고

 

2.10 센서 디바이스 API

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3), 설치시험기(TS3), 관제서버(MS) 등을 위해 게이트웨이에 소속된 센서 디바이스의 자원에 대한 정보 제공 및 제어를 위하여 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 

2.10.1 센서 공통 설정정보 조회

 센서 공통 설정정보 조회 API는 디바이스의 모든 센서 모듈에 대한 공통 설정정보를 조회하는 API이다.

 센서 디바이스에는 인지센서, 문열림 감지 센서 등 센싱 상태를 제공하는 Status형과 온도센서, 습도센서, 조도센서 등 상태값을 제공하는 Value형으로 구분한다. 본 API에서는 센서형과 무관하게 공통인 속성을 제공한다.

 

2.10.1.1 전체 센서 모듈 조회

 

디바이스의 전체 센서 모듈에 대한 설정정보를 조회하는 API이다.

 

전체 센서 모듈에 대한 설정정보 조회에서는 센서 설정정보중 공통인 속성에 대해서만 응답한다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/sensor

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sensor_list

Object Array

M

조명 설정 정보

mid

Uint8

M

모듈 논리주소

mtype

Uint8

M

모듈 상세 종류

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype}

M

센서 출력

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sensor_list": [

{

"mid":2,

"mtype":5,

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"string",

"value":"p"

},

{

"mid":3,

"mtype":1

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"uint16",

"value":27

}

]

}

}

인지센서(mtype=5)와 온도(mtype=1)센서로 구성된 디바이스

 

2.10.1.2 특정 센서타입 조회

 

복수개의 모듈로 구성된 디바이스에서 특정 센서 타입 모듈의 공통 설정정보를 일괄 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/sensor?mtype={mtype}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mtype

Uint8

디바이스 모듈 상세종류

Example URI

{base_url}/devices/65535/sensor?mtype=1

게이트웨이에 연결된 모든 온도센서(1) 설정정보 조회

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sensor_list

Object Array

M

조명 설정 정보

did

Uint16

CM

디바이스 논리주소

- 조건: 요청 URL의 디바이스 논리주소(did) 값이 전체 디바이스(65535)인 경우

mid

Uint8

M

모듈 논리주소

mtype

Uint8

M

모듈 상세 종류

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype}

M

센서 출력

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"sensor_list": [

{

"did":1,

"mid":2,

"mtype":1;

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"uint16",

"value":27

},

{

"did":2,

"mid":2,

"mtype":1;

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"uint16",

"value":27

},

]

}

}

게이트웨이에 연결된 모든 온도센서(1) 설정정보 조회 응답

 

 

2.10.2 센서 개별 설정정보 조회

센서 개별 설정정보 조회 API는 디바이스의 개별 센서 모듈에 대한 모든 설정정보를 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/sensor

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

비고

 

 

1.1.1.1 Status형 응답

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype}

M

센서 출력

klist

String Array

M

제어 키 목록

control_list

Object Array

CM

센서 상태별 제어 정보

- 조건: 센서 이벤트 발생시 동작 모드(opmode)가 act 또는 act_notify인 경우

key

String

M

제어 키

scid

Uint16

O

제어 장면 정보

tlist

Object Array

O

제어 대상 정보 객체 목록

light

Object

M

조명 상태정보 객체

{light attributes}

-

-

조명 상태정보 객체의 멤버 속성들

did

Uint16

O

제어 대상 디바이스 논리주소

mid

Uint8

O

제어 대상 디바이스 모듈 논리주소

gid

Uint16

O

제어 대상 그룹 논리주소

{특수 속성}

 

 

센서 종류에 따른 고유 속성

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"string",

"value":"n",

"klist":["p","t","n"],

"control_list": [

  {"key":"p", "scid":2},

  {"key":"t", "scid":3},

  {

"key":"n",

"tlist":[

{

"light":{"onoff":"off"},

"gid":65535

}

]

}

],

"ptime":1000,

"ttime":800

}

}

}

[인지센서 설정정보]

- value(센서 출력) 속성의 데이터 타입(vtype)은 "string"

- 현재 상태(value)는 "n"로 비인지 상태

- 제어 키(klist)는 "p", "t", "n" 가능

- "p" 상태인 경우 장면 2(scid=2) 동작

- "t" 상태인 경우 장면 3(scid=3) 동작

- "n" 상태인 경우 제어 대상 정보 객체 목록(tlist)에 따라 동작

- 인지센서 고유 속성: ptime, ttime

비고

- Status형 센서 모듈의 세부종류별 키 목록과 특수속성은 스마트 조명 속성 규격서 참조

 
 

 2.10.2.2 Value형 응답

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

channel

Unit8

O

센처 출력의 채널 수

vtype

String

M

센서 출력(value)의 데이터 형식

value

{vtype}

M

센서 출력

klist

String Array

M

제어 키 목록

control_list

Object Array

CM

이벤트 발생 시 제어 정보

- 조건: 센서 이벤트 발생시 동작 모드(opmode)가 act 또는 act_notify인 경우

key

String

M

제어 키

scid

Uint16

O

제어 장면 정보

tlist

Object Array

O

제어 대상 정보 객체 목록

light

Object

M

조명 상태정보 객체

{light attributes}

-

-

조명 상태정보 객체의 멤버 속성들

did

Uint16

O

제어 대상 디바이스 논리주소

mid

Uint8

O

제어 대상 디바이스 모듈 논리주소

gid

Uint16

O

제어 대상 그룹 논리주소

high

{type value}

O

High level 값

base

{type value}

O

Base level 값

low

{type value}

O

Low level 값

{특수 속성}

 

 

센서 종류에 따른 고유 속성

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"vtype":"uint16",

"value":654,

"klist":["h","b","l"],

"control_list": [

  {"key":"h", "scid":2},

  {"key":"b", "scid":3},

  {

"key":"l",

"tlist":[

{

"light":{"onoff":"on"},

"gid":65535

}

]

}

],

"high":800,

"base":600,

"low":400,

"aperiod":600

}

}

}

[조도센서 설정정보]

- value(센서 출력) 속성의 데이터 타입(vtype)은 "uint16"

- 현재 조도(value)는 654 lux

- Value형 센서이므로 "h", "b", "l" 제어 키 사용

- "h" 상태인 경우 장면 2(scid=2) 동작

- "b" 상태인 경우 장면 3(scid=3) 동작

- "l" 상태인 경우 제어 대상 정보 객체 목록(tlist)에 따라 동작

- "h" 키 발생 기준: 800 lux 이상

- "b" 키 발생 기준: 600 lux

- "l" 키 발생 기준: 400 lux 이하

- 조도센서 고유 속성: aperiod

비고

- Value형 센서 모듈의 세부종류별 특수속성은 스마트 조명 속성 규격서 참조

- channel이 1 초과이면 센서 출력(value)의 데이터 형식은 array(uint8a, uint16a, floata)이어야 하며 value는 array 형태를 가지며, array에는 channel 수에 해당하는 데이터를 포함하여야 함

 
2.10.3 센서 공통 설정정보 변경

 센서 공통 설정정보 변경 API는 디바이스의 모든 센서 모듈에 대한 공통 설정정보를 변경하는 API이다.
 
2.10.3.1 전체 센서 모듈 동일 변경

 디바이스의 전체 센서 모듈에 대한 공통 설정정보를 동일하게 변경하는 API이다.
 
  • HTTP Request

URI

{base_url}/devices/{did}/sensor

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
2.10.3.2 특정 센서타입 동일 변경

 디바이스의 특정 센서타입의 센서 모듈에 대한 공통 설정정보를 동일하게 변경하는 API이다.
 
  • HTTP Request

URI

{base_url}/devices/{did}/sensor?mtype={mtype}

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mtype

Uint8

디바이스 모듈 상세종류

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60

}

{base_url}/devices/65535/sensor?mtype=5

게이트웨이에 연결된 모든 인지센서(5) 설정정보 변경

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
2.10.4 센서 개별 설정정보 변경

 디바이스의 개별 센서 모듈에 대한 설정정보를 변경하는 API이다.
개별 센서 모듈에 대한 설정정보 변경에서는 해당 모듈의 모든 변경가능한 설정정보를 포함할 수 있다.
 
2.10.4.1 Status형 센서 모듈 변경

 Status형 센서 모듈에 대한 설정정보 변경을 요청하는 API이다.
 
 
  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/sensor

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

control_list

Object Array

M

센서 상태별 제어 정보

key

String

M

제어 키

scid

Uint16

O

제어 장면 정보

tlist

Object Array

O

제어 대상 정보 객체 목록

light

Object

M

조명 상태정보 객체

{light attributes}

-

-

조명 상태정보 객체의 멤버 속성들

did

Uint16

O

제어 대상 디바이스 논리주소

mid

Uint8

O

제어 대상 디바이스 모듈 논리주소

gid

Uint16

O

제어 대상 그룹 논리주소

{특수 속성}

-

O

센서 종류에 따른 고유 속성

- 쓰기가 가능한 속성에 한함

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"control_list": [

{

"key":"p", "scid":2

},

{

"key":"t", "scid":3

},

{

"key":"n",

"tlist":[

{

"light":{"onoff":"off"},

"gid":65535

}

]

}

],

"ptime":1000,

"ttime":800

}

 

비고

- 센서 상태별 제어 정보 객체의 하위 속성중 제어 장면 정보(scid)와 제어 대상 정보 객체 목록(tlist)중 하나의 속성을 포함하고 있어야 함

- Status형 센서 모듈의 세부종류별 키 목록과 특수속성은 스마트 조명 속성 규격서 참조

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
2.10.4.2 Value형 센서 모듈 변경

 Value형 센서 모듈에 대한 설정정보 변경을 요청하는 API이다.
 
 
  • HTTP Request

URI

{base_url}/devices/{did}/modules/{mid}/sensor

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

did

Uint16

디바이스 논리주소

mid

Uint8

모듈 논리주소

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

control_list

Object Array

M

센서 상태별 제어 정보

key

String

M

제어 키

scid

Uint16

O

제어 장면 정보

tlist

Object Array

O

제어 대상 정보 객체 목록

light

Object

M

조명 상태정보 객체

{light attributes}

-

-

조명 상태정보 객체의 멤버 속성들

did

Uint16

O

제어 대상 디바이스 논리주소

mid

Uint8

O

제어 대상 디바이스 모듈 논리주소

gid

Uint16

O

제어 대상 그룹 논리주소

high

{type value}

O

High level 값

base

{type value}

O

Base level 값

low

{type value}

O

Low level 값

{특수 속성}

-

O

센서 종류에 따른 고유 속성

- 쓰기가 가능한 속성에 한함

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60,

"control_list": [

{"key":"h", "scid":2},

{"key":"b", "scid":3},

{

"key":"l",

"tlist":[

{

"light":{"onoff":"off"},

"gid":65535

}

]

}

],

"high":800,

"base":600,

"low":400,

"aperiod":600

}

 

비고

- Value형 센서 모듈의 세부종류별 특수속성은 스마트 조명 속성 규격서 참조

 

 

  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 

2.11 그룹 API

 그룹은 디바이스들을 하나의 논리적 모임으로 묶어 관리하는 개념이다.

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3), 설치시험기(TS3), 관제서버(MS) 등을 위해 게이트웨이에 소속된 조명/센서 디바이스를 그룹으로 생성하여 관리, 제어하기 위한 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 

2.11.1 그룹 생성


 그룹 생성 API는 게이트웨이에 그룹 생성을 요청하고 그룹 논리주소(GID)를 발급받는 API이다. 


 Request 메시지에서 gname이 없는 경우 Response에서 게이트웨이가 임의 할당 가능하다. 


 그룹 생성 API는 UD3, TS3만 사용하며, MS는 MS에서 생성한 그룹을 그룹 등록 API를 통하여 게이트웨이에 등록만 가능하다.


 그룹 생성에 성공한 게이트웨이는 그룹이 생성된 시간으로 수정된 새로운 그룹 동기화 버전 정보를 응답 메시지에 제공하여야 한다.

 

  • HTTP Request

URI

{base_url}/groups

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

 

gname    

String

O

그룹 이름

gmlist    

Object Array

M

그룹 소속 멤버 정보 목록

gmtype

String

M

그룹 멤버 종류

lid

Hex(28)

M

디바이스 위치주소

did

Uint16

M

디바이스 논리주소

mid_list

Uint8 Array

CM

디바이스 모듈 논리주소 목록

Example

{

    "gname":" Group #2"

"gmlist": [

{ "gmtype":"device","lid":"0001000000000000000001", "did": 1},

{ "gmtype":"module","lid":"0001000000000000000002", "did": 3, "mid_list": [2] },

{ "gmtype":"module","lid":"0001000000000000000003", "did": 4, "mid_list": [2, 3]

}

]

}

 

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 그룹 동기화 버전

gid

Uint16

M

그룹 논리주소

Example

{

"result_code":"2001",

"result_msg":"Created",

"result_data": {

"sync":"2023-01-17T17:13:40Z",

"gid": 32

}

}

 

 

2.11.2 그룹 등록


 그룹 등록 API는 관제서버(MS)에서 생성한 그룹 정보를 게이트웨이에 등록을 요청하는 API이다. 


 Request 메시지에서 gname이 없는 경우 게이트웨이에서 임의 할당하여 사용 가능하다. Request 메시지의 그룹 논리주소(GID) 할당은 할당 가능한 범위(1~65534) 내에 있어야 한다. GID가 게이트웨이에 이미 할당된 ID인 경우 게이트웨이는 오류 응답(result_code: 6108)을 보낸다.


 그룹 등록 API는 MS만 사용 가능하다. 


 그룹 등록에 성공한 게이트웨이는 그룹이 등록된 시간으로 수정된 새로운 그룹 동기화 버전 정보를 응답 메시지에 제공하여야 한다.

 

  • HTTP Request

URI

{base_url}/groups

Method

PUT

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

gid

Uint16

M

그룹 논리주소

gname    

String

O

그룹 이름

gmlist    

Object Array

M

그룹 소속 멤버 정보 목록

gmtype

String

M

그룹 멤버 종류

lid

Hex(28)

M

디바이스 위치주소

did

Uint16

M

디바이스 논리주소

mid_list

Uint8 Array

CM

디바이스 모듈 논리주소 목록

- 조건: 그룹 멤버 종류(gmtype)이 모듈(module)인 경우

Example

{

"gid": 49154,

    "gname":" Group #2"

"gmlist": [

{ "gmtype":"device","lid":"0001000000000000000001", "did": 1},

{ "gmtype":"module","lid":"0001000000000000000002", "did": 3, "mid_list": [2] },

{ "gmtype":"module","lid":"0001000000000000000003", "did": 4, "mid_list": [2, 3]

}

]

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 그룹 동기화 버전

Example

{

"result_code":"2004",

"result_msg":"Changed",

"result_data": {

"sync":"2023-01-17T17:13:40Z"

}

}

 

 

 

2.11.3 그룹 목록 조회


 게이트웨이로부터 게이트웨이에 등록된 모든 그룹에 대한 정보를 목록으로 조회하는 API이다.

 

2.11.3.1 그룹 전체정보 목록 조회


 게이트웨이에 등록된 모든 그룹의 전체정보를 포함하는 목록을 조회하는 API이다.

 

  • HTTP Request

URI

{base_url}/groups

Method

GET

Header

Content-Type: application/json

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

그룹 동기화 버전

groups

Object Array

M

그룹 정보 목록

gid

Uint16

M

그룹 논리주소

gname

String

O

그룹 이름

gmlist           

Object Array

M

그룹 소속 멤버 정보 목록

gmtype

String

M

그룹 멤버 종류

lid

Hex(28)

M

디바이스 위치주소

did

Uint16

M

디바이스 논리주소

mid_list

Uint8 Array

CM

디바이스 모듈 논리주소 목록

- 조건: 그룹 멤버 종류(gmtype)이 모듈(module)인 경우

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"sync":"2023-01-17T17:13:40Z",

"groups": [

{

"gid": 1,

"gname":"Group #1",

"gmlist": [

{ "gmtype":"device","lid":"00010000…", "did": 1},

{ "gmtype":"module","lid":"00010000…", "did": 3, "mid_list": [2] },

{ "gmtype":"module","lid":"00010000…", "did": 4, "mid_list": [2, 3] }

]

},

{

"gid": 2,

"gname":"Group #2",

"gmlist": [

{ "gmtype":"device","lid":"00010000…", "did": 1},

{ "gmtype":"module","lid":"00010000…", "did": 3, "mid_list": [2] },

{ "gmtype":"module","lid":"00010000…", "did": 4, "mid_list": [2] }

{ "gmtype":"module","lid":"00010000…", "did": 5, "mid_list": [2] }

]

}

]

}

}

 

비고

 

 
2.11.3.2 그룹 논리주소 목록 조회

 게이트웨이에 등록된 그룹 논리주소 목록 조회 API는 게이트웨이에 등록된 그룹의 논리주소 목록을 조회하는 API이다.
 
  • HTTP Request

URI

{base_url} /groups?attr=gid

Method

GET

Header

Content-Type: application/json

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

그룹 동기화 버전

gid_list

Object Array

M

그룹 논리주소 목록

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"sync":"2023-01-17T17:13:40Z",

"gid_list": [1,2,3,4]

}

}

 

비고

 

 
2.11.4 그룹 구성정보 조회

 그룹 구성정보 조회 API는 게이트웨이로부터 특정 그룹에 대한 구성정보를 조회하는 API이다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

gid

Uint16

M

그룹 논리주소

gname

String

O

그룹 이름

gmlist

Object Array

M

그룹 소속 멤버 정보 목록

gmtype

String

M

그룹 멤버 종류

lid

Hex(28)

M

디바이스 위치주소

did

Uint16

M

디바이스 논리주소

mid_list

Uint8 Array

CM

디바이스 모듈 논리주소 목록

- 조건: 그룹 멤버 종류(gmtype)이 모듈(module)인 경우

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"gid": 32768,

"gname":"Group #1",

"gmlist": [

{ "gmtype":"device","lid":"0001000000000000000001", "did": 1},

{ "gmtype":"module","lid":"0001000000000000000002", "did": 3, "mid_list": [2] },

{ "gmtype":"module","lid":"0001000000000000000003", "did": 4, "mid_list": [2,3] }

]

 }

}

 

비고

 

 
2.11.5 그룹 구성정보 변경

 게이트웨이에 등록된 그룹의 전체 구성정보 변경을 요청하는 API이다.

 그룹 소속 멤버의 추가 또는 삭제를 위하여 그룹 구성정보를 변경하는 경우에는 그룹 소속 멤버 정보 목록(gmlist)에는 추가 또는 삭제 멤버가 반영된 모든 그룹 소속 멤버를 포함하여야 한다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

Body

항목

타입(길이)

C

내용

gname    

String

O

그룹 이름

gmlist    

Object Array

O

그룹 소속 멤버 정보 목록

gmtype

String

M

그룹 멤버 종류

lid

Hex(28)

M

디바이스 위치주소

did

Uint16

M

디바이스 논리주소

mid_list

Uint8 Array

CM

디바이스 모듈 논리주소 목록

- 조건: 그룹 멤버 종류(gmtype)이 모듈(module)인 경우

Example

{

    "gname":" Group #2"

"gmlist": [

{ "gmtype":"device","lid":"0001000000000000000001", "did": 2 },

{ "gmtype":"device","lid":"0001000000000000000002", "did": 3 }

]

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
 
2.11.6 그룹 삭제

 그룹 삭제 API는 게이트웨이에 등록된 그룹 정보 삭제를 요청하는 API이다.

 그룹 삭제에 성공한 게이트웨이는 그룹이 삭제된 시간으로 수정된 새로운 그룹 동기화 버전 정보를 응답 메시지에 제공하여야 한다.
 
2.11.6.1 개별 그룹 삭제
 
  • HTTP Request

URI

{base_url}/groups/{gid}

Method

DELETE

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

그룹 동기화 버전

gid

Uint16

M

그룹 논리주소

Example

{

    "result_code":"2002",

    "result_msg":"Deleted",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"gid": 32768

}

}

 

 
2.11.6.2 전체 그룹 삭제

 게이트웨이에 등록된 그룹 정보 전체 삭제를 요청하는 API이다.
 
  • HTTP Request

URI

{base_url}/groups/65535

Method

DELETE

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

 

 

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

그룹 동기화 버전

gid_list

Uint16 Array

M

그룹 논리주소 목록

Example

{

    "result_code":"2002",

    "result_msg":"Deleted",

    "result_data": {

"sync":" 2023-01-17T17:13:40Z",

"gid_list": [1, 3, 34, 40]

}

}

그룹 논리주소 목록에는 삭제된 모든 그룹 논리주소를 포함함

 
2.11.7 그룹 조명 상태정보 변경 (그룹 조명제어)

 조명 그룹 상태정보 변경 API는 조명 디바이스로 구성된 그룹에 대하여 그룹 단위로 조명 상태를 변경(조명 제어)하는 API이다.

 그룹 조명 상정정보 변경 요청을 받은 게이트웨이는 개별 조명 디바이스의 상태변화 유무와 상관없이 바로 응답 메시지를 전송한다. 그룹 제어에 따른 조명 상태 변화는 게이트웨이 B-SLP MQTT API의 그룹 상태 메시지를 통하여 확인 가능하다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}/light

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

디바이스 논리주소

Body

항목

타입(길이)

C

내용

onoff

String

O

조명 점등(on)/소등(off) 상태 정보

level

Uint8

O

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint16

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Uint8

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

tt

Uint16

O

동작소요시간(ms)

Example 1

{

"onoff":"on",

"tt": 0

}

 

Example 2

{

"colortemp": 5000,

"tt": 0

}

 

Example 3

{

"level": 100,

    "colortemp": 5000,

"tt": 0

}

 

Example 4

{

    "x": 0.22,

    "y": 0.48,

"tt": 0

}

 

Example 5

{

    "hue": 359,

    "sat": 100,

    "bright": 100,

"tt": 0

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
 
 
2.11.8 그룹 조명 설정정보 변경
 
 그룹 조명 설정정보 변경 API는 조명 디바이스로 구성된 그룹에 대하여 조명 설정정보를 동일하게 변경하는 API이다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}/lightconfig

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

Body

항목

타입(길이)

C

내용

onoff_tt

Uint16

O

점소등소요시간

dimup_tt

Uint16

O

최대밝기도달시간

dimdn_tt

Uint16

O

최소밝기도달시간

on_htime

Uint16

O

점등유지시간

off_htime

Uint16

O

소등유지시간

on_dtime

Uint16

O

점등대기시간

off_dtime

Uint16

O

소등대기시간

color_tt

Uint16

O

색상변경소요시간

offlevel

Uint8

O

Off 이름령어 시 점등되는 레벨

level_rate

Uint8

O

조명 출력 비율

rperiod

Uint16

O

조명 상태정보 보고 주기

last_light

String

O

점등시 마지막 조명 상태정보 복구

Example

{

"onoff_tt": 0,

"dimup_tt": 0,

"dimdn_tt": 0,

"on_htime": 65535,

"off_htime": 65535,

"on_dtime": 0,

"off_dtime": 0,

"color_tt": 0,

"offlevel": 20,

"level_rate":80,

"rperiod":60

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 

2.11.9 그룹 센서 설정정보 변경


2.11.9.1 전체 그룹 동일 변경


 그룹 센서 설정정보 변경 API는 센서 디바이스로 구성된 그룹에 대하여 센서 공통 설정정보를 동일하게 변경하는 API이다.

 

  • HTTP Request

URI

{base_url}/groups/{gid}/sensor

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
2.11.9.2 특정 센서타입 그룹 설정
 
  • HTTP Request

URI

{base_url}/groups/{gid}/sensor?mtype={mtype}

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

Body

항목

타입(길이)

C

내용

active

String

M

센서 동작 상태 정보

opmode

String

M

센서 이벤트 발생시 동작 모드

mperiod

Uint16

M

센서 측정 주기

rperiod

Uint16

M

센서 정보 보고 주기

Example

{

"active":"enable",

"opmode":"notify",

"mperiod": 5000,

"rperiod":60

}

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

Example

{

"result_code":"2004",

"result_msg":"Changed"

}

 

 
2.11.10 그룹 하위 디바이스 조회

2.11.10.1 디바이스 전체정보 목록 조회

 특정 그룹에 소속된 디바이스의 전체정보를 조회하는 API이다.

 디바이스 정보 목록(devices)에 포함되는 디바이스 속성은 "2.8.1.1 디바이스 전체정보 목록 조회"와 동일하다. 단, 그룹 멤버로 모듈단위로 포함된 디바이스의 경우에는 모듈 정보(modules)에서 해당 모듈만을 포함한다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}/devices

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

devices

Object Array

M

디바이스 정보 목록

{devices attributes}

-

-

디바이스 전체정보 목록 조회 참고

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"devices": [

{

"did": 2,

"dinfo": {

"dpid":"1234567890AABBCCDD",

"pc":"03EF01…",

"sn":"1609123456",

"lid":"0000000000000000000000000000",

"dfault": 0,

"mqtt_df_enable":"enable"

},

"cap": {

"mcap": {

    "in_maxm": 1,

    "in_usedm": 1

},

"gcap": {

    "maxg": 1,

    "usedg": 1

},

"scap": {

    "maxg": 1,

    "usedg": 1

}

},

"modules": [

 {

"mid": 2,

"minfo": {

"mclass":"l"

"mtype": 3,

"form":"in"

},

"light": {

"onoff":"on",

"level":100

},

"lightconfig": {

"onoff_tt":60,

 

}

 }

],

"gid_list":[1,2,4,7],

"scid_list":[2,4,5]

}

{

"did": 3,

"dinfo": {

"dpid":"1234567890AABBCCDD",

"pc":"03EF01….",

"sn":"1609123457",

"lid":"0000000000000000000000000000",

"dfault": 2,

"fslist": [

{

"mid":2,

"fcode":"80000000"

}

] ,

"mqtt_df_enable":"disable"

},

"cap": {

"mcap": {

    "in_maxm": 1,

    "in_usedm": 1

},

"gcap": {

    "maxg": 1,

    "usedg": 1

},

"scap": {

    "maxg": 1,

    "usedg": 1

}

},

"modules": [

 {

"mid": 2,

"minfo": {

"mclass":"s"

"mtype": 5,

"form":"in"

},

"sensor": {

"active":"enable",

"opmode":100,

"mperiod":1,

"rperiod":50,

"vtype":"string",

"value":"n"

}

 }

],

"gid_list":[3],

"scid_list":[]

      ]

}

}

 

비고

 

 
2.11.10.2 디바이스 객체속성 목록 조회

 디바이스 객체속성 목록 조회 API는 특정 그룹에 소속된 디바이스들의 하위 객체정보를 조회하는 API이다.

 그룹 멤버로 모듈단위로 포함된 디바이스의 경우에는 모듈 정보(modules)에서 해당 모듈만을 포함한다.
 
  • HTTP Request

URI

{base_url}/groups/{gid}/devices/{attributes}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

비고

- 그룹 하위 디바이스 조회의 디바이스 전체정보 목록 조회 API에서 속성 필터 사용으로 동일한 호출 가능

: {base_url}/groups/{gid}/device?attrs={attributes}

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

{attribues}

-

-

attributes 객체

{attributes member}

-

-

attributes 객체의 멤버 속성

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"devices": [

{

"did": 2,

"{attributes}" {

"{attributes member}":{value},

}

},

{

"did": 3,

"{attributes}" {

"{attributes member}":{value},

}

}

]

}

}

 

 

비고

 

 

 

 
 

 디바이스 객체속성 목록 조회 API에서도 다음과 같은 속성 필터 또는 속성 제한 API 확장 기능을 이용하여 특정 속성만 조회가 가능하다.


- 하위 속성 호출: {base_url}/groups/{gid}/devices/{attributes}?attr={attribute}
- 하위 속성값 기준 호출: {base_url}/groups/{gid}/devices/{attributes}?{attribute}={value}
- 하위 객체 호출: {base_url}/groups/{gid}/devices/{attributes}?attrs={attributes}

 

 다음은 특정 그룹에 소속된 디바이스들의 모듈(modules) 속성중에서 조명 상태정보(light)만을 조회하는 속성 필터(attrs=light)를 적용한 API 예제이다.

 

  • HTTP Request

URI

{base_url}/groups/{gid}/devices/modules?attrs=light

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

gid

Uint16

그룹 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

devices

Object Array

M

디바이스 정보 목록

did

Uint16

M

디바이스 논리주소

modules

Object Array

M

디바이스의 모듈정보 객체 목록

mid

Uint8

M

모듈 논리주소

light

Object

CM

조명 상태정보

onoff

String

M

조명 점소등 상태

level

Uint8

CM

디밍 레벨

- 조건: 조명이 점등(on) 상태인 경우

- 소등(off) 상태인 경우 "0"이어야 함

colortemp

Uint16

O

상관 색온도

hue

Uint16

O

조명 색상(HSB)의- 색상

sat

Uint8

O

조명 색상(HSB)의- 채도

bright

Uint8

O

조명 색상(HSB)의- 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

RGB 모델 - Red

g

Uint8

O

RGB 모델 - Green

b

Uint8

O

RGB 모델 - Bule

Example

{attrs}=light

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"devices": [

{

"did": 1,

"modules": [

{

"mid":2,

"light":{

"onoff":"on",

"level": 100,

"colortemp": 5000

}

}

]

},

{

"did": 2,

"modules": [

{

"mid":2,

"light":{

"onoff":"on",

"level": 100,

"colortemp": 5000

}

}

]

},

 

]

}

}

 

 
 

 

 

 

2.12 장면 API

 장면(Scene)은 여러 조명 디바이스의 개별 상태정보를 하나의 논리적 모임으로 묶어 관리하는 개념이다. 한번의 장면 제어를 통하여 여러 조명 디바이스를 각기 다른 조명상태로 변경이 가능하다.

 본 절에서는 B-SLP를 지원하는 사용자 입력장치(UD3), 설치시험기(TS3), 관제서버(MS) 등을 위해 게이트웨이에 장면을 생성하여 관리, 제어하기 위한 스마트 조명 게이트웨이에서 지원하는 B-SLP API를 제시한다.

 

2.12.1 장면 생성


 장면 생성 API는 게이트웨이에 장면 자원 생성을 요청하고 장면 논리주소(SCID)를 발급받는 API이다. 
 장면 생성 정보를 받은 게이트웨이는 개별 조명에 스마트 조명 L-SLP API를 사용하여 등록한다. 장면 소속 대상 정보 목록의 등록 순서는 그룹, 디바이스, 모듈 순서로 등록해야 한다.

 그룹, 디바이스, 모듈 정보는 중첩이 되지 않도록 하여야 하며 장면 생성 요청 메시지를 수신한 게이트웨이는 중첩 여부를 확인하여야 한다. 중첩이 발생하는 경우 오류코드 4104(파라미터 값이 올바르지 않습니다.)로 응답하여야 한다.


 장면 생성에 성공한 게이트웨이는 장면이 생성된 시간으로 수정된 새로운 장면 동기화 버전 정보를 응답 메시지에 제공하여야 한다.

 

  • HTTP Request

URI

{base_url}/scenes

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

sname    

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간(s)

sslist      

Object Array

M

장면 설정 정보 목록

slid

Uint16

M

장면 설정 목록 논리주소

light

Object

M

조명 상태정보 객체

- 최소 1개 이상의 속성 정보 포함

onoff

String

O

조명기기의 현재 점등(on)/소등(off) 상태 정보

level

Uint8

O

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint16

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Uint8

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

tt

Uint16

O

동작소요시간(ms)

tglist

Object Array

M

장면 소속 대상 정보 목록

tgtype

String

M

대상 타입

did

Uint16

CM

디바이스 논리주소

- 조건: 대상 타입이 "device" 또는 "module"인 경우

mid_list

Uint8 Array

CM

모듈 논리주소 목록

- 조건: 대상 타입이 "module"인 경우

gid

Uint16

CM

그룹 논리주소

- 조건: 대상 타입이 "group"인 경우

Example

{

"sname":" Scene #2",

"sslist": [

{

"slid":1,

"light":{

"onoff":"on",

"level":100,

"colortemp":5000,

"tt":1

},

"tglist":[

{ "tgtype":"device", "did":3 },

{ "tgtype":"module", "did":4, "mid_list":[2] },

{ "tgtype":"group", "gid":10 }

]

},

{

"slid":2,

"light":{

"onoff":"on",

"level":80,

"colortemp":5000,

"tt":1

},

"tglist":[

{ "tgtype":"group", "gid":11 }

]

}

]

}

 

비고

- 장면 이름(sname)이 없는 경우 게이트웨이에서 임의 할당하여 사용 가능

- 장면 수행 시간(sopt)가 생략된 경우 기본값(65535, 무한대)으로 설정

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 장면 동기화 버전

scid

Uint16

M

장면 논리주소

Example

{

    "result_code":"2001",

    "result_msg":"Created",

    "result_data": {

"sync":"2023-01-17T17:13:40Z",

"scid": 3

}

}

 

비고

 

 

 

2.12.2 장면 등록


 장면 등록 API는 관제서버(MS)에서 생성한 장면 정보를 게이트웨이에 등록을 요청하는 API이다. 


 Request 메시지의 장면 논리주소(SCID)는 게이트웨이가 사용중이지 않은 논리주소를 사용하여야 한다. 게이트웨이가 사용중인 장면 논리주소인 경우 게이트웨이는 오류 응답(result_code: 6108)을 보낸다.


 장면 등록 API는 MS만 사용 가능하다.


 장면 등록 정보를 받은 게이트웨이는 개별 조명에 스마트 조명 L-SLP API를 사용하여 등록한다. 장면 소속 대상 정보 목록의 등록 순서는 그룹, 디바이스, 모듈 순서로 등록해야 한다. 그룹, 디바이스, 모듈 정보는 중첩이 되지 않도록 하여야 하며 장면 생성 요청 메시지를 수신한 게이트웨이는 중첩 여부를 확인하여야 한다. 중첩이 발생하는 경우 오류코드 4104(파라미터 값이 올바르지 않습니다.)로 응답하여야 한다.


 장면 등록에 성공한 게이트웨이는 장면이 등록된 시간으로 수정된 새로운 장면 동기화 버전 정보를 응답 메시지에 제공하여야 한다.

 

  • HTTP Request

URI

{base_url}/scenes

Method

PUT

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

scid

Uint16

M

장면 논리주소

sname    

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist      

Object Array

M

장면 설정정보 목록

slid

Uint16

M

장면 설정정보 논리주소

light

Object

M

조명 상태정보 객체

- 최소 1개 이상의 속성 정보 포함

onoff

String

O

조명기기의 현재 점등(on)/소등(off) 상태 정보

level

Uint8

O

조명 밝기(디밍 레벨)

colortemp

Uint16

O

조명 상관 색온도

hue

Uint16

O

조명 색상(HSB)의 색상

sat

Uint8

O

조명 색상(HSB)의 채도

bright

Uint8

O

조명 색상(HSB)의 휘도

x

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 x

y

Float(3,2)

O

조명 색상(CIE 1931 XY 색좌표)의 y

r

Uint8

O

조명 색상(R, G, B)의 적색(Red)

g

Uint8

O

조명 색상(R, G, B)의 녹색(Green)

b

Uint8

O

조명 색상(R, G, B)의 청색(Blue)

tt

Uint16

O

동작소요시간(ms)

tglist

Object Array

M

장면 소속 대상 정보 목록

tgtype

String

M

대상 타입

did

Uint16

CM

디바이스 논리주소

- 조건: 대상 타입이 "device" 또는 "module"인 경우

mid_list

Uint8 Array

CM

모듈 논리주소 목록

- 조건: 대상 타입이 "module"인 경우

gid

Uint16

CM

그룹 논리주소

- 조건: 대상 타입이 "group"인 경우

Example

{

"scid":20,

"sname":" Scene #2",

"sslist": [

{

"slid":1.

"light":{

"onoff":"on",

"level":100,

"colortemp":5000,

"tt":1

},

"tglist":[

{ "tgtype":"device", "did":3 },

{ "tgtype":"module", "did":4, "mid_list":[3] },

{ "tgtype":"group", "gid":10 }

]

},

{

"slid":2.

"light":{

"onoff":"on",

"level":80,

"colortemp":5000,

"tt":1

},

"tglist":[

{ "tgtype":"group", "gid":11 }

]

}

]

}

 

비고

- 장면 이름(sname)이 없는 경우 게이트웨이에서 임의 할당하여 사용 가능

- 장면 수행 시간(sopt)가 생략된 경우 기본값(65535, 무한대)으로 설정

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 장면 동기화 버전

Example

{

"result_code":"2004",

"result_msg":"Changed",

"result_data": {

"sync":"2023-01-17T17:13:40Z"

}

}

 

 
2.12.3 현재상태 장면 생성

 현재상태 장면 생성 API는 사용자 입력장치(UD3, TS3)에서 개별 조명 디바이스의 현재상태 장면에 대한 장면 자원 생성을 요청하고 장면 논리주소(SCID)를 발급받는 API이다.

 현재상태 장면 생성 API에는 장면 설정정보 목록(sslist)은 선택 사항이며, 포함되지 않는 경우 게이트웨이는 게이트웨이에 연결된 모든 조명 디바이스를 대상으로 장면을 생성하여야 한다. 장면 설정정보 목록(sslist)을 포함하는 경우에는 장면 설정 목록 논리주소(slid)와 조명 상태정보 객체(light)를 포함해서는 안되며 장면 소속 대상 정보 배열(tglist)만 포함한다.
 
 현재 상태 장면 생성 요청을 받은 게이트웨이는 현재 조명 디바이스의 상태정보를 바탕으로 장면 설정 정보 목록(sslist)를 생성하여 장면을 생성하고(장면 논리주소 할당), 장면에 포함되는 개별 조명 디바이스에 스마트 조명 L-SLP API를 사용하여 장면을 등록한다. 장면 소속 대장 정보 목록의 그룹, 디바이스, 모듈 정보는 중첩이 되지 않도록 하여야 한다.
 
 생성된 장면 설정정보의 상세 내용은 장면 설정정보 조회 API를 사용한다.

 현재상태 장면 생성에 성공한 게이트웨이는 장면 생성 시간으로 수정된 새로운 장면 동기화 버전 정보를 응답 메시지에 제공하여야 한다.
 
  • HTTP Request

URI

{base_url}/scenes

Method

POST

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

sname    

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist

Object Array

O

장면 설정 정보 목록

tglist

Object Array

M

장면 소속 대상 정보 배열

tgtype

String

M

대상 타입

did

Uint16

CM

디바이스 논리주소

- 조건: 대상 타입이 “device” 또는 “module”인 경우

mid_list

Uint8 Array

CM

모듈 논리주소 목록

- 조건: 대상 타입이 “module”인 경우

gid

Uint16

CM

그룹 논리주소

- 조건: 대상 타입이 “group”인 경우

Example

{

"sname":" Scene #2"

}

 

비고

- 장면 수행 시간(sopt)가 생략된 경우 기본값(65535, 무한대)으로 설정

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 장면 동기화 버전

scid

Uint16

M

장면 논리주소

Example

{

    "result_code":"2001",

    "result_msg":"Created",

    "result_data": {

"sync":"2023-01-17T17:13:40Z",

"scid": 3

}

}

 

비고

- 장면 이름(sname)이 없는 경우 게이트웨이에서 임의 할당하여 사용 가능

- 장면 수행 시간(sopt)가 생략된 경우 기본값(65535, 무한대)으로 설정

 
 
2.12.4 현재상태 장면 등록

 현재상태 장면 등록 API는 관제서버(MS)가 현재상태 장면 정보를 게이트웨이에 등록을 요청하는 API이다. 

 Request 메시지의 장면 논리주소(SCID)는 게이트웨이가 사용중이지 않은 논리주소를 사용하여야 한다. 게이트웨이가 사용중인 장면 논리주소인 경우 게이트웨이는 오류 응답(result_code: 6108)을 보낸다.

 장면 등록 API는 MS만 사용 가능하다.

 현재상태 장면 등록 API에는 장면 설정정보 목록(sslist)은 선택 사항이며, 포함되지 않는 경우 게이트웨이는 게이트웨이에 연결된 모든 조명 디바이스를 대상으로 장면을 등록하여야 한다. 장면 설정정보 목록(sslist)을 포함하는 경우에는 장면 설정 목록 논리주소(slid)와 조명 상태정보 객체(light)를 포함해서는 안되며 장면 소속 대상 정보 배열(tglist)만 포함한다.
 
 장면 등록 정보를 받은 게이트웨이는 개별 조명에 스마트 조명 L-SLP API를 사용하여 등록한다. 장면 소속 대상 정보 목록의 등록 순서는 그룹, 디바이스, 모듈 순서로 등록해야 한다.
 
 
 그룹, 디바이스, 모듈 정보는 중첩이 되지 않도록 하여야 하며 장면 생성 요청 메시지를 수신한 게이트웨이는 중첩 여부를 확인하여야 한다. 중첩이 발생하는 경우 오류코드 4104(파라미터 값이 올바르지 않습니다.)로 응답하여야 한다.

 등록된 장면 설정정보의 상세 내용은 장면 설정정보 조회 API를 사용한다.

 장면 등록에 성공한 게이트웨이는 장면 등록 시간으로 수정된 새로운 장면 동기화 버전 정보를 응답 메시지에 제공하여야 한다.
 
 
  • HTTP Request

URI

{base_url}/scenes

Method

PUT

Header

Content-Type: application/json

Body

항목

타입(길이)

C

내용

scid

Uint16

M

장면 논리주소

sname

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist

Object Array

O

장면 설정 정보 목록

slid

Uint16

M

장면 설정 목록 논리주소

tglist

Object Array

M

장면 소속 대상 정보 배열

tgtype

String

M

대상 타입

did

Uint16

CM

디바이스 논리주소

- 조건: 대상 타입이 “device” 또는 “module”인 경우

mid_list

Uint8 Array

CM

모듈 논리주소 목록

- 조건: 대상 타입이 “module”인 경우

gid

Uint16

CM

그룹 논리주소

- 조건: 대상 타입이 “group”인 경우

Example

{

"scid":12,

"sname":" Scene #2"

}

 

비고

- 장면 이름(sname)이 없는 경우 게이트웨이에서 임의 할당하여 사용 가능

- 장면 수행 시간(sopt)가 생략된 경우 기본값(65535, 무한대)으로 설정

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

신규 장면 동기화 버전

Example

{

"result_code":"2004",

"result_msg":"Changed",

"result_data": {

"sync":"2023-01-17T17:13:40Z"

}

}

 

 
2.12.5 장면 목록 조회

 게이트웨이에 등록된 모든 장면의 정보를 목록으로 조회하는 API이다.

2.12.5.1 장면 전체정보 목록 조회

 게이트웨이에 등록된 모든 장면의 전체정보를 포함하는 목록을 조회하는 API이다.
 
  • HTTP Request

URI

{base_url}/scenes

Method

GET

Header

Content-Type: application/json

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

장면 동기화 버전

scenes

Object Array

M

장면 정보 목록

scid

Uint16

M

장면 논리주소

sname

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist

Object Array

M

장면 설정 목록

slid

Uint16

M

장면 설정 목록 논리주소

light

Object

M

조명 상태정보 객체

{light attribute}

-

-

조명 상태정보 객체의 속성

tglist

Object Array

M

조명 상태정보가 적용될 대상 객체 목록

tgtype

String

M

조명 상태정보가 적용될 대상의 종류

did

Uint16

CM

디바이스 논리주소

mid_list

Uint8 Array

CM

모듈 논리주소 목록

gid

Uint16

CM

그룹 논리주소

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"sync":"2023-01-17T17:13:40Z"

"scenes": [

{

"scid": 2,

"sname":"장면 #1",

"sopt":65535,

"sslist": [

{

"slid":1,

"light":{

"onoff":"on",

"level":80,

"colortemp":5000

},

"tglist":[

{

"tgtype ":"device",

"did": 1

},

{

"tgtype":"module",

"did": 2,

"mid_list": [2]

}

]

},

{

"slid":2,

"light":{

"onoff":"on",

"level":50,

"colortemp":5000

},

"tglist":[

{

"tgtype":"group",

"gid": 32

}

]

}

]

}

]

}

}

 

비고

 

 
2.12.5.2 장면 논리주소 목록 조회

 게이트웨이에 등록된 모든 장면의 논리주소를 포함하는 목록을 조회하는 API이다.
 
  • HTTP Request

URI

{base_url}/scenes?attr=scid

Method

GET

Header

Content-Type: application/json

비고

 

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

sync

String(20)

M

장면 동기화 버전

scid_list

Uint16 Array

M

장면 논리주소 목록

Example

{

  "result_code":"2000",

  "result_msg":"Success",

  "result_data": {

"sync":"2023-01-17T17:13:40Z"

"scid_list": [1, 2]

}

}

 

비고

 

 
2.12.6 장면 설정정보 조회
 
 게이트웨이로부터 특정 장면에 대한 정보를 조회하는 API이다.
 
  • HTTP Request

URI

{base_url}/scenes/{scid}

Method

GET

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

scid

Uint16

장면 논리주소

 
  • HTTP Response

Header

Content-Type: application/json;charset=UTF-8

Body

항목

타입(길이)

C

내용

result_code

String

M

결과 코드

result_msg

String

M

결과 메시지

result_data

Object

M

결과 데이터

scid

Uint16

M

장면 논리주소

sname

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist

Object Array

M

장면 설정 목록

light

Object

M

조명 상태정보 객체

{light attribute}

-

-

조명 상태정보 객체의 속성

tglist

Object Array

M

조명 상태정보가 적용될 대상 객체 목록

tgtype

String

M

조명 상태정보가 적용될 대상의 종류

did

Uint16

CM

디바이스 논리주소

mid_list

Uint8 Array

CM

모듈 논리주소 목록

gid

Uint16

CM

그룹 논리주소

Example

{

    "result_code":"2000",

    "result_msg":"Success",

    "result_data": {

"scid": 2,

"sname":"장면 #1",

"sopt":65535,

"sslist": [

 {

"light":{

"onoff":"on",

"level":80,

"colortemp":5000

},

"tglist":[

{

"tgtype ":"device",

"did": 1

},

{

"tgtype":"module",

"did": 2,

"mid_list": [2]

}

]

},

{

"light":{

"onoff":"on",

"level":50,

"colortemp":5000

},

"tglist":[

{

"tgtype":"group",

"gid": 32

}

]

}

]

}

}

}

 

 
2.12.7 장면 설정정보 변경

 장면 설정정보 변경 API는 게이트웨이에 등록된 장면의 설정정보 수정을 요청하는 API이다.
 
  • HTTP Request

URI

{base_url}/scenes/{scid}

Method

PATCH

Header

Content-Type: application/json

URI Parameter

항목

타입(길이)

내용

scid

Uint16

장면 논리주소

Body

항목

타입(길이)

C

내용

sname

String

O

장면 이름

sopt

Uint16

O

장면 수행 시간

sslist

Object Array