GeoSnake - Bluetooth Commands

Version: 1.0
Firmware: v1.2.0+

---

Table of Contents

1. Introduction
2. BLE Connection
3. Text Commands
   • Measurement
   • Measurement Scheduling
   • WiFi
   • Power Management
   • Time
   • Configuration
   • Information
   • System
4. Binary Commands (Legacy)
5. Using with Mobile Apps
6. Automation and Scripts
7. Troubleshooting

---

Introduction

GeoSnake communicates via Bluetooth Low Energy (BLE) using the Nordic UART Service (NUS) protocol.

BLE Service UUIDs

• Service UUID: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
• TX Characteristic (notifications): 6E400003-B5A3-F393-E0A9-E50E24DCCA9E
• RX Characteristic (write): 6E400002-B5A3-F393-E0A9-E50E24DCCA9E

Communication Principles

• Commands are sent as text strings (ASCII) to RX characteristic
• Responses are received as notifications from TX characteristic
• Commands end with \n or \r\n (newline)
• Responses have format: {"status":"ok","data":...} (JSON)

---

BLE Connection

Device Name

Default name: GeoSnake
Can be changed via command set_ble_name.

Connection Steps

1. Enable Bluetooth on your device
2. Scan for BLE devices
3. Find device named GeoSnake
4. Connect to device
5. Find service 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
6. Enable notifications on TX characteristic
7. Send commands to RX characteristic

Connection Range

• Typical: 10-20 meters (open space)
• Indoors: 5-10 meters
• Through walls: 2-5 meters

---

Text Commands

All commands are case-sensitive and must be sent exactly as shown.

Measurement

start

Description: Start measurement
Parameters: None
Response: {"status":"ok","message":"Measurement started"}

Example:

> start
< {"status":"ok","message":"Measurement started"}

---

stop

Description: Stop measurement
Parameters: None
Response: {"status":"ok","message":"Measurement stopped"}

Example:

> stop
< {"status":"ok","message":"Measurement stopped"}

---

status

Description: Get current status
Parameters: None
Response: JSON with complete status

Example:

> status
< {
    "status": "ok",
    "data": {
        "measuring": true,
        "odr": 4000,
        "range": 2,
        "hpf": "OFF",
        "samples": 125678,
        "file": "data_20241207_143022.csv",
        "wifi_connected": false,
        "battery_voltage": 3.75,
        "time": "2024-12-07 14:35:12"
    }
  }

---

set_odr <frequency>

Description: Set sampling frequency (ODR - Output Data Rate)
Parameters:

• frequency: 4000, 2000, 1000, 500, 250, 125, 62.5, 31.25, 15.625, 7.813, 3.906

Example:

> set_odr 1000
< {"status":"ok","message":"ODR set to 1000 Hz"}

---

set_range <range>

Description: Set measurement range
Parameters:

• range: 2, 4, 8 (±2g, ±4g, ±8g)

Example:

> set_range 4
< {"status":"ok","message":"Range set to ±4g"}

---

set_hpf <filter>

Description: Set high-pass filter
Parameters:

• filter: OFF, 0.001, 0.0025, 0.0063, 0.016, 0.039, 0.097, 0.245, 0.625, 1.563, 3.906

Example:

> set_hpf 0.245
< {"status":"ok","message":"HPF set to 0.245 Hz"}

---

Measurement Scheduling

add_schedule <start_time> <duration> <repeat>

Description: Add scheduled measurement
Parameters:

• start_time: Start time in format YYYY-MM-DD HH:MM:SS
• duration: Duration in seconds
• repeat: Repeat period in seconds (0 = no repeat)

Example:

> add_schedule 2024-12-07 18:00:00 3600 86400
< {"status":"ok","message":"Schedule added","id":0}

Explanation: Measurement starts on Dec 7, 2024 at 18:00, lasts 1 hour (3600s), repeats daily (86400s)

---

list_schedules

Description: List all schedules
Parameters: None
Response: JSON array with all schedules

Example:

> list_schedules
< {
    "status": "ok",
    "data": [
        {
            "id": 0,
            "enabled": true,
            "start": "2024-12-07 18:00:00",
            "duration": 3600,
            "repeat": 86400,
            "next_run": "2024-12-07 18:00:00"
        }
    ]
  }

---

enable_schedule <id>

Description: Enable schedule
Parameters:

• id: Schedule ID (from list_schedules)

Example:

> enable_schedule 0
< {"status":"ok","message":"Schedule 0 enabled"}

---

disable_schedule <id>

Description: Disable schedule
Parameters:

• id: Schedule ID

Example:

> disable_schedule 0
< {"status":"ok","message":"Schedule 0 disabled"}

---

delete_schedule <id>

Description: Delete schedule
Parameters:

• id: Schedule ID

Example:

> delete_schedule 0
< {"status":"ok","message":"Schedule 0 deleted"}

---

WiFi

connect_wifi <ssid> <password>

Description: Connect to WiFi network
Parameters:

• ssid: Network name
• password: Network password

Example:

> connect_wifi MyNetwork MyPassword123
< {"status":"ok","message":"Connecting to WiFi..."}

---

disconnect_wifi

Description: Disconnect from WiFi
Parameters: None

Example:

> disconnect_wifi
< {"status":"ok","message":"WiFi disconnected"}

---

wifi_status

Description: Get WiFi status
Parameters: None
Response: JSON with WiFi information

Example:

> wifi_status
< {
    "status": "ok",
    "data": {
        "connected": true,
        "ssid": "MyNetwork",
        "ip": "192.168.1.100",
        "rssi": -45
    }
  }

---

start_ap

Description: Start WiFi Access Point
Parameters: None

Example:

> start_ap
< {"status":"ok","message":"AP started","ssid":"GeoSnake_AP","ip":"192.168.4.1"}

---

stop_ap

Description: Stop WiFi Access Point
Parameters: None

Example:

> stop_ap
< {"status":"ok","message":"AP stopped"}

---

Power Management

set_power_mode <mode>

Description: Set power mode
Parameters:

• mode: NORMAL, LOW_POWER, DEEP_SLEEP

Example:

> set_power_mode LOW_POWER
< {"status":"ok","message":"Power mode set to LOW_POWER"}

Power Modes:

• NORMAL: Full performance, all features enabled
• LOW_POWER: Reduced WiFi activity, lower consumption
• DEEP_SLEEP: Deep sleep between measurements (lowest consumption)

---

get_battery

Description: Get battery voltage
Parameters: None
Response: Battery voltage in volts

Example:

> get_battery
< {"status":"ok","data":{"voltage":3.75,"percentage":75}}

---

enable_wifi_sleep

Description: Enable WiFi power saving (WiFi turns off when idle)
Parameters: None

Example:

> enable_wifi_sleep
< {"status":"ok","message":"WiFi sleep enabled"}

---

disable_wifi_sleep

Description: Disable WiFi power saving (WiFi always on)
Parameters: None

Example:

> disable_wifi_sleep
< {"status":"ok","message":"WiFi sleep disabled"}

---

Time

set_time <time>

Description: Set device time
Parameters:

• time: Time in format YYYY-MM-DD HH:MM:SS

Example:

> set_time 2024-12-07 14:30:00
< {"status":"ok","message":"Time set"}

---

get_time

Description: Get current device time
Parameters: None

Example:

> get_time
< {"status":"ok","data":{"time":"2024-12-07 14:30:15"}}

---

sync_ntp

Description: Synchronize time with NTP server
Parameters: None (requires WiFi connection)

Example:

> sync_ntp
< {"status":"ok","message":"Time synchronized","time":"2024-12-07 14:30:00"}

---

Configuration

set_ble_name <name>

Description: Set Bluetooth device name
Parameters:

• name: New device name (max 20 characters)

Example:

> set_ble_name MyGeoSnake
< {"status":"ok","message":"BLE name set to MyGeoSnake"}

---

set_ap_ssid <ssid>

Description: Set Access Point name
Parameters:

• ssid: New AP name

Example:

> set_ap_ssid GeoSnake_Lab1
< {"status":"ok","message":"AP SSID set"}

---

set_ap_password <password>

Description: Set Access Point password
Parameters:

• password: New password (min 8 characters)

Example:

> set_ap_password MySecurePass123
< {"status":"ok","message":"AP password set"}

---

save_config

Description: Save configuration to flash
Parameters: None

Example:

> save_config
< {"status":"ok","message":"Configuration saved"}

---

load_config

Description: Load configuration from flash
Parameters: None

Example:

> load_config
< {"status":"ok","message":"Configuration loaded"}

---

Information

get_info

Description: Get device information
Parameters: None
Response: JSON with device details

Example:

> get_info
< {
    "status": "ok",
    "data": {
        "device": "GeoSnake",
        "firmware": "v1.2.0",
        "hardware": "ESP32-C6",
        "sensor": "ADXL355",
        "build_date": "Dec  7 2024",
        "build_time": "14:30:00"
    }
  }

---

get_sd_info

Description: Get SD card information
Parameters: None
Response: JSON with SD card details

Example:

> get_sd_info
< {
    "status": "ok",
    "data": {
        "mounted": true,
        "type": "SDHC",
        "total_mb": 15193,
        "used_mb": 2456,
        "free_mb": 12737
    }
  }

---

list_files

Description: List files on SD card
Parameters: None
Response: JSON array with file list

Example:

> list_files
< {
    "status": "ok",
    "data": [
        {
            "name": "data_20241207_143022.csv",
            "size": 1234567,
            "date": "2024-12-07 14:30:22"
        }
    ]
  }

---

System

restart

Description: Restart device
Parameters: None

Example:

> restart
< {"status":"ok","message":"Restarting..."}

---

factory_reset

Description: Factory reset (restore default settings)
Parameters: None
Warning: Deletes all configuration!

Example:

> factory_reset
< {"status":"ok","message":"Factory reset complete. Restarting..."}

---

format_sd

Description: Format SD card
Parameters: None
Warning: Deletes all data!

Example:

> format_sd
< {"status":"ok","message":"SD card formatted"}

---

ota_update <url>

Description: Start OTA firmware update
Parameters:

• url: URL to firmware file (.bin)

Example:

> ota_update http://192.168.1.10/firmware.bin
< {"status":"ok","message":"OTA update started..."}

---

Binary Commands (Legacy)

Binary commands are supported for backward compatibility.

Format

• Command ID: 1 byte
• Payload: Variable (depends on command)
• Checksum: 1 byte (XOR of all bytes)

Example Commands

• 0x01: Start measurement
• 0x02: Stop measurement
• 0x03: Get status
• 0x10: Set ODR
• 0x11: Set range

Note: Text commands are recommended for new applications.

---

Using with Mobile Apps

nRF Connect (Android/iOS)

1. Install app: Download from Google Play or App Store
2. Scan: Tap "SCAN" → find "GeoSnake"
3. Connect: Tap device name
4. Find service: Scroll to UUID 6E400001...
5. Enable notifications: Tap ↓ icon next to TX characteristic
6. Send command: Tap ↑ icon next to RX characteristic → type command → send

Example session:

1. Connect to GeoSnake
2. Enable TX notifications
3. Send: "status\n"
4. Receive: {"status":"ok","data":{...}}
5. Send: "start\n"
6. Receive: {"status":"ok","message":"Measurement started"}

---

Bluefruit Connect (iOS)

1. Install app: Download from App Store
2. Connect: Select device "GeoSnake"
3. Select UART: Tap "UART" module
4. Send commands: Type in text field → press Send

Tip: Use "Macro" feature to save frequently used commands.

---

Automation and Scripts

Python Example (using bleak)

import asyncio
from bleak import BleakClient, BleakScanner

UART_SERVICE_UUID = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
UART_RX_CHAR_UUID = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"
UART_TX_CHAR_UUID = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"

async def main():
    # Find device
    device = await BleakScanner.find_device_by_name("GeoSnake")
    
    async with BleakClient(device) as client:
        # Enable notifications
        def callback(sender, data):
            print(f"Response: {data.decode()}")
        
        await client.start_notify(UART_TX_CHAR_UUID, callback)
        
        # Send commands
        await client.write_gatt_char(UART_RX_CHAR_UUID, b"start\n")
        await asyncio.sleep(2)
        
        await client.write_gatt_char(UART_RX_CHAR_UUID, b"status\n")
        await asyncio.sleep(2)

asyncio.run(main())

---

Node.js Example (using @abandonware/noble)

const noble = require('@abandonware/noble');

const UART_SERVICE_UUID = '6e4000001b5a3f393e0a9e50e24dcca9e';
const UART_RX_CHAR_UUID = '6e4000002b5a3f393e0a9e50e24dcca9e';
const UART_TX_CHAR_UUID = '6e4000003b5a3f393e0a9e50e24dcca9e';

noble.on('stateChange', async (state) => {
    if (state === 'poweredOn') {
        await noble.startScanningAsync([UART_SERVICE_UUID], false);
    }
});

noble.on('discover', async (peripheral) => {
    if (peripheral.advertisement.localName === 'GeoSnake') {
        await noble.stopScanningAsync();
        await peripheral.connectAsync();
        
        const {characteristics} = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
            [UART_SERVICE_UUID],
            [UART_RX_CHAR_UUID, UART_TX_CHAR_UUID]
        );
        
        const rx = characteristics.find(c => c.uuid === UART_RX_CHAR_UUID);
        const tx = characteristics.find(c => c.uuid === UART_TX_CHAR_UUID);
        
        tx.on('data', (data) => {
            console.log('Response:', data.toString());
        });
        
        await tx.subscribeAsync();
        await rx.writeAsync(Buffer.from('start\n'), false);
    }
});

---

Troubleshooting

Cannot Connect to Device

Symptoms: Device not visible in scan or connection fails

Solutions:

1. Check if Bluetooth is enabled on your device
2. Restart GeoSnake (power cycle)
3. Move closer to device (< 5m)
4. Check if another device is connected (only 1 connection at a time)
5. Restart Bluetooth on your device

---

Commands Not Working

Symptoms: No response or error response

Solutions:

1. Check if notifications are enabled on TX characteristic
2. Verify command syntax (case-sensitive!)
3. Add newline \n at end of command
4. Wait for previous command to complete
5. Check device status with status command

---

Slow Response

Symptoms: Commands take long time to execute

Solutions:

1. Move closer to device
2. Disable WiFi (disconnect_wifi) if not needed
3. Check battery level (get_battery)
4. Reduce interference (turn off other BLE devices)

---

Connection Drops

Symptoms: Connection frequently disconnects

Solutions:

1. Reduce distance to device
2. Check battery level (low battery = weak signal)
3. Disable power saving mode (set_power_mode NORMAL)
4. Update mobile app firmware
5. Try different mobile device

---

Advanced Tips

Efficient Automation

• Use status command for monitoring (poll every 2-5 seconds)
• Batch multiple settings changes before save_config
• Use schedules for unattended operation
• Combine LOW_POWER mode with WiFi sleep for battery operation

Debugging

• Always check status first
• Use get_info to verify firmware version
• Monitor battery voltage regularly
• Check SD card space before long measurements

Best Practices

• Set time via NTP when WiFi available (sync_ntp)
• Save configuration after important changes (save_config)
• Test commands individually before automation
• Implement error handling in scripts
• Keep backup of important configurations

---

Command Summary

Category	Commands
Measurement	start, stop, status, set_odr, set_range, set_hpf
Scheduling	add_schedule, list_schedules, enable_schedule, disable_schedule, delete_schedule
WiFi	connect_wifi, disconnect_wifi, wifi_status, start_ap, stop_ap
Power	set_power_mode, get_battery, enable_wifi_sleep, disable_wifi_sleep
Time	set_time, get_time, sync_ntp
Config	set_ble_name, set_ap_ssid, set_ap_password, save_config, load_config
Info	get_info, get_sd_info, list_files
System	restart, factory_reset, format_sd, ota_update

Total: 35+ commands available

---

For more information see:

• User Manual - Complete device guide
• Web API - HTTP API documentation
• Web GUI - Web interface guide