GPS Positioning

The M2000 gateway supports GPS positioning. Use Call the RESTful API to call the GPS APIs:

• Read the GPS state: the gps field in the GET /cassia/info response, refer to Get/Set Gateway Info

• Enable GPS at startup: POST /cassia/info to set dongle.gps_startup to "1"

• Request positioning: GET /cassia/gps/request, returns after positioning succeeds

Note

• The gateway must support the gps feature (features in the /cassia/info response contains gps)

• Right after the gateway boots, the GPS module is still initializing and the API may return gps is starting

• Without satellite reception, /cassia/gps/request can block for a long time. Always set a timeout with asyncio.wait_for()

Example

import asyncio
import json

import cassiablue

REQUEST_TIMEOUT_S = 30


def dms_to_deg(dms, sign):
    d, m, s = str(dms).split(".")
    deg = int(d) + int(m) / 60 + int(s) / 3600
    return -deg if sign in ("S", "W") else deg


def print_gps(gps):
    if not gps:
        print("no gps data")
        return

    lat, lon = gps.get("LAT"), gps.get("LON")
    if lat and lon:
        print("lat:", dms_to_deg(lat, gps.get("NS")))
        print("lon:", dms_to_deg(lon, gps.get("WE")))
        print("time(UTC):", gps.get("TIME"))
    else:
        print("no fix")

    for i in (1, 2, 3):
        sv = gps.get("SATELLITE%d" % i)
        if sv:
            print("satellite:", sv, "snr:", gps.get("SATELLITE%d_SNR" % i))


async def read_gps_state():
    ok, ret = await cassiablue.send_cmd("/cassia/info")
    if not ok:
        print("get info failed:", ret)
        return
    print_gps(json.loads(ret).get("gps"))


async def request_gps():
    try:
        ok, ret = await asyncio.wait_for(cassiablue.send_cmd("/cassia/gps/request"), REQUEST_TIMEOUT_S)
    except asyncio.TimeoutError:
        print("gps request timeout, no fix yet")
        return

    if not ok:
        print("gps request failed:", ret)
        return
    print_gps(json.loads(ret).get("gps"))


async def main():
    print("read cached gps state")
    await read_gps_state()

    print("request gps")
    await request_gps()


asyncio.run(main())

API

Request Positioning

ok, result = await asyncio.wait_for(cassiablue.send_cmd("/cassia/gps/request"), 30)

Successful response example:

{
  "gps": {
    "TIME": "07:40:09",
    "LON": "117.14.18",
    "LAT": "32.47.21",
    "NS": "N",
    "WE": "E",
    "SATELLITE1": 8,
    "SATELLITE1_SNR": 37,
    "SATELLITE2": 26,
    "SATELLITE2_SNR": 44,
    "SATELLITE3": 31,
    "SATELLITE3_SNR": 46
  }
}

gps Fields

Field	Type	Description	Example
TIME	str	UTC time	07:40:09
LON	str	Longitude (degrees.minutes.seconds)	117.14.18
LAT	str	Latitude (degrees.minutes.seconds)	32.47.21
NS	str	Hemisphere (N north S south)	N
WE	str	Hemisphere (E east W west)	E
SATELLITE1~3	int	Satellite ID (0 means none)	8
SATELLITE1~3_SNR	int	Satellite SNR	37

Coordinate Format

LAT / LON use the degrees.minutes.seconds format, not decimal degrees. Conversion:

32.47.21 = 32 + 47/60 + 21/3600 = 32.789167

When NS is S or WE is W, the corresponding coordinate is negative.

Read the GPS State

The gps field in the GET /cassia/info response is the latest GPS state, with the same fields as the table above. Without a fix, LAT / LON are empty strings.

Enable GPS at Startup

body = json.dumps({"dongle": {"gps_startup": "1"}})
ok, result = await cassiablue.send_cmd("/cassia/info", "POST", None, body)

Refer to Get/Set Gateway Info for how to set it. After the configuration changes, the gateway reboots and GPS is enabled automatically after the reboot.