Lightning Piggy Web Installer

This easy and intuitive web installer allows anyone to easily and repeatably build a Lightning Piggy for themselves, using only the browser.

If something doesn't work, take a look at the troubleshooting instructions.

Step 1

Connect your Lightning Piggy to your PC with a USB cable.

Make sure it's a regular cable that supports data and power, not just power, as we'll need to send data.

The power light of the Lightning Piggy should turn on, indicting that it's started.

Step 2a (required)

Fill in the configuration details so your Lightning Piggy knows which network to connect to and which servers to use:

Step 2b (optional)

Specify these options to enable more features:

Step 3

Choose your Lightning Piggy flavor and click "START INSTALLATION":

Step 4

Tell your webbrowser which serial port to use. Usually it's the one with "CP210" because that's the type of USB-to-Serial chip that's in the Lightning Piggy.

We've tested this with Google Chrome on Linux, MacOS and Windows so if you're using that setup, it should work!

Tell your webbrowser which serial port to use.

Step 5

Click choose the "INSTALL" option and confirm that it will erase the data on your Lighning Piggy.

Device dashboard install Confirm Installation

Step 6

Wait and watch the installation progress!

Wait and watch the installation progress

Don't unplug your Lightning Piggy while it's installing as that might lead to it not starting up anymore.

Step 7

You'll get confirmation when the installation is complete.

Installation complete.



Your computer needs to have a "device driver" installed to know how to talk to the Lightning Piggy.

On Linux computers (such as Ubuntu) these drivers are usually installed by default, so you're good!

On Windows and MacOS computers, you might get a popup that tells you to install one of these drivers if you don't select a serial port:

No port selected - install drivers


If your computer has the driver, but your webbrowser is unable to access your computer's serial port, you'll get an error like "Failed to open serial port":

Failed to open serial port

On Linux and MacOS computers, you can fix this by running a command that (temporarily) gives all users access to it. Something like:

sudo chmod 777 /dev/ttyUSB*

Checking Lightning Piggy's logs

You can view and download the serial port logs to see what your Lightning Piggy is doing behind the scenes while it's starting up.

To do so, click "Logs and Console" and perhaps push the reset button on your Lightning Piggy to do a fresh startup.

Logs and console

There's a "Download Logs" button that will let you download them so you can include them when you're reporting an issue or asking for help.

The default filename is "esp-web-tools-logs.txt" because that's what's used to install the firmware.

Logs and console

Checking your webbrowser's logs

You can view and download the logs (called "console") of your web browser by pressing F12 or CTRL+SHIFT+i to bring up the Developer Tools.

On the tab "Console" you can see what the installer is doing in the background. These details can help pinpoint an issue.

Browser console

Errors about "Improv Wi-Fi Serial" are normal, as the Lightning Piggy doesn't support nor need Improv Wi-Fi at the moment.

Ad Blockers and other browser extensions

If you're getting weird Javascript errors such as 'Trying to access beyond buffer length', it might be caused by your Adblocker or other browser extensions messing with the installer's Javascript.

Please try disabling them for this page and see if that helps.

Typical configuration mistakes

For the hostname (such as fill in only the hostname itself, not

Most configurations are case-sensitive, so for the boot slogan use YES and not Yes or yes. Same for the timezone, for the currency etc.

Reporting issues

Of course, it's possible that your specific setup causes an issue or there's a bug somewhere that prevents you from installing your Lightning Piggy.

If you think that's the case, please gather all the details you can about your specific setup, including the logs of the Lightning Piggy and your webbrowser (if you can) and make a few screenshots to show what works and what doesn't.

Then create a new GitHub Issue and attach the files to it. That will allow the community to help you troubleshoot, find a solution, and improve the project to prevent similar issues from occurring. Thanks for helping out!