NetX Duo

1 Introduction

Azure RTOS NetX Duo is a dual IPv4 and IPv6 TCP/IP network stack designed specifically for deeply embedded, real-time, and IoT applications. It comes with different set of features. Alongside the TCP/IP IPv4/IPv6 network stack, it provides a crypto library implementing the standard crypto and hash methods, and a TLS/DTLS library to support secure network connections.

NetX Duo Overview

  • NetX Duo core offers a full TCP/IP IPv4IPV6 compliant stack with 3 types of API: TCP/IP, UDP/IP and RAW API.
  • Crypto core implements the common crypto cipher suites and hashing algorithms useful for securing connections and exchanging encrypted data: AES, 3DES, HMAC, RSA, SHA1, SHA224, SHA256, SHA384, SHA512, MD5, HMAC-SHA1, and so on (each algorithm has its own implementation file .c and header file .h, which facilitate the selection and the integration of the required algorithms by the applications).
  • TLS core implements the secure connection API. Based on both the Crypto core and NetX Duo core, it supports the TLS and DTLS protocols with their different variants. (TLS 1.0 TLS 1.2, TLS 1.3)

It also supports the X509 public signed certificates protocol.

  • Addon protocols are a pre-supported set of network applicative protocols that ease the integration of the networking feature in the end user application. The main supported protocols are the following:


Further details are available in the NetX Duo official documentation

NetX Duo folders are organized as explained below:

NetX Duo Folders

2 STM32 Integration

NetX Duo can run on any networking hardware, such as Ethernet, WiFi modules, cellular modems, and so on. For the moment only the following hardware are supported:

  • Ethernet: Currently any STM32 board that provides an Ethernet IP, uses the Ethernet PHY microchip LAN874X (driver under Drivers/BSP/Components In the X-CUBE-AZRTOS-H7 package).

Info.png NetX requires the Zero-copy feature that is currently supported only in the STM32H7 HAL Ethernet driver.

  • WiFi: this support is very specific, focusing only on WiFi modules supporting bypass mode

NetX Duo requires a low-level driver to interact between the physical layer already chosen, and the NetX Duo core requests (initialize, transmit data, receive data).

NetX Duo Low Layer Interfacing

This is an interface, on top of the HAL Ethernet driver. It is part of the NetX Duo source code with the possibility of tuning via a configuration file.

NetX Duo Low Layer Files

  • nx_stm32_eth_config_template.h: a template config header file to tune the corresponding driver for aspecific STM32 MCU/board. This file should be copied into the application source tree and renamed to nx_stm32_eth_driver.h, then customized according to the driver needs.
  • nx_stm32_*_driver.h: the driver header file containing the driver defines and data structure.
  • nx_stm32_*_driver_config_template.h: an application level config file that allows users to tune some options related to the driver, a template file is provided in the driver source tree for reference.
  • nx_stm32_*_driver.c: this is referenced directly by the application and may be different between STM32 series depending on the supported features.

This is not the final version; future versions are planned to add interrupt mode to the currently implemented polling mode.

  • nx_stm32_xxx_driver_template.c/.h: an empty interface that can be used to implement a new custom driver.

Info.png WiFi driver is not yet supported in X-CUBE-AZRTOS-H7 v1.0.0 (first integration of Azure RTOS in STM32Cube Ecosystem) and is planned for a future release

After low-level configuration, it is called in application code when an IP instance is created:

  /* Create an IP instance by linking the ux network driver */
  ret = nx_ip_create(&EthIP, "NetX IP Instance 0", 
                                NULL_IP_ADDRESS,  NULL_IP_ADDRESS, 
                               IP_MEMORY_SIZE, DEFAULT_PRIORITY);

2.1 Known limitations

  • The support of the BSD API is not fully-compliant, this may impact the portability of legacy applications. More details are available in the official NetX Duo documentation official documentation

3 How to use

The main APIs needed to use the NetX Duo are described in table below: (further details and a full API description are available from NetX Duo official documentation)

Function Name Short Description
nx_tcp_socket_create( ) Create a TCP socket
nx_udp_socket_create( ) Create a UDP socket
nx_tcp_server_socket_listen( ) Set up TCP socket to listen
nx_udp_socket_bind( ) Bind UDP socket to the PORT
nx_tcp_server_socket_accept( ) Accept a TCP remote client socket connection
nx_tcp_socket_receive( ) Receive a packet from a TCP remote client
nx_udp_socket_receive( ) Receive a packet from a UDP remote client
nx_tcp_socket_disconnect( ) Disconnect the TCP server socket
nx_tcp_server_socket_unaccept( ) Reject the TCP server socket
nx_tcp_server_socket_relisten( ) Set up server socket for listening again

The main steps to use the NetX Duo are:

  • First, initialize nx_system from the tx_application_define function, then create a pool (named ETH_pool in the next example).


    /* Initialize the NetX system.  */

    /* Create a packet pool.  */
    status = nx_packet_pool_create(&pool_0, "NetX Main Packet Pool", SAMPLE_PACKET_SIZE,
                                   (UCHAR *)sample_pool_stack , sample_pool_stack_size);

  • Then, create and configure an IP instance which belongs to pool already created.
  • Enable the needed NetX Duo components depending on the target application:
Function Name Short Description
nx_arp_enable( ) Enable the Address Resolution Protocol (AutoIP Protocol need ARP)
nx_icmp_enable( ) Required for Ping
nx_udp_enable( ) Enable UDP traffic (DNS & DHCP need UDP)
nx_tcp_enable( ) Enable TCP traffic

4 STM32 NetX Duo applications

The Following figure shows the project architecture and main application files.

NetX Duo Application Files

STM32 Packages provide the following set of applications (supported applications list may differ between products and boards):

Application Short Description
Nx_TCP_Echo_Server Demonstrates how to develop a NetX TCP server to communicate with a remote client using the NetX TCP socket API. [readme]
Nx_TCP_Echo_Client Demonstrates how to develop a NetX TCP client to communicate with a remote sever using the NetX TCP socket API. [readme]
Nx_UDP_Echo_Server Demonstrates how to develop a NetX UDP server to communicate with a remote client using the NetX UDP socket API. [readme]
Nx_UDP_Echo_Client Demonstrates how to develop a NetX UDP client to communicate with a remote sever using the NetX UDP socket API. [readme]
Nx_WebServer Demonstrates how to develop Web HTTP server based application. It is designed to load files and static web pages stored in an SD Card using a Web HTTP server, the code provides all required features to build a compliant Web HTTP Server. [readme]
Nx_MQTT_Client Demonstrates how to exchange data between client and server using MQTT protocol in an encrypted mode supporting TLS v1.2.. [readme]
Nx_SNTP_Client Demonstrates how to develop a NetX SNTP client and connect with an STNP server to get a time update. [readme]