DOCSEARCHbyAlgolia
Submit Docs

Eclipse ThreadX NetX Duo

repository·master·Indexed 43 days ago

https://github.com/eclipse-threadx/netxduo

An industrial-grade, dual IPv4 and IPv6 TCP/IP network stack designed for deeply embedded real-time and IoT applications. It includes support for various protocols via addon modules such as MQTT, HTTP, FTP, and DNS, as well as Azure IoT Middleware for connectivity to Azure IoT Hub and Device Provisioning Service (DPS).

Tokens
21.8K
Snippets
73
Records
87
Agent score
55%

What's inside NetX Duo

  1. Overview of Azure IoT Middleware for Azure RTOS

    master

    Azure IoT Middleware for Azure RTOS is a platform-specific binding layer between Azure RTOS and the Azure SDK for Embedded C.

    It serves several key purposes:

    • Exposes smart client interfaces (IoTHub_Client, DeviceProvisioning_Client) for application consumption.
    • Orchestrates interactions between the Embedded C SDK and the platform.
    • Provides Azure RTOS platform initialization.
    • Supports IoT Plug and Play.
    • Provides security capabilities and is resource-limitation aware.
    • Supports various protocols.

    It functions as an addon module for NetX Duo, facilitating the MQTT and TLS stacks provided by NetX Duo addons.

  2. Understand the NetX Duo repository structure

    master

    The NetX Duo repository is organized as follows:

    • addons/: Addon modules for various protocols and connectivity.
    • cmake/: CMake configuration files for building the project.
    • common/: Core NetX Duo source files.
    • crypto_libraries/: NetX Crypto files.
    • nx_secure/: NetX Secure files.
    • ports/: Architecture and compiler-specific files.
    • samples/: Sample code demonstrating usage.
    • utility/: Test cases and utilities (e.g., iperf).
    • LICENSE.txt & LICENSE-HARDWARE.txt: Licensing terms.

  3. Features of Azure IoT Middleware

    master

    The Azure IoT Middleware provides the following capabilities:

    Basic Features

    • Connectivity: Connect to Azure IoT Hub via MQTT.
    • IoT Hub Primitives: Support for Device to Cloud (D2C) messages, Device Twins, and Direct methods.
    • IoT Plug and Play: Support for Telemetry, Properties, and Commands data formats.
    • Authentication: Supports SAS Token and X.509 client certificates.
    • Data Handling: Includes JSON parsers.

    Device Update for IoT Hub

    • Provides an agent for Device Update for IoT Hub to enable over-the-air (OTA) updates.
    • Offers simple APIs for device builders to integrate OTA capabilities easily.

  4. Configure NetX Duo protocols and connectivity via addons

    master

    NetX Duo provides protocol and connectivity support through addon modules located in the addons directory. Key available modules include:

    • azure_iot
    • dhcp
    • dns
    • ftp
    • http
    • mqtt
    • pop3
    • ppp
    • rtp
    • rtsp
    • sntp
    • web (Telnet)

    Refer to the official NetX Duo documentation for a full list of available addons.

  5. IoT Plug and Play (PnP) capabilities

    master

    The sample supports IoT Plug and Play (PnP) for devices using a Digital Twin Model ID (DTMI).

    Supported Capabilities:

    • Methods: Supports getMaxMinReport. It requires a JSON payload with a since field containing an ISO8601 timestamp. The response contains maxTemp, minTemp, avgTemp, startTime, and endTime.
    • Telemetry: The device sends a JSON message containing a temperature field (type double).
    • Twin:
      • Desired Property: targetTemperature (type double).
      • Reported Property: maxTempSinceLastReboot (type double).
      • Acknowledgements: When a desired property is updated, the device responds with reported properties including ac (ack code), av (ack version), and an optional ad (ack description).

  6. Generate self-signed X509 certificates using OpenSSL

    master

    To use X509 authentication, you must generate self-signed certificates where the Common Name (CN) matches your DeviceId.

    1. Create configuration file

    Create x509_config.cfg to define client authentication extensions:

    cat > x509_config.cfg <<EOT
[req]
req_extensions = client_auth
distinguished_name = req_distinguished_name

[req_distinguished_name]

[ client_auth ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth
EOT

    2. Generate Certificates

    For RSA:

    # Generate private key and certificate
openssl genrsa -out privkey.pem 2048
openssl req -new -days 365 -nodes -x509 -key privkey.pem -out cert.pem -config x509_config.cfg -subj "/CN=<Same as device Id>"

# Convert to DER format
openssl rsa -outform der -in privkey.pem -out privkey.der 
openssl x509 -outform der -in cert.pem -out cert.der

    For EC (Elliptic Curve):

    # Generate private key and certificate
openssl req -new -x509 -nodes -days 365 -newkey ec:<(openssl ecparam -name secp384r1) -keyout privkey.pem -out cert.pem -config x509_config.cfg -subj "/CN=<Same as device Id>"

# Convert to DER format
openssl ec -outform der -in privkey.pem -out privkey.der
openssl x509 -outform der -in cert.pem -out cert.der

    3. Convert DER to C hex arrays

    Use xxd to convert the .der files into hex arrays and append them to sample_device_identity.c:

    xxd -i cert.der | sed -E "s/(unsigned char) (\w+)/\1 sample_device_cert_ptr/g; s/(unsigned int) (\w+)_len/\1 sample_device_cert_len/g" >> sample_device_identity.c
xxd -i privkey.der | sed -E "s/(unsigned char) (\w+)/\1 sample_device_private_key_ptr/g; s/(unsigned int) (\w+)_len/\1 sample_device_private_key_len/g" >> sample_device_identity.c

  7. Configure Device Provisioning Service (DPS) with Symmetric Key

    master

    To use Azure Device Provisioning Service (DPS) with Symmetric Key authentication, create an individual enrollment in the Azure portal.

    Add the following macros to your compiler options to enable DPS and provide the necessary service details.

    #define ENDPOINT                                    "<Service Endpoint or Global device endpoint>"
#define ID_SCOPE                                    "<ID Scope value>"
#define REGISTRATION_ID                             "<RegistrationId from Individual registration>"
#define DEVICE_SYMMETRIC_KEY                        "<Symmetric key from Individual registration detail page>"

/* Enable DPS */
#define ENABLE_DPS_SAMPLE

  8. Configure IoTHub connection using Symmetric Key

    master

    To connect to an Azure IoTHub using Symmetric Key authentication, register a new device in the Azure portal and obtain its connection string in the format HostName=<>;DeviceId=<>;SharedAccessKey=<>.

    Add the following macros to your compiler options to configure the sample. By default, Telemetry, Cloud-to-Device (C2D) messages, and Direct Methods are enabled. You can disable them by defining the corresponding DISABLE_*_SAMPLE macros.

    /* Connection Configuration */
#define HOST_NAME                                   "<Hostname from connection string>"
#define DEVICE_ID                                   "<DeviceId from connection string>"
#define DEVICE_SYMMETRIC_KEY                        "<SharedAccessKey from connection string>"

/* Feature Control (Optional) */
#define DISABLE_TELEMETRY_SAMPLE
#define DISABLE_C2D_SAMPLE
#define DISABLE_DIRECT_METHOD_SAMPLE

  9. Build NetX Duo as a static library using CMake and Ninja

    master

    To build NetX Duo as a standalone static library using the Arm GNU Toolchain and CMake, follow these steps:

    1. Prerequisites

    Install the following tools:

    • CMake (version 3.0 or later)
    • Arm GNU Toolchain for arm-none-eabi
    • Ninja

    2. Build ThreadX

    Build the ThreadX library first, as it is a required dependency.

    3. Clone the Repository

    NetX Duo uses submodules for its dependencies. Clone the repository recursively:

    git clone --recursive https://github.com/eclipse-threadx/netxduo.git

    4. Configure Features

    Define the required features and addons in nx_user.h. You can use common/inc/nx_user_sample.h as a reference template.

    5. Execute Build

    To build the library for a Cortex-M4 target, use the following commands:

    cmake -Bbuild -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/cortex_m4.cmake .
cmake --build ./build
    $ git clone --recursive https://github.com/eclipse-threadx/netxduo.git

$ cmake -Bbuild -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/cortex_m4.cmake .

$ cmake --build ./build

  10. Create and send IoT Hub reported properties

    master

    To update properties on the IoT Hub from the device (Reported Properties), you must first create a message packet and then send it.

    1. Use nx_azure_iot_hub_client_reported_properties_create to allocate an NX_PACKET containing the reported properties structure.
    2. Use nx_azure_iot_hub_client_reported_properties_send to transmit the packet.

    Note that nx_azure_iot_hub_client_reported_properties_send provides a response_status_ptr which indicates if the IoT Hub actually accepted the properties. This status is only valid if the function returns NX_AZURE_IOT_SUCCESS.

    /* 1. Create the reported properties packet */
NX_PACKET *packet_ptr;
UINT status;

status = nx_azure_iot_hub_client_reported_properties_create(&hub_client, &packet_ptr, wait_ticks);

/* 2. Send the packet */
UINT request_id;
UINT response_status;
ULONG version;

status = nx_azure_iot_hub_client_reported_properties_send(&hub_client, packet_ptr, &request_id, &response_status, &version, wait_ticks);

if (status == NX_AZURE_IOT_SUCCESS) {
    /* Check response_status to see if IoT Hub accepted the update */
}

  12. Configure macros to build Azure IoT Middleware

    master

    To build the Azure IoT Middleware for Azure RTOS as part of NetX Duo, you must define specific macros in your CMakeLists.txt or nx_user.h.

    Required macros:

    • NX_ENABLE_EXTENDED_NOTIFY_SUPPORT
    • NX_SECURE_ENABLE
    • NXD_MQTT_CLOUD_ENABLE

    Refer to nx_user_sample.h in the NetX Duo repository for examples on how to define these macros in the NetX user header file.

    // Example macro definitions in nx_user.h or CMakeLists.txt
#define NX_ENABLE_EXTENDED_NOTIFY_SUPPORT
#define NX_SECURE_ENABLE
#define NXD_MQTT_CLOUD_ENABLE