From 2534a09f6b718285239ca7c11d4afc67629cbaa6 Mon Sep 17 00:00:00 2001 From: Robert Lubos Date: Tue, 5 Dec 2023 12:43:43 +0100 Subject: [PATCH 1/2] net: doc: Reference the Kconfig option that enables app libraries Several application protocol libraries documentation missed information on how can they be enabled (i. e. missed info about associated Kconfig symbol). This commit fixes it. Signed-off-by: Robert Lubos --- doc/connectivity/networking/api/coap.rst | 3 ++- doc/connectivity/networking/api/coap_client.rst | 1 + doc/connectivity/networking/api/http.rst | 1 + doc/connectivity/networking/api/lwm2m.rst | 2 ++ doc/connectivity/networking/api/mqtt.rst | 3 ++- doc/connectivity/networking/api/mqtt_sn.rst | 3 ++- doc/connectivity/networking/api/tftp.rst | 6 ++++++ 7 files changed, 16 insertions(+), 3 deletions(-) diff --git a/doc/connectivity/networking/api/coap.rst b/doc/connectivity/networking/api/coap.rst index ffb794a0c8a3..e3a4d01d594b 100644 --- a/doc/connectivity/networking/api/coap.rst +++ b/doc/connectivity/networking/api/coap.rst @@ -17,7 +17,8 @@ that support CoAP's features. For more information about the protocol itself, see `IETF RFC7252 The Constrained Application Protocol `_. Zephyr provides a CoAP library which supports client and server roles. -The library is configurable as per user needs. The Zephyr CoAP library +The library can be enabled with :kconfig:option:`CONFIG_COAP` Kconfig option and +is configurable as per user needs. The Zephyr CoAP library is implemented using plain buffers. Users of the API create sockets for communication and pass the buffer to the library for parsing and other purposes. The library itself doesn't create any sockets for users. diff --git a/doc/connectivity/networking/api/coap_client.rst b/doc/connectivity/networking/api/coap_client.rst index 2251bb3d0da6..0d682a047465 100644 --- a/doc/connectivity/networking/api/coap_client.rst +++ b/doc/connectivity/networking/api/coap_client.rst @@ -11,6 +11,7 @@ Overview ******** The CoAP client library allows application to send CoAP requests and parse CoAP responses. +The library can be enabled with :kconfig:option:`CONFIG_COAP_CLIENT` Kconfig option. The application is notified about the response via a callback that is provided to the API in the request. The CoAP client handles the communication over sockets. As the CoAP client doesn't create socket it is using, the application is responsible for creating diff --git a/doc/connectivity/networking/api/http.rst b/doc/connectivity/networking/api/http.rst index 060a41643d9a..d32748e77fae 100644 --- a/doc/connectivity/networking/api/http.rst +++ b/doc/connectivity/networking/api/http.rst @@ -13,6 +13,7 @@ Overview The HTTP client library allows you to send HTTP requests and parse HTTP responses. The library communicates over the sockets API but it does not create sockets on its own. +It can be enabled with :kconfig:option:`CONFIG_HTTP_CLIENT` Kconfig option. The application must be responsible for creating a socket and passing it to the library. Therefore, depending on the application's needs, the library can communicate over diff --git a/doc/connectivity/networking/api/lwm2m.rst b/doc/connectivity/networking/api/lwm2m.rst index 3baa4516c5d5..dbf1f622b4e5 100644 --- a/doc/connectivity/networking/api/lwm2m.rst +++ b/doc/connectivity/networking/api/lwm2m.rst @@ -25,6 +25,8 @@ REST API to manage various interfaces with the client. LwM2M uses a simple resource model with the core set of objects and resources defined in the specification. +The LwM2M library can be enabled with :kconfig:option:`CONFIG_LWM2M` Kconfig option. + Example LwM2M object and resources: Device ****************************************** diff --git a/doc/connectivity/networking/api/mqtt.rst b/doc/connectivity/networking/api/mqtt.rst index 973b61860e35..9c75a20c5c25 100644 --- a/doc/connectivity/networking/api/mqtt.rst +++ b/doc/connectivity/networking/api/mqtt.rst @@ -16,7 +16,8 @@ publish/subscribe messaging transport for machine-to-machine communication. For more information about the protocol itself, see http://mqtt.org/. Zephyr provides an MQTT client library built on top of BSD sockets API. The -library is configurable at a per-client basis, with support for MQTT versions +library can be enabled with :kconfig:option:`CONFIG_MQTT_LIB` Kconfig option and +is configurable at a per-client basis, with support for MQTT versions 3.1.0 and 3.1.1. The Zephyr MQTT implementation can be used with either plain sockets communicating over TCP, or with secure sockets communicating over TLS. See :ref:`bsd_sockets_interface` for more information about Zephyr sockets. diff --git a/doc/connectivity/networking/api/mqtt_sn.rst b/doc/connectivity/networking/api/mqtt_sn.rst index 3da4d903725f..318073bbe223 100644 --- a/doc/connectivity/networking/api/mqtt_sn.rst +++ b/doc/connectivity/networking/api/mqtt_sn.rst @@ -17,7 +17,8 @@ over any message-based transport. Originally, it was mainly created with ZigBee but others like Bluetooth, UDP or even a UART can be used just as well. Zephyr provides an MQTT-SN client library built on top of BSD sockets API. The -library is configurable at a per-client basis, with support for MQTT-SN version +library can be enabled with :kconfig:option:`CONFIG_MQTT_SN_LIB` Kconfig option +and is configurable at a per-client basis, with support for MQTT-SN version 1.2. The Zephyr MQTT-SN implementation can be used with any message-based transport, but support for UDP is already built-in. diff --git a/doc/connectivity/networking/api/tftp.rst b/doc/connectivity/networking/api/tftp.rst index 36d9d2cf0bba..6bb309e07917 100644 --- a/doc/connectivity/networking/api/tftp.rst +++ b/doc/connectivity/networking/api/tftp.rst @@ -3,6 +3,12 @@ TFTP #### +Zephyr provides a simple TFTP client library that can enabled with +:kconfig:option:`CONFIG_MQTT_SN_LIB` Kconfig option. + +See :zephyr:code-sample:`TFTP client sample application ` for +more information about the library usage. + API Reference ************* From ae5af5a23e16cf3b571961861a9f33f376c58a94 Mon Sep 17 00:00:00 2001 From: Robert Lubos Date: Tue, 5 Dec 2023 12:57:18 +0100 Subject: [PATCH 2/2] net: doc: Remove Network Connectivity API page The Network Connectivity API page is kind of pointless, as it provides little information (which can be found elsewhere as well) and it was pointer out that it kind of creates noise in the documentation as it can be confused with the page which provides a summary of network APIs. Therefore, remove the page, and move the information from it elsewhere. The brief summary of what APIs to use was moved the Networking APIs index page. The information about the samples demonstrating BSD sockets API usage was moved to the BSD sockets documentation page itself. Signed-off-by: Robert Lubos --- doc/_scripts/redirects.py | 1 + doc/connectivity/networking/api/index.rst | 11 +++++++++++ doc/connectivity/networking/api/sockets.rst | 4 ++++ doc/connectivity/networking/index.rst | 1 - .../networking/networking-api-usage.rst | 16 ---------------- 5 files changed, 16 insertions(+), 17 deletions(-) delete mode 100644 doc/connectivity/networking/networking-api-usage.rst diff --git a/doc/_scripts/redirects.py b/doc/_scripts/redirects.py index 0394c7c016ab..2542818eb6f8 100644 --- a/doc/_scripts/redirects.py +++ b/doc/_scripts/redirects.py @@ -16,6 +16,7 @@ ('application/index', 'develop/application/index'), ('boards/x86/ehl_crb/doc/index', 'boards/x86/intel_ehl/doc/index'), ('boards/x86/rpl_crb/doc/index', 'boards/x86/intel_rpl/doc/index'), + ('connectivity/networking/networking-api-usage', 'connectivity/networking/api/index'), ('development_process/code_flow', 'project/code_flow'), ('development_process/index', 'project/index'), ('development_process/issues', 'project/issues'), diff --git a/doc/connectivity/networking/api/index.rst b/doc/connectivity/networking/api/index.rst index 2386a075460f..1264ff2aafb9 100644 --- a/doc/connectivity/networking/api/index.rst +++ b/doc/connectivity/networking/api/index.rst @@ -3,6 +3,17 @@ Networking APIs ############### +Zephyr provides support for the standard BSD socket APIs (defined in +:zephyr_file:`include/zephyr/net/socket.h`) for the applications to +use. See :ref:`BSD socket API ` for more details. + +Apart of the standard API, Zephyr provides a set of custom networking APIs and +libraries for the application to use. See the list below for details. + +.. note:: + The legacy connectivity API in :zephyr_file:`include/zephyr/net/net_context.h` + should not be used by applications. + .. toctree:: :maxdepth: 2 diff --git a/doc/connectivity/networking/api/sockets.rst b/doc/connectivity/networking/api/sockets.rst index 720bebeb8200..a2d1c4169c51 100644 --- a/doc/connectivity/networking/api/sockets.rst +++ b/doc/connectivity/networking/api/sockets.rst @@ -57,6 +57,10 @@ there is a table mapping file descriptors to internal object pointers. The file descriptor table is used by the BSD Sockets API even if the rest of the POSIX subsystem (filesystem, stdin/stdout) is not enabled. +See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client` +sample applications to learn how to create a simple server or client BSD socket based +application. + .. _secure_sockets_interface: Secure Sockets diff --git a/doc/connectivity/networking/index.rst b/doc/connectivity/networking/index.rst index f900bb563304..14efb069eac5 100644 --- a/doc/connectivity/networking/index.rst +++ b/doc/connectivity/networking/index.rst @@ -12,7 +12,6 @@ operation of the stacks and how they were implemented. overview.rst net-stack-architecture.rst - networking-api-usage.rst networking_with_host.rst network_monitoring.rst api/index.rst diff --git a/doc/connectivity/networking/networking-api-usage.rst b/doc/connectivity/networking/networking-api-usage.rst deleted file mode 100644 index 0145482fec9b..000000000000 --- a/doc/connectivity/networking/networking-api-usage.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _networking_api_usage: - -Network Connectivity API -######################## - -Applications should use the BSD socket API defined in -:zephyr_file:`include/zephyr/net/socket.h` to create a connection, send or receive data, -and close a connection. The same API can be used when working with UDP or -TCP data. See :ref:`BSD socket API ` for more details. - -See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client` -sample applications to learn how to create a simple server or client BSD socket based -application. - -The legacy connectivity API in :zephyr_file:`include/zephyr/net/net_context.h` should not be -used by applications.