.. _SLM_AT_SOCKET:

Socket AT commands
******************

.. contents::
   :local:
   :depth: 2

This page describes socket-related AT commands.
The application can open up to 8 sockets and select the active one among them.

For more information on the networking services, see the `Zephyr Network APIs`_.

Socket #XSOCKET
===============

The ``#XSOCKET`` command allows you to open or close a socket and to check the socket handle.

Set command
-----------

The set command allows you to open or close a socket.

Syntax
~~~~~~

::

   #XSOCKET=<op>[,<type>,<role>[,<cid>]]

* The ``<op>`` parameter can accept one of the following values:

  * ``0`` - Close a socket.
  * ``1`` - Open a socket for IP protocol family version 4.
    Protocol family is ignored with ``<type>`` parameter value ``3``.
  * ``2`` - Open a socket for IP protocol family version 6.
    Protocol family is ignored with ``<type>`` parameter value ``3``.

  When ``0``, the highest-ranked socket is made active after the current one is closed.

* The ``<type>`` parameter can accept one of the following values:

  * ``1`` - Set ``SOCK_STREAM`` for the stream socket type using the TCP protocol.
  * ``2`` - Set ``SOCK_DGRAM`` for the datagram socket type using the UDP protocol.
  * ``3`` - Set ``SOCK_RAW`` for the raw socket type using a generic packet protocol.
    The ``<op>`` parameter can be either ``1`` or ``2`` as raw socket ignores the protocol family.

* The ``<role>`` parameter can accept one of the following values:

  * ``0`` - Client.
  * ``1`` - Server.

* The ``<cid>`` parameter is an integer indicating the used PDN connection.
  It represents ``cid`` in the ``+CGDCONT`` command.
  Its default value is ``0``.

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKET: <handle>,<type>,<protocol>
   #XSOCKET: <result>,"closed"

* The ``<handle>`` value is an integer and can be interpreted as follows:

  * Positive or ``0`` - The socket opened successfully.
  * Negative - The socket failed to open.

* The ``<type>`` value can be one of the following integers:

  * ``1`` - Set ``SOCK_STREAM`` for the stream socket type using the TCP protocol.
  * ``2`` - Set ``SOCK_DGRAM`` for the datagram socket type using the UDP protocol.
  * ``3`` - Set ``SOCK_RAW`` for the raw socket type using a generic IP protocol.

* The ``<protocol>`` value can be one of the following integers:

  * ``0`` - IPPROTO_IP.
  * ``6`` - IPPROTO_TCP.
  * ``17`` - IPPROTO_UDP.

* The ``<result>`` value indicates the result of closing the socket.
  When ``0``, the socket closed successfully.

Examples
~~~~~~~~

::

   AT#XSOCKET=1,1,0
   #XSOCKET: 3,1,6
   OK
   AT#XSOCKET=1,2,0
   #XSOCKET: 1,2,17
   OK
   AT#XSOCKET=2,1,0
   #XSOCKET: 1,1,6
   OK
   AT#XSOCKET=1,3,0
   #XSOCKET: 1,3,0
   OK
   AT#XSOCKET=0
   #XSOCKET: 0,"closed"
   OK

Read command
------------

The read command allows you to check the socket handle.

Syntax
~~~~~~

::

   #XSOCKET?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKET: <handle>,<family>,<role>,<type>,<cid>

* The ``<handle>`` value is an integer.
  When positive or ``0``, the socket is valid.

* The ``<family>`` value is present only in the response to a request to open the socket.
  It can return one of the following values:

  * ``1`` - IP protocol family version 4.
  * ``2`` - IP protocol family version 6.
  * ``3`` - Packet family.

* The ``<role>`` value can be one of the following integers:

  * ``0`` - Client.
  * ``1`` - Server.

* The ``<type>`` value can be one of the following integers:

  * ``1`` - Set ``SOCK_STREAM`` for the stream socket type using the TCP protocol.
  * ``2`` - Set ``SOCK_DGRAM`` for the datagram socket type using the UDP protocol.
  * ``3`` - Set ``SOCK_RAW`` for the raw socket type using a generic packet protocol.

* The ``<cid>`` parameter is an integer indicating the used PDN connection.
  It represents ``cid`` in the ``+CGDCONT`` command.

Example
~~~~~~~~

::

   AT#XSOCKET?
   #XSOCKET: 3,1,0,1,0
   OK

Test command
------------

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

Syntax
~~~~~~

::

   #XSOCKET=?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKET: <list of ops>,<list of types>,<list of roles>,<cid>

Example
~~~~~~~~

::

   AT#XSOCKET=?
   #XSOCKET: (0,1,2),(1,2,3),(0,1),<cid>
   OK

Secure socket #XSSOCKET
=======================

The ``#XSSOCKET`` command allows you to open or close a secure socket, and to check the socket handle.

.. note::
   TLS and DTLS servers are currently not supported.

Set command
-----------

The set command allows you to open or close a secure socket.

Syntax
~~~~~~

::

   #XSSOCKET=<op>[,<type>,<role>,<sec_tag>[,<peer_verify>[,<cid>]]

* The ``<op>`` parameter can accept one of the following values:

  * ``0`` - Close a socket.
  * ``1`` - Open a socket for IP protocol family version 4.
  * ``2`` - Open a socket for IP protocol family version 6.

  When ``0``, the highest-ranked socket is made active after the current one is closed.

* The ``<type>`` parameter can accept one of the following values:

  * ``1`` - Set ``SOCK_STREAM`` for the stream socket type using the TLS 1.2 protocol.
  * ``2`` - Set ``SOCK_DGRAM`` for the datagram socket type using the DTLS 1.2 protocol.

* The ``<role>`` parameter can accept one of the following values:

  * ``0`` - Client.
  * ``1`` - Server.

* The ``<sec_tag>`` parameter is an integer.
  It indicates to the modem the credential of the security tag to be used for establishing a secure connection.
  It is associated with a credential, that is, a certificate or PSK. The credential should be stored on the modem side beforehand.
  Note that when ``<role>`` has a value of ``1``, ``<sec_tag>`` can only be used if the :file:`overlay-native_tls.conf` configuration file is used.

* The ``<peer_verify>`` parameter can accept one of the following values:

  * ``0`` - None (default for server role).
  * ``1`` - Optional.
  * ``2`` - Required (default for client role).

* The ``<cid>`` parameter is an integer indicating the used PDN connection.
  It represents ``cid`` in the ``+CGDCONT`` command.
  Its default value is ``0``.

Response syntax
~~~~~~~~~~~~~~~

::

   #XSSOCKET: <handle>,<type>,<protocol>
   #XSOCKET: <result>,"closed"

* The ``<handle>`` value is an integer and can be interpreted as follows:

  * Positive or ``0`` - The socket opened successfully.
  * Negative - The socket failed to open.

* The ``<type>`` value can be one of the following integers:

  * ``1`` - ``SOCK_STREAM`` for the stream socket type using the TLS 1.2 protocol.
  * ``2`` - ``SOCK_DGRAM`` for the datagram socket type using the DTLS 1.2 protocol.

* The ``<protocol>`` value can be one of the following integers:

  * ``258`` - IPPROTO_TLS_1_2.
  * ``273`` - IPPROTO_DTLS_1_2.

* The ``<result>`` value indicates the result of closing the socket.
  When ``0``, the socket closed successfully.

Examples
~~~~~~~~

::

   AT#XSSOCKET=1,1,0,16842753,2
   #XSSOCKET: 2,1,258
   OK
   AT#XSOCKET=0
   #XSOCKET: 0,"closed"
   OK

   AT#XSSOCKET=1,2,0,16842753
   #XSSOCKET: 2,2,273
   OK
   AT#XSOCKET=0
   #XSOCKET: 0,"closed"
   OK

Read command
------------

The read command allows you to check the secure socket handle.

Syntax
~~~~~~

::

   #XSSOCKET?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSSOCKET: <handle>,<family>,<role>,<type>,<sec_tag>,<cid>

* The ``<handle>`` value is an integer.
  When positive or ``0``, the socket is valid.

* The ``<family>`` value can be one of the following integers:

  * ``1`` - IP protocol family version 4.
  * ``2`` - IP protocol family version 6.

* The ``<role>`` value can be one of the following integers:

  * ``0`` - Client
  * ``1`` - Server

* The ``<type>`` value can be one of the following integers:

  * ``1`` - ``SOCK_STREAM`` for the stream socket type using the TLS 1.2 protocol.
  * ``2`` - ``SOCK_DGRAM`` for the datagram socket type using the DTLS 1.2 protocol.

* The ``<sec_tag>`` value is an integer.
  It indicates to the modem the credential of the security tag to be used for establishing a secure connection.

* The ``<cid>`` value is an integer indicating the used PDN connection.
  It represents ``cid`` in the ``+CGDCONT`` command.

Example
~~~~~~~~

::

   AT#XSSOCKET?
   #XSSOCKET: 2,1,0,1,16842753,0
   OK

Test command
------------

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

Syntax
~~~~~~

::

   #XSSOCKET=?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSSOCKET: <list of ops>,<list of types>,<list of roles>,<sec_tag>,<peer_verify>,<cid>

Example
~~~~~~~~

::

   AT#XSSOCKET=?
   #XSSOCKET: (0,1,2),(1,2),(0,1),<sec_tag>,<peer_verify>,<cid>
   OK

Select Socket #XSOCKETSELECT
============================

The ``#XSOCKETSELECT`` command allows you to select an active socket among multiple opened ones.

Set command
-----------

The set command allows you to select an active socket.

Syntax
~~~~~~

::

   #XSOCKETSELECT=<handle>

* The ``<handle>`` parameter is the handle value returned from the #XSOCKET or #XSSOCKET commands.

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKETSELECT: <handle>

* The ``<handle>`` value is an integer.
  When positive or ``0``, the socket is valid.

Example
~~~~~~~~

::

   AT#XSOCKETSELECT=4
   #XSOCKETSELECT: 4
   OK

Read command
------------

The read command allows you to list all sockets that have been opened and the active socket.

Syntax
~~~~~~

::

   #XSOCKETSELECT?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKETSELECT: <handle>,<family>,<role>,<type>,<sec_tag>,<ranking>,<cid>
   #XSOCKETSELECT: <handle_active>

* The ``<handle>`` value is an integer that indicates the handle of the socket.

* The ``<family>`` value can be one of the following integers:

  * ``1`` - IP protocol family version 4.
  * ``2`` - IP protocol family version 6.

* The ``<role>`` value can be one of the following integers:

  * ``0`` - Client.
  * ``1`` - Server.

* The ``<type>`` value can return one of the following:

  * ``1`` - Set ``SOCK_STREAM`` for the stream socket type using the TLS 1.2 protocol.
  * ``2`` - Set ``SOCK_DGRAM`` for the datagram socket type using the DTLS 1.2 protocol.

* The ``<sec_tag>`` value is an integer.
  It indicates to the modem the credential of the security tag to be used for establishing a secure connection.
  For a non-secure socket, it returns the value of –1.

* The ``<ranking>`` value is an integer.
  It indicates the ranking value of this socket, where the largest value means the highest ranking.

* The ``<cid>`` value is an integer indicating the used PDN connection.
  It represents ``cid`` in the ``+CGDCONT`` command.

* The ``<handle_active>`` value is an integer that indicates the handle of the active socket.

Examples
~~~~~~~~

::

  AT#XSOCKETSELECT?
  #XSOCKETSELECT: 0,1,0,1,-1,2,0
  #XSOCKETSELECT: 1,1,0,2,-1,3,0
  #XSOCKETSELECT: 2,1,0,1,16842755,4,0
  #XSOCKETSELECT: 3,1,0,2,16842755,5,0
  #XSOCKETSELECT: 4,1,1,1,-1,6,0
  #XSOCKETSELECT: 5,1,1,2,-1,7,0
  #XSOCKETSELECT: 6,1,1,1,16842755,8,0
  #XSOCKETSELECT: 7,1,0,1,-1,9,0
  #XSOCKETSELECT: 7
  OK

  AT#XSOCKETSELECT=4
  #XSOCKETSELECT: 4,1,1
  OK

  AT#XSOCKETSELECT?
  #XSOCKETSELECT: 0,1,0,1,-1,2,0
  #XSOCKETSELECT: 1,1,0,2,-1,3,0
  #XSOCKETSELECT: 2,1,0,1,16842755,4,0
  #XSOCKETSELECT: 3,1,0,2,16842755,5,0
  #XSOCKETSELECT: 4,1,1,1,-1,6,0
  #XSOCKETSELECT: 5,1,1,2,-1,7,0
  #XSOCKETSELECT: 6,1,1,1,16842755,8,0
  #XSOCKETSELECT: 7,1,0,1,-1,9,0
  #XSOCKETSELECT: 4
  OK

Test command
------------

The test command is not supported.

Socket options #XSOCKETOPT
==========================

The ``#XSOCKETOPT`` command allows you to get and set socket options.

Set command
-----------

The set command allows you to get and set socket options.

Syntax
~~~~~~

::

   #XSOCKETOPT=<op>,<name>[,<value>]

* The ``<op>`` parameter can accept one of the following values:

  * ``0`` - Get
  * ``1`` - Set

* The ``<name>`` parameter can accept one of the following values:

  * ``2`` - :c:macro:`AT_SO_REUSEADDR` (set-only).

    * ``<value>`` is an integer that indicates whether the reuse of local addresses is enabled.
      It is ``0`` for disabled or ``1`` for enabled.

  * ``20`` - :c:macro:`AT_SO_RCVTIMEO`.

    * ``<value>`` is an integer that indicates the receive timeout in seconds.

  * ``21`` - :c:macro:`AT_SO_SNDTIMEO`.

    * ``<value>`` is an integer that indicates the send timeout in seconds.

  * ``30`` - :c:macro:`AT_SO_SILENCE_ALL`.

    * ``<value>`` is an integer that indicates whether ICMP echo replies for IPv4 and IPv6 are disabled.
      It is ``0`` for allowing ICMP echo replies or ``1`` for disabling them.

  * ``31`` - :c:macro:`AT_SO_IP_ECHO_REPLY`.

    * ``<value>`` is an integer that indicates whether ICMP echo replies for IPv4 are enabled.
      It is ``0`` for disabled or ``1`` for enabled.

  * ``32`` - :c:macro:`AT_SO_IPV6_ECHO_REPLY`.

    * ``<value>`` is an integer that indicates whether ICMP echo replies for IPv6 are enabled.
      It is ``0`` for disabled or ``1`` for enabled.

  * ``40`` - :c:macro:`AT_SO_BINDTOPDN` (set-only).

    * ``<value>`` is an integer that indicates the packet data network ID to bind to.

  * ``55`` - :c:macro:`AT_SO_TCP_SRV_SESSTIMEO`.

    * ``<value>`` is an integer that indicates the TCP server session inactivity timeout for a socket.
      It accepts values from the range ``0`` to ``135``, where ``0`` is no timeout and ``135`` is 2 hours, 15 minutes.

  * ``61`` - :c:macro:`AT_SO_RAI` (set-only).
    Release Assistance Indication (RAI).

    * ``<value>`` The option accepts an integer, indicating the type of RAI.
      Accepted values for the option are:

      * ``1`` - :c:macro:`RAI_NO_DATA`.
        Indicates that the application does not intend to send more data.
        This socket option applies immediately and lets the modem exit connected mode more quickly.

      * ``2`` - :c:macro:`RAI_LAST`.
        Indicates that the application does not intend to send more data after the next call to :c:func:`send` or :c:func:`sendto`.
        This lets the modem exit connected mode more quickly after sending the data.

      * ``3`` - :c:macro:`RAI_ONE_RESP`.
        Indicates that the application is expecting to receive just one data packet after the next call to :c:func:`send` or :c:func:`sendto`.
        This lets the modem exit connected mode more quickly after having received the data.

      * ``4`` - :c:macro:`RAI_ONGOING`.
        Indicates that the application is expecting to receive just one data packet after the next call to :c:func:`send` or :c:func:`sendto`.
        This lets the modem exit connected mode more quickly after having received the data.

      * ``5`` - :c:macro:`RAI_WAIT_MORE`.
        Indicates that the socket is in active use by a server application.
        This lets the modem stay in connected mode longer.

  * ``62`` - :c:macro:`AT_SO_IPV6_DELAYED_ADDR_REFRESH`.

    * ``<value>`` is an integer that indicates whether delayed IPv6 address refresh is enabled.
      It is ``0`` for disabled or ``1`` for enabled.

See :ref:`nRF socket options <nrfxlib:nrf_sockets>` for explanation of the supported options.

Examples
~~~~~~~~

::

   AT#XSOCKETOPT=1,20,30
   OK

::

   AT#XSOCKETOPT=0,20
   #XSOCKETOPT: 30
   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
~~~~~~

::

   #XSOCKETOPT=?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSOCKETOPT: <list of ops>,<name>,<value>

Example
~~~~~~~~

::

   AT#XSOCKETOPT=?
   #XSOCKETOPT: (0,1),<name>,<value>
   OK

.. _SLM_AT_SSOCKETOPT:

Secure socket options #XSSOCKETOPT
==================================

The ``#XSSOCKETOPT`` command allows you to set secure socket options.

Set command
-----------

The set command allows you to set secure socket options.

Syntax
~~~~~~

::

   #XSSOCKETOPT=<op>,<name>[,<value>]

* The ``<op>`` parameter can accept one of the following values:

  * ``0`` - Get.
  * ``1`` - Set.

* The ``<name>`` parameter can accept one of the following values:

  * ``2`` - :c:macro:`AT_TLS_HOSTNAME`.

    * ``<value>`` is a string that indicates the hostname to check against during TLS handshakes.
      It can be ``NULL`` to disable hostname verification.

  * ``4`` - :c:macro:`AT_TLS_CIPHERSUITE_USED` (get-only).
    The TLS cipher suite chosen during the TLS handshake.
    This option is only supported with modem firmware 2.0.0 and newer.

  * ``5`` - :c:macro:`AT_TLS_PEER_VERIFY`.

    * ``<value>`` is an integer that indicates what peer verification level should be used.
      It is ``0`` for none, ``1`` for optional or ``2`` for required.

  * ``12`` - :c:macro:`AT_TLS_SESSION_CACHE`.

    * ``<value>`` is an integer that indicates whether TLS session caching should be used.
      It is ``0`` for disabled or ``1`` for enabled.

  * ``13`` - :c:macro:`AT_TLS_SESSION_CACHE_PURGE` (set-only).
    Indicates that the TLS session cache should be deleted.

    * ``<value>`` can be any integer value.

  * ``14`` - :c:macro:`AT_TLS_DTLS_CID` (set-only).

    * ``<value>`` is an integer that indicates the DTLS connection identifier setting.
      It can be one of the following values:

      * ``0`` - :c:macro:`TLS_DTLS_CID_DISABLED`.
      * ``1`` - :c:macro:`TLS_DTLS_CID_SUPPORTED`.
      * ``2`` - :c:macro:`TLS_DTLS_CID_ENABLED`.

    This option is only supported with modem firmware 1.3.5 and newer.
    See :ref:`nrfxlib:dtls_cid_setting` for more details regarding the allowed values.

  * ``15`` - :c:macro:`AT_TLS_DTLS_CID_STATUS` (get-only).
    It is the DTLS connection identifier status.
    It can be retrieved after the DTLS handshake.
    This option is only supported with modem firmware 1.3.5 and newer.
    See :ref:`nrfxlib:dtls_cid_status` for more details regarding the returned values.

  * ``18`` - :c:macro:`AT_TLS_DTLS_HANDSHAKE_TIMEO`.

    * ``<value>`` is an integer that indicates the DTLS handshake timeout in seconds.
      It can be one of the following values: ``1``, ``3``, ``7``, ``15``, ``31``, ``63``, ``123``.

See :ref:`nRF socket options <nrfxlib:nrf_sockets>` for explanation of the supported options.


Example
~~~~~~~~

::

   AT#XSSOCKETOPT=1,5,2
   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
~~~~~~

::

   #XSSOCKETOPT=?

Response syntax
~~~~~~~~~~~~~~~

::

   #XSSOCKETOPT: <list of ops>,<name>,<value>

Example
~~~~~~~~

::

   AT#XSSOCKETOPT=?
   #XSSOCKETOPT: (0,1),<name>,<value>
   OK


Socket binding #XBIND
=====================

The ``#XBIND`` command allows you to bind a socket with a local port.

This command can be used with TCP servers and both UDP clients and servers.

Set command
-----------

The set command allows you to bind a socket with a local port.

Syntax
~~~~~~

::

   #XBIND=<port>

* The ``<port>`` parameter is an unsigned 16-bit integer (0 - 65535).
  It represents the specific port to use for binding the socket.

Example
~~~~~~~~

::

   AT#XBIND=1234
   OK

Read command
------------

The read command is not supported.


Test command
------------

The test command is not supported.

Connection #XCONNECT
====================

The ``#XCONNECT`` command allows you to connect to a server and to check the connection status.

This command is for TCP and UDP clients.

Set command
-----------

The set command allows you to connect to a TCP or UDP server.

Syntax
~~~~~~

::

   #XCONNECT=<url>,<port>

* The ``<url>`` parameter is a string.
  It indicates the hostname or the IP address of the server.
  The maximum supported size of the hostname is 128 bytes.
  When using IP addresses, it supports both IPv4 and IPv6.

* The ``<port>`` parameter is an unsigned 16-bit integer (0 - 65535).
  It represents the port of the TCP or UDP service on the remote server.

Response syntax
~~~~~~~~~~~~~~~

::

   #XCONNECT: <status>

* The ``<status>`` value is an integer.
  It can return one of the following values:

* ``1`` - Connected.
* ``0`` - Disconnected.

Examples
~~~~~~~~

::

   AT#XCONNECT="test.server.com",1234
   #XCONNECT: 1
   OK

::

   AT#XCONNECT="192.168.0.1",1234
   #XCONNECT: 1
   OK

::

   AT#XCONNECT="2a02:c207:2051:8976::1",4567
   #XCONNECT: 1
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

Set listen mode #XLISTEN
========================

The ``#XLISTEN`` command allows you to put the TCP socket in listening mode for incoming connections.

This command is for TCP servers.

Set command
-----------

The set command allows you to put the TCP socket in listening mode for incoming connections.

Syntax
~~~~~~

::

   #XLISTEN

Response syntax
~~~~~~~~~~~~~~~

There is no response.

Example
~~~~~~~~

::

   AT#XLISTEN
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

Accept connection #XACCEPT
==========================

The ``#XACCEPT`` command allows you to accept an incoming connection from a TCP client.

This command is for TCP servers.

Set command
-----------

The set command allows you to wait for the TCP client to connect.

Syntax
~~~~~~

::

   #XACCEPT=<timeout>

* The ``<timeout>`` value sets the timeout value in seconds.
  ``0`` means no timeout, and it makes this request become blocking.

Response syntax
~~~~~~~~~~~~~~~

::

   #XACCEPT: <handle>,<ip_addr>

* The ``<handle>`` value is an integer.
  It represents the socket handle of the accepted connection.
* The ``<ip_addr>`` value indicates the IP address of the peer host.

Example
~~~~~~~~

::

   AT#XACCEPT=60
   #XACCEPT: 2,"192.168.0.2"
   OK

Read command
------------

The read command allows you to check socket handle of the accepted connection.

Syntax
~~~~~~

::

   #XACCEPT?

Response syntax
~~~~~~~~~~~~~~~

::

   #XACCEPT: <handle>

* The ``<handle>`` value is an integer and can be interpreted as follows:

  * Positive - The incoming socket is valid.
  * ``0`` - There is no active incoming connection.

Example
~~~~~~~~

::

   AT#XACCEPT?
   #XACCEPT: 192.168.0.2
   OK

Test command
------------

The test command is not supported.

Send data #XSEND
================

The ``#XSEND`` command allows you to send data over TCP and UDP connections.

Set command
-----------

The set command allows you to send data over the connection.

Syntax
~~~~~~

::

   #XSEND=[<data>][,<flags>]

* The ``<data>`` parameter is a string that contains the data to be sent.
  The maximum size of the data is 1024 bytes.
  When the parameter is not specified, SLM enters ``slm_data_mode``.

* The ``<flags>`` parameter sets the sending behavior.
  It can be set to the following value:

  * ``512`` - Blocks send operation until the request is acknowledged.
    The request will not return until the send operation is completed by lower layers, or until the timeout given by the AT_SO_SNDTIMEO socket option, is reached.
    Valid timeout values are 1 to 600 seconds.

Response syntax
~~~~~~~~~~~~~~~

::

   #XSEND: <size>

* The ``<size>`` value is an integer.
  It represents the actual number of bytes that has been sent.

Example
~~~~~~~~

::

   AT#XSEND="Test TCP"
   #XSEND: 8
   OK

   AT#XSEND=,512
   OK
   Test datamode with flags
   +++

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

Receive data #XRECV
===================

The ``#XRECV`` command allows you to receive data over TCP or UDP connections.

Set command
-----------

The set command allows you to receive data over the connection.

Syntax
~~~~~~

::

   #XRECV=<timeout>[,<flags>]

The ``<timeout>`` value sets the timeout value in seconds.
When ``0``, it means no timeout, and it makes this request become blocking.

The ``<flags>`` value sets the receiving behavior based on the BSD socket definition.
It can be set to one of the following values:

* ``2`` means reading data without removing it from the socket input queue.
* ``64`` means overriding the operation to non-blocking.
* ``256`` (TCP only) means blocking until the full amount of data can be returned.

Response syntax
~~~~~~~~~~~~~~~

::

   #XRECV: <size>
   <data>

* The ``<data>`` value is a string that contains the data being received.
* The ``<size>`` value is an integer that represents the actual number of bytes received.

Example
~~~~~~~~

::

   AT#XRECV=10
   #XRECV: 7
   Test OK
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

UDP send data #XSENDTO
======================

The ``#XSENDTO`` command allows you to send data over UDP.

Set command
-----------

The set command allows you to send data over UDP.

Syntax
~~~~~~

::

   #XSENDTO=<url>,<port>[,<data>][,<flags>]

* The ``<url>`` parameter is a string.
  It indicates the hostname or the IP address of the remote peer.
  The maximum size of the hostname is 128 bytes.
  When using IP addresses, it supports both IPv4 and IPv6.
* The ``<port>`` parameter is an unsigned 16-bit integer (0 - 65535).
  It represents the port of the UDP service on remote peer.
* The ``<data>`` parameter is a string that contains the data to be sent.
  Its maximum size is 1024 bytes.
  When the parameter is not specified, SLM enters ``slm_data_mode``.
* The ``<flags>`` parameter sets the sending behavior.
  It can be set to the following value:

  * ``512`` - Blocks send operation until the request is acknowledged.
    The request will not return until the send operation is completed by lower layers, or until the timeout given by the AT_SO_SNDTIMEO socket option, is reached.
    Valid timeout values are 1 to 600 seconds.

Response syntax
~~~~~~~~~~~~~~~

::

   #XSENDTO: <size>

* The ``<size>`` value is an integer.
  It represents the actual number of bytes that has been sent.

Example
~~~~~~~~

::

   AT#XSENDTO="test.server.com",1234,"Test UDP"
   #XSENDTO: 8
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

UDP receive data #XRECVFROM
===========================

The ``#XRECVFROM`` command allows you to receive data over UDP.

Set command
-----------

The set command allows you to receive data over UDP.

Syntax
~~~~~~

::

   #XRECVFROM=<timeout>[,<flags>]

The ``<timeout>`` value sets the timeout value in seconds.
When ``0``, it means no timeout, and it makes this request become blocking.

The ``<flags>`` value sets the receiving behavior based on the BSD socket definition.
It can be set to one of the following values:

* ``2`` means reading data without removing it from the socket input queue.
* ``64`` means overriding the operation to non-blocking.

Response syntax
~~~~~~~~~~~~~~~

::

   #XRECVFROM: <size>,"<ip_addr>",<port>
   <data>

* The ``<data>`` value is a string that contains the data being received.
* The ``<size>`` value is an integer that represents the actual number of bytes received.
* The ``<ip_addr>`` value is a string that represents the IPv4 or IPv6 address of the remote peer.
* The ``<port>`` value is an integer that represents the UDP port of the remote peer.

Example
~~~~~~~~

::

   AT#XRECVFROM=10
   #XRECVFROM: 7,"192.168.1.100",24210
   Test OK
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

Poll sockets #XPOLL
===================

The ``#XPOLL`` command allows you to poll selected or all sockets that have already been opened.

Set command
-----------

The set command allows you to poll a set of sockets to check whether they are ready for I/O.

Syntax
~~~~~~

::

   #XPOLL=<timeout>[,<handle1>[,<handle2> ...<handle8>]

* The ``<timeout>`` value sets the timeout value in milliseconds, and the poll blocks up to this timeout.
  ``0`` means no timeout, and the poll returns without blocking.
  ``-1`` means indefinite, and the poll blocks indefinitely until any events are received.

* The ``<handleN>`` value sets the socket handles to poll.
  The handles values could be obtained by ``AT#XSOCKETSELECT?`` command.
  If no handle values are specified, all opened sockets will be polled.

Response syntax
~~~~~~~~~~~~~~~

::

   #XPOLL: <error>
   #XPOLL: <handle>,<revents>

* The ``<error>`` value is an error code when the poll fails.
* The ``<handle>`` value is an integer.
  It is the handle of a socket that have events returned, so-called ``revents``.
* The ``<revents>`` value is a hexadecimal string.
  It represents the returned events, which could be a combination of ``POLLIN``, ``POLLERR``, ``POLLHUP``, and ``POLLNVAL``.

Examples
~~~~~~~~

::

   AT#XPOLL=2000,0
   #XPOLL: 0,"0x0001"
   OK

   AT#XPOLL=2000,1
   #XPOLL: 1,"0x0001"
   OK

   AT#XPOLL=2000
   #XPOLL: 0,"0x0001"
   #XPOLL: 1,"0x0001"
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.

Asynchronous socket polling #XAPOLL
===================================

The ``#XAPOLL`` command allows you to receive Unsolicited Result Code (URC) notifications for events on all opened sockets or for selected sockets that have already been opened.

.. note::

    The ``#XAPOLL`` command is not usable at the same time with the socket AT commands that use poll internally (``#XPOLL`` and ``#XACCEPT``).

Set command
-----------

The set command allows you to activate or deactivate asynchronous polling for sockets.

Activating asynchronous polling when it is already running, will stop the current polling and start a new one with the new parameters.

Syntax
~~~~~~

::

   #XAPOLL=<op>,<events>[,<handle1>[,<handle2> ...<handle8>]

* The ``<op>`` value can accept one of the following values:

  * ``0`` - Stop asynchronous polling.
  * ``1`` - Start asynchronous polling.

* The ``<events>`` value is an integer, which is interpreted as a bit field.
  It represents the events to poll for, which can be a combination of ``POLLIN`` and ``POLLOUT``.
  Permanent error and closure events (``POLLERR``, ``POLLHUP``, and ``POLLNVAL``) are always polled.
  The value can be any combination of the following values summed up:

  * ``0`` - Poll the default events.
  * ``1`` - Read events (``POLLIN``) are polled, in addition to the default events.
  * ``4`` - Write events (``POLLOUT``) are polled, in addition to the default events.

* The ``<handleN>`` value sets the socket handle to poll.
  Handles are sent in the ``AT#XSOCKET`` response.
  Handles can also be obtained with ``AT#XSOCKET?`` or ``AT#XSOCKETSELECT?`` commands.
  If no handles are specified, all open sockets will be polled, including any new sockets that are created after ``#XAPOLL`` has been started.

Response syntax
~~~~~~~~~~~~~~~

When the asynchronous socket events are enabled, SLM sends events as URC notifications.

* For ``POLLIN`` events, the URC notification is sent only for the first incoming data on the socket.
  ``AT#XRECV`` or ``AT#XRECVFROM`` command will re-enable the URC notification for the next incoming data.

* For ``POLLOUT`` events, the URC notification is sent only for the first time when the socket is ready for writing.
  ``AT#XSEND`` or ``AT#XSENDTO`` command will re-enable the URC notification for the next time when the socket is ready for writing.

* For ``POLLERR``, ``POLLHUP``, and ``POLLNVAL`` events, the URC notification is sent only once for each socket.
  No further URC notifications will be sent for the same socket.

::

   #XAPOLL: <handle>,<revents>

* The ``<handle>`` value is an integer.
  It is the handle of the socket that has events.
* The ``<revents>`` value is an integer, which must be interpreted as a bit field.
  It represents the returned events as a combination of ``POLLIN`` (1), ``POLLOUT`` (4), ``POLLERR`` (8), ``POLLHUP`` (16), and ``POLLNVAL`` (32) summed up.
  Hexadecimal representation is avoided to support AT command parsers that do not support hexadecimal values.

Example
~~~~~~~

::

   AT#XAPOLL=1,5

   OK

   AT#XSOCKET=1,1,0

   #XSOCKET: 1,1,6

   OK

   AT#XCONNECT="test.server.com",1234

   #XCONNECT: 1

   OK

   #XAPOLL: 1,4

   // Send data to the test server, which will echo it back.
   AT#XSEND="echo"

   #XSEND: 4

   OK

   #XAPOLL: 1,4

   // Test server sends the data back and closes the connection. POLLIN and POLLHUP events are received.
   #XAPOLL: 1,17

   AT#XRECV=1

   #XRECV: 4
   echo
   OK

   AT#XSOCKET=0

   #XSOCKET: 0,"closed"

   OK

   // #XAPOLL: 1,32 (POLLNVAL) is not received here as a closure event POLLHUP was already received.

   AT#XAPOLL=0

   OK

Read command
------------

The read command allows you to check the status of asynchronous polling.

Syntax
~~~~~~

::

   #XAPOLL?

Response syntax
~~~~~~~~~~~~~~~

::

   #XAPOLL: <running>,<events>,[<handle1> ...<handle8>]

* The ``<running>`` value can be one of the following integers:

  * ``0`` - Asynchronous polling is not running.
  * ``1`` - Asynchronous polling is running.

* The ``<events>`` value is an integer, which must be interpreted as a bit field.
  It represents the events that are being polled, which can be any combination of ``POLLIN`` and ``POLLOUT``.
  Permanent error and closure events (``POLLERR``, ``POLLHUP``, and ``POLLNVAL``) are always polled.
  The value can be any combination of the following values:

  * ``0`` - Poll the default events.
  * ``1`` - Poll read events (``POLLIN``) in addition to the default events.
  * ``4`` - Poll write events (``POLLOUT``) in addition to the default events.

* The ``<handleN>`` values return the socket handles that are being polled.

Example
~~~~~~~~

::

   AT#XSOCKET=1,1,0


   #XSOCKET: 0,1,6

   OK
   AT#XAPOLL=1,1


   OK
   AT#XAPOLL?


   #XAPOLL: 1,1,0

   OK

Test command
------------

The test command provides information about the command and its parameters.

Syntax
~~~~~~

::

   AT#XAPOLL=?

Response syntax
~~~~~~~~~~~~~~~

::

   #XAPOLL: <stop/start>,<events>,<handle1>,<handle2>,...

Example
~~~~~~~~

::

   AT#XAPOLL=?


   #XAPOLL: (0,1),<0,1,4,5>,<handle1>,<handle2>,...

   OK

Resolve hostname #XGETADDRINFO
==============================

The ``#XGETADDRINFO`` command allows you to resolve hostnames to IPv4 and IPv6 addresses.

Set command
-----------

The set command allows you to resolve hostnames to IPv4 and IPv6 addresses.

Syntax
~~~~~~

::

   #XGETADDRINFO=<hostname>[,<address_family>]

* The ``<hostname>`` parameter is a string.
* The ``<address_family>`` parameter is an integer that gives a hint for DNS query on address family.

  * ``0`` means unspecified address family.
  * ``1`` means IPv4 address family.
  * ``2`` means IPv6 address family.

  If ``<address_family>`` is not specified, there will be no hint given for DNS query.

Response syntax
~~~~~~~~~~~~~~~

::

   #XGETADDRINFO: "<ip_addresses>"

* The ``<ip_addresses>`` value is a string.
  It indicates the IPv4 or IPv6 address of the resolved hostname.

Example
~~~~~~~~

::

   AT#XGETADDRINFO="google.com"
   #XGETADDRINFO: "142.251.42.142"
   OK
   AT#XGETADDRINFO="google.com",0
   #XGETADDRINFO: "172.217.31.142"
   OK
   AT#XGETADDRINFO="google.com",1
   #XGETADDRINFO: "142.251.42.142"
   OK
   AT#XGETADDRINFO="ipv6.google.com",2
   #XGETADDRINFO: "2404:6800:4004:824::200e"
   OK

Read command
------------

The read command is not supported.

Test command
------------

The test command is not supported.
