Synergy Software Package User's Manual
NetX/NetX Duo Auto IP

Table of Contents

NetX/NetX Duo Auto IP Introduction

The Auto IP Protocol is designed to dynamically configure IPv4 addresses on a local network without requiring a server, unlike the Dynamic Host Configuration Protocol (DHCP). The Auto IP uses address resolution protocol (ARP) for automatic IP address assignment and allocates addresses in the range of 169.254.1.0 through 169.254.254.255.

Note
Except for internal processing, the NetX Duo™ Auto IP module is identical in the application, set-up and running of an Auto IP session as the NetX™ Auto IP module.

NetX/NetX Duo Auto IP Module Features

  • Compliant with RFC3927 and related RFCs
  • Uses ARP probes to check for address conflicts
  • Uses the collision handler notification in NetX to detect an address already in use
  • Registers a valid Auto IP address with the IP instance
  • Provides high-level APIs for:
    • Creating and deleting an Auto IP instance
    • Starting and stopping the Auto IP thread task
    • Specifying the network interface on which to run Auto IP
NetX_Auto_IP_BD.png
NetX/NetX Duo Auto IP Module Block Diagram
Note
In the figure above, the NetX (or NetX Duo) Network Driver modules has multiple implementation options available. See the description just after the module stack figure in Including the NetX/NetX Duo Auto IP Module in an Application for additional details.

NetX/NetX Duo Auto IP Module APIs Overview

The NetX Auto IP defines APIs for creating, deleting, getting and setting addresses. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

NetX/NetX Duo Auto IP Module API Summary

Function Name Example API Call and Description
nx_auto_ip_create nx_auto_ip_create(&g_auto_ip0, "AutoIP 0", &g_ip0, stack_pointer, stack_size, priority);
Create an Auto IP instance.
nx_auto_ip_delete nx_auto_ip_delete(&g_auto_ip_0);
Delete Auto IP instance.
nx_auto_ip_get_address nx_auto_ip_get_address(&g_auto_ip_0, &local_address);
Get current Auto IP address.
nx_auto_ip_set_interface nx_auto_ip_set_interface(&g_auto_ip_0, interface_index);
Set network interface needing an Auto IP address.
nx_auto_ip_start nx_auto_ip_start(&g_auto_ip_0, IP_ADDRESS(0,0,0,0));
Start Auto IP processing. If the address input is NULL. NetX Auto IP randomly assigns an address in the Auto IP address range.
nx_auto_ip_stop nx_auto_ip_stop(&g_auto_ip_0);
Stop Auto IP processing.
nx_dhcp_server_stop nx_dhcp_server_stop(&dhcp_server);
Stop DHCP server processing.
Note
For details on operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the associated Azure RTOS User's Manual in the References section.

Status Return Values

Name Description
NX_SUCCESS Successful AutoIP function.
NX_AUTO_IP_ERROR Error creating components of Auto IP instance.
NX_PTR_ERROR* Invalid pointer input.
NX_CALLER_ERROR* Invalid caller of this service.
NX_AUTO_IP_NO_LOCAL No Auto IP address registered with the NetX IP instance.
NX_AUTO_IP_BAD_INTERFACE_INDEX Invalid network interface.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.
  • These are error codes which are only returned if error checking is enabled. Refer to the NetX User Guide for the Renesas Synergy™ Platform or NetX Duo User's Guide for the Renesas Synergy™ Platform for more details on error-checking services in NetX and NetX Duo, respectively.

NetX/NetX Duo Auto IP Module Operational Overview

The NetX Auto IP protocol first selects a random address within the Auto IP IPv4 address range of 169.254.1.0 through 169.254.254.255. Alternatively, the application may force a starting IP address by providing it to the nx_auto_ip_startservice; this is useful in situations where an Auto IP address has been used previously.

Once an auto IP address is selected, the NetX Auto IP sends out a series of ARP probes for the selected address. An ARP probe consists of an ARP request message with the sender address set to 0.0.0.0 and the target address set to the desired Auto IP address. A series of these ARP probes are sent (the actual number is set by the ARP probes to send property of the NetX Auto IP instance); if another network node responds to this probe or sends an identical probe for the same address, a new auto IP address is randomly selected within the auto IP IPv4 address range and the probe processing repeats.

If ARP probes to send and probes are sent without any responses, the NetX Auto IP issues many ARP announcements (set by the Number of ARP announces property) for the selected address. An ARP announcement consists of an ARP request message with both the sender and target address in the ARP message set to the selected auto IP address. If another network node responds to an announced message or sends an identical announcement for the same address, a new auto IP address is randomly selected within the auto IP IPv4 address range, and the probe processing starts over. When the probe and announcement completes without any detected conflicts, the selected auto IP address is considered valid and the address is registered with the IP instance.

The NetX Auto IP registers the auto IP-generated IP address with the NetX IP instance successful probe and announcement processing. The Auto IP application can be notified of address changes using the nx_ip_address_change_notify callback in NetX, or it can use the nx_ip_status_check to determine when a valid IP address is assigned. Once a valid address is assigned, the application should stop the auto IP task using the nx_auto_ip_stop service. The address change callback notifies the application of address changes after the auto IP thread task is suspended. Possible reasons for an address changing without explicitly being done with an auto IP may be due to auto IP-address conflicts with other nodes, or a DHCP address resolution to replace the auto IP address.

NetX/NetX Duo Auto IP Module Important Operational Notes and Limitations

NetX/NetX Duo Auto IP Module Operational Notes

  • The NetX DHCP Client and NetX Auto IP can both be used to ensure a host has a valid IP address. Typically, the DHCP Client attempts to contact a server. If none of the servers responds to the DHCP Client, the client is suspended and the auto IP task is started. Auto IP generally guarantees a local address even if no DHCP Server is available. The DHCP Client can try later to broadcast requests to a DHCP Server; this process, if successful, automatically overwrites the auto IP local address.
  • When the IP address changes, the application is responsible for closing out existing socket connections.

NetX/NetX Duo Auto IP Module Limitations

  • If the NetX DHCP is used with the auto IP, the DHCP thread created must have a higher priority than the auto IP thread.
  • The NetX Auto IP does not provide a mechanism to retain previously used IP address.
  • Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the NetX/NetX Duo Auto IP Module in an Application

This section describes how to include either or both NetX/NetX Duo Auto IP module in an application using the SSP configurator.

Note
It is assumed you are familiar with creating a project, adding threads, adding a stack to a thread, and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the NetX/NetX Duo Auto IP module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

NetX/NetX Duo Auto IP Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_auto_ip0 NetX Auto IP Threads New Stack> X-Ware> NetX> Protocols> NetX Auto IP
g_auto_ip0 NetX Duo Auto IP Threads New Stack> X-Ware> NetX Duo> Protocols> NetX Duo Auto IP

When the NetX/NetX Duo Auto IP module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

 

NetX_Auto_IP_MS.png
NetX/NetX Duo Auto IP Module Stack

In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:

  • NetX Duo Port using PPP on nxd_ppp
  • NetX Port ETHER on sf_el_nx
  • NetX Port using Cellular Framework on sf_cellular_nsal_nx
  • NetX Port using PPP on nx_ppp
  • NetX Port using Wi-Fi Framework on sf_wifi_nsal_nx

Configuring the NetX/NetX Duo Auto IP Module

The NetX/NetX Duo Auto IP module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table values. This helps to orient you and can be a useful hands-on approach to learning the ins and outs of developing with SSP.

Configuration Settings for the NetX/NetX Duo Auto IP Module

ISDE Property Value Description
Wait before sending first probe (seconds) 1 Wait before sending first probe selection.
ARP probes to send 3 ARP probes to send selection.
Minimum wait between probes (seconds) 1 Minimum wait between probes selection.
Maximum wait between probes (seconds) 2 Maximum wait between probes selection.
Maximum conflicts before increasing processing delay 10 Maximum conflicts before increasing processing delay selection.
Wait extend after maximum conflicts (seconds) 60 Wait extend after maximum conflicts selection.
Wait before announcement (seconds) 2 Wait before announcement selection.
Number of ARP announces 2 Number of ARP announces selection.
Wait between announces (seconds) 2 Wait between announces selection.
Wait between defense announces (seconds) 10 Wait between defense announces selection.
Name g_auto_ip0 Module name.
Internal thread stack size (bytes) 2048 Internal thread stack size selection.
Internal thread priority 3 Internal thread priority selection.
Name of generated initialization function auto_ip_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

In some cases, settings other than the defaults for stack modules can be desirable. For example, it might be useful to select different addresses for the Ethernet port. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference. 

Note
  Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.

Configuration Settings for the NetX/NetX Duo Auto IP Lower-Level Modules

Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:

Configuration Settings for the NetX/NetX Duo IP Instance

ISDE Property Value Description
Name g_ip0 Module name.
IPv4 Address (use commas for separation) 0,0,0,0 IPv4 Address selection.
Subnet Mask (use commas for separation) 255,255,255,0 Subnet Mask selection.
**IPv6 Global Address (use commas for separation) 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 IPv6 global address selection.
**IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 IPv6 link local address selection.
IP Helper Thread Stack Size (bytes) 2048 IP Helper Thread Stack Size (bytes) selection.
IP Helper Thread Priority 3 IP Helper Thread Priority selection.
ARP Enable ARP selection.
ARP Cache Size in Bytes 512 ARP Cache Size in Bytes selection.
Reverse ARP Enable, Disable

Default: Disable 		Reverse ARP selection.
TCP Enable, Disable

Default: Enable 		TCP selection.
UDP Enable, Disable

Default: Enable 		UDP selection.
ICMP Enable, Disable

Default: Enable 		ICMP selection.
IGMP Enable, Disable

Default: Enable 		IGMP selection.
IP fragmentation Enable, Disable

Default: Disable 		IP fragmentation selection.
Name of generated initialization function ip_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

** Indicates properties that are only available in NetX Duo.

Configuration Settings for the NetX/NetX Duo Common Instance

ISDE Property Value Description
Name of generated initialization function nx_common_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the NetX/NetX Duo Packet Pool Instance

ISDE Property Value Description
Name g_packet_pool0 Module name.
Packet Size in Bytes 640 Packet size selection.
Number of Packets in Pool 16 Number of packets in pool selection.
Name of generated initialization function packet_pool_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the S7G2 Synergy MCU Group. Other MCUs may have different default values and available configuration settings.

NetX/NetX Duo Auto IP Module Clock Configuration

The ETHERC peripheral module uses PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator clock tab prior to a build, or by using the CGC interface at run-time.

NetX/NetX Duo Auto IP Module Pin Configuration

The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.

Note
The selected operation mode determines the peripheral signals available and the MCU pins required.

Pin Selection for the ETHERC Module

Resource ISDE Tab Pin selection Sequence
ETHERC Pins Select Peripherals> Connectivity:ETHERC> ETHERC1.RMII
Note
The selection sequence assumes ETHERC1 is the desired hardware target for the driver.

Pin Configuration Settings for the ETHERC1

Property Value Description
Operation Mode Disabled, Custom, RMII

Default: Disabled 		Select RMII as the Operation Mode for ETHERC1.
Pin Group Selection Mixed, _A only

Default: _A only 		Pin group selection.
REF50CK P701 REF50CK pin.
TXD0 P700 TXD0 pin.
TXD1 P406 TXD1 pin.
TXD_EN P405 TXD_EN pin.
RXD0 P702 RXD0 pin.
RXD1 P703 RXD1 pin.
RX_ER P704 RX_ER pin.
CRS_DV P705 CRS_DV pin.
MDC P403 MDC pin.
MDIO P404 MDIO pin.
Note
The example settings are for a project using the S7G2 Synergy MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

Using the NetX/NetX Duo Auto IP Module in an Application

In a typical application, it is assumed that an IP instance has been created and an ARP is enabled. Once this IP instance is accomplished, the typical steps in using the NetX Auto IP in an application are:

  1. Allow time for the IP thread task and the network driver to get initialized (2-3 seconds) using the tx_thread_sleep API.
  2. Set the address change notification with the nx_ip_address_change_notify API [Optional].
  3. Start the Auto IP instance with the nx_auto_ip_start API.
  4. Check for a valid address for the IP instance using either the nx_ip_status_check or nx_auto_ip_get_address API. The nx_ip_status_check API defaults to the primary address. If running Auto IP on a secondary interface, use the nx_ip_interface_status_check. Note that nx_auto_ip_get_address API works for Auto IP on either primary or secondary addresses.
  5. If a valid local IP address is assigned, stop the auto IP thread task using the nx_auto_ip_stop API.

The following figure illustrates common steps in a typical operational flow diagram:

NetX_Auto_IP_TA.png
Flow Diagram of a Typical NetX/NetX Duo Auto IP Module Application