Synergy Software Package User's Manual
Telnet Communications Framework on sf_comms_telnet

Table of Contents

Telnet Communications Framework Introduction

The Communications Framework on NX provides a high-level API for communications framework applications and uses the Ethernet peripheral on the Synergy MCU.

Telnet Communications Framework Module Features

  • High-level connectivity is supported on Ethernet but is easily changeable to UART and USB connectivity without API modification
  • Supports channel locking for exclusive access
  • Thread-aware implementation uses mutex and event flags internally
sf_comms_telnet_BD.png
Telnet Communications Framework Module Block Diagram

Telnet Communications Framework Module APIs Overview

The Telnet Communications Framework module defines APIs to open, read from, write to, lock, unlock and close the module. 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.

Telnet Communications Framework Module API Summary

Function Name Example API Call and Description
open g_sf_comms_telnet0.p_api->open (g_sf_comms_telnet0.p_ctrl, g_sf_comms_telnet0.p_cfg);
Initialize the module.
read g_sf_comms_telnet0.p_api->read (g_sf_comms_telnet0.p_ctrl, p_dest, bytes, timeout);
Read a number of bytes of data into the destination.
write g_ sf_comms_telnet0.p_api->write (g_sf_comms_telnet0.p_ctrl, P_src, bytes, timeout);
Write a number of bytes from the source.
lock g_sf_comms_telnet0.p_api->lock (g_sf_comms_telnet0.p_ctrl, locktype, timeout);
Acquire lock type for the Telnet comms instance.
unlock g_sf_comms_telnet0.p_api->unlock (g_sf_comms_telnet0.p_ctrl, locktype);
Release the lock type for the Telnet comms instance.
close g_sf_comms_telnet0.p_api->close (g_sf_comms_telnet0.p_ctrl);
Disconnect Telnet server and clean up resources.
versionGet g_ sf_comms_telnet0.p_api->versionGet(&version);
Get version and store it in provided version pointer.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS API Call Successful.
SSP_ERR_INVALID_ARGUMENT Parameter has invalid value.
SSP_ERR_INTERNAL An internal TheadX error has occurred.
SSP_ERR_NOT_OPEN Unit is not open.
SSP_ERR_ASSERTION A parameter is NULL.
SSP_ERR_IN_USE Peripheral is still running in another mode; perform Close first.
SSP_ERR_UNSUPPORTED Command not supported.
SSP_ERR_OUT_OF_MEMORY Cannot allocate pool memory.
SSP_ERR_TIMEOUT An event timed out.
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.

Telnet Communications Framework Module Operational Overview

The Communications Framework using Telnet on NX provides an easy to use connection over an Ethernet port. The high-level APIs are compatible with other connection protocols, such as UART and USB, so that it is easy to switch from one implementation to another without changing APIs.

Operations supported by the framework include initializing the module using the sf_comms_api_t::open API, and closing the module using the sf_comms_api_t::close API. A communications read is implemented by the sf_comms_api_t::read API and a communications write by the sf_comms_api_t::write API. The sf_comms_api_t::read and sf_comms_api_t::write lock the module only until the called API is in action.

During a read operation, when using the TX_WAIT_FOREVER timeout, if the Ethernet link goes down, the sf_comms_api_t::read API will continue to wait for the data from the read queue. Once the Ethernet link is back up, the read operation resumes and exits. To exit the read operation during a link down event, the user must explicitly abort the read operation by calling the sf_comms_api_t::close API in the link status change callback function. The sf_comms_api_t::lock API locks the module until the sf_comms_api_t::unlock API is called on the same module instance. This helps ensure that processing is completed before moving to the next API function call.

A user defined disconnect callback function (Telnet client disconnect callback) can be defined by the user to handle the Telnet client disconnection due to Client inactivity timeout. This callback will be called when the configured Client inactivity timeout occurs.

The underlying NetX driver supports the configuration of the IP address, the Network mask, and the Ethernet channel. When a different communications implementation is used (like USB) different low-level module configuration settings are used to define its interface. Thus, no code needs to be changed in the application, only need changes to configuration settings. The same API calls are retained at the application level.

Telnet Communications Framework Module Important Operational Notes and Limitations

Telnet Communications Framework Module Operational Notes

  • The Ethernet peripheral can use either RMII or MII depending on MCU capabilities.

Telnet Communications Framework Module Limitations

  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Telnet Communications Framework Module in an Application

This section describes how to include the Telnet Communications Framework 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 Telnet Communications Framework module to an application, simply add it to a HAL /Common thread using the stacks selection sequence given in the following table. (The default name for the Telnet Communications Framework module is sf_comms_telnet0. This name can be changed in the associated Properties window.)

Telnet Communications Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
sf_comms_telnet0 Telnet Communications Framework on sf_comms_telnet Threads New Stack> Framework> Connectivity> Telnet Communications Framework on sf_comms_telnet

When the Telnet Communications Framework module on sf_comms_telnet 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.

sf_comms_telnet_MS.png
Telnet Communications Framework Module Stack

Configuring the Telnet Communications Framework Module

The Telnet Communications Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are 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 the SSP.

Configuration Settings for the Telnet Communications Framework Module on sf_comms_telnet

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable the parameter checking.
Packet size in pool memory (bytes) 1536 Packet size in pool memory selection.
Packets to allocate in pool memory (units) 5 Packets to allocate in pool memory selection.
Timeout for internal options (ticks) 10 Timeout for internal options selection.
Maximum number of instances 4 Maximum instances that can be open at any given time.
Name sf_comms_telnet0 Module name.
Name of generated initialization function sf_comms_telnet_init0 Name of generated initialization selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Telnet client disconnect callback NULL User defined callback invoked when the client is disconnected.
Note
The example values and defaults are for a project using the Synergy S7G2 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. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference.

Note
Most of the property settings for lower level modules are fairly intuitive and can usually be determined by inspection of the associated Properties window from the SSP configurator.

Configuring the Telnet Communications Framework Lower-Level Modules

Typically, only a small number of settings must be modified from the default for lower-level drivers as indicated with 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 will be 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 Telnet Server on telnet_server

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 selection.
Server time out (seconds) 10 Duration internal services will suspend for.
Client inactivity timeout (seconds) 600 Client inactivity duration for disconnection.
Timeout check period (seconds) 60 Client activity timeout check interval.
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 Telnet Server only creates this packet pool if 'Option negotiation' is enabled.
Total packet pool size (bytes) 2048 Telnet Server only creates this packet pool if NX_TELNET_SERVER_OPTION_DISABLE.
Name g_telnet_server0 Module name.
Thread Stack Size (bytes) 2048 Thread stack size selection.
Name of Client Connect Callback Function NULL Name of client connect callback function selection.
Name of Receive Data Callback Function NULL Name of receive data callback function selection.
Name of Client Disconnect Callback Function NULL Name of client disconnect callback function selection.
Name of generated initialization function telnet_server_init0 Name of generated initialization function selection.
Auto Initialization Disable Auto initialization selection.
Note
The example values 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/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.
**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 storage units Bytes, Entries
Default: Bytes 		ARP cache storage units selection.
ARP Cache Size (in storage units) 520 ARP Cache Size in Bytes/Entries selection.
Note: 1 Entry = 52 Bytes.
Reverse ARP Enable, Disable

Default: Disable 		Reverse ARP selection.
TCP 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 values 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 NetX Telnet Common

ISDE Property Value Description
Type of Service for TCP 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 values 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/NetX Duo Common on nxd

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 values 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/NetX Duo Packet Pool Instance

ISDE Property Value Description
Name g_packet_pool0 Module name.
Packet Size in Bytes 1568 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 values 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 ETHER

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter checking.
Channel 0 Phy Reset Pin IOPORT_PORT_09_PIN_03 Channel 0 Phy reset pin selection.
Channel 0 MAC Address High Bits 0x00002E09 Channel 0 MAC address high bits selection.
Channel 0 MAC Address Low Bits 0x0A0076C7 Channel 0 MAC address low bits selection.
Channel 1 Phy Reset Pin IOPORT_PORT_07_PIN_06 Channel 1 PHY reset pin selection.
Channel 1 MAC Address High Bits 0x00002E09 Channel 1 MAC address high bits selection.
Channel 1 MAC Address Low Bits 0x0A0076C8 Channel 1 MAC address low bits selection.
Number of Receive Buffer Descriptors 8 Number of receive buffer descriptors selection.
Number of Transmit Buffer Descriptors 32 Number of transmit buffer descriptors selection.
Ethernet Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Ethernet interrupt priority selection.
Link status monitoring method PHY Interrupt (Uses LINKSTA Pin), PHY Polling
 
Default: PHY Polling 		Link status monitoring method selection.
Name g_sf_el_nx Module name.
Channel 0 Channel selection.
Callback NULL Callback selection.
Unknown packet receive Callback NULL Unknown packet receive 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.

Telnet Communications Framework Module Clock Configuration

The Telnet Communications Framework module uses the Ethernet peripheral which uses the PCLKA as its clock source.

To change the clock frequency at run-time, use the CGC Interface.

Telnet Communications Framework Module Pin Configuration

To use the Telnet Communications Framework module, the port pins for the peripheral inputs and outputs must be set in the pin configurator in the ISDE. The following table illustrates the method for selecting the pins within the ISDE configuration window:

Pin Selection Sequence for the Telnet Communications Framework Module

Resource ISDE Tab Pin selection Sequence
SSI Pins Select Peripherals> Peripherals> Connectivity:ETHERC> ETHERC0.RMI or ETHERC1.RMII

Using the Telnet Communications Framework Module in an Application

The typical steps in using the Telnet Communications Framework module in an application are:

  1. Initialize the Communications Framework on NX using the sf_comms_api_t::open API
  2. Lock the channel for continuous communications using the sf_comms_api_t::lock API if needed
  3. Receive data using the sf_comms_api_t::read API
  4. Send data using the sf_comms_api_t::write API
  5. Unlock the channel from continuous communication using the sf_comms_api_t::unlock command if needed
  6. Close the channel using the sf_comms_api_t::close API

These common steps are illustrated in a typical operational flow in the following figure:

sf_comms_telnet_TA.png
Flow Diagram of a Typical Telnet Communications Framework Module Application