v1.1.0

[v1.1.0] - 2026-09-22

SmartThings를 위한 전용 Edge 드라이버와, 그 드라이버가 쓰는 서비스 API /st/v1이 추가되었습니다. 설계 문서: docs/design/edge-driver.md.

기존 PCControl 드라이버 호환 경로(/{secret}/{command})는 그대로입니다. 옮겨 갈 의무는 없습니다.

SmartThings Edge 드라이버 (edge/)

Edge 드라이버는 이 릴리스의 레포에 포함되어 있지만 채널 공개는 추가 실기 테스트 뒤에 별도 태그(edge-v1.0.0)로 진행합니다. 그때까지 SmartThings 연동은 기존 PCControl 드라이버로 그대로 쓸 수 있습니다.

• 허브 안에서 로컬로 도는 Lua 5.3 드라이버. 장치 하나가 PC 하나이며 자식 장치는 만들지 않습니다 (#71 #81)
• 실제 전원 상태 — 켜짐 · 절전 · 최대 절전 · 꺼짐 · 깨우는 중 · 종료 대기. 스위치는 전원 상태에서 파생되므로 실제와 어긋나지 않습니다 (#71 #72)
• 커스텀 capability 여섯 — pcPower(전원 상태), pcExec(명령 실행과 마지막 실행), pcDelay(예약 표시·취소와 예약할 명령), pcUser(잠금·유휴, 옵트인), pcInfo(연결·업데이트·WoL·안내), pcVersion(버전 줄) (#72 #86)
• 상세 화면은 두 카드 — 위에 상태(전원 상태 · 마지막 실행 · 예약 요약 · 세션 · 상태 · 버전), 아래에 조작(명령 · 예약할 명령 · 예약 시간). 모든 줄이 값을 가집니다 (#78 #82 #85 #86)
• 명령 목록에서 깨우기 · 절전 · 최대 절전 · 재시작 · 종료 · 잠금 · 화면 끄기 · 화면 켜기를 실행하고, 유예를 따를지는 버튼 실행 방식 환경설정이 정합니다 (#82 #84)
• 예약은 명령과 시간을 각각 고르고, 시간 목록의 취소가 예약을 지웁니다. 프리셋은 5 · 10 · 15 · 30 · 45분, 1 · 1.5 · 2 · 3 · 4 · 6 · 8 · 12시간, 1 · 2 · 3일 — 최대 72시간이고 앱 예약 탭 · WebUI · 텔레그램도 같은 상한을 씁니다. 예약 요약은 한 시간부터 "2시간 후", 하루부터 "1일 3시간 후"로 읽습니다. 두 목록 모두 고르지 않고 닫으면 아무 일도 일어나지 않습니다 (#84 #85 #88 #89)
• 버전 줄 — "v1.1.0 · 드라이버 1.0". 장치의 화면은 추가 시점의 정의로 굳으므로, 화면이 바뀔 때마다 프로필 이름 버전이 올라갑니다(현재 pc.v15) (#85 #86 #87 #88 #89)
• 값 문구는 프레젠테이션에 "켜짐 (On)"처럼 한국어·영어를 병기합니다. 앱이 번역 파일의 속성 값 라벨을 쓰지 않는 것이 확인됐습니다 (#83)
• Wake-on-LAN — 매직 패킷을 즉시 · 2초 뒤 · 5초 뒤, 포트 7과 9로 보내고 90초 안에 응답이 없으면 실패를 알립니다. MAC은 비워 두면 서비스가 보고한 어댑터를 씁니다 (#73)
• SSDP 자동 검색으로 장치를 만들고, machine_id로 중복을 막고, followDiscovery로 DHCP 주소 변화를 따라갑니다 (#73)
• 프레젠테이션이 바뀌면 프로필 이름 버전을 올리고, 기존 장치는 첫 init에서 현재 프로필로 자동 이전됩니다 (#79 #82 #83 #84 #85 #86)
• 환경설정 — IP · 검색 따라가기 · 포트 · 시크릿 · MAC · WoL 브로드캐스트 · 상태 확인 주기 · 스위치 끄기 동작 · 버튼 실행 방식 · 문구 언어. 제목과 설명은 한국어에 영어 병기 (#78)
• CI — edge/** 변경마다 Lua 테스트와 문법 검사, edge-vX.Y.Z 태그에서 src/driver_version.lua와 태그 일치 검증 후 패키징 → 채널 배정 → 릴리스 자산 첨부 (#74)
• 배포 도구 — 네임스페이스 일괄 적용 tools/apply-namespace.js, capability 생성 tools/create-capabilities.sh, 정의·프레젠테이션·번역 갱신 tools/sync-capabilities.sh (#74 #78)

서비스 /st/v1 API (#67)

• GET /st/v1/status — 전원 · 유예 · 예약 · 마지막 명령 · 업데이트 · WoL 어댑터 · 디스플레이 · 세션을 한 덩어리로
• POST /st/v1/command — 명령 + 모드(default / immediate / grace) + 분(0~4320, 0보다 크면 예약) (#89)
• DELETE /st/v1/schedule — 예약 취소
• 헤더 인증 — 시크릿을 URL이 아니라 X-PC-Secret으로 받습니다. 불일치 401, 허용 목록 밖 403, 초당 10회 초과 429
• 예약 출처 smartthings — SmartThings에서 건 예약이 앱 · 트레이 · 텔레그램 어디서나 "SmartThings"로 표시됩니다

푸시 구독 (#68)

• POST /st/v1/subscribe로 허브가 콜백을 등록하면 전원 · 예약 · 원격 명령 · 시스템 · 디스플레이 · 세션 이벤트를 즉시 보냅니다. TTL 60~3600초(기본 600), 드라이버는 80%에 갱신합니다
• 매 이벤트에 전체 status를 실어 드라이버가 차이를 계산하지 않습니다
• power.stopping은 종료 · 재시작 · 절전 · 최대 절전을 구분해 동기로(최대 1.5초) 보냅니다. 그래서 타일이 "꺼짐"이 아니라 "절전"을 표시합니다
• 콜백은 http://이고 호스트가 요청 출처 IP와 같은 사설 대역이어야 합니다. 전송 실패가 연속 3회면 구독을 지웁니다
• 알림 카테고리 필터와 조용한 시간대는 장치 상태 푸시에 적용되지 않습니다(알림이 아니라 상태이므로)

SSDP 자동 검색 (#69 #76)

• urn:smartthings-pc-control:device:pc:1에 대한 M-SEARCH에 응답하고, M-SEARCH를 받은 인터페이스의 주소로 LOCATION을 만듭니다
• 무인증 GET /st/v1/description — 프로토콜 · machine_id · 호스트명 · 버전 · 포트 · 시크릿 설정 여부만 반환합니다
• 방화벽 규칙 SmartThings PC Control SSDP(인바운드 UDP 1900)를 설치 시 추가하고, smartthings.discovery가 켜져 있는 한 서비스 시작마다 확인합니다 (#76)

GUI (#70)

• 네트워크 탭에 SmartThings 섹션 — 연결된 허브(IP · 드라이버 버전 · 마지막 확인), 토글 자동 검색(SSDP) 허용 / 세션 정보 노출(잠금·유휴) / 사용자 이름 포함, 허브 허용 목록과 [현재 허브 추가] · [삭제]
• 시크릿이 비어 있으면 설정을 권하는 안내를 표시합니다
• 새 API — GET /api/st/hub(연결된 허브 정보), GET /api/telegram/state(폴링 · 409 충돌 상태)

세션 유휴 시간 (#77)

• 트레이 앱이 30초마다 POST /api/session/heartbeat로 유휴 시간을 올리고, 서비스는 90초 이내 값만 상태에 싣습니다. 서비스는 세션 0에 있어 직접 잴 수 없기 때문입니다
• 잠금 여부와 사용자 이름은 트레이 앱과 무관하게 동작합니다. 유휴 변화는 푸시로 보내지 않습니다

텔레그램 (#75)

• 모든 알림과 봇 답장이 🖥 <PC 이름> 줄로 시작합니다. 이름은 telegram.pc_name, 비어 있으면 호스트 이름
• 여러 PC가 같은 봇 토큰으로 getUpdates를 돌면 텔레그램이 한 쪽만 허용합니다. 이 409 충돌을 감지해 로그와 알림 탭에 경고하고 폴링 백오프를 늘립니다. 방침: 봇 하나 = PC 하나

새 명령

• turnscreenon — 꺼진 모니터를 다시 켭니다(로그인 세션 필요). /st/v1/command와 레거시 경로 양쪽에서 쓸 수 있습니다
• 텔레그램 /screenon — 같은 명령의 단축키. /lock · /screenoff와 함께 확인 없이 실행되는 안전 명령입니다

설정

• smartthings.discovery(기본 true) — SSDP 응답 on/off
• smartthings.allowed_hubs(기본 []) — /st/v1을 쓸 수 있는 허브 IP. 비어 있으면 모두 허용
• smartthings.expose_session / expose_session_user(기본 false) — 잠금·유휴 시간 노출과 사용자 이름 포함
• telegram.pc_name(기본 "") — 메시지 머리말의 PC 이름. 비면 호스트 이름
• smartthings.*는 모두 핫 리로드입니다(재시작 불필요)

업그레이드 안내

• 기존 설치본은 앱의 [지금 업데이트]로 올리면 됩니다. config.json은 그대로 호환되고 smartthings 블록은 기본값으로 채워집니다
• 방화벽 규칙이 하나 늘어납니다 — 자동 검색이 켜져 있으면(기본) 서비스가 시작할 때 인바운드 UDP 1900 규칙을 추가합니다. install을 다시 돌릴 필요는 없습니다. 원하지 않으면 네트워크 탭에서 자동 검색(SSDP) 허용을 끄세요(이미 만들어진 규칙은 uninstall 때 삭제됩니다)
• 기존 PCControl 드라이버 사용자는 아무것도 하지 않아도 됩니다. 레거시 경로와 응답은 바뀌지 않았고, 두 드라이버를 같은 PC에 동시에 붙여도 서로 방해하지 않습니다
• 새 드라이버를 쓰려면 서비스가 v1.1.0 이상이어야 합니다. 그 아래 버전에 연결하면 드라이버가 버전 불일치로 표시합니다
• 텔레그램을 여러 PC에서 쓰고 있었다면 봇을 PC마다 분리하세요. 같은 토큰을 공유하면 한 PC만 명령을 받습니다

Full Changelog: v1.0.0...v1.1.0