Sams Teach Yourself Arduino Programming in 24 Hours (2015)

---

The Ethernet Class

The Ethernet class contains three class methods:

begin: Initializes the network connection.

localIP: Retrieves the IP address of the Ethernet Shield.

maintain: Requests a renewal of a Dynamic Host Control Protocol (DHCP) IP address.

Every sketch that uses the Ethernet Shield must use the Ethernet class begin method to initialize the shield on the network. The begin method has one required parameter and four optional parameters:

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

In Ethernet networks, every device must have a unique low-level address, called the Media Access Control (MAC) address. The MAC address is usually expressed as a 12-digit hexadecimal number, often using colons or dashes to separate the numbers in pairs to make it easier to read. For example, my Arduino Ethernet Shield MAC address is shown on the sticker as follows:

90-A2-DA-0E-98-34

Newer Arduino Ethernet Shield devices are each assigned a unique MAC address and have a sticker with the address on the device. Older Ethernet Shield devices aren’t assigned a unique MAC address, so it’s up to you to assign one with the begin method. Just make sure that the address you use doesn’t match any other devices on your network.

Besides the MAC address, to interact on the network, your Arduino device will also need a unique IP address. The IP address identifies each network device within a specific subnetwork.

You can assign an IP address to a network device in two different ways:

Manually assign a static address

Request an address from the network dynamically

The following two sections discuss how to use both types of address methods with your Ethernet Shield.

Static Addresses

For the static address method, you’re responsible for assigning a unique IP address to each device on your network. You do that by specifying both the MAC and IP addresses in the begin method:

Ethernet.begin(mac, ip);

You specify the MAC address using a byte array of hexadecimal values. For example:

byte mac[] = {0x90, 0xa2, 0xda, 0x0e, 0x98, 0x34 };

Unfortunately, you cannot specify the IP address as a string value. This is where the IPAddress class comes in. The IPAddress class allows you to specify an IP address using standard decimal numbers, but converts them into the byte format required for the begin method:

IPAddress ip(192, 168, 1, 10);

Besides the IP address, you may also need to assign a default router and subnet mask for your Arduino device to communicate outside of your local network, and may need to provide the IP address of the DNS server for your network:

IPAddress gateway(192, 168, 1, 1);
IPAddress dns(192, 168, 1, 1);
IPAddress subnet(255, 255, 255, 0);

After you define all the values, you just plug them into the begin method:

byte mac[] = {0x90, 0xa2, 0xda, 0x0e, 0x98, 0x34 };
IPAddress ip(192, 168, 1, 10);
IPAddress gateway(192, 168, 1, 1);
IPAddress dns(192, 168, 1, 1);
IPAddress subnet(255, 255, 255, 0);
Ethernet.begin(mac, ip, dns, gateway, subnet);

After you’ve assigned the IP address to the Ethernet Shield, you’re ready to start communicating on the network.

Dynamic Addresses

The Dynamic Host Configuration Protocol (DHCP) provides a way for network devices to obtain an IP address automatically from a network DHCP server. Most wired and wireless home network routers include a DHCP server to assign IP addresses to devices on the home network.

To obtain an IP address for your Arduino using DHCP, you use the begin function, but only specify the MAC address for the device:

byte mac[] = {0x90, 0xa2, 0xda, 0x0e, 0x98, 0x34 };
Ethernet.begin(mac);

The Ethernet Shield will send a DHCP request onto the network, requesting an IP address (and any other network information such as the DNS server and default gateway) from the DHCP server.

When you use the begin method in DHCP mode, it will return a true value if a valid IP address is assigned to the Ethernet Shield, or a false value if not. You can test that in your code:

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

void setup() {
Serial.begin(9600);
byte mac[] = {0x90, 0xa2, 0xda, 0x0e, 0x98, 0x34 };
if (Ethernet.begin(mac))
{
Serial.print("Found a valid IP address: ");
Serial.println(Ethernet.localIP());
} else
{
Serial.println("Unable to get an IP address");
}
}

void loop() {
}

As shown here, you use the localIP method to retrieve the actual address assigned to the Ethernet Shield by the DHCP server. You’ll need that whether you’re using your Arduino as a server device, so that you know the address for your clients to connect to.

The EthernetClient Class

You use the EthernetClient class to connect to remote servers to exchange data. The client class allows you to send data to a remote host, as well as receive data from the remote host. The EthernetClient class has quite a few different methods, as shown in Table 21.1.

TABLE 21.1 The EthernetClient Class

Because you need to start the connection only once, you usually connect to the remote server within the setup function in your sketch. Then in the loop function, you can loop between sending and receiving data, depending on what the server requires. The connected function allows you to check whether the remote host has disconnected the session, and the available function allows you to check if any data has been sent from the remote host.

A simple client connection to retrieve an FTP server welcome message from a remote FTP server looks like this:

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

byte mac[] = {0x90, 0xa2, 0xda, 0x0e, 0x98, 0x34 };
EthernetClient client;

void setup() {
Serial.begin(9600);
Ethernet.begin(mac);
delay(1000);
if (client.connect("ftp.ubuntu.com", 21))
{
Serial.println("Connected to server");
} else
{
Serial.println("Connection attempt failed");
}
}

void loop() {
if (!client.connected())
{
Serial.println("Disconnected from remote host");
client.stop();
while(1);
} else
{
if (client.available())
{
char incoming = client.read();
Serial.print(incoming);
}
}
}

This code snippet uses the EthernetClient class to connect to the ftp.ubuntu.com FTP server on the standard FTP port (21). The FTP server returns a welcome message, which is received using the read method and displayed on the serial monitor. Figure 21.2 shows the output in the serial monitor after you run this program.

FIGURE 21.2 The serial monitor output showing the returned FTP server message.