Network Dual-Stack Component  Version 7.0 (Beta)
MDK-Professional Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Enumerations Groups Pages
Creating a Network Application

The steps to create a microcontroller application that uses TCP/IP communication are:

  1. Select RTE Components along with the Network Services that are required for your application.
  2. Enable the Network Driver and Controller that is integrated in the microcontroller.
  3. Configure the various Network Components.
  4. Configure the system resources according to the network component's Resource Requirements.
  5. Implement the User Code using code templates that are provided for the Network Component.
  6. Debug your application using the built-in mechanisms in the Network Component.
  7. Sometimes, it is necessary to change some network settings at runtime.

RTE Component Selection

Only a few steps are necessary to complete the RTE Component selection:

  1. 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.
  2. From the CMSIS Driver Component:
    • If you do Ethernet communication, select appropriate CMSIS Driver:Ethernet (API) or CMSIS Driver:Ethernet MAC (API) and CMSIS Driver:Ethernet PHY (API) drivers suitable for your application. For PPP or SLIP communication simply select CMSIS Driver:USART (API):USART.
  3. From the Device Component:
    • Additional device specific drivers may be required according to the validation output.
  4. 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.
nw_rte_comp_selection.png
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 interface 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 interface. Note: 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 an example project that is provided for various evaluation boards.

Network Configuration

All configuration files for the Network Component are listed in the Project window below the Component Class Network.

Network Core

net_config_c.png
Net_Config.c Configuration File

The Network Core configuration file Net_Config.c 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). This requires a NetBIOS Name Service to be enabled in the configuration. This name is very useful if you don't know the IP address that has been assigned to your device by the DHCP server.

The Memory Pool Size specifies the amount of RAM in bytes allocated for the memory pool. The buffers for the network packets are allocated from this memory pool. Usually, the default value of 12000 bytes is sufficient.

Many Network Services are started by the Network Core automatically. If you disable Start System Service, you need to enable/start them at runtime using the dedicated functions for that.

To change the default OS resource settings for the Network Core, use Core Thread Stack Size. The default value is 1024 bytes.

Network Interface

The Network Interface configuration files Net_Config_Interface_n.h contain general IP address and other settings. You also need to specify the hardware driver number that is to be used with the network interface. In case of Ethernet for example, this is usually 0. If you are using a SLIP or PPP over a serial connection, you need to specify the hardware driver number of the exact UART you wish to use. All settings for the different interfaces are described here:

Network Socket

Usually, the needs of most applications are served by using the default settings for the sockets. Of course, there are configuration files for all three socket types that are specified in

Network Service

The configuration files for all the Network Services are explained in the respective section:

System Resource Configuration

For proper operation, the Network Component requires some system configuration settings. The requirements are:

  • Additional stack size of 512 bytes. This can be configured in the device's startup_device.s file (Stack_Size).
  • The Network Component uses two CMSIS-RTOS threads netCore_Thread and netETH_Thread when Ethernet Interface is enabled. So you need to increase the Number of concurrent running threads by 2. The default thread stack size should be at least 512 Bytes. Also, User Timers need to be enabled.

All these changes must be done in the RTX_Conf_CM.c file. For more information, check the Network Component's Resource Requirements section.

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.

The following templates are available for the Network component:

Template NameUser Functions
DNS_Client.c dns_cbfunc (Callback function for notification about DNS client events), resolve_host (DNS resolving process)
FTP_Client_UIF.c netFTPc_Process (Request parameters for FTP client session), netFTPc_Notify (Notify the user application when FTP client operation ends)
FTP_Server_Access.c netFTPs_AcceptClient (Accept or deny connection from remote FTP client)
FTP_Server_Event.c netFTPs_Notify (Notify the user application about events in FTP server service)
FTP_Server_Multiuser.c netFTPs_CheckUsername (Check if an user account exists), netFTPs_CheckPassword (Check user account password), netFTPs_FileAccess (Check if remote user is allowed to access a file)
HTTP_Server_Access.c netHTTPs_AcceptClient (Accept or deny connection from remote HTTP client)
HTTP_Server_CGI.c netCGI_ProcessQuery (Process query string received by GET request), netCGI_ProcessData (Process data received by POST request), netCGI_Script (Generate dynamic web data from a script line)
HTTP_Server_Error.c net_http_error (Define user-friendly HTTP error messages)
HTTP_Server_Multiuser.c netHTTPs_CheckAccount (Check if an user account exists), netHTTPs_FileAccess (Check if remote user is allowed to access a file)
SMTP_Client_UIF.c netSMTPc_Process (Request parameters for SMTP client session), netSMTPc_Notify (Notify the user application when SMTP client operation ends), netSMTPc_AcceptAuthentication (Accept or deny authentication requested by SMTP server)
SNMP_Agent_MIB.c mib_table (Defines MIB information data table), register_mib_table (Registers a MIB table in SNMP agent)
TCP_Socket_Client.c tcp_cb_client (Notify the user application about TCP socket events), send_data (Connect to TCP server and send data)
TCP_Socket_Server.c tcp_cb_server (Notify the user application about TCP socket events)
Telnet_Server_Access.c netTELNETs_AcceptClient (Accept or deny connection from remote Telnet client)
Telnet_Server_Multiuser.c netTELNETs_CheckUsername (Check if an user account exists), netTELNETs_CheckPassword (Check user account password)
Telnet_Server_UIF.c netTELNETs_ProcessMessage (Request message for Telnet server session), netTELNETs_ProcessCommand (Process a command and generate response)
TFTP_Client_UIF.c tftp_client_notify (Notify the user application when TFTP client operation ends)
TFTP_Server_Access.c netTFTPs_AcceptClient (Accept or deny connection from remote TFTP client)
UDP_Socket.c udp_cb_func (Notify the user application about UDP socket events), send_udp_data (Send UDP data to destination client)

Debugging

In the Manage Run-Time Environment window, 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 use ITM channel for printing debug messages. Otherwise, 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. Reduce the amount of printed debug messages in Net_Debug.c configuration or disable the debug mode completely.

Enabling Debug

To enable debugging with the Network Component, simply choose the Debug variant in the Manage Run-Time Environment window:

nw_debug_variant.png

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 OnlyOnly 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 DebugAllocates 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.
LOOP Loopback Debug Handles localhost loopback interface.
ARP ARP Debug Handles Ethernet MAC address resolution and caching.
IP4 IPv4 Debug Processes the IP version 4 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.
IP6 IPv6 Debug Processes the IP version 6 network layer.
ICMP6 ICMPv6 Debug Processes ICMP version 6 messages. Best known example is the ping.
NDP6 NDP Debug Handles Neighbor Discovery MAC address resolution and caching.
UDP UDP Debug Processes UDP frames.
TCP TCP Debug Processes TCP frames.
BSD BSD Debug Processes TCP and UDP frames via standard BSD Sockets API.
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.
DHCP6 DHCP6 Debug Handles automatic configuration of IP address in IP version 6.
DNS DNS Debug Handles the resolution of the IP address from a host name.
SNMP SNMP Debug Manages devices on IP network.
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.
TELN Telnet Server Debug Allows remote clients to control the system using the command line interface.
TFTP TFTP Server Debug A simple service which allows you 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.
SNTP SNTP Debug Manages clock synchronization over the network.

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 ITM debug channel 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.

Runtime Configuration

Sometimes it is necessary to change the parameters and mode of operation of the network interface at startup or runtime. This is possible with the system control functions that allow reading and changing the settings of the network interface and also some system settings like the hostname.

This enables you to use the same application code for serial production of embedded devices. The runtime configuration feature let you read the configuration parameters from an EEPROM and configure the network interface for each embedded device differently.

To control the network interface options, you can use:

  • netIF_GetOption function to retrieve the options,
  • netIF_SetOption function to set the options.

The options which can be changed are defined in the netIF_Option enumerator. However, be aware that some interfaces do not support all set of available options. For example, the PPP interface does not have a MAC address. If you try to modify a not supported option, an error is returned.

The localhost name is used to access the embedded system without knowledge of its IP address. netSYS_GetHostName is used to retrieve localhost name, whereas netSYS_SetHostName lets you change the localhost name.

The Dynamic Host Configuration can be disabled or enabled at runtime. When disabled, the user provided network parameters defined in the Net_Config_ETH_0.h configuration file are used instead. To disable the DHCP client, use netDHCP_Disable. To (re-)enable the client, use netDHCP_Enable.

Note
Each embedded Ethernet device must have an unique MAC address, IP address, and hostname. This is very important when multiple devices are connected to the same LAN. Otherwise, the system might not work (due to collisions or disturbed network communications).