APPLICATION NOTE. AT11412: UART to Ethernet Gateway with SAM4S. SMART ARM-Based Microcontroller. Introduction. Features

APPLICATION NOTE

AT11412: UART to Ethernet Gateway with SAM4S

SMART ARM-Based Microcontroller

Introduction

This application note aims at describing the LwIP stack and how to use it to design a UART to Ethernet Gateway. This application note will elaborate the software

architecture, internal data transmission scheme and memory footprint to help users make their own Gateway easily according to the real requirement.

Figure 1. The UART to Ethernet Gateway

Features



Atmel® _{SAM4S ARM}® _Cortext®_{-M4-based MCU}



LwIP stack support



DHCP mode support



UDP server support



TCP client/server support



Support 15 clients in TCP server mode



Ethernet data flow control support



TCP client/server with keep-alive detection and auto reconnection



Multiple UART data package mode

Table of Contents

1.

Kits Overview ... 3

1.1 SAM4S Xplained Pro Evaluation Kit ... 3

1.2 Ethernet1 Xplained Pro ... 3

2.

Application Scenarios ... 4

3.

Software Implementation... 5

3.1 APIs Introduction ... 5

3.1.1 LwIP Stack Overview ... 5

3.1.2 Main APIs Introduction ... 5

3.2 Internal Mechanism of Data Transmission ... 8

3.2.1 Data Transfer from UART to Ethernet ... 8

3.2.1.1 UART Data Package Format ... 8

3.2.1.2 UART Data Transfer ... 8

3.2.1.3 Flow Control for UART Port ... 9

3.2.2 Data Transfer from Ethernet to UART... 10

3.3 Quick-start Setup ... 11

4.

Footprint ... 13

5.

Conclusion ... 14

Appendix A.

Additional Information ... 15

A.1 LwIP Configuration ... 15

1.

Kits Overview

1.1

SAM4S Xplained Pro Evaluation Kit

The Atmel® _{SAM4S Xplained Pro evaluation kit is a hardware platform to evaluate the ATSAM4SD32C microcontroller.} Supported by the Atmel Studio integrated development platform (IDE), the kit provides easy access to the features of the Atmel ATSAM4SD32C and explains how to integrate the device in a custom design. The Xplained Pro MCU series evaluation kits include an on-board Embedded Debugger, and no external tools are necessary to program or debug the ATSAM4SD32C. The Xplained Pro extension series evaluation kits offer additional peripherals to extend the features of the board and ease the development of custom designs. More details about the SAM4S Xplained Pro evaluation kit are available here: http://www.atmel.com/tools/ATSAM4S-XPRO.aspx.

Figure 1-1. SAM4S Xplained Pro Evaluation Kit

1.2

Ethernet1 Xplained Pro

Ethernet1 Xplained Pro is a basic extension board for the Xplained Pro platform. The Ethernet is controlled via a SPI interface up to 40MHz for high throughput Ethernet applications. Ethernet1 Xplained Pro connects to any Xplained Pro standard extension header on any Xplained Pro MCU board. More details about Ethernet1 Xplained Pro extension board is available here: http://www.atmel.com/tools/ETHERNET1_XPRO.aspx.

Figure 1-2. Ethernet1 Xplained Pro Extension Board

2.

Application Scenarios

The Gateway can be used in some IoT applications or other scenarios which need both UART and Ethernet.

The Gateway features one TCP server, one TCP client and one UDP server. The TCP server can allow maximum 15 TCP clients to connect at the same time. The UDP server can receive broadcast message and reply the Gateway IP information to the remote sender if necessary.

In this demonstration, the IP address of the Gateway is allocated by the DHCP and the external clients can’t know the Gateway IP address when they want to connect to the Gateway. In order to solve this issue, the Gateway features a UDP server which can tell the external clients in the same network the IP address of the Gateway when it receives a broadcast message that contains “Atmel-Gateway” at the header of the message. For example, if there is a mobile phone that connects to the same network as Gateway, the mobile phone can send a broadcast message “Atmel-Gateway” through UDP protocol and then the Gateway will reply with a message in the form of “IP address, MAC address, Description”. External clients can extract the IP address information from this message and then can connect to the Gateway using this IP address. More clients can connect to the Gateway after they get the Gateway IP address. The Gateway also behaves as a TCP clients and it will try to connect to a pre-defined server every 5mins if the connection is not established.

There is one application scenario that the Gateway can be used in a ZigBee network. Figure 2-1 illustrates the application scenario. The Gateway connects the ZigBee coordinator via UART and connects itself to Ethernet through network cable. The remote clients can send a UDP broadcast message that contains certain information to get the Gateway IP address and then connect it to the Gateway. After that, the remote clients can control or get information from the ZigBee network through the Gateway, such as light infomation. Each client can control the light on or off and if the light status changed, the Gateway will send this information to all the clients. The Gateway can also connect itself to a remote server to upload data to remote server or receive command from the server, such as changing configuration parameters or firmware update.

Figure 2-1. Example of Application Scenario Internet ZigBee Cordinator UART to Ethernet Gateway SerialNet AT Command Remote Server Remote Clients

3.

Software Implementation

3.1

APIs Introduction

3.1.1 LwIP Stack Overview

The Lightweight TCP/IP stack is designed for embedded systems. The focus of the LwIP TCP/IP implementation is to reduce resource usage while still having a full scale TCP. This makes LwIP suitable for use in embedded systems with tens of kilobytes of free RAM and room for around 40 kilobytes of code ROM.

LwIP features:



IP (Internet Protocol) including packet forwarding over multiple network interfaces



ICMP (Internet Control Message Protocol) for network maintenance and debugging



IGMP (Internet Group Management Protocol) for multicast traffic management



UDP (User Datagram Protocol) including experimental UDP-lite extensions



TCP (Transmission Control Protocol) with congestion control, RTT estimation and fast recovery/fast retransmit



DNS (Domain Name Server)



Specialized raw API for enhanced performance



Optional Berkeley-alike socket API



DHCP (Dynamic Host Configuration Protocol)



PPP (Point-to-Point Protocol)



PPPoE (Point to Point Protocol over Ethernet)



ARP (Address Resolution Protocol) for Ethernet

For more details about the LwIP, refer to LwIP Wiki: http://lwip.wikia.com/wiki/LwIP_Wiki or the Atmel AT04055: Using the LwIP Network Stack application note.

3.1.2 Main APIs Introduction

The main APIs used for the Gateway Ethernet part are the LwIP RAW APIs. The Raw API is a non-blocking, event-driven API designed to be used without an operating system that implements zero-copy send and receive.

Table 3-1. TCP RAW APIs used in this Application

API Function Description

Network interface Management

netif_add Add a network interface to the list of LwIP netifs

TCP connection setup

tcp_new Creates a new connection PCB (Protocol Control Block). A PCB is a structure

used to store connection status.

tcp_bind Binds the pcb to a local IP address and port number

tcp_listen Commands a pcb to start listening for incoming connections

tcp_accept Sets the callback function to call when a new connection arrives on a listening

connection

tcp_connect Connects to a remote TCP host

Sending TCP data

tcp_write Queues up data to be sent

tcp_sent Sets the callback function that should be called when data has successfully been

sent and acknowledged by the remote host Receiving TCP

data

tcp_recv Sets the callback function that will be called when new data arrives

tcp_recved Informs LwIP core that the application has processed the data

Callback argument tcp_arg Specify the argument that should be passed callback functions

Closing and aborting connections

tcp_close Closes a TCP connection with a remote host

tcp_err Sets the callback function to call when a connection is aborted because of an

error

tcp_abort Aborts a TCP connection



Network interface management

In LwIP device drivers for physical network hardware are represented by a network interface structure similar to that in BSD. To create a new network interface, a new space should be allocated for the struct netif and call

netif_add():

struct netif *netif_add(struct netif *netif, struct ip_addr *ipaddr, struct ip_addr *netmask, struct ip_addr *gw, void *state,

err_t (* init)(struct netif *netif),

err_t (* input)(struct pbuf *p, struct netif *netif))

In this application, DHCP mode is used and the ip address, netmask and default gateway don’t need to be specified when calling netif_add function. These parameters will be set automatically when DHCP client gets a leased address from the DHCP server successfully.

The init parameter specifies a driver-initialization function that should be called once the netif structure has been prepared by netif_add.

The final parameter input is the function that a driver will call when it has received a new packet. TCP connection setup functions



TCP connection setup

 struct tcp_pcb * tcp_new(void)

Creates a new connection control block (PCB). The connection is initially in the "closed" state. If memory is not available for creating the new PCB, NULL is returned.

 err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr, u16_t port)

Binds the PCB to a local IP address and port number. The IP address can be specified as IP_ADDR_ANY in order to bind the connection to all local IP addresses. If the IP address is not given (i.e., ipaddr == NULL), the IP address of the outgoing network interface is used instead. If the port is specified as zero, the function selects an available port. The connection must be in the "closed" state.

If another connection is bound to the same port, the function will return ERR_USE, otherwise ERR_OK is returned.

 struct tcp_pcb * tcp_listen (struct tcp_pcb *pcb)

The "pcb" parameter specifies a connection, which must be in the "closed" state and must have been bound to a local port with the tcp_bind() function. This functions sets up the local port to listen for incoming connections.

After calling tcp_listen(), tcp_accept()must be called. Until doing so, incoming connections for this port will be aborted.

tcp_listen() may return NULL if no memory was available for the listening connection.

 void tcp_accept(struct tcp_pcb *pcb, err_t (* accept)(void *arg, struct tcp_pcb *newpcb, err_t err))

Commands a PCB to start listening for incoming connections. tcp_listen()must have been previously called. When a new connection arrives on the local port, the specified function will be called with the PCB for the new connection.

 err_t tcp_connect(struct tcp_pcb * pcb, struct ip_addr * ipaddr, u16_t port, err_t (* connected)(void * arg, struct tcp_pcb * tpcb, err_t err));

Sets up the pcb to connect to the remote host and sends the initial SYN segment which opens the connection. If the connection has not already been bound to a local port, a local port is assigned to it. The tcp_connect() function returns immediately; it does not wait for the connection to be properly setup. Instead, it will call the function specified as the fourth argument (the "connected" argument) when the connection is established. If the connection could not be properly established, either because the other host refused the connection or because the other host didn't answer, the error handling function will be called with an the "err" argument set accordingly.

The tcp_connect() function can return ERR_MEM if no memory is available for enqueueing the SYN segment. If the SYN indeed was enqueued successfully, the tcp_connect() function returns ERR_OK.



Sending TCP data

 err_t tcp_write(struct tcp_pcb *pcb, const void *data, u16_t len, u8_t apiflags)

Enqueues the data pointed to by the argument dataptr. The length of the data is passed as the len parameter.

The apiflags argument can have either of the following bits:

TCP_WRITE_FLAG_COPY indicates that LwIP should allocate new memory and copy the data into it. If not specified, no new memory should be allocated and the data should only be referenced by pointer.

The tcp_write() function will fail and return ERR_MEM if the length of the data exceeds the current send buffer size or if the length of the queue of outgoing segment is larger than the upper limit defined in lwipopts.h (TCP_SND_QUEUELEN). If the function returns ERR_MEM, the application should wait until some of the currently enqueued data has been successfully received by the other host and try again.

 tcp_sent(struct tcp_pcb *pcb, tcp_sent_fn sent)

Used to specify the function that should be called when TCP data has been successfully delivered to the remote host.



Receiving TCP data

 void tcp_recv(struct tcp_pcb *pcb, err_t (* recv)(void *arg, struct tcp_pcb *tpcb, struct pbuf *p, err_t err))

TCP data reception is callback based; an application-specified callback function is called when new data arrives.

Sets the callback function that will be called when new data arrives. If there are no errors and the callback function returns ERR_OK, then it is responsible for freeing the pbuf. Otherwise, it must not free the pbuf so that LwIP core code can store it. If the remote host closes the connection, the callback function will be called with a NULL pbuf to indicate that fact.



Close connection

 tcp_close(struct tcp_pcb *pcb)

Closes the connection. The function may return ERR_MEM if no memory was available for closing the connection.If the close succeeds, the function returns ERR_OK.

3.2

Internal Mechanism of Data Transmission

The UART to Ethernet Gateway works between two interfaces. The purpose UART to Ethernet Gateway software is to get all the information at one interface and send it to the other as quickly as possible. Due to the low speed of serial port and high speed of Ethernet, several features must be considered during development, such as the data flow control. In this application, data flow control for the Ethernet interface and data buffer schemes are implemented. There will be a detail description of internal mechanism of data transmission in the below sections.

3.2.1 Data Transfer from UART to Ethernet 3.2.1.1 UART Data Package Format

There are no package header and tail. The data received will be considered as a valid package if no data received in a time interval. The time interval can be specified according to the real application. It is 10ms in this Gateway Demo. 3.2.1.2 UART Data Transfer

There are two 2048 bytes data buffer for the UART port. These two buffers work as a ping-pong buffer. One buffer can be used to receive data from UART and the other can be used to transfer data to Ethernet at the same time.

A dynamically allocated buffer link-list is used for the Ethernet part. Normally, the Ethernet interface is faster than the UART port, so the buffer link-list is rarely used. However, the network congestion may occur sometimes and in this case the UART data can be stored in the buffer link-list temporarily.

Figure 3-1. Flowchart of forwarding UART Data to Network UART Buffer0 Buffer1 Two 2048 Bytes data buffer TCP/IP Connection 0 TCP/IP Connection 1 TCP/IP Connection N A.._. TCP Send Buffer TCP Send Buffer TCP Send Buffer A.._. A.._. RX

Dynamically allocated buffer list

In this application, the Gateway will forward the UART data to all the TCP/IP clients that connect to the Gateway. The TCP send buffer is defined by TCP_SND_BUF in the file lwipopts.h.

Figure 3-2. Flowchart of Software

UART Data Received

Valid Frame? Drop frame

TCP is idle?

Copy data to TCP Send Buffer

Sending data through TCP

Add data buffer to the link-list Y

N

Y

N

Free allocated buffer Copy data to allocated buffer

All the data in the buffer link-list has been transferred? N

TCP in idle state Y

Note that the data doesn’t need to be copied into the TCP send buffer in order to save RAM. In this case, the data is referenced by the pointer and the memory behind the data pointer must not change until the data is ACKed by the remote host.

3.2.1.3 Flow Control for UART Port

Although there is a dynamically allocated buffer list for the UART data to be stored temporarily in case of network congestion, it’s better to have a data flow control for the UART port because maybe there aren’t sufficient RAM to be allocated in some low RAM micro controllers.

There are two flow control schemes, one is hardware flow control and the other is software flow control. Using hardware flow control, two extra pins (clear-to-send (CTS) and request-to-send (RTS)) in addition to TxD and RxD are used to stop or start communication at both UART sides. For software flow control, start (XON) and stop (XOFF) commands are sent as characters, as part of data communication. Only two pins are used (RxD and TxD). However, an extra software layer must be added to UART software drivers to have this feature.

In this Gateway demo application, there is no flow control implementation for the UART port.

3.2.2 Data Transfer from Ethernet to UART

The network data is much faster than the UART data transmission, so a data flow control for the network data is mandatory. Fortunately, TCP provides the data flow control scheme. TCP can negotiate packet lengths to be sent from one Ethernet device to the other. When one side’s windows buffer becomes full, the other side can slow down its data rate or even stop until the remote side’s window buffer is available.

The DMA is used for the UART port to speed up the data transmission and to reduce the CPU usage.

Figure 3-3. Flowchart of forwarding Network Data to UART

UART DMA TCP/IP Connection 0 TCP/IP Connection 1 TCP/IP Connection N A.._. A.._. TX TCP Window Buffer TCP Window Buffer TCP Window Buffer 0 1 N Packets …...

The TCP window buffer is defined by TCP_WND in the file lwipopts.h.

Figure 3-4. Flowchart of Software

Network data packet received

Copy data to allocated buffer

The same TCP info found in the buffer pool?

Find a free Buffer pool to store the TCP info

Add data to TCP buffer link-list

Start DMA to transfer data through UART

Free allocated buffer N

Y

Inform remote side the data has been taken Data transfer finished?

Y

All the data in the buffer link-list has been transferred?

Remove the TCP info from the buffer pool N

Y N

Check the data buffer pool

Network data exist? Y DMA is free?

N N

Y

In the Ethernet task, when the network data packet is received, the data is copied into an allocated buffer. Then, check the buffer pool if there are data packets in the buffer pool that have not been transferred to UART for the same TCP connection. If yes, add the data buffer to the tail of the link-list. Otherwise, find a free buffer for this TCP connection and add data to the TCP buffer link-list.

In the polling task, if there is network data in the buffer pool and the DMA is not in use, the DMA will be started and data will be transferred. At the end of data transfer, the allocated buffer will be freed and the Gateway will inform the remote side the data has been received, so the remote side can transfer proper size of data packet to the Gateway next time according to the Gateway available window buffer. If all the data in the buffer link-list has been transferred, the TCP info will be removed from the buffer pool.

3.3

Quick-start Setup

To evaluate the functionality of this Gateway, a TCP/IP packet tool on PC can be used to setup a quickly and simply testing.



Connect the Ethernet1 Xplained PRO board to the EXT1 header of SAM4S Xplained PRO board



Power the SAM4S Xplained PRO board via the DEBUG USB interface and connect this board to a network router through the Ethernet1 Xplained PRO board. Make sure the PC and the board is in the same local area network.

Figure 3-5. Hardware Setup



Compile the source code and download the firmware image to the board via the on-board embedded debugger



Open the TCP/IP packet tool. Packet Sender is taken as the PC tool just for test purpose which can be found

here: http://packetsender.com/.



Open the serial tool, such as putty or terminal window in Atmel Studio which can be downloaded from Atmel Gallery



Power up the board and broadcast “Atmel-Gateway” message using UDP protocol in packet sender tool to get the IP address of the board

Figure 3-6. Get the Board IP Address

The UDP port number is defined in file src/network/updsev.h



Retrieve the IP address from the received UDP data packet and use this IP address (192.168.1.3) to do data transfer through TCP protocol

Figure 3-7. Data Transfer through TCP Protocol

The TCP port number is defined in file src/network/server.h.

Packet Sender tool always closes the TCP connection after each data packet transferred. For this reason, data transfer from serial port to Ethernet can’t be tested. Users can write a test code that can keep long TCP connection between client and server to do a full test of the Gateway functionalities.

4.

Footprint

Figure 4-1 and Figure 4-2 illustrate the Flash and RAM spaces that each module used in the software of this demonstration.

Figure 4-1. UART to Ethernet Gateway RAM Footprint [KB]

Table 4-1. Primary uses of RAM within LwIP [KB]

UDP PCB TCP PCB TCP SEG PBUF POOL ARP Table Others

0.09 2.5 0.47 22.5 0.2 0.58

Figure 4-2. UART to Ethernet Gateway Flash Footprint [KB]

LwIP 26.34 PHY 1.78 UART 4.35

Low level driver 0.14 Application 0.19 Other 2.08 LwIP 24.07 PHY 2.58 UART 0.77 Low level driver

3.35 Application

3.01

Other 8.06

The RAM consumed by LwIP stack depends on how many clients will connect to the Gateway. From the RAM footprint, the pbuf consumes most of the RAM. The number pbuf pool can be decreased according to the real requirement if there are fewer clients that connected to the Gateway. In addition, the system must have sufficient RAM reserved for heap since the dynamically allocated buffer will be used to store the data that will be sent or received. Much RAM will be needed if there is network congestion while UART sends data continuously or many clients send data to the Gateway simultaneously.

5.

Conclusion

This document describes the basic software architecture, the main LwIP APIs used in this application, the internal scheme of data transmission between UART and Ethernet and a short description about data flow control for both side. This implementation features a small memory footprint TCP/IP to serial communication for a low-end microcontroller solution. It does not require in-depth knowledge of Ethernet TCP/IP and can be easily modified to meet different real application scenarios.

Appendix A.

Additional Information

A.1

LwIP Configuration

Table A-1 lists the LwIP stack configuration in this application, and these configurations can be modified according to real application in file config/lwipopts.h.

Table A-1. LwIP Options for UART to Ethernet Gateway Demonstration

Option Value Description

LWIP_TCP _{1 Turn on TCP}

LWIP_UDP _{1 Turn on UDP}

LWIP_DHCP _{1 Enable DHCP module}

MEMP_NUM_TCP_PCB _{16 The number of simultaneously active}

TCP connections

MEMP_NUM_UDP_PCB 3 The number of UDP protocol control

blocks

MEMP_NUM_TCP_PCB_LISTEN 1 The number of listening TCP

connections

MEMP_NUM_TCP_SEG 30 The number of simultaneously queued

TCP segments

MEMP_NUM_PBUF _{2 The number of memp struct pbufs}

PBUF_POOL_SIZE _{15 The number of buffers in the pbuf pool}

PBUF_POOL_BUFSIZE TCP_MSS+40+PBUF_LINK_HLEN+4 _{The size of each pbuf in the pbuf pool}

TCP_MSS _{1460 TCP Maximum segment size}

TCP_WND 2 * TCP_MSS _{The size of a TCP window}

TCP_SND_BUF 2 * TCP_MSS _{TCP sender buffer space}

MEM_LIBC_MALLOC 1 _{Use malloc/free/realloc provided by}

Appendix B.

Revision History

Doc. Rev. Date Comments

Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 │ www.atmel.com © 2015 Atmel Corporation. / Rev.: Atmel-42429A-UART-to-Ethernet-Gateway-with-SAM4S-AT11412_Application-Note_032015.

Atmel®_{, Atmel logo and combinations thereof, Enabling Unlimited Possibilities}®_{, and others are registered trademarks or trademarks of Atmel Corporation in U.S. and}

other countries. ARM®_{, Cortex}®_{, ARM Connected}® _{logo, and others are the registered trademarks or trademarks of ARM Ltd. Windows}® _{is a registered trademark of}

Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks of others.

DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, b y estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AN D CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON -INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, IN DIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or complet eness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any ti me without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and sha ll not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in conne ction with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety -Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless sp ecifically designated by Atmel as military-grade. Atmel