Arduino

Ethernet Library
Nuno Pessanha Santos

[email protected]

[email protected]
INDEX
Introduction ................................................................................................................................. 3
Ethernet class .............................................................................................................................. 4
1.1. Ethernet.begin()............................................................................................................ 4
Server class................................................................................................................................... 5
2.1. Server().......................................................................................................................... 5
2.2. begin() ........................................................................................................................... 6
2.3. available() ...................................................................................................................... 7
2.4. write() ............................................................................................................................ 8
2.5. print() ............................................................................................................................ 9
2.6. println() ......................................................................................................................... 9
Client class.................................................................................................................................. 10
3.1. Client() ......................................................................................................................... 10
3.2. connected() ................................................................................................................. 11
3.3. connect() ..................................................................................................................... 12
3.4. write() .......................................................................................................................... 14
3.5. print() .......................................................................................................................... 14
3.6. println() ....................................................................................................................... 14
3.7. available() .................................................................................................................... 15
3.8. read() ........................................................................................................................... 16
3.9. flush() .......................................................................................................................... 16
3.10. stop() ........................................................................................................................... 17

2
Nuno Pessanha Santos – [email protected] / [email protected]
 Introduction
Ethernet library
With the Arduino Ethernet Shield, this library allows an Arduino board to connect to the
internet. It can serve as either a server accepting incoming connections or a client making
outgoing ones. The library supports up to four concurrent connection (incoming or outgoing or
a combination).
Ethernet class
The Ethernet class initializes the ethernet library and network settings.
 begin()
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()
 begin()
 available()
 write()
 print()
 println()
Client class
The client class creates clients that can connect to servers and send and receive data.
 Client()
 connected()
 connect()
 write()
 print()
 println()
 available()
 read()
 flush()
 stop()

3
Nuno Pessanha Santos – [email protected] / [email protected]
 Ethernet class
1.1. Ethernet.begin()
Description
Initializes the ethernet library and network settings.
Syntax
Ethernet.begin(mac,ip);
Ethernet.begin(mac,ip,gateway);
Ethernet.begin(mac, ip, gateway, subnet);
Parameters
mac: the MAC address for the device (array of 6 bytes)
ip: the IP address of the device (array of 4 bytes)
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
None
Example
#include <Ethernet.h>
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
void setup()
{
Ethernet.begin(mac, ip);
}
void loop () {}

4
Nuno Pessanha Santos – [email protected] / [email protected]
 Server class
2.1. Server()
Description
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
Example
#include <Ethernet.h>
// network configuration. gateway and subnet are optional.
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };
// telnet defaults to port 23
Server server = Server(23);
void setup()
{
// initialize the ethernet device
Ethernet.begin(mac, ip, gateway, subnet);
// start listening for clients
server.begin();
}
void loop()
{
Client client = server.available();
if (client) {
server.write(client.read());
}
}

5
Nuno Pessanha Santos – [email protected] / [email protected]
2.2. begin()
Description
Tells the server to begin listening for incoming connections.
Syntax
server.begin()
Parameters
None
Returns
None
Example
#include <Ethernet.h>

// network configuration. gateway and subnet are optional.

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };
// telnet defaults to port 23
Server server = Server(23);
void setup()
{
// initialize the ethernet device
Ethernet.begin(mac, ip, gateway, subnet);
// start listening for clients
server.begin();
}
void loop()
{
Client client = server.available();
if (client) {
server.write(client.read());
}
}

6
Nuno Pessanha Santos – [email protected] / [email protected]
2.3. available()
Description
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
None
Example
#include <Ethernet.h>
// network configuration. gateway and subnet are optional.
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };
// telnet defaults to port 23
Server server = Server(23);
void setup()
{
// initialize the ethernet device
Ethernet.begin(mac, ip, gateway, subnet);
// start listening for clients
server.begin();
}
void loop()
{
Client client = server.available();
if (client) {
server.write(client.read());
}
}

7
Nuno Pessanha Santos – [email protected] / [email protected]
2.4. write()
Description
Write data to all the clients connected to a server.
Syntax
server.write(data)
Parameters
data: the value to write (byte or char)
Returns
None
Example
#include <Ethernet.h>
// network configuration. gateway and subnet are optional.
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte gateway[] = { 10, 0, 0, 1 };
byte subnet[] = { 255, 255, 0, 0 };
// telnet defaults to port 23
Server server = Server(23);
void setup()
{
// initialize the ethernet device
Ethernet.begin(mac, ip, gateway, subnet);
// start listening for clients
server.begin();
}
void loop()
{
Client client = server.available();
if (client) {
server.write(client.read());
}
}

8
Nuno Pessanha Santos – [email protected] / [email protected]
2.5. print()
Description
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).

2.6. println()
Description
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)
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).

9
Nuno Pessanha Santos – [email protected] / [email protected]
 Client class
3.1. Client()
Description
Creates a client which can connect to the specified internet IP address and port.
Syntax
Client(ip, port)
Parameters
ip: the IP address that the client will connect to (array of 4 bytes)
port: the port that the client will connect to (int)
Example
#include <Ethernet.h>
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google
Client client(server, 80);
void setup()
{
Ethernet.begin(mac, ip);
Serial.begin(9600);
delay(1000);
Serial.println("connecting...");
if (client.connect()) {
Serial.println("connected");
client.println("GET /search?q=arduino HTTP/1.0");
client.println();
} else {
Serial.println("connection failed");
}
}
void loop()
{
if (client.available()) {
char c = client.read();
Serial.print(c);
}
if (!client.connected()) {

10
Nuno Pessanha Santos – [email protected] / [email protected]
 Serial.println();
Serial.println("disconnecting.");
client.stop();
for(;;)
;
}
}

3.2. connected()
Description
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.
Example
#include <Ethernet.h>
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google
Client client(server, 80);
void setup()
{
Ethernet.begin(mac, ip);
Serial.begin(9600);
delay(1000);
Serial.println("connecting...");
if (client.connect()) {
Serial.println("connected");
client.println("GET /search?q=arduino HTTP/1.0");
client.println();
} else {

11
Nuno Pessanha Santos – [email protected] / [email protected]
 Serial.println("connection failed");
}
}
void loop()
{
if (client.available()) {
char c = client.read();
Serial.print(c);
}
if (!client.connected()) {
Serial.println();
Serial.println("disconnecting.");
client.stop();
for(;;)
;
}
}

3.3. connect()
Description
Connect to the IP address and port specified in the constructor. The return value indicates
success or failure.
Syntax
client.connect()
Parameters
none
Returns
Returns true if the connection succeeds, false if not.
Example
#include <Ethernet.h>
byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 10, 0, 0, 177 };
byte server[] = { 64, 233, 187, 99 }; // Google
Client client(server, 80);
void setup()

12
Nuno Pessanha Santos – [email protected] / [email protected]
{
Ethernet.begin(mac, ip);
Serial.begin(9600);
delay(1000);
Serial.println("connecting...");
if (client.connect()) {
Serial.println("connected");
client.println("GET /search?q=arduino HTTP/1.0");
client.println();
} else {
Serial.println("connection failed");
}
}
void loop()
{
if (client.available()) {
char c = client.read();
Serial.print(c);
}
if (!client.connected()) {
Serial.println();
Serial.println("disconnecting.");
client.stop();
for(;;)
;
}
}

13
Nuno Pessanha Santos – [email protected] / [email protected]
3.4. write()
Description
Write data to the server the client is connected to.
Syntax
client.write(data)
Parameters
data: the byte or char to write

3.5. print()
Description
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: BIN for binary (base 2), DEC for decimal
(base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).

3.6. println()
Description
Print data, followed by a 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)
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).

14
Nuno Pessanha Santos – [email protected] / [email protected]
3.7. available()
Description
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.
#include <Ethernet.h>

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

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

Client client(server, 80);

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

delay(1000);

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

if (client.connect()) {
Serial.println("connected");
client.println("GET /search?q=arduino HTTP/1.0");
client.println();
} else {
Serial.println("connection failed");
}
}

15
Nuno Pessanha Santos – [email protected] / [email protected]
void loop()
{
if (client.available()) {
char c = client.read();
Serial.print(c);
}

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

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

3.9. flush()
Discard any bytes that have been written to the client but not yet read.
Syntax
client.flush()
Parameters
none
Returns
none

16
Nuno Pessanha Santos – [email protected] / [email protected]
3.10. stop()
Description
Disconnect from the server.
Syntax
client.stop()
Parameters
none
Returns
none

17
Nuno Pessanha Santos – [email protected] / [email protected]