 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Hypertext Transfer Protocol (HTTP) is a protocol designed for transferring content on the web. HTTP is a simple protocol that utilizes reliable Transmission Control Protocol (TCP) services to perform its content-transfer function. All operations on the web utilize the HTTP protocol.
Unsupported Features
Multi-thread support has not been tested in this version of SSP. Multi-part support has not been tested in this version of SSP.
The NetX HTTP Client module defines APIs for creating, deleting, getting and putting. 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 HTTP Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_http_client_create | nx_http_client_create(&my_client, "my client", &ip_0, &pool_0, 100);Create an HTTP Client Instance. |
| nx_http_client_delete | nx_http_client_delete(&my_client);Delete an HTTP Client instance. |
| nx_http_client_get_start | nx_http_client_get_start(&my_client, IP_ADDRESS(1,2,3,5), "/TEST.HTM",NX_NULL, 0, "myname", "mypassword", 1000);Start an HTTP GET request (IPv4 only). |
| nxd_http_client_get_start** | nxd_http_client_get_start(&my_client, &server_ip_address, "/TEST.HTM",NX_NULL, 0, "myname", "mypassword", 1000);Start an HTTP GET request (IPv4 or IPv6) |
| nx_http_client_get_packet | nx_http_client_get_packet(&my_client, &next_packet, 1000);Get next resource data packet. |
| nx_http_client_put_start | nx_http_client_put_start(&my_client, IP_ADDRESS(1, 2, 3, 5),"/TEST.HTM", "myname", "mypassword", 20, NX_WAIT_FOREVER);Start an HTTP PUT request (IPv4 only). |
| nxd_http_client_put_start** | nxd_http_client_put_start(&my_client, &server_ip_address,"/client_test.htm", "name", "password", 103, 50);Start an HTTP PUT request (IPv4 or IPv6) |
| nx_http_client_put_packet | nx_http_client_put_packet(&my_client, packet_ptr, NX_WAIT_FOREVER);Send next resource data packet. |
| nx_http_client_set_connect_port** | nx_http_client_set_connect_port(&g_http_client0, 81);Connect to the HTTP server port on the specified port. Intended for situations where the Client must use another port beside 80. |
**This API is only available in NetX Duo HTTP Client. For definitions of 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 HTTP function |
| NX_CALLER_ERROR** | Invalid caller of the service |
| NX_PTR_ERROR** | Invalid HTTP, ip_ptr, or packet pool pointer |
| NX_INVALID_PORT** | Invalid port input |
| NX_HTTP_POOL_ERROR | Invalid payload size in packet pool |
| NX_HTTP_NOT_READY | HTTP Client not in ready state |
| NX_HTTP_PASSWORD_TOO_LONG | Password exceeded expected length |
| NX_HTTP_AUTHENTICATION_ERROR | Invalid name and/or password |
| NX_HTTP_FAILED | HTTP client error communicating with the HTTP server |
| NX_HTTP_GET_DONE | HTTP client get packet operation is complete |
| NX_HTTP_BAD_PACKET_LENGTH | Invalid packet received - length incorrect |
| NX_HTTP_INCOMPLETE_PUT_ERROR | Server responds before PUT is complete |
| NX_HTTP_REQUEST_UNSUCCESSFUL_CODE | Received an error code instead of 2xx from server |
| NX_HTTP_PASSWORD_TOO_LONG | Password exceeded expected length |
| NX_HTTP_USERNAME_TOO_LONG | Username exceeded expected length |
| NX_SIZE_ERROR | Invalid total size of resource in PUT request |
| NX_INVALID_PACKET | Invalid TCP packet; not enough room for packet header |
**These are error codes which are only returned if error checking is enabled. Refer to the NetX User's Guide for the Renesas Synergy Platform or NetX Duo User's Guide for the Renesas Synergy Platform for more details on error‑checking services in NetX and NetX Duo, respectively.
The NetX HTTP Client module creates an IP instance which carries out NetX operations and enables TCP services in the NetX library. It creates the HTTP client instance and a TCP socket for sending and receiving HTTP messages to the server listening on port 80. The HTTP client requires a packet pool; the module can supply one by sharing the IP default packet pool (g_packet_pool0), or by creating a new one. The minimum packet payload is set by the Minimum packet size property of the HTTP client instance. This packet pool is used by the HTTP client only to transmit packets, so the packet-pool size and payload can be optimized based on the expected size and the number of HTTP client packets sent out.
The NetX Duo HTTP Client supports both IPv4 and IPv6 connections; if the HTTP client needs to use IPv6 to connect to a server, make sure the NetX Duo IPv6 Support property is enabled in the NetX Duo Source element. It may also be necessary to enable ICMPv6 checksum computation for the underlying ICMPv6 protocols; to do so, set the Checksum computation support on transmitted ICMPv6 packets and Checksum computation support on received ICMPv6 packets properties of the NetX Duo source element to be enabled. (If the host hardware automatically computes ICMPv6 checksums, these can be left disabled.) Make sure the IPv6 Global Address of the Client host is set in the IP instance element; NetX Duo will do the necessary processing to enable IPv6 and ICMPv6 services required for IPv6 underlying protocols.
Once the HTTP client has a valid IP address, it can make PUT and GET requests. To upload packets, use the nx_http_client_put_start service. This service has a server IP address input, so the HTTP client can connect to the server. If the data to upload exceeds more than one packet, the application uses the nx_http_client_put_packet service until all the data is uploaded. To download data from the server, use the nx_http_client_get_start service; this requires the server IP address so the HTTP client can connect to the server. If the data to download exceeds more than one packet, the application uses the nx_http_client_get_packet service until all the data is downloaded; this is indicated by getting the NX_HTTP_GET_DONE status return.
In the NetX Duo HTTP Client module, the application can use the nxd_http_client_put_start for IPv4 connections, and the nxd_http_client_get_start service for either IPv4 or IPv6 connections; nx_http_client_put_start and nx_http_client_get_start services are also available in the Net Duo HTTP Client. The nx_http_client_put_packet and nx_http_client_get_packet services do not require an HTTP Server IP address, so there is no Duo-equivalent APIs for these services.
In NetX Duo HTTP Client, the nx_http_client_set_connect_port service is available for those circumstances where the HTTP client needs to connect to the HTTP server on a port other than the default of Port 80.
HTTP Server Responses
Once the HTTP server processes the client command, it returns an ASCII response string that includes a 3-digit numeric-status code listed in the following table. The numeric response is used by the HTTP client software to determine whether the operation succeeded or failed.
Various HTTP server responses to client commands
| Numeric Field | Meaning |
|---|---|
| 200 | Request was successful |
| 400 | Request was not formed properly |
| 401 | Unauthorized request, client needs to send authentication |
| 404 | Specified resource in request was not found |
| 500 | Internal HTTP server error |
| 501 | Request not implemented by HTTP server |
| 502 | Service is not available |
For example, a successful client request to PUT the file test.htm is responded to with the message HTTP/1.0 200 OK.
This section describes how to include either or both the NetX and NetX Duo HTTP Client module in an application using the SSP configurator.
To add the NetX/NetX Duo HTTP Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo HTTP Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_dns0 NetXHTTP Client | Threads | New Stack> X-Ware> NetX> Protocols> NetXHTTP Client |
| g_dns0 NetX Duo HTTP Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo HTTP Client |
When the NetX and/or NetX Duo HTTP 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 HTTP 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 HTTP Client Module
| ISDE Property | Value | Description |
|---|---|---|
| Minimum packet size (bytes) | 300 | Minimum packet size selection |
| Operation timeout (seconds) | 10 | Operation timeout selection |
| *Maximum password length (bytes) | 20 | Maximum password length selection |
| *Maximum username length (bytes) | 20 | Maximum username length selection |
| Name | g_http_client0 | Module name |
| TCP socket window size (bytes) | 1024 | TCP socket window size selection |
| Name of generated initialization function | http_client_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
*Indicates properties that are not 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 HTTP Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Type of Service | Normal, Minimum delay, Maximum data, Maximum reliabililty, Minimum cost Default: Normal | Type of service UDP requests selection |
| Fragmentation option | Don't fragment, Fragment okay Default: Don't fragment | Fragment option selection |
| Time to live | 128 | Time to live selection |
| MD5 Support | Enable, Disable Default: Disable | MD5 support selection |
| Maximum resource name length (bytes) | 40 | Packet queue depth selection |
| **Maximum password length (bytes) | 20 | Maximum password length selection |
| **Maximum username length (bytes) | 20 | Minimum username length 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 |
Configuration Settings for the NetX MD5 Instance
| ISDE Property | Value | Description |
|---|---|---|
| No configurable properties |
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 HTTP Client module in a typical application are:
1. Wait for valid IP address and network driver initialization using the nx_ip_status_check API.
2. Upload data to the HTTP server with the nx_http_client_put_start API. For IPv6 connections, use the nxd_http_client_put_start API in the NetX Duo HTTP Client (which can also be used for IPv4 connections).
3. Download data from the HTTP server with the nx_http_client_get_start API. For IPv6 connections, use the nxd_http_client_get_start API in the NetX Duo HTTP Client (which can also be used for IPv4 connections).
4. Delete the HTTP client with the nx_http_client_delete API. (Note that the packet pool can also be deleted if it's not used elsewhere in the application.)
The following figure illustrates common steps in a typical operational flow diagram:
