ARDUINO ETHERNET SHIELD

ARDUINO ETHERNET SHIELD

ARDUINO ETHERNET SHIELD

The Arduino Ethernet Shield allows you to easily

connect your Arduino to the internet.
This shield enables your Arduino to send and receive
data from anywhere in the world with an internet
connection.
You can use it to do fun stuff like control robots
remotely from a website, or ring a bell every time you
get a new twitter message.
This shield opens up endless amounts of possibility by
allowing you to connect your project to the internet in
no-time flat.
Setup
Shield Features
The Ethernet Shield is based upon the
W51000 chip, which has an internal 16K
buffer.
It has a connection speed of up to
10/100Mb.
It relies on the Arduino Ethernet library,
which comes bundled with the
development environment.
There is also an on-board micro SD slot
which enables you to store a heck-of-a-
lot of data, and serve up entire websites
using just your Arduino.
The board also has space for the
addition of a Power over Ethernet (PoE)
module, which allows you to power your
Arduino over an Ethernet connection.
The Arduino Ethernet Shield 2

Operating voltage 5V
(supplied from the
Arduino Board)
Ethernet Controller:
W5500 with internal
32K buffer
Connection speed:
10/100Mb
Connection with
Arduino on SPI port
Ethernet / Ethernet 2 library
Ethernet / Ethernet 2 library
These libraries are designed to work with the
Arduino Ethernet Shield (Ethernet.h) or the
Arduino Ethernet Shield 2 and Leonardo
Ethernet (Ethernet2.h).
The libraries are allow an Arduino board to
connect to the internet.
The board can serve as either a server accepting
incoming connections or a client making
outgoing ones.
Ethernet library (Ethernet.h) manages the
W5100 chip, while Ethernet2 library
(Ethernet2.h) manages the W5500 chip; all the
functions remain the same.
Arduino - Ethernet

Arduino
communicates
with the shield
using the SPI bus.
This is on digital
pins 11, 12, and
13 on the Uno .
On UNO board,
pin 10 is used as
SS.
ETHERNET CLASS
Ethernet class

The Ethernet class initializes the

ethernet library and network
settings.
begin()
localIP()
maintain()
begin()

Initializes the ethernet library and network

settings.
With version 1.0, the library supports DHCP.
Using Ethernet.begin(mac) with the proper
network setup, the Ethernet shield will
automatically obtain an IP address. T
his increases the sketch size significantly.
To make sure the DHCP lease is properly
renewed when needed, be sure to
call Ethernet.maintain() regularly.
begin()

SYNTAX
Ethernet.begin(mac);
Ethernet.begin(mac, ip);
Ethernet.begin(mac, ip, dns);
Ethernet.begin(mac, ip, dns, gateway);
Ethernet.begin(mac, ip, dns, gateway, subnet);

PARAMETERS
mac: the MAC (Media access control) address for the
device (array of 6 bytes). this is the Ethernet hardware
address of your shield. Newer Arduino Ethernet Shields
include a sticker with the device's MAC address. For
older shields, choose your own.
begin()
ip: the IP address of the device (array of 4 bytes)
dns: the IP address of the DNS server (array of 4 bytes).
optional: defaults to the device IP address with the last
octet set to 1
gateway: the IP address of the network gateway (array
of 4 bytes). optional: defaults to the device IP address
with the last octet set to 1
subnet: the subnet mask of the network (array of 4
bytes). optional: defaults to 255.255.255.0
RETURNS
The DHCP version of this function, Ethernet.begin(mac),
returns an int: 1 on a successful DHCP connection, 0 on
failure. The other versions don't return anything.
 Example

#include <SPI.h>
#include <Ethernet.h>

// the media access control (ethernet hardware) address for the

shield:
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
//the IP address for the shield:
byte ip[] = { 10, 0, 0, 177 };

void setup()
{
Ethernet.begin(mac, ip);
}

void loop () {}
localIP()

Obtains the IP address of the Ethernet shield.

Useful when the address is auto assigned
through DHCP.
SYNTAX
Ethernet.localIP();
Parameters
none
Returns
the IP address
Example

#include <SPI.h>
#include <Ethernet.h>

// Enter a MAC address for your controller below.

// Newer Ethernet shields have a MAC address printed
on a sticker on the shield
byte mac[] = {
0x00, 0xAA, 0xBB, 0xCC, 0xDE, 0x02 };

// Initialize the Ethernet client library

// with the IP address and port of the server
// that you want to connect to (port 80 is default for
HTTP):
EthernetClient client;
void setup() {
Serial.begin(9600);
if (Ethernet.begin(mac) == 0) {
Serial.println("Failed to configure Ethernet using
DHCP");
// no point in carrying on, so do nothing
forevermore:
for(;;)
;
}
// print your local IP address:
Serial.println(Ethernet.localIP());
}
void loop() {}
maintain()

Allows for the renewal of DHCP leases.

When assigned an IP address via DHCP, ethernet
devices are given a lease on the address for an
amount of time.
With Ethernet.maintain(), it is possible to
request a renewal from the DHCP server.
Depending on the server's configuration, you
may receive the same address, a new one, or
none at all.
maintain()

You can call this function as often as you want, it will

only re-request a DHCP lease when needed (returning 0
in all other cases).
The easiest way is to just call it on every loop()
invocation, but less often is also fine.
Not calling this function (or calling it significantly less
then once per second) will prevent the lease to be
renewed when the DHCP protocol requires this,
continuing to use the expired lease instead (which will
not directly break connectivity, but if the DHCP server
leases the same address to someone else, things will
likely break).
maintain()

SYNTAX
Ethernet.maintain();
Parameters
none
Returns
byte:
0: nothing happened
1: renew failed
2: renew success
3: rebind fail
4: rebind success
IP ADDRESS CLASS
IP Address class

The IPAddress class works with

local and remote IP addressing.

IPAddress()
IPAddress()

Defines an IP address. It can be used to

declare both local and remote addresses.
Syntax
IPAddress(address);
Parameters
address: a comma delimited list
representing the address (4 bytes, ex. 192,
168, 1, 1)
Returns
None
SERVER CLASS
Server class

The Server class creates servers which can send

data to and receive data from connected clients
(programs running on other computers or
devices).
Server
EthernetServer()
begin()
available()
write()
print()
println()
Server

Server is the base class for all Ethernet server

based calls. It is not called directly, but invoked
whenever you use a function that relies on it.
Functions
EthernetServer()
begin()
available()
write()
print()
println()
EthernetServer()

Create a server that listens for

incoming connections on the specified
port.
Syntax
Server(port);
Parameters
port: the port to listen on (int)
Returns
None
begin()

Tells the server to begin listening for

incoming connections.
Syntax
server.begin()
Parameters
None
Returns
None
available()

Gets a client that is connected to the server and has

data available for reading. The connection persists when
the returned client object goes out of scope; you can
close it by calling client.stop().
Syntax
server.available()
Parameters
None
Returns
a Client object; if no Client has data available for
reading, this object will evaluate to false in an if-
statement
write()

Write data to all the clients connected to a server. This

data is sent as a byte or series of bytes.
Syntax
server.write(val)
server.write(buf, len)
Parameters
val: a value to send as a single byte (byte or char)
buf: an array to send as a series of bytes (byte or char)
len: the length of the buffer
Returns
byte
write() returns the number of bytes written. It is not
necessary to read this.
print()
Print data to all the clients connected to a server. Prints
numbers as a sequence of digits, each an ASCII
character (e.g. the number 123 is sent as the three
characters '1', '2', '3').
Syntax
server.print(data)
server.print(data, BASE)
Parameters
data: the data to print (char, byte, int, long, or string)
BASE (optional): the base in which to print numbers:
BIN for binary (base 2), DEC for decimal (base 10), OCT
for octal (base 8), HEX for hexadecimal (base 16).
Returns
byte
println()

Print data, followed by a newline, to all the

clients connected to a server. Prints
numbers as a sequence of digits, each an
ASCII character (e.g. the number 123 is sent
as the three characters '1', '2', '3').
Syntax
server.println()
server.println(data)
server.println(data, BASE)
println()

Parameters
data (optional): the data to print (char, byte, int,
long, or string)
BASE (optional): the base in which to print
numbers: BIN for binary (base 2), DEC for
decimal (base 10), OCT for octal (base 8), HEX for
hexadecimal (base 16).
Returns
byte
println() will return the number of bytes written,
though reading that number is optional
Example

#include <SPI.h>
#include <Ethernet.h>
// the media access control (ethernet hardware)
address for the shield:
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
//the IP address for the shield:
byte ip[] = { 10, 0, 0, 177 };
// the router's gateway address:
byte gateway[] = { 10, 0, 0, 1 };
// the subnet:
byte subnet[] = { 255, 255, 0, 0 };
// telnet defaults to port 23
EthernetServer server = EthernetServer(23);
void setup()
{
// initialize the ethernet device
Ethernet.begin(mac, ip, gateway, subnet);
// start listening for clients
server.begin();
}
void loop()
{
// if an incoming client connects, there will be bytes
available to read:
EthernetClient client = server.available();
if (client == true) {
// read bytes from the incoming client and write
them back
// to any clients connected to the server:
server.write(client.read());
}
}
CLIENT CLASS
Client class
Client is the base class for all Ethernet client based calls.
It is not called directly, but invoked whenever you use a
function that relies on it.
Functions
EthernetClient()
connected()
connect()
write()
print()
println()
available()
read()
flush()
stop()
EthernetClient()

Creates a client which can connect to a

specified internet IP address and port
(defined in the client.connect() function).
Syntax
EthernetClient()
Parameters
None
connected()

Whether or not the client is connected. Note

that a client is considered connected if the
connection has been closed but there is still
unread data.
Syntax
client.connected()
Parameters
none
Returns
Returns true if the client is connected, false if
not.
connect()

Connects to a specified IP address and port.

The return value indicates success or
failure. Also supports DNS lookups when
using a domain name.
Syntax
client.connect()
client.connect(ip, port)
client.connect(URL, port)
connect()
Parameters
ip: the IP address that the client will connect to (array of 4 bytes)
URL: the domain name the client will connect to (string,
ex.:"arduino.cc")
port: the port that the client will connect to (int)
Returns
Returns an int (1,-1,-2,-3,-4) indicating connection status :
SUCCESS 1
TIMED_OUT -1
INVALID_SERVER -2
TRUNCATED -3
INVALID_RESPONSE -4
write()
Write data to the server the client is connected to. This
data is sent as a byte or series of bytes.
Syntax
client.write(val)
client.write(buf, len)
Parameters
val: a value to send as a single byte (byte or char)
buf: an array to send as a series of bytes (byte or char)
len: the length of the buffer
Returns
byte
write() returns the number of bytes written. It is not
necessary to read this value.
 print()
Print data to the server that a client is connected to. Prints numbers
as a sequence of digits, each an ASCII character (e.g. the number 123
is sent as the three characters '1', '2', '3').
Syntax
client.print(data)
client.print(data, BASE)
Parameters
data: the data to print (char, byte, int, long, or string)
BASE (optional): the base in which to print numbers: DEC for decimal
(base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).
Returns
byte: returns the number of bytes written, though reading that
number is optional
println()

Print data, followed by a carriage return

and newline, to the server a client is
connected to. Prints numbers as a
sequence of digits, each an ASCII character
(e.g. the number 123 is sent as the three
characters '1', '2', '3').
Syntax
client.println()
client.println(data)
client.print(data, BASE)
println()

Parameters
data (optional): the data to print (char,
byte, int, long, or string)
BASE (optional): the base in which to print
numbers: DEC for decimal (base 10), OCT
for octal (base 8), HEX for hexadecimal
(base 16).
Returns
byte: return the number of bytes written,
though reading that number is optional
available()

Returns the number of bytes available for

reading (that is, the amount of data that has
been written to the client by the server it is
connected to).
Syntax
client.available()
Parameters
none
Returns
The number of bytes available.
read()

Read the next byte received from the

server the client is connected to (after the
last call to read()).
Syntax
client.read()
Parameters
none
Returns
The next byte (or character), or -1 if none is
available.
flush()

Waits until all outgoing characters in

buffer have been sent.
Syntax
client.flush()
Parameters
none
Returns
none
stop()

Disconnect from the server.

Syntax
client.stop()
Parameters
none
Returns
none
Example

#include <Ethernet.h>
#include <SPI.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };

byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google

EthernetClient client;
void setup()
{
Ethernet.begin(mac, ip);
Serial.begin(9600);
client.connect(server, 80);
delay(1000);
 Cont..

Serial.println("connecting...");

if (client.connected()) {
Serial.println("connected");
client.println("GET /search?q=arduino HTTP/1.0");
client.println();
} else {
Serial.println("connection failed");
}
}
 Cont..
void loop()
{
if (client.available()) {
char c = client.read();
Serial.print(c);
}

if (!client.connected()) {
Serial.println();
Serial.println("disconnecting.");
client.stop();
for(;;)
;
}
}
ETHERNETUDP CLASS
EthernetUDP class

The EthernetUDP class enables UDP message to be sent

and received.
begin()
read()
write()
beginPacket()
endPacket()
parsePacket()
available()
stop()
remoteIP()
remotePort()
UDP.begin()

Initializes the ethernet UDP library and network

settings.
Syntax
EthernetUDP.begin(localPort);

Parameters
localPort: the local port to listen on (int)
Returns
1 if successful, 0 if there are no sockets available
to use
UDP.read()

Reads UDP data from the specified buffer. If no

arguments are given, it will return the next character in
the buffer.
This function can only be successfully called
after UDP.parsePacket().
Syntax
UDP.read();
UDP.read(packetBuffer, MaxSize);
Parameters
packetBuffer: buffer to hold incoming packets (char)
MaxSize: maximum size of the buffer (int)
Returns
char : returns the characters in the buffer
UDP.write()
Writes UDP data to the remote connection. Must be wrapped
between beginPacket() and endPacket(). beginPacket() initializes
the packet of data, it is not sent until endPacket() is called.
Syntax
UDP.write(message);
UDP.write(buffer, size);
Parameters
message: the outgoing message (char)
buffer: an array to send as a series of bytes (byte or char)
size: the length of the buffer
Returns
byte : returns the number of characters sent. This does not have
to be read
UDP.beginPacket()
Starts a connection to write UDP data to the remote
connection
Syntax
UDP.beginPacket(remoteIP, remotePort);

Parameters
remoteIP: the IP address of the remote connection (4
bytes)
remotePort: the port of the remote connection (int)

Returns
Returns an int: 1 if successful, 0 if there was a problem
resolving the hostname or port.
UDP.endPacket()

Called after writing UDP data to the remote

connection.
Syntax
UDP.endPacket();

Parameters
None
Returns
Returns an int: 1 if the packet was sent
successfully, 0 if there was an error
UDP.parsePacket()
Checks for the presence of a UDP packet, and
reports the size. parsePacket() must be called
before reading the buffer with UDP.read().
Syntax
UDP.parsePacket();

Parameters
None
Returns
int: the size of a received UDP packet
UDP.available()

Get the number of bytes (characters) available for

reading from the buffer. This is data that's already
arrived.
This function can only be successfully called
after UDP.parsePacket().
Syntax
UDP.available()
Parameters
None
Returns
the number of bytes available to read
stop()

Disconnect from the server. Release

any resource being used during the
UDP session.
Syntax
EthernetUDP.stop()
Parameters
none
Returns
none
 UDP.remoteIP()

Gets the IP address of the remote connection.

This function must be called
after UDP.parsePacket().
Syntax
UDP.remoteIP();

Parameters
None
Returns
4 bytes : the IP address of the remote connection
UDP.remotePort()

Gets the port of the remote UDP connection.

This function must be called
after UDP.parsePacket().
Syntax
UDP.remotePort();

Parameters
None
Returns
int : the port of the UDP connection to a remote
host
Example

#include <SPI.h>
#include <Ethernet.h>
#include <EthernetUdp.h>
// Enter a MAC address and IP address for your
controller below.
// The IP address will be dependent on your local
network:
byte mac[] = {
0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
IPAddress ip(192, 168, 1, 177);
unsigned int localPort = 8888; // local port to listen
on
 Example

// An EthernetUDP instance to let us send and receive

packets over UDP
EthernetUDP Udp;

void setup() {
// start the Ethernet and UDP:
Ethernet.begin(mac,ip);
Udp.begin(localPort);

void loop() {