findyIoT

findyIoT - the HiGPS communication protocol.

The findyIoT class below is verbatim from the device firmware (firmware_core.py of Logger Pro and the findyIoT module). On a device a single instance exists as the module global protocol; its methods reference the firmware module globals (modem, db, device, Gimei, connectionSuccess, wdt/wdtAlert…) exactly as shown here.

Which parameters a report carries is decided by the application: the datalist attribute is set from fw.report(alarm, datalist) and the list itself lives in the user-editable last.py.

findylab.findyIoT.Gimei = '0'

Device IMEI (set during first boot on a device).

findylab.findyIoT.firmwareVersion = '3_5_4'

Firmware version string appended to every report.

findylab.findyIoT.errors = ''

Accumulated error text, sent as the &er= request field.

findylab.findyIoT.connectionSuccess = False

True after the last request reached the server.

findylab.findyIoT.defaults = ['421', '422', '524', '525', '553', '554', '555', '556', '523', '575', '576', '577', '578', '579', '580', '581', '587', '636', '637', '638', '639', '640']

Parameter IDs sent once at first boot (the defaults report).

class findylab.findyIoT.findyIoT

HiGPS protocol engine (the protocol instance on a device).

Verbatim class from firmware_core.py. Requests are built by the get_<type> methods and sent through the global modem; server replies (*SET/*GET/…) dispatch to set_<type> handlers via parse().

datalist

Parameter IDs sent by get_samplings(). Populated from fw.report(alarm, datalist); the list itself is owned by last.py.

Type:

list

Note

Methods reference the firmware_core module globals (modem, db, Gimei, connectionSuccess, wdt…), exactly as on the device.

__init__()

Initializes the protocol state (request type, IMEI, datalist).

main(command, execute=True)

Sends a request and processes chained server commands.

Keeps calling send() while the server keeps returning a follow-up command, so one report can carry out a whole remote-configuration session.

Parameters:

• command (str) – Request type - 'samplings', 'samplingsAlarm', 'defaults', 'dataBat', 'setting,<id>' or 'command,<id>'.

• execute (bool) – When False, server commands are received but not executed (used for status echoes).

Returns:

The final send() result (falsy when the chain ended).

send(commandtype, execute)

Sends a single request to the HiGPS server.

Builds the body via the matching get_<type> method and performs the GET. A bare 10-digit reply is a server timestamp and synchronizes the RTC (also sets the global timeOffset); a command reply dispatches to the matching set_<type> handler - at most _DISPATCH_MAX levels deep, so a server looping the same *SET cannot overflow the stack. Sets the global connectionSuccess.

Parameters:

• commandtype (str) – Request type, optionally with a comma parameter ('setting,421').

• execute (bool) – Whether to act on the server reply.

Returns:

The follow-up request to send, or False when done.

Return type:

str

parse(rsp)

Classifies a server reply.

Parameters:

rsp (str) – Decoded server reply.

Returns:

One of 'set', 'get', 'start', 'stop', 'mode', 'modeQ', 'gprs', 'eng', 'wifi', 'user', 'phones' - or False when the reply carries no command.

Return type:

str

set_set(response)

Executes a *SET server command.

*SET,<id>$ executes an “E”-type parameter’s function; *SET,<id>,<value>$ writes a “W”-type parameter and persists the database.

Parameters:

response (str) – The raw *SET reply.

Returns:

A 'setting,<id>' echo request, or False.

Return type:

str

set_get(response)

Executes a *GET server command (read one parameter).

Parameters:

response (str) – The raw *GET reply.

Returns:

A 'setting,<id>' upload request, or False.

Return type:

str

get_defaults()

Builds the first-boot report with the defaults parameter set.

Returns:

Request body (IMEI=...&bat=...&data=...).

Return type:

str

get_samplings()

Builds the standard report body.

Sends the parameters in datalist (set by fw.report) plus battery level. Works on a copy of the list; the pulse/analog extras (437/540, 439/541, 594/520, 570/595) are appended when the enable flags 636-639 are set.

Returns:

Request body (IMEI=...&bat=...&data=...).

Return type:

str

get_samplingsAlarm()

Builds an alarm report: get_samplings() plus the 440,1 flag.

Returns:

Request body with the alarm marker appended.

Return type:

str

get_dataBat()

Builds the minimal fallback report (IMEI + battery only).

Used when building the full report failed, so the server still hears from the device.

Returns:

Request body.

Return type:

str

get_data(datalist)

Serializes parameter values into the wire format.

History buffers (594/595) are unpacked from packed floats; pulse ring-buffers (540/541) are serialized with their header fields (t_/p_/i_).

Parameters:

datalist (list) – Parameter IDs to include; unknown IDs are skipped.

Returns:

"<id>,<value>;" pairs.

Return type:

str

get_setting(id)

Builds a single-parameter upload (&set= request).

Parameters:

id (str) – Parameter ID; must be readable (“R” or “W”).

Returns:

Request body, or None for non-readable parameters.

Return type:

str

get_command(id)

Builds a command acknowledgement request.

Parameters:

id (str) – Parameter ID of an “E”-type command.

Returns:

Request body, or None for non-command parameters.

Return type:

str

downloadUpdate()

Downloads the OTA package named in parameter 51 (command 55).

Re-entrancy wrapper around the actual download: the completion acknowledgement (command,55) is sent with execute=True so a queued *SET,52 flows straight into update(); a server that kept answering with *SET,55 would otherwise re-enter this method until the stack overflowed. The download itself is zip-based, resumable per chunk (the partial file is pinned to the package via update.meta) and CRC32-verified before parameter 53 reports ready (2). Progress and errors go to parameters 53/54 - see Over-the-air update.

Returns:

True when the package is downloaded and verified.

Return type:

bool

update()

Applies the downloaded package (command 52).

Re-verifies the archive, extracts it into the OTA_STAGE directory (each file CRC32-checked as written) and creates the OTA_COMMIT marker; boot.py then copies the staged tree onto the live filesystem on the next boot. Parameter 53 is 3 while updating; a failure leaves 53 at 2 (downloaded) with 54 = 8 so the server can retry. Resets the device on success.

Returns:

False when there is no valid package or staging failed.

Return type:

bool

resetCount1()

Resets the pulse counters (command 429).

Re-initializes the ULP program, resets the modem, re-registers and acknowledges the command to the server.

Returns:

True.

Return type:

bool

updateTime()

Refreshes the device timestamp and acknowledges with command 8.

serialNumber()

Uploads the chip serial number as a setting.

Note

Inherited quirk: defined without self and references self in the body - calling it raises. Kept verbatim.

factoryReset()

Acknowledges command 222, wipes the database and resets.

restart()

Restarts the modem radio (AT+CFUN=0 / AT+CFUN=1).

Note

Inherited quirk: this second definition shadows the command-221 handler above and references self.us which findyIoT does not have. Kept verbatim.