.. _net_app_api:

Network Application API
#######################

The Network Application (net-app) API allows applications to:

**Initialize**
  The application for networking use. This means, for example,
  that if the application needs to have an IPv4 address, and if DHCPv4 is
  enabled, then the net-app API will make sure that the device will get an
  IPv4 address before the application is started.

**Set**
  Various options for the networking subsystem. This means that if the
  user has set options like IP addresses, IEEE 802.15.4 channel etc. in the
  project configuration file, then those settings are applied to the system
  before the application starts.

**Create**
  A simple TCP/UDP server or client application. The net-app API
  has functions that make it easy to create a simple TCP or UDP based network
  application. The net-app API also provides transparent TLS and DTLS support
  for the application.

The net-app API functionality is enabled by :option:`CONFIG_NET_APP` option.
The current net-app API implementation is still experimental and may change and
improve in future releases.

Initialization
##############

The net-app API provides a :cpp:func:`net_app_init()` function that can
configure the networking subsystem for the application. The following
configuration options control this configuration:

:option:`CONFIG_NET_APP_AUTO_INIT`
  automatically configures the system according to other configuration options.
  The user does not need to call :cpp:func:`net_app_init()` in this case as that
  function will be automatically called when the system boots. This option is
  enabled by default.

:option:`CONFIG_NET_APP_INIT_TIMEOUT`
  specifies how long to wait for the network configuration during the system
  boot. For example, if DHCPv4 is enabled, and if the IPv4 address discovery
  takes too long or the DHCPv4 server is not found, the system will resume
  booting after this number of seconds.

:option:`CONFIG_NET_APP_NEED_IPV6`
  specifies that the application needs IPv6 connectivity. The
  :cpp:func:`net_app_init()` function will wait until it is able to setup an
  IPv6 address for the system before continuing. This means that the IPv6
  duplicate address detection (DAD) has finished and the system has properly
  setup the IPv6 address.

:option:`CONFIG_NET_APP_NEED_IPV6_ROUTER`
  specifies that the application needs IPv6 router connectivity; i.e., it needs
  access to external networks (such as the Internet). The
  :cpp:func:`net_app_init()` function will wait until it receives a router
  advertisement (RA) message from the IPv6 router before continuing.

:option:`CONFIG_NET_APP_NEED_IPV4`
  specifies that the application needs IPv4 connectivity. The
  :cpp:func:`net_app_init()` function will wait, unless a static IP address is
  configured, until it is able to setup an IPv4 address for the network
  subsystem.

Setup
#####

Various system level network configuration options can be added to the project
configuration file. These settings are enabled by the
:option:`CONFIG_NET_APP_SETTINGS` configuration option. This option is disabled
by default, and other net-app options may also be disabled by default if
generic support for the networking feature is disabled. For example, the IPv6
net-app options are only available if generic IPv6 support is enabled.

:option:`CONFIG_NET_APP_MY_IPV6_ADDR`
  This option sets a static IPv6 address for the system. This is typically only
  useful in device testing as normally the system should use SLAAC (IPv6
  Stateless Address Auto Configuration), which is enabled by default in the
  system. The system can be configured to use multiple IPv6 addresses; this is
  controlled by the :option:`CONFIG_NET_IF_UNICAST_IPV6_ADDR_COUNT`
  configuration option.

:option:`CONFIG_NET_APP_PEER_IPV6_ADDR`
  This option specifies what is the peer device IPv6 address. This is only
  useful when testing client/server type applications. This peer address is
  typically used as a parameter when calling :cpp:func:`net_app_connect()`.

:option:`CONFIG_NET_APP_MY_IPV4_ADDR`
  This option sets a static IPv4 address for the system. This is typically
  useful only in device testing as normally the system should use DHCPv4 to
  discover the IPv4 address.

:option:`CONFIG_NET_APP_PEER_IPV4_ADDR`
  This option specifies what is the peer device IPv4 address. This is only
  useful when testing client/server type applications. This peer address is
  typically used as a parameter when connecting to other device.

The following options are only available if IEEE 802.15.4 wireless network
technology support is enabled.

:option:`CONFIG_NET_APP_IEEE802154_DEV_NAME`
  This option specifies the name of the IEEE 802.15.4 device.

:option:`CONFIG_NET_APP_IEEE802154_PAN_ID`
  This option specifies the used PAN identifier.
  Note that the PAN id can be changed at runtime if needed.

:option:`CONFIG_NET_APP_IEEE802154_CHANNEL`
  This option specifies the used radio channel.
  Note that the used channel can be changed at runtime if needed.

:option:`CONFIG_NET_APP_IEEE802154_RADIO_TX_POWER`
  This option specifies the initial radio TX power level. The TX power level can
  be changed at runtime if needed.

:option:`CONFIG_NET_APP_IEEE802154_SECURITY_KEY`
  This option specifies the initially used security key. The security key can be
  changed at runtime if needed.

:option:`CONFIG_NET_APP_IEEE802154_SECURITY_KEY_MODE`
  This option specifies the initially used security key mode. The security key
  mode can be changed at runtime if needed.

:option:`CONFIG_NET_APP_IEEE802154_SECURITY_LEVEL`
  This option specifies the initially used security level. The used security
  level can be changed at runtime if needed.

Client / Server Applications
############################

The net-app API provides functions that enable the application to create
client / server applications easily. If needed, the applications can
have the communication secured by TLS (for TCP connections) or DTLS (for
UDP connections) automatically.

A simple **TCP server** application would make the following net-app API
function calls:

* :cpp:func:`net_app_init_tcp_server()` to configure a local address and TCP
  port.

* :cpp:func:`net_app_set_cb()` to configure callback functions to invoke in
  response to events, such as data reception.

* :cpp:func:`net_app_server_tls()` will optionally setup the system for secured
  connections. To enable the TLS server, also call the
  :cpp:func:`net_app_server_tls_enable()` function.

* :cpp:func:`net_app_listen()` will start listening for new client connections.

Creating a **UDP server** is also very easy:

* :cpp:func:`net_app_init_udp_server()` to configure a local address and UDP
  port.

* :cpp:func:`net_app_set_cb()` to configure callback functions to invoke in
  response to events, such as data reception.

* :cpp:func:`net_app_server_tls()` will optionally setup the system for secured
  connections. To enable the DTLS server, also call the
  :cpp:func:`net_app_server_tls_enable()` function.

* :cpp:func:`net_app_listen()` will start listening for new client connections.

If the server wants to stop listening for connections, it can call
:cpp:func:`net_app_release()`. After this, if the application wants to start
listening for incoming connections again, it must call the server
initialization functions.

For TLS/DTLS connections, the server can be disabled by a call to
:cpp:func:`net_app_server_tls_disable()`. There are separate enable/disable
functions for TLS support because we need a separate crypto thread for calling
mbedtls crypto API functions. The enable/disable TLS functions will
either create the TLS thread or kill it.

A simple **TCP client** application would make the following net-app API
function calls:

* :cpp:func:`net_app_init_tcp_client()` to configure a local address, peer
  address and TCP port. If the DNS resolver support is enabled in the
  project configuration file, then the peer address can be given as a hostname,
  and the API tries to resolve it to IP address before connecting.

* :cpp:func:`net_app_set_cb()` to configure callback functions to invoke in
  response to events, such as data reception.

* :cpp:func:`net_app_client_tls()` will optionally setup the system for secured
  connections. The TLS crypto thread will be automatically created when the
  application calls :cpp:func:`net_app_connect()` function.

* :cpp:func:`net_app_connect()` will initiate a new connection to the peer host.

Creating a **UDP client** is also very easy:

* :cpp:func:`net_app_init_udp_client()` to configure a local address, peer
  address and UDP port. If peer name is a hostname, then it will be
  automatically resolved to IP address if DNS resolver is enabled.

* :cpp:func:`net_app_set_cb()` to configure callback functions to invoke in
  response to events, such as data reception.

* :cpp:func:`net_app_client_tls()` will optionally setup the system for secured
  connections. The DTLS crypto thread will be automatically created when the
  application calls :cpp:func:`net_app_connect()` function.

* :cpp:func:`net_app_connect()` will initiate a new connection to the peer host.
  As the UDP is connectionless protocol, this function is very simple and it
  will just call the connected callback if that is defined.

As both the ``echo_server`` and ``echo_client`` applications use net-app API
functions, please see those applications for more detailed usage examples.

The `net-tools`_ project has information how to test the system if TLS and
DTLS support is enabled. See the **README** file in that project for more
information.

.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools