 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Hypertext Transfer Protocol (HTTP) utilizes reliable Transmission Control Protocol (TCP) services to perform its content transfer function; all operations on the Web utilize the HTTP protocol. The NetXTM Duo HTTP Server accommodates both IPv4 and IPv6 networks, while the NetXTM HTTP Server only supports IPv4 communications. IPv6 does not directly affect the HTTP protocol; however, some differences with the NetX HTTP Server are necessary to accommodate IPv6 and are noted in this document.
Unsupported Features
HTTP Insert GMT Date Header Callback has not been tested in this version of SSP. HTTP Cache Info Get Callback has not been tested in this version of SSP.
The NetX HTTP Server module defines APIs for creating, deleting, generating response packets, response sending and getting information from a received packet. 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 Server Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_http_server_cache_info_callback_set | nx_http_server_cache_info_callback_set(&my_server, cache_info_get);Set callback to retrieve age and last modified date of specified URL. |
| nx_http_server_callback_data_send | nx_http_server_callback_data_send(server_ptr, "HTTP/1.0 200 rnContent-Length: 103rnContent-Type: text/htmlrnrn",63);nx_http_server_callback_data_send(server_ptr, "<HTML>rn<HEAD><TITLE>NetX HTTP Test </TITLE></HEAD>rn <BODY>rn<H1>NetX Test Page </H1>rn</BODY>rn</HTML>rn", 103);Send HTTP data from callback function. |
| nx_http_server_callback_generate_response_header | nx_http_server_callback_generate_response_header (server_ptr, &packet_ptr, status_code, content_length, content_type, additional_header);Create response header in callback functions. |
| nx_http_server_callback_packet_send | nx_http_server_callback_packet_send(server_ptr, packet_ptr);Send an HTTP packet from an HTTP callback. |
| nx_http_server_callback_response_send | nx_http_server_callback_response_send(server_ptr,"HTTP/1.0 404 ", "NetX HTTP Server unable to find file: ", resource);Send response from callback function. |
| nx_http_server_content_get | nx_http_server_content_get(server_ptr, packet_ptr, 0, my_buffer, 100, &actual_size);Get content from the request. |
| nx_http_server_content_get_extended | nx_http_server_content_get_extended(server_ptr, packet_ptr, 0, my_buffer, 100, &actual_size);Get content from the request; supports empty (zero Content Length) requests. |
| nx_http_server_content_length_get | nx_http_server_content_length_get(packet_ptr);Get length of content in the request. Length is the status return value. A length of zero indicates an error. |
| nx_http_server_content_length_get_extended | nx_http_server_content_length_get_extended(packet_ptr, &content_length);Get length of content in the request; supports empty (zero Content Length) requests. |
| nx_http_server_create | nx_http_server_create(&my_server, "my server", &ip_0, &ram_disk, stack_ptr, stack_size, &pool_0, my_authentication_check, my_request_notify);Create an HTTP Server instance. |
| nx_http_server_delete | nx_http_server_delete(&my_server);Delete an HTTP Server instance. |
| nx_http_server_get_entity_content | nx_http_server_get_entity_content(server_ptr, &packet_ptr, &offset, &length);Return size and location of entity content in URL. |
| nx_http_server_get_entity_header | nx_http_server_get_entity_header(server_ptr, &packet_ptr, entity_header_buffer, buffer_size);Extract URL entity header into specified buffer. |
| nx_http_server_gmt_callback_set | nx_http_server_gmt_callback_set(&my_server, gmt_get);Set callback to retrieve GMT date and time. |
| **nx_http_server_invalid_userpassword_notify_set | nx_http_server_invalid_userpassword_notify_set(&my_server, invalid_username_password_callback);Set callback for when invalid username and password is received in a Client request. |
| nx_http_server_mime_maps_additional_set | nx_http_server_mime_maps_additional_set(&my_server, &my_mime_maps[0], 2);Define additional mime maps for HTML. |
| nx_http_server_packet_content_find | nx_http_server_packet_content_find(server_ptr, packet_ptr, &content_length);Extract content length in HTTP header and set pointer to start of content data. |
| nx_http_server_packet_get | nx_http_server_packet_get(server_ptr, &packet_ptr);Receive client packet directly. |
| nx_http_server_param_get | nx_http_server_param_get(packet_ptr, 0, param_destination, 30);Get parameter from the request. |
| nx_http_server_query_get | nx_http_server_query_get(packet_ptr, 0, query_destination, 30);Get query from the request. |
| nx_http_server_start | nx_http_server_start(&my_server);Start the HTTP Server. |
| nx_http_server_stop | nx_http_server_stop(&my_server);Stop the HTTP Server. |
| nx_http_server_type_get | nx_http_server_type_get(server_ptr, resource_name, type_string);Extract HTTP type e.g. text/plain from header. Type is returned in the status return. A value of zero indicates an error. |
**This API is only available in NetX Duo HTTP Server. 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 | Successfully performed function |
| NX_PTR_ERROR** | Invalid pointer input |
| NX_CALLER_ERROR ** | Invalid caller of service |
| NX_HTTP_DATA_END | End of request content |
| NX_HTTP_TIMEOUT | HTTP Server timeout in getting next packet of content |
| NX_CALLER_ERROR | Invalid caller of this service |
| NX_HTTP_INCOMPLETE_PUT_ERROR | Improper HTTP header format |
| NX_HTTP_POOL_ERROR | Packet payload of pool is not large enough to contain complete HTTP request |
| NX_HTTP_BOUNDARY_ALREADY_FOUND | Content for the HTTP server internal multipart markers is already found |
| NX_HTTP_NOT_FOUND | Entity header field or client request parameter or multipart component not found |
| NX_HTTP_IMPROPERLY_TERMINATED_PARAM | Client request parameter not properly terminated |
| NX_HTTP_NO_QUERY_PARSED | Server unable to find query in client request |
| NX_HTTP_TIMEOUT | No packet received in the specified wait interval |
| NX_HTTP_ERROR | Internal HTTP Server error |
| NX_HTTP_SERVER_DEFAULT_MIME | No matching extension type found. Return the default MIME type. Not an error status. |
| 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 Server module creates an IP instance that carries out NetX operations and enables it for TCP services in the NetX library; it then creates the HTTP Server instance and TCP socket for listening to client requests on port 80. The HTTP Server requires a packet pool; the module can supply one either by sharing the IP default packet pool (g_packet_pool0) or create a new one. The minimum packet payload is set by the Minimum size of packets in pool property of the HTTP Server module. This packet pool is used by the HTTP Server only to transmit packets, so the packet pool size and payload can be optimized on the expected size and number of HTTP Server packets sent out.
The NetX Duo HTTP Server supports both IPv4 and IPv6 connections. If the HTTP Server has clients desiring to connect over IPv6, make sure the NetX Duo IPv6 Support property is enabled in the NetX Duo Source element. It may 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 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. Thereafter, the NetX Duo does the necessary processing to enable IPv6 and ICMPv6 services required for IPv6 underlying protocols.
The HTTP Server is also designed for use with the FileX® embedded file system.
HTTP Server Responses
When the HTTP Server processes the client command, it returns an ASCII response string that includes a 3-digit numeric status code. The numeric response is used by the HTTP Client software to determine whether the operation succeeded or failed. Following is a list of various HTTP Server responses to client commands:
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.
HTTP Authentication
HTTP authentication is optional and is not required for all web requests. There are two types of authentication, basic and digest. Basic authentication is equivalent to the name and password authentication found in many protocols. In HTTP basic authentication, the name and passwords are concatenated and encoded in the base64 format. The main disadvantage of basic authentication is the name and password are transmitted openly in the request, making it easy for the name and password to be stolen. Digest authentication addresses this problem by never transmitting the name and password in the request. Instead, an algorithm is used to derive a 128-bit key or digest from the name, password, and other information. The NetX HTTP Server supports the standard MD5 digest algorithm.
The HTTP Server authentication callback can decide if a requested resource requires authentication. If authentication is required and the client request did not include the proper authentication, an HTTP/1.0 401 Unauthorized response with the type of authentication required is sent to the client. The client is then expected to form a new request with the proper authentication.
HTTP Authentication Callback
The HTTP Server authentication callback routine is specified by the Name of Authentication Checking Function property of the HTTP Server Thread. This function is called at the beginning of each HTTP Client request.
The callback routine provides the NetX HTTP Server with the username, password, and realm strings associated with the resource and returns the type of authentication necessary. If no authentication is necessary for the resource, the authentication callback should return the value of NX_HTTP_DONT_AUTHENTICATE. If basic authentication is required for the specified resource, the routine should return NX_HTTP_BASIC_AUTHENTICATE. If MD5 digest authentication is required, the callback routine should return NX_HTTP_DIGEST_AUTHENTICATE.
The format of the authenticate callback routine is defined as:
The input parameters are defined as follows:
Input Parameters Definitions
| Parameter | Meaning |
|---|---|
| request_type | Specifies the HTTP Client request, valid requests are defined as: NX_HTTP_SERVER_GET_REQUEST NX_HTTP_SERVER_POST_REQUEST NX_HTTP_SERVER_HEAD_REQUEST NX_HTTP_SERVER_PUT_REQUEST NX_HTTP_SERVER_DELETE_REQUEST |
| resource | Specific resource requested. |
| name | Destination for the pointer to the required username. |
| password | Destination for the pointer to the required password. |
| realm | Destination for the pointer to the realm for this authentication. |
Name, password, and realm pointers are not used if NX_HTTP_DONT_AUTHENTICATE is returned by the authentication callback routine. The HTTP Server developer must ensure that the maximum size of the username and password (defined by the Maximum username length and Maximum password length properties of the NetX HTTP Common) are large enough for the username and password specified in the authentication callback. These are both defaulted to size 20 characters.
HTTP Server Request Notify callback
If a request callback is specified, (the Name of Request Notify Callback Function property of the NetX HTTP Server module) the NetX HTTP Server forwards requests to the specified function after authentication and validity of the client request is completed without errors. The callback should indicate (by the return status) if no more processing of the client request is required (return status NX_HTTP_CALLBACK_COMPLETED), if there was an error in the callback processing, (status is non-zero), or the process was completed successfully and the HTTP Server should continue processing the client request. The format of this callback is:
To disable the request notify callback, set the Name of Request Notify Callback Function property to NULL.
HTTP Invalid Username/Password Callback
The optional Invalid Username/Password callback in the NetX HTTP Server module is invoked if the HTTP Server receives an invalid username-and-password combination in a client request. To set the Invalid Username/Password callback function, use the nx_http_server_invalid_user_password_set service. Note that for NetX Duo HTTP Server module, this takes a NXD_ADDRESS *client_ip_address, while NetX HTTP Server module takes a ULONG client_ip_address.
HTTP Insert GMT Date Header Callback
The NetX HTTP Server supports an optional callback to insert a date header in its response messages. This callback is invoked when the Server responds to a Client PUT or GET request. To set the GMT callback use the nx_http_server_gmt_callback service before starting the NetX HTTP Server thread.
HTTP Cache Info Get Callback
The NetX HTTP Server has an optional callback to request the maximum age and date from the HTTP application for a specific resource. This information is used to determine if the HTTP server sends the entire page in response to a Client Get request. If the if modified since in the Client request is not found or does not match the last modified date returned by the get-cache callback, the entire page is sent. To set a cache callback function, use the nx_http_server_cache_info_callback_set service.
HTTP Multipart Support
Multipurpose Internet Mail Extensions (MIME) was originally intended for the SMTP protocol, but its use has spread to HTTP. MIME allows messages to contain mixed message types (for example, image/jpg and text/plain) within the same message. The NetX HTTP Server has added services to determine content type in HTTP messages containing MIME from the client. To enable multipart support, set the Multipart HTTP requests support property of the NetX HTTP Server module to enable.
This section describes how to include either or both the NetX and NetX Duo HTTP Server module in an application using the SSP configurator.
To add the NetX/NetX Duo HTTP Server module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo HTTP Server Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_http_server0 NetX HTTP Server | Threads | New Stack> X-Ware> NetX> Protocols> NetX HTTP Server |
| g_http_server0 NetX Duo HTTP Server | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo HTTP Server |
When the NetX and/or NetX Duo HTTP Server 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 HTTP Server 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 Server Module
| ISDE Property | Value | Description |
|---|---|---|
| FileX Support | Enable, Disable Default: Enable | FileX support selection |
| Multipart HTTP requests support | Enable, Disable Default: Disable | Multipart HTTP requests support selection |
| Internal thread priority | 16 | Internal thread priority selection |
| Internal thread time slicing interval (bytes) | NetX Default: 1 NetX Duo Default: 2 | Internal thread time slicing interval selection |
| Server socket window size (bytes) | 2048 | Server socket window size selection |
| Server time out (seconds) | 10 | Server time out selection |
| Server time out for accept (seconds) | 10 | Server time out for accept selection |
| Server time out for disconnect (seconds) | 10 | Server time out for disconnect selection |
| Server time out for receive (seconds) | 10 | Server time out for receive selection |
| Server time out for send (seconds) | 10 | Server time out for send selection |
| Maximum size of header field (bytes) | 256 | Maximum size of header field selection |
| Maximum connections in queue | 5 | Maximum connections in queue selection |
| Maximum client user user name length (bytes) | 20 | Maximum client user password length selection |
| Maximum client user password length (bytes) | 20 | Minimum size of packets in pool selection |
| Minimum size of packets in pool (bytes) | 600 | Minimum size of packets in pool selection |
| Name | g_http_server0 | Module name |
| Internal thread stack size (bytes) | 4096 | Internal thread stack size selection |
| Name of Authentication Checking Function | authentication_check | Name of Authentication Checking Function selection |
| Name of Request Notify Callback Function | request_notify | Name of Authentication Checking Function selection |
| Name of generated initialization function | http_server_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, it might be useful to select different IP masks and addresses. 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 Server module in a typical application are:
Auto Generated code to initialize NetX and NetX Duo HTTP Server in the Application (common_data.c)
nx_packet_pool_create APInx_ip_create APInx_arp_enable APInx_tcp_enable APInx_http_server_create APIUser Application Code (<thread>_entry.c)
nx_ip_status_check API.nx_http_server_start API.nx_http_server_stop API.nx_http_server_delete API.Users do not have to worry about auto-generated code. Auto-generated code is included once the user generates the project after configuring the stack. Users only need to write the user application code in the associated file (typically <thread>_entry.c).
The following figure illustrates common steps in a typical operational flow diagram:
