The steps to create a microcontroller application that uses TCP/IP communication are:
- Select RTE Components along with the Network Services that are required for your application.
- Enable the Network Driver and Controller that is integrated in the microcontroller.
- Configure the various Network Components.
- Implement the User Code.
RTE Component Selection
Only a few steps are necessary to complete the RTE Component selection:
- From the Network Component:
- Select Network:CORE that provides the basic functionality required for TCP/IP communication.
- Select your desired Network:Interface. For example, set Network:Interface:Ethernet to '1' for enabling Ethernet communication.
- Select the desired Network Services. For example, select Network:Service:Web Server Compact to create a simple Web Server.
- Select the desired Network Sockets. For example, select Network:Socket:TCP for TCP communication. Usually, you will also select Network:Socket:UDP for stateless communication.
- From the Drivers Component:
- If you do Ethernet communication, select appropriate Ethernet MAC and PHY drivers suitable for your application. For PPP or SLIP communication simply select the UART driver.
- From the Device Component:
- Additional device specific drivers may be required according to the validation output.
- From the CMSIS Component:
- Select the CMSIS:CORE to provide the core interface to the processor.
- Select a suitable CMSIS:RTOS that is a required for the Networking Component.
RTE Component for Networking
Network Driver and Controller Configuration
The Network Device Driver and the Network Controller of the microcontroller need to be correctly configured. This means:
- The Ethernet or UART (for SLIP/PPP) is typically configured in the RTE_Device.h configuration file. While this file provides multiple options, it is typically sufficient to enable the Ethernet/UART related to this driver. Some microcontrollers may require settings that are related to a physical layer interface (PHY).
- The Network Controller of the microcontroller typically needs specific clock settings. Consult the user's guide of the microcontroller to understand the requirements. Alternatively you may copy the setup of a Network example that is provided for various evaluation boards.
Network Configuration
Network Core
The Network Core configuration file Net_Config.c is listed in the Project Window under the file group "Network" and contains the setting for the Local Host Name. This is a name under which the network device can be accessed on a local area network (LAN). It usually requires a DHCP server to be present in the LAN. This name is very useful if you don't know the IP address that has been assigned to your device by the DHCP server.
Network Interface
The Network Interface configuration file Net_Config_Interface_0.c is also listed under the file group "Network". It contains the general IP address settings. You also need to specify the hardware driver number for the used interface. In case of Ethernet for example, this is usually 0. But if you are using SLIP or PPP over a serial connection, you need to specify the hardware driver number of the exact UART you wish to use. Special settings for the different interfaces are as follows:
- For Ethernet you can edit the settings for ARP, IGMP, NetBIOS, and DHCP.
- Additional fields for PPP include Login Authentication and other PPP specific settings.
- For SLIP you can only select to Use Default Gateway on the remote network.
Network Socket
The three different socket types have specific settings that are specified in Net_Config_BSD.h, Net_Config_TCP.h, and Net_Config_UDP.h. Usually, the needs of most applications are served by using the default settings. If you need more information on the settings, please visit the reference section.
Network Service
The configuration files for all the Network Services follow the same naming convention as the other configuration files. These files contain all necessary settings for the Services.
User Code Implementation
User code template files provide access to all functions that are required to communicate over the Network. The available functions are explained in the Reference section of the Network Component. These routines can be adapted to the needs of the microcontroller application, in case more functionality is needed.
Runtime Configuration
Each embedded Ethernet device must have a unique MAC address, IP address, and hostname. This is very important when multiple devices are connected to the same LAN. Otherwise, network collisions might occur, network communications on a local LAN might be disturbed, and the system might not work.
You can use the same application code for serial production of embedded devices. The runtime configuration feature allows you to read configuration parameters from the EEPROM and configure the Ethernet network interface for each embedded device differently.
- The MAC address is written to the Ethernet controller registers when the controller initializes (when calling the function net_initialize). For this reason, the variable own_hw_adr[6] must be set before the system initializes.
- The Ethernet interface configuration parameters must be set after the system initializes. The structure localm[0] can simply be overwritten with new values.
- The local hostname can be changed by overwriting the default value, which is set in the Net_Config.c system configuration file. The local host name accesses the embedded system by the name instead of the IP address.
- Dynamic Host Configuration can be disabled at runtime. In this case, user provided network parameters defined in the Net_Config.c configuration file are used instead. The DHCP Client can be disabled by calling the function dhcp_disable after the system initializes. The DHCP Client must be enabled in the configuration so that the DHCP Client code links to the application code.
- Note
- You can change the localm Ethernet IP parameters also while the system is working. See the Compact Web Server Example. The Ethernet controller MAC address can only be changed when the system starts. It is not advisable to change it later.
Debugging
In the Run-Time Environment, the Network Core can be configured for two different variants:
- Debug: this variant includes debug libraries with debugging information and messages that are sent to stdio. Use this variant when debugging your application.
- Release: this variant does not include debugging code. Use this variant when deploying the application.
- Note
- If the target system has only one serial port that is used by the PPP or SLIP Network Interface, then do not enable the debug mode. The debug messages will interfere with the IP packets and the system might malfunction or crash.
- If the debug mode is used on a high traffic LAN, the system might block. Disable the debug mode in this case.
Enabling Debug
To enable debugging with the Network Component, simply choose the Debug variant in the Manage Run-Time Environment window:
All necessary files, such as the Net_Debug.c file and the debug library will be automatically added to your project.
Debug Levels
The system is made up of several modules that output debug messages. It is possible to configure the debug output for each module separately. This can be done in the Net_Debug.c file. There are three debug levels available:
Level | Description |
Off | The debug messages for the selected module are disabled. |
Errors Only | Only error messages are output. This mode is useful for error tracking. |
Full Debug | In this mode, all debug messages are output. |
The following debug options are available:
- Print Time Stamp switch enables or disables printing the time information with debug messages. If this switch is not enabled, the timing information is not printed.
- Debug level for each module defines what kind of debug messages are printed.
The owner module of the displayed debug message is identified by the message prefix. The following system and application modules are configurable for debugging:
ID | Module | Description |
MEM | Memory Management Debug | Allocates and releases frame buffers. |
ETH | Ethernet Debug | Handles Ethernet link. |
PPP | PPP Debug | Handles serial line direct or modem connection PPP link. |
SLIP | SLIP Debug | Handles serial line direct or modem connection SLIP link. |
ARP | ARP Debug | Handles Ethernet MAC address resolution and caching. |
IP | IP Debug | Processes the IP network layer. |
ICMP | ICMP Debug | Processes ICMP messages. Best known example is the ping. |
IGMP | IGMP Debug | Processes IGMP messages, Hosts groups and IP Multicasting. |
UDP | UDP Debug | Processes UDP frames. |
TCP | TCP Debug | Processes TCP frames. |
NBNS | NBNS Debug | The NetBIOS Name Service maintains name access to your hardware. |
DHCP | DHCP Debug | Handles automatic configuration of IP address, Net mask, Default Gateway, and Primary and Secondary DNS servers. |
DNS | DNS Debug | Handles the resolution of the IP address from a host name. |
SNMP | SNMP Debug | Manages devices on IP network. |
SNTP | SNTP Debug | Manages clock synchronization over the network. |
BSD | BDS Debug | Processes TCP and UDP frames via standard BSD Sockets API. |
HTTP | HTTP Server Debug | Delivers web pages on the request to web clients. |
FTP | FTP Server Debug | Manages the files stored on the server and serves the file requests received from the clients. |
FTPC | FTP Client Debug | Connects to FTP server to transfer files on the server, and to manage files stored on the server. |
TNET | Telnet Server Debug | Allows remote clients to control the system using the command line interface. |
TFTP | TFTP Server Debug | A simple service which allows to send files to or read files from the server. |
TFTPC | TFTP Client Debug | Connects to TFTP server to send or receive files. |
SMTP | SMTP Client Debug | Connects to SMTP server to send emails. |
An example of the debug output is:
015.0 ETH:*** Processing frame ***
015.0 ETH: Dest.MAC: 1E:30:6C:A2:45:4E
015.0 ETH: Src. MAC: 00:11:43:A4:FE:40
015.0 ETH: Protocol: IP
015.0 ETH: Length : 66 bytes
015.0 IP :*** Processing frame ***
015.0 IP : Src. IP : 192.168.1.1
015.0 IP : Dest.IP : 192.168.1.5
015.0 IP : Protocol: TCP
015.0 IP : Identif.: 0xBC73
015.0 IP : Length : 52 bytes
015.0 IP : Frame valid, IP version 4 OK
015.0 TCP:*** Processing frame ***
015.0 TCP: Src. Port: 4568
015.0 TCP: Dest.Port: 80
015.0 TCP: Seq. Num.: 4132762560
015.0 TCP: Ack. Num.: 0
015.0 TCP: Flags : SYN
015.0 TCP: Win. Size: 65535
015.0 TCP: Checksum : 0xEF81
015.0 TCP: Frame len: 32 bytes
015.0 TCP: Allocated Socket 2, port 80
015.0 TCP: Socket 2, State LISTEN
015.0 TCP: Process Options, 12 bytes
015.0 TCP: Remote MSS: 1460
015.0 TCP: Next state SYN_REC
In the above example, Ethernet, IP and TCP debug messages are enabled:
- Received Ethernet packets are processed by the Ethernet layer and a debug message containing Ethernet header information is printed out. Ethernet debug information contains source and destination MAC address, Ethernet frame length and Ethernet protocol type.
- The packet is then passed to the IP layer. IP layer prints out IP debug messages containing the IP header information such as source and destination IP address, frame length, protocol type etc.
- When the IP layer has processed the packet, the packet is passed to the upper TCP layer. TCP layer prints out TCP debug messages containing the TCP header information such as source and destination ports, sequence and acknowledge numbers, checksum value, frame length etc.
Redirecting Output
Debug messages are output to a standard IO port. The sendchar function outputs a single character. If required, you can customize this function to send the debug messages to some other device. In most cases, a serial UART is used to print out the debug messages.
- Note
- When the sendchar function runs in polling mode, printing all debug messages significantly reduces the performance. The preferred way is to rewrite the sendchar function to work in the interrupt mode.
- Use the highest baud rate possible to reduce the impact on performance from printing the debug messages.
- If the debug mode is enabled and the embedded system is connected to a high traffic LAN with plenty of broadcast packets, the system might malfunction.
- Printing debug messages blocks out the system task scheduler during the time when the message is being sent from the serial port. The incoming IP packets accumulate in the memory. This soon causes an out of memory error. Any further incoming packets are lost until some memory is released.
Localhost
The localhost is the standard hostname given to the address of the loopback network interface. The IP address of the localhost is 127.0.0.1. The packets, destined to the localhost address, are routed back internally by the IP layer of the Network Component.
Using the loopback interface is useful for testing software, since it bypasses local network interface hardware. Connecting to locally hosted network services using loopback addresses puts less of a load on network resources.
You can use the local host IP address to communicate between different applications using the socket interface on the same system, for example between a FTP server and FTP client. The FTP client connects to FTP server and manage files on FTP server using the localhost address. Of course the files are manipulated locally on the same system. No IP packets actually appear on any of the hardware interfaces.