 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Telnet Protocol (Telnet) is a protocol 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.
Unsupported Features
Telnet Option Negotiation has not been tested for NetX Duo Telnet Server in this version of SSP
The NetX Telnet Server module defines APIs for creating, deleting, sending packets, starting and stopping. 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 Server Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_telnet_server_create | nx_telnet_server_create(&my_server, "Telnet Server", &ip_0,pointer, 2048, telnet_new_connection, telnet_receive_data, telnet_connection_end);Create a Telnet Server. |
| nx_telnet_server_delete | nx_telnet_server_delete(&my_server);Delete a Telnet Server. |
| nx_telnet_server_disconnect | nx_telnet_server_disconnect(&my_server, 2);Disconnect the Telnet Client specified by the client list index (2nd input). |
| nx_telnet_server_get_open_connection_count | nx_telnet_server_get_open_connection_count(&my_server, &conn_count);Retrieve the number of open connections. |
| nx_telnet_server_packet_send | nx_telnet_server_packet_send(&my_server, 2, my_packet, 100);Send packet to Telnet Client specified by client list index (second input). |
| nx_telnet_packet_pool_set | nx_telnet_server_packet_pool_set(&my_server, &telnet_server_packet_pool);Set packet pool as Telnet Server packet pool. |
| nx_telnet_server_start | nx_telnet_server_start(&my_server);Start theTelnet Server. |
| nx_telnet_server_stop | nx_telnet_server_stop(&my_server);Stop the Telnet Server. |
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | Successful telnet function |
| NX_PTR_ERROR* | Invalid Server, IP, stack, or application callback pointers |
| NX_CALLER_ERROR* | Invalid caller of this service |
| NX_OPTION_ERROR* | Invalid logical connection |
| NX_IP_ADDRESS_ERROR* | Invalid IP address |
| NX_TELNET_FAILED | Server packet send failed |
| NX_TELNET_NO_PACKET_POOL | Cannot start Telnet Server, no packet pool available |
| NX_TELNET_NOT_CONNECTED | Cannot disconnect Telnet Server because it is not connected |
| NX_TELNET_NOT_DISCONNECTED | Cannot connect or delete Telnet Server because it is not disconnected |
*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.
The NetX Telnet package requires that a NetX IP instance has already been created. In addition, TCP must be enabled on that same IP instance. The Telnet Client portion of the NetX Telnet package has no further requirements. It also requires complete access to TCP well-known port 23 for handling all Telnet Client requests. The Telnet Server keeps a list of client connections and uses an index into this list to specify certain clients when needed. The size of this list is set in the Maximum clients to server simultaneously property.
The Telnet Server can be enabled for limited Option negotiation with the Telnet Client. To enable this feature, set the Option negotiation to enable. If this feature is enabled, the Telnet Server needs a packet pool. The application can set the packet payload and number of packets; packet_size_inthe pool and Totalpacket_pool_sizeProperties, respectively and let the Telnet Server create the packet pool. When the Telnet Server is deleted, the packet pool is deleted with it.
Alternatively, it can create the packet pool directly and be set as the Telnet Server packet pool by 1) enabling Use application packet pool or by 2) creating the packet pool by calling the NetXnx_packet_pool_create API and 3) setting the packet pool in the Telnet Server using the nx_telnet_server_packet_pool_set API. When the Telnet Server is deleted, the application must delete the packet pool directly (nx_packet_pool_delete API).
Telnet New Connection Callback
The NetX Telnet Server calls the new connection callback function when a new Telnet Client request is received. The callback function is set in the NetX Telnet Server Name of Client Connect Callback Function property. Actions of the new connection callback include sending a banner or prompt to the client. It could also include a prompt for login information if authentication is required. The second argument of the new connection callback specifies the client is connecting.
Telnet Receive Data Callback
The NetX Telnet Server Module calls the data received callback function when a new Telnet Client data is received. The second input of the callback is an index into the Telnet Server's list of clients so the Telnet Server knows which client wants to disconnect. The callback function is set in the Name of Receive Data Callback Function property. Typical actions of the receive data callback include echoing the data back and/or parsing the data and providing data because of interpreting a command from the client.
Telnet End Connection Callback
The NetX Telnet Server calls the end connection callback function when it receives a Telnet Client disconnect request. The second input of the callback is an index into the Telnet Server's list of clients so the Telnet Server knows which Client wants to disconnect. The callback function is set in the Name of Client Disconnect Callback Function property. Typical actions of the end connection callback include cleaning up resources used for the Telnet Client session.
Telnet Option Negotiation
Upon making a connection with the Telnet Client, the Telnet Server will send out this set of Telnet options to the client if it has not received option requests from the client:
will echo
don't echo
will sga
When it receives Telnet data from the client, the Telnet Server checks if the first byte is the IAC (Interpret as Command) code; if so, it will process all the options in the client packet. Options not in the list above are not supported and will be ignored.
nx_telnet_server_packet_send fails, the callback must release that packet.nx_telnet_server_get_open_connection_count API. nx_telnet_server_stop API and restarted using the nx_telnet_server_start API. When the Telnet Server is stopped, all client connections are dropped and the server stops listening on the Telnet port.This section describes how to include either or both the NetX and NetX Duo Telnet Server module in an application using the SSP configurator.
To add the NetX and NetX Duo Telnet Server 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 Server Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_telnet_server0 NetX Telnet Server | Threads | New Stack> X-Ware> NetX> Protocols> NetX Telnet Server |
| g_telnet_server0 NetX Duo Telnet Server | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo Telnet Server |
When the NetX and/or NetX Duo Telnet Server 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.
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:
The NetX and NetX Duo Telnet Server 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.
Configuration Settings for the NetX and NetX Duo Telnet Server Module
| ISDE Property | Value | Description |
|---|---|---|
| Internal thread priority | 16 | Internal thread priority selection |
| Maximum clients to serve simultaneously | 4 | Maximum clients to serve simultaneously selection |
| Socket window size (bytes) | 2048 | Socket window size (bytes) selection |
| Server time out (seconds) | 10 | Server time out (seconds) selection |
| Client inactivity timeout (seconds) | 600 | Client inactivity timeout (seconds) selection |
| Timeout check period (seconds) | 60 | Timeout check period (seconds) selection |
| Option negotiation | Enable, Disable Default: Enable | Option negotiation selection |
| Use application packet pool | Enable, Disable Default: Disable | Use application packet pool selection |
| Packet size in the pool (bytes) | 300 | Packet size in the pool (bytes) selection |
| Total packet pool size (bytes) | 2048 | Total packet pool size (bytes) selection |
| Name | g_telnet_server0 | Name selection |
| Internal thread stack size (bytes) | 2048 | Internal thread stack size (bytes) selection |
| Name of Client Connect Callback Function | telnet_client_connect | Name of Client Connect Callback Function selection |
| Name of Receive Data Callback Function | telnet_receive_data | Name of Receive Data Callback Function selection |
| Name of Client Disconnect Callback Function | telnet_client_disconnect | Name of Client Disconnect Callback Function selection |
| Name of generated initialization function | telnet_server_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
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.
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 |
** 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 |
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 |
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 |
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.
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.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin Selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals > Connectivity:ETHERC > ETHERC1.RMII |
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 |
The steps in using the NetX and NetX Duo Telnet Server module in a typical application are:
1. Use the nx_ip_status_check API to check that the IP instance can communicate.
2. Configure the Telnet Server to do option negotiation [optional].
3. If options negotiation is enabled, configure the Telnet Server to create its own packet pool (default) or set the Telnet Server pool from the application.
4. Start the Telnet Server using the nx_telnet_server_start API.
5. Process client requests with the callbacks specified at build time.
6. Delete the Telnet Server when done.
7. If the Telnet Server packet pool was created by the application, it can be deleted if not in use by other threads.
The NetX Telnet Server module application needs to execute response processing in the registered callback function. Typically, in callback processing, the content of the received packet is confirmed and data content is transmitted with the nx_telnet_server_packet_send API. When disconnection of communication is required from the server side, call the nx_telnet_server_disconnect API.
The following figure illustrates common steps in a typical operational flow diagram:
