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

Table of Contents

NetX/NetX Duo TFTP Client Introduction

The Trivial File Transfer Protocol (TFTP) is a lightweight protocol designed for file transfers over UDP. Unlike more robust TCP based protocols, TFTP does not perform extensive error checking and can have limited performance because it is a stop-and-wait protocol. After a TFTP data packet is sent, the sender waits for an ACK to be returned by the recipient. Although this is simple, it does limit the overall TFTP throughput. The TFTP Server utilizes the well-known UDP port 69 to listen for client requests. TFTP Clients may use any available UDP port. Data packets are 512 bytes, until the last packet. A packet containing fewer than 512 bytes signals the end of file.

Note
Except where noted, the NetX Duo TFT Client is identical in application set up and running of a TFTP session as the NetX TFTP Client.  For setting up the IP instance for IPv6 in NetX Duo, please refer to the NetX Duo User Guide for the Renesas Synergy™ Platform.

Unsupported Features

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

NetX/NetX Duo TFTP Client Module Features

  • The NetX TFTP Client Module is compliant with RFC 1350 and related RFCs.
  • High level APIs for:
    • Creating and deleting a TFTP client
    • Reading and writing files to TFTP recipient (server)
    • Set network interface for TFTP Client to run on
nx_tftp_client_BD.png
NetX/NetX Duo TFTP 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/NetX Duo TFTP Client Module in an Application for additional details.

NetX/NetX Duo TFTP Client Module APIs Overview

The NetX/NetX Duo TFTP Client module defines APIs for creating and starting the TFTP Client. Internally, the TFTP Client handles all communication with the TFTP Server to transfer files. 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/NetX Duo TFTP Client Module API Summary

Function Name Example API Call and Description
nx_tftp_client_file_open nx_tftp_client_file_open(&g_tftp_client0, "test.txt", server_ip_address, NX_TFTP_OPEN_FOR_READ, NX_WAIT_FOREVER);
Open TFTP client file (IPv4 only).
nxd_tftp_client_file_open** nxd_tftp_client_file_open(&g_tftp_client0, "test.txt", &server_ip_address_v6, NX_TFTP_OPEN_FOR_READ, NX_WAIT_FOREVER, NX_IP_VERSION_V6);
Open TFTP client file. Can be IPv4 type or IPv6
nx_tftp_client_create nx_tftp_client_create(&g_tftp_client0, "TFTP Client", &g_ip0, &g_packet_pool0);
Create a TFTP client instance
nxd_tftp_client_create** nx_tftp_client_create(&g_tftp_client0, "g_tftp_client0 TFTP Client", &g_ip0, &g_packet_pool0, NX_IP_VERSION_V6);
Create a TFTP client instance.
nx_tftp_client_delete nx_tftp_client_delete(&g_tftp_client0);
Delete a TFTP client instance.
nxd_tftp_client_delete** nxd_tftp_client_delete(&g_tftp_client0);
Delete a TFTP client instance.
nx_tftp_client_error_info_get nx_tftp_client_error_info_get(&g_tftp_client0, &error_code, &error_string);
Get client error information.
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 TFTP 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 Successful TFTP create
NX_PTR_ERROR* Invalid IP, pool, or TFTP pointer
NX_CALLER_ERROR * Invalid caller of this service
NX_TFTP_NOT_CLOSED Cannot open file; Client already has file open
NX_TFTP_CODE_ERROR Error status received from TFTP server
NX_INVALID_TFTP_SERVER_ADDRESS Invalid server address received
NX_TFTP_FAILED Unknown code received from Server
NX_TFTP_NO_ACK_RECEIVED No ACK received from server on read or write
NX_TFTP_INVALID_BLOCK_NUMBER Block of data in TFTP server ACK does not match TFTP Client after read or write request.
NX_TFTP_NOT_OPEN TFTP client not in the open state for file read or write
NX_IP_ADDRESS_ERROR* Invalid Server IP address
NX_OPTION_ERROR* Invalid open type
NX_INVALID_TFTP_SERVER_ADDRESS Invalid server address received
NX_TFTP_END_OF_FILE End of file detected (not an error) during file download (read) transfer
NX_TFTP_TIMEOUT Timeout waiting for Server ACK of write request
NX_TFTP_INVALID_INTERFACE* Invalid interface input
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/NetX Duo TFTP Client Module Operational Overview

In the NetX/NetX Duo TFTP Client module, the client is automatically created and the UDP socket is created for sending and receiving TFTP packets. In a TFTP Client application, the TFTP Client first 'opens' a file.  If the Server returns an acknowledgment, the Client can then request a file transfer for either reading (receiving from) or writing (sending to) the TFTP Server.  After each file transfer the TFTP Client closes the file.

A TFTP Server listens for Client requests on the well-known port 69. The TFTP Client socket can bind to any port. When transferring a file in TFTP, the amount of data that added to a packet can only be 512 bytes, unless there is less than 512 bytes left to send. A packet containing fewer than 512 bytes signals the end of file. The general sequence of events is as follows:

TFTP Read File Requests:

  1. Client issues an "Open for Read" request with the file name and waits for the Server response.
  2. Server sends the first 512 bytes of the file as 'block number 1'
  3. Client receives the data, sends an ACK specifying block number is '1' , and waits for the next packet.
  4. The Server sends the rest of the data incrementing the block number each time, and the Client ACKs sends an ACK with the corresponding block number each time.
  5. The sequence ends when the last packet containing fewer than 512 bytes is received. nx_tftp_client_file_read returns NX_TFTP_END_OF_FILE when the last packet of a file transfer is received.

TFTP Write Requests:

  1. Client issues an "Open for Write" request with the file name and waits for an ACK with a block number of 0 from the Server.
  2. The Server sends an ACK with a block number of zero.
  3. Client sends the first 512 bytes of the file to the Server and waits for an ACK.
  4. Server sends ACK after the bytes are written.
  5. The sequence ends when the Client completes sends a packet containing fewer than 512 bytes.

NetX/NetX Duo TFTP Client Module Important Operational Notes and Limitations

NetX/NetX Duo TFTP Client Module Operational Notes

  • If nx_tftp_client_file_read returns NX_SUCCESS, the caller must release the packet after it is done with it.
  • If nx_tftp_client_file_write returns NX_TFTP_NOT_OPEN, the caller must release the packet.  In all other cases NetX or NetX TFTP Client Module will release the packet.
  • For file data, any data can be used. The NetX TFTP Client Module does not make any changes to send or receive data.
  • The NetX TFTP Client Module is compliant with RFC 1350 and related RFCs.

NetX/NetX Duo TFTP Client Module Limitations

  • The line feed code of the text file cannot be changed; this must be processed by the user application.
  • The NetX TFTP Client Module services can be called from multiple threads simultaneously. However, read or write requests for a particular client instance should be done in sequence from the same thread.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the NetX/NetX Duo TFTP Client Module in an Application

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

NetX/NetX Duo TFTP Client Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_tftp0 NetXTFTP Client Threads New Stack> X-Ware> NetX> Protocols> NetXTFTP Client
g_tftp0 NetX Duo TFTP Client Threads New Stack> X-Ware> NetX Duo> Protocols> NetX Duo TFTP Client

When the NetX and/or NetX Duo TFTP 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_tftp_client_MS.png
NetX/NetX Duo TFTP 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/NetX Duo TFTP Client Module

The NetX/NetX Duo TFTP 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/NetX Duo TFTP Client Module

ISDE Property Value Description
Source port to use NX_ANY_PORT Source port to use selection
Name g_tftp_client0 Module name
Name of generated initialization function tftp_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 pins for the Ethernet peripheral. 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/NetX Duo TFTP 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/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/NetX Duo TFTP Common Instance

ISDE Property Value Description
Maximum error string length (bytes) 64 Maximum error string length selection
Time to live 128 Time to live selection
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
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/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/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/NetX Duo TFTP 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/NetX Duo TFTP 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/NetX Duo TFTP Client Module in an Application

The following example assumes that a system is already establish with a working IP, ARP and UDP enabled and the link is running.

The steps in using the NetX/NetX Duo TFTP Client module in a typical application are:

1. Poll the nx_ip_status_check API for when the IP instance has a valid IP address.

2. To request a file write, call the nx_tftp_client_file_open API with NX_TFTP_OPEN_FOR_WRITE as the open_type input.

3. Allocate a packet using the nx_tftp_client_packet_allocate API and write the file data into the packet buffer.  This packet is ready to send. 

4. Send to the Server by calling the nx_tftp_client_file_write API.

5. Repeat until all file data is sent. Unless this API returns NX_TFTP_NOT_OPEN, the application should not release the packet.

6. Close the file by calling the nx_tftp_client_file_close.

7. To request a file read, call the nx_tftp_client_file_open API with NX_TFTP_OPEN_FOR_READ as the open_type input.

8. Receive file data by calling the nx_tftp_client_file_read API.

9. Continue until a packet of less than 512 bytes is received.  Release the packets back to the packet pool when done with it.

10. Use the nx_tftp_client_file_close API to close the file.

11. Delete instance by nx_tftp_client_delete API when done with the TFTP Client.

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

nx_tftp_client_TA.png
Flow Diagram of a Typical NetX/NetX Duo TFTP Client Module Application