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

Transcription

1 APPLICATION NOTE Introduction AT11412: UART to Ethernet Gateway with SAM4S SMART ARM-Based Microcontroller 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 High speed data transfer by DMA

2 Table of Contents 1. Kits Overview SAM4S Xplained Pro Evaluation Kit Ethernet1 Xplained Pro Application Scenarios Software Implementation APIs Introduction LwIP Stack Overview Main APIs Introduction Internal Mechanism of Data Transmission Data Transfer from UART to Ethernet UART Data Package Format UART Data Transfer Flow Control for UART Port Data Transfer from Ethernet to UART Quick-start Setup Footprint Conclusion Appendix A. Additional Information A.1 LwIP Configuration Appendix B. Revision History

3 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: 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: 3

4 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. 4

5 Figure 2-1. Example of Application Scenario Remote Clients ZigBee Cordinator SerialNet AT Command UART to Ethernet Gateway Internet Remote Server 3. Software Implementation 3.1 APIs Introduction 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: or the Atmel AT04055: Using the LwIP Network Stack application note Main APIs Introduction The main APIs used for the Gateway Ethernet part are the LwIP RAW APIs. The Raw API is a non-blocking, eventdriven API designed to be used without an operating system that implements zero-copy send and receive. 5

6 Table 3-1. TCP RAW APIs used in this Application Network interface Management TCP connection setup Sending TCP data Receiving TCP data API Function netif_add tcp_new tcp_bind tcp_listen tcp_accept tcp_connect tcp_write tcp_sent tcp_recv tcp_recved Description Add a network interface to the list of LwIP netifs Creates a new connection PCB (Protocol Control Block). A PCB is a structure used to store connection status. Binds the pcb to a local IP address and port number Commands a pcb to start listening for incoming connections Sets the callback function to call when a new connection arrives on a listening connection Connects to a remote TCP host Queues up data to be sent Sets the callback function that should be called when data has successfully been sent and acknowledged by the remote host Sets the callback function that will be called when new data arrives 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 tcp_err tcp_abort Closes a TCP connection with a remote host Sets the callback function to call when a connection is aborted because of an error 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 6

7 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. TCP_WRITE_FLAG_MORE indicates that the push flag should not be set in the TCP segment. 7

8 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 Data Transfer from UART to Ethernet 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 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. 8

9 Figure 3-1. Flowchart of forwarding UART Data to Network TCP Send Buffer TCP/IP Connection 0 RX UART Buffer0 Buffer1 TCP Send Buffer TCP/IP Connection 1 Two 2048 Bytes data buffer A... Dynamically allocated buffer list A... A... TCP Send Buffer TCP/IP Connection N 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? N Drop frame Y Copy data to allocated buffer TCP is idle? N Y Copy data to TCP Send Buffer Add data buffer to the link-list Sending data through TCP Free allocated buffer N All the data in the buffer link-list has been transferred? Y TCP in idle state 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 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. 9

10 In this Gateway demo application, there is no flow control implementation for the UART port 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 Packets N TCP Window Buffer TCP Window Buffer TCP/IP Connection 0 TCP/IP Connection 1 TX UART DMA A... A... TCP Window Buffer TCP/IP Connection N The TCP window buffer is defined by TCP_WND in the file lwipopts.h. Figure 3-4. Flowchart of Software Ethernet Task Polling Task Network data packet received Copy data to allocated buffer The same TCP info found in the buffer pool? N Find a free Buffer pool to store the TCP info Add data to TCP buffer link-list Y Check the data buffer pool N Network data exist? Y N DMA is free? Y Start DMA to transfer data through UART N Data transfer finished? Y Free allocated buffer Inform remote side the data has been taken N All the data in the buffer link-list has been transferred? Y Remove the TCP info from the buffer pool 10

11 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: 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 11

12 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 ( ) 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. 12

13 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] Application 0.19 Other 2.08 Low level driver 0.14 UART 4.35 PHY 1.78 LwIP Table 4-1. Primary uses of RAM within LwIP [KB] UDP PCB TCP PCB TCP SEG PBUF POOL ARP Table Others Figure 4-2. UART to Ethernet Gateway Flash Footprint [KB] Application 3.01 Other 8.06 Low level driver 3.35 LwIP UART 0.77 PHY

14 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. 14

15 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 C- library 15

16 Appendix B. Revision History Doc. Rev. Date Comments 42429A 03/2015 Initial document release 16

17 Atmel Corporation 1600 Technology Drive, San Jose, CA USA T: (+1)(408) F: (+1)(408) Atmel Corporation. / Rev.:. 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, INDIRECT, 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 products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automoti ve-grade.