SmartWeb

1. Przegląd

SmartWeb to lokalna aplikacja serwera mostu działająca na urządzeniach z systemem Android.

Jej główne zastosowania to:

- Sprawdza status uwierzytelniania SmartThings i wspomaga powiązane wywołania API.

- Zapewnia ogólną funkcjonalność proxy HTTP.

- Umożliwia otwarcie strony w rzeczywistym WebView (przeglądarce) w celu odczytania ostatecznego kodu HTML.

- Działa jako pośrednik dla sterowników SmartThings Edge, lokalnych stron internetowych i skryptów automatyzacji.

2. Informacje podstawowe

- Domyślny port: 8088

- Domyślny format adresu: http://deviceIP:8088

Przykład:

- http://192.168.219.137:8088

3. Układ ekranu

3.1 Karta Serwer

Na karcie Serwer można sprawdzić status serwera mostu i dowiedzieć się, jak korzystać z kluczowych interfejsów API.

Przykłady wyświetlanej zawartości:

- Adres serwera mostu

- Format użycia /api/forward

- Format użycia /api/web

- API sprawdzania statusu uwierzytelniania SmartThings

- API wykonywania w tle WebView

3.2 Karta Ustawienia

Na karcie Ustawienia można sprawdzić ustawienia środowiska i status wymagany do korzystania z aplikacji.

Przykłady:

- Status wyjątku optymalizacji baterii

- Status uprawnień do powiadomień

- Wyświetlanie/kopiowanie logów

- Informacje o wersji aplikacji

4. Kluczowe interfejsy API

4.1 POST /api/ping

Opis: Krótko sprawdza status serwera mostu i status uwierzytelniania SmartThings.

Metoda:

- Tylko POST

Przykład:

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

Przykładowa odpowiedź:

{

"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

Opis:

Zwraca listę urządzeń SmartThings w prostym formacie.

Metoda:

- Tylko GET

Przykład:

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

Przykładowa odpowiedź:

{

"items": [

{

"deviceId": "...",

"label": "Google Home Mini Library",

"name": "Google Home"

}

]

}

Zastosowanie:

- Wyszukiwanie deviceId po nazwie urządzenia

- Wyszukiwanie nazw głośników

- Wybieranie urządzeń na podstawie etykiet

4.3 GET /api/forward?url=origin_address

Opis:

Standardowy serwer proxy HTTP.

Metoda:

- Tylko GET

Przykład:

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

Zastosowanie:

- Wywołania API JSON

- Odczyt statycznych stron HTML

- Wywołania API REST SmartThings

Funkcje:

- Przekazuje większość nagłówków żądań

- Automatycznie używa danych uwierzytelniających, jeśli brakuje nagłówka Authorization podczas wywoływania API SmartThings

- Nie wykonuje JavaScript

- Może być słaby w przypadku stron walidacji Cloudflare/przeglądarki

Uwaga:

- Nieodpowiednie dla witryn wymagających wykonania JavaScript

4.4 GET lub POST /api/web?url=origin_address

Opis: Otwiera stronę w rzeczywistym WebView i zwraca ostateczny kod HTML.

Metoda:

- GET lub POST

Zastosowanie:

- Witryny wymagające wykonania JavaScript

- Strony walidacji Cloudflare

- Witryny nie wczytane przez /api/forward

Przykład:

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

Lub:

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

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

Odpowiedź:

- Ostateczna treść HTML (text/html) w przypadku powodzenia

- Ciąg znaków błędu w przypadku niepowodzenia

Cechy:

- Otwiera stronę jak w prawdziwej przeglądarce

- Możliwe wykonanie JavaScript

- Powolne, ale stabilne

Parametry limitu czasu:

- limit czasu: sekundy

- limit czasu: sekundy

- timeoutSeconds: sekundy

- timeoutMs: milisekundy

Przykład:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

Uwaga:

- Odpowiedzią jest sam kod HTML, a nie JSON.

- Wywołujący musi przeanalizować kod HTML, aby uzyskać niezbędne wartości.

4.5 GET lub POST /api/webview/run

Opis:

Uruchamia stronę w widoku WebView w tle przez określony czas.

Metoda:

- GET lub POST

Zastosowanie:

- Utrzymuje działanie określonej strony w tle przez określony czas.

- Utrzymuje wykonywanie operacji JS/strony.

Przykład:

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

Funkcje:

- Uruchamia do 5 stron jednocześnie.

- Nadmiarowe żądania są przechowywane w kolejce.

4.6 GET /api/webview/stop

Opis:

Zatrzymuje wykonywanie obiektu WebView działającego w tle.

Metoda:

- Obecnie używana jako GET

5. Różnica między /api/forward a /api/web

/api/forward

- Standardowy serwer proxy HTTP

- Szybki

- Odpowiedni dla wywołań JSON/API

- Nie wykonuje JavaScript

- Odpowiedni dla stron statycznych/ogólnych API

/api/web

- Odczyt z przeglądarki oparty na WebView

- Powolny, ale stabilny

- Wykonywalny JavaScript

- Obsługuje strony Cloudflare/walidacji przeglądarki

- Odpowiedni dla stron wymagających przeglądarki

Zalecane kryteria:

- Ogólne API/Strony statyczne: /api/forward

- Strony, które muszą być otwierane w przeglądarce: /api/web

6. Podsumowanie dozwolonych metod

Tylko POST

- /api/ping

- /api/smartthings/token

- /api/smartthings/access-token

Tylko GET

- /api/smartthings/devices

- /api/forward

GET lub POST

- /api/web

- /api/webview/run

Zatrzymywanie

- /api/webview/stop

7. Wyjaśnienie wartości bridgeDevice

Urządzenie bridgeDevice dla /api/ping to jedno z poniższych:

- tv

- pad

- phone

Kryteria określenia:

- tv: Android TV / urządzenia Leanback

- pad: lowestScreenWidthDp ≥ 600

- phone: Others

8. Przykłady użycia

8.1 Sprawdź stan serwera

POST /api/ping

8.2 Sprawdź listę urządzeń

GET /api/smartthings/devices

8.3 Ogólny serwer proxy API

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

8.4 Odczyt stron wymaga przeglądarki

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

9. Podsumowanie

SmartWeb to lokalny serwer pomostowy działający na urządzeniach z systemem Android.

Kluczowe punkty:

- Sprawdź status uwierzytelniania SmartThings

- Proste API listy urządzeń

- Standardowy serwer proxy HTTP (/api/forward)

- Odczyt w przeglądarce oparty na WebView (/api/web)

- Uruchom WebView w tle (/api/webview/run)

W szczególności funkcja /api/web umożliwia odczyt stron, które trudno odczytać za pomocą standardowych żądań HTTP, przy użyciu rzeczywistej metody przeglądarki.