Networking¶

FreeRTOS applications use lwIP 2.1.2 as the TCP/IP stack and mbedTLS 2.28.2 for TLS. IPRO7 reaches a network in one of two ways: Wi-Fi through an IPRO6S that acts as the radio and attaches over SDIO, or the IPRO7 Ethernet MAC (EMAC, RMII) with an external PHY. On the IPRO7AI Reef EVK the IPRO6S is the FIN card in the microSD socket. Both links feed the same lwIP stack, so socket code does not change with the interface.

Architecture¶

Network configuration¶

The build copies .config into autoconf.h as written; Kconfig select and depends on are not applied, so write out every key the link needs.

CONFIG_IPRO7AI_REEF=y
CONFIG_USE_PSRAM=y
CONFIG_IPRO7_WIFI_HOST_HOTCODE=y
CONFIG_WIFI_USE_IPRO6S=y
CONFIG_COMPONENTS_LWIP_ENABLE=y
CONFIG_COMPONENTS_LWIP_APP_ENABLE=y
CONFIG_ETHERNET=y
CONFIG_COMPONENTS_IPRONET_HOST_ENABLE=y
CONFIG_RTSP_SERVER=y
CONFIG_RTSP_LISTEN_PORT=8554
CONFIG_RTSP_DEFAULT_VIDEO_FPS=15
CONFIG_RTSP_SHELL=y

CONFIG_COMPONENTS_LWIP_ENABLE=y
CONFIG_COMPONENTS_LWIP_APP_ENABLE=y
CONFIG_ETHERNET=y
CONFIG_COMPONENTS_MBEDTLS_ENABLE=y
CONFIG_MBEDTLS_BIGNUM_USE_HW=y

An application can override lwIP settings with its own lwipopts_app.h, which lwipopts.h includes when it exists. With ipronet_host, copy apps/platform/ipro7ai_reef_demo/lwipopts_app.h (the same file as in ipro7_sdio_wifi): it moves the lwIP buffers into PSRAM and enlarges the TCP window. The component README notes that TCP upload throughput drops to about a quarter without it.

lwIP¶

lwIP provides a BSD-style socket API (lwip/sockets.h, lwip/netdb.h). The DHCP client, DNS, SNTP, IPv6, lwiperf and lwIP's HTTP client are built in; the DHCP server, mDNS, MQTT and altcp TLS are added with the keys above.

This TCP client follows the steps of apps/platform/common/ipronet_ota_cli/ota_http_fetch.c, which ipro7ai_reef_demo compiles for ipro6s_ota: resolve the host name, open a socket, connect. Use sockets only after the interface has an address (with ipronet_host, after the on_got_ip callback).

#include <string.h>
#include "lwip/sockets.h"
#include "lwip/netdb.h"

int tcp_send(const char *host, uint16_t port, const void *data, size_t len)
{
    struct hostent *hp = gethostbyname(host);
    if (hp == NULL) {
        return -1;
    }

    struct sockaddr_in sa;
    memset(&sa, 0, sizeof(sa));
    sa.sin_family = AF_INET;
    sa.sin_port = htons(port);
    memcpy(&sa.sin_addr, hp->h_addr, hp->h_length);

    int s = socket(AF_INET, SOCK_STREAM, 0);
    if (s < 0) {
        return -1;
    }
    if (connect(s, (struct sockaddr *)&sa, sizeof(sa)) < 0 ||
        send(s, data, len, 0) < 0) {
        close(s);
        return -1;
    }
    close(s);
    return 0;
}

Ethernet¶

The IPRO7 EMAC connects to an external PHY over RMII (10/100 Mbps); the HAL includes an RTL8201F PHY driver. The Reef carries no PHY, so this path is for your own board. The lwIP glue is bsp/hal/src/hal_ethernetif.c: once the link is up its DHCP task requests an address, and falls back to the static address defined in that file when DHCP times out. For the EMAC pins see bsp/hal/src/hal_emac.c and Pinout & Peripheral Mapping.

The netif is added and lwIP started the same way as in apps/platform/ipro7_demo/demo/soc/peripheral/emac_demo.c:

static struct netif emac_netif;

static void regist_netif(void *arg)
{
    struct netif *netif = (struct netif *)arg;
    ip4_addr_t ipaddr, netmask, gw;

    ip_addr_set_zero(&ipaddr);
    ip_addr_set_zero(&netmask);
    ip_addr_set_zero(&gw);
    netif_add(netif, &ipaddr, &netmask, &gw, NULL, ethernetif_init, tcpip_input);
    netif_set_default(netif);
    ethernet_link_status_updated(netif);
#if LWIP_NETIF_LINK_CALLBACK
    netif_set_link_callback(netif, ethernet_link_status_updated);
#endif
}

int cmd_emac_lwip(int argc, char **argv)
{
    tcpip_init(regist_netif, (void *)&emac_netif);
    return 0;
}

ipro7_demo targets the IPRO7 EVB and compiles emac_demo.c only with CONFIG_DEMO_EMAC=y, which its shipped .config does not set.

TLS / DTLS (mbedTLS)¶

mbedTLS 2.28.2 is added with CONFIG_COMPONENTS_MBEDTLS_ENABLE=y. The default configuration builds on mbedTLS's own config.h, including the TLS 1.2 client and X.509. An application that provides its own mbedtls_app_config.h replaces the whole default configuration (the mbedTLS component must find it on its include path). Entropy comes from the hardware random number generator (port/entropy_poll_alt.c).

On IPRO7, CONFIG_MBEDTLS_ECC_USE_HW falls back to the software implementation; the build prints a warning.

For a TLS client, start from components/crypto/mbedtls/mbedtls/programs/ssl/ssl_client1.c. When porting it:

• Check the return value of every initialization and connection call.
• Load the CA certificates your service trusts with mbedtls_ssl_conf_ca_chain(), use MBEDTLS_SSL_VERIFY_REQUIRED, and set the host name with mbedtls_ssl_set_hostname(). The platform clock must be right for certificate validity checks.
• Handle MBEDTLS_ERR_SSL_WANT_READ / MBEDTLS_ERR_SSL_WANT_WRITE, partial transfers and timeouts, and free the TLS context and the socket on every error path.
• Replace the example's test certificates and host with your product's.

HTTP, MQTT and RTSP¶

For HTTPS or MQTT over TLS, build the secure connection with mbedTLS (or altcp TLS) yourself, and handle status codes, chunked transfer, length limits and timeouts.

Wi-Fi through an IPRO6S¶

flowchart LR
  A["IPRO7<br/>application + ipronet_host + lwIP"] -->|"SDIO 4-bit<br/>GPIO28–33"| B["IPRO6S<br/>ipro6_if_wifi"]
  B -->|Wi-Fi| C["Access point"]

IPRO7 is the SDIO host. The IPRO6S runs ipro6_if_wifi and bridges Ethernet frames to Wi-Fi; DHCP runs on the IPRO6S, and the IP stack and your sockets run on IPRO7. The SDIO bus is fixed to GPIO28–33 and the component sets up the pins. On the Reef these are the microSD socket's lines, so the FIN card takes the place of an SD card.

ipronet_host.h in brief:

• The callbacks (on_connected, on_disconnected, on_got_ip, on_scan_result) run in the component's RX task. They must not block and must not call ipronet_connect / disconnect / scan / stop; hand the work to your own task.
• With auto_reconnect = 1 (the default) the component rejoins the AP after a disconnect; with 0 your application calls ipronet_connect() again from on_disconnected.
• All return codes are listed in ipronet_host.h (IPRONET_OK is 0) and in components/network/ipronet_host/README.md.

Hands-on on the Reef¶

Join a Wi-Fi network from the Reef and stream the camera over RTSP, using the shell commands of the out-of-box firmware. The tutorial version, with a video player on the host, is the Wi-Fi and RTSP tutorial.

You need the IPRO6S FIN card running ipro6_if_wifi (defconfig_ipro6_sdio), an OV5640 or OV2640 camera module on the camera connector, and a Wi-Fi access point.

Next: build your own application from this configuration with Create Your First Application, and check it with Test Your Application.

Other Wi-Fi modules¶

The Reef connects to Wi-Fi only through the IPRO6S FIN card. Driver and probe code for other SDIO Wi-Fi modules in the package targets the IPRO7 EVB and is not a supported Reef path; see Examples.

IPRO6S as the Wi-Fi device¶

The IPRO6S side of the link is an IPRO6S FreeRTOS application from the same SDK. Its outputs end in _IPRO6.bin, and its prebuilt Wi-Fi libraries exist only for the shipped configurations, so keep the Wi-Fi options and CONFIG_WIRELESS_LIB_VARIANT of one of them.

The chip, its board and flashing are covered on IPRO6S.

Limitations in this release¶

• Networking is available to FreeRTOS applications only. Under Zephyr there is no Ethernet driver and no ipronet_host; the Zephyr Wi-Fi driver in zephyr/drivers/wifi is the IPRO6S on-chip driver, and IPRO6S is not supported under Zephyr in this release. See Zephyr RTOS.
• ipronet_host supports station mode and a single netif, and does not detect a dead transport: after the card loses power, recover with ipronet_stop() and ipronet_start().
• No high-level HTTP client component and no cellular modem component.
• The ipro7_sdio_wifi README mentions iperf; the component it relies on is not in the package.
• ipro_agora_sentino connects to MQTT over plain TCP; for products, use MQTT over TLS with certificate verification.

Reference applications¶

Other boards: ipro7_sdio_wifi is the stand-alone ipronet_host reference with every bring-up stage as a shell command, and ipro7_demo carries the EMAC demo; both are configured for the IPRO7 EVB.

• Wi-Fi and RTSP tutorial: the Reef walk-through with a video player.
• IPRO7AI Reef EVK: the microSD socket, JP3 and the FIN card.
• OTA Updates: updating the FIN card with ipro6s_ota.
• Thread & Matter: IEEE 802.15.4 and OpenThread under Zephyr.