Synergy Software Package User's Manual
NetX/NetX Duo Telnet Client

Table of Contents

NetX and NetX Duo Telnet Client Introduction

The Telnet Protocol (Telnet) protocol is designed for transferring commands and responses between two nodes on the Internet. Telnet is a simple protocol that utilizes reliable Transmission Control Protocol (TCP) services to perform its transfer function. The NetX™ Telnet Client provides a high-level API for applications wishing to implement a Telnet Client.

Note
Except for internal processing, the NetX Duo™ Telnet Client is nearly identical in the application, set up and running a Telnet session as the NetX™ Telnet Client (except where noted).

Unsupported Features

Multi-thread support has not been tested in this version of SSP. 

NetX and NetX Duo Telnet Client Module Features

  • The NetX™ Telnet Client Module is compliant with RFC854 and related RFCs
  • Provides high-level APIs to:
    • Create and delete a Telnet Client instance
    • Connect and disconnect a Telnet Client instance
    • Send to and receive packets from a Telnet Server
    • Support multi-thread operation
nx_telnet_client_BD.png
NetX and NetX Duo Telnet Client Module Block Diagram
Note
In the figure above, the NetX (or NetX Duo) Network Driver module has multiple implementation options available. See the description just after the module stack figure in Including the NetX and NetX Duo Telnet Client Module in an Application for additional details.

NetX and NetX Duo Telnet Client Module APIs Overview

The NetX™ Telnet Client Module defines APIs for creating, deleting, connecting, disconnecting, receiving and sending telnet communications. 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 and NetX Duo Telnet Client Module API Summary

Function Name Example API Call and Description
nx_telnet_client_connect nx_telnet_client_connect(&g_telnet_client0, server_ip_address, server_port, NX_WAIT_FOREVER);
Connect a Telnet Server. Supports only IPv4.
**nxd_telnet_client_connect nxd_telnet_client_connect(&g_telnet_client0, &server_ip_address_v6, server_port, NX_WAIT_FOREVER);
Connect to a Telnet Server. Supports IPv4 and IPv6.
nx_telnet_client_create nx_telnet_client_create(&g_telnet_client0, "Telnet Client", &g_ip0, 1024);
Create a Telnet Client.
nx_telnet_client_delete nx_telnet_client_delete(&g_telnet_client0);
Delete a Telnet Client.
nx_telnet_client_disconnect nx_telnet_client_disconnect(&g_telnet_client0, NX_WAIT_FOREVER);
Disconnect from the Telnet Server (IPv4 or IPv6).
nx_telnet_client_packet_receive nx_telnet_client_packet_receive(&g_telnet_client0, &packet_ptr, NX_WAIT_FOREVER);
Receive packet from the Telnet Server.
nx_telnet_client_packet_send nx_telnet_client_packet_send(&g_telnet_client0, packet_ptr, NX_WAIT_FOREVER);
Send packet to the Telnet Server (IPv4 or IPv6).
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.

**This API is only available in NetX Duo Telnet Client. For definitions of NetX Duo specific data types, see the NetX Duo User Guide for the Renesas Synergy™ Platform.

Status Return Values

Name Description
NX_SUCCESS API Call Successful
NX_TELNET_ERROR Error while creating TCP socket as part of creating the Telnet Client instance
NX_TELNET_NOT_CONNECTED Client not disconnected
NX_TELNET_NOT_DISCONNECTED Client socket is not in closed state (cannot make a TCP connection; cannot delete the Telnet Client if the socket is still connected).
NX_TELNET_INVALID_PARAMETER* Invalid non-pointer input to Telnet Client create
NX_PTR_ERROR* Invalid pointer input
NX_IP_ADDRESS_ERROR* Invalid IP address to connect to Telnet Server
NX_CALLER_ERROR* Invalid caller of this service
Note
Lower-level drivers may return common error codes. See SSP User's Manual API References for the associated module for a definition of all relevant status return values.

*These error codes are only returned if error checking is enabled. Please refer to the NetX Duo User Guide for the Renesas Synergy™ Platform for more details on error checking services in NetX Duo.

NetX and NetX Duo Telnet Client Module Operational Overview

In the NetX™ Telnet Client Module, the IP thread task for NetX™ is created and runs, the Telnet Client is created and the TCP socket for connecting to the Telnet Server is ready for use automatically. The Telnet Client connects to the server by calling the nx_telnet_client_connect API. (This API is available in NetX Duo™ Telnet and is limited to IPv4 TCP connections. In NetX Duo™, the application can also use the nxd_telnet_client_connect which supports both IPv4 and IPv6.) If that succeeds, then the Telnet Client should wait to receive a Server 'banner' announcing itself using the nx_telnet_client_packet_receive API. Thereafter the Telnet Client can create packets with single characters of data using the nx_packet_allocate and nx_packet_data_append API. These packets are sent to the Telnet Server by calling the nx_telnet_client_packet_send API.

For a more complete description of the NetX™ Telnet Client and NetX Duo™ Telnet Client operations, refer to the associated User Guides found in the Synergy Gallery, under the SSP Documentation tab as "Azure RTOS and NetX™ Component Documentation for Renesas Synergy". Open the zip file and navigate to the related User Guides for detailed descriptions. This document provides only an introduction to component operations. Module selection, configuration, and example uses are described in detail in the following sections.

NetX and NetX Duo Telnet Client Module Important Operational Notes and Limitations

NetX and NetX Duo Telnet Client Module Operational Notes

  • The NetX Duo™ Telnet Client Module services can be called from multiple threads simultaneously. However, read or write requests for a particular Telnet Client instance should be done in sequence from the same thread.

NetX and NetX Duo Telnet Client Module Limitations

  • The Telnet Client does not support Telnet negotiation or send IAC and command code sequences.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the NetX and NetX Duo Telnet Client Module in an Application

This section describes how to include either or both the NetX and NetX Duo Telnet Client 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 and NetX Duo Telnet Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.

NetX and NetX Duo Telnet Client Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_telnet_client0 NetX™ Telnet Client Threads New Stack> X-Ware> NetX™> Protocols> NetX™ Telnet Client
g_telnet_client0 NetX Duo™ Telnet Client Threads New Stack> X-Ware> NetX Duo™> Protocols> NetX Duo™ Telnet Client

When the NetX and/or NetX Duo Telnet Client 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.

nx_telnet_client_MS.png
NetX and NetX Duo Telnet Client 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 and NetX Duo Telnet Client Module

The NetX and NetX Duo Telnet Client 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 and NetX Duo Telnet Client Module

ISDE Property Value Description
Name g_telnet_client0 Module name
TCP Socket Window Size in Bytes 1024 TCP socket window size selection
Name of generated initialization function telnet_client_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 lower-level modules can be desirable. For example, it might be useful to select different IP addresses and subnet masks. The configurable properties for the lower-level stack modules are provided 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 and NetX Duo Telnet Client 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 and NetX Duo IP Instance

ISDE Property Value Description
Name g_ip0 Module name
IPv4 Address (use commas for separation) 192,168,0,2 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 function
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 and NetX Duo Telnet Common Instance

ISDE Property Value Description
Type of Service for UDP requests Normal, Minimum delay, Maximum data, Maximum reliability, Minimum cost

Default: Normal 		Type of service UDP requests selection
Fragmentation option Don't fragment, Fragment okay

Default: Don't fragment 		Fragment option selection
Server TCP port number 23 Server TCP port number selection
Time to live 128 Time to live 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 and 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 and 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 and NetX Duo Telnet Client Module Clock Configuration

The ETHERC peripheral module uses the 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 and NetX Duo Telnet Client 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 what peripheral signals available and what MCU pins are 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 and the SK-S7G2 Kit. Other Synergy MCUs and other Synergy Kits may have different available pin configuration settings.

Using the NetX and NetX Duo Telnet Client Module in an Application

The NetX™ Telnet Client Module does not need the usual initialization by an application. A configurator generates initialization process. The user application only needs Telnet communication processing.

The steps in using the NetX and NetX Duo Telnet Client module in a typical application are:

1. Use the nx_ip_status_check API to check that the IP instance is initialized and the application can start using NetX™ services.

2. Connect to the Telnet Server via the nx_telnet_client_connect API. (Note: For NetX Duo™ the preferred API is nxd_telnet_client_connect).

3. Receive the Telnet Server welcome banner using nx_telnet_client_packet_receive API [Optional]

4. Create a packet to send with the nx_packet_allocate and nx_packet_data_append APIs.

5. Send the packet using the nx_telnet_client_packet_send API

6. Receive the Server's response packet using the nx_telnet_client_receive API.

7. Disconnect communication using the nx_telnet_client_disconnect API

8. Delete the instance using the nx_telnet_client_delete API when done sending and receiving.

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

nx_telnet_client_TA.png
Flow Diagram of a Typical NetX and NetX Duo Telnet Client Module Application