Enable WebREPL

The first step to using the WebREPL is to make sure it is available and enabled on your ESP8266 board.  As of the latest 1.8.6 MicroPython releases the WebREPL is not enabled by default and must be switched on with a one time command run through the serial port.  Make sure you're using MicroPython 1.8.6 or higher to follow the below instructions.

Check out this handy guide on loading MicroPython firmware if you aren't sure how to load firmware.

To enable the WebREPL connect to the board using its serial connection and run the following command as mentioned in the documentation:

import webrepl_setup

You will be prompted to enable or disable the WebREPL, and to set a password.  Enter your choices for both prompts then press y when prompted to save and reboot.

Access WebREPL

Once the WebREPL is running you can connect to it over the ESP8266's WiFi radio.  If the board isn't connected already to a wireless access point then it will create one which you can connect to from your computer.

To connect to the board's WiFi network look for a WiFi network advertised as MicroPython-*:

Where the * is the a set of numbers and letters unique to each ESP8266 board (based on its MAC address).

You will need to enter the password micropythoN to connect to the board's access point (the N is capitalized!).  If you have trouble see more details on connecting to the board's WiFi network in the official documentation.

Next you'll need to have available the WebREPL client web page on your machine.  You can either access the client webpage from micropython.org (assuming your computer can be connected to both the internet and your MicroPython board's network) or download it from its home on GitHub by clicking the button below and extracting the files:

If you download the WebREPL client extract the files and open webrepl.html in your browser (Firefox and Chrome are the officially supported browsers at this time).

Note you can't access the WebREPL client page directly from the ESP8266 board.  To save space in flash memory the ESP8266 only provides a websocket interface and not the actual client webpage.  You'll need to download the WebREPL client page ahead of time or access it from the internet.

Once the WebREPL client page is loaded you should see something like the following (as of ~August 2016, be aware the WebREPL is under active development and might change how it looks over time!):

Now make sure your computer is connected to the ESP8266's WiFi network, then click the Connect button (using the default address of ws:// next to the button).

Once connected the WebREPL should prompt you to enter the password you set while running the webrepl_setup command earlier.  Enter the password that you set to continue.

Try entering Python code at the REPL to see the output of it running.  The WebREPL should function just like the serial REPL so you can use it to experiment with MicroPython, run code you've loaded on the board, and more:

That's all there is to accessing the WebREPL from the ESP8266's WiFi network!

Access WebREPL From Other WiFi Networks

Accessing the WebREPL over the ESP8266's own WiFi access point like above is handy if there's no router or other WiFi network available.  However if you do have access to a WiFi network you can instead connect the ESP8266 to this network and access the WebREPL from any other machine on the network.  This makes it easier to use the WebREPL without losing access to the internet or your own WiFi network on a laptop that can only be connected to one WiFi network at a time.

To use the WebREPL on another WiFi network you'll first need to connect the ESP8266 to the WiFi network.  The MicroPython ESP8266 documentation shows a few simple commands to connect to a network.  From the serial REPL (don't use the WebREPL since you'll lose access when the commands change to a different WiFi network!) run the following commands:

import network
wlan = network.WLAN(network.STA_IF)
wlan.connect('ssid', 'password')

Where ssid is the name of the WiFi access point SSID, and password is the password required to use the access point (try an empty string '' if no password is required).

After a moment the ESP8266 should connect to the WiFi network.  You can run the ifconfig function to check that the board has been assigned an IP address and is on the network:


Notice the first result from the ifconfig call is the IP address assigned to the ESP8266 ( in this example, but it will differ depending on your WiFi network).  If you don't see an IP address then something is wrong with the WiFi configuration or connection to the network.  Double check the SSID and password are correct and try the connect call again.

One important thing to note is that the ESP8266 will always remember the last WiFi network it used and attempt to connect automatically on reboot.  This is handy since it means when the ESP8266 boots up it will automatically connect to the last network without you having to run the commands above again.  The board will only remember the last network though and not an entire history of older networks.

Once the board is connected to the WiFi network enable the WebREPL (as described in the previous section) and notice it prints two IP addresses that it's listening on:

In this case the WebREPL is listening on which is the ESP8266's access point, and which is the IP address of the ESP8266 on a WiFi network.

Now open the WebREPL and use the IP address of the board on your network instead of the default:

Once connected you can use the WebREPL just as you were using it on the ESP8266's WiFi network!

Note if you're connecting the board to a WiFi network it is a very smart idea to disable debug output since connecting and disconnecting WiFi network and can spew debug output to the serial REPL.  If the board can't connect to the WiFi network, like if you move it to a different location away from the network, you'll see a constant stream of debug output as the board tries and fails to reconnect to the network.  This debug output can cause problems with tools like ampy that try to use the board's serial REPL and don't expect the debug output.

This guide was first published on Aug 26, 2016. It was last updated on Aug 26, 2016.

This page (Access WebREPL) was last updated on Aug 25, 2016.

Text editor powered by tinymce.