From 293354e2b92d29b8f613bb875fd98f0ed04d595b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E5=BD=AC=E5=BD=AC?= Date: Wed, 20 Aug 2025 16:00:59 +0800 Subject: [PATCH] GNSS Update Section API Documentation --- en/gnsslib/quecgnss.md | 399 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 397 insertions(+), 2 deletions(-) diff --git a/en/gnsslib/quecgnss.md b/en/gnsslib/quecgnss.md index 0f4c9eb..48f2db6 100644 --- a/en/gnsslib/quecgnss.md +++ b/en/gnsslib/quecgnss.md @@ -5,7 +5,7 @@ This feature provides the APIs of the built-in GNSS feature. > QuecPython modules list that support built-in GNSS:
> ECX00U AA/LA series
> EG91XU AA series
-> EC800M GA/GB/GC/GD series
+> EC800M GA/GB/GC/GD series
EG810M GA series
EC800G GA series
> BG95M1/M3 model **Example** @@ -15,6 +15,9 @@ import quecgnss def main(): + quecgnss.configSet(0,1)#Set the positioning constellation to GPS + Beidou. + quecgnss.configSet(2,1)#Turn on AGPS + quecgnss.configSet(4,1)#Turn on the backup power supply ret = quecgnss.init() if ret == 0: print('GNSS init ok.') @@ -72,6 +75,190 @@ $GNGLL,3149.324754,N,11706.922338,E,022508.000,A,A*46 $GNGSA,A,3,31,3 ``` +## Overview of GNSS Positioning Data + +```python +NMEA Port Data Classification:： + $GPGGA Global Positioning System Fix Data + $GPGSA GNSS DOP and Active Satellites + $GPGSV GNSS Satellites in View + $GPRMC Recommended Minimum Specific GNSS Data + $GPVTG Course Over Ground and Ground Speed + $GPDTM Datum Reference + $GPGNS GNSS Fix Data +NMEA Sentence Parsing： +The basic format of the GSV sentence is as follows: + + $GPGSV,(1),(2),(3),(4),(5),(6),(7),...,(4),(5),(6),(7)*hh(CR)(LF) + + Field 1: Total number of GSV sentences. + + Field 2: Sequence number of the current GSV sentence. + + Field 3: Total number of satellites in view (00–12, leading zeros are transmitted). + + Field 4: Satellite PRN number (01–32, leading zeros are transmitted). + + Field 5: Elevation of the satellite (00–90 degrees, leading zeros are transmitted). + + Field 6: Azimuth of the satellite (000–359 degrees, leading zeros are transmitted). + + Field 7: Signal-to-noise ratio (00–99 dB; left blank if the satellite is not being tracked) — also referred to as the C/N0 value. + +The basic format of the GGA sentence is as follows: + + $GPGGA,(1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12)*hh(CR)(LF) + + Field 1: UTC time, hhmmss.sss (hours, minutes, seconds format). + + Field 2: Latitude ddmm.mmmm (degrees and minutes format, leading zeros transmitted). + + Field 3: Latitude hemisphere — N (North) or S (South). + + Field 4: Longitude dddmm.mmmm (degrees and minutes format, leading zeros transmitted). + + Field 5: Longitude hemisphere — E (East) or W (West). + + Field 6: GPS status — 0 = Invalid, 1 = GPS fix, 2 = DGPS fix, 3 = Invalid PPS, 6 = Estimated. + + Field 7: Number of satellites used (00–12, leading zeros transmitted). + + Field 8: HDOP (Horizontal Dilution of Precision), range 0.5–99.9. + + Field 9: Altitude (-9999.9 to 99999.9). + + Field 10: Altitude unit, meters. + + Field 11: Height of geoid (ellipsoid relative to mean sea level). + + Field 12: Height unit of geoid separation, meters. + +The basic format of the GSA sentence is as follows: + + $GPGSA,(1),(2),(3),(3),,,,,,,,,,(3),(4),(5),(6),(7)*hh(CR)(LF) + + Field 1: Mode — A = Automatic 2D/3D, M = Manual 2D/3D. + + Field 2: Fix type — 1 = No fix, 2 = 2D fix, 3 = 3D fix. + + Field 3: PRN codes — Satellite PRN number(s) being used in the current fix (00; leading zeros transmitted, up to 12 satellites). + + Field 4: PDOP (Position Dilution of Precision), range 0.0–500.0. + + Field 5: HDOP (Horizontal Dilution of Precision), range 0.0–500.0. + + Field 6: VDOP (Vertical Dilution of Precision), range 0.0–500.0. + + Field 7: Satellite system ID. + +The basic format of the VTG sentence is as follows: + + $GPVTG,(1),(2),(3),(4),(5),(6),(7),(8),(9)*hh(CR)(LF) + + Field 1: Course over ground (000–359, leading zeros transmitted). + + Field 2: Reference — T = True North. + + Field 3: Course over ground (000–359, leading zeros transmitted). + + Field 4: Reference — M = Magnetic North. + + Field 5: Horizontal speed (0.00, leading zeros transmitted). + + Field 6: Unit — N = Knots. + + Field 7: Horizontal speed (0.00, leading zeros transmitted). + + Field 8: Unit — K = Kilometers per hour (km/h). + + Field 9: Mode indicator — E = Estimated, A = Autonomous (non-DGPS). + +The basic format of the RMC sentence is as follows: + + $GPRMC,(1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13)*hh(CR)(LF) + + Field 1: UTC time, hhmmss.sss format. + + Field 2: Status — A = Valid (fix), V = Invalid (no fix). + + Field 3: Latitude ddmm.mmmm (degrees and minutes format, leading zeros transmitted). + + Field 4: Latitude hemisphere — N (North) or S (South). + + Field 5: Longitude dddmm.mmmm (degrees and minutes format, leading zeros transmitted). + + Field 6: Longitude hemisphere — E (East) or W (West). + + Field 7: Speed over ground, in knots. + + Field 8: Course over ground, in degrees. + + Field 9: UTC date, DDMMYY format. + + Field 10: Magnetic variation (000–180 degrees, leading zeros transmitted). + + Field 11: Magnetic variation direction — E (East) or W (West). + + Field 12: Mode indicator — E = Estimated, A = Autonomous (non-DGPS). + + Field 13: Navigation status — V = Navigation status not provided. + +The basic format of the DTM sentence is as follows: + + $GNDTM,<1>,<2>,<3>,<4>,<5>,<6>,<7>,<8>*<9>(CR)(LF) + + <1>Local datum code — W84, P90. + + <2>Datum subcode — blank. + + <3>Latitude offset. + + <4>Latitude hemisphere — N (North) or S (South). + + <5>Longitude offset. + + <6>Longitude hemisphere — E (East) or W (West). + + <7>Altitude offset. + + <8>Reference datum code — W84. + + <9>Checksum. + +The basic format of the GNS sentence is as follows: + + $GNGNS,<1>,<2>,<3>,<4>,<5>,<6>,<7>,<8>.<9>,<10>,<11>,<12>,<13>,*<14>(CR)(LF) + + <1> UTC time: Fix time hhmmss.ss — 000000.00 ~ 235959.99 + + <2> Latitude: ddmm.mmmmm — 0000.00000 ~ 8959.9999 + + <3> Latitude hemisphere: N = North, S = South + + <4> Longitude: dddmm.mmmmm — 0000.00000 ~ 17959.99999 + + <5> Longitude hemisphere: E = East, W = West + + <6> Mode indicator: N = No fix; A = Autonomous; D = Differential; P = Precise; R = RTK Fixed; F = RTK Float; E = Estimated; M = Manual input; S = Simulator + + <7> Satellites used: Number of satellites used in fix, 00–99 + + <8> HDOP: Horizontal Dilution of Precision, 0.5–99.9 + + <9> Altitude: Unit = meters + + <10> Geoid separation: Height of geoid relative to WGS84 ellipsoid + + <11> Differential data age: blank if prefix is “GN” + + <12> Reference station ID: blank if prefix is “GN” + + <13> Navigation status: C = Caution, S = Safe, U = Unsafe, V = Invalid + + <14> Checksum +``` + + ## Initialize GNSS @@ -151,4 +338,212 @@ A tuple `(size, data)` - Successful execution `size` - Size of the data read. `data` - GNSS location data. --1 - Failed execution \ No newline at end of file +-1 - Failed execution + +## GNSS/LTE Priority Settings + +> Currently, this function is only supported by BG95M1/M3 models. + +### `quecgnss.setPriority` + +```python +quecgnss.setPriority(Priority) +``` + +On some modules, GNSS and LTE share RF resources. This interface is used to control the priority of RF resource usage between GNSS and LTE. + +**Parameter** + +`Priority`， integer type, sets the priority value between GNSS and LTE. + +Correspondence of priority levels for GNSS/LTE on different platforms: + +| Priority | BG95M1/M3 | +| ------ | -------- | +| 0 | GNSS>LTE | +| 1 | LTE>GNSS | + +**Return Value** + + `0` - Successful execution + + `-1` - Failed execution + +## Get GNSS/LTE Priority + +> Currently, this function is only supported by BG95M1/M3 models. + +### `quecgnss.getPriority` + +```python +quecgnss.getPriority() +``` + +On some modules, GNSS and LTE share RF resources. This interface is used to read the priority of RF resource usage between GNSS and LTE. + +**Return Value** + +Returns an integer representing the GNSS/LTE priority. + +Correspondence of GNSS/LTE priority across different platforms: + +| Priority | BG95M1/M3 | +| ------ | -------- | +| 0 | GNSS>LTE | +| 1 | LTE>GNSS | + +## Built-in GNSS Configuration Parameter Settings + +> Currently, this function is supported only by the EC800M GA/GB/GC/GD series, EG810M GA series, and ECX00U AA/LA series. + +### `quecgnss.configSet` + +```python +quecgnss.configSet(config_type, config_value) +``` + +Sets GNSS parameters, including satellite system, NMEA sentence types, whether to use AGNSS, APFLASH, etc. + +**Parameter Description** + +* `config_type`，int，The types of GNSS configuration options to be set are as follows: + +| Value | Description | +| ---- | ---------------------- | +| 0 | Configure the satellite system to be used | +| 1 | Configure the types of NMEA sentences to output | +| 2 | Configure whether to enable AGPS | +| 3 | Configure whether to enable APFLASH | +| 4 | Configure whether to enable GNSS backup power | + +* `config_value`，int，The values of GNSS configuration options and their meanings are as follows: + +Satellite System（config_type = 0）： + +| Value | Description | +| ----- | ----------------------- | +| 0 | GPS | +| 1 | GPS + BeiDou | +| 3 | GPS + GLONASS + Galileo | +| 4 | GPS + GLONASS | +| 5 | GPS + BeiDou + Galileo | +| 6 | GPS + Galileo | +| 7 | BeiDou | + +NMEA Sentence Types (config_type = 1): This field is represented as a bitmap. Options to be enabled should be set to 1. +For example, to output GGA + RMC + GSV + GSA + VTG, the bitmap should be `011111`, which corresponds to a decimal value of 31. + +| Value | Description | +| ----- | --------------------- | +| 0 | Disable all (000000). | +| 1 | GGA(000001) | +| 2 | RMC(000010) | +| 4 | GSV(000100) | +| 8 | GSA(001000) | +| 16 | VTG(010000) | +| 32 | GLL(100000) | +| 63 | All outputs (111111). | + +Enable AGPS (config_type = 2): When enabled, GNSS will download ephemeris data from the network and attempt to use it at startup to accelerate positioning. + +| Value | Description | +| ----- | ----------- | +| 0 | Disable | +| 1 | Enable | + +Enable APFLASH (config_type = 3): When enabled, GNSS will store ephemeris data on the Quecpython module and attempt to use it at startup to accelerate positioning. + +| Value | Description | +| ----- | ----------- | +| 0 | Disable | +| 1 | Enable | + +Enable Backup Power (config_type = 4): When enabled and backup power is properly connected, the GNSS chip can autonomously store ephemeris data. + +>Backup power is supported on the EC800M GB/GD series. + +| Value | Description | +| ---- | ----------- | +| 0 | Disable | +| 1 | Enable | + +**Return Value** + +int: 0 indicates success; any other value indicates failure. + +## Read Built-in GNSS Configuration Parameters + +> Currently, this function is supported only by the EC800M GA/GB/GC/GD series, EG810M GA series, and ECX00U AA/LA series. + +### `quecgnss.configGet` + +```python +quecgnss.configGet(config_type) +``` + +Reads GNSS parameters, including satellite system, NMEA sentence types, whether AGNSS is used, APFLASH, etc. + +**Parameter Description** + +* `config_type`，int，The types of GNSS configuration options to be read are as follows： + +| Value | Description | +| ---- | ---------------------- | +| 0 | Configure the satellite system to be used | +| 1 | Configure the types of NMEA sentences to output | +| 2 | Configure whether to enable AGPS | +| 3 | Configure whether to enable APFLASH | +| 4 | Configure whether to enable GNSS backup power | + +**Return Value** + +int，Meanings are as follows (–1 indicates failure). + +Satellite System（config_type = 0）： + +| Value | Description | +| ----- | ----------------------- | +| 0 | GPS | +| 1 | GPS + BeiDou | +| 3 | GPS + GLONASS + Galileo | +| 4 | GPS + GLONASS | +| 5 | GPS + BeiDou + Galileo | +| 6 | GPS + Galileo | +| 7 | BeiDou | + +NMEA Sentence Types (config_type = 1): This field is represented as a bitmap. Options that are enabled are set to 1. +For example, if GGA + RMC + GSV + GSA + VTG are output, the returned value is 31, which corresponds to the bitmap 011111 in binary. + +| Value | Description | +| ----- | --------------------- | +| 0 | Disable all (000000). | +| 1 | GGA(000001) | +| 2 | RMC(000010) | +| 4 | GSV(000100) | +| 8 | GSA(001000) | +| 16 | VTG(010000) | +| 32 | GLL(100000) | +| 63 | All outputs (111111). | + +Enable AGPS (config_type = 2): When enabled, GNSS will download ephemeris data from the network and attempt to use it at startup to accelerate positioning. + +| Value | Description | +| ----- | ----------- | +| 0 | Disable | +| 1 | Enable | + +Enable APFLASH (config_type = 3): When enabled, GNSS will store ephemeris data on the Quecpython module and attempt to use it at startup to accelerate positioning. + +| Value | Description | +| ----- | ----------- | +| 0 | Disable | +| 1 | Enable | + +Enable Backup Power (config_type = 4): When enabled and backup power is properly connected, the GNSS chip can autonomously store ephemeris data. + +>Backup power is supported on the EC800M GB/GD series. + +| Value | Description | +| ---- | ----------- | +| 0 | Disable | +| 1 | Enable | \ No newline at end of file -- Gitee