221 lines
9.5 KiB
ReStructuredText
221 lines
9.5 KiB
ReStructuredText
.. _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
|