1. 개요2. 상세3. 개발 준비4. 문서5. 통합 개발 환경
5.1. Samsung Automation Studio5.2. SmartThings Developer Workspace
6. SmartThings Edge7. SmartThings API8. pysmartthings9. Samsung Developers5.2.1. WebHook5.2.2. AWS Lambda5.2.3. Works With SmartThings 인증을 받는 법5.2.4. 제품 불러오기
5.3. SmartThings Console5.2.4.1. 직접 연결 제품을 개발하는 법5.2.4.2. 모바일 연결 제품을 개발하는 법5.2.4.3. 허브 연결 제품을 개발하는 법5.2.4.4. 클라우드 연결 제품을 개발하는 법
5.2.5. 자동화 만들기[clearfix]
1. 개요
SmartThings 플랫폼의 개발을 다루는 문서이다.2. 상세
스마트싱스의 디벨로퍼 페이지는 Samsung Developers에서 별도의 사이트로 분리되어 운영하고 있다.
SmartThings는 SmartThings 디벨로퍼에서 개인 개발자와 제품 및 서비스를 생산하는 기업 개발자를 모두 지원한다. SmartThings는 개발자 중심의 오픈 플랫폼으로 출발했기 때문에, 스마트싱스에 인증 된 회사나 개발자가 아닌 일반 개발자나 개인도 스마트앱스를 만들어서 추가로 설치하여 이용할 수 있다.
이 과정에서 제조사 중심인 다른 IoT 스마트홈 플랫폼과는 다르게, 세부적인 SmartThings의 설정을 제어할 수 있게 되면서, 이전보다 개인화된 스마트홈을 구축할 수 있다.
3. 개발 준비
3.1. 개발자 모드 활성화
SmartThings 앱의 [메뉴] → [설정]에 있는 'SmartThings 앱 정보'를 5초간 길게 누르면 개발자 옵션이 활성화되면서, 개발자 모드가 나타난다. 이후, 개발자 모드 옆에 있는 On/Off 스위치를 눌러서 활성화할 수 있다.개발자 옵션이 활성화 될 때, 별도의 토스트 메세지가 뜨지 않으므로, 'SmartThings 앱 정보'를 5초간 길게 누른 후, 당황할 필요 없이, 스크롤을 아래로 내리면 된다.
3.2. SmartThings 개인 권한 토큰
3.3. 대시보드
3.3.1. SmartThings CLI
3.3.2. SmartThings Advanced Web App
3.3.3. SmartThings API Browser+
개인 개발자 TAustin가 만든 웹 기반 RESTful API의 그래픽 인터페이스이다.SmartThings API Browser+를 쓰려면 SmartThings 개인 권한 토큰을 얻어야 한다.
3.4. 프로그래밍 언어, 포맷
언어와 포맷의 모든 것을 배울 필요는 없다. 기본적인 문법만 익히고 필요한 것만 라이브러리에서 끌어오면 개발을 진행할 수 있다.- Lua는 SmartThings Edge의 기반 언어이다. SmartThings Edge를 통해 기존 SmartThings의 완전한 로컬 기반 자동화를 만들 수 있다.
- Node.js는 SmartThings 스키마의 기반 언어이다. 이를 통해 자바스크립트를 사용하는 타사 IoT 플랫폼의 클라우드 및 클라우드 커넥터를 SmartThings Cloud와 연결하는 것이 원활해진다.
- Webhook은 HTTP 기반의 실시간 전송 프로토콜(RTP)을 지원하는 비동기식 패턴 API로, 이벤트가 발생하면 이벤트 정보와 액션 데이터를 브로커를 통해 클라이언트에게 푸시 메세지의 형태의 HTTP POST로 전송한다. SmartThings에서는 webCoRE에서 지원하는 누적 조건을 Webhook의 푸시 메세지로도 지원하면서, SmartThings 클라우드에 스트리밍하지 않고 별도의 서버에 스트리밍 되다가, Command가 발생할 때 클라우드 서버와의 통신을 통해 만들어져 있는 자동화의 정보를 송수신한다. SmartThings는 Webhook의 리소스인 REST API도 도입해서 기존의 Groovy 기반의 SmartThings API를 RESTful API로 개선하여 WebHook과의 호환성을 높혔다.
- JSON은 위의 스마트앱스와 커넥터가 작동하는 데이터 통신 포맷이다. 이렇게 WebHook의 REST API가 적용 된 JSON 환경의 SmartThings API 기반으로 만든 스마트앱스와 커넥터를 웹에서 바로 패키징해서 SmartThings 클라우드에 연동해서 올릴 수 있다.
3.5. 커뮤니티
SmartThings가 공식 운영하는 커뮤니티에서 개발 정보를 얻을 수 있다.3.5.1. SmartThings Community
3.5.2. SmartThings Community (Github)
깃허브 스마트싱스 커뮤니티깃허브 스마트싱스 SDK for Direct Connected Devices
3.5.3. SmartThings 커뮤니티 (삼성 멤버스)
4. 문서
4.1. SmartThings Developer Documentation
SmartThings의 개발 라이브러리이다. 영어로만 제공된다.
SmartThings Developers 유저 번역에서 SmartThings Developers 문서들의 비공식 한글 번역이 이뤄지고 있다.
4.2. SmartThings Brand Guidline
스마트싱스의 로고와 트레이드 마크 등에 대한 디자인 가이드라인이다. SmartThings의 배지를 포함해서 로고 시스템, 컬러 팔레트, 다양한 경우에서의 목업 등 디자인 에셋과 쓰는 법이 있다.
스마트싱스에서 쓰이는 로고와 배지의 AI, PNG 파일을 타입 별로 다운로드 할 수 있다.
4.2.1. 로고
4.2.2. 배지
4.2.2.1. SmartThings Compatible (Certified SmartThings Compatible)
스마트싱스 디벨로퍼에서 자체 테스트를 해서 호환되는 기기들에 붙는 배지이다. 영업일 기준 2일 내외로 확인해준다.
이 배지가 있는 기기는, 스마트싱스 호환 목록에 등록된다.
SmartThings Compatible로 이름이 바뀌기 앞서 Certified SmartThings Compatible로 불렸다. Certified SmartThings Compatible이라고 적힌 배지가 있다면, 이 배지를 뜻한다.
4.2.2.2. Works With SmartThings
4.2.2.3. Works as a SmartThings Hub
Works as a SmartThings Hub는 SmartThings Hub의 역할을 할 수 있는 스마트 홈 및 IoT 허브, 게이트웨이 중 SmartThings의 인증을 받은 제품에 붙는 배지이다.
5. 통합 개발 환경
5.1. Samsung Automation Studio
5.2. SmartThings Developer Workspace
SmartThings Developers의 Developer Workspace에서는 WebHook 과 AWS Lambda 모두 2가지 방법으로 SmartApp을 만들 수 있다.개발자는 SmartThings와 SmartApp 사이의 HTTP POST 요청을 수신하고 분석하기 위한 커스텀 콜백 기능을 만들어야 한다.
5.2.1. WebHook
| SmartThings Automation |
WebHook은 SmartThings 플랫폼에서 HTTP POST 요청을 수신하고 처리할 수 있으면서 특정한 이벤트가 생긴 후 해당 커스텀 콜백 함수에 접속할 수 있는 HTTPS URL를 뜻한다.
SmartApp 개발자가 이 URL로 들어가는 서버에 코드를 저장해두면 SmartThings 플랫폼에서 필요할 때 호출한다. 이때 서버는 개인이 갖고 있는 사설 서버가 필요하다.
5.2.2. AWS Lambda
AWS Lambda는 사용자가 서버를 만들고 관리하지 않고도 커스텀 콜백 함수를 발행하고 실행할 수 있도록 AWS에서 제공하는 컴퓨팅 서비스인 AWS Lambda를 써서 SmartApp을 개발하는 것이다.AWS Lambda를 기반으로 하는 SmartApp은 개발자가 먼저 커스텀 콜백 함수를 AWS에 배포한 다음 SmartThings 플랫폼이 AWS Lambda를 실행할 수 있도록 권한을 얻어야 한다. 그런 다음 AWS 콘솔의 Lambda 페이지에서 Lambda 함수에 대한 Amazon 리소스 이름(ARN)을 만들고 SmartThings Developer Workplace에 위의 ARN을 입력하여 Lambda로 SmartApp 등록을 할 수 있다.
5.2.3. Works With SmartThings 인증을 받는 법
자세한 내용은 SmartThings Developers의 인증(CERTIFICATION) 문서 참조.
Works With SmartThings의 인증 프로세스에는 4단계가 있다.
- 인증 요청 제출: 인증 신청서 양식을 쓰고 SmartThings Developer Workspace에 신청서를 제출한다. 이 요청은 공인 테스트 제공업체로 전달되며, 공인 테스트 제공업체는 기기 인증을 위한 가격 견적을 발행한다.
- 디바이스 배송: 견적을 수락한 후 지침에 따라 공인 테스트 제공업체에 기기를 배송한다. 이 과정은 지역에 따라 다를 수 있다.
- 디바이스 테스트: 테스트 공급자가 장치를 받으면 인증 테스트를 시작한다. 검사 결과는 영업일 기준 10일 이내에 전달된다. 재검사가 필요한 경우 추가 검사에 대한 견적서가 발행된다. 테스트를 통과한 제품은 SmartThings에 올라간다.
- 디바이스를 SmartThings에 퍼블리시 : IoT 제품을 SmartThings에 올릴 수 있으며 SmartThings Developer Workspace에서 통합 릴리스 날짜를 정할 수 있다. 이 때부터 Works With SmartThings 로고와 배지를 쓸 수 있다.
5.2.4. 제품 불러오기
5.2.4.1. 직접 연결 제품을 개발하는 법
[Device Integration] > [Direct-connected] 에서 시작할 수 있다.직접 연결 제품은 SmartThings 클라우드를 통해 SmartThings 플랫폼과 통신한다.
| SmartThings - Directly Connected Device |
제품에는 X.509 인증서나 ED25519 공개 키 같은 보안 인증을 먼저 신청하고 제품에도 설치해야 한다.
- X.509 인증서를 신청하는 경우 개발자는 X.509 인증서의 UUID를 저장해야 한다.
- ED25519 공개 키인 경우 개발자는 SmartThings API를 써서 디바이스 서명으로 변환할 수 있다.
다음에는 SmartThings 앱에서 보여질 인터페이스인 플러그인을 만들고 SmartThings 클라우드에 접속할 수 있는 URL로 제품에서 데이터 및 명령을 송수신 해야한다. 제품은 CoAP 프로토콜을 써서 SmartThings 클라우드와 통신할 수 있다.
SmartThings는 페어링을 하기 위한 하드웨어/소프트웨어(가상)의 원격 버튼이나 제품에 있는 버튼을 눌러서 SmartThings에 페어링 시킬 수 있는 옵션도 제공한다. 엔드 유저가 제조사에서 제공하는 별도의 원격 제어 버튼 또는 제품에 있는 버튼을 눌러서 같은 WiFi 네트워크에서 IoT 제품과 SmartThings 앱을 페어링할 수 있다.
How to Build Direct Connected Devices - SmartThings 커뮤니티
5.2.4.2. 모바일 연결 제품을 개발하는 법
[Device Integration] > [Mobile-connected] 에서 시작할 수 있다.5.2.4.3. 허브 연결 제품을 개발하는 법
[Device Integration] > [SmartThings Hub] 에서 시작할 수 있다.5.2.4.4. 클라우드 연결 제품을 개발하는 법
[Device Integration] > [SmartThings Cloud Connector] 에서 시작할 수 있다.| SmartThings - Cloud-to-Cloud Device |
클라우드 연결 제품을 개발하려면 클라우드 사이의 통신을 해 주는 커넥터(Connector)를 만들어야 한다. 커넥터는 IoT 제품이 SmartThings 클라우드와 간접적으로 통신할 수 있도록 연결해 주는 소프트웨어 드라이버이면서, SmartThings 클라우드의 명령을 받아 다른 클라우드에 명령하는 명령 생성자이다.
커넥터는 OAuth 액세스 토큰으로 다른 클라우드와 인터넷으로 연결할 수 있다. 그래서 다른 클라우드의 상태를 SmartThings가 인식할 수 있어 커넥터를 통해 다른 클라우드에 연결된 IoT 제품의 상태가 SmartThings 클라우드에 인식되고 SmartThings의 대시보드에서 보이도록 업데이트 된다.
5.2.5. 자동화 만들기
5.2.5.1. 라이프 사이클(삶의 주기)의 개념
스마트앱스(SmartApp)는 스마트앱스의 설치부터 삭제까지의 여러 단계를 삶의 주기로 만들고 단계를 움직일 때 나오는 요청에 대한 핸들러를 만들어야 한다. 유저가 스마트앱스(SmartApp)를 SmartThings 클라우드에 설치할 때 삶의 주기에 들어가고 삭제할 때 끝난다.
- PING
스마트앱스(SmartApp)가 응답하는 지, 잘 돌아가는 지 찾을 때 나오는 요청이다. 스마트앱스(SmartApp)가 SmartThings 클라우드에 등록이 된 다음에 주기적으로 요청이 나온다. SmartThings 플랫폼은 스마트앱스(SmartApp)가 제대로 돌아가는 지 알기 위해 스마트앱스(SmartApp) 식별 번호가 있는 PING 요청을 보낸다. 스마트앱스(SmartApp)는 스마트앱스(SmartApp) 식별 번호가 있는 pingData 필드의 파라미터를 SmartThings Cloud에 응답하며 요청을 반환한다. - CONFIRMATION
- CONFIGURATION
스마트앱스(SmartApp)의 정보를 불러올 때 나오는 요청이다. - INSTALL
스마트앱스(SmartApp)를 SmartThings 클라우드에 설치할 때 나오는 요청이다. - UPDATE
스마트앱스(SmartApp)를 업데이트할 때 나오는 요청이다. - EVENT
새로운 이벤트가 생길 때 나오는 요청이다. 이벤트 요청의 7가지 라이프 사이클 단계를 포함해야 합니. - OAUTH_CALLBACK
스마트앱스(SmartApp)에 타사 클라우드를 액세스할 때 나오는 요청이다. - UNINSTALL
스마트앱스(SmartApp) 제거를 할 때 나오는 요청이다.
5.2.5.2. 구독
5.3. SmartThings Console
===# SmartThings Groovy IDE (지원 중단) #===||<tablealign=center><tablebgcolor=#F3F3F3> ![파일:SmartThings-IDE-PC-main.png]()
|| ![파일:SmartThings-IDE-Mobilephone-main.png]()
||
| SmartThings Groovy IDE의 PC 웹 메인화면 | SmartThings Groovy IDE의 모바일 웹 메인화면 |
[clearfix]
SmartThings는 웹 IDE를 제공한다. IDE의 뜻은 통합 개발 환경 문서 참조.
SmartThings Groovy IDE는 Groovy 언어를 기반으로, SmartThings에 연결 된 모든 기기들의 등록된 정보를 모두 수정할 수 있다. 이렇게 통신방식, 프로토콜의 종류, API 등 애플리케이션에서 하지 못했던 영역의 설정을 여러가지 방법으로 수정, 설치, 삭제해서 SmartThings의 확장성을 크게 향상시키고, SmartThings 내의 네트워크를 사용자의 행동과 패턴에 따라 완전히 개인화할 수 있다.
SmartThings(기업)가 삼성에게 인수되기 전 부터 운영하던 IDE로, SmartThings Classic을 위한 계정을 별도로 발행했으나, SmartThings가 삼성전자의 IoT 브랜드가 된 이후부터는 삼성계정으로 완전히 전환했다.[1] 그러므로, 현재의 SmartThings IDE는 삼성 계정을 사용하며, 삼성 계정에 의해서, SmartThings에 등록 된 기기들의 정보가 저장 된 SmartThings 클라우드가 IDE와 연동되어 웹사이트 형식으로 보여지게 된다.
SmartThings Groovy IDE는 스마트싱스 앱 안에서 제작할 수 있는 가장 기초적인 자동화와 모드부터, webCoRE의 개발 지식이 요구되는 스마트앱스, DTH(Device Type Handler) 등의 복잡한 시스템도 만들어 올릴 수 있는 성능이 있다. 이 성능을 이용해 조건별, 상황별 자동화를 구축하면 본인만의 시스템을 만들어서 수동조작이 거의 필요없는 진정한 의미의 자동화를 실현할 수 있다. 여기서 더 발전하면, 본인 뿐만 아니라, 모든 가족 구성원들의 행동패턴까지 고려해서 조정하는 스마트홈을 구축할 수 있다.
PC 화면과 모바일 화면의 메인화면이 살짝 다르다. PC 웹 메인화면의 상단 GNB에 있는 메뉴들은 Developer Tools라는 카테고리에 묶여서 네비게이션의 하단에 위치해있고, PC 웹 메인화면의 푸터 부분에 있는 다양한 메뉴들이 모바일 웹 메인화면에서는 네비게이션 바의 최상단에 위치해있다. 단, 메인화면만 다르고, 하위 페이지의 모습은 PC와 모바일이 완전히 똑같기 때문에, 모바일 화면에서도 IDE를 쓸 수 있다.
SmartThings Edge 아키텍쳐가 나오면서 지원이 중단되었다.
SmartThings Advanced Web App이 나오면서 SmartThings Groovy IDE가 닫혔다.
====# GitHub 연동 (지원 중단) #====
GitHub의 SmartThings 연동은 아래에 서술 될 DTH(Device Type Handler)나 외부 스마트앱스를 설치하려면 GitHub에 SmartThings와 깃허브 계정과의 연동이 필요하다. 깃허브를 사용하면, SmartThings DTH와 SmartThings 스마트앱스 개발을 위해 개발자들이 GitHub에 올린 프로젝트 코드들을 본인의 개인 계정으로 쉽게 통합할 수 있다. 그리고 개인 계정에 통합 된 DTH와 스마트앱스는 SmartThings에서 등록할 수 있다. 이렇게 되면, 외부 DTH와 스마트앱스를 쉽게 다운로드 할 수 있으면서, 본 개발자가 개별적인 업데이트를 제공 하더라도 기존의 DTH와 스마트앱스 사용자에게 문제가 발생하지 않고, 개발자가 다른 방법보다는 비교적 쉽게 호스팅을 할 수 있으며, 다른 사람도 직접 프로젝트 코드 파일을 다운로드 받아서 커스텀 혹은 후속 개발을 진행할 수 있는 장점이 있다.
SmartThings에서 공식적으로 지원하는 라이브러리 및 가이드 중 하나인 SmartThings Classic 도큐멘테이션에서도 SmartThings IDE와 GitHub와의 연동을 위한 문서가 작성되어있으니 더 세부적이고 자세한 정보를 알고싶다면 참고하는 것이 좋다. 단, 이 도큐멘트 문서는 오래되었고, 이후 SmartThings IDE에 많은 업데이트가 진행되었으므로, 현재의 SmartThings IDE에서 진행하는 깃허브 연동에 대한 내용과 완전히 동일하지는 않다.
깃허브 계정을 SmartThings IDE와 연동하는 방법은 다음과 같다.
- 1. Git Hub에 접속해서 깃허브 계정을 생성한다.
- 2. SmartThings IDE에 접속해서 PC의 경우 [My SmartApps] → [Enable GitHub Integration] → [Next] → [Authorize SmartThingsCommunity]에서, 모바일의 경우 [네비게이션 메뉴] → [Enable GitHub Integration] → [Next] → [Authorize SmartThingsCommunity]에서 SmartThings와 깃허브 계정을 인증하기 전 단계를 완료한다.
- 3. 깃허브 계정을 로그인해서 SmartThings IDE에 깃허브 계정을 인증한다.
====# 스마트앱스 설치 (지원 중단) #====
- 1. 깃허브에 올라온 스마트앱스 중에 설치를 원하는 스마트앱스가 올라온 저장소(repository, 레파지토리)[2]의 링크 혹은 깃허브의 파인더 검색결과를 통해 저장소에 접근한다.
- 2. 저장소(repository, 레파지토리)가 올라와 있는 페이지에 접속했다면 [Fork]를 누른다. 이 때 깃허브 개인 계정에 저장소(repository, 레파지토리)가 통합된다.
- 3. SmartThings IDE에 접속해서 PC의 경우 [My SmartApps] → [Update from Repo]에서, 모바일의 경우 [네비게이션 메뉴] → [SmartApps] → [Next] → [Authorize SmartThingsCommunity]에서 깃허브의 개인 계정에 통합시킨 저장소(repository, 레파지토리)가 SmartThings에서도 표시된 것을 확인할 수 있다. 해당 스마트앱스를 클릭한다.
- 4.스마트앱스를 클릭하면 뜨는 'Update From Repo - (스마트앱스 이름)' 팝업에서 'New (Only in GitHub)'에 있는 폴더 중 필요한 폴더를 선택한다. 이후 [Publish 체크] → [Execute Update]를 누르면 SmartThings에 스마트앱스 설치가 완료된다.
- 5.SmartApps에 설치 된 스마트앱스의 제일 왼쪽 차트에 있는 수정 아이콘을 클릭한 이후 → [OAuth] → [Enable OAuth in a Smart App]에서 사용자 인증을 완료할 수 있다.
- 6.SmartApps에 Namespace / Name에 있는 스마트앱스의 이름을 클릭한 이후 → [Publish] → [For Me]를 통해 나의 스마트앱스를 만들 수 있다.
- 7.SmartThings 앱에서 [라이프] → [추가]를 들어가면 내 스마트앱스 리스트에 스마트앱스가 표시된다. 해당 스마트앱스를 클릭하고 Choose a security password for your dashboard에서 대시보드의 비밀번호를 설정하면 설치가 완료된다.
====# Device Type Handler 설치 (지원 중단) #====
DTH(Device Type Handler)는 SmartThings 스마트앱스와 기기 사이에 필요한 명령을 정확한 형식으로 변환하기 위해 제품의 타입을 인식하는 드라이버 프로그램이다.
SmartThings가 생산하거나, Works With SmartThings, SmartThings Compatible 인증이 있는 제품들은 모두 SmartThings를 위한 DTH가 서버에 미리 등록되어 있기 때문에, 별도의 DTH 설치 없이도 허브에 바로 연결할 수 있다. 하지만 Works with SmartThings 인증이 없고, Zigbee나 Z-Wave 등 SmartThings Hub가 인식할 수 있는 통신규격을 사용하는 IoT 제품을 SmartThings에 연결하고 싶거나, 기존의 연결방식을 더 개선하기 위해 추가하는 목적으로 DTH를 수정해야 하는 경우, SmartThings IDE에서 DTH를 별도로 설치하면 SmartThings Hub가 제품을 올바른 타입으로 인식해서 연결을 할 수 있다.DTH는 스마트앱스처럼 사용자가 직접 제작해서 설치할 수도 있고, 깃허브나 다른 장소에 올려진 DTH를 SmartThings에 불러와서 설치할 수도 있다.
====# webCoRE (지원 중단) #====
6. SmartThings Edge
6.1. SmartThings Edge Driver
7. SmartThings API
SmartThings API는 커스텀 SmartApp을 만들 수 있는 API와 인터페이스이다. SmartThings 고유의 Capability와 명령어 셋을 적용하여 SmartApp을 만들어 복잡한 자동화나 기기 등록과 다양한 서비스를 만들 수 있다.7.1. Rules API
7.2. Scenes API
8. pysmartthings
9. Samsung Developers
그 밖의 SmartThings의 개발 관련 정보는 Samsung Developers에서 볼 수 있다.
[1] 이후 SmartThings Classic ID를 갖고 있는 사람은 계속 접속 할 수 있으나, SmartThings Classic 계정의 신규 발행은 불가능하다. SmartThings Hub가 2세대부터 삼성계정으로 연동되기 시작하고, 특히 SmartThings Hub 3세대는 완전히 삼성 계정과 SmartThings앱에 포함되면서, 더 이상 신규 발행할 필요가 없고, 그냥 삼성 계정으로 로그인 하면 된다.[2] 프로젝트 파일이 업로드 된 페이지를 깃허브에서는 저장소(repository, 레파지토리)라고 부른다. 전체 공개 설정을 해 둔 클라우드 스토리지의 공유 폴더와 비슷하다.