GeoSnake - Web Interface API Documentation

Overview

The web interface is accessible via WiFi Access Point or when connected to an external WiFi network.

Access:

URL: http://192.168.4.1 (when connected to WiFi AP)
SSID: STATOTEST-GEOSNAKE-XXX (default, XXX is device identifaciton number)

The interface provides a REST API for device control and a web application with a modern graphical interface.

HTTP API Endpoints

📄 Static Files

`GET /`

Returns the main HTML page of the web interface.

`GET /logo.svg`

Returns the Statotest SVG logo.

Response:

Content-Type: image/svg+xml

📊 Status and Statistics

`GET /api/status`

Returns current measurement status and configuration.

Response JSON:

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

Fields:

measuring (boolean): Whether measurement is in progress
odr (int): ODR value (0-10)
range (int): Measurement range (1-3)
frequency (float): Target output frequency in Hz
rtc_time (string): Current time from RTC
firmware (string): Firmware version

`GET /api/stats`

Returns measurement statistics.

Response JSON:

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

`GET /api/sd_info`

Returns SD card information.

Response JSON:

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

Fields:

total (number): Total capacity in bytes
free (number): Free space in bytes

⚙️ Measurement Control

`GET /start`

Starts accelerometer measurement.

Response:

OK

`GET /stop`

Stops accelerometer measurement.

Response:

OK

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

Sets the output data rate (ODR).

Query Parameters:

value (int): ODR value (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

Example:

GET /set_odr?value=6

Response:

OK

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

Sets the accelerometer measurement range.

Query Parameters:

value (int): Range
- 1 = ±2g
- 2 = ±4g
- 3 = ±8g

Example:

GET /set_range?value=2

Response:

OK

`POST /set_frequency`

Sets the target software output frequency.

Request Body (JSON):

{
  "frequency": 50.0
}

Response:

OK

📁 File Management

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

Returns a list of files and folders in the specified path.

Query Parameters:

path (string, optional): Directory path (default: root)

Example:

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>`

Downloads the specified file from the SD card.

Query Parameters:

file (string): File name including path

Example:

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

Response:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="<filename>"
Binary file content

`POST /api/delete`

Deletes the specified file.

Request Body (JSON):

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

Response:

OK

`POST /api/delete_all`

Deletes all files on the SD card.

Request Body: Empty or {}

Response:

OK

Warning: This operation is irreversible!

`POST /api/delete_folder`

Deletes an entire folder including all files.

Request Body (JSON):

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

Response:

OK

📡 WiFi Management

`GET /wifi_status`

Returns WiFi connection status.

Response JSON:

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

Fields:

sta_connected (boolean): Whether connected to WiFi
sta_ssid (string): Network name
sta_ip (string): Assigned IP address
internet (boolean): Whether internet is available

`POST /connect_wifi`

Connects to a WiFi network.

Request Body (JSON):

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

Response:

OK

Note: Connection happens in the background. Use /wifi_status to check status.

`GET /disconnect_wifi`

Disconnects from WiFi network (STA mode).

Response:

OK

`GET /api/wifi_scan`

Performs a scan of available WiFi networks.

Response JSON:

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

Fields:

ssid (string): Network name
rssi (int): Signal strength in dBm
auth (string): Security type

⏰ Measurement Scheduling

`GET /api/schedules`

Returns a list of all scheduled measurements.

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`

Adds a new scheduled measurement.

Request Body (JSON):

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

Fields:

name (string): Schedule name
start_time (string): Start time (YYYY-MM-DD HH:MM:SS)
end_time (string, optional): End time

Response:

OK

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

Deletes a scheduled measurement.

Query Parameters:

id (int): Schedule ID (0-9)

Example:

DELETE /api/schedule?id=0

Response:

OK

🏷️ Device Configuration

`GET /api/device_config`

Returns device configuration.

Response JSON:

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

`POST /api/device_config`

Saves new device configuration.

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: Changes take effect after device restart.

🕐 Time Management

`GET /api/time`

Returns current time from RTC.

Response JSON:

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

`POST /api/sync_ntp`

Synchronizes time from NTP server.

Request Body: Empty or {}

Response:

OK

Note: Requires active internet connection.

`POST /api/set_time`

Sets time manually.

Request Body (JSON):

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

Response:

OK

🔋 Power Management

`POST /api/power`

Sets power mode.

Request Body (JSON):

{
  "mode": "normal"
}

Parameters:

mode (string): "normal" or "low"
- normal: 160 MHz CPU, no sleep
- low: 80 MHz CPU, light sleep

Response:

OK

Note: Device automatically restarts after 2 seconds.

`POST /api/modem`

Controls WiFi modem sleep mode.

Request Body (JSON):

{
  "enable": true
}

Parameters:

enable (boolean): true = enable modem sleep, false = disable

Response:

OK

`POST /api/deepsleep`

Enters deep sleep mode.

Request Body (JSON):

{
  "duration": 3600
}

Parameters:

duration (int): Sleep duration in seconds (1-86400)

Response:

Entering deep sleep...

Note: Device powers down and wakes up after specified duration.

🔄 OTA Updates

`GET /api/check_update`

Checks for new firmware version availability.

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`

Downloads and installs new firmware version.

Request Body (JSON):

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

Response:

Downloading and installing update...

Note: Device automatically restarts after update completion.

`POST /api/spiffs_update`

Updates web interface (SPIFFS).

Request Body: Multipart/form-data with uploaded file

Response:

SPIFFS updated successfully

Web Interface Structure

Tabs

📊 Dashboard - Overview and quick controls
⚙️ Sensor Config - ADXL355 configuration
⏰ Schedule - Measurement scheduling
📁 Files - SD card file management
🔋 Power - Power management
🏷️ Device - Device configuration
📡 WiFi - WiFi settings and connection

JavaScript API (Frontend)

The web interface provides these main functions:

Measurement Control

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

File Management

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

File Downloads:

If JSZip library is available (from CDN), files are downloaded as ZIP archive
If not available (offline mode), files are downloaded sequentially one by one

WiFi Management

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

Scheduling

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

Power Management

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

Using the Web Interface

Basic Workflow

Connect to device:
- Connect to WiFi network
- Open browser and navigate to http://192.168.4.1
Check status:
- In Dashboard tab, check current device status
- Verify free space on SD card
Configure sensor:
- Go to Sensor Config
- Set desired ODR and range
- Adjust target output frequency
Start measurement:
- Click Start Measurement in Dashboard
- Monitor real-time statistics
Download data:
- Go to Files
- Select files or entire folders
- Click Download Selected to download as ZIP
Scheduling:
- In Schedule tab, set up automatic measurements
- Enter date, start and end times
- Save schedule

Development Tips

AJAX Calls

All API endpoints support CORS for local development.

Example:

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

Polling for Updates

The interface automatically refreshes status every 2 seconds:

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

Error Handling

Always check response status:

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

Troubleshooting

API not responding:

Check WiFi connection
Verify URL is correct (http://192.168.4.1)
Try turning WiFi off and on on device

Files not downloading:

If popup blocker is an issue, try allowing popups
In offline mode, files download sequentially (may take longer)

WiFi connection fails:

Check password correctness
Ensure network is on 2.4 GHz (ESP32 doesn't support 5 GHz)
Try WiFi scan to verify network availability

OTA update fails:

Verify internet connection
Check update server availability
Ensure sufficient free memory (minimum 1 MB)

Overview​

HTTP API Endpoints​

📄 Static Files​

GET /​

GET /logo.svg​

📊 Status and Statistics​

GET /api/status​

GET /api/stats​

GET /api/sd_info​

⚙️ Measurement Control​

GET /start​

GET /stop​

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

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

POST /set_frequency​

📁 File Management​

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

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

POST /api/delete​

POST /api/delete_all​

POST /api/delete_folder​

📡 WiFi Management​

GET /wifi_status​

POST /connect_wifi​

GET /disconnect_wifi​

GET /api/wifi_scan​

⏰ Measurement Scheduling​

GET /api/schedules​

POST /api/schedule​

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

🏷️ Device Configuration​

GET /api/device_config​

POST /api/device_config​

🕐 Time Management​

GET /api/time​

POST /api/sync_ntp​

POST /api/set_time​

🔋 Power Management​

POST /api/power​

POST /api/modem​

POST /api/deepsleep​

🔄 OTA Updates​

GET /api/check_update​

POST /api/ota_update​

POST /api/spiffs_update​

Web Interface Structure​

Tabs​

JavaScript API (Frontend)​

Measurement Control​

File Management​

WiFi Management​

Scheduling​

Power Management​

Using the Web Interface​

Basic Workflow​

Development Tips​

AJAX Calls​

Polling for Updates​

Error Handling​

Troubleshooting​

Overview

HTTP API Endpoints

📄 Static Files

`GET /`

`GET /logo.svg`

📊 Status and Statistics

`GET /api/status`

`GET /api/stats`

`GET /api/sd_info`

⚙️ Measurement Control

`GET /start`

`GET /stop`

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

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

`POST /set_frequency`

📁 File Management

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

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

`POST /api/delete`

`POST /api/delete_all`

`POST /api/delete_folder`

📡 WiFi Management

`GET /wifi_status`

`POST /connect_wifi`

`GET /disconnect_wifi`

`GET /api/wifi_scan`

⏰ Measurement Scheduling

`GET /api/schedules`

`POST /api/schedule`

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

🏷️ Device Configuration

`GET /api/device_config`

`POST /api/device_config`

🕐 Time Management

`GET /api/time`

`POST /api/sync_ntp`

`POST /api/set_time`

🔋 Power Management

`POST /api/power`

`POST /api/modem`

`POST /api/deepsleep`

🔄 OTA Updates

`GET /api/check_update`

`POST /api/ota_update`

`POST /api/spiffs_update`

Web Interface Structure

Tabs

JavaScript API (Frontend)

Measurement Control

File Management

WiFi Management

Scheduling

Power Management

Using the Web Interface

Basic Workflow

Development Tips

AJAX Calls

Polling for Updates

Error Handling

Troubleshooting