 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The File Transfer Protocol (FTP) is a protocol designed for file transfers. The FTP utilizes reliable Transmission Control Protocol (TCP) services to perform its file transfer function. The actual FTP file transfer is performed on a dedicated FTP connection.
Unsupported Features
Multi-thread support has not been tested in this version of SSP.
Passive transfer mode has not been tested for NetX Duo in this version of SSP.
The NetX/NetX Duo FTP Client defines APIs for client creation/deletion, connecting/disconnecting to and from the server, directory operations and file operations. 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 FTP Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_ftp_client_create | nx_ftp_client_create(&my_client, "My Client", &client_ip,2000, &client_pool);Delete an FTP Client instance. |
| nx_ftp_client_delete | nx_ftp_client_delete(&my_client);Delete an FTP Client instance. |
| nx_ftp_client_connect | nxd_ftp_client_connect(&my_client, server_ip_addr, NULL, NULL, 100);Connect to an FTP Server with IPv6 and IPv4 support. |
| **nxd_ftp_client_connect | nxd_ftp_client_connect(&my_client, server_ip_addr, NULL, NULL, 100);Connect to an FTP Server with IPv6 and IPv4 support. |
| nx_ftp_client_disconnect | nx_ftp_client_disconnect(&my_client, 200);Disconnect from the FTP Server. |
| nx_ftp_client_create | nx_ftp_client_directory_create(&my_client, "my_dir", 200);Create a directory on the server. |
| nx_ftp_client_directory_set | nx_ftp_client_directory_listing_set(&my_client, "my_dir", &my_packet,200);Get a directory listing from the server. |
| nx_ftp_client_directory_delete | nx_ftp_client_directory_delete(&my_client, "my_dir", 200);Delete a directory on the server. |
| nx_ftp_client_directory_listing_get | nx_ftp_client_directory_listing_get(&my_client, "my_dir", &my_packet,200);Get a directory listing from the server. |
| nx_ftp_client_directory_listing_continue | nx_ftp_client_directory_listing_continue(&my_client, &my_packet,200);Continue a directory listing from the server. |
| nx_ftp_client_file_open | nx_ftp_client_file_open(&my_client, "my_file.txt", NX_FTP_OPEN_FOR_READ,200);Open a file on the server. |
| nx_ftp_client_file_close | nx_ftp_client_file_close(&my_client, 200);Close the currently open file on the server. |
| nx_ftp_client_file_read | nx_ftp_client_file_read(&my_client, &my_packet, 200);Read from a file already open on the server. |
| nx_ftp_client_file_write | nx_ftp_client_file_write(&my_client, my_packet, 200);Write to an already open file on the server. |
| nx_ftp_client_file_rename | nx_ftp_client_file_rename(&my_client, "my_file.txt", "new_file.txt",200);Rename a file on the server. |
| nx_ftp_client_file_delete | nx_ftp_client_file_delete(&my_client, "my_file.txt", 200);Delete a file on the server. |
**This API is only available in NetX Duo FTP 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 FTP function. |
| NX_FTP_NOT_DISCONNECTED | FTP client is already connected. |
| NX_FTP_200_CODE_NOT_RECEIVED | Server rejects FTP connection. |
| NX_FTP_300_CODE_NOT_RECEIVED | Server rejects user/password. |
| NX_PTR_ERROR | Invalid FTP, username, or password pointer. |
| NX_CALLER_ERROR | Invalid caller of this service. |
| NX_IP_ADDRESS_ERROR | Invalid IP address. |
| NX_FTP_NO_2XX_RESPONSE_XXD | FTP server error response. |
| NX_FTP_NO_2XX_RESPONSE_PORT | FTP server response to PORT. |
| NX_FTP_NO_1XX_RESPONSE | FTP server response to NLST. |
| NX_FTP_END_OF_LISTING | No more entries in directory. |
| NX_FTP_NO_2XX_RESPONSE_DISCONNECT | FTP server response to disconnect. |
FTP Client Requirements
To function properly, the NetX FTP Client package requires NetX. Similarly, the NetX Duo FTP Client package relies on NetX Duo. The host application must create an IP instance for running NetX services and periodic tasks. If running the FTP host application over an IPv6 network, IPv6, and ICMPv6 must be enabled on the IP task. TCP must be also enabled for either IPv6 or IPv4 networks. The IPv6 host application must set its link local and global IPv6 address using the IPv6 API and/or DHCPv6.
The FTP Server and Client are also designed to work with the FileX® embedded file system. If FileX is not available, the host developer can implement or substitute their own file system along the guidelines suggested in filex_stub.h by defining each of the services listed in that file.
The FTP Client portion of the NetX FTP package has no further requirements.
FTP File Names
FTP file names should be in the format of the target file system, usually FileX. They should be NULL terminated ASCII strings, with full path information if necessary. There is no specified limit for the size of FTP file names in the NetX FTP implementation. The packet pool payload size should be able to accommodate the maximum path and file name.
FTP Client Commands
The FTP has a simple mechanism for opening connections and performing file and directory operations. There is basically a set of standard FTP commands that are issued by the Client after a connection has been successfully established on the TCP well-known port 21. The following shows some of the basic FTP commands. Note that the only difference when FTP runs over IPv6 is that the PORT command is replaced with the EPRT command:
FTP Client Commands
| FTP Command | Meaning |
|---|---|
| CWD path | Change working directory. |
| DELE filename | Delete specified file name. |
| EPRT ip_address, port | Provide IPv6 address and Client data port. |
| LIST directory | Get directory listing. |
| MKD directory | Make new directory. |
| NLST directory | Get directory listing. |
| NOOP | No operation, returns success. |
| PASS password | Provide password for login. |
| PORT ip_address,port | Provide IP address and Client data port. |
| PWD path | Pickup current directory path. |
| QUIT | Terminate Client connection. |
| RETR filename | Read specified file. |
| RMD directory | Delete specified directory. |
| RNFR oldfilename | Specify file to rename. |
| RNTO newfilename | Rename file to supplied file name. |
| STOR filename | Write specified file. |
| TYPE I | Select binary file image. |
| USER username | Provide username for login. |
FTP Server Responses
Once the FTP Server processes the Client request, it returns a 3-digit coded response in ASCII followed by optional ASCII text. The numeric response is used by the FTP Client software to determine whether the operation succeeded or failed. The following list shows various FTP Server responses to Client requests:
First Numeric Field
| First Numeric Field | Meaning |
|---|---|
| 1xx | Positive preliminary status – another reply coming. |
| 2xx | Positive completion status. |
| 3xx | Positive preliminary status – another command must be sent. |
| 4xx | Temporary error condition. |
| 5xx | Error condition. |
Second Numeric Field
| Second Numeric Field | Meaning |
|---|---|
| 0xx | Syntax error in command. |
| 1xx | Positive preliminary status – another reply coming. |
| 2xx | Positive completion status. |
| 3xx | Positive preliminary status – another command must be sent. |
| 4xx | Temporary error condition. |
| 5xx | Error condition. |
FTP Write Requests:
FTP Authentication
Whenever a FTP connection takes place, the Client must provide the Server with a username and password. Some FTP sites allow what is called Anonymous FTP, that allows FTP access without a specific username and password. For this type of connection, anonymous should be supplied for username and the password should be a complete e-mail address.
You are responsible for supplying the NetX FTP Client and the NetX Duo FTP Client with login and logout authentication routines. These are supplied during the nxd_ftp_server_create and nx_ftp_server_create services and called from the password processing. The difference between the two is the nxd_ftp_server_create input function pointers to login and logout authenticate functions expect the NetX Duo address type NXD_ADDRESS. This data type holds both IPv4 or IPv6 address formats, making this function the Duo service supporting both IPv4 and IPv6 networks. The nx_ftp_server_create input function pointers to login and logout authenticate functions expect ULONG IP address type. This function is limited to IPv4 networks. You are encouraged to use the Duo service whenever possible.
If the login function returns NX_SUCCESS, the connection is authenticated and the FTP operations are allowed. Otherwise, if the login function returns something other than NX_SUCCESS, the connection attempt is rejected.
FTP Multi-Thread Support
RFCs
FTP Constraints
The FTP standard has many options regarding the representation of file data. NetX FTP does not implement switch options like ls – al. The NetX FTP Server and the NetX Duo FTP Server expect to receive requests and their arguments in a single packet rather than consecutive packets.
Like UNIX implementations, NetX FTP assumes the following file format constraints:
This section describes how to include either or both the NetX and NetX Duo FTP Client module in an application using the SSP configurator.
To add the NetX/NetX Duo FTP Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo FTP Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_dns0 NetX FTP Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX FTP Client |
| g_dns0 NetX Duo FTP Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo FTP Client |
When the NetX and/or NetX Duo FTP 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.
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:
Additionally, in the stack above, the FileX stack has also not been populated yet. There are multiple possible selections for the FileX module; 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/NetX Duo FTP 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.
Configuration Settings for the NetX/NetX Duo FTP Client Module
| ISDE Property | Value | Description |
|---|---|---|
| **TCP socket to use | NX_ANY_PORT | TCP socket to use selection |
| Name | g_ftp_client0 | Module name. |
| TCP socket window size (bytes) | 2048 | TCP socket window size selection |
| Name of generated initialization function | ftp_client_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
** Indicates properties that are only available in NetX Duo.
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.
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. |
** Indicates properties that are only available in NetX Duo.
Configuration Settings for the NetX/NetX Duo FTP Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| FileX support | Enabled, Disabled Default: Enabled | FileX support selection. |
| Control Type of Service | Normal, Minimum delay, Maximum data, Maximum reliability, Minimum cost Default: Normal | Control type of service selection. |
| Data Type of Service | Normal, Minimum delay, Maximum data, Maximum reliability, Minimum cost Default: Normal | Data type of service selection. |
| Fragmentation option | Don't fragment, Fragment okay Default: Don't fragment | Fragment option selection. |
| Time to live | 128 | Time to live selection. |
| Duration between client inactivity check (seconds) | 60 | Duration between client inactivity check selection. |
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. |
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. |
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/NetX Duo FTP Client module in a typical application are:
Step 1. Create FTP Client using the nx_ftp_client_create API.
Step 2. Connect to the FTP Server using the nx_ftp_client_connect API.
The following steps can be used for writing to a file.
Step 3. Open a file using the nx_ftp_client_open API.
Step 4. Write to a file as needed using the nx_ftp_client_write API.
Step 5. Close a file using the nx_ftp_client_close API.
The following steps can be taken for reading from a file.
Step 6. Open a file using the nx_ftp_client_open API.
Step 7. Read from a file as needed using the nx_ftp_client_read API.
Step 8. Close a file using the nx_ftp_client_close API.
The following figure illustrates common steps in a typical operational flow diagram:
