lwIP stack on nRF5

Table of Contents

• lwIP stack driver
• lwIP version and reference

This information applies to the following SoftDevice: S132

Nordic's IoT solution aims at ensuring that any embedded IPv6 stack can be used with its 6LoWPAN solution. Therefore, the solution has been designed in a way that makes it easy to port a third-party stack to nRF5, if required.

Note that only embedded stacks that implement IPv6 hosts can be considered for porting. IPv4 only stacks cannot be used for this purpose.

To showcase the ability to run third-party stacks, lwIP (lightweight IP), an open source embedded TCP/IP stack, has been ported to nRF5. See savannah.nongnu.org/projects/lwip for detailed information about lwIP.

The lwIP stack can be configured and fine-tuned based on the platform. The nRF5 port of lwIP is configured with a NO_SYS define, which means that the stack is run without an operating system. See the header files <InstallFolder>external/lwip/src/port/arch/lwipopts.h and <InstallFolder>external/lwip/src/port/arch/cc.h for details of the lwIP configuration.

lwIP stack driver

The lwIP stack driver implements functions for adding or deleting a network interface and sending and receiving data on it. The driver interfaces with the BLE 6LoWPAN library and translates calls to add or delete an interface on BLE 6LoWPAN to add and delete operations for a network interface. The driver also ensures that the correct IPv6 link-local address is provided to the lwIP stack, to create auto-configured IPv6 addresses when prefixes are advertised by the router.

The diagram below depicts the stack structure of the lwIP stack on nRF5.

Figure 2: lwIP on nRF5.

The lwIP stack is configured to use the memory management functions implemented in the memory manager library. The driver provides wrapper functions over the Memory Manager API to interface with the lwIP stack. Therefore, the Memory Manager library must be initialized before the lwIP stack.

In addition, the lwIP driver provides the sys_now function that is needed to maintain lwIP time-outs. The function is implemented to use the RTC1 counter, which is also used by the timer library of the SDK. Therefore, the timer module must be initialized before the lwIP stack. lwIP stack expects the ticks to be in milliseconds. Therefore, the driver defines the PRESCALER value to be used for the timer module. All applications using lwIP should use this PRESCALER value defined by the driver.

lwIP requires regular servicing of the stack to check out time-outs. The lwIP stack expects the sys_check_timeouts API to be called at least every 250 ms. This periodic timer is not implemented in the driver. However, all example applications for lwIP that are included in this SDK implement this timer, servicing lwIP time-outs every 100 ms.

On initialization, the driver registers a callback with the Nordic BLE 6LoWPAN library. When receiving a BLE_6LO_EVT_INTERFACE_ADD event, the driver registers a network interface with the lwIP. This network interface is added as a point-to-point interface with the IPv6 link-local address generated from the EUI-64 IID (which is assumed to be correctly initialized by the application based on the Bluetooth device address). The network interface is configured to use address auto-configuration to automatically create global addresses based on the prefix that is distributed by the router, appended with the EUI-64 IID of the network interface (see Creating link-local IPv6 addresses). The lwIP is also configured to send periodic neighbor solicitation messages and perform duplicate address detection.

The added lwIP network interface implements the output_ip6 routine and maps data transmissions initiated by the stack to ble_6lowpan_interface_send. When receiving a notification of an IP packet (BLE_6LO_EVT_INTERFACE_DATA_RX) from the BLE 6LoWPAN library, data is submitted to the lwIP stack on the network interface using the ip6_input lwIP API.

The added network interface is removed from lwIP's list of network interfaces when receiving a BLE_6LO_EVT_INTERFACE_DELETE event from the BLE 6LoWPAN library.

Note

lwIP is a dual stack supporting both IPv4 and IPv6. On nRF5, the IPv4 part of the stack is not removed, but it is never used.

The lwIP stack does not permit reaching global addresses without the network interface having a global address. This global address is created after router advertisements are received and the duplicate address detection procedure is complete. This might take a few seconds.

lwIP version and reference

lwIP 2.0.2 is included in the example applications using lwIP. The source uses the tag STABLE-2_0_2_RELEASE_VER tag of lwip repository with modifications in:

• <InstallFolder>external/lwip/src/core/ipv6/nd6.c to relax the check on the on link flag for BLE.
• <InstallFolder>external/lwip/src/include/lwip/ip.h to suppress lint warnings.
• <InstallFolder>external/lwip/src/include/lwip/tcp.h to suppress lint warnings.

The source distributed in the SDK contains these modifications.

The lwIP Git repository is located at git.savannah.gnu.org/cgit/lwip.git.

Note

lwIP uses a modified BSD license. This license does not conflict with the Nordic IoT SDK license. However, it is not identical. Therefore, it is recommended to read and understand the licensing terms of lwIP. See lwip.wikia.com/wiki/License for details. This license is also included in the SDK at <InstallFolder>external/lwip/license.txt.