ZONES Command — Geofence Download
Downloads a binary geofence (zones) file to the device over HTTP and manages the loaded slot. The download is asynchronous: the command returns immediately and the final result arrives when it finishes.
What is it for?
🗺️ Main use cases:
- ⬇️ Provision the device with a geofence set hosted on a server (HTTP GET)
- 🔄 Update geofences remotely without reconfiguring point by point
- ⏹️ Cancel an ongoing download if it was launched by mistake or the file changed
- 🗑️ Delete the geofence slot loaded on the device
- 🔍 Check whether geofences are loaded, plus their version, CRC and size
The geofence storage module must be enabled on the device. If it is not, SZONES responds RZONES,ERR,mode_off and QZONES responds RZONES,DISABLED.
Commands
| Operation | Syntax | Immediate response |
|---|---|---|
| Download | SZONES"url" | RZONES,START |
| Cancel download | SZONESC | RZONESC |
| Delete slot | SZONESD | RZONESD |
| Query status | QZONES | RZONES,LOADED|EMPTY|DISABLED |
Download (SZONES)
The URL must be in quotes. It accepts an optional prefix to force the channel:
| Prefix | Channel |
|---|---|
| (no prefix) | WiFi with fallback to modem |
W: | Forces WiFi |
M: | Forces modem |
>SZONES"http://host/zones.bin"<
>RZONES,START<The download runs in a separate task, so the parser stays free to process other commands (e.g. SZONESC to cancel over the same channel). When it finishes, the device emits the final result:
| Result | Description |
|---|---|
RZONES,OK,ver=…,crc=0x…,elem=…,size=… | Valid download, geofences loaded |
RZONES,CANCELED | Canceled by the user (SZONESC) |
RZONES,ERR,<reason> | Error during download |
>SZONES"http://host/zones.bin"<
>RZONES,START<
// ... download in progress ...
>RZONES,OK,ver=3,crc=0x1A2B3C4D,elem=25,size=8192<Start errors
| Response | Cause |
|---|---|
RZONES,ERR,mode_off | Geofence module not enabled |
RZONES,ERR,bad_url_format | URL not properly quoted |
RZONES,ERR,busy_or_nomem | A download is already running or no memory |
Cancel download (SZONESC)
Cancels the ongoing download. It is idempotent: if there is no active download, it does nothing.
>SZONESC<
>RZONESC<On cancel, the partition may be left with partial data; on the next reload the CRC fails and it is not loaded. The next SZONES"…" starts clean.
Delete slot (SZONESD)
Unloads and erases the device geofence slot. It is the clean alias of the legacy SZONES**D command (kept for backward compatibility).
>SZONESD<
>RZONESD<
>SZONES**D< // legacy equivalent
>RZONES**D<Query status (QZONES)
>QZONES<
>RZONES,LOADED,ver=3,crc=0x1A2B3C4D,elem=25,size=8192<| Response | Meaning |
|---|---|
RZONES,LOADED,ver=…,crc=0x…,elem=…,size=… | Geofences are loaded |
RZONES,EMPTY | Module enabled, no geofences loaded |
RZONES,DISABLED | Geofence module disabled |
| Field | Description |
|---|---|
| ver | Geofence file version |
| crc | File CRC (hexadecimal) |
| elem | Number of elements (geofences) |
| size | File size in bytes |