sparkf un.

co m

https://www.sparkfun.co m/tuto rials/409

SparkFun Ethernet Shield Quickstart Guide

Equip your Arduino with network/internet connectivity using the SparkFun Ethernet Shield and the powerf ul Ethernet library! In this tutorial, well cover how to get up and running with the SparkFun Ethernet Shield. Requirements, hardware, assembly, and programming will all be covered. Follow along, and your Arduino should be skimming Twitter and hosting webpages in no time!

Requirements
In addition to the shield, youll need a f ew more bits and pieces to get the most out of the SparkFun Ethernet Shield:

Headers (and soldering t ools)

Headers provide the shield with a solid, electrical connection to your Arduino. You've got a f ew options when it comes to headers, but f or most shields I recommend the stacking headers. T hese allow you to plug wires, or even other shields, into the unused Arduino pins. You will need to solder those headers into your shield. So, if you dont already have one, Id recommend getting a good, cheap soldering iron, and some solder. A stand wouldnt hurt either, and it might save your carpet. (More on this in the assembly section below).

An Et hernet cable
T his will interf ace between your Ethernet Shields RJ-45 jack and a router or switch. CAT 5, CAT 6, really anything with a pair of RJ-45 terminations should work. Find a length that works best f or you 1, 3, 5, or 10 f eet. Or make your own cable to f ind your best f it!

SD Card (opt ional)

Youll quickly f ind that the Ethernet-equipped Arduino sketches use a big chunk of the Arduinos SRAM and f lash. If you want to host webpages, or read and store inf ormation, a SD card is a great way to expand upon the Arduinos rather limited memory. You wont need a high-capacity card 1GB or so will certainly do though really any SD card youve got lying around should work.

Arduino Development Board

While the Ethernet Shield could work with just about any development platf orm, its certainly best suited f or Arduinos. If youre looking f or an Arduino to pair with this shield, Id recommend the rock-solid Arduino Uno. Other Arduinos (Mega, Leonardo, Due) should work with the Shield, but you

may need a TransmogriShield to move pins around.

Arduino Sof t ware

No revelations here, youll need the Arduino IDE to program the Arduino. Fortunately f or us, the IDE comes with a f antastic Ethernet library as well as an SD library. If you dont have the most recent version, you can download it f rom Arduinos downloads page.

Hardware
T he SparkFun Ethernet Shield is comprised of two stand-out components a Wiznet W5100 T CP/IP embedded Ethernet controller and a SD socket. T he W5100 is a powerf ul little chip, which implements all sorts of complex network protocols T CP, UDP, ICMP, IPv4, ARP, IGMP, PPPoE, and the physcial Ethernet layer. T his alleviates a lot of programming stress on us and memory stress on the Arduino. All of the communication between the W5100 and the Arduino is SPI-based and handled using the Ethernet library, which well discuss in the f irmware section below. T he W5100 is supported by a number of components capacitors, a crystal, reset monitors but most especially an Ethernet jack, actually a MagJack. Inside that little RJ-45 jack are a number of transf ormers and magnetics required f or isolating Ethernet signals (you could say this jack ismore than meets the eye). T here are even some LEDs poking out the end. T he SD socket extends near the edge of the shield, where the card should be inserted. T he socket sits next to a 74HC4050 (high-to-low level shif ter), which handles all of the 5V-to-3.3V voltage shif ting (those delicate SD cards shouldn't be subjected to 5V signals). Some of the less spectacular components (dont tell them I said that) on the Ethernet Shield include a reset button, 3.3V regulator , and a number of blinky LEDs. T he reset button works just like the one the Arduino itself , though itll also reset the W5100. T he LEDs include a power indicator LED, as well as a number of status LEDs (Ethernet receive/transmit, collision, and speed) tied to the W5100, which will appear to have a mind of their own.

What Id really like to stress in this section is which pins the shield requires of the Arduino. Heres a table of the six pins used by the shield: Arduino Pin 2 4 SparkFun Ethernet Shield Pin Function W5100 - Interrupt output (optional, set with jumper) SD Card - Chip select

10 11 12 13

W5100 - Chip select SD Card and W5100 - MOSI SD Card and W5100 - MISO SD Card and W5100 - SPI Clock

In general youll want to avoid using the chip-select pins (4 and 10) f or anything else. If you have other SPI devices, you should be able to link them up on the same SPI bus (pins 11, 12, and 13). Pin 2 is actually not used by def ault on the shield. T heres a jumper on the top side of the board if you want to enable the W5100s interrupt output (I dont think the Ethernet shield makes use of this pin regardless, though). T he SparkFun Ethernet Shield, particularly the Wiznet W5100, can be a power-hungry little beast. Its recommended that you use a power supply that can source at least 400mA. Powering the shield over USB will work in most cases, though it wouldnt hurt to power your Arduino via a 9V wall-wart. T he W5100s hunger f or power will cause it and the 3.3V regulator to heat up. T his is normal, especially when the chip is doing a lot of work. T hey should never get untouchable hot, but they might get too-hot-tocomf ortably-leave-your-f inger-on-f or-extended-periods hot.

Assembly
T heres really just one step in this section: soldering ! If youve never soldered bef ore, thats OK! T his is actually a perf ect place to start all of the solder points are through-hole and well-spaced. However, Id really recommend checking out our soldering crash course f irst. Read the guide, watch the video, and youll pick up some good tips that will help your f irst soldering experience go more smoothly. T here are f our headers to solder. T he real challenge in soldering these headers is getting them straight and aligned with eachother and the mating Arduino headers. Insert the headers through the top-side of the Ethernet Shield board so the extra-long pins extend out the bottom. I like to insert all f our of my headers bef ore soldering any of them. When plugging them in, make sure the 6-pin headers go into the 6-pin holes and the 8-pin headers to the 8-pin holes.

Now, f lip the board over, and solder all 28 connections. Try to keep the header pins extending f rom the bottom of the shield as perpendicular to the PCB as possible. If you have another shield, it does a great job holding those headers straight (like in the above picture).

Once the shield is soldered, f eel f ree to plug it into the Arduino. Make sure none of the pins bend and they

all go into their mating Arduino pins. You can also plug a SD card and Ethernet cable into the Ethernet Shield. T he SD card goes into the shiny little socket on the end of the board; insert it so that the cards logo is f acing up. Plug one in, and f eel that satisf ying, locking click. Youll also need to plug that Ethernet cable to something on the other end. It could be an RJ-45 wall-jack, an Ethernet switch, router, or an ad-hoc something-or-other. Finally, once youve gotten all of that plugged in, power up the Arduino . You should be able to power it of f the USB cable. And, with that, you should see some blinkies! T he PWR LED should illuminate f or sure. You may also see the SPD, and RX/TX light up/blink too. Also look f or the green and yellow LEDs on the magjack to light up as well.

Time to upload some code to the Arduino!

Firmware
T he examples in this section will all make use of the Arduino Ethernet library. T his library comes with Arduino, so no downloading or installing required. Id encourage you to check out all of the example sketches f or the Ethernet library. Go to File > Examples > Ethernet > and pick a sketch to check out, most should work without any modif ication. T he Ethernet library allows the Arduino to turn into one of two Ethernet devices: a client or a server . Turning your Arduino into client allows you to connect to and request data f rom servers. For example, your client could make an http request to Twitter, and search f or a tweet. Lets discuss a client example f irst.

Et hernet Client
Load up the TwitterClient example in the File > Examples > Ethernet menu. T his is my go-to example f or making sure my Ethernet Shield is working. T his example connects to Twitter and uses its API to search f or arduino. It displays the results in the Serial Monitor.

T here are a f ew f unctions and variable declarations Id like to point out in this example. First, near the top, we declare an array named mac, and an IPAddres named ip: byt e mac[] = { 0x00, 0xAA, 0xBB, 0xCC, 0xDE, 0x01 }; IPAddress ip(192,168,1,20); // init ialize t he library inst ance: Et hernet Client client ; ... char serverName[] = "api.t wit t er.com"; // t wit t er URL T hat mac variable is what will become the MAC address of your Arduino a 6-byte value, which should be unique to a network, and represents the physical network address of your device. Every Arduino Ethernet sketch will need to declare a MAC address. T hese are declared as an array of bytes (in this example the MAC address becomes 00-AA-BB-CC-DE-01) but Id encourage you to create your own MAC. Just remember its a hex value, so only use 0-9 and A-F, and it must be six bytes. T he ip variable declares a static IP address f or your Arduino. T he value above would set the static IP address of the Arduino to 192.168.1.20. You may have to change this value, depending on your network subnet and gateway addresses. Also know that this variable is optional. Hopef ully you dont even have to use it. T he Ethernet library has DHCP f unctionality, which means your Arduino can be assigned a dynamic IP by a DHCP server. T his is great f or client sketches where knowing our IP doesnt matter as much. Finally, we make a call to the EthernetClient class to create an instance named client . T he client object is going to be widely used through the rest of this sketch whenever we want to connect to a server or send/receive data. Finally, the serverName string is set to the Twitter URL. T he Ethernet library has DNS built in, so you dont have to seek out IP addresses if you dont want to! T his string will be used later, when we attempt to connect to Twitter. Next lets look inside the set up() f unction, where youll see this: if (!Et hernet .begin(mac)) { // if DHCP fails, st art wit h a hard-coded address: Serial.print ln("failed t o get an IP address using DHCP, t rying manually"); Et hernet .begin(mac, ip); } Ethernet.begin() should be called in every Ethernet sketch. Its used to initialize the Ethernet library as well as the network settings on your Arduino. Notice that there are two different calls to Et hernet .begin(). T he f irst call puts solely the MAC address as a parameter. T his version of begin attempts to grab a dynamic IP address f rom a DHCP server. If that f ails, it tries to connect using the static IP def ined earlier. Finally, check out the connect ToServer() f unction:

void connect ToServer() { // at t empt t o connect , and wait a millisecond: Serial.print ln("connect ing t o server..."); if (client .connect (serverName, 80)) { Serial.print ln("making HTTP request ..."); // make HTTP GET request t o t wit t er: client .print ln("GET /1/st at uses/user_t imeline.xml?screen_name=arduino&count =1 HTTP/1.1"); client .print ln("HOST: api.t wit t er.com"); client .print ln(); } // not e t he t ime of t his connect at t empt : last At t empt Time = millis(); } T his f unction uses the client.connect() to attempt to connect to Twitters API on the T CP port (80). Following that, it makes an HT T P GET request to the server asking f or at an address of api.twitter.com/1/statuses/user_timeline.xml?screen_name=arduino&count=1. For more inf o on what that means check out the Twitters API Documentation. Basically, were seeking out the timeline of @arduino, and looking at the single most recent tweet theyve sent. You could even look at other users timelines by replacing arduino with sparkfun or whatever your f avorite twitter stream may be. Finally, in the loop, assuming the Arduino connected to the twitter server, well read in the HT T P data returned. Much of the loop is devoted to parsing the returned data, so we end up with something like this if we peer into the Serial Monitor: Attempting to get an IP address using DHCP: My address:192.168.20.53 connecting to server... making HT T P request... >@aoqassam nice :) Go have some f un with Twitter, or learn how to setup your Arduino as a server next.

Et hernet Server
Another great example included with Arduinos Ethernet library is WebServer . Find it under File > Examples > Ethernet. T his sketch sets up the Arduino as a server device, and hosts up a webpage whenever a client connects to it. T he webpage is simple it shows the status of the analog pins ,but it goes a long way to showing what can be done. At the top are some f amiliar variable def initions mac and ip. T he IP address def inition becomes much more important in this case, because youll need to know the IP address when pointing your browser to the Arduino. You may need to modif y the ip variable to conf orm with your networks gateway. T he def ault 192.168.1.177 will work f or networks gateways like the common 192.168.1.0, but it may need to be modif ied f or others. Also make sure the IP address you pick isnt already in use by another device on the network, creating an IP address conflict . IP addresses must be unique! You can still opt to use DHCP, by removing the ip parameter f rom the Et hernet .begin(mac) line. Keep in mind that, with dynamic address assignments, your IP address could change f rom reset to reset. In this sketch, the EthernetServer class is used to create an object named server on port 80 (T CP). And server.begin() is called to initialize the server. In the loop we wait f or a client to connect. Once we get something, the Arduino serves up a simple HT ML webpage. client .print lns and client .print s are used to serve up HT ML code. Try it out! Upload the code, and point your computers web browser to the IP address assigned to your

Arduino. You may need to open up your Serial Monitor to f ind out what IP address it was assigned. T hatll result in something like this: server is at 192.168.20.58 new client GET / HT T P/1.1 Host: 192.168.20.58 Connection: keep-alive CacheControl: max-age=0 User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.11 (KHT ML, like Gecko) Chrome/23.0.1271.91 Saf ari/537.11 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Ref erer: http://192.168.20.58/ AcceptEncoding: gzip,def late,sdch Accept-Language: en-US,en;q=0.8 Accept-Charset: ISO-8859-1,utf 8;q=0.7,*;q=0.3 client disonnected new client GET /f avicon.ico HT T P/1.1 Host: 192.168.20.58 Connection: keep-alive Accept: */* User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.11 (KHT ML, like Gecko) Chrome/23.0.1271.91 Saf ari/537.11 Accept-Encoding: gzip,def late,sdch Accept-Language: en-US,en;q=0.8 Accept-Charset: ISO-8859-1,utf -8;q=0.7,*;q=0.3 client disconnected Notice the IP address it lists f or your Arduino server. Assuming your computers on the same network, you should be able to open up your f avorite web browser, type the IP address into the address bar and GO. You should be greeted with a webpage like below. Which reloads itself every f ive seconds or so. If youve got some HT ML-f u try modif ying or adding more client .print s to make your webpage prettier.

Resources
Here are some documents related to the Ethernet Shield itself which you might f ind usef ul: Schematic If youd like more in-depth inf ormation on the SparkFun Ethernet Shields hardware setup, check the schematic out. Eagle Files T hese are the PCB design f iles, shared because this hardware is open source! You can download and use Eagle Lite f or f ree to view these f iles. For more inf ormation on the Arduino libraries used: Ethernet library ref erence SD library ref erence Thanks for reading! I hope this has gotten you well on the way to creating the next super-awesome, network-

enabled Arduino project. If youre left with any burning questions, comments, or feedback, please post away in the comments below!