This chapter contains a description of various issues related to installation, setup, and usage of the NetX Duo Telnet component.
The NetX Duo Telnet package is available at https://github.com/eclipse-threadx/netxduo. The package includes the following files:
In order to use Telnet 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 nxd_telnet_client.h, nxd_telnet_client.c, nxd_telnet_server.c and nxd_telnet_server.h files should be copied into this directory.
Using Telnet for NetX Duo is easy. Basically, the application code must include nxd_telnet_server.h for Telnet Server applications and nxd_telnet_client.h for Telnet Client applications after it includes tx_api.h and nx_api.h, in order to use ThreadX and NetX Duo. Once the header is included, the application code is then able to make the Telnet function calls specified later in this guide. The application must also include nxd_telnet_client.c and nxd_telnet_server.c in the build process. These files 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 Telnet.
If no Telnet Client capabilities are required, the nxd_telnet_client.c file may be omitted.
Note also that because Telnet utilizes NetX Duo TCP services, TCP must be enabled with the nx_tcp_enable call prior to using Telnet.
An example of how to use NetX Duo Telnet is shown below. In this example, the Telnet include files are brought in at line 7 and 8. Next, the Telnet Server is created in “tx_application_define” at line 146. Note that the Telnet Server and Client control blocks are defined as global variables at line 23-24 previously.
Before the Telnet Server or Client can be started they must validate their IP address with NetX Duo. For IPv4 connections this is accomplished by simply waiting briefly to let the NetX Duo driver initialize the system on line 166. For IPv6 connections, this requires enabling IPv6 and ICMPv6 which it does in lines 171-172. The Client sets its global and link local IPv6 addresses on the primary interface on lines 181-186 and waits for NetX Duo validation to complete in the background. The Server also sets its global and link local addresses on its primary interface in lines 192 – 198. Note that the two services, nxd_ipv6_global_address_set and nxd_ipv6_linklocal_address_set are replaced with nxd_ipv6_address_set service. The former two services are still available for legacy NetX applications but are eventually deprecated. Developers are encouraged to use nxd_ipv6_address_set instead.
After successful IP address validation with NetX Duo, the Telnet Server is started at line 215 using the nxd_telnet_server_start service. At line 226 the Telnet Client is created using the nx_telnet_client_create service. It then connects with the Telnet Server on line 242 for IPv4 applications and line 238 for IPv6 applications using the nxd_telnet_client_connect and nx_telnet_client_connect services respectively. After successful validation and connection with the server, it makes a few exchanges before disconnecting.
/* This is a small demo of TELNET on the high-performance NetX Duo TCP/IP stack.
This demo relies on ThreadX and NetX Duo to show a simple TELNET connection,
send, server echo, and then disconnection from the TELNET server. */
#include "tx_api.h"
#include "nx_api.h"
#include "nxd_telnet_client.h"
#include "nxd_telnet_server.h"
#define DEMO_STACK_SIZE 4096
/* Define the ThreadX and NetX object control blocks... */
TX_THREAD test_thread;
NX_PACKET_POOL pool_server;
NX_PACKET_POOL pool_client;
NX_IP ip_server;
NX_IP ip_client;
/* Define TELNET objects. */
NX_TELNET_SERVER my_server;
NX_TELNET_CLIENT my_client;
#ifdef FEATURE_NX_IPV6
/* Define NetX Duo IP address for the NetX Duo Telnet Server and Client. */
NXD_ADDRESS server_ip_address;
NXD_ADDRESS client_ip_address;
#endif
#define SERVER_ADDRESS IP_ADDRESS(1,2,3,4)
#define CLIENT_ADDRESS IP_ADDRESS(1,2,3,5)
/* Define the counters used in the demo application... */
ULONG error_counter;
/* Define timeout in ticks for connecting and sending/receiving data. */
#define TELNET_TIMEOUT 200
/* Define function prototypes. */
void thread_test_entry(ULONG thread_input);
void _nx_ram_network_driver(struct NX_IP_DRIVER_STRUCT *driver_req);
/* Define the application's TELNET Server callback routines. */
void telnet_new_connection(NX_TELNET_SERVER *server_ptr, UINT
logical_connection);
void telnet_receive_data(NX_TELNET_SERVER *server_ptr, UINT logical_connection,
NX_PACKET *packet_ptr);
void telnet_connection_end(NX_TELNET_SERVER *server_ptr, UINT
logical_connection);
/* Define main entry point. */
int main()
{
/* Enter the ThreadX kernel. */
tx_kernel_enter();
}
/* Define what the initial system looks like. */
void tx_application_define(void *first_unused_memory)
{
UINT status;
CHAR *pointer;
UINT iface_index, address_index;
/* Setup the working pointer. */
pointer = (CHAR *) first_unused_memory;
/* Create the main thread. */
tx_thread_create(&test_thread, "test thread", thread_test_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 packet pool. */
nx_packet_pool_create(&pool_server, "Server NetX Packet Pool", 600, pointer, 8192);
pointer = pointer + 8192;
/* Create an IP instance. */
nx_ip_create(&ip_server, "Server NetX IP Instance", SERVER_ADDRESS,
0xFFFFFF00UL, &pool_server, _nx_ram_network_driver,
pointer, 4096, 1);
pointer = pointer + 4096;
/* Create another packet pool. */
nx_packet_pool_create(&pool_client, "Client NetX Packet Pool", 600,
pointer, 8192);
pointer = pointer + 8192;
/* Create another IP instance. */
nx_ip_create(&ip_client, "Client NetX IP Instance", CLIENT_ADDRESS,
0xFFFFFF00UL, &pool_client, _nx_ram_network_driver,
pointer, 4096, 1);
pointer = pointer + 4096;
/* Enable ARP and supply ARP cache memory for IP Instance 0. */
nx_arp_enable(&ip_server, (void *) pointer, 1024);
pointer = pointer + 1024;
/* Enable ARP and supply ARP cache memory for IP Instance 1. */
nx_arp_enable(&ip_client, (void *) pointer, 1024);
pointer = pointer + 1024;
/* Enable TCP processing for both IP instances. */
nx_tcp_enable(&ip_server);
nx_tcp_enable(&ip_client);
#ifdef FEATURE_NX_IPV6
/* Next set the NetX Duo Telnet Server and Client addresses. */
server_ip_address.nxd_ip_address.v6[3] = 0x105;
server_ip_address.nxd_ip_address.v6[2] = 0x0;
server_ip_address.nxd_ip_address.v6[1] = 0x0000f101;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db1;
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
client_ip_address.nxd_ip_address.v6[3] = 0x101;
client_ip_address.nxd_ip_address.v6[2] = 0x0;
client_ip_address.nxd_ip_address.v6[1] = 0x0000f101;
client_ip_address.nxd_ip_address.v6[0] = 0x20010db1;
client_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
#endif
/* Create the NetX Duo TELNET Server. */
status = nx_telnet_server_create(&my_server, "Telnet Server", &ip_server,
pointer, 2048, telnet_new_connection, telnet_receive_data,
telnet_connection_end);
/* Check for errors. */
if (status)
error_counter++;
return;
}
/* Define the test thread. */
void thread_test_entry(ULONG thread_input)
{
NX_PACKET *my_packet;
UINT status;
/* Allow other threads (e.g. IP thread task) to run first. */
tx_thread_sleep(100);
#ifdef FEATURE_NX_IPV6
/* Here's where we make the Telnet Client IPv6 enabled. */
nxd_ipv6_enable(&ip_client);
nxd_icmp_enable(&ip_client);
/* Wait till the IP task thread initializes the system. */
tx_thread_sleep(100);
/* Set up the Client addresses on the Client IP for the primary interface. */
if_index = 0;
status = nxd_ipv6_address_set(&ip_ client, iface_index, NX_NULL, 10,
&address_index);
status = nxd_ipv6_address_set(&ip_ client, iface_index, & client _ip_address,
64, &address_index);
/* Allow NetX Duo time to validate addresses. */
tx_thread_sleep(400);
/* Set up the Server addresses on the Client IP. */
iface_index = 0;
status = nxd_ipv6_address_set (&ip_server, iface_index, NX_NULL, 10,
&address_index);
status = nxd_ ipv6_address _set(&ip_server, iface_index, & server _ip_address,
64, &address_index);
/* Allow NetX Duo time to validate addresses. */
tx_thread_sleep(400);
#endif
/* Start the TELNET Server. */
status = nx_telnet_server_start(&my_server);
/* Check for errors. */
if (status != NX_SUCCESS)
{
return;
}
/* Create a TELNET client instance. */
status = nx_telnet_client_create(&my_client, "My TELNET Client",
&ip_client, 600);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
#ifdef FEATURE_NX_IPV6
/* Connect the TELNET client to the TELNET Server at port 23. */
status = nxd_telnet_client_connect(&my_client, &server_ip_address, 23,
TELNET_TIMEOUT);
#else
/* Connect the TELNET client to the TELNET Server at port 23. */
status = nx_telnet_client_connect(&my_client, SERVER_ADDRESS, 23,
TELNET_TIMEOUT);
#endif
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* Allocate a packet. */
status = nx_packet_allocate(&pool_client, &my_packet, NX_TCP_PACKET,
NX_WAIT_FOREVER);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* Build a simple 1-byte message. */
nx_packet_data_append(my_packet, "a", 1, &pool_client, NX_WAIT_FOREVER);
/* Send the packet to the TELNET Server. */
status = nx_telnet_client_packet_send(&my_client, my_packet, TELNET_TIMEOUT);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* Pickup the Server header. */
status = nx_telnet_client_packet_receive(&my_client, &my_packet,
TELNET_TIMEOUT);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* At this point the packet should contain the Server's banner
message sent by the Server callback function below. Just
release it for this demo. */
nx_packet_release(my_packet);
/* Pickup the Server echo of the character. */
status = nx_telnet_client_packet_receive(&my_client, &my_packet,
TELNET_TIMEOUT);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* At this point the packet should contain the character 'a' that
we sent earlier. Just release the packet for now. */
nx_packet_release(my_packet);
/* Now disconnect form the TELNET Server. */
status = nx_telnet_client_disconnect(&my_client, TELNET_TIMEOUT);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
/* Delete the TELNET Client. */
status = nx_telnet_client_delete(&my_client);
/* Check status. */
if (status != NX_SUCCESS)
{
return;
}
}
/* This routine is called by the NetX Telnet Server whenever a new Telnet client
connection is established. */
void telnet_new_connection(NX_TELNET_SERVER *server_ptr, UINT logical_connection)
{
UINT status;
NX_PACKET *packet_ptr;
/* Allocate a packet for client greeting. */
status = nx_packet_allocate(&pool_server, &packet_ptr, NX_TCP_PACKET,
NX_NO_WAIT);
if (status != NX_SUCCESS)
{
error_counter++;
return;
}
/* Build a banner message and a prompt. */
nx_packet_data_append(packet_ptr,"**** Welcome to NetX TELNET Server ****\r\n\r\n\r\n", 45,
&pool_server, NX_NO_WAIT);
nx_packet_data_append(packet_ptr, "NETX> ", 6, &pool_server, NX_NO_WAIT);
/* Send the packet to the client. */
status = nx_telnet_server_packet_send(server_ptr, logical_connection,
packet_ptr, TELNET_TIMEOUT);
if (status != NX_SUCCESS)
{
error_counter++;
nx_packet_release(packet_ptr);
}
return;
}
/* This routine is called by the NetX Telnet Server whenever data is present on a
Telnet client connection. */
void telnet_receive_data(NX_TELNET_SERVER *server_ptr, UINT logical_connection,
NX_PACKET *packet_ptr)
{
UINT status;
UCHAR alpha;
/* This demo echoes the character back; on <cr,lf> sends a new prompt back to
the client. A real system would likely buffer the character(s) received in a
buffer associated with the supplied logical connection and process it. */
/* Just throw away carriage returns. */
if ((packet_ptr -> nx_packet_prepend_ptr[0] == '\r') && (packet_ptr -> nx_packet_length == 1))
{
printf("telnet server received just a CRLF\n");
nx_packet_release(packet_ptr);
return;
}
/* Setup new line on line feed. */
if ((packet_ptr -> nx_packet_prepend_ptr[0] == '\n') || (packet_ptr -> nx_packet_prepend_ptr[1] == '\n'))
{
/* Clean up the packet. */
packet_ptr -> nx_packet_length = 0;
packet_ptr -> nx_packet_prepend_ptr = packet_ptr -> nx_packet_data_start + NX_TCP_PACKET;
packet_ptr -> nx_packet_append_ptr = packet_ptr -> nx_packet_data_start + NX_TCP_PACKET;
/* Build the next prompt. */
nx_packet_data_append(packet_ptr, "\r\nNETX> ", 8, &pool_server,
NX_NO_WAIT);
/* Send the packet to the client. */
status = nx_telnet_server_packet_send(server_ptr, logical_connection,
packet_ptr, TELNET_TIMEOUT);
if (status != NX_SUCCESS)
{
error_counter++;
nx_packet_release(packet_ptr);
}
return;
}
/* Pickup first character (usually only one from client). */
alpha = packet_ptr -> nx_packet_prepend_ptr[0];
/* Echo character. */
status = nx_telnet_server_packet_send(server_ptr, logical_connection,
packet_ptr, TELNET_TIMEOUT);
if (status != NX_SUCCESS)
{
error_counter++;
nx_packet_release(packet_ptr);
}
/* Check for a disconnection. */
if (alpha == 'q')
{
/* Initiate server disconnection. */
nx_telnet_server_disconnect(server_ptr, logical_connection);
}
}
/* This routine is called by the NetX Telnet Server when the client disconnects. */
void telnet_connection_end(NX_TELNET_SERVER *server_ptr, UINT logical_connection)
{
/* Cleanup any application specific connection or buffer information. */
return;
}
There are several configuration options for building Telnet for NetX Duo. These #defines can be set by the application prior to inclusion of nxd_telnet_server.h.and nxd_telnet_client.h.
Following is a list of all options, where each is described in detail: