213 lines
7.9 KiB
ReStructuredText
213 lines
7.9 KiB
ReStructuredText
Getting a MicroPython REPL prompt
|
|
=================================
|
|
|
|
REPL stands for Read Evaluate Print Loop, and is the name given to the
|
|
interactive MicroPython prompt that you can access on the ESP8266. Using the
|
|
REPL is by far the easiest way to test out your code and run commands.
|
|
|
|
There are two ways to access the REPL: either via a wired connection through the
|
|
UART serial port, or via WiFi.
|
|
|
|
REPL over the serial port
|
|
-------------------------
|
|
|
|
The REPL is always available on the UART0 serial peripheral, which is connected
|
|
to the pins GPIO1 for TX and GPIO3 for RX. The baudrate of the REPL is 115200.
|
|
If your board has a USB-serial convertor on it then you should be able to access
|
|
the REPL directly from your PC. Otherwise you will need to have a way of
|
|
communicating with the UART.
|
|
|
|
To access the prompt over USB-serial you need to use a terminal emulator program.
|
|
On Windows TeraTerm is a good choice, on Mac you can use the built-in screen
|
|
program, and Linux has picocom and minicom. Of course, there are many other
|
|
terminal programs that will work, so pick your favourite!
|
|
|
|
For example, on Linux you can try running::
|
|
|
|
picocom /dev/ttyUSB0 -b115200
|
|
|
|
Once you have made the connection over the serial port you can test if it is
|
|
working by hitting enter a few times. You should see the Python REPL prompt,
|
|
indicated by ``>>>``.
|
|
|
|
WebREPL - a prompt over WiFi
|
|
----------------------------
|
|
|
|
WebREPL allows you to use the Python prompt over WiFi, connecting through a
|
|
browser. The latest versions of Firefox and Chrome are supported.
|
|
|
|
For your convenience, WebREPL client is hosted at
|
|
`<http://micropython.org/webrepl>`__ . Alternatively, you can install it
|
|
locally from the the GitHub repository
|
|
`<https://github.com/micropython/webrepl>`__ .
|
|
|
|
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
|
|
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 password prompt.
|
|
|
|
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
|
|
--------------
|
|
|
|
Once you have a prompt you can start experimenting! Anything you type at the
|
|
prompt will be executed after you press the Enter key. MicroPython will run
|
|
the code that you enter and print the result (if there is one). If there is an
|
|
error with the text that you enter then an error message is printed.
|
|
|
|
Try typing the following at the prompt::
|
|
|
|
>>> print('hello esp8266!')
|
|
hello esp8266!
|
|
|
|
Note that you shouldn't type the ``>>>`` arrows, they are there to indicate that
|
|
you should type the text after it at the prompt. And then the line following is
|
|
what the device should respond with. In the end, once you have entered the text
|
|
``print("hello esp8266!")`` and pressed the Enter key, the output on your screen
|
|
should look exactly like it does above.
|
|
|
|
If you already know some python you can now try some basic commands here. For
|
|
example::
|
|
|
|
>>> 1 + 2
|
|
3
|
|
>>> 1 / 2
|
|
0.5
|
|
>>> 12**34
|
|
4922235242952026704037113243122008064
|
|
|
|
If your board has an LED attached to GPIO2 (the ESP-12 modules do) then you can
|
|
turn it on and off using the following code::
|
|
|
|
>>> import machine
|
|
>>> pin = machine.Pin(2, machine.Pin.OUT)
|
|
>>> pin.on()
|
|
>>> pin.off()
|
|
|
|
Note that ``on`` method of a Pin might turn the LED off and ``off`` might
|
|
turn it on (or vice versa), depending on how the LED is wired on your board.
|
|
To resolve this, machine.Signal class is provided.
|
|
|
|
Line editing
|
|
~~~~~~~~~~~~
|
|
|
|
You can edit the current line that you are entering using the left and right
|
|
arrow keys to move the cursor, as well as the delete and backspace keys. Also,
|
|
pressing Home or ctrl-A moves the cursor to the start of the line, and pressing
|
|
End or ctrl-E moves to the end of the line.
|
|
|
|
Input history
|
|
~~~~~~~~~~~~~
|
|
|
|
The REPL remembers a certain number of previous lines of text that you entered
|
|
(up to 8 on the ESP8266). To recall previous lines use the up and down arrow
|
|
keys.
|
|
|
|
Tab completion
|
|
~~~~~~~~~~~~~~
|
|
|
|
Pressing the Tab key will do an auto-completion of the current word that you are
|
|
entering. This can be very useful to find out functions and methods that a
|
|
module or object has. Try it out by typing "ma" and then pressing Tab. It
|
|
should complete to "machine" (assuming you imported machine in the above
|
|
example). Then type "." and press Tab again to see a list of all the functions
|
|
that the machine module has.
|
|
|
|
Line continuation and auto-indent
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Certain things that you type will need "continuing", that is, will need more
|
|
lines of text to make a proper Python statement. In this case the prompt will
|
|
change to ``...`` and the cursor will auto-indent the correct amount so you can
|
|
start typing the next line straight away. Try this by defining the following
|
|
function::
|
|
|
|
>>> def toggle(p):
|
|
... p.value(not p.value())
|
|
...
|
|
...
|
|
...
|
|
>>>
|
|
|
|
In the above, you needed to press the Enter key three times in a row to finish
|
|
the compound statement (that's the three lines with just dots on them). The
|
|
other way to finish a compound statement is to press backspace to get to the
|
|
start of the line, then press the Enter key. (If you did something wrong and
|
|
want to escape the continuation mode then press ctrl-C; all lines will be
|
|
ignored.)
|
|
|
|
The function you just defined allows you to toggle a pin. The pin object you
|
|
created earlier should still exist (recreate it if it doesn't) and you can
|
|
toggle the LED using::
|
|
|
|
>>> toggle(pin)
|
|
|
|
Let's now toggle the LED in a loop (if you don't have an LED then you can just
|
|
print some text instead of calling toggle, to see the effect)::
|
|
|
|
>>> import time
|
|
>>> while True:
|
|
... toggle(pin)
|
|
... time.sleep_ms(500)
|
|
...
|
|
...
|
|
...
|
|
>>>
|
|
|
|
This will toggle the LED at 1Hz (half a second on, half a second off). To stop
|
|
the toggling press ctrl-C, which will raise a KeyboardInterrupt exception and
|
|
break out of the loop.
|
|
|
|
The time module provides some useful functions for making delays and doing
|
|
timing. Use tab completion to find out what they are and play around with them!
|
|
|
|
Paste mode
|
|
~~~~~~~~~~
|
|
|
|
Pressing ctrl-E will enter a special paste mode. This allows you to copy and
|
|
paste a chunk of text into the REPL. If you press ctrl-E you will see the
|
|
paste-mode prompt::
|
|
|
|
paste mode; Ctrl-C to cancel, Ctrl-D to finish
|
|
===
|
|
|
|
You can then paste (or type) your text in. Note that none of the special keys
|
|
or commands work in paste mode (eg Tab or backspace), they are just accepted
|
|
as-is. Press ctrl-D to finish entering the text and execute it.
|
|
|
|
Other control commands
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are four other control commands:
|
|
|
|
* Ctrl-A on a blank line will enter raw REPL mode. This is like a permanent
|
|
paste mode, except that characters are not echoed back.
|
|
|
|
* Ctrl-B on a blank like goes to normal REPL mode.
|
|
|
|
* Ctrl-C cancels any input, or interrupts the currently running code.
|
|
|
|
* Ctrl-D on a blank line will do a soft reset.
|
|
|
|
Note that ctrl-A and ctrl-D do not work with WebREPL.
|