Renesas NetX, NetX Duo Application Note
Application Note
Renesas Synergy™ Platform
NetX™ and NetX Duo™ Auto IP Module Guide
Introduction
This module guide will enable you to effectively use a module with your own design. Upon completion of this
guide, you will be able to add this module to your own design, configure it correctly for the target application,
and write code using the included application project code as a reference and efficient starting point.
References to more detailed API descriptions and suggestions of other application projects that illustrate
advanced uses of the module are available on the Renesas Syner g y Knowledg e Bas e (see the References
section at end of the document), it is a valuable resources for creating more complex designs.
The Auto IP Protocol is design ed to dynamically configure IPv4 addresses on a local network without
requiring a server; unlike the Dynamic Host Configuration Protocol (DHCP). 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
running of an Auto IP session as the NetX
Contents
1. NetX and NetX Duo Auto IP Module Features ......................................................................... 2
Auto IP is identical in the application, set-up, and
™
Auto IP.
2. NetX and NetX Duo Auto IP Module APIs Overview ................................................................ 2
3. NetX and NetX Duo Auto IP Module Operational Overview ..................................................... 3
3.1 NetX and NetX Duo Auto IP Module Important Operational Notes and Limitations ............................... 4
3.1.1 NetX and NetX Duo Auto IP Module Operational Notes ....................................................................... 4
3.1.2 NetX and NetX Duo Auto IP Module Limitations ................................................................................... 4
4. Including the NetX and NetX Duo Auto IP Module in an Application ........................................ 4
5. Configuring the NetX and NetX Duo Auto IP Module ............................................................... 5
5.1 Configuration Settings for the NetX and NetX Duo Auto IP Lower-Level Modules ................................. 6
5.2 NetX and NetX Duo Auto IP Module Clock Configuration ...................................................................... 8
5.3 NetX and NetX Duo Auto IP Module Pin Configuration .......................................................................... 8
6. Using the NetX and NetX Duo Auto IP Module in an Application ............................................. 8
7. The NetX and NetX Duo Auto IP Module Application Project ................................................... 9
8. Customizing the NetX and NetX Duo Auto IP Module for a Target Application ...................... 13
9. Running the NetX and NetX Duo Auto IP Module Application Project .................................... 13
10. NetX and NetX Duo Auto IP Module Conclusion .................................................................... 15
11. NetX and NetX Duo Auto IP Module Next Steps .................................................................... 15
12. NetX and NetX Duo Auto IP Module Reference Information .................................................. 16
Revision History ............................................................................................................................ 18
R11AN0135EU0102 Rev.1.02 Page 1 of 18
May.02.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ Auto IP Module Guide
Function Name
Example API Call and Description
nx_auto_ip_create
nx_auto_ip_create(&g_auto_ip0, "AutoIP 0", &g_ip0,
Create an Auto IP instance
1. NetX and 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
Figure 1. NetX and NetX Duo Auto IP Module Block Diagram
2. NetX and NetX Duo Auto IP Module APIs Overview
The NetX Auto IP def ines APIs for creating, deleting, getting, and s etting addresses. A c omplete 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.
Table 1. NetX and NetX Duo Auto IP Module API Summary
stack_pointer, stack_size, priority);
R11AN0135EU0102 Rev.1.02 Page 2 of 18
May.02.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ Auto IP Module Guide
Function Name
Example API Call and Description
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));
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);
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
Start Auto IP processing. If the address input is NULL. NetX Auto IP randomly
assigns an address in the Auto IP address range.
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 Express Logic User’s Manual in the
References section.
Table 2. Status Return Values
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.
3. NetX and 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_start service; 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
R11AN0135EU0102 Rev.1.02 Page 3 of 18
May.02.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ Auto IP Module Guide
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
within the auto IP IPv4 addr es s range, and the probe processing starts over. When the probe, and the
announcement, com pletes with out any detected conflicts, the selected auto IP address is considered valid
and the address is registered with the IP inst a nce.
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.
3.1 NetX and NetX Duo Auto IP Module Important Operational Notes and Limitations
3.1.1 NetX and 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 respond 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.
3.1.2 NetX and 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.
4. Including the NetX and NetX Duo Auto IP Module in an Application
This section describes how to include either or both NetX and 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 Us er ’s Manual to learn how to manage each of these important steps in creating
To add the NetX and NetX Duo Auto IP module to an application, simply add it to a thread using the stacks
selection sequence given in the following table. (The default name for the NetX and NetX Duo Auto IP
module is g_auto_ip0. This name can be changed in the associated Properties window.)
Table 3. NetX and NetX Duo Auto IP Module Selection Sequence
As shown in the following figure, when the NetX Auto IP module is added to the thread stack, the
configurator automatically adds any needed lower-level modules. Any modules needing additional
configuration inform ation have the box text highlighted in Red. Modul es 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.
SSP-based applications.
R11AN0135EU0102 Rev.1.02 Page 4 of 18
May.02.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ Auto IP Module Guide
Parameter
Value
Description
Wait before sending first probe
(seconds)
1
Wait before sending first probe selection
Clicking on any Pink banded modules brings up the New icon and displays possible choices.
Figure 2. NetX and NetX Duo Auto IP Module Stack
5. Configuring the NetX and Ne tX Duo Auto IP Module
The NetX 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.
One of the properties most often identified as requiring a change is the interrupt priority; this configuration
setting is available within the Properties window of the associated module. Simply select the indicated
module and then view the Properties window; the interrupt settings are often toward the bottom of the
properties list, so scroll down until they become available. Also note that the interrupt priorities listed in the
Properties win do w in the ISDE indicates the validity of the setting based on the targeted MCU (CM4 or
CM0+). This level of detail is not included in the following configuration properties tables but is easily visible
with the ISDE when configuring interru pt -priority levels.
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
Table 4. Configuration Settings for the NetX and NetX Duo Auto IP Module
hands-on approach to learning the ins and outs of developing with SSP.
R11AN0135EU0102 Rev.1.02 Page 5 of 18
May.02.19
Renesas Synergy™ Platform NetX™ and NetX Duo™ Auto IP Module Guide
Parameter
Value
Description
ARP probes to send
3
ARP probes to send selection
Minimum wait between probes
1
Minimum wait between probes selection. (The
probes.)
Maximum wait between probes
(seconds)
2
Maximum wait between probes selection
Maximum conflicts before increasing
10
Maximum conflicts before increasing processing
address.
Wait extend after maximum conflicts
60
Interval that Auto IP waits before trying another
reached.
Wait before announcement (seconds)
2
Wait before announcement if the local IP
address being probed results in zero conflicts.
Number of ARP announces
2
Number of ARP announcements sent 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
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
zeros use the MAC address)
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
520
ARP Cache Size in Bytes selection
(seconds)
processing delay
(seconds)
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.
Auto IP recommends a random delay between
delay before Auto IP tries another local IP
local address after the maximum conflicts is
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.
5.1 Configuration Settings for the NetX and 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 al l th e settings within the properties section for the module.
Table 5. Configuration Settings for the NetX and NetX Duo IP Instance
commas for separation. When All
0x0, 0x0, 0x0
R11AN0135EU0102 Rev.1.02 Page 6 of 18
May.02.19
Loading...