SmartWeb

1. Panoramica

SmartWeb è un'app server bridge locale che viene eseguita su dispositivi Android.

I suoi scopi principali sono i seguenti:

- Verifica lo stato di autenticazione di SmartThings e assiste nelle chiamate API correlate.

- Fornisce funzionalità proxy HTTP generali.

- Consente di aprire una pagina in una WebView (browser) per leggere l'HTML finale.

- Funge da intermediario per i driver SmartThings Edge, le pagine web locali e gli script di automazione.

2. Informazioni di base

- Porta predefinita: 8088

- Formato indirizzo predefinito: http://IPdispositivo:8088

Esempio:

- http://192.168.219.137:8088

3. Layout della schermata

3.1 Scheda Server

Nella scheda Server, è possibile verificare lo stato del server bridge e come utilizzare le API principali.

Esempi di contenuti visualizzati:

- Indirizzo del server bridge

- Formato di utilizzo /api/forward

- Formato di utilizzo /api/web

- API per la verifica dello stato di autenticazione di SmartThings

- API per l'esecuzione di WebView in background

3.2 Scheda Impostazioni

Nella scheda Impostazioni, è possibile verificare le impostazioni dell'ambiente e lo stato necessari per l'utilizzo dell'app.

Esempi:

- Stato dell'eccezione di ottimizzazione della batteria

- Stato dell'autorizzazione alle notifiche

- Visualizzazione/copia dei log

- Informazioni sulla versione dell'app

4. API principali

4.1 POST /api/ping

Descrizione: Verifica brevemente lo stato del server bridge e lo stato di autenticazione di SmartThings.

Metodo:

- Solo POST

Esempio:

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

Esempio di risposta:

{

"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

Descrizione:

Restituisce un elenco di dispositivi SmartThings in un formato semplice.

Metodo:

- Solo GET

Esempio:

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

Esempio di risposta:

{

"items": [

{

"deviceId": "...",

"label": "Google Home Mini Library",

"name": "Google Home"

}

]

}

Utilizzi:

- Per trovare l'ID del dispositivo in base al nome del dispositivo

- Per cercare i nomi degli altoparlanti

- Per selezionare i dispositivi in ​​base alle etichette

4.3 GET /api/forward?url=origin_address

Descrizione:

Un proxy HTTP standard.

Metodo:

- Solo GET

Esempio:

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

Utilizzi:

- Chiamate API JSON

- Lettura di pagine HTML statiche

- Chiamate API REST di SmartThings

Caratteristiche:

- Trasmette la maggior parte delle intestazioni di richiesta

- Utilizza automaticamente le credenziali se l'intestazione Authorization è mancante durante le chiamate alle API di SmartThings

- Non esegue JavaScript

- Potrebbe essere vulnerabile alle pagine di convalida di Cloudflare/browser

Attenzione:

- Non adatto a siti che richiedono l'esecuzione di JavaScript

4.4 GET o POST /api/web?url=indirizzo_di_origine

Descrizione: Apre la pagina in una WebView e restituisce l'HTML finale.

Metodo:

- GET o POST

Utilizzo:

- Siti che richiedono l'esecuzione di JavaScript

- Pagine di validazione di Cloudflare

- Siti non caricati tramite /api/forward

Esempio:

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

Oppure:

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

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

Risposta:

- Corpo HTML finale (text/html) in caso di successo

- Stringa di errore in caso di errore

Caratteristiche:

- Apre la pagina come un vero browser

- Possibilità di esecuzione di JavaScript

- Lento ma robusto

Parametri di timeout:

- timeout: secondi

- timeoutSeconds: secondi

- timeoutMs: millisecondi

Esempio:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

Nota:

- La risposta è il corpo HTML stesso, non JSON.

- Il chiamante deve analizzare l'HTML per ottenere i valori necessari.

4.5 GET o POST /api/webview/run

Descrizione:

Esegue una pagina in una WebView in background per un periodo di tempo predefinito.

Metodo:

- GET o POST

Utilizzi:

- Mantenere una pagina specifica in esecuzione in background per un periodo di tempo predefinito.

- Mantenere attive le operazioni JavaScript/l'esecuzione della pagina.

Esempio:

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

Caratteristiche:

- Esegue fino a 5 pagine contemporaneamente.

- Le richieste in eccesso vengono memorizzate in una coda.

4.6 GET /api/webview/stop

Descrizione:

Interrompe l'esecuzione di una WebView in background.

Metodo:

- Attualmente utilizzato come GET

5. Differenza tra /api/forward e /api/web

/api/forward

- Proxy HTTP standard

- Veloce

- Adatto per chiamate JSON/API

- Non esegue JavaScript

- Adatto per pagine statiche/API generiche

/api/web

- Lettura tramite browser basata su WebView

- Lento ma robusto

- Eseguibile JavaScript

- Supporta Cloudflare/pagine di validazione del browser

- Adatto per pagine che richiedono un browser

Criteri consigliati:

- API generiche/pagine statiche: /api/forward

- Pagine che devono essere aperte in un browser: /api/web

6. Riepilogo dei metodi consentiti

Solo POST

- /api/ping

- /api/smartthings/token

- /api/smartthings/access-token

Solo GET

- /api/smartthings/devices

- /api/forward

GET o POST

- /api/web

- /api/webview/run

Per arrestare

- /api/webview/stop

7. Spiegazione del valore bridgeDevice

Il bridgeDevice per /api/ping può essere uno dei seguenti:

- tv

- pad

- phone

Criteri di determinazione:

- tv: dispositivi Android TV / Leanback

- pad: smallestScreenWidthDp >= 600

- phone: altri

8. Esempi di utilizzo

8.1 Verifica dello stato del server

POST /api/ping

8.2 Verifica dell'elenco dei dispositivi

GET /api/smartthings/devices

8.3 Proxy API generale

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

8.4 Lettura dei siti che richiedono un browser

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

9. Riepilogo

SmartWeb è un server bridge locale in esecuzione su dispositivi Android.

Punti chiave:

- Verifica dello stato di autenticazione di SmartThings

- Semplice API per l'elenco dei dispositivi

- Proxy HTTP standard (/api/forward)

- Lettura tramite browser basata su WebView (/api/web)

- Esecuzione di WebView in background (/api/webview/run)

In particolare, la funzione /api/web consente di leggere pagine difficili da leggere tramite richieste HTTP standard, utilizzando un metodo di lettura simile a quello di un browser.