NetX Port Using PPP

Table of Contents

• NetX Port Using PPP Module Introduction
  • NetX Port Using PPP Module Features
• NetX Port Using PPP Module APIs Overview
• NetX Port Using PPP Module Operational Overview
  • NetX Port Using PPP Module Important Operational Notes and Limitations
    • NetX Port Using PPP Module Operational Notes
    • NetX Port Using PPP Module Limitations
• Including the NetX Port Using PPP Module in an Application
• Configuring the NetX Port Using PPP Module
  • Configuration Settings for the NetX Port Using PPP Lower-Level Modules
• Using the NetX Port Using PPP Module in an Application

NetX Port Using PPP Module Introduction

The Azure RTOS NetX Port PPP module (nx_ppp) for NetX and NetX Duo is integrated into the SSP. Its function is to interface the NetX and NetX Duo software with the Synergy hardware. Point-to-Point Protocol (PPP) is a data link layer (layer 2) communication between two directly connected (point to point) devices. It can provide data transmission, authentication, and encryption functionality.

NetX Port Using PPP Module Features

• High-level interface for NetX and NetX Duo for the Renesas Synergy^TM Platform
• CHAP authentication support
• PAP authentication support
• IPCP response support
• Handler provided for invalid packets

NetX Port Using PPP Module Block Diagram

NetX Port Using PPP Module APIs Overview

The NetX Port using PPP Module defines APIs for creating, authentication and assigns 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 Port using PPP Module API Summary

Function Name	Example API Call and Description
nx_ppp_create	nx_ppp_create(&ppp_ptr, name, &ip_ptr, stack_memory_ptr, stack_size, thread_priority, &pool_ptr, ppp_non_ppp_packet_handler, ppp_byte_send); Creates PPP instance for given IP instance.
nx_ppp_dns_address_set	nx_ppp_dns_address_set(&ppp_ptr,& dns_address); Sets the primary DNS address for the PPP device.
nx_ppp_secondary_dns_address_set	nx_ppp_secondary_dns_address_set(&ppp_ptr, &secondary_dns_address); Sets secondary DNS address for the PPP device.
nx_ppp_ip_address_assign	nx_ppp_ip_address_assign(&ppp_ptr, local_ip_address, peer_ip_address); Assigns Local and Peer IP address.
nx_ppp_link_down_notify	nx_ppp_link_down_notify(&ppp_ instance, link_down_callback); Registers a callback for link down event.
nx_ppp_link_up_notify	nx_ppp_link_up_notify(&ppp_instance, link_up_callback); Registers a callback for link up event.
nx_ppp_nak_authentication_notify	nx_ppp_nak_authentication_notify(&ppp_ptr, nak_auth_callback); Registers a callback for authentication NAK received from peer.
nx_ppp_chap_enable	nx_ppp_chap_enable(&ppp_instance, get_challenge_values, get_responder_values, get_verification_values); Enables CHAP authentication for given PPP instance.
nx_ppp_pap_enable	nx_ppp_pap_enable(&ppp_instance, generate_login, verify_login); Enables PAP authentication for given PPP instance.

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	Valid PPP pointer.
NX_PTR_ERROR	Invalid pointer input.
NX_CALLER_ERROR	Invalid caller of this service.
NX_NOT_IMPLEMENTED	PAP logic was disabled via NX_PPP_DISABLE_PAP. CHAP logic was disabled via NX_PPP_DISABLE_CHAP.

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 Port Using PPP Module Operational Overview

The NetX PPP package requires the application to provide a serial communication driver. The driver must support 8-bit characters and may also employ software flow control. It is the application’s responsibility to initialize the driver, which should be done prior to creating the PPP instance. In order to send PPP packets, a serial driver output byte routine must be provided to PPP (specified in the nx_ppp_create function). This serial driver byte output routine will be called repetitively in order to transmit the entire PPP packet. It is the serial driver’s responsibility to buffer the output. On the receive side, the application’s serial driver must call the PPP nx_ppp_byte_receive function whenever a new byte arrives. This is typically done from within the context of an Interrupt Service Routine(ISR). The nx_ppp_byte_receive function places the incoming byte into a circular buffer and alerts the PPP receive thread of its presence.

NetX Port Using PPP Module Important Operational Notes and Limitations

NetX Port Using PPP Module Operational Notes

If a modem is required for connection to the internet, some special considerations are required in order to use PPP. Basically, using a modem introduces additional initialization logic and logic for loss of communication. In addition, most of the additional modem logic is done outside the context of NetX PPP. The basic flow of using the NetX PPP with a modem is:

1. Initialize the Modem
2. Dial Internet Service Provider (ISP)
3. Wait for Connection
4. Wait for UserID Prompt
5. Start NetX PPP [PPP in operation]
6. Loss of Communication
7. Stop NetX PPP (or restart via nx_ppp_restart)

Additional Information

Refer to the NetX User Guide for the Renesas Synergy™ Platform and NetX Duo User Guide for the Renesas Synergy™ Platform for additional operational details.

NetX Port Using PPP Module Limitations

• No PPP Client XML support as it may not be useful.
• Current XML supports only PPP and not PPPoE.
• sf_comms_telnet, sf_ux_comms_v2 are not supported.

Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the NetX Port Using PPP Module in an Application

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

Note

This section assumes 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 Port using PPP module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

The NetX Port using PPP Framework is used as a lower level module and is not available to add as a separate stack. An example is illustrated in the following figure where a module must be selected to Add NetX Network Driver. The following figure shows the selection of the NetX Port using PPP Framework to complete the stack for the module.

NetX/NetX Duo Port Using PPP Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_nx_ppp0 NetX Port on nx_ppp	Threads	New Stack> X-Ware> NetX> NetX IP Instance
g_nxd_ppp0 NetX Duo Port on nxd_ppp	Threads	New Stack> X-Ware> NetX Duo> NetX Duo Instance

NetX Port Using PPP Module Stack

Configuring the NetX Port Using PPP Module

The NetX Port using PPP Module must be configured by the user for the desired operation. 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. 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 settings. This will help 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 Port using PPP Module

ISDE Property	Value	Description
CHAP authentication support	Enable, Disable Default: Enable	CHAP authentication selection.
PAP authentication support	Enable, Disable Default: Enable	PAP authentication selection.
DNS Option in IPCP response support	Enable, Disable Default: Enable	IPCP response selection.
Maximum DNS address request retires from the peer	2	Specifies the maximum number of DNS address request retries from the peer.
Data packet allocation timeout (seconds)	4	Timeout for data packet allocation.
Retry interval (seconds)	1	Specifies interval in seconds to wait before processing.
Maximum retries for reallocating packet	4	Specifies the maximum number of retries for reallocating packet.
Maximum retries for protocol request response	4	Specifies the maximum number of retries for protocol request response.
Maximum retries for LCP configure request	20	Specifies the maximum number of retries for LCP configure request.
Maximum retries for PAP authentication request	20	Specifies the maximum number of retries for  PAP configure request.
Maximum retries for CHAP challenge message	20	Specifies the maximum number of retries for CHAP challenge message.
Maximum retries for IPCP configure request	20	Specifies the maximum number of retries for IPCP configure request.
Name	g_nx_ppp0	Name of PPP instance.
Internal thread  priority	2	Internal thread priority selection.
Internal thread stack size (bytes)	2048	Thread Stack Size(bytes) selection.
Read thread priority	10	Thread Priority selection.
Peer IPV4 Address	192.168.0.111	IPv4 Address selection.
Name of invalid packet handler function	invalid_packet_handler	Name of invalid packet handler function selection.
Name of generated initialization function	nx_ppp_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.

Configuration Settings for the NetX Port Using PPP 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
Default Gateway Address (use commas for separation)	0,0,0,0	Default gateway address 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
Link status change callback	NULL	Link status change callback 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		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.

Configuration Settings for the UART Communications Framework Module on sf_uart_comms

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if parameter checking is included.
Read Input Queue Size (4-Byte Words)	15	Buffer size for data reception queue. sf_uart_comms utilizes the ThreadX Queue for the queue management.
Name	g_sf_comms0	Name of UART communications framework module.
Name of generated initialization function	sf_comms_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 UART HAL Module on r_sci_uart

ISDE Property	Value	Description
External RTS Operation	Enable, Disable Default: Disable	Enable an IOPORT pin to be used as RTS signal. For RTS functionality set this configuration parameter to Enable and specify the configuration Name of UART callback function for the RTS external pin control.
Reception	Enable, Disable Default: Enable	Enable or disable UART reception for all UART channels on SCI. Setting this configuration parameter to Disable reduces code size because the portion of code for UART reception is not compiled. You cannot set this parameter for individual UART channels.
Transmission	Enable, Disable Default: Enable	Enable or disable UART transmission for all UART channels on SCI. Setting Disable to this configuration allows to get smaller code size due to the portion of code for UART transmission is compiled out, however, you can only set Disable to this configuration if any other SCI channels which work as UART ports do not perform the transmission.
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_uart0	The name to be used for UART on SCI module control block instance. This name is also used as the prefix of the other variable instances.
Channel	0	SCI channel number.
Baud Rate	9600	Baud rate selection.
Data Bits	7 bits, 8, bits, 9 bits Default: 8 bits	UART data bits.
Parity	None, Odd, Even Default: None	UART parity bits.
Stop Bits	1 bit, 2 bits Default: 1 bit	UART stop bits.
CTS/RTS Selection	CTS (Note that RTS is available when enabling External RTS Operation mode which uses 1 GPIO pin), RTS (CTS is disabled) Default: RTS (CTS is disabled)	Select CTS or RTS for the CTSn/RTSn pin of SCI channel n. The SCI hardware supports either the CTS or the RTS control signal on this pin but not both. For an application that uses both CTS and RTS, select CTS for this configuration parameter and enable the configuration External RTS Operation specifying the configuration Name of UART callback function for the RTS external pin control.
Name of UART callback function to be defined by user	NULL	Name must be a valid C symbol.
Name of UART callback function for the RTS external pin control to be defined by user	NULL	Name must be a valid C symbol.
Clock Source	Internal Clock, External Clock 8x baudrate, External Clock 16x baudrate Default: Internal Clock	Selection of the clock source to be used in the baud-rate clock generator block.
Baudrate Clock Output from SCK pin	Enable, Disable Defaualt: Disable	Optional setting to output the baud-rate clock on the SCKn pin for the selected channel n.
Start bit detection	Fallling Edge, Low Level Default: Falling Edge	Start bit detection mode in the reception; usually set Falling Edge to this configuration.
Noise Cancel	Enable, Disable Defaualt: Disable	Enable the digital noise cancellation on RXDn pin. The digital noise filter block in SCI consists of two-stage flip-flop circuits. For detail, refer to the Noise cancellation section in the Renesas SynergyTM hardware manual.
Bit Rate Modulation Enable	Enable, Disable Defaualt: Enable	Bit rate modulation enable selection.
Receive FIFO Trigger Level	One, Max Default: Max	Receive FIFO trigger level selection.
Receive Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Receive interrupt priority selection.
Transmit Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit interrupt priority selecition.
Transmit End Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Transmit end interrupt priority selection.
Error Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	Error interrupt priority selection.
Baud rate Percent Error	Value must be greater than 0.0 and less than 15.0   Default; 2.0	Maximum baudrate percent error allowed in order for the module to function.
UART Communication Mode	RS232, RS485   Default: RS232	UART communication mode selection, usually it is RS232 mode.
.UART RS485 Communication Mode	Half Duplex, Full Duplex   Default: Half duplex	UART RS485 communication mode selection as half duplex or full duplex.
RS485 DE Port	00 to 11   Default: 09	Select the port number of Driver Enable pin.
RS485 DE Pin	00 to 15   Default: 14	Select the pin number of Driver Enable pin.

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 Transfer Driver on r_dtc Event SCI0 TXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Software Start	Enabled, Disabled Defaualt: Disabled	Software start selection.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Linker section to keep DTC vector table.
Name	g_transfer0	Module name.
Mode	Normal	Mode selection.
Transfer Size	1 Byte	Transfer size selection.
Destination Address Mode	Fixed	Destination address mode selection.
Source Address Mode	Incremented	Source address mode selection.
Repeat Area (Unused in Normal Mode	Source	Repeat area selection.
Interrupt Frequency	After all transfers have completed	Interrupt frequency selection.
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	0	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection.
Activation Source (Must enable IRQ)	Event SCI0 TXI	Activation source selection.
Auto Enable	FALSE	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	ELC Software Event interrupt priority 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 Transfer Driver on r_dtc Event SCI0 RXI

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Name	g_transfer1	Module name.
Mode	Normal	Mode selection.
Transfer Size	1 Byte	Transfer size selection.
Destination Address Mode	Incremented	Destination address mode selection.
Source Address Mode	Fixed	Source address mode selection.
Repeat Area (Unused in Normal Mode	Destination	Repeat area selection.
Interrupt Frequency	After all transfers have completed	Interrupt frequency selection.
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	0	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection.
Activation Source (Must enable IRQ)	Event SPI0 RXI	Activation source selection.
Auto Enable	FALSE	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	ELC Software Event interrupt priority 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.

Using the NetX Port Using PPP Module in an Application

The steps in using the NetX/NetX Duo Port using PPP module in a typical application are:

Auto Generated code to initialize NetX and NetX Duo Port using PPP in the Application (common_data.c)

• Create Packet pool using the nx_packet_pool_create API
• Create PPP using nx_ppp_create API
• Define IP address using the nx_ppp_ip_address_assign API
• Create IP instance using nx_ip_create() API
• Enable ARP using the nx_arp_enable API
• Enable TCP using the nx_tcp_enable API
• Enable UDP using the nx_udp_enable API
• Enable ICMP using the nx_icmp_enable API
• Enable IGMP using the nx_igmp_enable API

User Application Code (<thread>_entry.c)

• Call Link-up callback nx_ppp_link_up_notify() function (optional)
• Call Link-down callback nx_ppp_link_down_notify() (optional)
• Enable PAP using nx_ppp_pap_enable() API (optional) 
• Wait for IP status check using nx_ip_status_check().
• Check IP and new mask assigned using nx_ip_interface_address_get().
• Wait till link is established using nx_ppp_status_get().
• Ping the client IP address to check the PPP connection using nx_icmp_ping().