1. 개요
SmartWeb은 안드로이드 기기에서 동작하는 로컬 브리지 서버 앱입니다.
주요 목적은 다음과 같습니다.
- SmartThings 인증 상태를 확인하고 관련 API 호출을 돕습니다.
- 일반 HTTP 프록시 기능을 제공합니다.
- 실제 WebView(브라우저)로 페이지를 열어 최종 HTML을 읽어올 수 있습니다.
- SmartThings Edge 드라이버, 로컬 웹페이지, 자동화 스크립트의 중계 역할을 합니다.
2. 기본 정보
- 기본 포트: 8088
- 기본 주소 형식: http://기기IP:8088
http://192.168.219.137:8088
3. 화면 구성
3.1 서버 탭
서버 탭에서는 브리지 서버의 상태와 주요 API 사용법을 확인할 수 있습니다.
표시되는 내용 예:
- 브리지 서버 주소
- /api/forward 사용 형식
- /api/web 사용 형식
- SmartThings 인증 상태 확인 API
- 백그라운드 WebView 실행 API
3.2 설정 탭
설정 탭에서는 앱 사용에 필요한 환경 설정과 상태를 확인할 수 있습니다.
예:
- 배터리 최적화 예외 여부
- 알림 권한 상태
- 로그 보기/복사
- 앱 버전 정보
4. 주요 API
4.1 POST /api/ping
설명:
브리지 서버 상태와 SmartThings 인증 상태를 간단히 확인합니다.
메서드:
- POST만 허용
POST http://기기IP:8088/api/ping
응답 예:
{
"battery": 86,
"bridgeDevice": "phone",
"bridgeVersion": "2026.05.15",
"serverStartTime": "05/14 03:00",
"stOauthConnected": true,
"accessTokenExpiresAt": 1778773965000,
"accessTokenMinutesLeft": 1332
}
필드 설명:
- battery: 현재 배터리 퍼센트
- bridgeDevice: tv, pad, phone 중 하나
- bridgeVersion: 앱 버전 문자열
- serverStartTime: 브리지 서버 시작 시각
- stOauthConnected: SmartThings 인증 여부
- accessTokenExpiresAt: access token 만료 시각(ms)
- accessTokenMinutesLeft: access token 남은 시간(분)
4.2 POST /api/smartthings/token
설명:
SmartThings 인증 정보를 브리지 서버에 전달합니다.
메서드:
- POST만 허용
용도:
- 외부 인증 처리 후 브리지 서버에 인증 정보를 반영할 때 사용
4.3 POST /api/smartthings/access-token
설명:
현재 SmartThings 인증 상태와 access token 정보를 조회합니다.
로컬에서만 호출이 가능합니다.
메서드:
- POST만 허용
POST http://기기IP:8088/api/smartthings/access-token
응답 예:
{
"authenticated": true,
"expiresAt": 1778773965000,
"minutesLeft": 1332,
"accessToken": "..."
}
필드 설명:
- authenticated: SmartThings 인증 여부
- expiresAt: access token 만료 시각(ms)
- minutesLeft: access token 남은 시간(분)
- accessToken: 현재 access token
4.4 GET /api/smartthings/devices
설명:
SmartThings 기기 목록을 간단한 형태로 반환합니다.
메서드:
- GET만 허용
GET http://기기IP:8088/api/smartthings/devices
사용예:
http://192.168.219.137:8088/api/smartthings/devices
http://192.168.219.137:8088/api/smartthings/devices?type=LAN
http://192.168.219.137:8088/api/smartthings/devices?type=MATTER&capability=switch
http://192.168.219.137:8088/api/smartthings/devices?type=EDGE_CHILD&capability=switch
http://192.168.219.137:8088/api/smartthings/devices?capability=speechSynthesis
응답 예:
{
"items":[
{"deviceId":"...","label":"구글홈미니 서재"},
{"deviceId":"...","label":"빅스비(서재)"},
{"deviceId":"...","label":"거실 불"},
{"deviceId":"...","label":"거실 콘센트"},
{"deviceId":"...","label":"가스 밸브"},
{"deviceId":"...","label":"인덕션"},
{"deviceId":"...","label":"안방 난방"},
{"deviceId":"...","label":"환풍기"},
{"deviceId":"...","label":"안방 선풍기"},
{"deviceId":"...","label":"에어모니터"}
]
}
용도:
- 기기 이름으로 deviceId를 찾을 때
- 스피커 이름 검색
- 라벨 기반 기기 선택
4.5 POST /api/forward?url=원본주소
설명:
일반 HTTP 프록시입니다.
메서드:
- POST만 허용
POST http://기기IP:8088/api/forward?url=https://api.smartthings.com/v1/devices
용도:
- JSON API 호출
- 정적 HTML 페이지 읽기
- SmartThings REST API 호출
특징:
- 요청 헤더 대부분 전달
- SmartThings API 호출 시 Authorization 헤더가 없으면 인증 정보를 자동 사용
- JavaScript 실행은 하지 않음
- Cloudflare/브라우저 검증 페이지에는 약할 수 있음
주의:
- JavaScript 실행이 필요한 사이트에는 적합하지 않음
4.6 GET 또는 POST /api/web?url=원본주소
설명:
실제 WebView로 페이지를 열고 최종 HTML을 반환합니다.
메서드:
- GET 또는 POST
용도:
- JavaScript 실행이 필요한 사이트
- Cloudflare 검증 페이지
- /api/forward로 읽히지 않는 사이트
GET http://기기IP:8088/api/web?url=https://www.timeanddate.com/astronomy/@37.57,126.97
또는
POST http://기기IP:8088/api/web
Content-Type: application/json
{
"url": "https://www.timeanddate.com/astronomy/@37.57,126.97",
"timeout": 20
}
응답:
- 성공 시 최종 HTML 본문(text/html)
- 실패 시 에러 문자열
특징:
- 실제 브라우저처럼 페이지를 엶
- JavaScript 실행 가능
- 느리지만 강함
타임아웃 파라미터:
- timeout: 초
- timeoutSeconds: 초
- timeoutMs: 밀리초
예:
- ?timeout=20
- ?timeoutSeconds=20
- ?timeoutMs=20000
주의:
- 응답은 JSON이 아니라 HTML 본문 자체
- 필요한 값은 호출한 쪽에서 HTML 파싱 필요
4.7 GET 또는 POST /api/webview?url=웹페이지주소
설명:
백그라운드 WebView에서 페이지를 실행하고, 페이지 JS가 window.__result에 결과를 저장할 때까지 동기적으로 대기한 뒤 JSON으로 반환합니다.
엣지드라이버에서 허브에 생성한 웹 페이지를 호출하여 JS 코드를 실행하는 용도로 사용합니다.
해당 웹페이지에 JS 코드를 작성하면, Lua로 구현하기 어렵거나 느린 코드를 안드로이드 앱에서 빠르게 처리할 수 있습니다.
메서드:
- GET 또는 POST
용도:
외부 API/페이지에서 데이터를 수집하여 Lua로 반환 (예: 날씨 정보 수집)
JS로만 처리 가능한 로직을 웹페이지에 위임하여 결과를 동기적으로 수신
GET http://기기IP:8088/api/webview/run?url=http://허브주소:포트&timeout=60
동작 방식 (기본: 동기 모드):
- 백그라운드 WebView에서 지정한 URL의 페이지를 로드
- 페이지 JS 실행 완료 후 window.__result.ok 가 true 또는 false로 세팅되면 즉시 반환
- timeout 내에 window.__result가 세팅되지 않으면 오류 반환
비고:
async=true 파라미터를 전달하면 결과를 기다리지 않고 즉시 {"result":"ok"}를 반환하는 비동기(fire-and-forget) 모드로 동작
페이지는 window.__result = { ok: true, ... } 형식으로 결과를 저장해야 함
5. /api/forward 와 /api/web 차이
/api/forward
- 일반 HTTP 프록시
- 빠름
- JSON/API 호출에 적합
- JavaScript 실행 안 함
- 정적 페이지/일반 API에 적합
/api/web
- WebView 기반 브라우저 읽기
- 느리지만 강함
- JavaScript 실행 가능
- Cloudflare/브라우저 검증 페이지 대응
- 브라우저가 필요한 페이지에 적합
권장 기준:
- 일반 API/정적 페이지: /api/forward
- 브라우저로 실제 열어야 하는 페이지: /api/web
6. 메서드 허용 방식 요약
POST만
- /api/ping
- /api/smartthings/token
- /api/smartthings/access-token
- /api/forward
GET만
- /api/smartthings/devices
GET 또는 POST
- /api/web
- /api/webview
7. 사용 예시
7.1 서버 상태 확인
POST /api/ping
7.2 SmartThings 인증 상태 확인 (로컬에서만 호출 가능)
POST /api/smartthings/access-token
7.3 기기 목록 확인
GET /api/smartthings/devices
7.4 일반 API 프록시
GET /api/forward?url=https://api.smartthings.com/v1/devices
7.5 브라우저가 필요한 사이트 읽기
GET /api/web?url=https://www.timeanddate.com/astronomy/@37.53,126.64
8. 정리
SmartWeb은 안드로이드 기기 위에서 동작하는 로컬 브리지 서버입니다.
핵심 포인트:
- SmartThings 인증 상태 확인
- 간단한 기기 목록 API
- 일반 HTTP 프록시 (/api/forward)
- WebView 기반 브라우저 읽기 (/api/web)
- 백그라운드 WebView 실행 (/api/webview)
특히 /api/web 기능을 통해 일반 HTTP 요청으로는 읽기 어려운 페이지도
실제 브라우저 방식으로 읽어올 수 있습니다.