From 5c3d75c937c1e7d220dcb8fb4230dd8280b1453f Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 6 Nov 2016 10:02:33 +0300 Subject: [PATCH] docs/esp8266: Update for new WebREPL setup procedure. --- docs/esp8266/general.rst | 13 ++++++++----- docs/esp8266/quickref.rst | 28 +++++++++++++--------------- docs/esp8266/tutorial/filesystem.rst | 7 +++---- docs/esp8266/tutorial/repl.rst | 28 ++++++++++++++++------------ 4 files changed, 40 insertions(+), 36 deletions(-) diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index 3ffb2ff339..04afed46ed 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -71,13 +71,16 @@ and developers, who can diagnose themselves any issues arising from modifying the standard process). Once the filesystem is mounted, ``boot.py`` is executed from it. The standard -version of this file is created during first-time module set up and by -default starts up a WebREPL daemon to handle incoming connections. This -file is customizable by end users (for example, you may want to disable -WebREPL for extra security, or add other services which should be run on +version of this file is created during first-time module set up and has +commands to start a WebREPL daemon (disabled by default, configurable +with ``webrepl_setup`` module), etc. This +file is customizable by end users (for example, you may want to set some +parameters or add other services which should be run on a module start-up). But keep in mind that incorrect modifications to boot.py may still lead to boot loops or lock ups, requiring to reflash a module -from scratch. +from scratch. (In particular, it's recommended that you use either +``webrepl_setup`` module or manual editing to configure WebREPL, but not +both). As a final step of boot procedure, ``main.py`` is executed from filesystem, if exists. This file is a hook to start up a user application each time diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index d06fe5a6f1..4a7ed3404b 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -336,29 +336,27 @@ WebREPL (web browser interactive prompt) WebREPL (REPL over WebSockets, accessible via a web browser) is an experimental feature available in ESP8266 port. Download web client from https://github.com/micropython/webrepl (hosted version available -at http://micropython.org/webrepl), and start the daemon on a device -using:: +at http://micropython.org/webrepl), and configure it by executing:: + + import webrepl_setup + +and following on-screen instructions. After reboot, it will be available +for connection. If you disabled automatic start-up on boot, you may +run configured daemon on demand using:: import webrepl webrepl.start() -(Release versions have it started on boot by default.) - -On a first connection, you will be prompted to set password for future -sessions to use. - The supported way to use WebREPL is by connecting to ESP8266 access point, but the daemon is also started on STA interface if it is active, so if your router is set up and works correctly, you may also use WebREPL while connected to your normal Internet access point (use the ESP8266 AP connection method if you face any issues). -WebREPL is an experimental feature and a work in progress, and has known -issues. +Besides terminal/command prompt access, WebREPL also has provision for file +transfer (both upload and download). Web client has buttons for the +corresponding functions, or you can use command-line client ``webrepl_cli.py`` +from the repository above. -There's also provision to transfer (both upload and download) -files over WebREPL connection, but it has even more experimental status -than the WebREPL terminal mode. It is still a practical way to -get script files onto ESP8266, so give it a try using ``webrepl_cli.py`` -from the repository above. See the MicroPython forum for other -community-supported alternatives to transfer files to ESP8266. +See the MicroPython forum for other community-supported alternatives +to transfer files to ESP8266. diff --git a/docs/esp8266/tutorial/filesystem.rst b/docs/esp8266/tutorial/filesystem.rst index 9033a8576f..27b0d2608c 100644 --- a/docs/esp8266/tutorial/filesystem.rst +++ b/docs/esp8266/tutorial/filesystem.rst @@ -64,7 +64,6 @@ device starts up. Accessing the filesystem via WebREPL ------------------------------------ -You can access the filesystem over WebREPL using the provided command-line -tool. This tool is found at ``__ -and is called webrepl_cli.py. Please refer to that program for information -on how to use it. +You can access the filesystem over WebREPL using the web client in a browser +or via the command-line tool. Please refer to Quick Reference and Tutorial +sections for more information about WebREPL. diff --git a/docs/esp8266/tutorial/repl.rst b/docs/esp8266/tutorial/repl.rst index 338e9fdd8f..1922da128d 100644 --- a/docs/esp8266/tutorial/repl.rst +++ b/docs/esp8266/tutorial/repl.rst @@ -41,6 +41,18 @@ For your convenience, WebREPL client is hosted at locally from the the GitHub repository ``__ . +Before connecting to WebREPL, you should set a password and enable it via +a normal serial connection. Initial versions of MicroPython for ESP8266 +came with WebREPL automatically enabled on the boot and with the +ability to set a password via WiFi on the first connection, but as WebREPL +was becoming more widely known and popular, the initial setup has switched +to a wired connection for improved security:: + + import webrepl_setup + +Follow the on-screen instructions and prompts. To make any changes active, +you will need to reboot your device. + To use WebREPL connect your computer to the ESP8266's access point (MicroPython-xxxxxx, see the previous section about this). If you have already reconfigured your ESP8266 to connect to a router then you can @@ -49,19 +61,11 @@ skip this part. Once you are on the same network as the ESP8266 you click the "Connect" button (if you are connecting via a router then you may need to change the IP address, by default the IP address is correct when connected to the ESP8266's access -point). If the connection succeeds then you should see a welcome message. +point). If the connection succeeds then you should see a password prompt. -On the first connection you need to set a password. Make sure that the -terminal widget is selected by clicking on it, and then follow prompts to -type in your password twice (they should match each other). Then ESP8266 -will then reboot with the password applied (the WiFi will go down but come -back up again). Note that some modules may have troubles rebooting -automatically and need reset button press or power cycle (do this if -you don't see ESP8266 access point appearing in a minute or so). - -You should then click the "Connect" button again, and enter your password -to connect. If you type in the correct password you should get a prompt -looking like ``>>>``. You can now start typing Python commands! +Once you type the password configured at the setup step above, press Enter once +more and you should get a prompt looking like ``>>>``. You can now start +typing Python commands! Using the REPL --------------