Skip to content

Commit 5c3d75c

Browse files
pfalconpfalcon
committed
docs/esp8266: Update for new WebREPL setup procedure.
1 parent e84e3e7 commit 5c3d75c

4 files changed

Lines changed: 41 additions & 37 deletions

File tree

‎docs/esp8266/general.rst‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -71,13 +71,16 @@ and developers, who can diagnose themselves any issues arising from
7171
modifying the standard process).
7272

7373
Once the filesystem is mounted, ``boot.py`` is executed from it. The standard
74-
version of this file is created during first-time module set up and by
75-
default starts up a WebREPL daemon to handle incoming connections. This
76-
file is customizable by end users (for example, you may want to disable
77-
WebREPL for extra security, or add other services which should be run on
74+
version of this file is created during first-time module set up and has
75+
commands to start a WebREPL daemon (disabled by default, configurable
76+
with ``webrepl_setup`` module), etc. This
77+
file is customizable by end users (for example, you may want to set some
78+
parameters or add other services which should be run on
7879
a module start-up). But keep in mind that incorrect modifications to boot.py
7980
may still lead to boot loops or lock ups, requiring to reflash a module
80-
from scratch.
81+
from scratch. (In particular, it's recommended that you use either
82+
``webrepl_setup`` module or manual editing to configure WebREPL, but not
83+
both).
8184

8285
As a final step of boot procedure, ``main.py`` is executed from filesystem,
8386
if exists. This file is a hook to start up a user application each time

‎docs/esp8266/quickref.rst‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -336,29 +336,27 @@ WebREPL (web browser interactive prompt)
336336
WebREPL (REPL over WebSockets, accessible via a web browser) is an
337337
experimental feature available in ESP8266 port. Download web client
338338
from https://github.com/micropython/webrepl (hosted version available
339-
at http://micropython.org/webrepl), and start the daemon on a device
340-
using::
339+
at http://micropython.org/webrepl), and configure it by executing::
341340

342-
import webrepl
343-
webrepl.start()
341+
import webrepl_setup
344342

345-
(Release versions have it started on boot by default.)
343+
and following on-screen instructions. After reboot, it will be available
344+
for connection. If you disabled automatic start-up on boot, you may
345+
run configured daemon on demand using::
346346

347-
On a first connection, you will be prompted to set password for future
348-
sessions to use.
347+
import webrepl
348+
webrepl.start()
349349

350350
The supported way to use WebREPL is by connecting to ESP8266 access point,
351351
but the daemon is also started on STA interface if it is active, so if your
352352
router is set up and works correctly, you may also use WebREPL while connected
353353
to your normal Internet access point (use the ESP8266 AP connection method
354354
if you face any issues).
355355

356-
WebREPL is an experimental feature and a work in progress, and has known
357-
issues.
356+
Besides terminal/command prompt access, WebREPL also has provision for file
357+
transfer (both upload and download). Web client has buttons for the
358+
corresponding functions, or you can use command-line client ``webrepl_cli.py``
359+
from the repository above.
358360

359-
There's also provision to transfer (both upload and download)
360-
files over WebREPL connection, but it has even more experimental status
361-
than the WebREPL terminal mode. It is still a practical way to
362-
get script files onto ESP8266, so give it a try using ``webrepl_cli.py``
363-
from the repository above. See the MicroPython forum for other
364-
community-supported alternatives to transfer files to ESP8266.
361+
See the MicroPython forum for other community-supported alternatives
362+
to transfer files to ESP8266.

‎docs/esp8266/tutorial/filesystem.rst‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ device starts up.
6464
Accessing the filesystem via WebREPL
6565
------------------------------------
6666

67-
You can access the filesystem over WebREPL using the provided command-line
68-
tool. This tool is found at `<https://github.com/micropython/webrepl>`__
69-
and is called webrepl_cli.py. Please refer to that program for information
70-
on how to use it.
67+
You can access the filesystem over WebREPL using the web client in a browser
68+
or via the command-line tool. Please refer to Quick Reference and Tutorial
69+
sections for more information about WebREPL.

‎docs/esp8266/tutorial/repl.rst‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,18 @@ For your convenience, WebREPL client is hosted at
4141
locally from the the GitHub repository
4242
`<https://github.com/micropython/webrepl>`__ .
4343

44+
Before connecting to WebREPL, you should set a password and enable it via
45+
a normal serial connection. Initial versions of MicroPython for ESP8266
46+
came with WebREPL automatically enabled on the boot and with the
47+
ability to set a password via WiFi on the first connection, but as WebREPL
48+
was becoming more widely known and popular, the initial setup has switched
49+
to a wired connection for improved security::
50+
51+
import webrepl_setup
52+
53+
Follow the on-screen instructions and prompts. To make any changes active,
54+
you will need to reboot your device.
55+
4456
To use WebREPL connect your computer to the ESP8266's access point
4557
(MicroPython-xxxxxx, see the previous section about this). If you have
4658
already reconfigured your ESP8266 to connect to a router then you can
@@ -49,19 +61,11 @@ skip this part.
4961
Once you are on the same network as the ESP8266 you click the "Connect" button
5062
(if you are connecting via a router then you may need to change the IP address,
5163
by default the IP address is correct when connected to the ESP8266's access
52-
point). If the connection succeeds then you should see a welcome message.
53-
54-
On the first connection you need to set a password. Make sure that the
55-
terminal widget is selected by clicking on it, and then follow prompts to
56-
type in your password twice (they should match each other). Then ESP8266
57-
will then reboot with the password applied (the WiFi will go down but come
58-
back up again). Note that some modules may have troubles rebooting
59-
automatically and need reset button press or power cycle (do this if
60-
you don't see ESP8266 access point appearing in a minute or so).
61-
62-
You should then click the "Connect" button again, and enter your password
63-
to connect. If you type in the correct password you should get a prompt
64-
looking like ``>>>``. You can now start typing Python commands!
64+
point). If the connection succeeds then you should see a password prompt.
65+
66+
Once you type the password configured at the setup step above, press Enter once
67+
more and you should get a prompt looking like ``>>>``. You can now start
68+
typing Python commands!
6569

6670
Using the REPL
6771
--------------

0 commit comments

Comments
 (0)