Webserver Example

Scope

This example demonstrates how to integrate an HTML webserver using the Ethernet over EtherCAT (EoE) mailbox protocol and LWIP. To learn more about EoE, please refer to the Ethernet over EtherCAT FAQ.

Related Files

• ecSubDeviceWebserver.c
• ecSubDeviceWebserver.h
• EtherCAT_SubDevice_webserver.c
• ESL_eoeDemo.c
• ESL_eoeDemoData.h

LWIP

LWIP is a Lightweight TCP/IP stack written in ANSI C that provides the following features:

• IPv4 and IPv6 with UDP, TCP, ICMP and IGMP
• Ethernet and IPv4/IPv6 over IEEE 802.3
• DNS
• SNTP
• DHCP
• UDP and TCP SOCKET API
• IPv4 and IPv6 multicast

The LWIP project is distributed under the BSD-3-Clause license. The project can be downloaded here. It is also included in the MCU+SDK.

LWIP Settings

The LWIP settings for the Webserver Example can be found in the files located in the source/industrial_comms/ethercat_subdevice/stack/lwip/lwip-config/ directory:

• lwiphooks.h: Contains hooks into the LWIP stack that allow the application to interact with it.
• lwipopts.h: Contains configuration options for the LWIP stack to enable/disable features and optimize memory usage.
• lwippools.h: Contains memory pool definitions used by the LWIP stack for different protocols.

More information can be found in the official LWIP documentation. Changes to these files require a rebuild of the LWIP libraries using the provided makefile:

make -s -f makefile.amxxx.r5f

The resulting libraries will be placed in the /lib folder.

LWIP Debugging

LWIP debugging can be enabled in the lwipopts.h file by setting the LWIP_DEBUG macro to a non-zero value and configuring the debug level:

#define LWIP_DEBUG          1
 
#ifdef LWIP_DEBUG
#define LWIP_DBG_MIN_LEVEL         LWIP_DBG_LEVEL_ALL
#define PPP_DEBUG                  LWIP_DBG_ON
#define MEM_DEBUG                  LWIP_DBG_ON
#define MEMP_DEBUG                 LWIP_DBG_ON
// Additional debug options...
#endif

Webserver Example Implementation

The Webserver example extends the Simple example by creating:

• A dedicated webserver thread that initializes and runs the HTTP server
• EoE callback handlers for processing incoming Ethernet frames and network settings
• LWIP integration for webserver functionality
• EoE APIs for handling EoE settings and messages

After running the application and configuring TwinCAT (or another EoE-capable MainDevice), you can connect to the webserver by entering the SubDevice's IP address in a web browser. The server supports three different pages:

• Main page (xxx.xxx.xxx.xxx/main.html): Displays a simple welcome page
• Favicon (xxx.xxx.xxx.xxx/favicon.ico): Shows a small Texas Instruments logo
• 404 Error: Displayed for any other requested URL

Implementation Overview

The EoE implementation consists of two main components:

1. EoE callback handlers registered in the main application that process incoming EoE frames
2. A dedicated webserver task that initializes the network interface and handles HTTP requests

EC_SLV_APP_SS_loopTask

The main application task registers the EoE callbacks:

• EC_API_SLV_EoE_cbRegisterReceiveHandler: Registers the EC_SLV_APP_EoE_SS_receiveHandler function, which is called when an EoE message with an Ethernet frame is received. The function passes the Ethernet frame to the LWIP network interface for processing.

bool EC_SLV_APP_EoE_SS_receiveHandler(void *pContext, uint16_t *pData, uint16_t size)
{
    LOCK_TCPIP_CORE();
    struct pbuf *p = pbuf_alloc(PBUF_RAW, size, PBUF_POOL);
 
    DebugP_assert(p != NULL);
    pbuf_take(p, (const void *)pData, size);
 
    if (gnetif.input(p, &gnetif) != ERR_OK)
    {
        pbuf_free(p);
        p = NULL;
    }
    UNLOCK_TCPIP_CORE();
 
    return true;
}

• EC_API_SLV_EoE_cbRegisterSettingIndHandler: Registers the EC_SLV_APP_EoE_SS_settingIndHandler function, which is called when an EoE message with network settings is received. The function applies the received settings to the LWIP network interface.

bool EC_SLV_APP_EoE_SS_settingIndHandler(void *pContext, uint16_t *pMac, uint16_t *pIp, uint16_t *pSubNet, uint16_t *pDefaultGateway, uint16_t *pDnsIp)
{
    ip4_addr_t ip;
    ip4_addr_t subnet;
    ip4_addr_t gateway;
    ip4_addr_t dns;
 
    eoeContext_s.settingsReceived = 1;
 
    // Apply MAC address if valid
    if (pMac != NULL && (pMac[0] | pMac[1] | pMac[2]) != 0)
    {
        gnetif.hwaddr[0] = pMac[0] >> 8;
        gnetif.hwaddr[1] = pMac[0] & 0xFF;
        gnetif.hwaddr[2] = pMac[1] >> 8;
        gnetif.hwaddr[3] = pMac[1] & 0xFF;
        gnetif.hwaddr[4] = pMac[2] >> 8;
        gnetif.hwaddr[5] = pMac[2] & 0xFF;
    }
 
    // Convert network settings to LWIP format
    IP4_ADDR(&ip,
        pIp[0] & 0xFF, pIp[0] >> 8,
        pIp[1] & 0xFF, pIp[1] >> 8);
 
    IP4_ADDR(&subnet,
        pSubNet[0] & 0xFF, pSubNet[0] >> 8,
        pSubNet[1] & 0xFF, pSubNet[1] >> 8);
 
    IP4_ADDR(&gateway,
        pDefaultGateway[0] & 0xFF, pDefaultGateway[0] >> 8,
        pDefaultGateway[1] & 0xFF, pDefaultGateway[1] >> 8);
 
    IP4_ADDR(&dns,
        pDnsIp[0] & 0xFF, pDnsIp[0] >> 8,
        pDnsIp[1] & 0xFF, pDnsIp[1] >> 8);
 
    // Apply settings to network interface
    LOCK_TCPIP_CORE();
    netif_set_addr(&gnetif, &ip, &subnet, &gateway);
    UNLOCK_TCPIP_CORE();
 
    return true;
}

EC_SLV_APP_EoE_SS_Task

The webserver task performs the following steps:

1. Network Interface Initialization: Initializes the virtual network interface with netif_if_init()
   • Creates a semaphore for LWIP initialization
   • Initializes the TCP/IP stack with tcpip_init()
   • Adds the network interface with netif_add()
   • Configures the interface with MAC address, ARP handling, and output function
2. Webserver Initialization: Sets up the HTTP server with EC_SLV_APP_EoE_SS_initializeWebserver()
   • Creates a socket with socket()
   • Binds the socket to port 80 with bind()
   • Starts listening for connections with listen()
3. HTTP Request Handling: Enters a loop to process incoming connections
   • Accepts connections with accept()
   • Receives data with recv()
   • Processes GET requests with EC_SLV_APP_EoE_SS_WebSrvProcessGetAndRespond()
   • Sends appropriate responses based on the requested URL
   • Closes the connection with shutdown() and close()

Frame Handling Flow

When an EoE frame is received:

1. The EtherCAT stack invokes the registered callback EC_SLV_APP_EoE_SS_receiveHandler
2. The callback allocates a LWIP packet buffer and copies the frame data
3. The frame is passed to the LWIP stack via gnetif.input()
4. LWIP processes the frame according to the protocol (TCP/IP, UDP, etc.)
5. For HTTP requests, the webserver task handles the incoming connection

Thread Safety

The EoE implementation uses LOCK_TCPIP_CORE() and UNLOCK_TCPIP_CORE() macros to ensure thread safety when accessing the LWIP stack. These macros protect critical sections of code that interact with the network interface.

Error Handling

The EoE implementation includes robust error handling for network operations:

• EC_SLV_APP_EoE_SS_WebSrvStrError() converts error codes to human-readable strings
• EC_SLV_APP_EoE_SS_WebSrvIsFatalErr() distinguishes between fatal and non-fatal errors
• Error conditions are logged for debugging purposes

MAC Address Management

The EoE implementation can use MAC addresses from different sources:

1. MAC address received from the EtherCAT MainDevice via EoE settings
2. MAC address stored in EEPROM (retrieved using EC_SLV_APP_EEP_getMacAddress)
3. Default MAC address (all zeros) if other sources are unavailable

Debugging

The source code contains debug print statements that can be enabled by defining the EOE_DEBUG_PRINTS macro in ESL_eoeDemo.h. These prints provide detailed information about:

• EoE message reception and processing
• Network interface initialization
• Webserver operation and connections
• Error conditions and handling

Testing and Troubleshooting

When testing the EoE functionality, consider the following:

1. Ensure that the EtherCAT MainDevice is configured to support EoE
2. Verify that the IP address, subnet mask, and gateway settings are correct
3. Use Wireshark to capture and analyze EoE traffic with these useful filters:
   • ecat_mailbox.eoe (EoE Fragment)
   • ecat_mailbox.eoe.fragment (EoE Fragment Header)
   • ecat_mailbox.eoe.fraghead (EoE Fragment Data)

For more filters, refer to the Wireshark EtherCAT Mailbox Filter Reference.

Common issues include:

• Incorrect network settings
• Firewall blocking connections
• MAC address conflicts
• Insufficient memory for LWIP buffers