Přeskočit na hlavní obsah

GeoSnake - Webové Rozhraní API Dokumentace

Přehled​

Webové rozhraní je dostupné přes WiFi Access Point nebo při připojení k externí WiFi síti.

Výchozí přístup:

  • SSID: GeoSnake-Config
  • Heslo: geosnake123
  • URL: http://192.168.4.1

Rozhraní poskytuje REST API pro ovládání zařízení a webovou aplikaci s modernním grafickým rozhraním.

HTTP API Endpointy​

📄 Statické Soubory​

GET /​

Vrátí hlavní HTML stránku webového rozhraní.

GET /logo.svg​

Vrátí SVG logo Statotest.

Response:

  • Content-Type: image/svg+xml

📊 Status a Statistiky​

GET /api/status​

Vrátí aktuální stav měření a konfiguraci.

Response JSON:

{
  "measuring": true,
  "odr": 6,
  "range": 1,
  "frequency": 50.0,
  "rtc_time": "14:30:45",
  "firmware": "v1.2.0"
}

Pole:

  • measuring (boolean): Zda probíhá měření
  • odr (int): Hodnota ODR (0-10)
  • range (int): Měřící rozsah (1-3)
  • frequency (float): Cílová výstupní frekvence v Hz
  • rtc_time (string): Aktuální čas z RTC
  • firmware (string): Verze firmware

GET /api/stats​

Vrátí statistiky měření.

Response JSON:

{
  "total_samples": 125000,
  "files_created": 3,
  "elapsed_seconds": 8130,
  "elapsed_formatted": "2h 15m 30s",
  "write_errors": 0
}

GET /api/sd_info​

Vrátí informace o SD kartě.

Response JSON:

{
  "total": 34359738368,
  "free": 30601641984
}

Pole:

  • total (number): Celková kapacita v bajtech
  • free (number): Volné místo v bajtech

⚙️ Ovládání Měření​

GET /start​

Spustí měření akcelerometru.

Response:

OK

GET /stop​

Zastaví měření akcelerometru.

Response:

OK

GET /set_odr?value=<0-10>​

Nastaví výstupní datovou frekvenci (ODR).

Query Parametry:

  • value (int): Hodnota ODR (0-10)
    • 0 = 4000 Hz
    • 1 = 2000 Hz
    • 2 = 1000 Hz
    • 3 = 500 Hz
    • 4 = 250 Hz
    • 5 = 125 Hz
    • 6 = 62.5 Hz
    • 7 = 31.25 Hz
    • 8 = 15.625 Hz
    • 9 = 7.813 Hz
    • 10 = 3.906 Hz

Příklad:

GET /set_odr?value=6

Response:

OK

GET /set_range?value=<1-3>​

Nastaví měřící rozsah akcelerometru.

Query Parametry:

  • value (int): Rozsah
    • 1 = ±2g
    • 2 = ±4g
    • 3 = ±8g

Příklad:

GET /set_range?value=2

Response:

OK

POST /set_frequency​

Nastaví cílovou výstupní frekvenci softwaru.

Request Body (JSON):

{
  "frequency": 50.0
}

Response:

OK

📁 Správa Souborů​

GET /api/files?path=<path>​

Vrátí seznam souborů a složek v zadané cestě.

Query Parametry:

  • path (string, volitelný): Cesta k adresáři (výchozí: root)

Příklad:

GET /api/files?path=/2024/12/07

Response JSON:

{
  "files": [
    {
      "name": "data_20241207_143000.csv",
      "size": 1048576,
      "type": "file"
    },
    {
      "name": "data_20241207_150000.csv",
      "size": 524288,
      "type": "file"
    }
  ],
  "folders": [
    {
      "name": "2024",
      "type": "folder"
    }
  ],
  "path": "/2024/12/07"
}

GET /api/download?file=<filename>​

Stáhne zadaný soubor ze SD karty.

Query Parametry:

  • file (string): Název souboru včetně cesty

Příklad:

GET /api/download?file=/2024/12/07/data_20241207_143000.csv

Response:

  • Content-Type: application/octet-stream
  • Content-Disposition: attachment; filename="<filename>"
  • Binární obsah souboru

POST /api/delete​

Smaže zadaný soubor.

Request Body (JSON):

{
  "file": "/2024/12/07/data_20241207_143000.csv"
}

Response:

OK

POST /api/delete_all​

Smaže všechny soubory na SD kartě.

Request Body: Prázdné nebo {}

Response:

OK

Upozornění: Tato operace je nevratná!

POST /api/delete_folder​

Smaže celou složku včetně všech souborů.

Request Body (JSON):

{
  "folder": "/2024/12/07"
}

Response:

OK

📡 WiFi Management​

GET /wifi_status​

Vrátí stav WiFi připojení.

Response JSON:

{
  "sta_connected": true,
  "sta_ssid": "MyNetwork",
  "sta_ip": "192.168.1.100",
  "internet": true
}

Pole:

  • sta_connected (boolean): Zda je připojeno k WiFi
  • sta_ssid (string): Název sítě
  • sta_ip (string): Přidělená IP adresa
  • internet (boolean): Zda je dostupný internet

POST /connect_wifi​

Připojí se k WiFi síti.

Request Body (JSON):

{
  "ssid": "MyNetwork",
  "password": "MyPassword123"
}

Response:

OK

Note: Připojení probíhá na pozadí. Použijte /wifi_status pro kontrolu stavu.

GET /disconnect_wifi​

Odpojí se od WiFi sítě (STA režim).

Response:

OK

GET /api/wifi_scan​

Provede sken dostupných WiFi sítí.

Response JSON:

{
  "networks": [
    {
      "ssid": "MyNetwork",
      "rssi": -45,
      "auth": "WPA2"
    },
    {
      "ssid": "NeighborNetwork",
      "rssi": -78,
      "auth": "WPA2"
    }
  ]
}

Pole:

  • ssid (string): Název sítě
  • rssi (int): Síla signálu v dBm
  • auth (string): Typ zabezpečení

⏰ Plánování Měření​

GET /api/schedules​

Vrátí seznam všech naplánovaných měření.

Response JSON:

{
  "schedules": [
    {
      "id": 0,
      "enabled": true,
      "is_active": false,
      "name": "Morning measurement",
      "start_time": 1701936600,
      "end_time": 1701940200,
      "start_formatted": "2024-12-07 06:00:00",
      "end_formatted": "2024-12-07 07:00:00"
    }
  ]
}

POST /api/schedule​

Přidá nové naplánované měření.

Request Body (JSON):

{
  "name": "Test measurement",
  "start_time": "2024-12-07 14:30:00",
  "end_time": "2024-12-07 16:30:00"
}

Pole:

  • name (string): Název plánu
  • start_time (string): Čas začátku (YYYY-MM-DD HH:MM:SS)
  • end_time (string, volitelný): Čas konce

Response:

OK

DELETE /api/schedule?id=<id>​

Smaže naplánované měření.

Query Parametry:

  • id (int): ID plánu (0-9)

Příklad:

DELETE /api/schedule?id=0

Response:

OK

🏷️ Konfigurace Zařízení​

GET /api/device_config​

Vrátí konfiguraci zařízení.

Response JSON:

{
  "ap_ssid": "GeoSnake-Config",
  "ap_password": "geosnake123",
  "ble_name": "STATOTEST-GEOSNAKE"
}

POST /api/device_config​

Uloží novou konfiguraci zařízení.

Request Body (JSON):

{
  "ap_ssid": "MyGeoSnake",
  "ap_password": "SecurePass123",
  "ble_name": "GEOSNAKE-LAB-01"
}

Response:

{
  "status": "ok",
  "message": "Device config saved. Restart to apply changes."
}

Note: Změny se projeví až po restartu zařízení.

🕐 Správa Času​

GET /api/time​

Vrátí aktuální čas z RTC.

Response JSON:

{
  "time": "2024-12-07 14:30:45",
  "unix": 1701956445
}

POST /api/sync_ntp​

Synchronizuje čas z NTP serveru.

Request Body: Prázdné nebo {}

Response:

OK

Note: Vyžaduje aktivní internetové připojení.

POST /api/set_time​

Nastaví čas manuálně.

Request Body (JSON):

{
  "datetime": "2024-12-07 15:00:00"
}

Response:

OK

🔋 Správa Napájení​

POST /api/power​

Nastaví výkonový režim.

Request Body (JSON):

{
  "mode": "normal"
}

Parametry:

  • mode (string): "normal" nebo "low"
    • normal: 160 MHz CPU, žádný sleep
    • low: 80 MHz CPU, light sleep

Response:

OK

Note: Zařízení se automaticky restartuje po 2 sekundách.

POST /api/modem​

Ovládá WiFi modem sleep režim.

Request Body (JSON):

{
  "enable": true
}

Parametry:

  • enable (boolean): true = zapnout modem sleep, false = vypnout

Response:

OK

POST /api/deepsleep​

Přejde do deep sleep režimu.

Request Body (JSON):

{
  "duration": 3600
}

Parametry:

  • duration (int): Doba spánku v sekundách (1-86400)

Response:

Entering deep sleep...

Note: Zařízení se vypne a probudí po zadané době.

🔄 OTA Aktualizace​

GET /api/check_update​

Zkontroluje dostupnost nové verze firmware.

Response JSON:

{
  "update_available": true,
  "current_version": "v1.2.0",
  "latest_version": "v1.3.0",
  "download_url": "http://otaupdateserver.azurewebsites.net/geosnake/adxl/firmware.bin"
}

POST /api/ota_update​

Stáhne a nainstaluje novou verzi firmware.

Request Body (JSON):

{
  "url": "http://otaupdateserver.azurewebsites.net/geosnake/adxl/firmware.bin"
}

Response:

Downloading and installing update...

Note: Zařízení se automaticky restartuje po dokončení aktualizace.

POST /api/spiffs_update​

Aktualizuje webové rozhraní (SPIFFS).

Request Body: Multipart/form-data s uploadovaným souborem

Response:

SPIFFS updated successfully

Struktura Webového Rozhraní​

Záložky (Tabs)​

  1. 📊 Dashboard - Přehled stavu a rychlé ovládání
  2. ⚙️ Sensor Config - Konfigurace ADXL355
  3. ⏰ Schedule - Plánování měření
  4. 📁 Files - Správa souborů na SD kartě
  5. 🔋 Power - Správa napájení
  6. 🏷️ Device - Konfigurace zařízení
  7. 📡 WiFi - WiFi nastavení a připojení

JavaScript API (Frontend)​

Webové rozhraní poskytuje tyto hlavní funkce:

Ovládání Měření​

async function startMeasurement()
async function stopMeasurement()
async function updateODR()
async function updateRange()
async function updateFrequency()

Správa Souborů​

async function refreshFiles()
async function downloadFile(filename)
async function deleteFile(filename)
async function deleteAllFiles()
async function downloadSelected()
async function downloadCurrentFolder()

Stahování souborů:

  • Pokud je dostupná knihovna JSZip (z CDN), soubory se stáhnou jako ZIP archiv
  • Pokud není dostupná (offline režim), soubory se stáhnou postupně jednotlivě

WiFi Management​

async function connectWiFi()
async function disconnectWiFi()
async function scanWiFi()
async function updateWiFiStatus()

Plánování​

async function loadSchedules()
async function addSchedule()
async function deleteSchedule(id)

Power Management​

async function setPowerMode(mode)
async function setModemSleep(enable)
async function enterDeepSleep()

Použití Webového Rozhraní​

Základní Workflow​

  1. Připojení k zařízení:

    • Připojte se k WiFi síti GeoSnake-Config (heslo: geosnake123)
    • Otevřete prohlížeč a přejděte na http://192.168.4.1

  2. Kontrola stavu:

    • V záložce Dashboard zkontrolujte aktuální stav zařízení
    • Ověřte volné místo na SD kartě

  3. Konfigurace senzoru:

    • Přejděte na Sensor Config
    • Nastavte požadovaný ODR a rozsah
    • Upravte cílovou frekvenci výstupu

  4. Spuštění měření:

    • Klikněte na Start Measurement v Dashboardu
    • Sledujte statistiky v reálném čase

  5. Stažení dat:

    • Přejděte na Files
    • Vyberte soubory nebo celé složky
    • Klikněte na Download Selected pro stažení jako ZIP

  6. Plánování:

    • V záložce Schedule nastavte automatické měření
    • Zadejte datum, čas začátku a konce
    • Uložte plán

Tipy pro Vývoj​

AJAX Volání​

Všechny API endpointy podporují CORS pro lokální vývoj.

Příklad:

fetch('http://192.168.4.1/api/status')
  .then(response => response.json())
  .then(data => console.log(data));

Polling pro Aktualizace​

Rozhraní automaticky refreshuje status každé 2 sekundy:

setInterval(() => {
  updateStatus();
  updateWiFiStatus();
}, 2000);

Error Handling​

Vždy kontrolujte response status:

fetch('/api/start')
  .then(response => {
    if (!response.ok) throw new Error('Start failed');
    return response.text();
  })
  .catch(error => alert('Error: ' + error.message));

Řešení Problémů​

API neodpovídá:

  • Zkontrolujte připojení k WiFi
  • Ověřte, že je URL správná (http://192.168.4.1)
  • Zkuste vypnout a zapnout WiFi na zařízení

Soubory se nestahují:

  • Pokud je problém s popup blockerem, zkuste povolit popupy
  • V offline režimu se soubory stahují postupně (může trvat déle)

WiFi připojení selže:

  • Zkontrolujte správnost hesla
  • Ujistěte se, že síť je na 2.4 GHz (ESP32 nepodporuje 5 GHz)
  • Zkuste provést WiFi scan pro ověření dostupnosti sítě

OTA aktualizace selhává:

  • Ověřte připojení k internetu
  • Zkontrolujte dostupnost aktualizačního serveru
  • Ujistěte se, že je dostatek volné paměti (minimálně 1 MB)