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 of 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. Note that users of MDK-Professional can select between an IPv4/IPv6 dual-stack and an IPv4-only implementation, while users of MDK-Plus can only select the IPv4 implementation.
   • 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. If you use wireless communication, select appropriate CMSIS Driver:WiFi (API) driver that supports transparent mode.
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 or CMSIS:RTOS2 that is required for the Networking Component.
5. If you need to secure the communication, select from the Security Component:
   • mbed TLS

RTE Component Selection Example

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.

Ethernet PHY Configuration

For Ethernet network communication, usually an external Ethernet PHY is required to interface the physical line to the digital MAC of the microcontroller device. The MAC usually contains two buses:

1. Data bus: MII, RMII, or Serial Network Interface (SNI)
2. Management bus: Serial Management Interface (SMI) (using MDC and MDIO)

SMI is used to access the PHY’s internal registers to read the state of the link (up/down), duplex mode, speed, and to restart auto-negotiation etc. SMI is a serial bus, which allows to connect up to 32 devices. Devices on the bus are accessed using a 5-bit device address. A default device address is hardware configurable by pin-strapping on the device (some pins are sampled when a reset is asserted or at power-up).

The device’s internal weak pull-up or pull-down resistors define a default device address. This address can be changed by connecting strong pull-up or pull-down resistors externally. In this case, the ETH_PHY_ADDR in the PHY driver needs to be changed accordingly to be able to control the PHY and to communicate with it. Use the Options for Component dialog to override the default setting for ETH_PHY_ADDR:

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 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. The default Core Thread priority is osPriorityNormal. You can change this priority by changing the NET_THREAD_PRIORITY defined in this configuration file. This priority must be lower than the priorities of the network interface threads.

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:

• Net_Config_ETH_0.h
• Net_Config_WiFi_0.h
• Net_Config_PPP.h
• Net_Config_SLIP.h

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

• Net_Config_BSD.h
• Net_Config_TCP.h
• Net_Config_UDP.h

Network Service

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

• Net_Config_HTTP_Server.h
• Net_Config_FTP_Server.h
• Net_Config_FTP_Client.h
• Net_Config_TFTP_Server.h
• Net_Config_TFTP_Client.h
• Net_Config_Telnet_Server.h
• Net_Config_SNMP_Agent.h
• Net_Config_DNS_Client.h
• Net_Config_SNTP_Client.h
• Net_Config_SMTP_Client.h

Security Configuration

The mbed TLS component provides an API for secure communication. When selecting this software component, the mbedTLS_config.h configuration file is added to the project. The proper usage of this file is out of the scope of this document. For further information, check the online documentation of .

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).
• Additional two threads when Ethernet Interface is enabled (netCore_Thread and netETH_Thread).
  • If you use RTX v5, you do not need to change the RTX settings, because all resources are statically allocated.
  • If you use RTX v4, you must change the following settings in the file:
    • Increase the Number of concurrent running user threads by 2
    • Increase the Number of threads with user-provided stack size by 2
    • Increase Total stack size [bytes] for threads with user-provided stack size by 1536 bytes
    • Enable User Timers

For more information, check the Network Component's Resource Requirements section.

User Code Implementation

Before using the networking communications, the Network Core must be initialized with the function netInitialize. The function initializes the Network system resources and creates threads and other RTOS objects. The initialization is usually executed from the app_main thread.

The initialization process is different depending on which network interface is used:

• Ethernet interface

  __NO_RETURN static void app_main (void *arg) {
    (void)arg;
   
    netInitialize ();
   
    osThreadTerminate(osThreadGetId());
    for(;;);
  }

• WiFi interface

  __NO_RETURN static void app_main (void *arg) {
    NET_WIFI_CONFIG wifi_config;
    (void)arg;
   
    netInitialize ();
   
    // Configure wireless parameters
    wifi_config.ssid       = "GuestAccess";
    wifi_config.password   = "guest";
    wifi_config.security   = netWiFi_SecurityWPA2;
    wifi_config.channel    = 0;
    wifi_config.wps_method = netWiFi_WPS_None;
   
    // Connect to wireless network
    netWiFi_Activate (0, &wifi_config);
   
    osThreadTerminate(osThreadGetId());
    for(;;);
  }

• PPP interface

  __NO_RETURN static void app_main (void *arg) {
    (void)arg;
   
    netInitialize ();
   
    // Connect to remote PPP server
    netPPP_Connect ("04213372", "Guest", "test")
   
    osThreadTerminate(osThreadGetId());
    for(;;);
  }

User Code Templates

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 Name	User 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

The Network Component is distributed in library form and doesn't allow direct code debug. However, it can be configured to generate debug events and provide dynamic visibility to the component operation.

The following variants can be selected for the Network:Core component in the Manage Run-Time Environment window:

• Debug: this variant supports event annotations for the and makes it very easy to analyze the internal operation of the Network Component during application debug.
• Debug STDIO: this is a legacy debug variant that prints event information as ASCII messages.
• Release: this variant does not include additional debugging code. Use this variant when deploying the application.

The figure below shows selection of IPv4/IPv6 Debug variant as an example.

The Debug Events describes the events implemented in Network Services.

Note

Users of MDK-Plus edition can only access IPv4 Debug/Debug STDIO/Release variants.

Event Recorder Support

is a powerful tool that provides visibility to the dynamic execution of the program. The Network Component generates a broad set of Debug Events for the Event Recorder and implements required infrastructure to interface with it.

To use the Event Recorder together with Network Component, it is required to create an image with event generation support. The necessary steps are:

1. : in the RTE management dialog select the Debug variant for the target Network:Core software component.
2. : in the RTE management dialog enable the software component CMSIS-View:Event Recorder.
3. : in the application code, call the function EventRecorderInitialize.
   
4. : if necessary, adjust default Event Recorder configuration.
5. Build the application code, download it to the target hardware and start debug session.

Now, when the network services generate event information, it can be viewed in the .

Event filtering

The Network debug variant generates lots of debug events. This might have an impact on the operation of the Network library. It is a good idea to disable debug for modules, which are not used, or at least to reduce the number of messages, that are generated. Therefore, enable Error events for such modules and enable Debug events only for the modules you are focused on.

Event IDs

The network component uses the following event IDs:

Component	Event ID
Net_SYS	0xC0
Net_MEM	0xC1
Net_ETH	0xC2
Net_WiFi	0xDD
Net_PPP	0xC3
Net_SLIP	0xC4
Net_LOOP	0xC5
Net_IP4	0xC6
Net_ICMP	0xC7
Net_IGMP	0xC8
Net_NBNS	0xC9
Net_DHCP	0xCA
Net_ARP	0xCB
Net_IP6	0xCC
Net_ICMP6	0xCD
Net_DHCP6	0xCE
Net_NDP	0xCF
Net_UDP	0xD0
Net_TCP	0xD1
Net_BSD	0xD2
Net_HTTPs	0xD3
Net_FTPs	0xD4
Net_FTPc	0xD5
Net_Teln	0xD6
Net_TFTPs	0xD7
Net_TFTPc	0xD8
Net_SMTP	0xD9
Net_DNS	0xDA
Net_SNMP	0xDB
Net_SNTP	0xDC

Runtime Configuration

It is often necessary to change the parameters and mode of operation of the network interface at startup or runtime. System control functions allow reading and changing the settings of the network interface and the system (for example the hostname).

This is required for using the same application code for serial production of embedded devices. The runtime configuration feature enables reading of configuration parameters from an EEPROM or SD Card and configuring 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
• netIF_SetDefault function to set default interface for internet access

The options which can be changed are defined in the netIF_Option enumerator. However, some interfaces do not support the complete set of available options. For example, the PPP interface does not have a MAC address. If you try to modify an unsupported 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 the localhost name, whereas netSYS_SetHostName changes the localhost name.

The DHCP client can be disabled or enabled at runtime. When disabled, the user provided network parameters defined in the Net_Config_ETH_0.h or Net_Config_WiFi_0.h configuration files are used. Switch the state of the DHCP client using netDHCP_Disable and netDHCP_Enable.

Note

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, the system might not work (due to collisions or disturbed network communications).

Code Example

#include "rl_net.h"
 
/* The following values are read from EEPROM */
const char mac_addr[]  = { "00-01-02-32-3c-46" };
const char ip_addr[]   = { "192.168.0.150"     };
const char def_gw[]    = { "192.168.0.1"       };
const char net_mask[]  = { "255.255.255.0"     };
const char pri_dns[]   = { "194.25.2.129"      };
const char sec_dns[]   = { "194.25.2.130"      };
const char host_name[] = { "Keil_MCB"          };
bool DHCP_enabled      = false;
 
int main (void) {
  uint8_t buf[8];
 
  netInitialize ();
 
  /* Change host name */
  netSYS_SetHostName (host_name);
 
  /* Change MAC address */
  netMAC_aton (mac_addr, buf);
  netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionMAC_Address, buf, NET_ADDR_ETH_LEN);
 
  if (DHCP_enabled == false) {
    /* Static configuration mode */ 
    netDHCP_Disable (NET_IF_CLASS_ETH | 0);
 
    /* Change IP address */
    netIP_aton (ip_addr, NET_ADDR_IP4, buf);
    netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_Address, buf, NET_ADDR_IP4_LEN);
 
    /* Change Network mask */
    netIP_aton (net_mask, NET_ADDR_IP4, buf);
    netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_SubnetMask, buf, NET_ADDR_IP4_LEN);
 
    /* Change Default Gateway address */
    netIP_aton (def_gw, NET_ADDR_IP4, buf);
    netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_DefaultGateway, buf, NET_ADDR_IP4_LEN);
 
    /* Change Primary DNS Server address */
    netIP_aton (pri_dns, NET_ADDR_IP4, buf);
    netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_PrimaryDNS, buf, NET_ADDR_IP4_LEN);
 
    /* Change Secondary DNS Server address */
    netIP_aton (sec_dns, NET_ADDR_IP4, buf);
    netIF_SetOption (NET_IF_CLASS_ETH | 0, netIF_OptionIP4_SecondaryDNS, buf, NET_ADDR_IP4_LEN);
  }
}