sparkfun ESP8266 User manual

Introduction
Over the past year, the ESP8266 has been a growing star among IoT or Wi i-related projects.
It’s an extremely cost-effective Wi i module, that – with a little extra effort – can be
programmed just like any microcontroller. Unfortunately, the ESP8266 has mostly only been
available in a tiny, modular form, which, with limited I/O and a funky pin-out, can be difficult to
build a project around.
The original ESP8266 Wi i module. Great for piggybacking onto an Arduino, hard to build a
project around.
Spark un’s new development board for the ESP8266 breaks out all of the module’s pins, and
comes equipped with a LiPo charger, power supply, and all of the other supporting circuitry it
requires. We lovingly call it the Thing – it’s the perfect foundation for your Internet of Things.
P
i
n
I
t
S
h
a
r
e
o
n
F
a
c
e
b
o
o
k
S
h
a
r
e
o
n
T
w
i
t
t
e
r

Covered in this Tutorial
This tutorial will familiarize you with all things Spark un Thing. It’s split into sections, which
cover:
•Hardware Overview – A quick rundown of the Thing’s components and pinout.
•Powering the Thing – The Thing can be powered through either USB or a LiPo battery.
•Programming the Thing – Interface a 3.3V TDI Basic with the Thing to program it.
•Hardware Assembly – Tips and recommendations on what to solder to the Thing’s I/O
pins.
•Installing the ESP8266 Arduino Addon – The Thing can be programmed using Arduino!
Just follow the instructions here to install the board definitions.
•Example Sketch: Posting to Phant – Our first example shows how you can use the
Thing to post data to data.sparkfun.com.
•Example Sketch: AP Web Server – Set the Thing up as an access point and use it to
serve web pages.
•Example Sketch: Goodnight Thing (Sleep Mode) – Put the Thing to sleep to save that
sweet battery juice.
•Using the Arduino Addon – There are a few key differences between programming the
Thing and any other Arduino board.
Required Materials
To follow along with this tutorial, and get up-and-running with the Thing, you may need a few
extra tools and materials. This wishlist includes everything we use in this tutorial to program
and use the Thing:
ESP8266 Thing Hookup Guide Spark un Wish List
Spark un ESP8266 Thing WRL-13231 The Spark un ESP8266 Thing is a breakout and development board for
the ESP8266 Wi i SoC – a leading platform for Internet of Things (IoT) or Wi i-re…

Spark un Cerberus USB Cable - 6ft CAB-12016 You've got the wrong USB cable. It doesn't matter which one
you have, it's the wrong one. But what if you could have the right one? What if you could …
Spark un TDI Basic Breakout - 3.3V DEV-09873 This is the newest revision of our [ TDI Basic]
(http://www.sparkfun.com/commerce/product_info.php?products_id=8772). We now use a SMD 6-pin
header on …
(2) Arduino Stackable Header - 10 Pin PRT-11376 This is a 10-pin female header, with extra long
legs -- great for stacking R3-compatible Arduino shields! Pins are spaced by 0.1". **Documents:*** [D…
Polymer Lithium Ion Battery - 850mAh PRT-00341 These are very slim, extremely light weight
batteries based on the new Polymer Lithium Ion chemistry. This is the highest energy density currently
in …
VIEW ESP8266 THING HOOKUP GUIDE ON SPARKFUN.COM
Suggested Reading
Before continuing on with this tutorial, you may want to familiarize yourself with some of these
topics if they’re unfamiliar to you:
•How to Power a Project
•Logic Levels
•Serial Communication
•How to Solder
Hardware Overview
The ESP8266 Thing is a relatively simple board. The pins are broken out to two parallel,
breadboard-compatible rows. USB and LiPo connectors at the top of the board provide power
– controlled by the nearby ON/O switch. And LEDs towards the inside of the board indicate
power, charge, and status of the IC.
Here’s a quick overview of the Thing’s main components:

The Pinout
The Thing’s I/O headers can be broken down into three sections:
Serial Programming Header
This six-pin header will be the main point of contact between the Thing and your development
computer. The pinout of this header matches the extremely common “ TDI header.” That
means you can interface it with either a 3.3V TDI Basic or a 3.3V I/O TDI Cable to program
and debug the Thing.
or a quick breakdown of the pins on this header, consult the table below. If a pin is directly
tied to an ESP8266 I/O, it’ll be noted:
Pin
Label
ESP8266
I O # Notes
DTR
Performs auto-reset, and puts the ESP8266 into bootloader mode.
Connects through a capacitor to RESET, and a buffer to the ESP8266's
GPIO0.
TXO 7 ESP8266 UART1 data output.
RXI 8 ESP8266 UART1 data input.
3V3 By default, this pin does not supply the ESP8266 directly (a jumper on

the back can change that).
NC Not connected to anything on the Thing.
GND Ground (0V).
I2C Header
I 2 C is a very popular communication protocol in the embedded world. Whether you want to
hook the Thing up to a motion sensor, light sensor, digital-to-analog converter, or OLED
display, I2C is often the protocol of choice.
This header includes four pins – all that should be required to connect an I2C device up to the
Thing.
Pin
Label
ESP8266
I O # Notes
GND Ground (0V).
3V3 3.3V
SDA 2 Can either be used as ESP8266 GPIO2 or I2C serial data (SDA).
SCL 14 Can either be used as ESP8266 GPIO14 or I2C serial clock (SCL).
Also used as the SPI clock (SCLK).
This pinout matches that of most of our I2C-based breakout boards, so you can piggyback
them right on top of the Thing.
If you need the extra I/O, instead of I2C, the SDA and SCL pins can be used as GPIO 2 and
14 respectively. The SCL pin also serves as the clock (SCLK) for the ESP8266’s SPI
interface.
General I/O Header
The rest of the power, control, and I/O pins are broken out on the other side of the board.
They are:
Pin
Label
ESP8266
I O # Notes
GND Ground (0V).
VIN USB connected: ~4.5V output LiPo connected (no USB): ~3.7V output
No supply: Can be used as a voltage supply input to the 3.3V regulator.
55 This pin is also tied to the on-board LED.
00
44
13 13 Hardware SPI MOSI
12 12 Hardware SPI MISO
XPD 16 Can be connected to reset to set the ESP8266 into deep sleep mode.
ADC A0 A 10-bit ADC with a maximum voltage of 1V.
EN ESP8266 enable pin. HIGH = on, LOW = off. Pulled HIGH on-board.
What happened to the rest of the GPIO pins? Why the eclectic pin-numbering scheme? We’re
taking what the ESP8266 gives us. Unfortunately, most of the remaining GPIO are connected

to the on-board SPI flash memory IC, which stores the ESP8266’s program memory and
potentially other data.
Back of the Thing
lipping the Thing over revels a few trace jumpers and test points, which you may find handy
for your application. (Plus a friendly Phant.io logo, to remind you about our data storage
service on data.sparkfun.com.)
Jumpers
Jumper
Label
Default
Setting Notes
DTR Closed Allows for auto-reset while programming the ESP8266, but makes
serial debugging difficult.
I2C PU Closed Connects 10kΩ pull-up resistors to the SDA and SCL pins.
FTDI VCC Open Connects the 3V3 pin on the serial header directly to the
ESP8266's 3.3V supply.
Of these jumpers, the DTR one is the most commonly modified. The DTR output of the TDI
Basic is used for two purposes: to reset the ESP8266 and pull GPIO0 low (putting the chip in
bootloader mode). Keeping this jumper closed enables programming, but makes debugging
via the Serial Monitor difficult, as the board will reset into bootloader mode whenever the
terminal opens. Using and modifying this jumper is discussed later in this tutorial.
The TDI_VCC jumper defaults to open to ensure that, if a 3.3V Logic (5V power) TDI
Cable is used to program the Thing, 5V isn’t accidentally delivered to the IC. Also, most 3.3V
TDI boards don’t have a lot of juice to supply on the 3.3V bus (they often supply about 50mA
max).

Test Points
These pins are made available just in case they become necessary to your project. The six
pins bundled up together are connected to the Thing’s on-board SPI flash memory, but if you
really need the extra GPIO, or want to experiment with the pins, they’re available.
The RST pin is more useful, but we didn’t leave room to break it out – at least not
directly. RST is tied through a 0.1µ capacitor to the DTR pin, to allow for automatic reset
during programming. or many applications that need the RST pin, toggling the DTR pin
works as well. Putting the ESP8266 into deep sleep is one such application.
Selecting the Antenna
The Thing’s default Wi i antenna is a PCB trace antenna based on this TI app note. It’s cost-
effective and actually works really well!
If you need to connect a more sensitive antenna to the chip, a U. L connector is also
available on the board, but isn’t connected by default to the ESP8266’s antenna pin. To
connect this antenna to the chip, you’ll need to heat up the 0Ω resistor and rotate it 90°:
An (ugly, uncleaned) resistor swapped from printed antenna to U. L antenna.
A soldering iron, pair of tweezers, (2) steady hands, and good set of eyes should be enough
to accomplish the task.

Why Are There Unpopulated Parts?
We initially set out to make the Thing a secure, common-sensor base station. The empty pads
you see are landing spots for three unique IC’s:
•ATECC108A – A “full turnkey Elliptic Curve Digital Signature Algorithm (ECDSA)
engine”, which can be used for unique serial numbers, hashing, key storage, or
random numbers. A great start to securing your IoT project!
•TMP102 Temperature Sensor – A simple, 12-bit, digital temperature sensor.
•TSL2561 Light Sensor – A nifty luminosity/light sensor.
•Plus a few footprints for decoupling capacitors.
After a late change of heart, we decided to keep the board as low cost as possible (that’s the
ESP8266’s best feature!), while leaving the option for later expansion. The pads are still there.
If you want to add any of these components, hopefully all you should need is a hot air
station (maybe probably not a Heaterizer) and some tweezers.
Powering the Thing
The Thing provides for two methods of power delivery: USB or LiPo. The USB connector on
the Thing is of the Micro-B variety. A micro-B cable plugged into either a computer USB port
or a 5V USB Wall Wart can power the Thing.
Any of our single-cell LiPo batteries will also work to power the Thing – they all have the same
2-pin JST connector.

Add an 850mAh LiPo and an LSM9DS0 9Do IMU to the Thing, to create an IoT motion
sensor.
If both USB and LiPo are connected to the Thing, it’ll take power from the USB port and
charge the LiPo battery at up to 500mA.
Electrical Characteristics
The ESP8266’s maximum voltage is 3.6V, so the Thing has an onboard 3.3V regulator to
deliver a safe, consistent voltage to the IC. That means the ESP8266’s I/O pins also run at
3.3V, you’ll need to level shift any 5V signals running into the IC.
The input to this regulator can either be delivered by USB, LiPo battery, or through
the VIN pin.
Max Input Voltage: If you supply power to the board through the VIN, make sure the voltage
does not exceed 6V. That's the maximum input voltage of the AP2112K-3.3V regulator the
board uses.
Alternatively, if you have an external, regulated, supply you’d like to deliver directly to the
ESP8266, you can supply that voltage through the 3V3 pin (on the I2C header). While this
voltage doesn’t have to be 3.3V, it must be within the range of 1.7-3.6V.
Current Ratings
On average, the Thing pulls about 80mA. Wi i transmits and receives can momentarily
increase that draw. Here’s a table, transcribed from the ESP8266 datasheet, with some of the
more common current characteristics.
Parameter Typica
lMax Unit
Transmit 802.11b (1 Mbps) 215 mA
Transmit 802.11b (11 Mbps) 197 mA
Transmit 802.11g (54 Mbps) 145 mA
Transmit 802.11n 135 mA
Receive 802.11b 60 mA
Receive 802.11g 60 mA
Receive 802.11n 62 mA
Standby 0.9 mA
Deep Sleep 10 µA
Maximum I/O Pin Drive
Capability 12 mA
If your application requires maximum battery life, you’ll likely need to make liberal use of the
ESP8266’s deep sleep functionality. That’ll be covered later in this tutorial.

Programming the Thing
The ESP8266 has a built-in serial bootloader, which allows for easy programming and re-
programming. You don’t need a specialized, expensive programmer – just a simple, USB-to-
Serial converter.
We use a 3.3V TDI Basic to program the Thing, but other serial converters with 3.3V I/O
levels should work (e.g. TDI SmartBasic, TDI Cable 5V VCC-3.3V I/O, T231X Breakout.
The converter does need a DTR line in addition to the RX and TX pins.
The TDI Basic’s 6-pin header matches up exactly to the Thing’s 6-pin serial port header. To
set up for programming, simply connect the TDI directly to this port – take care to match up
the DTR and GND pins!
If you’re short on USB ports, the Spark un Cerberus Cable might be just what you need.

If you solder female headers to the Thing, plugging a 6-pin row of right-angle male
headers between the TDI and header helps create a temporary programming interface.
Hardware Assembly
Oh. We’re getting ahead of ourselves. To connect the TDI programmer to your Thing you’ll
need to solder something to the Thing.
If you’ve never soldered before, this is a great time to start! These solder points are easy,
through-hole pins, check out our How to Solder - Through-hole Soldering for help getting
started.
What, exactly, you solder to the board depends both on how you’ll use it in your project, and
how you’ll interface it with the programmer. When it comes to selecting a header (or wire) to
solder, there are a variety of options. We’ve tried a lot of them with the Thing:
10-pin Stackable Headers make it convenient to both breadboard the Thing and jumper wire
out of it.

Or you can mix and match headers to best fit your needs. Right-angle male headers may help
to interface between the TDI and the Thing. Straight male headers are a good choice for
low-profile connections. Straight female headers may help with connecting to I2C sensors.
And, of course, wire can be soldered to any of the pins that have a long way to connect to
something.

Once you’ve soldered up at least the programming port, you’re ready to load some code onto
the Thing. Let’s blink some LEDs and IoT (Internet our Thing).
Installing the ESP8266 Arduino Addon
There are a variety of development environments that can be equipped to program the
ESP8266. You can go with a simple Notepad/gcc setup, or fine-tune an Eclipse environment,
use a virtual machine provided by Espressif, or come up with something of your own.
ortunately, the amazing ESP8266 community recently took the IDE selection a step further
by creating an Arduino addon. If you’re just getting started programming the ESP8266, this is
the environment we recommend beginning with, and the one we’ll document in this tutorial.
This ESP8266 addon for Arduino is based on the amazing work by Ivan Grokhotkov and the
rest of the ESP8266 community. Check out the ESP8266 Arduino GitHub repository for more
information.

Installing the Addon With the Arduino Boards Manager
With the release of Arduino 1.6.4, adding third party boards to the Arduino IDE is easily
achieved through the new board manager. If you’re running an older version of Arduino (1.6.3
or earlier), we recommend upgrading now. As always, you can download the latest version of
Arduino from arduino.cc.
To begin, we’ll need to update the board manager with a custom URL. Open up Arduino, then
go to the Preferences ( ile > Preferences). Then, towards the bottom of the window, copy this
URL into the “Additional Board Manager URLs” text box:
COPY CODE
http://arduino.esp8266.com/stable/package_esp8266com_index.json
If you already have a URL in there, and want to keep it, you can separate multiple URLs by
placing a comma between them. (Arduino 1.6.5 added an expanded text box, separate links
in here by line.)
Hit OK. Then navigate to the Board Manager by going to Tools > Boards > Boards Manager.
There should be a couple new entries in addition to the standard Arduino boards. Look
for esp8266. Click on that entry, then select Install.

The board definitions and tools for the ESP8266 Thing include a whole new set of gcc, g++,
and other reasonably large, compiled binaries, so it may take a few minutes to download and
install (the archived file is ~110MB). Once the installation has completed, an Arduino-blue
“INSTALLED” will appear next to the entry.
Selecting the ESP8266 Thing Board
With the Board addon installed, all that’s left to do is select “ESP8266 Thing” from
the Tools > Boards menu.

Then select your TDI’s port number under the Tools > Port menu.
Upload Blink
To verify that everything works, try uploading the old standard: Blink. Instead of blinking pin
13, like you may be used to though, toggle pin 5, which is attached to the onboard LED.
COPY CODE
#define ESP8266_LED 5
void setup()
{
pinMode(ESP8266_LED, OUTPUT);
}
void loop()
{

digitalWrite(ESP8266_LED, HIGH);
delay(500);
digitalWrite(ESP8266_LED, LOW);
delay(500);
}
If the upload fails, first make sure the ESP8266 Thing is turned on – the red “PWR” LED
should be illuminated.
Faster Uploads! The serial upload speed defaults to 115200 bps, which is reliable, but can
feel a bit slow. You can increase the upload speed by a factor of about 8 by
selecting 921600 under the Tools > Upload Speed menu.
This faster upload speed can be slightly less reliable, but will save you loads of time!
There are still some bugs to be fleshed out of the esptool, sometimes it may take a couple
tries to successfully upload a sketch. If you continue to fail, try turning the ESP8266 Thing on
then off, or unplug then replug the TDI in. If you still have trouble, get in touch with our
amazing tech support team.
Example Sketch: Posting to Phant
Our main goal for creating the ESP8266 Thing was finding a good platform to interact with our
free online data storage service: data.sparkfun.com.
Here’s a simple example sketch that posts four values to a test stream. eel free to use that
stream temporarily to make sure your Thing is working (don’t abuse it please!).
Install the Phant Library! This example makes use of the Spark un Phant Arduino library, to
make assembling Phant POSTs as easy as possible. The Phant library can be installed using

Arduino's Library Manager. Go to the Sketch > Include Library > Manage Libraries..., then
search for "Phant" to find the library. Install the latest version (or at least 2.2.0).
Or you can grab the Phant library from our phant-arduino repository, and follow along with
our Installing an Arduino Library for help installing the library.
Copy the code below, or download the example sketch.
Before uploading your code to the Thing, make sure you modify
the Wi iSSD and Wi iPSK variables, setting them to the SSID and password of your Wi i
network. The rest of the sketch should just work.
COPY CODE
// Include the ESP8266 Wi i library. (Works a lot like the// Arduino Wi i library.)#include <ESP8266Wi i.h>//
Include the Spark un Phant library.#include <Phant.h>
//////////////////////// Wi i Definitions ////////////////////////const char Wi iSSID[] = "Wi i_Network";
const char Wi iPSK[] = "Wi i_Password";
/////////////////////// Pin Definitions ///////////////////////const int LED_PIN = 5; // Thing's onboard, green LEDconst int
ANALOG_PIN = A0; // The only analog pin on the Thingconst int DIGITAL_PIN = 12; // Digital pin to be read
////////////////// Phant Keys //////////////////const char PhantHost[] = "data.sparkfun.com";
const char PublicKey[] = "wpvZ9pE1qb JAjaGd3bn";
const char PrivateKey[] = "wzeB1z0xWNt1YJX27xdg";
/////////////////// Post Timing ///////////////////const unsigned long postRate = 30000;
unsigned long lastPost = 0;
void setup()
{
initHardware();
connectWi i();
digitalWrite(LED_PIN, HIGH);
}

void loop()
{
if (lastPost + postRate <= millis())
{
if (postToPhant())
lastPost = millis();
else
delay(100);
}
}
void connectWi i()
{
byte ledStatus = LOW;
// Set Wi i mode to station (as opposed to AP or AP_STA)
Wi i.mode(WI I_STA);
// Wi I.begin([ssid], [passkey]) initiates a Wi I connection
// to the stated [ssid], using the [passkey] as a WPA, WPA2,
// or WEP passphrase.
Wi i.begin(Wi iSSID, Wi iPSK);
// Use the Wi i.status() function to check if the ESP8266
// is connected to a Wi i network.
while (Wi i.status() != WL_CONNECTED)
{
// Blink the LED
digitalWrite(LED_PIN, ledStatus); // Write LED high/low
ledStatus = (ledStatus == HIGH) ? LOW : HIGH;
// Delays allow the ESP8266 to perform critical tasks
// defined outside of the sketch. These tasks include
// setting up, and maintaining, a Wi i connection.
delay(100);
// Potentially infinite loops are generally dangerous.
// Add delays -- allowing the processor to perform other
// tasks -- wherever possible.
}
}
void initHardware()
{
Serial.begin(9600);
pinMode(DIGITAL_PIN, INPUT_PULLUP);
pinMode(LED_PIN, OUTPUT);
digitalWrite(LED_PIN, LOW);
// Don't need to set ANALOG_PIN as input,
// that's all it can be.
}
int postToPhant()
{
// LED turns on when we enter, it'll go off when we
// successfully post.
digitalWrite(LED_PIN, HIGH);
// Declare an object from the Phant library - phant
Phant phant(PhantHost, PublicKey, PrivateKey);

// Do a little work to get a unique-ish name. Append the
// last two bytes of the MAC (HEX'd) to "Thing-":
uint8_t mac[WL_MAC_ADDR_LENGTH];
Wi i.macAddress(mac);
String macID = String(mac[WL_MAC_ADDR_LENGTH - 2], HEX) +
String(mac[WL_MAC_ADDR_LENGTH - 1], HEX);
macID.toUpperCase();
String postedID = "Thing-" + macID;
// Add the four field/value pairs defined by our stream:
phant.add("id", postedID);
phant.add("analog", analogRead(ANALOG_PIN));
phant.add("digital", digitalRead(DIGITAL_PIN));
phant.add("time", millis());
// Now connect to data.sparkfun.com, and post our data:
Wi iClient client;
const int httpPort = 80;
if (!client.connect(PhantHost, httpPort))
{
// If we fail to connect, return 0.
return 0;
}
// If we successfully connected, print our Phant post:
client.print(phant.post());
// Read all the lines of the reply from server and print them to Serial
while(client.available()){
String line = client.readStringUntil('\r');
//Serial.print(line); // Trying to avoid using serial
}
// Before we exit, turn the LED off.
digitalWrite(LED_PIN, LOW);
return 1; // Return success
}
After loading the code onto your Thing, it will begin to run. The status LED connected to pin 5
will initially blink at about 2 Hz. After the Thing connects to your network, the green LED will
turn solid and post to the test stream. At that point the LED will go dark, only blinking every
30s-or-so as the Thing posts to Phant again.
If the LED never stops blinking, your Thing is probably having trouble connecting to the Wi i
network. Make sure the SSID and PSK variables are set correctly.
our values are posted to the Phant stream: the reading from the ADC pin, a digital reading
from pin 12, the Thing’s ID (“Thing” appendd with the last two MAC bytes), and a time variable
loaded from the millis() function. Load up the test stream to check for your Thing’s signature
there!