diff --git a/boards/arm/atsamr21_xpro/doc/index.rst b/boards/arm/atsamr21_xpro/doc/index.rst index b362648d652..139b6ea6bcb 100644 --- a/boards/arm/atsamr21_xpro/doc/index.rst +++ b/boards/arm/atsamr21_xpro/doc/index.rst @@ -159,10 +159,10 @@ externally connected SPI devices. +-------------+------------------------------------------------------------------------------------------+ Zephyr provide several samples that can use this technology. You can check -:ref:`wpanusb-sample` and :ref:`wpan_serial-sample` examples as starting +:zephyr:code-sample:`wpanusb` and :zephyr:code-sample:`wpan-serial` examples as starting points. Another good test can be done with IPv6 by using the server/client -echo demo. More information at :ref:`sockets-echo-server-sample` and -:ref:`sockets-echo-client-sample`. +echo demo. More information at :zephyr:code-sample:`sockets-echo-server` and +:zephyr:code-sample:`sockets-echo-client`. Programming and Debugging ************************* diff --git a/boards/arm/cc3220sf_launchxl/doc/index.rst b/boards/arm/cc3220sf_launchxl/doc/index.rst index 00dad2e5a96..8b88133ccbd 100644 --- a/boards/arm/cc3220sf_launchxl/doc/index.rst +++ b/boards/arm/cc3220sf_launchxl/doc/index.rst @@ -261,7 +261,7 @@ re-specify the SSID and password. To connect to an AP, first run the Zephyr Wi-Fi shell sample application, and connect to a known AP with SSID and password. -See :ref:`wifi_sample` +See :zephyr:code-sample:`wifi-shell` Once the connection succeeds, the network co-processor keeps the AP identity in its persistent memory. Newly loaded Wi-Fi applications then need not explicitly @@ -284,7 +284,7 @@ and enabled by: keys to the secure flash filesystem, and enabling the TI Trusted Root-Certificate Catalog. -See :ref:`sockets-http-get` and +See :zephyr:code-sample:`sockets-http-get` and :zephyr_file:`samples/net/sockets/http_get/boards/cc3220sf_launchxl.conf` for an example. diff --git a/boards/arm/cc3235sf_launchxl/doc/index.rst b/boards/arm/cc3235sf_launchxl/doc/index.rst index cb0c5f7858f..71d8a44a8fb 100644 --- a/boards/arm/cc3235sf_launchxl/doc/index.rst +++ b/boards/arm/cc3235sf_launchxl/doc/index.rst @@ -261,7 +261,7 @@ re-specify the SSID and password. To connect to an AP, first run the Zephyr Wi-Fi shell sample application, and connect to a known AP with SSID and password. -See :ref:`wifi_sample` +See :zephyr:code-sample:`wifi-shell` Once the connection succeeds, the network co-processor keeps the AP identity in its persistent memory. Newly loaded Wi-Fi applications then need not explicitly @@ -284,7 +284,7 @@ and enabled by: keys to the secure flash filesystem, and enabling the TI Trusted Root-Certificate Catalog. -See :ref:`sockets-http-get` and +See :zephyr:code-sample:`sockets-http-get` and :zephyr_file:`samples/net/sockets/http_get/boards/cc3235sf_launchxl.conf` for an example. diff --git a/boards/posix/native_posix/doc/index.rst b/boards/posix/native_posix/doc/index.rst index 630da2c17dc..185c80c583b 100644 --- a/boards/posix/native_posix/doc/index.rst +++ b/boards/posix/native_posix/doc/index.rst @@ -329,7 +329,7 @@ The following peripherals are currently provided with this board: be created if needed. The IP address configuration can be specified for each network interface instance. See :kconfig:option:`CONFIG_ETH_NATIVE_POSIX_SETUP_SCRIPT` option for more details. - The :ref:`eth-native-posix-sample` sample app provides + The :zephyr:code-sample:`eth-native-posix` sample app provides some use examples and more information about this driver configuration. Note that this device can only be used with Linux hosts, and that the user diff --git a/boards/shields/atmel_rf2xx/doc/index.rst b/boards/shields/atmel_rf2xx/doc/index.rst index 31abe4c03f8..dbcdccbd3e8 100644 --- a/boards/shields/atmel_rf2xx/doc/index.rst +++ b/boards/shields/atmel_rf2xx/doc/index.rst @@ -283,8 +283,8 @@ and Echo client samples, which provide out-of-the-box configuration for both IEEE 802.15.4 and OpenThread. To enable IEEE 802.15.4 support in the samples, build them with ``overlay-802154.conf`` overlay config file. Same way, to enable OpenThread support, build them with ``overlay-ot.conf`` overlay -config file. See :ref:`sockets-echo-server-sample` and -:ref:`sockets-echo-client-sample` for details. +config file. See :zephyr:code-sample:`sockets-echo-server` and +:zephyr:code-sample:`sockets-echo-client` samples for details. Build and Programming ********************* diff --git a/boards/shields/inventek_eswifi/doc/index.rst b/boards/shields/inventek_eswifi/doc/index.rst index 699fd540190..e19713acd3f 100644 --- a/boards/shields/inventek_eswifi/doc/index.rst +++ b/boards/shields/inventek_eswifi/doc/index.rst @@ -140,7 +140,7 @@ Tested Boards Sample usage ************ -The reference sample for WIFI is :ref:`wifi_sample`. It allows you use WIFI +The reference sample for WIFI is :zephyr:code-sample:`wifi-shell`. It allows you to use WIFI shell to scan local Wireless networks. With the password you can pick, connect and send ping. diff --git a/doc/connectivity/networking/api/capture.rst b/doc/connectivity/networking/api/capture.rst index ba6e347170d..ee7605624c4 100644 --- a/doc/connectivity/networking/api/capture.rst +++ b/doc/connectivity/networking/api/capture.rst @@ -18,7 +18,7 @@ using ``net-shell`` or automatically by using the ``net_capture`` API. Sample usage ************ -See :ref:`Network capture sample application ` and +See :zephyr:code-sample:`net-capture` sample application and :ref:`network_monitoring` for details. diff --git a/doc/connectivity/networking/api/coap.rst b/doc/connectivity/networking/api/coap.rst index 8e5690b3387..a7d54f02235 100644 --- a/doc/connectivity/networking/api/coap.rst +++ b/doc/connectivity/networking/api/coap.rst @@ -142,7 +142,7 @@ in Zephyr. See the `net-tools `_ project for more details -The :ref:`coap-server-sample` sample can be built and executed on QEMU as described +The :zephyr:code-sample:`coap-server` sample can be built and executed on QEMU as described in :ref:`networking_with_qemu`. Use this command on the host to run the libcoap implementation of @@ -181,7 +181,7 @@ Follow the instruction to setup CoAP test suite from here: - https://github.com/eclipse/titan.misc - https://github.com/eclipse/titan.misc/tree/master/CoAP_Conf -After the build is complete, the :ref:`coap-server-sample` sample can be built +After the build is complete, the :zephyr:code-sample:`coap-server` sample can be built and executed on QEMU as described in :ref:`networking_with_qemu`. Change the client (test suite) and server (Zephyr coap-server sample) addresses diff --git a/doc/connectivity/networking/api/dhcpv4.rst b/doc/connectivity/networking/api/dhcpv4.rst index f9588e9dda4..e06bcd9182a 100644 --- a/doc/connectivity/networking/api/dhcpv4.rst +++ b/doc/connectivity/networking/api/dhcpv4.rst @@ -23,7 +23,7 @@ Note that Zephyr only supports DHCP client functionality. Sample usage ************ -See :ref:`dhcpv4-client-sample` for details. +See :zephyr:code-sample:`dhcpv4-client` sample application for details. API Reference ************* diff --git a/doc/connectivity/networking/api/dns_resolve.rst b/doc/connectivity/networking/api/dns_resolve.rst index fc4f0d8613c..d119fc74190 100644 --- a/doc/connectivity/networking/api/dns_resolve.rst +++ b/doc/connectivity/networking/api/dns_resolve.rst @@ -35,7 +35,7 @@ For more information about DNS configuration variables, see: Sample usage ************ -See :ref:`DNS resolve sample application ` for details. +See :zephyr:code-sample:`dns-resolve` sample application for details. API Reference ************* diff --git a/doc/connectivity/networking/api/gptp.rst b/doc/connectivity/networking/api/gptp.rst index e3bba55f50d..12dedeaab0b 100644 --- a/doc/connectivity/networking/api/gptp.rst +++ b/doc/connectivity/networking/api/gptp.rst @@ -66,7 +66,7 @@ Testing The stack has been informally tested using the `OpenAVnu gPTP `_ and `Linux ptp4l `_ daemons. -The :ref:`gPTP sample application ` from the Zephyr +The :zephyr:code-sample:`gPTP sample application ` from the Zephyr source distribution can be used for testing. .. _IEEE 802.1AS-2011 standard: diff --git a/doc/connectivity/networking/api/gsm_modem.rst b/doc/connectivity/networking/api/gsm_modem.rst index d44f68b38f1..cf15e429796 100644 --- a/doc/connectivity/networking/api/gsm_modem.rst +++ b/doc/connectivity/networking/api/gsm_modem.rst @@ -12,7 +12,7 @@ The Zephyr uses :ref:`PPP (Point-to-Point Protocol) ` to connect to the GSM modem using UART. Note that some cellular modems have proprietary offloading support using AT commands, but usually those modems also support 3GPP standards and provide PPP connection to them. -See :ref:`GSM modem sample application ` how to setup Zephyr +See :zephyr:code-sample:`GSM modem sample application ` how to setup Zephyr to use the GSM modem. The GSM muxing, that is defined in diff --git a/doc/connectivity/networking/api/http.rst b/doc/connectivity/networking/api/http.rst index a8b81b86357..060a41643d9 100644 --- a/doc/connectivity/networking/api/http.rst +++ b/doc/connectivity/networking/api/http.rst @@ -68,7 +68,7 @@ The following is an example of a very simple response handling function: LOG_INF("Response status %s", rsp->http_status); } -See :ref:`HTTP client sample application ` for +See :zephyr:code-sample:`HTTP client sample application ` for more information about the library usage. API Reference diff --git a/doc/connectivity/networking/api/lwm2m.rst b/doc/connectivity/networking/api/lwm2m.rst index 6d26205511e..6ddc66a1836 100644 --- a/doc/connectivity/networking/api/lwm2m.rst +++ b/doc/connectivity/networking/api/lwm2m.rst @@ -227,7 +227,7 @@ The full list of registered objects and resource IDs can be found in the Zephyr's LwM2M library lives in the :zephyr_file:`subsys/net/lib/lwm2m`, with a client sample in :zephyr_file:`samples/net/lwm2m_client`. For more information -about the provided sample see: :ref:`lwm2m-client-sample` The sample can be +about the provided sample see: :zephyr:code-sample:`lwm2m-client`. The sample can be configured to use normal unsecure network sockets or sockets secured via DTLS. The Zephyr LwM2M library implements the following items: @@ -444,7 +444,7 @@ value of 1 is ok here). client.tls_tag = 1; /* <---- */ lwm2m_rd_client_start(&client, "endpoint-name", 0, rd_client_event); -For a more detailed LwM2M client sample see: :ref:`lwm2m-client-sample`. +For a more detailed LwM2M client sample see: :zephyr:code-sample:`lwm2m-client`. Multi-thread usage ****************** diff --git a/doc/connectivity/networking/api/mqtt.rst b/doc/connectivity/networking/api/mqtt.rst index b1090c8d394..973b61860e3 100644 --- a/doc/connectivity/networking/api/mqtt.rst +++ b/doc/connectivity/networking/api/mqtt.rst @@ -129,7 +129,7 @@ be called and an appropriate event notified. The connection can be closed by calling the ``mqtt_disconnect`` function. Zephyr provides sample code utilizing the MQTT client API. See -:ref:`mqtt-publisher-sample` for more information. +:zephyr:code-sample:`mqtt-publisher` for more information. Using MQTT with TLS ******************* @@ -162,7 +162,7 @@ registered in the system first. For more information on how to do that, refer to :ref:`secure sockets documentation `. An example of how to use TLS with MQTT is also present in -:ref:`mqtt-publisher-sample`. +:zephyr:code-sample:`mqtt-publisher` sample application. .. _mqtt_api_reference: diff --git a/doc/connectivity/networking/api/mqtt_sn.rst b/doc/connectivity/networking/api/mqtt_sn.rst index 40a1b9d8df8..13860346946 100644 --- a/doc/connectivity/networking/api/mqtt_sn.rst +++ b/doc/connectivity/networking/api/mqtt_sn.rst @@ -124,7 +124,7 @@ has no effect on the transport, however. If you want to close the transport (e.g the socket), call ``mqtt_sn_client_deinit``, which will deinit the transport as well. Zephyr provides sample code utilizing the MQTT-SN client API. See -:ref:`mqtt-sn-publisher-sample` for more information. +:zephyr:code-sample:`mqtt-sn-publisher-sample` for more information. Deviations from the standard **************************** diff --git a/doc/connectivity/networking/api/promiscuous.rst b/doc/connectivity/networking/api/promiscuous.rst index c5e18f58fb0..9b60770c00e 100644 --- a/doc/connectivity/networking/api/promiscuous.rst +++ b/doc/connectivity/networking/api/promiscuous.rst @@ -70,7 +70,7 @@ Finally the promiscuous mode can be turned OFF by the application like this: } -See :ref:`net-promiscuous-mode-sample` for a more comprehensive example. +See :zephyr:code-sample:`net-promiscuous-mode` for a more comprehensive example. API Reference diff --git a/doc/connectivity/networking/api/sockets.rst b/doc/connectivity/networking/api/sockets.rst index f7a77f68f67..3f632e3bea9 100644 --- a/doc/connectivity/networking/api/sockets.rst +++ b/doc/connectivity/networking/api/sockets.rst @@ -133,8 +133,8 @@ CA certificate and hostname can be set: Once configured, socket can be used just like a regular TCP socket. Several samples in Zephyr use secure sockets for communication. For a sample use -see e.g. :ref:`echo-server sample application ` or -:ref:`HTTP GET sample application `. +see e.g. :zephyr:code-sample:`echo-server sample application ` or +:zephyr:code-sample:`HTTP GET sample application `. Secure Sockets options ====================== diff --git a/doc/connectivity/networking/api/socks5.rst b/doc/connectivity/networking/api/socks5.rst index a935fd9e439..ab72270394a 100644 --- a/doc/connectivity/networking/api/socks5.rst +++ b/doc/connectivity/networking/api/socks5.rst @@ -47,5 +47,5 @@ SOCKS5 Proxy Usage in MQTT ************************** For MQTT client, there is :c:func:`mqtt_client_set_proxy()` API that the -application can call to setup SOCKS5 proxy. See :ref:`mqtt-publisher-sample` -for usage example. +application can call to setup SOCKS5 proxy. See :zephyr:code-sample:`mqtt-publisher` +sample application for usage example. diff --git a/doc/connectivity/networking/api/thread.rst b/doc/connectivity/networking/api/thread.rst index 6dae56d5c12..280758078fa 100644 --- a/doc/connectivity/networking/api/thread.rst +++ b/doc/connectivity/networking/api/thread.rst @@ -38,5 +38,5 @@ Sample usage You can try using OpenThread with the Zephyr Echo server and Echo client samples, which provide out-of-the-box configuration for OpenThread. To enable OpenThread support in these samples, build them with ``overlay-ot.conf`` overlay config file. -See :ref:`sockets-echo-server-sample` and :ref:`sockets-echo-client-sample` for -details. +See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client` +samples for details. diff --git a/doc/connectivity/networking/api/vlan.rst b/doc/connectivity/networking/api/vlan.rst index b0fe35b79a4..efa6d60b8b0 100644 --- a/doc/connectivity/networking/api/vlan.rst +++ b/doc/connectivity/networking/api/vlan.rst @@ -37,7 +37,7 @@ function. The VLAN tagging for a given network interface can be disabled by a :c:func:`net_eth_vlan_disable` function. The application needs to configure the VLAN network interface itself, such as setting the IP address, etc. -See also the :ref:`VLAN sample application ` for API usage +See also the :zephyr:code-sample:`VLAN sample application ` for API usage example. The source code for that sample application can be found at :zephyr_file:`samples/net/vlan`. diff --git a/doc/connectivity/networking/api/zperf.rst b/doc/connectivity/networking/api/zperf.rst index 4f6674679d2..fe09823c057 100644 --- a/doc/connectivity/networking/api/zperf.rst +++ b/doc/connectivity/networking/api/zperf.rst @@ -22,7 +22,7 @@ are missing. LAST PACKET NOT RECEIVED!!! zperf can be enabled in any application, a dedicated sample is also present -in Zephyr. See :ref:`zperf sample application ` for details. +in Zephyr. See :zephyr:code-sample:`zperf sample application ` for details. Sample Usage ************ diff --git a/doc/connectivity/networking/armfvp_user_networking_setup.rst b/doc/connectivity/networking/armfvp_user_networking_setup.rst index c0aeb3a0693..618a33a8242 100644 --- a/doc/connectivity/networking/armfvp_user_networking_setup.rst +++ b/doc/connectivity/networking/armfvp_user_networking_setup.rst @@ -33,7 +33,7 @@ Using Arm FVP User Mode Networking with Zephyr Arm FVP user mode networking can be enabled in any applications and it doesn't need any configurations on the host system. This feature has been enabled in DHCPv4 client sample. -See :ref:`Sample DHCPv4 client application ` +See :zephyr:code-sample:`dhcpv4-client` sample application. Limitations ************* diff --git a/doc/connectivity/networking/native_posix_setup.rst b/doc/connectivity/networking/native_posix_setup.rst index 249cef7f07a..cc94c9f790b 100644 --- a/doc/connectivity/networking/native_posix_setup.rst +++ b/doc/connectivity/networking/native_posix_setup.rst @@ -10,7 +10,7 @@ Networking with native_posix board This page describes how to set up a virtual network between a (Linux) host and a Zephyr application running in a native_posix board. -In this example, the :ref:`sockets-echo-server-sample` sample application from +In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from the Zephyr source distribution is run in native_posix board. The Zephyr native_posix board instance is connected to a Linux host using a tuntap device which is modeled in Linux as an Ethernet network interface. diff --git a/doc/connectivity/networking/network_monitoring.rst b/doc/connectivity/networking/network_monitoring.rst index 0dbe00fa4fa..b0a20b287d0 100644 --- a/doc/connectivity/networking/network_monitoring.rst +++ b/doc/connectivity/networking/network_monitoring.rst @@ -13,7 +13,7 @@ Zephyr. This page describes how to set up a way to capture network traffic so that user is able to use Wireshark or similar tool in remote host to see the network packets sent or received by a Zephyr device. -See also the :ref:`net-capture-sample` sample application from the Zephyr +See also the :zephyr:code-sample:`net-capture` sample application from the Zephyr source distribution for configuration options that need to be enabled. Host Configuration diff --git a/doc/connectivity/networking/networking-api-usage.rst b/doc/connectivity/networking/networking-api-usage.rst index d1249d01e6d..0145482fec9 100644 --- a/doc/connectivity/networking/networking-api-usage.rst +++ b/doc/connectivity/networking/networking-api-usage.rst @@ -8,8 +8,8 @@ Applications should use the BSD socket API defined in 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 :ref:`sockets-echo-server-sample` and :ref:`sockets-echo-client-sample` -applications how to create a simple server or client BSD socket based +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 diff --git a/doc/connectivity/networking/networking_with_multiple_instances.rst b/doc/connectivity/networking/networking_with_multiple_instances.rst index 6bd4531c829..c83f7e04ed6 100644 --- a/doc/connectivity/networking/networking_with_multiple_instances.rst +++ b/doc/connectivity/networking/networking_with_multiple_instances.rst @@ -122,8 +122,8 @@ In terminal #3, type: Step 4 - Start Zephyr instances =============================== -In this example we start :ref:`sockets-echo-server-sample` and -:ref:`sockets-echo-client-sample` applications. You can use other applications +In this example we start :zephyr:code-sample:`sockets-echo-server` and +:zephyr:code-sample:`sockets-echo-client` sample applications. You can use other applications too as needed. In terminal #4, if you are using QEMU, type this: diff --git a/doc/connectivity/networking/overview.rst b/doc/connectivity/networking/overview.rst index c339632fdf1..f271bcd8a8c 100644 --- a/doc/connectivity/networking/overview.rst +++ b/doc/connectivity/networking/overview.rst @@ -69,12 +69,12 @@ can be disabled if not needed. are provided by mbedTLS library. * **MQTT** Message Queue Telemetry Transport (ISO/IEC PRF 20922) is supported. - A sample :ref:`mqtt-publisher-sample` client application for MQTT v3.1.1 is + A sample :zephyr:code-sample:`mqtt-publisher` client application for MQTT v3.1.1 is implemented. * **CoAP** Constrained Application Protocol (`RFC 7252 `_) is supported. - Both :ref:`coap-client-sample` and :ref:`coap-server-sample` sample + Both :zephyr:code-sample:`coap-client` and :zephyr:code-sample:`coap-server` sample applications are implemented. * **LWM2M** OMA Lightweight Machine-to-Machine Protocol @@ -83,7 +83,7 @@ can be disabled if not needed. Reporting" interfaces. The required core LwM2M objects are implemented as well as several IPSO Smart Objects. (`LwM2M specification 1.1.1`_) is supported in similar manner when enabled with a Kconfig option. - :ref:`lwm2m-client-sample` implements the library as an example. + :zephyr:code-sample:`lwm2m-client` sample implements the library as an example. * **DNS** Domain Name Service (`RFC 1035 `_) client functionality diff --git a/doc/connectivity/networking/qemu_eth_setup.rst b/doc/connectivity/networking/qemu_eth_setup.rst index 5d6aab68962..a0219e6126c 100644 --- a/doc/connectivity/networking/qemu_eth_setup.rst +++ b/doc/connectivity/networking/qemu_eth_setup.rst @@ -10,7 +10,7 @@ Networking with QEMU Ethernet This page describes how to set up a virtual network between a (Linux) host and a Zephyr application running in QEMU. -In this example, the :ref:`sockets-echo-server-sample` sample application from +In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from the Zephyr source distribution is run in QEMU. The Zephyr instance is connected to a Linux host using a tuntap device which is modeled in Linux as an Ethernet network interface. @@ -71,7 +71,7 @@ by running ``net-setup.sh`` like this: Step 2 - Start app in QEMU board ================================ -Build and start the :ref:`sockets-echo-server-sample` sample application. +Build and start the :zephyr:code-sample:`sockets-echo-server` sample application. In this example, the qemu_x86 board is used. In terminal #2, type: diff --git a/doc/connectivity/networking/qemu_setup.rst b/doc/connectivity/networking/qemu_setup.rst index 5740145cd74..f2b979867a8 100644 --- a/doc/connectivity/networking/qemu_setup.rst +++ b/doc/connectivity/networking/qemu_setup.rst @@ -13,7 +13,7 @@ targets such as qemu_x86 and qemu_cortex_m3). Some virtual ARM boards (such as qemu_cortex_a53) only support a single UART, in this case QEMU Ethernet is preferred, see :ref:`networking_with_eth_qemu` for details. -In this example, the :ref:`sockets-echo-server-sample` sample application from +In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from the Zephyr source distribution is run in QEMU. The QEMU instance is connected to a Linux host using a serial port, and SLIP is used to transfer data between the Zephyr application and Linux (over a chain of diff --git a/doc/connectivity/networking/usbnet_setup.rst b/doc/connectivity/networking/usbnet_setup.rst index 5f193770504..a71a48c6771 100644 --- a/doc/connectivity/networking/usbnet_setup.rst +++ b/doc/connectivity/networking/usbnet_setup.rst @@ -12,7 +12,7 @@ and a Zephyr application running on USB supported devices. The board is connected to Linux host using USB cable and provides an Ethernet interface to the host. -The :ref:`sockets-echo-server-sample` application from the Zephyr source +The :zephyr:code-sample:`sockets-echo-server` application from the Zephyr source distribution is run on supported board. The board is connected to a Linux host using a USB cable providing an Ethernet interface to the host. diff --git a/doc/connectivity/usb/device/usb_device.rst b/doc/connectivity/usb/device/usb_device.rst index 752d6392077..19fd5e61577 100644 --- a/doc/connectivity/usb/device/usb_device.rst +++ b/doc/connectivity/usb/device/usb_device.rst @@ -166,7 +166,7 @@ CDC ACM UART as backend for a subsystem or application: * ``zephyr,bt-c2h-uart`` used in Bluetooth, for example see :ref:`bluetooth-hci-uart-sample` * ``zephyr,ot-uart`` used in OpenThread, - for example see :ref:`coprocessor-sample` + for example see :zephyr:code-sample:`coprocessor` * ``zephyr,shell-uart`` used by shell for serial backend, for example see :zephyr_file:`samples/subsys/shell/shell_module` * ``zephyr,uart-mcumgr`` used by :ref:`smp_svr_sample` @@ -339,7 +339,7 @@ Ethernet connection between the remote (USB host) and Zephyr network support. * CDC EEM class, enabled with :kconfig:option:`CONFIG_USB_DEVICE_NETWORK_EEM` * RNDIS support, enabled with :kconfig:option:`CONFIG_USB_DEVICE_NETWORK_RNDIS` -See :ref:`zperf-sample` or :ref:`sockets-dumb-http-server-sample` for reference. +See :zephyr:code-sample:`zperf` or :zephyr:code-sample:`socket-dumb-http-server` for reference. Typically, users will need to add a configuration file overlay to the build, such as :zephyr_file:`samples/net/zperf/overlay-netusb.conf`. @@ -500,7 +500,7 @@ The following Product IDs are currently used: +-------------------------------------+--------+ | :ref:`bluetooth-hci-usb-h4-sample` | 0x000C | +-------------------------------------+--------+ -| :ref:`wpanusb-sample` | 0x000D | +| :zephyr:code-sample:`wpan-usb` | 0x000D | +-------------------------------------+--------+ The USB device descriptor field ``bcdDevice`` (Device Release Number) represents diff --git a/doc/connectivity/usb/device_next/usb_device.rst b/doc/connectivity/usb/device_next/usb_device.rst index c7755329538..1ef6f7ef933 100644 --- a/doc/connectivity/usb/device_next/usb_device.rst +++ b/doc/connectivity/usb/device_next/usb_device.rst @@ -51,7 +51,7 @@ At the moment only CDC ECM class is implemented and has support for multiple ins It provides a virtual Ethernet connection between the remote (USB host) and Zephyr network support. -See :ref:`zperf-sample` for reference. +See :zephyr:code-sample:`zperf` for reference. To build the sample for the new device support, set the configuration overlay file ``-DDEXTRA_CONF_FILE=overlay-usbd_next_ecm.conf`` and devicetree overlay file ``-DDTC_OVERLAY_FILE="usbd_next_ecm.overlay`` either directly or via ``west``. diff --git a/doc/hardware/peripherals/canbus/controller.rst b/doc/hardware/peripherals/canbus/controller.rst index 85dee4b0f67..82e004a6df1 100644 --- a/doc/hardware/peripherals/canbus/controller.rst +++ b/doc/hardware/peripherals/canbus/controller.rst @@ -331,9 +331,9 @@ which adds some computation and memory overhead. Samples ******* -We have two ready-to-build samples demonstrating use of the Zephyr CAN API +We have two ready-to-build samples demonstrating use of the Zephyr CAN API: :ref:`Zephyr CAN counter sample ` and -:ref:`SocketCAN sample `. +:zephyr:code-sample:`SocketCAN sample `. CAN Controller API Reference diff --git a/doc/releases/release-notes-1.14.rst b/doc/releases/release-notes-1.14.rst index 32393436194..45ed7625890 100644 --- a/doc/releases/release-notes-1.14.rst +++ b/doc/releases/release-notes-1.14.rst @@ -862,7 +862,7 @@ Networking * :ref:`Network interface ` numbering starts now from 1 for POSIX compatibility. * :ref:`OpenThread ` enhancements. -* :ref:`zperf ` sample application fixes. +* :zephyr:code-sample:`zperf ` sample application fixes. * :ref:`LLDP ` (Link Layer Discovery Protocol) enhancements. * ARP cache update fix. * gPTP link delay calculation fixes. diff --git a/doc/releases/release-notes-3.4.rst b/doc/releases/release-notes-3.4.rst index 0fb4efbe40f..092fa251c6f 100644 --- a/doc/releases/release-notes-3.4.rst +++ b/doc/releases/release-notes-3.4.rst @@ -1143,7 +1143,7 @@ Networking which allow to disable ND/MLD respectively on an interface. * Reworked network interface mutex protection, to use individual mutex for each interface, instead of a global one. - * Added new :ref:`aws-iot-mqtt-sample`. + * Added new :zephyr:code-sample:`aws-iot-mqtt`. * Added a few missing NULL pointer checks in network interface functions. * OpenThread: diff --git a/doc/services/device_mgmt/ota.rst b/doc/services/device_mgmt/ota.rst index 737b957c082..8f400582740 100644 --- a/doc/services/device_mgmt/ota.rst +++ b/doc/services/device_mgmt/ota.rst @@ -74,7 +74,7 @@ Lightweight M2M (LWM2M) The :ref:`lwm2m_interface` protocol includes support for firmware update via :kconfig:option:`CONFIG_LWM2M_FIRMWARE_UPDATE_OBJ_SUPPORT`. Devices securely -connect to an LwM2M server using DTLS. An :ref:`lwm2m-client-sample` sample is +connect to an LwM2M server using DTLS. A :zephyr:code-sample:`lwm2m-client` sample is available but it does not demonstrate the firmware update feature. .. _MCUboot bootloader: https://mcuboot.com/ diff --git a/samples/net/capture/README.rst b/samples/net/capture/README.rst index 87259408582..c6846e5d552 100644 --- a/samples/net/capture/README.rst +++ b/samples/net/capture/README.rst @@ -1,13 +1,16 @@ -.. _net-capture-sample: +.. zephyr:code-sample:: net-capture + :name: Network packet capture + :relevant-api: net_capture -Network Packet Capture -###################### + Capture network packets and send them to a remote host via IPIP tunnel. Overview ******** This application will setup the device so that net-shell can be used -to enable network packet capture. The captured packets are sent to +to enable network packet capture. + +The captured packets are sent to remote host via IPIP tunnel. The tunnel can be configured to be in the same connection as what we are capturing packets or it can be a separate bearer. For example if you are capturing network traffic for interface 1, diff --git a/samples/net/cellular_modem/README.rst b/samples/net/cellular_modem/README.rst index 7c30a850705..384d8b3bef5 100644 --- a/samples/net/cellular_modem/README.rst +++ b/samples/net/cellular_modem/README.rst @@ -1,7 +1,7 @@ -.. _cellular_modem_sample: +.. zephyr:code-sample:: cellular-modem + :name: Cellular modem -Cellular Modem Sample -######################## + Use a cellular modem to communicate with a UDP server. Overview ******** diff --git a/samples/net/cloud/aws_iot_mqtt/README.rst b/samples/net/cloud/aws_iot_mqtt/README.rst index 0f0d08234d2..8ad0d1f9738 100644 --- a/samples/net/cloud/aws_iot_mqtt/README.rst +++ b/samples/net/cloud/aws_iot_mqtt/README.rst @@ -1,7 +1,8 @@ -.. _aws-iot-mqtt-sample: +.. zephyr:code-sample:: aws-iot-mqtt + :name: AWS IoT Core MQTT + :relevant-api: bsd_sockets mqtt_socket dns_resolve tls_credentials json sntp random_api -AWS IoT Core MQTT Sample -######################## + Connect to AWS IoT Core and publish messages using MQTT. Overview ******** diff --git a/samples/net/cloud/mqtt_azure/README.rst b/samples/net/cloud/mqtt_azure/README.rst index a1414b8df43..1369b83d0e5 100644 --- a/samples/net/cloud/mqtt_azure/README.rst +++ b/samples/net/cloud/mqtt_azure/README.rst @@ -1,7 +1,8 @@ -.. _mqtt-azure-sample: +.. zephyr:code-sample:: mqtt-azure + :name: Microsoft Azure IoT Hub MQTT + :relevant-api: bsd_sockets mqtt_socket tls_credentials random_api -MQTT Azure Sample -################# + Connect to Azure IoT Hub and publish messages using MQTT. Overview ******** diff --git a/samples/net/cloud/tagoio_http_post/README.rst b/samples/net/cloud/tagoio_http_post/README.rst index 235a35265e4..dc0f2b9da6c 100644 --- a/samples/net/cloud/tagoio_http_post/README.rst +++ b/samples/net/cloud/tagoio_http_post/README.rst @@ -1,7 +1,8 @@ -.. _cloud-tagoio-http-post-sample: +.. zephyr:code-sample:: tagoio-http-post + :name: TagoIO HTTP Post + :relevant-api: bsd_sockets http_client dns_resolve tls_credentials -TagoIO IoT Cloud HTTP Sample -############################ + Send random temperature values to TagoIO IoT Cloud Platform using HTTP. Overview ******** diff --git a/samples/net/dhcpv4_client/README.rst b/samples/net/dhcpv4_client/README.rst index 60e985eb0a9..e8c232a7e94 100644 --- a/samples/net/dhcpv4_client/README.rst +++ b/samples/net/dhcpv4_client/README.rst @@ -1,7 +1,8 @@ -.. _dhcpv4-client-sample: +.. zephyr:code-sample:: dhcpv4-client + :name: DHCPv4 client + :relevant-api: dhcpv4 net_mgmt -Sample DHCPv4 client application -################################ + Start a DHCPv4 client to obtain an IPv4 address from a DHCPv4 server. Overview ******** diff --git a/samples/net/dns_resolve/README.rst b/samples/net/dns_resolve/README.rst index 28cfabdf013..ac2ea0f391b 100644 --- a/samples/net/dns_resolve/README.rst +++ b/samples/net/dns_resolve/README.rst @@ -1,7 +1,8 @@ -.. _dns-resolve-sample: +.. zephyr:code-sample:: dns-resolve + :name: DNS resolve + :relevant-api: dns_resolve net_mgmt -DNS Resolve Application -####################### + Resolve an IP address for a given hostname. Overview ******** diff --git a/samples/net/dsa/README.rst b/samples/net/dsa/README.rst index 588adf28db1..729aac7785e 100644 --- a/samples/net/dsa/README.rst +++ b/samples/net/dsa/README.rst @@ -1,7 +1,8 @@ -.. _dsa-sample: +.. zephyr:code-sample:: dsa + :name: DSA (Distributed Switch Architecture) + :relevant-api: DSA -DSA Sample Application -###################### + Test and debug Distributed Switch Architecture Overview ******** diff --git a/samples/net/eth_native_posix/README.rst b/samples/net/eth_native_posix/README.rst index 2ec9c55c52d..7d7232acd5c 100644 --- a/samples/net/eth_native_posix/README.rst +++ b/samples/net/eth_native_posix/README.rst @@ -1,7 +1,8 @@ -.. _eth-native-posix-sample: +.. zephyr:code-sample:: eth-native-posix + :name: Native POSIX Ethernet + :relevant-api: net_core ethernet -Native Posix Ethernet -##################### + Create a network interface to the host system. Overview ******** diff --git a/samples/net/gptp/README.rst b/samples/net/gptp/README.rst index 4b7f6a100fc..a2c8696d95a 100644 --- a/samples/net/gptp/README.rst +++ b/samples/net/gptp/README.rst @@ -1,7 +1,8 @@ -.. _gptp-sample: +.. zephyr:code-sample:: gptp + :name: gPTP + :relevant-api: gptp ptp_time -gPTP Sample Application -####################### + Enable gPTP support and monitor functionality using net-shell. Overview ******** diff --git a/samples/net/gsm_modem/README.rst b/samples/net/gsm_modem/README.rst index aebfc2ab3a5..2021b0e0554 100644 --- a/samples/net/gsm_modem/README.rst +++ b/samples/net/gsm_modem/README.rst @@ -1,7 +1,7 @@ -.. _gsm-modem-sample: +.. zephyr:code-sample:: gsm-modem + :name: Generic GSM modem -Generic GSM Modem Sample -######################## + Use a GSM modem to connect to a GPRS network. Overview ******** diff --git a/samples/net/ipv4_autoconf/README.rst b/samples/net/ipv4_autoconf/README.rst index 1ee783cbe41..614f2c64047 100644 --- a/samples/net/ipv4_autoconf/README.rst +++ b/samples/net/ipv4_autoconf/README.rst @@ -1,7 +1,8 @@ -.. _ipv4-autoconf-sample: +.. zephyr:code-sample:: ipv4-autoconf + :name: IPv4 autoconf client + :relevant-api: networking net_if net_context net_mgmt -IPv4 autoconf client application -################################ + Perform IPv4 autoconfiguration and self-assign a random IPv4 address Overview ******** diff --git a/samples/net/lldp/README.rst b/samples/net/lldp/README.rst index 856c4342910..ba392d8be94 100644 --- a/samples/net/lldp/README.rst +++ b/samples/net/lldp/README.rst @@ -1,7 +1,8 @@ -.. _lldp-sample: +.. zephyr:code-sample:: lldp + :name: Link Layer Discovery Protocol (LLDP) + :relevant-api: lldp net_l2 -LLDP Sample Application -####################### + Enable LLDP support and setup VLANs. Overview ******** diff --git a/samples/net/lwm2m_client/README.rst b/samples/net/lwm2m_client/README.rst index c05a1149d31..4e231ba0051 100644 --- a/samples/net/lwm2m_client/README.rst +++ b/samples/net/lwm2m_client/README.rst @@ -1,7 +1,8 @@ -.. _lwm2m-client-sample: +.. zephyr:code-sample:: lwm2m-client + :name: LwM2M client + :relevant-api: lwm2m_api -LwM2M client -############ + Implement a LwM2M client that connects to a LwM2M server. Overview ******** diff --git a/samples/net/mdns_responder/README.rst b/samples/net/mdns_responder/README.rst index 8b9d93299a4..015f6c8b444 100644 --- a/samples/net/mdns_responder/README.rst +++ b/samples/net/mdns_responder/README.rst @@ -1,7 +1,8 @@ -.. _mdns-responder-sample: +.. zephyr:code-sample:: mdns-responder + :name: mDNS responder + :relevant-api: net_core dns_sd bsd_sockets -mDNS Responder Application -########################## + Listen and respond to mDNS queries. Overview ******** diff --git a/samples/net/mqtt_publisher/README.rst b/samples/net/mqtt_publisher/README.rst index 04ff4c47bfd..2c22394036b 100644 --- a/samples/net/mqtt_publisher/README.rst +++ b/samples/net/mqtt_publisher/README.rst @@ -1,7 +1,8 @@ -.. _mqtt-publisher-sample: +.. zephyr:code-sample:: mqtt-publisher + :name: MQTT publisher + :relevant-api: mqtt_socket -MQTT Publisher -############## + Send MQTT PUBLISH messages to an MQTT server. Overview ******** diff --git a/samples/net/mqtt_sn_publisher/README.rst b/samples/net/mqtt_sn_publisher/README.rst index 57e82f30594..e7831487650 100644 --- a/samples/net/mqtt_sn_publisher/README.rst +++ b/samples/net/mqtt_sn_publisher/README.rst @@ -1,7 +1,8 @@ -.. _mqtt-sn-publisher-sample: +.. zephyr:code-sample:: mqtt-sn-publisher + :name: MQTT-SN publisher + :relevant-api: mqtt_sn_socket -MQTT-SN Publisher -################# + Send MQTT-SN PUBLISH messages to an MQTT-SN gateway. Overview ******** @@ -16,8 +17,8 @@ requires a reliable TCP/IP transport, MQTT-SN is designed to be usable on any datagram-based transport like UDP, ZigBee or even a plain UART (with an additional framing protocol). -The Zephyr MQTT-SN Publisher sample application is a MQTT-SN v1.2 -client that sends MQTT-SN PUBLISH messages to a MQTT-SN gateway. +The Zephyr MQTT-SN Publisher sample application is an MQTT-SN v1.2 +client that sends MQTT-SN PUBLISH messages to an MQTT-SN gateway. It also SUBSCRIBEs to a topic. See the `MQTT-SN v1.2 spec`_ for more information. @@ -43,7 +44,7 @@ Currently, this sample application only supports static IP addresses. Open the :file:`prj.conf` file and set the IP addresses according to the LAN environment. -You will also need to start a MQTT-SN gateway. With paho, you can either +You will also need to start an MQTT-SN gateway. With Paho, you can either build it from source - see `PAHO MQTT-SN Gateway`_ - or run an unofficial docker image, like `kyberpunk/paho`_. diff --git a/samples/net/openthread/coprocessor/README.rst b/samples/net/openthread/coprocessor/README.rst index ee76942c3fc..9ba9fc62f0d 100644 --- a/samples/net/openthread/coprocessor/README.rst +++ b/samples/net/openthread/coprocessor/README.rst @@ -1,7 +1,8 @@ -.. _coprocessor-sample: +.. zephyr:code-sample:: coprocessor + :name: OpenThread co-processor + :relevant-api: openthread -OpenThread Co-Processor -####################### + Build a Thread border-router using OpenThread's co-processor designs. Overview ******** diff --git a/samples/net/promiscuous_mode/README.rst b/samples/net/promiscuous_mode/README.rst index 44e5bdd27c0..3587deb8d9c 100644 --- a/samples/net/promiscuous_mode/README.rst +++ b/samples/net/promiscuous_mode/README.rst @@ -1,7 +1,8 @@ -.. _net-promiscuous-mode-sample: +.. zephyr:code-sample:: net-promiscuous-mode + :name: Promiscuous mode + :relevant-api: promiscuous -Promiscuous Mode Sample Application -################################### + Enable promiscuous mode on all interfaces and print information about incoming packets. Overview ******** diff --git a/samples/net/sockets/big_http_download/README.rst b/samples/net/sockets/big_http_download/README.rst index 0cefa732063..222af88d573 100644 --- a/samples/net/sockets/big_http_download/README.rst +++ b/samples/net/sockets/big_http_download/README.rst @@ -1,14 +1,15 @@ -.. _sockets-big-http-download: +.. zephyr:code-sample:: sockets-big-http-download + :name: Large HTTP download + :relevant-api: bsd_sockets tls_credentials -Socket Big HTTP Download Example -################################ + Download a large file from a web server using BSD sockets. Overview ******** The sockets/big_http_download sample application for Zephyr implements a simple HTTP GET client using a BSD Sockets compatible API. Unlike -the :ref:`sockets-http-get` sample application, it downloads a file of +the :zephyr:code-sample:`sockets-http-get` sample application, it downloads a file of several megabytes in size, and verifies its integrity using hashing. It also performs download repeatedly, tracking the total number of bytes transferred. Thus, it can serve as a "load testing" application for diff --git a/samples/net/sockets/can/README.rst b/samples/net/sockets/can/README.rst index 5239985c260..800665a8523 100644 --- a/samples/net/sockets/can/README.rst +++ b/samples/net/sockets/can/README.rst @@ -1,7 +1,8 @@ -.. _socket-can-sample: +.. zephyr:code-sample:: socket-can + :name: SocketCAN + :relevant-api: bsd_sockets socket_can -Socket CAN -########## + Send and receive raw CAN frames using BSD sockets API. Overview ******** diff --git a/samples/net/sockets/coap_client/README.rst b/samples/net/sockets/coap_client/README.rst index fedea647b3c..a26d632772b 100644 --- a/samples/net/sockets/coap_client/README.rst +++ b/samples/net/sockets/coap_client/README.rst @@ -1,7 +1,8 @@ -.. _coap-client-sample: +.. zephyr:code-sample:: coap-client + :name: CoAP client + :relevant-api: coap udp -CoAP client -########### + Use the CoAP library to implement a client that fetches a resource. Overview ******** diff --git a/samples/net/sockets/coap_server/README.rst b/samples/net/sockets/coap_server/README.rst index 5159c66b989..57e4a818809 100644 --- a/samples/net/sockets/coap_server/README.rst +++ b/samples/net/sockets/coap_server/README.rst @@ -1,7 +1,8 @@ -.. _coap-server-sample: +.. zephyr:code-sample:: coap-server + :name: CoAP server + :relevant-api: coap udp -CoAP Server -########### + Use the CoAP library to implement a server that exposes CoAP resources. Overview ******** diff --git a/samples/net/sockets/dumb_http_server/README.rst b/samples/net/sockets/dumb_http_server/README.rst index f578d877bd1..56e6ac281e4 100644 --- a/samples/net/sockets/dumb_http_server/README.rst +++ b/samples/net/sockets/dumb_http_server/README.rst @@ -1,7 +1,8 @@ -.. _sockets-dumb-http-server-sample: +.. zephyr:code-sample:: socket-dumb-http-server + :name: Dumb HTTP server + :relevant-api: bsd_sockets net_pkt -Socket Dumb HTTP Server -####################### + Implement a simple, portable, HTTP server using BSD sockets. Overview ******** diff --git a/samples/net/sockets/dumb_http_server_mt/README.rst b/samples/net/sockets/dumb_http_server_mt/README.rst index e999f8229cf..76e55cbbc0f 100644 --- a/samples/net/sockets/dumb_http_server_mt/README.rst +++ b/samples/net/sockets/dumb_http_server_mt/README.rst @@ -1,14 +1,15 @@ -.. _sockets-dumb-http-server-mt-sample: +.. zephyr:code-sample:: socket-dumb-http-server-mt + :name: Dumb HTTP server (multi-threaded) + :relevant-api: bsd_sockets net_pkt thread_apis tls_credentials -Socket Multithreaded Dumb HTTP Server -##################################### + Implement a simple HTTP server supporting simultaneous connections using BSD sockets. Overview ******** The ``sockets/dumb_http_server_mt`` sample application for Zephyr implements a skeleton HTTP server using a BSD Sockets compatible API. -This sample has similar functionality as :ref:`sockets-dumb-http-server-sample` +This sample has similar functionality as :zephyr:code-sample:`socket-dumb-http-server` except it has support for multiple simultaneous connections, TLS and IPv6. Also this sample application has no compatibility with POSIX. This HTTP server example is very minimal and does not really parse an incoming diff --git a/samples/net/sockets/echo/README.rst b/samples/net/sockets/echo/README.rst index 0d91e0ac3e7..68edc84c46f 100644 --- a/samples/net/sockets/echo/README.rst +++ b/samples/net/sockets/echo/README.rst @@ -1,7 +1,8 @@ -.. _sockets-echo-sample: +.. zephyr:code-sample:: socket-echo + :name: Echo server (simple) + :relevant-api: bsd_sockets -Socket Echo Server -################## + Implements a simple IPv4 TCP echo server using BSD sockets. Overview ******** diff --git a/samples/net/sockets/echo_async/README.rst b/samples/net/sockets/echo_async/README.rst index e17953b506c..0499973fc2e 100644 --- a/samples/net/sockets/echo_async/README.rst +++ b/samples/net/sockets/echo_async/README.rst @@ -1,7 +1,8 @@ -.. _async-sockets-echo-sample: +.. zephyr:code-sample:: async-sockets-echo + :name: Asynchronous echo server using poll() + :relevant-api: bsd_sockets -Asynchronous Socket Echo Server -############################### + Implement an asynchronous IPv4/IPv6 TCP echo server using BSD sockets and poll() Overview ******** @@ -9,7 +10,7 @@ Overview The sockets/echo-async sample application for Zephyr implements an asynchronous IPv4/IPv6 TCP echo server using a BSD Sockets compatible API with non-blocking sockets and a ``poll()`` call. This is an extension of -the :ref:`sockets-echo-sample` sample. It's a more involved application, +the :zephyr:code-sample:`sockets-echo` sample. It's a more involved application, supporting both IPv4 and IPv6 with concurrent connections, limiting maximum number of simultaneous connections, and basic error handling. @@ -42,7 +43,7 @@ After the sample starts, it expects connections at 192.0.2.1 (IPv4), or $ telnet 2001:db8::1 4242 # or this for IPv6 After a connection is made, the application will echo back any line sent to -it. Unlike the above-mentioned :ref:`sockets-echo-sample`, this application +it. Unlike the above-mentioned :zephyr:code-sample:`sockets-echo` sample, this application supports multiple concurrent client connections. You can open another terminal window and run the same telnet command as above. The sample supports up to three connected clients, but this can be adjusted diff --git a/samples/net/sockets/echo_async_select/README.rst b/samples/net/sockets/echo_async_select/README.rst index af30527727d..cc2b48735d8 100644 --- a/samples/net/sockets/echo_async_select/README.rst +++ b/samples/net/sockets/echo_async_select/README.rst @@ -1,7 +1,8 @@ -.. _async-sockets-echo-select-sample: +.. zephyr:code-sample:: async-sockets-echo-select + :name: Asynchronous echo server using select() + :relevant-api: bsd_sockets -Asynchronous Socket Echo Server Using select() -############################################## + Implement an asynchronous IPv4/IPv6 TCP echo server using BSD sockets and select() Overview ******** @@ -9,7 +10,7 @@ Overview The sockets/echo_async_select sample application for Zephyr implements an asynchronous IPv4/IPv6 TCP echo server using a BSD Sockets compatible API with non-blocking sockets and a ``select()`` call. This is a variant of -the :ref:`async-sockets-echo-sample` sample. +the :zephyr:code-sample:`async-sockets-echo` sample. The source code for this sample application can be found at: :zephyr_file:`samples/net/sockets/echo_async_select`. @@ -40,7 +41,7 @@ After the sample starts, it expects connections at 192.0.2.1 (IPv4), or $ telnet 2001:db8::1 4242 # or this for IPv6 After a connection is made, the application will echo back any line sent to -it. Unlike the :ref:`sockets-echo-sample`, this application +it. Unlike the :zephyr:code-sample:`sockets-echo` sample, this application supports multiple concurrent client connections. You can open another terminal window and run the same telnet command as above. The sample supports up to three connected clients, but this can be adjusted diff --git a/samples/net/sockets/echo_client/README.rst b/samples/net/sockets/echo_client/README.rst index 31d03d18202..ce9ccf2532b 100644 --- a/samples/net/sockets/echo_client/README.rst +++ b/samples/net/sockets/echo_client/README.rst @@ -1,7 +1,8 @@ -.. _sockets-echo-client-sample: +.. zephyr:code-sample:: sockets-echo-client + :name: Echo client (advanced) + :relevant-api: bsd_sockets tls_credentials -Socket Echo Client -################## + Implement a client that sends IP packets, waits for data to be sent back, and verifies it. Overview ******** @@ -105,7 +106,7 @@ running ``west build`` or ``cmake``. The certificate and private key used by the sample can be found in the sample's ``src`` directory. The default certificates used by Socket Echo Client and -:ref:`sockets-echo-server-sample` enable establishing a secure connection +:zephyr:code-sample:`sockets-echo-server` enable establishing a secure connection between the samples. SOCKS5 proxy support @@ -178,6 +179,6 @@ You can verify TLS communication with a Linux host as well. See https://github.com/zephyrproject-rtos/net-tools documentation for information on how to test TLS with Linux host samples. -See the :ref:`sockets-echo-server-sample` documentation for an alternate +See the :zephyr:code-sample:`sockets-echo-server` documentation for an alternate way of running, with the echo-client on the Linux host and the echo-server in QEMU. diff --git a/samples/net/sockets/echo_server/README.rst b/samples/net/sockets/echo_server/README.rst index fed7ef00a41..20ce37e7991 100644 --- a/samples/net/sockets/echo_server/README.rst +++ b/samples/net/sockets/echo_server/README.rst @@ -1,7 +1,8 @@ -.. _sockets-echo-server-sample: +.. zephyr:code-sample:: sockets-echo-server + :name: Echo server (advanced) + :relevant-api: bsd_sockets tls_credentials -Socket Echo Server -################## + Implement a UDP/TCP server that sends received packets back to the sender. Overview ******** @@ -107,7 +108,7 @@ running ``west build`` or ``cmake``. The certificate used by the sample can be found in the sample's ``src`` directory. The default certificates used by Socket Echo Server and -:ref:`sockets-echo-client-sample` enable establishing a secure connection +:zephyr:code-sample:`sockets-echo-client` enable establishing a secure connection between the samples. Running echo-client in Linux Host @@ -140,6 +141,6 @@ You can verify TLS communication with a Linux host as well. See https://github.com/zephyrproject-rtos/net-tools documentation for information on how to test TLS with Linux host samples. -See the :ref:`sockets-echo-client-sample` documentation for an alternate +See the :zephyr:code-sample:`sockets-echo-client` sample documentation for an alternate way of running, with the echo-server on the Linux host and the echo-client in QEMU. diff --git a/samples/net/sockets/http_client/README.rst b/samples/net/sockets/http_client/README.rst index 1d37121ad56..855c36d068a 100644 --- a/samples/net/sockets/http_client/README.rst +++ b/samples/net/sockets/http_client/README.rst @@ -1,7 +1,8 @@ -.. _sockets-http-client-sample: +.. zephyr:code-sample:: sockets-http-client + :name: HTTP client + :relevant-api: bsd_sockets http_client tls_credentials secure_sockets_options -Socket HTTP Client -################## + Implement an HTTP(S) client that issues a variety of HTTP requests. Overview ******** diff --git a/samples/net/sockets/http_get/README.rst b/samples/net/sockets/http_get/README.rst index bd4a6824d7f..790b9756f31 100644 --- a/samples/net/sockets/http_get/README.rst +++ b/samples/net/sockets/http_get/README.rst @@ -1,7 +1,8 @@ -.. _sockets-http-get: +.. zephyr:code-sample:: sockets-http-get + :name: HTTP GET using plain sockets + :relevant-api: bsd_sockets tls_credentials secure_sockets_options -Socket HTTP GET Example -####################### + Implement an HTTP(S) client using plain BSD sockets. Overview ******** diff --git a/samples/net/sockets/net_mgmt/README.rst b/samples/net/sockets/net_mgmt/README.rst index 4fade75c725..92d6d8524c7 100644 --- a/samples/net/sockets/net_mgmt/README.rst +++ b/samples/net/sockets/net_mgmt/README.rst @@ -1,7 +1,8 @@ -.. _sockets-net-mgmt-sample: +.. zephyr:code-sample:: sockets-net-mgmt + :name: Network management socket + :relevant-api: bsd_sockets net_if -Network Management Socket -######################### + Listen to network management events using a network management socket. Overview ******** diff --git a/samples/net/sockets/packet/README.rst b/samples/net/sockets/packet/README.rst index fe6ce34c7cd..ea096be0a23 100644 --- a/samples/net/sockets/packet/README.rst +++ b/samples/net/sockets/packet/README.rst @@ -1,7 +1,8 @@ -.. _packet-socket-sample: +.. zephyr:code-sample:: packet-socket + :name: Packet socket + :relevant-api: bsd_sockets ethernet -Packet socket sample -#################### + Use raw packet sockets over Ethernet. Overview ******** diff --git a/samples/net/sockets/sntp_client/README.rst b/samples/net/sockets/sntp_client/README.rst index 9515ca3158c..1e061c36a70 100644 --- a/samples/net/sockets/sntp_client/README.rst +++ b/samples/net/sockets/sntp_client/README.rst @@ -1,7 +1,8 @@ -.. _sntp-client-sample: +.. zephyr:code-sample:: sntp-client + :name: SNTP client + :relevant-api: bsd_sockets sntp -SNTP client sample -################## + Use SNTP to get the current time from the host. Overview ******** diff --git a/samples/net/sockets/socketpair/README.rst b/samples/net/sockets/socketpair/README.rst index 7372d1293f0..3dce3caea7e 100644 --- a/samples/net/sockets/socketpair/README.rst +++ b/samples/net/sockets/socketpair/README.rst @@ -1,7 +1,8 @@ -.. _sockets-socketpair-sample: +.. zephyr:code-sample:: sockets-socketpair + :name: Socketpair + :relevant-api: bsd_sockets -Socketpair Example -################## + Implement communication between threads using socket pairs. Overview ******** diff --git a/samples/net/sockets/tcp/README.rst b/samples/net/sockets/tcp/README.rst index 5f43d02d41f..c0540cca147 100644 --- a/samples/net/sockets/tcp/README.rst +++ b/samples/net/sockets/tcp/README.rst @@ -1,7 +1,8 @@ -.. _sockets-tcp-sample: +.. zephyr:code-sample:: sockets-tcp-sample + :name: TCP sample for TTCN-3 based sanity check + :relevant-api: bsd_sockets -TCP Sample for TTCN-3 based Sanity Check -######################################## + Use TTCN-3 to validate the functionality of the TCP stack. Overview ******** diff --git a/samples/net/sockets/txtime/README.rst b/samples/net/sockets/txtime/README.rst index 67909d609c8..46979ce68bb 100644 --- a/samples/net/sockets/txtime/README.rst +++ b/samples/net/sockets/txtime/README.rst @@ -1,7 +1,8 @@ -.. _so_txtime-sample: +.. zephyr:code-sample:: so_txtime + :name: UDP sender using SO_TXTIME + :relevant-api: bsd_sockets ethernet -SO_TXTIME sample -################ + Control the transmission time of a packet using SO_TXTIME socket option. Overview ******** @@ -14,9 +15,9 @@ provided for qemu_x86 board. Also frdm_k64f and sam_e70_xplained boards are supported. Other mcux or gmac Ethernet driver based boards should work too. User can control how long the application should wait between packets sent by -setting CONFIG_NET_SAMPLE_PACKET_INTERVAL option. +setting :kconfig:option:`CONFIG_NET_SAMPLE_PACKET_INTERVAL` option. Also the TXTIME value can be specified in the config file by setting the -CONFIG_NET_SAMPLE_PACKET_TXTIME option. In this case the value is +:kconfig:option:`CONFIG_NET_SAMPLE_PACKET_TXTIME` option. In this case the value is used as an offset from the current time. Building and Running @@ -25,8 +26,8 @@ Building and Running When the application is run, it starts to send UDP packets. You can start ``echo-server`` application from `net-tools`_ project to catch these and send the data back to this application. Optionally you can set -CONFIG_NET_SAMPLE_PACKET_SOCKET option, which makes the application -to create an AF_PACKET type socket. In this case, the ``echo-server`` +:kconfig:option:`CONFIG_NET_SAMPLE_PACKET_SOCKET` option, which makes the application +to create an ``AF_PACKET`` type socket. In this case, the ``echo-server`` application cannot be used as a peer. This sample can be built and executed on qemu_x86 board as diff --git a/samples/net/sockets/websocket_client/README.rst b/samples/net/sockets/websocket_client/README.rst index d6ae83b568f..b8cf079683f 100644 --- a/samples/net/sockets/websocket_client/README.rst +++ b/samples/net/sockets/websocket_client/README.rst @@ -1,7 +1,8 @@ -.. _sockets-websocket-client-sample: +.. zephyr:code-sample:: sockets-websocket-client + :name: WebSocket Client + :relevant-api: bsd_sockets websocket -Socket Websocket Client -####################### + Implement a Websocket client that connects to a Websocket server. Overview ******** diff --git a/samples/net/stats/README.rst b/samples/net/stats/README.rst index e7d4ac6d911..84204d46131 100644 --- a/samples/net/stats/README.rst +++ b/samples/net/stats/README.rst @@ -1,7 +1,8 @@ -.. _net_stats-sample: +.. zephyr:code-sample:: net-stats + :name: Network statistics + :relevant-api: net_stats -Network Statistics Sample Application -##################################### + Query and display network statistics from a user application. Overview ******** diff --git a/samples/net/syslog_net/README.rst b/samples/net/syslog_net/README.rst index 04440b34f77..6e4247a5828 100644 --- a/samples/net/syslog_net/README.rst +++ b/samples/net/syslog_net/README.rst @@ -1,7 +1,8 @@ -.. _syslog-net-sample: +.. zephyr:code-sample:: syslog-net + :name: Remote syslog + :relevant-api: log_backend log_ctrl -Syslog net Application -###################### + Enable a remote syslog service that sends syslog messages to a remote server Overview ******** diff --git a/samples/net/telnet/README.rst b/samples/net/telnet/README.rst index ee77c9b1402..1c648e2e970 100644 --- a/samples/net/telnet/README.rst +++ b/samples/net/telnet/README.rst @@ -1,7 +1,8 @@ -.. _telnet-console-sample: +.. zephyr:code-sample:: telnet-console + :name: Telnet console + :relevant-api: shell_api net_core net_if net_mgmt -Sample TELNET console application -################################# + Access Zephyr shell over telnet. Overview ******** diff --git a/samples/net/tftp_client/README.rst b/samples/net/tftp_client/README.rst index ac7181f4605..40da21adcf6 100644 --- a/samples/net/tftp_client/README.rst +++ b/samples/net/tftp_client/README.rst @@ -1,7 +1,8 @@ -.. _tftp-client-sample: +.. zephyr:code-sample:: tftp-client + :name: TFTP client + :relevant-api: tftp_client -TFTP client -############ + Use the TFTP client library to get/put files from/to a TFTP server. Overview ******** diff --git a/samples/net/virtual/README.rst b/samples/net/virtual/README.rst index 6869d21e1a4..8b83fc9e0e7 100644 --- a/samples/net/virtual/README.rst +++ b/samples/net/virtual/README.rst @@ -1,7 +1,8 @@ -.. _virtual_network_interface-sample: +.. zephyr:code-sample:: virtual-network-interface + :name: Virtual network interface + :relevant-api: virtual virtual_mgmt -Virtual Network Interface Application -##################################### + Create a sample virtual network interface. Overview ******** @@ -9,11 +10,14 @@ Overview This sample application creates a sample virtual network interface for demonstrative purposes, it does not do anything useful here. There are total 4 network interfaces. + Ethernet network interface is providing the real network interface and all the virtual interfaces are running on top of it. + On top of Ethernet interface there are two virtual network interfaces, one provides only IPv6 tunnel, and the other only IPv4. These two tunnels are provided by IPIP tunnel. + The sample provides tunnel interface which runs on top of the IPv6 tunnel. The source code for this sample application can be found at: diff --git a/samples/net/vlan/README.rst b/samples/net/vlan/README.rst index 3cd2c812bff..346dc07a6c3 100644 --- a/samples/net/vlan/README.rst +++ b/samples/net/vlan/README.rst @@ -1,7 +1,8 @@ -.. _vlan-sample: +.. zephyr:code-sample:: vlan + :name: Virtual LAN + :relevant-api: vlan_api net_l2 net_if -Virtual LAN Sample Application -############################## + Setup two virtual LAN networks and use net-shell to view the networks' settings. Overview ******** diff --git a/samples/net/wifi/README.rst b/samples/net/wifi/README.rst index 8638e48103e..81aaa61a729 100644 --- a/samples/net/wifi/README.rst +++ b/samples/net/wifi/README.rst @@ -1,7 +1,8 @@ -.. _wifi_sample: +.. zephyr:code-sample:: wifi-shell + :name: Wi-Fi shell + :relevant-api: net_stats -Wi-Fi sample -############ + Test Wi-Fi functionality using the Wi-Fi shell module. Overview ******** diff --git a/samples/net/wpan_serial/README.rst b/samples/net/wpan_serial/README.rst index 669c574117d..3bcf5dbb4d4 100644 --- a/samples/net/wpan_serial/README.rst +++ b/samples/net/wpan_serial/README.rst @@ -1,7 +1,8 @@ -.. _wpan_serial-sample: +.. zephyr:code-sample:: wpan-serial + :name: 802.15.4 "serial-radio" + :relevant-api: ieee802154 uart_interface -802.15.4 "serial-radio" sample -############################## + Implement a slip-radio device for Contiki-based border routers. Overview ******** diff --git a/samples/net/wpanusb/README.rst b/samples/net/wpanusb/README.rst index e6e87502a66..aa4b6e38e14 100644 --- a/samples/net/wpanusb/README.rst +++ b/samples/net/wpanusb/README.rst @@ -1,7 +1,8 @@ -.. _wpanusb-sample: +.. zephyr:code-sample:: _wpanusb + :name: 802.15.4 USB + :relevant-api: ieee802154 _usb_device_core_api -wpanusb sample -############## + Implement a device that exposes an IEEE 802.15.4 radio over USB. Overview ******** diff --git a/samples/net/zperf/README.rst b/samples/net/zperf/README.rst index ded271b9a43..949acba5e76 100644 --- a/samples/net/zperf/README.rst +++ b/samples/net/zperf/README.rst @@ -1,7 +1,8 @@ -.. _zperf-sample: +.. zephyr:code-sample:: zperf + :name: zperf: Network Traffic Generator + :relevant-api: net_config -zperf: Network Traffic Generator -################################ + Use the zperf shell utility to evaluate network bandwidth. Description *********** diff --git a/samples/subsys/mgmt/updatehub/README.rst b/samples/subsys/mgmt/updatehub/README.rst index 0324ab97025..aea33944193 100644 --- a/samples/subsys/mgmt/updatehub/README.rst +++ b/samples/subsys/mgmt/updatehub/README.rst @@ -203,7 +203,7 @@ Step 4.3: Build for Modem Modem needs add ``overlay-modem.conf``. Now, a DTC overlay file is used to configure the glue between the modem and an arduino headers. The modem config -uses PPP over GSM modem, see :ref:`gsm-modem-sample`. +uses PPP over GSM modem, see :zephyr:code-sample:`gsm-modem-sample` sample application. .. zephyr-app-commands:: :zephyr-app: zephyr/samples/subsys/mgmt/updatehub @@ -220,7 +220,7 @@ Step 4.4: Build for IEEE 802.15.4 [experimental] For IEEE 802.15.4 needs add ``overlay-802154.conf``. This requires two nodes: one will be the host and the second one will be the device under test. The validation needs a Linux kernel >= 4.9 with all 6loWPAN support. The start -point is try reproduce the Zephyr :ref:`wpanusb-sample`. It is out of scope +point is try reproduce the Zephyr :zephyr:code-sample:`wpan-usb`. It is out of scope at this moment provide support since it is experimental. The gateway was tested with both native linux driver and ``atusb`` and with ``wpanusb`` sample.