nRF Cloud AT commands

Note

These AT commands are Experimental.

The page describes nRF Cloud-related AT commands.

nRF Cloud access

The #XNRFCLOUD command controls the access to the nRF Cloud service.

Note

To use #XNRFCLOUD, the following preconditions apply:

  • You must first onboard the device to nRF Cloud, using the device-specific UUID as the device ID. See nRF Cloud Preconnect onboarding for more information.

  • The CONFIG_SM_NRF_CLOUD Kconfig option must be enabled.

  • The device must have access to nRF Cloud through the LTE network.

Set command

The set command allows you to access the nRF Cloud service.

Note

The #XNRFCLOUD command uses default PDN connection with ID 0. Raw sockets must not use the PDN connection at the same time. See Socket AT commands for more information.

Syntax

AT#XNRFCLOUD=<op>[,<send_location>]

  • The <op> parameter can have the following integer values:

    • 0 - Disconnect from the nRF Cloud service.

    • 1 - Connect to the nRF Cloud service.

    • 2 - Send a message in the JSON format to the nRF Cloud service.

    When <op> is 2, Serial Modem enters Data mode.

  • The <send_location> parameter is used only when the value of <op> is 1. It can have the following integer values:

    • 0 - The device location is not sent to nRF Cloud. This is the default behavior if the parameter is omitted.

    • 1 - The device location is sent to nRF Cloud.

    Note

    The location is sent to the nRF Cloud whenever a fix is produced by the GNSS module. You must use the #XGNSS AT command to start GNSS either in single-fix or periodic navigation mode. The interval between fixes must be at least 5 seconds.

Unsolicited notification

#XNRFCLOUD: <ready>,<send_location>

  • The <ready> parameter indicates whether the connection to nRF Cloud is established or not.

  • The <send_location> parameter indicates whether the device location will be sent to nRF Cloud or not.

Example

// Connect to nRF Cloud without sending location.
AT#XNRFCLOUD=1

OK

#XNRFCLOUD: 1,0
// Send a message to nRF Cloud.
AT#XNRFCLOUD=2

OK
{"msg":"Hello, nRF Cloud"}+++

#XDATAMODE: 0
// Disconnect from nRF Cloud.
AT#XNRFCLOUD=0

OK

#XNRFCLOUD: 0,0
// Connect to nRF Cloud and send location.
AT#XNRFCLOUD=1,1

OK

#XNRFCLOUD: 1,1
AT#XNRFCLOUD=0

#XNRFCLOUD: 0,1

OK

Read command

The read command checks whether the connection to nRF Cloud is established or not.

Syntax

AT#XNRFCLOUD?

Response syntax

#XNRFCLOUD: <ready>,<send_location>,<sec_tag>,<device_id>

  • The <ready> parameter indicates whether the connection to nRF Cloud is established or not.

  • The <send_location> parameter indicates whether the device location will be sent to nRF Cloud or not.

  • The <sec_tag> parameter indicates the sec_tag used for accessing nRF Cloud.

  • The <device_id> parameter indicates the device ID used for accessing nRF Cloud.

Example

AT#XNRFCLOUD?

#XNRFCLOUD: 1,0,16842753,"50503041-3633-4261-803d-1e2b8f70111a"

OK

Test command

The test command tests the existence of the command and provides information about the type of its subparameters.

Syntax

AT#XNRFCLOUD=?

Example

AT#XNRFCLOUD=?

#XNRFCLOUD: (0,1,2),<send_location>

OK

nRF Cloud location

The #XNRFCLOUDPOS command sends a request to nRF Cloud to determine the device’s location. The request uses information from the cellular network, Wi-Fi® access points, or both.

Note

To use #XNRFCLOUDPOS, the following preconditions apply:

Set command

The set command allows sending a location request to nRF Cloud.

Syntax

AT#XNRFCLOUDPOS=<cell_count>,<wifi_pos>[,<MAC 1>[,<RSSI 1>],<MAC 2>[,<RSSI 2>][,<MAC 3>[...]]]

  • The <cell_count> parameter indicates the number of cells to include in the location request. The value range is 0 to 15. For cellular positioning, a recommended value is 4. 0 means that no cellular network information will be included in the location request. The Serial Modem uses the AT%NCELLMEAS command to retrieve the cellular network information, and depending on the value of <cell_count>, the command might be executed multiple times.

    Note

    Since the Serial Modem uses the AT%NCELLMEAS command internally, the host must not use the AT%NCELLMEAS command during #XNRFCLOUDPOS command execution. You may still use AT%NCELLMEAS command before or after #XNRFCLOUDPOS command execution for your own purposes. You will also see %NCELLMEAS notifications, which you can ignore, during the #XNRFCLOUDPOS command execution.

  • The <wifi_pos> parameter can have the following integer values:

    • 0 - Do not include Wi-Fi access point information in the location request.

    • 1 - Use Wi-Fi access point information. The access points must be given as additional parameters to the command. The minimum number of access points to provide is two (NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN), and the maximum is limited by the AT command buffer size (CONFIG_SM_AT_BUF_SIZE).

  • The <MAC x> parameter is a string. It indicates the MAC address of a Wi-Fi access point and must be formatted as %02x:%02x:%02x:%02x:%02x:%02x (WIFI_MAC_ADDR_TEMPLATE).

  • The <RSSI x> parameter is an optional integer. It indicates the signal strength of a Wi-Fi access point in dBm, between -128 and 0. If provided, it must follow the MAC address parameter of the access point. Providing the RSSI parameters helps improve the accuracy of the Wi-Fi location.

Unsolicited notification

#XNRFCLOUDPOS: <status>[,<type>,<latitude>,<longitude>,<uncertainty>]

  • The <status> parameter indicates the status of the location request.

    • 0 - Successful request. Other parameters are also present.

    • -1 - Location request failed.

    • <positive integer> - Requesting location from the cloud failed with cloud error as defined in nrf_cloud_error values.

This is emitted when a successful response to a sent location request is received.

  • The <type> parameter indicates the service used to fulfill the location request.

    • 0 (LOCATION_TYPE_SINGLE_CELL) - Single-cell cellular location.

    • 1 (LOCATION_TYPE_MULTI_CELL) - Multi-cell cellular location.

    • 2 (LOCATION_TYPE_WIFI) - Wi-Fi location.

  • The <latitude> parameter represents the latitude in degrees.

  • The <longitude> parameter represents the longitude in degrees.

  • The <uncertainty> parameter represents the radius of the uncertainty circle around the location in meters, also known as Horizontal Positioning Error (HPE).

Example

AT%XSYSTEMMODE=1,0,0,0

OK
AT+CFUN=1

OK
AT#XNRFCLOUD=1

OK

#XNRFCLOUD: 1,0
AT#XNRFCLOUDPOS=1,0

OK

#XNRFCLOUDPOS: 0,0,35.455833,139.626111,1094

AT#XNRFCLOUDPOS=5,0

OK

%NCELLMEAS: 0,"0199F10A","44020","107E",65535,3750,5,49,27,107504,3750,251,33,4,0,475,107,26,14,25,475,58,26,17,25,475,277,24,9,25,475,51,18,1,25

%NCELLMEAS: 0,"01234567","44020","0340",50,175456,3400,34,5,24,1775066,1,0,"00143FAE","44020","0140",65535,0,6200,47,40,14,1775066,0,0

%NCELLMEAS: 0,"00987654","44020","0240",50,1754746,5500,44,4,4,1463457,1,0,"002F4344","44020","0140",65535,0,6200,47,40,14,1775066,0,0,"001C0502","44013","5A00",65535,0,6400,130,29,18,1775124,0,0,"00136107","44013","5A00",65535,0,3600,202,26,13,234533,0,0

#XNRFCLOUDPOS: 0,1,35.455833,139.626111,1094
AT#XNRFCLOUDPOS=0,1,"40:9b:cd:c1:5a:40","00:90:fe:eb:4f:42"

OK

#XNRFCLOUDPOS: 0,2,35.457335,139.624443,60
AT#XNRFCLOUDPOS=0,1,"40:9b:cd:c1:5a:40",-40,"00:90:fe:eb:4f:42",-69

OK

#XNRFCLOUDPOS: 0,2,35.457346,139.624449,20

Read command

The read command is not supported.

Test command

The test command is not supported.