This chapter contains a description of various issues related to installation, setup, and usage of the NetX Duo Point-to-Point Protocol (PPP) component.
The NetX Duo Point-to-Point Protocol (PPP) package is available at https://github.com/eclipse-threadx/netxduo. The package includes the following files:
In order to use PPP for NetX Duo, the entire distribution mentioned previously should be copied to the same directory where NetX Duo is installed. For example, if NetX Duo is installed in the directory “\threadx\arm7\green” then the nx_ppp.h and nx_ppp.c files should be copied into this directory.
Using PPP for NetX Duo is easy. Basically, the application code must include nx_ppp.h after it includes tx_api.h and nx_api.h, in order to use ThreadX and NetX Duo, respectively. Once nx_ppp.h is included, the application code is then able to make the PPP function calls specified later in this guide. The application must also include nx_ppp.c in the build process. This file must be compiled in the same manner as other application files and its object form must be linked along with the files of the application. This is all that is required to use NetX Duo PPP.
If a modem is required for connection to the internet, some special considerations are required in order to use the NetX Duo PPP product. 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 Duo PPP. The basic flow of using the NetX Duo PPP with a modem goes something like this:
Initialize Modem
Dial Internet Service Provider (ISP)
Wait for Connection
Wait for UserID Prompt
Start NetX Duo PPP [PPP in operation]
Loss of Communication
Stop NetX Duo PPP (or restart via nx_ppp_restart)
Using the application’s low-level serial output routine, the modem is initialized via a series of ASCII character commands (see modem’s documentation for more details).
Using the application’s low-level serial output routine, the modem is instructed to dial the ISP. For example, the following is typical of an ASCII string used to dial an ISP at the number 123-4567:
“ATDT123456\r”
At this point, the application waits to receive indication from the modem that a connection has been established. This is accomplished by looking for characters from the application’s low-level serial input routine. Typically, modems return an ASCII string “CONNECT” when a connection has been established.
Once the connection has been established, the application must now wait for an initial login request from the ISP. This typically takes the form of an ASCII string like “Login?”
At this point, the NetX Duo PPP can be started. This is accomplished by calling the nx_ppp_create service followed by the nx_ip_create service. Additional services to enable PAP and to setup the PPP IP addresses might also be required. Please review the following sections of this guide for more information.
Once PPP is started, any non-PPP information is passed to the “invalid packet handling” routine the application specified to the nx_ppp_create service. Typically, modems send an ASCII string such as “NO CARRIER” when communication is lost with the ISP. When the application receives a non-PPP packet with such information, it should proceed to either stop the NetX Duo PPP instance or to restart the PPP state machine via the nx_ppp_restart API.
Stopping the NetX Duo PPP is fairly straightforward. Basically, all created sockets must be unbound and deleted. Next, delete the IP instance via the nx_ip_delete service. Once the IP instance is deleted, the nx_ppp_delete service should be called to finish the process of stopping PPP. At this point, the application is now able to attempt to reestablish communication with the ISP.
An example that illustrates how easy it is to use NetX Duo PPP is described below. In this example, the PPP include file nx_ppp.h is brought in at line 3. Next, PPP is created in “tx_application_define” at line 56. The PPP control block “my_ppp” was defined as a global variable at line 9 previously.
Note: PPP should be created prior to creating the IP instance. After successful creation of PPP and IP, the thread “my_thread” waits for the PPP link to come alive at line 98. At line 104, both PPP and NetX Duo are fully operational.
The one item not shown in this example is the application’s serial byte receive ISR. It will need to call nx_ppp_byte_receive with “my_ppp” and the byte received as input parameters.
0001 #include "tx_api.h"
0002 #include "nx_api.h"
0003 #include "nx_ppp.h"
0004
#define DEMO_STACK_SIZE 4096
TX_THREAD my_thread;
NX_PACKET_POOL my_pool;
NX_IP my_ip;
NX_PPP my_ppp;
/* Define function prototypes. */
void my_thread_entry(ULONG thread_input);
void my_serial_driver_byte_output(UCHAR byte);
void my_invalid_packet_handler(NX_PACKET *packet_ptr);
/* Define main entry point. */
intmain()
{
/* Enter the ThreadX kernel. */
tx_kernel_enter();
}
/* Define what the initial system looks like. */
void tx_application_define(void *first_unused_memory)
{
CHAR *pointer;
UINT status;
/* Setup the working pointer. */
pointer = (CHAR *) first_unused_memory;
/* Create "my_thread". */
tx_thread_create(&my_thread, "my thread", my_thread_entry, 0,
pointer, DEMO_STACK_SIZE,
2, 2, TX_NO_TIME_SLICE, TX_AUTO_START);
pointer = pointer + DEMO_STACK_SIZE;
/* Initialize the NetX system. */
nx_system_initialize();
/* Create a packet pool. */
status = nx_packet_pool_create(&my_pool, "NetX Main Packet Pool",
1024, pointer, 64000);
pointer = pointer + 64000;
/* Check for pool creation error. */
if (status)
error_counter++;
/* Create a PPP instance. */
status = nx_ppp_create(&my_ppp, "My PPP", &my_ip, pointer, 1024, 2,
&my_pool, my_invalid_packet_handler, my_serial_driver_byte_output);
pointer = pointer + 1024;
/* Check for PPP creation pool. */
if (status)
error_counter++;
/* Create an IP instance with the PPP driver. */
status = nx_ip_create(&my_ip,"My NetX IP Instance",
IP_ADDRESS(216,2,3,1), 0xFFFFFF00, &my_pool,
nx_ppp_driver, pointer, DEMO_STACK_SIZE, 1);
pointer = pointer + DEMO_STACK_SIZE;
/* Check for IP create errors. */
if (status)
error_counter++;
/* Enable ICMP for my IP Instance. */
status = nx_icmp_enable(&my_ip);
/* Check for ICMP enable errors. */
if (status)
error_counter++;
/* Enable UDP. */
status = nx_udp_enable(&my_ip);
if (status)
error_counter++;
}
/* Define my thread. */
void my_thread_entry(ULONG thread_input)
{
UINT status;
ULONG ip_status;
NX_PACKET *my_packet;
/* Wait for the PPP link in my_ip to become enabled. */
status = nx_ip_status_check(&my_ip,NX_IP_LINK_ENABLED,&ip_status,3000);
/* Check for IP status error. */
if (status)
return;
/* Link is fully up and operational. All NetX activities
are now available. */
}
There are several configuration options for building PPP for NetX Duo. The following list describes each in detail: