W5100 Library

1. Overview

W5100 is a common Ethernet controller with built-in protocol offloading features that allows small microcontrollers like Ansteron Board to access to computer network and the Internet. Connection between Ansteron Board and W5100 is based on SPI interface. The library provides functions for basic network communication and data transfer.

2. Circuit

A W5100 chip will need other components such as power supply, signal transformer and RJ-45 connectors in order to from a functional device. For details on pin configuration and reference schematics, please refer device's datasheet and manufacturer website. In this tutorial, the connection between Ansteron Board and W5100 is simplified, only important signals are shown

Note that signal pins of W5100 are 5V tolerant. They can be directly connected to Ansteron Board operating at 5V while the chip itself requires 3.3V supply.

The circuit above shows connection between Ansteron Board and a W5100 module or breakout. The module could be purchased assembled from many stores, which has everything needed to connect to Ethernet network. Power supply for the module can be drawn from +5V pin of Ansteron Board.

One pull-up resistor on /CS line is required if the module doesn't have one. W5100 has to release SPI signals when it's not being selected to allow other devices to work as well as program downloading, which is done on the same bus.

3. Operation

Once connected to a network, W5100 can communicate with other devices on that network. It can also access to the Internet through a Gateway (or Router) which connects to Internet Service Provider.

There are two operation modes, client and server. As a server, W5100 wait for a client to connect, receive requests and respond to the client. When operating as a client, W5100 connect to a server, which could be on the same network or the Internet, then send requests and receive response.

The library handles interface between Ansteron Board and W5100 as well as two basic network protocols which are DHCP (Dynamic Host Configuration Protocol) and DNS (Domain Name System). Both server and client mode can run concurrently, up to user program.

DHCP allows Ansteron Board to automatically set up network settings such as IP, net mask, Gateway and DNS server addresses. Most networks that have a Router/Gateway and connected to the Internet can use this feature. Network settings can also be set manually.

DNS protocol allows translation from domain name (like www.ansteron.com) into IP address. For internet applications, this should be used to avoid unexpected IP address changes.

All functions of the library has prefix "ENET_" which stands for Ethernet. Before communication can work, the interface must be set up. DHCP routine will then run to retrieve addresses or they must be manually entered. When that is done, the interface is ready.

4. Example

There are examples for both client and server modes come with Ansteron IDE, in example folder.

5. Functions

All IP addresses given or returned from functions of the library are long type (32 bit integer), except some set up functions. Notation 192.168.1.1 is corresponding to value 0xC0A80101 but that cannot be used in the program.

The default MAC address is 00:1D:A4:01:12:2F. If other MAC address is used, they must be enter right after function setup_ENET(), using function ENET_set_MAC_address().

setup_ENET(cs_pin);

Setup the interface with W5100. Input cs_pin is the pin that connects to /CS signal of W5100 (PIN_Bx, PIN_Cx, PIN_Dx). It can be any pin on Ansteron Board except pin B3, B4 and B5. The function returns 1 if succeeded, 0 if failed.

SPI interface between Ansteron Board and W5100 works at 4 MHz by default

ENET_run_DHCP();

Automatically retrieve and setup network information. Function returns 1 if succeeded, 0 if failed. The process should only take a second or two in most cases but it could wait up to 10 seconds for DHCP response. This function should be call once on start-up and cannot be used while server mode is running.

ENET_resolve(domain, timeout);

Resolve a domain name into IP address. The function returns IP address of the domain name in form of 32 bit long integer value. If the domain name was not found or an error occurred, 0 will be returned. This function cannot work while server mode is running. Input domain is a zero-terminated string (ex. "www.ansteron.com"). Time-out value is in second.

ENET_set_ip(b3,b2,b1,b0);

ENET_set_gateway_ip(b3,b2,b1,b0);

ENET_set_DNS_ip(b3,b2,b1,b0);

ENET_set_netmask(b3,b2,b1,b0);

ENET_set_MAC_address(pointer);

Manually set up network information. If DHCP was not used, these functions must be called to set up the network before other functions can work. b3..b0 are components of IP address, number values range from 0 to 255. For MAC function, input is a pointer to a char array of 6 bytes MAC address.

ENET_get_ip();

ENET_get_gateway_ip();

ENET_get_DNS_ip();

ENET_get_netmask();

Read current network settings. These functions returns IP addresses and netmask as long values.

Server mode:

ENET_server_open(port_number);

Open server on given port number. Function returns 1 if succeeded, 0 if failed. When a port is successfully opened, client can connect using server IP address and the same port number.

ENET_server_close();

Close any opening port.

ENET_server_connected();

Return the IP address of connected client. If there is no client, zero will be returned.

ENET_server_disconnected();

This function return 1 if client has disconnected, zero otherwise.

ENET_server_reopen();

Disconnect from connecting client and reopen the port. This can be called when server has finished responding to a request and would like to disconnect to serve the next client. Be informed that server can only serve one client at a time. It will be unreachable to other clients when one is being connected.

ENET_server_read(buffer, max_length);

Read data or request received from connected client. Input buffer is a pointer to location where data will be placed. Input max_length is the size of given buffer. Function returns number of bytes read if succeeded, zero if there is no data received (without waiting).

ENET_server_write(buffer, size);

Send data in buffer to connected client. Function will not return until all data has been lined up for sending. It does not return any value.

ENET_server_print(string);

Send a string to connected client. The string is zero terminated and function returns number of bytes sent. Ending zero of the string will not be sent.

Client mode:

ENET_client_connect(ip,port,timeout);

Connect to a server at given IP address and port number. Returned value from function ENET_resolve() can be passed directly to this function. Value 1 is returned if function succeeded and connection is ready, 0 if failed. Time-out value is in second

ENET_client_close();

Close any opening connection.

ENET_client_disconnected();

The function returns 1 if server has disconnected, 0 if connection is still active.

ENET_client_write(buffer,size);

Send data or request to server. Function will not return until all given data is lined up for sending. It does not return any value.

ENET_client_read(buffer, max_size);

Read data/response from server. Data will be written into buffer, up to max_size number of bytes. Function returns number of bytes read, zero if there is no data. It returns zero immediately if no data was received.

In UDP mode, the first 8 bytes is UDP header. User program should discard if the header is not use.

ENET_client_print(string);

Send a string to server. The string is zero-terminated. Function returns number of bytes sent. Ending zero of the string will not be sent.

ENET_client_UDP(ip,port);

UDP is a connectionless data transfer method. The function will initialize client mode to send UDP packets instead of regular TCP protocol. Functions ENET_client_write(), ENET_client_read() and ENET_client_print() can be used to send and receive UDP packets.

Even though UDP shares the same functions with client mode, the term client does not have a meaning in this context.

6. Note

Please be informed that W5100 module may draw up to 200mA while operating.

W5100 has 4 sockets but only the first two are used, giving each one 4KB of buffer. Socket 0 is used for DHCP, DNS and server mode, socket 1 is used for client mode and user UDP mode. If DHCP is not necessary, manually set up address will reduce program size.

In UDP mode, each write will result in one packet sent. Compose the message on memory and send it at once to a void being broken up into small packets.