SmartThings Web Host

1. Tổng quan

SmartWeb là ứng dụng máy chủ cầu nối cục bộ chạy trên thiết bị Android.

Các mục đích chính của nó như sau:

- Kiểm tra trạng thái xác thực SmartThings và hỗ trợ các cuộc gọi API liên quan.

- Cung cấp chức năng proxy HTTP tổng quát.

- Cho phép bạn mở một trang trong WebView (trình duyệt) thực tế để đọc HTML cuối cùng.

- Hoạt động như một trung gian cho trình điều khiển SmartThings Edge, các trang web cục bộ và các tập lệnh tự động hóa.

2. Thông tin cơ bản

- Cổng mặc định: 8088

- Định dạng địa chỉ mặc định: http://deviceIP:8088

Ví dụ:

- http://192.168.219.137:8088

3. Bố cục màn hình

3.1 Tab Máy chủ

Trong Tab Máy chủ, bạn có thể kiểm tra trạng thái của máy chủ cầu nối và cách sử dụng các API chính.

Ví dụ về nội dung hiển thị:

- Địa chỉ máy chủ cầu nối

- Định dạng sử dụng /api/forward

- Định dạng sử dụng /api/web

- API kiểm tra trạng thái xác thực SmartThings

- API thực thi WebView nền

3.2 Tab Cài đặt

Trong tab Cài đặt, bạn có thể kiểm tra các cài đặt môi trường và trạng thái cần thiết để sử dụng ứng dụng.

Ví dụ:

- Trạng thái ngoại lệ tối ưu hóa pin

- Trạng thái quyền thông báo

- Xem/sao chép nhật ký

- Thông tin phiên bản ứng dụng

4. Các API chính

4.1 POST /api/ping

Mô tả: Kiểm tra nhanh trạng thái máy chủ cầu nối và trạng thái xác thực SmartThings.

Phương thức:

- Chỉ POST

Ví dụ:

POST http://deviceIP:8088/api/ping

Ví dụ phản hồi:

{

"battery": 86,

"bridgeDevice": "phone",

"bridgeVersion": "Version: 2026.05.15",

"serverStartTime": "05/14 03:00",

"stOauthConnected": true,

"accessTokenExpiresAt": 1778773965000,

"accessTokenMinutesLeft": 1332

}

4.2 GET /api/smartthings/devices

Mô tả:

Trả về danh sách các thiết bị SmartThings ở định dạng đơn giản.

Phương thức:

- Chỉ GET

Ví dụ:

GET http://deviceIP:8088/api/smartthings/devices

Ví dụ phản hồi:

{

"items": [

{

"deviceId": "...",

"label": "Google Home Mini Library",

"name": "Google Home"

}

]

}

Công dụng:

- Khi tìm deviceId theo tên thiết bị

- Tìm kiếm tên loa

- Chọn thiết bị dựa trên nhãn

4.3 GET /api/forward?url=origin_address

Mô tả:

Một proxy HTTP tiêu chuẩn.

Phương thức:

- Chỉ GET

Ví dụ:

GET http://deviceIP:8088/api/forward?url=https://api.smartthings.com/v1/devices

Ứng dụng:

- Gọi API JSON

- Đọc các trang HTML tĩnh

- Gọi API REST của SmartThings

Tính năng:

- Truyền hầu hết các tiêu đề yêu cầu

- Tự động sử dụng thông tin xác thực nếu thiếu tiêu đề Authorization khi gọi API của SmartThings

- Không thực thi JavaScript

- Có thể yếu trước các trang xác thực của Cloudflare/trình duyệt

Lưu ý:

- Không phù hợp với các trang web yêu cầu thực thi JavaScript

4.4 GET hoặc POST /api/web?url=origin_address

Mô tả: Mở trang trong WebView thực tế và trả về HTML cuối cùng.

Phương thức:

- GET hoặc POST

Cách sử dụng:

- Các trang web yêu cầu thực thi JavaScript

- Trang xác thực của Cloudflare

- Các trang web không được tải qua /api/forward

Ví dụ:

GET http://deviceIP:8088/api/web?url=https://

Hoặc:

POST http://deviceIP:8088/api/web

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

Phản hồi:

- Nội dung HTML cuối cùng (text/html) khi thành công

- Chuỗi lỗi khi thất bại

Tính năng:

- Mở trang như một trình duyệt thực

- Có thể thực thi JavaScript

- Chậm nhưng mạnh mẽ

Tham số thời gian chờ:

- timeout: giây

- timeoutSeconds: giây

- timeoutMs: mili giây

Ví dụ:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

Lưu ý:

- Phản hồi là chính nội dung HTML, không phải JSON.

- Người gọi cần phân tích cú pháp HTML để lấy các giá trị cần thiết.

4.5 GET hoặc POST /api/webview/run

Mô tả:

Chạy một trang trong WebView nền trong một khoảng thời gian nhất định.

Phương thức:

- GET hoặc POST

Công dụng:

- Giữ cho một trang cụ thể chạy ngầm trong một khoảng thời gian nhất định.

- Giữ cho các thao tác JS/thực thi trang tiếp tục chạy.

Ví dụ:

GET http://deviceIP:8088/api/webview/run?url=http://hubaddress:port&timeout=60

Tính năng:

- Chạy đồng thời tối đa 5 trang.

- Các yêu cầu vượt quá được lưu trữ trong hàng đợi.

4.6 GET /api/webview/stop

Mô tả:

Dừng việc thực thi của một WebView chạy ngầm.

Phương thức:

- Hiện đang được sử dụng là GET

5. Sự khác biệt giữa /api/forward và /api/web

/api/forward

- Proxy HTTP tiêu chuẩn

- Nhanh

- Phù hợp cho các cuộc gọi JSON/API

- Không thực thi JavaScript

- Phù hợp cho các trang tĩnh/API chung

/api/web

- Đọc dữ liệu qua trình duyệt dựa trên WebView

- Chậm nhưng mạnh mẽ

- Có thể thực thi JavaScript

- Hỗ trợ các trang xác thực của Cloudflare/trình duyệt

- Phù hợp cho các trang yêu cầu trình duyệt

Tiêu chí được đề xuất:

- API chung/Trang tĩnh: /api/forward

- Các trang cần được mở trong trình duyệt: /api/web

6. Tóm tắt các phương thức được cho phép

Chỉ POST

- /api/ping

- /api/smartthings/token

- /api/smartthings/access-token

Chỉ GET

- /api/smartthings/devices

- /api/forward

GET hoặc POST

- /api/web

- /api/webview/run

Để dừng

- /api/webview/stop

7. Giải thích giá trị bridgeDevice

bridgeDevice cho /api/ping là một trong những thiết bị sau:

- TV

- Pad

- Phone

Tiêu chí xác định:

- TV: Thiết bị Android TV / Leanback

- Pad: smallestScreenWidthDp >= 600

- Phone: Khác

8. Ví dụ sử dụng

8.1 Kiểm tra trạng thái máy chủ

POST /api/ping

8.2 Kiểm tra danh sách thiết bị

GET /api/smartthings/devices

8.3 Proxy API chung

GET /api/forward?url=https://api.smartthings.com/v1/devices

8.4 Đọc các trang web yêu cầu trình duyệt

GET /api/web?url=https://

9. Tóm tắt

SmartWeb là một máy chủ cầu nối cục bộ chạy trên các thiết bị Android.

Các điểm chính:

- Kiểm tra trạng thái xác thực SmartThings

- API danh sách thiết bị đơn giản

- Proxy HTTP tiêu chuẩn (/api/forward)

- Đọc nội dung bằng trình duyệt dựa trên WebView (/api/web)

- Chạy WebView trong nền (/api/webview/run)

Đặc biệt, chức năng /api/web cho phép bạn đọc các trang khó đọc thông qua các yêu cầu HTTP tiêu chuẩn bằng phương pháp trình duyệt thực tế.