Programming Arduino Getting Started with Sketches (2012)
10
Arduino Ethernet Programming
In this chapter, you will use an Ethernet shield to enable your Arduino to work over your home network (see Figure 10-1).
Figure 10-1 Arduino with Ethernet
Ethernet Shields
When buying an Ethernet shield, you need to take a little care, as you need to use an “official” shield based on the Wiznet chipset and not one of the cheaper but more difficult to use unofficial boards based on the ENC28J60 Ethernet controller chip.
The Ethernet shields are quite power hungry, so you will also need a 9V or 12V power supply rated at 1A or more. This supply will be attached to the Arduino power socket.
Communicating with Web Servers
Before looking at how the Arduino deals with communication between a browser and the web server that it uses, you need some understanding of the HyperText Transfer Protocol (HTTP) and the HyperText Markup Language (HTML).
HTTP
The HyperText Transport Protocol is the method by which web browsers communicate with a web server.
When you go to a page using a web browser, the browser sends a request to the server hosting that page, saying what it wants. What the browser asks for may be simply the contents of a page in HTML. The web server is always listening for such requests, and when it receives one, it processes it. In this simple case, processing the request just means sending back HTML that you have specified in the Arduino sketch.
HTML
The HyperText Markup Language is a way of adding formatting to ordinary text so that it looks good when the browser displays it. For example, the following code is HTML that displays on a browser page as shown in Figure 10-2:
The HTML contains tags. Tags have a start and an end and usually contain other tags. The start of a tag has a < and then the tag name, and then a >; for example, <html>. The end of a tag is similar except that it has a / after the <. In the preceding example, the outermost tag is <html> that contains a tab called <body>. All web pages should start with such tags, and you can see the corresponding ends for those tags at the end of the file. Note that you have to put the end tags in the right order, so the body tag must be closed before the html tag.
Now we get to the interesting bit in the middle, the h1 and p tags. These are the parts of the example that are actually displayed.
The h1 tag indicates a level 1 header. This has the effect of displaying the text that it contains in a large bold font. The p tag is a paragraph tag, and so all the text contained within it is displayed as a paragraph.
This really just scratches the surface of HTML. Many books and Internet resources are available for learning about HTML.
Figure 10-2 An HTML example
Arduino as a Web Server
The first example sketch simply uses the Arduino and Ethernet shield to make a small web server. It’s definitely not a Google server farm, but it will allow you to send a web request to your Arduino and view the results in a browser on your computer.
Before uploading the sketch 10-01, there are a couple of changes that you need to make. If you look at the top of the sketch, you will see the following lines:
The first of these, the mac address, must be unique among all the devices connected to your network. The second one is the IP address. Whereas most devices that you connect to your home network will have IP addresses assigned to them automatically by a protocol called Dynamic Host Configuration Protocol (DHCP), this is not true for the Ethernet shield. For this device, you have to define an IP address manually. This address cannot be any four numbers; they must be numbers that qualify as being internal IP addresses and fit in the range of IP addresses expected by your home router. Typically, the first three numbers will be something like 10.0.1.x or 192.168.1. x, where xis a number between 0 and 255. Some of these IP addresses will be in use by other devices on your network. To find an unused but valid IP address, connect to the administration page for your home router and look for an option that says “DHCP.” You should find a list of devices and their IP addresses, similar to that shown in Figure 10-3. Select a final number to use in you IP address. In this case, 192.168.1.30 looked like a good bet, and indeed it worked fine.
Attach the Arduino to your computer using the USB lead and upload the sketch. You can now disconnect the USB lead and attach the power supply to the Arduino and the Ethernet lead.
Open a connection on your computer’s browser to the IP address that you assigned for the Ethernet shield. Something very much like Figure 10-4 should appear.
Figure 10-3 Finding an unused IP address
Figure 10-4 A Simple Arduino server example
The listing for sketch 10-01 is as follows:
As with the LCD library discussed in Chapter 9, a standard Arduino library takes care of interfacing with the Ethernet shield.
The setup function initializes the Ethernet library using the mac and IP addresses that you set earlier.
The loop function is responsible for servicing any requests that come to the web server from a browser. If a request is waiting for a response, then calling server.available will return a client. A client is an object; you will learn a bit more about what this means in Chapter 11. But for now, all that you need to know is that whether a client exists (tested by the first if statement); then you can then determine whether it is connected to the web server by calling client.connected.
The next three lines of code print out a return header. This just tells the browser what type of content to display. In this case, the browser is to display HTML content.
Once the header has been written, all that remains is to write the remaining HTML back to the browser. This must include the usual <html> and <body> tags, and also includes a <h1> header tag and two <p> tags that will display the value on the analog input A0 and the value returned by the millis function; that value is the number of milliseconds since the Arduino was last reset.
Finally, client.stop tells the browser that the message is complete. The browser then displays the page.
Setting Arduino Pins over the Network
This second example of using an Ethernet shield allows you to turn the Arduino pins D3 to D7 on and off using a web form.
Unlike the simple server example, you are going to have to find a way to pass the pin settings to the Arduino.
The method for doing this is called posting data and is part of the HTTP standard. For this method to work, you have to build the posting mechanism into the HTML so that the Arduino returns HTML to the browser, which renders a form. This form (shown in Figure 10-5) has a selection of On and Off for each pin and an Update button that will send the pin settings to the Arduino.
Figure 10-5 The message sending form
When the Update button is pressed, a second request is sent to the Arduino. This will be just like the first request, except that the request will contain request parameters that will contain the values of the pins.
A request parameter is similar in concept to a function parameter. A function parameter enables you to get information to a function, such as the number of times to blink, and a request parameter enables you to pass data to the Arduino that is going to handle the web request. When the Arduino receives the web request, it can extract the pin settings from the request parameter and change the actual pins.
The code for the second example sketch follows:
The sketch uses two arrays to control the pins. The first, pins, just specifies which pins are to be used. The pinState array holds the state of each pin: either 0 or 1.
To get the information coming from the browser form about which pins should be on and which should be off, it is necessary to read the header coming from the browser. In fact, all you need is contained in the first line of the header. You will use a character array line1 to contain the first line of the header.
When the user clicks on the Update button and submits the form from the browser, the URL for the page will look something like this:
The request parameters come after the ? and are each separated by an &. Looking at the first parameter (0=1), this means that the first pin in the array (pins[0]) should have the value 1. If you were to look at the first line of the header, you would see those same request parameters there:
Before the parameters, there is the text GET/. This specifies the page requested by the browser. In this case, / indicates the root page.
In the loop of the sketch, you call the readHeader function to read the first line of the header. You then use the pageNameIs function to check that the page request is for the root page /.
The sketch then generates the header and the start of the HTML form that is to be displayed. Before writing the HTML for each of the pins, the sketch calls the setValuesFromParams function to read each of the request parameters and set the appropriate values in the pinStates array. This array is then used to set the values of the pin outputs before the writeHTMLforPin function is called for each of the pins. This function generates a selection list for each pin. It has to build this list part by part. The if statements ensure that the appropriate options are selected.
The functions readHeader, pageNameIs, and valueOfParam are useful general-purpose functions that you can make use of in your own sketches.
You can use your multimeter as you did in Chapter 6 to verify that the pins are indeed turning on and off. If you are feeling more adventurous, you could attach LEDs or relays to the pins to control things.
Conclusion
Having used shields and associated libraries in the last two chapters, it is now time to investigate the features that enable libraries to be written and learn how to write libraries of your own.