nRF Cloud AT commands ********************* .. contents:: :local: :depth: 2 .. note:: These AT commands are `Experimental `_. The page describes nRF Cloud-related AT commands. .. _SM_AT_NRFCLOUD: 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 :ref:`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 :ref:`SM_AT_SOCKET_RAW_SOCKET_LIMITATION` for more information. Syntax ~~~~~~ :: AT#XNRFCLOUD=[,] * The ```` 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 ```` is ``2``, |SM| enters :ref:`sm_data_mode`. * The ```` parameter is used only when the value of ```` 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 :ref:`#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: , * The ```` parameter indicates whether the connection to nRF Cloud is established or not. * The ```` 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: ,,, * The ```` parameter indicates whether the connection to nRF Cloud is established or not. * The ```` parameter indicates whether the device location will be sent to nRF Cloud or not. * The ```` parameter indicates the ``sec_tag`` used for accessing nRF Cloud. * The ```` 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), OK .. _SM_AT_NRFCLOUDPOS: 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: * The device must be connected to nRF Cloud using :ref:`#XNRFCLOUD `. * The :ref:`CONFIG_SM_NRF_CLOUD_LOCATION ` Kconfig option must be enabled. Set command ----------- The set command allows sending a location request to nRF Cloud. Syntax ~~~~~~ :: AT#XNRFCLOUDPOS=,[,[,],[,][,[...]]] * The ```` 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 |SM| uses the ``AT%NCELLMEAS`` command to retrieve the cellular network information, and depending on the value of ````, the command might be executed multiple times. .. note:: Since the |SM| 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 ```` 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 (:ref:`CONFIG_SM_AT_BUF_SIZE `). * The ```` 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 ```` 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: [,,,,] * The ```` parameter indicates the status of the location request. * ``0`` - Successful request. Other parameters are also present. * ``-1`` - Location request failed. * ```` - Requesting location from the cloud failed with cloud error as defined in :c:enum:`nrf_cloud_error` values. This is emitted when a successful response to a sent location request is received. * The ```` parameter indicates the service used to fulfill the location request. * ``0`` (:c:enumerator:`LOCATION_TYPE_SINGLE_CELL`) - Single-cell cellular location. * ``1`` (:c:enumerator:`LOCATION_TYPE_MULTI_CELL`) - Multi-cell cellular location. * ``2`` (:c:enumerator:`LOCATION_TYPE_WIFI`) - Wi-Fi location. * The ```` parameter represents the latitude in degrees. * The ```` parameter represents the longitude in degrees. * The ```` 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.