Int'l Light Convergence O2O EXPO

개요 데이터 모델 백본 네트워크 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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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로 요청하여야 한다.

HTTP Request

URI	{base_url}/devices/{did}/light
Method	PATCH
Header	Content-Type: application/json
URI Parameter	항목	타입(길이)		내용
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로 요청하여야 한다.

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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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	항목	타입(길이)		내용
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이다.

장면 등록 API는 MS만 사용 가능하다.

현재상태 장면 등록 API에는 장면 설정정보 목록(sslist)은 선택 사항이며, 포함되지 않는 경우 게이트웨이는 게이트웨이에 연결된 모든 조명 디바이스를 대상으로 장면을 등록하여야 한다. 장면 설정정보 목록(sslist)을 포함하는 경우에는 장면 설정 목록 논리주소(slid)와 조명 상태정보 객체(light)를 포함해서는 안되며 장면 소속 대상 정보 배열(tglist)만 포함한다.

장면 등록 정보를 받은 게이트웨이는 개별 조명에 스마트 조명 L-SLP API를 사용하여 등록한다. 장면 소속 대상 정보 목록의 등록 순서는 그룹, 디바이스, 모듈 순서로 등록해야 한다.

등록된 장면 설정정보의 상세 내용은 장면 설정정보 조회 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	항목	타입(길이)		내용
URI Parameter	scid	Uint16		장면 논리주소
Body	항목	타입(길이)	C	내용
	sname	String	O	장면 이름
	sopt	Uint16	O	장면 수행 시간
	sslist	Object Array	O	장면 설정 목록

Int'l Light Convergence EXPO

2.9.1 조명 상태정보 조회

2.9.1.1 전체 조명 모듈

2.9.1.2 개별 조명 모듈

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

2.9.2.1 전체 조명 모듈 동일 제어

2.9.2.2 전체 조명 모듈 개별 제어

2.9.2.3 개별 조명 모듈 제어

2.9.3 조명 설정정보 조회

2.10.1 센서 공통 설정정보 조회

2.10.1.1 전체 센서 모듈 조회

2.10.1.2 특정 센서타입 조회

2.10.2 센서 개별 설정정보 조회

1.1.1.1 Status형 응답

2.10.2.2 Value형 응답