GNSS AT commands
This page describes GNSS-related AT commands.
Control GNSS #XGNSS
The #XGNSS command controls the GNSS.
Set command
The set command allows you to start and stop the GNSS module.
Both the nRF Cloud A-GNSS service and the nRF Cloud P-GPS service can be used with the module, either together or independently of each other. Using them reduces the time it takes the GNSS module to estimate its position.
To use either of them, the device must be connected to nRF Cloud (using the #XNRFCLOUD AT command) when starting the GNSS module. In addition, the following Kconfig options must be enabled:
CONFIG_NRF_CLOUD_AGNSSto use A-GNSS.
CONFIG_NRF_CLOUD_PGPSto use P-GPS. This also requires applying theoverlay-pgps.overlaydevicetree overlay to both the application and themcubootimage (using the absolute path for the latter).
If both assistive services were enabled during compilation, you cannot choose to use only one of them at run time.
Syntax
AT#XGNSS=<op>,<cloud_assistance>,<interval>[,<timeout>]
The
<op>parameter can have the following integer values:0- Stop the GNSS module. In this case, no other parameter is allowed.1- Start the GNSS module.
<cloud_assistance>parameter is an integer that indicates whether to use the nRF Cloud assistive services that were enabled during compilation. It is0for disabled or1for enabled.<interval>parameter is an integer that indicates the GNSS fix interval in seconds. It can have one of the following values:0- Single-fix navigation mode.1- Continuous navigation mode. The fix interval is set to 1 second.Ranging from
10to65535- Periodic navigation mode. The fix interval is set to the specified value.
timeoutis an integer that indicates the maximum time in seconds that the GNSS receiver is allowed to run while trying to produce a valid Position, Velocity, and Time (PVT) estimate. It can only be specified in single-fix and periodic navigation modes, and must be omitted in continuous navigation mode. If omitted in single-fix or periodic navigation modes, the default value is 60 seconds.It can be one of the following:
0- The GNSS receiver runs indefinitely until a valid PVT estimate is produced.Any positive integer - The GNSS receiver is turned off after the specified time is up, even if a valid PVT estimate was not produced.
In periodic navigation mode, the <interval> and <timeout> parameters are temporarily ignored during the first fix.
Note
When <cloud_assistance> is disabled, no request is made to nRF Cloud for assistance data.
However, if it has been previously enabled and used, such data may remain locally available and will be used if still valid.
Note
Make sure that the GNSS antenna is configured properly. This can be achieved two ways:
Using the
CONFIG_MODEM_ANTENNA_AT_MAGPIOandCONFIG_MODEM_ANTENNA_AT_COEX0Kconfig options.By issuing the
%XMAGPIOand%XCOEX0AT commands manually at run time.
Tip
When the LTE link is enabled, make sure to have either Power Saving Mode (PSM) or extended Discontinuous Reception (eDRX) enabled to give the GNSS receiver the time it needs to acquire fixes.
Tip
Enable the CONFIG_SM_LOG_LEVEL_DBG Kconfig option if you have trouble acquiring fixes.
It makes the application print NMEA and PVT data when trying to acquire fixes, which can be of help when solving the issue.
Note
See the documentation for the nRF Cloud A-GNSS and nRF Cloud P-GPS libraries for information on how to best configure and use A-GNSS and P-GPS, respectively.
Note
When using P-GPS, make sure that the value of the CONFIG_SM_PGPS_INJECT_FIX_DATA Kconfig option matches your use case. It is enabled by default but should be disabled if the device is expected to move distances longer than a few dozen kilometers between fix attempts.
Note
When using P-GPS, apply the overlay-pgps.overlay devicetree overlay to both the application and the mcuboot image to provide a dedicated flash partition for P-GPS prediction data storage and to ensure MCUboot operates with the same partition layout.
The absolute path to the overlay file must be provided when passing it to the mcuboot image using mcuboot_EXTRA_DTC_OVERLAY_FILE.
See Configuration files for more information.
As an alternative to GNSS-based positioning, see #XNRFCLOUDPOS for cellular and Wi-Fi® positioning.
Unsolicited notification
#XGNSSPOS notification indicates that a new position fix has been acquired.
#XGNSSPOS: <latitude>,<longitude>,<altitude>,<accuracy>,<speed>,<heading>,<datetime>
The
<latitude>parameter represents the latitude in degrees.The
<longitude>parameter represents the longitude in degrees.The
<altitude>parameter represents the altitude above the WGS-84 ellipsoid in meters.The
<accuracy>parameter represents the accuracy (2D 1-sigma) in meters.The
<speed>parameter represents the horizontal speed in meters per second.The
<heading>parameter represents the heading of the movement of the user in degrees.The
<datetime>parameter represents the UTC date-time.
#XGNSS notification indicates GNSS status.
#XGNSS: <gnss_service>,<gnss_status>
The
<gnss_service>parameter is an integer. When it has the value1, it means that GNSS is supported in%XSYSTEMMODEand activated in+CFUN.The
<gnss_status>parameter is an integer. It can have the following values:0- GNSS is stopped.1- GNSS is started.2- GNSS wakes up in periodic mode.3- GNSS enters sleep because of timeout.4- GNSS enters sleep because a fix is acquired.
Example
Get GNSS fix in GNSS only mode:
AT%XSYSTEMMODE=0,0,1,0
OK
AT+CFUN=31
OK
AT#XGNSS=1,0,0,0
#XGNSS: 1,1
OK
#XGNSSPOS: 35.457576,139.625090,121.473785,22.199919,0.442868,0.000000,"2021-06-02 06:25:48"
#XGNSS: 1,4
Set PSM and eDRX configurations, use GNSS assistance from nRF Cloud and get GNSS fixes in continuous navigation mode:
AT%XSYSTEMMODE=1,0,1,0
OK
AT+CPSMS=1,,,"00000001","00000011"
OK
AT+CEDRXS=2,4,"0011"
OK
AT+CFUN=1
OK
+CEDRXP: 4,"0011","0011","0011"
AT#XNRFCLOUD=1
OK
#XNRFCLOUD: 1,0
AT#XGNSS=1,1,1
#XGNSS: 1,1
OK
#XGNSSPOS: 35.457417,139.625211,162.850952,15.621976,1.418092,0.000000,"2021-06-02 05:21:31"
#XGNSSPOS: 35.457435,139.625348,176.104797,14.245458,1.598184,69.148659,"2021-06-02 05:21:32"
#XGNSSPOS: 35.457417,139.625415,179.132980,13.318132,1.235241,69.148659,"2021-06-02 05:21:33"
#XGNSSPOS: 35.457410,139.625469,181.223541,12.667312,0.803951,69.148659,"2021-06-02 05:21:34"
AT#XGNSS=0
OK
#XGNSS: 1,0
Set PSM and eDRX configurations, use GNSS assistance from nRF Cloud and get GNSS fixes in periodic navigation mode every 10 seconds:
AT%XSYSTEMMODE=1,0,1,0
OK
AT+CPSMS=1,,,"00000001","00000011"
OK
AT+CEDRXS=2,4,"0011"
OK
AT+CFUN=1
OK
AT#XNRFCLOUD=1
OK
#XNRFCLOUD: 1,0
AT#XGNSS=1,1,10
#XGNSS: 1,1
OK
#XGNSS: 1,2
#XGNSSPOS: 35.457243,139.625435,149.005020,28.184258,10.431827,281.446014,"2021-06-24 04:35:52"
#XGNSS: 1,4
#XGNSS: 1,2
#XGNSSPOS: 35.457189,139.625602,176.811203,43.015198,0.601837,281.446014,"2021-06-24 04:36:32"
#XGNSS: 1,4
#XGNSS: 1,2
#XGNSSPOS: 35.457498,139.625422,168.243591,31.753956,0.191195,281.446014,"2021-06-24 04:37:12"
#XGNSS: 1,4
#XGNSS: 1,2
#XGNSSPOS: 35.457524,139.624667,100.745979,25.324850,6.347160,94.699837,"2021-06-24 04:37:52"
#XGNSS: 1,4
AT#XGNSS=0
#XGNSS: 1,0
OK
Read command
The read command allows you to check GNSS support and its status.
Syntax
AT#XGNSS?
Response syntax
#XGNSS: <gnss_service>,<gnss_status>
The
<gnss_service>parameter is an integer. When it has the value1, it means that GNSS is supported in%XSYSTEMMODEand activated in+CFUN.The
<gnss_status>parameter is an integer. It can have the following values:0- GNSS is stopped.1- GNSS is started.2- GNSS wakes up in periodic mode.3- GNSS enters sleep because of timeout.4- GNSS enters sleep because a fix is acquired.
Example
AT#XGNSS?
#XGNSS: 1,1
OK
Test command
The test command tests the existence of the command and provides information about the type of its subparameters.
Syntax
AT#XGNSS=?
Example
AT#XGNSS=?
#XGNSS: (0,1),(0,1),<interval>,<timeout>
OK
Delete GNSS data #XGNSSDEL
The #XGNSSDEL command deletes GNSS data from non-volatile memory.
This command should be issued when GNSS is activated but not started yet.
Note
This is a debug feature, and is not supposed to be used in production code.
Set command
The set command allows you to delete cached GNSS data. Using this command does not trigger A-GNSS nor P-GPS data request events. The execution of this command may delay the full functionality of A-GNSS and P-GPS until the next periodic data request has been received.
Syntax
AT#XGNSSDEL=<mask>
The <mask> parameter accepts an integer that is a bitwise OR of the following bitmasks:
0x001- Ephemerides0x002- Almanacs (excluding leap second and ionospheric correction)0x004- Ionospheric correction parameters0x008- Last good fix (the last position)0x010- GPS time-of-week (TOW)0x020- GPS week number0x040- Leap second (UTC parameters)0x100- Precision estimate of GPS time-of-week (TOW)0x400- Extended Kalman Filter (EKF) state (last position/velocity/time solution)
For example, the integer value with all of the above bits enabled will be 1407 (0x57f).
Example
AT%XSYSTEMMODE=0,0,1,0
OK
AT+CFUN=31
OK
AT#XGNSSDEL=1407
OK
AT+CFUN=0
OK
Read command
The read command is not supported.
Test command
The test command tests the existence of the command and provides information about the type of its subparameters.
Syntax
AT#XGNSSDEL=?
Example
AT#XGNSSDEL=?
#XGNSSDEL: <mask>
OK