 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Simple Mail Transfer Protocol (SMTP) is a protocol for sending mail across networks and the Internet and utilizes the reliable Transmission Control Protocol (TCP) services to perform its content transfer function.
Unsupported Features
Multiple network interface has not been tested for NetX Duo in this version of SSP.
The NetX SMTP Client defines APIs for creating, deleting and sending mail. 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 SMTP Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_smtp_client_create | nxd_smtp_client_create(&demo_client, &client_ip, &client_packet_pool,USERNAME,PASSWORD, FROM_ADDRESS, LOCAL_DOMAIN, CLIENT_AUTHENTICATION_TYPE, server_ip_address, SERVER_PORT);Create an SMTP Client Instance. |
| **nxd_smtp_client_create | nxd_smtp_client_create(&demo_client, &client_ip, client_packet_pool, USERNAME, PASSWORD, from_address, client_domain, authentication_type, &server_address, port);Create an SMTP Client instance for IPv4 or IPv6 networks. |
| nx_smtp_client_delete | nx_smtp_client_delete(&demo_client);Delete an SMTP Client instance. |
| nx_smtp_mail_send | nx_smtp_mail_send(&demo_client, recipient_address, NX_SMTP_MAIL_PRIORITY_NORMAL, SUBJECT_LINE, MAIL_BODY, strlen(MAIL_BODY));Create and send an SMTP Mail item. |
**This API is only available in NetX Duo SMTP Client. Please refer to the NetX Duo User Guide for the Renesas Synergy™ Platform for definition of NetX Duo specific data types.
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | SMTP call successful |
| NX_CALLER_ERROR* | Invalid caller of this service |
| NX_PTR_ERROR* | Invalid input pointer parameter |
| NX_SMTP_INVALID_PARAM* | Invalid non-pointer input |
| NX_IP_ADDRESS_ERROR* | Invalid IP address type |
| NX_SMTP_CLIENT_NOT_INITIALIZED | SMTP Client instance initialized for SMTP session |
A NetX IP instance is created and enabled for TCP services. The SMTP Client is created with a previously created packet pool as input, as well as information from the host, including the host's email address, mail domain, authentication type and server IP address** (Server IPv4 Address in the SMTP Client Module configuration table found below) and port (Server port in the SMTP Client Module configuration table found below). Server port defaults to the well-known SMTP port 25.
The payload of the packet pool used by the SMTP Client should be optimized to the typical SMTP data size plus network headers (IP, TCP and physical frame). For messages exceeding that packet payload, the SMTP Client will allocate additional packets for messages that exceed the packet payload. In the Packet Pool Instance configuration table found below, the setting for the packet pool payload defaults to 512 and the number of packets defaults to 16.
NetX SMTP Authentication
The creation of the SMTP Client also requires setting Authentication type, Client Name and Client Password (In the SMTP Client Module configuration table found below). Client Names can either be fully qualified domain names or display user names.
Authentication is a way for SMTP Clients to prove their identity to the SMTP Server and have their mail delivered as trusted users. Most commercial SMTP Servers require that Clients be authenticated.
Typically, authentication data consists of the sender's username and password. During an authentication challenge, the Server prompts for this information and the Client responds by sending the requested data in encoded format. The Server decodes the data and attempts to find a match in its user database. If found, the Server indicates the authentication is successful.
There are two flavors of authentication: basic and digest. Digest is not supported in the current NetX SMTP Client, and will not be discussed here. Basic authentication is equivalent to the name and password authentication described above. In SMTP basic authentication, the name and passwords are base64 encoded. The advantage of basic authentication is its ease of implementation and widespread use. The main disadvantage of basic authentication is name and password data is transmitted openly in the request.
Plain Authentication
The NetX SMTP Client sends an AUTH command with the PLAIN parameter. The NetX SMTP Server will indicate if it supports this type of authentication. If so, the Client replies with a single base64 encoded username and password message to the Server. The Server responds with a status code indicating if the Client authentication is successful or not.
Login Authentication
The NetX SMTP Client sends an AUTH command with the LOGIN parameter. The SMTP Server will indicate if it supports this type of authentication and start the authentication 'challenge'. It sends a base64 encoded prompt back to the Client which is typically "Username". The Client decodes the prompt, and replies with a base64 encoded username. If the Server accepts the Client username, it sends out a base64 encoded prompt for the Client password. The Client responds with a base64 encoded password. The Server will indicate if Client authentication is successful.
No Authentication
Some SMTP Servers are configured without authentication. If so, their 250 response to the Client EHLO message will not list any authentication types. However, no authentication types listed does not necessarily mean the Server does not require or support authentication. If the Client is configured for PLAIN or LOGIN authentication in this situation, the NetX Client thread task will default to PLAIN. If the Client is configured for NONE, the authentication step is skipped and the SMTP state advances to the MAIL state.
Note that if the Client is configured for no authentication and the SMTP Server does support authentication, the Client authentication type is switched to PLAIN.
Sending a Mail Message
After the SMTP Client is created, the SMTP Client application can start sending messages by calling the nx_smtp_mail_send service. Each time this service is called, NetX SMTP Client creates a new TCP connection with the SMTP server and begins an SMTP session. In this session, the Client sends a series of commands to the SMTP Server as part of the SMTP protocol, including passing authentication, and culminating in sending out the actual mail message. The TCP connection is then terminated, regardless of the outcome of the SMTP session. If the mail message is successfully sent, NX_SUCCESS is returned. If not the error code reflects either the SMTP Client error, e.g. failing authentication, or the underlying NetX error, e.g. failing to connect to the server.
After an SMTP session, regardless of success or failure in sending out a mail message, the SMTP Client is returned to the 'initial' state, and ready for another SMTP session (with the same SMTP server).
This section describes how to include either or both the NetX and NetX Duo SMTP Client module in an application using the SSP configurator.
To add the NetX/NetX Duo SMTP Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo SMTP Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_smtp_client0 NetX SMTP Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX SMTP Client |
| g_smtp_client0 NetX Duo SMTP Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo SMTP Client |
When the NetX and/or NetX Duo SMTP 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:
The NetX/NetX Duo SMTP 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 SMTP Client Module
| ISDE Property | Value | Description |
|---|---|---|
| TCP window size (bytes) | 1460 | TCP window size selection |
| Packet allocation timeout (seconds) | 2 | Packet allocation timeout selection |
| TCP socket connect timeout (seconds) | 10 | TCP socket connect timeout selection |
| TCP socket disconnect timeout (seconds) | 5 | TCP socket disconnect timeout selection |
| Server greeting reply timeout | 10 | Server greeting reply timeout selection |
| Command timeout (seconds) | 10 | Command timeout selection |
| Mail data request timeout (seconds) | 30 | Mail data request timeout selection |
| TCP socket send completion timeout (seconds) | 5 | TCP socket send completion timeout selection |
| Server challenge maximum string length (bytes) | 200 | Server challenge maximum string length selection |
| Maximum password length (bytes) | 20 | Maximum password length selection |
| Maximum username length (bytes) | 40 | Maximum username length selection |
| Name | g_smtp_client0 | Name selection |
| **Use server address type | IPv4, IPv6 Default: IPv6 | Use server address type selection |
| Server IPv4 Address (use commas for separation) | 192, 168, 0, 2 | Server IPv4 Address selection |
| **Server IPv6 Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | Server IPv6 Address selection |
| Server Port | 25 | Server Port selection |
| Client Name | username | Client Name selection |
| Client Password | password | Client Password selection |
| Client Address | username@domain.com | Client Address selection |
| Client Domain | domain.com | Client Domain selection |
| Authentication Type | Login | Authentication Type selection |
| Name of generated initialization function | smtp_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 stack modules can be desirable. For example, it might be useful to select different addresses for the Ethernet port. 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 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) | 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 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 selection |
** Indicates properties that are only available in NetX Duo.
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 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 SMTP Client module in a typical application are:
nx_smtp_mail_send.nx_smtp_client_delete.The following figure illustrates common steps in a typical operational flow diagram:
