A Vagrant-powered virtual machine providing an isolated development environment for the ESP8266 $5 dollar "Internet of Things" WiFi module.
-
A way to communicate with the chip's 3.3V TTL serial interface. I've had success with a cable from Adafruit that's based on the PL2303 USB-to-TTL module.
-
VirtualBox, a free open source virtualization package.
-
Vagrant, a virtualization management tool geared towards development environments.
-
Clone this repository.
-
If you'll be using a USB-to-TTL device like the Adafruit one I noted above, you'll need to edit the
Vagrantfile
to include your device's VendorId and ProductId. If you have the exact one I mentioned above, you may be fine with the existing configuration, but you may as well do this step too to be sure. It's an easy one.Connect your device to your computer and from the command line, run
VBoxManage list usbhost
. The output should be a list of entries that look like this:$ VBoxManage list usbhost Host USB Devices: ... UUID: 738b44fd-2f57-49dd-a16a-e31a0e7fa46f VendorId: 0x067b (067B) ProductId: 0x2303 (2303) Revision: 3.0 (0300) Port: 1 USB version/speed: 0/1 Manufacturer: Prolific Technology Inc. Product: USB-Serial Controller Address: p=0x2303;v=0x067b;s=0x0002653c8cdc2c52;l=0x14100000 Current State: Captured
Note the VendorId and ProductId. Set the
$vendor_id
and$product_id
variables inVagrantfile
to those values. They must be strings of the hexadecimal representations. -
In the console, run
vagrant up
. Note that this may take a decent chunk of time -- it was ~30 minutes on my 2013 Macbook Pro. Most of it is spent building the cross-compiler. Don't worry, it's a one-time cost. -
That's it! Now you can
vagrant ssh
and start building your images!
Well, if you're brand new to Vagrant, skip down a couple of sections for a very brief primer, then come back.
Oh hi! Wecome back! Now, if I were you, first thing I'd do is make sure my
serial cable worked. With it plugged in, vagrant ssh
into the machine and
run lsusb
to make sure it's in your list of devices. To see where it's
attached, run dmesg
and somewhere near the bottom you should see something
like usb 1-1: pl2303 converter now attached to ttyUSB0
. If not, you might try
unplugging it and plugging it back in, then running it again -- that way it'll
definitely be near the bottom of the log. If your device is attached anywhere
besides /dev/ttyUSB0
, you'll need to adjust your scripts and Makefiles as
appropriate. No big deal.
console.sh
is a tiny script to start a serial console on /dev/ttyUSB0
at
115200 baud. Most ESPs seem to ship with their baud set to that. You may need
to change the device, of course, based on the output from dmesg
. Now go ahead
and run that bad boy.
Plug your ESP8266 into your serial interface and tie its CH_PD and GPIO0 pins
HIGH. Pinouts, along with a ton of other info, can be found on the esp8266
wiki. Now
power it on. You should see a bunch of garbage in your serial terminal,
followed by the word READY
. Type AS+RST
and hit Enter, and you should get
this back:
AT+RST
OK
ets Jan 8 2013,rst cause:4, boot mode:(3,6)
wdt reset
load 0x40100000, len 24236, room 16
tail 12
chksum 0xb7
ho 0 tail 12 room 4
load 0x3ffe8000, len 3008, room 12
tail 4
chksum 0x2c
load 0x3ffe8bc0, len 4816, room 4
tail 12
chksum 0x46
csum 0x46
ready
You're in business! Now the fun part -- you can either play around with the AT commands, or kill the console and go on to build...
I've included a very awesome sample project from
Sprite_tm -- an HTTP server dubbed
esphttpd. From inside the
virtual machine, cd /vagrant/esphttpd && make
to build it. Then make sure
your chip is in firmware upload mode by tieing the CH_PD and GPIO2 pins HIGH
and the GPIO0 pin LOW. Power it on, and run sudo make flash
, followed by
sudo make htmlflash
. (The sudo
s are needed to access /dev/ttyUSB0)
NOTE 1: you may receive Failed to leave flash mode
exceptions after each
flash. Don't worry, it's most likely a false alarm.
NOTE 2: It's generally a good idea to power cycle the chip between uploads.
sudo make flash
includes a sleep 3
between two flashes to different
areas of memory, so you can use that delay to cycle.
For more info, see esphttpd/README
.
The project's root directory is mirrored to /vagrant
on the virtual machine.
You can sudo
from inside the machine without a password.
vagrant ssh
- ssh into the machine
vagrant halt
- shuts down the machine
vagrant suspend
- puts the machine to sleep
vagrant destroy
- removes every trace of the machine. NOTE: after a destroy,
the next vagrant up
will have to reprovision the machine from scratch,
meaning it'll take a while.
vagrant up
- spins up the machine, bringing it back up from halt
,
suspend
, or destroy
- https://github.com/esp8266/esp8266-wiki - the wiki containing everything I needed to build this repo
- http:https://esp8266.com - a forum for people interested in hacking on the chip
#esp8266
on Freenode- http:https://www.electrodragon.com/w/Wi07c - another nice wiki I found useful for exploring the AT commands
esphttpd, along with all the other resources in this repo, was copied wholesale from another place. In the case of esphttpd, that other place is this git repo. I decided to do this rather than make references to everything so that this repo would remain a set of tools that work together out of the box. I may change this practice in the future.
UPDATE: it's the future, and @slaff has helped move toward not shoving everything into this repo, so crosstool-NG is now pulled in by the provisioning script. So is esptool.py. Thanks @slaff!