2. Tools & Features¶
Do you have your basic setup working? Then it’s time to look at all the ways you can use and interact with your board. We’ll look at some more features of the Pymakr Plugin and see how we can use telnet, FTP and how to reset the board.
2.2 Main Features of Pycom Modules¶
All members in the current family of Pycom modules are powered by the ESP32, offering:
- 512 Kb available for the user as internal storage, (external SD card support available)
- Up to 96 Kb of RAM available for python code.
- Hardware floating point unit
- Up to 24 GPIO
LoRa(only available in the LoPy)
hashlibMD5, SHA1, SHA256, SHA384 and SHA512 hash algorithms
Click the links in the list above to see more details on that feature. For all available modules and libraries, please visit the Firmware API Reference section.
2.3 REPL over Telnet and Serial¶
REPL stands for Read Evaluate Print Loop, and is the name given to the interactive MicroPython prompt that you can access on the LoPy. Using the REPL is by far the easiest way to test out your python code and run commands. You can use the REPL in addition to writing scripts in
To use the REPL, you must connect to the LoPy either via
or with a USB to serial converter wired to one of the two UARTs on the
LoPy. When using the REPL over telnet, authentication is needed. The default credentials are:
network.server for info on how to change the defaults.
To enable REPL duplication on UART0 (the one accessible via the expansion board) do:
>>> from machine import UART >>> import os >>> uart = UART(0, 115200) >>> os.dupterm(uart)
Place this piece of code inside your boot.py so that it’s done automatically after reset. The WiPy 2.0 and LoPy already have this code in the boot.py file by default.
The boards already ship with a boot.py file that contains the REPL duplication code. In case that you erase it or change, you can enable it back using the lines above.
The following control commands are available in REPL:
Ctrl-Aon a blank line will enter raw REPL mode. This is like a permanent paste mode, except that characters are not echoed back.
Ctrl-Bon a blank like goes to normal REPL mode.
Ctrl-Ccancels any input, or interrupts the currently running code.
Ctrl-Don a blank line will do a soft reset.
Ctrl-Eenters ‘paste mode’ that allows you to copy and paste chuncks of text. Finish using
Instructions on how to connect can be found in the two chapters below. A small tutorial on how to use the REPL is available in chapter 3. Tutorials and Examples
Mac OS X and Linux¶
Open a terminal and run:
$ telnet 192.168.4.1
$ screen /dev/tty.usbmodem* 115200
When using telnet on mac, it takes a while connecting. This is because it’s waiting for a reverse dns lookup.
When you are finished and want to exit
screen, type CTRL-A CTRL-\. If your keyboard does not have a \-key (i.e. you need an obscure combination for \ like ALT-SHIFT-7) you can remap the
bind q quit
This will allow you to quit
screen by hitting CTRL-A Q.
On Linux, you can also try
minicom instead of screen. You may have to
/dev/ttyUSB01 or a higher number for
ttyUSB. And, you may need to give
yourself the correct permissions to access this devices (eg group
or use sudo).
First you need to install the FTDI drivers for the expansion board’s USB to serial converter. Then you need a terminal software. The best option is to download the free program PuTTY: putty.exe.
In order to get to the telnet REPL:
Using putty, select
Telnet as connection type, leave the default port (23)
and enter the IP address of your device (192.168.4.1 when in
then click open.
In order to get to the REPL UART:
Using your serial program you must connect to the COM port that you found in the previous step. With PuTTY, click on “Session” in the left-hand panel, then click the “Serial” radio button on the right, then enter you COM port (eg COM4) in the “Serial Line” box. Finally, click the “Open” button.
2.4 Local file system and FTP access¶
There is a small internal file system (a drive) on the LoPy, called
which is stored within the external serial flash memory. If a micro SD card
is hooked-up and mounted, it will be available as well. When the device starts
up, it always boots from the
boot.py located in the
/flash file system.
The file system is accessible via the native FTP server running in the LoPy. Open your FTP client of choice and connect to:
network.server for info on how to change the defaults.
The recommended clients are: Linux stock FTP (also on OS X), Filezilla and FireFTP.
For example, on a linux terminal:
$ ftp 192.168.4.1
The FTP server on the LoPy doesn’t support active mode, only passive, therefore, if using the native unix ftp client, just after logging in do:
Keep in mind that the FTP server on the LopY only supports one data connection at a time. If you are using other FTP Clients check thier documentation to set the maximun allowed connections accordingly.
Do not use the quick connect button, instead, open the site manager and create a new
configuration. In the
General tab make sure that encryption is set to:
plain FTP (insecure). In the Transfer Settings tab limit the max number of connections
to one, otherwise FileZilla will try to open a second command connection when retrieving
and saving files, and for simplicity and to reduce code size, only one command and one
data connections are possible. Other FTP clients might behave in a similar way.
2.5 Boot modes and safe boot¶
If you power up normally, or press the reset button, the LoPy will boot
into standard mode; the
boot.py file will be executed first, then
main.py will run.
You can override this boot sequence by pulling
G28) up (connect
it to the 3V3 output pin) during reset. This procedure also allows going
back in time to old firmware versions. The LoPy can hold up to 3 different
firmware versions, which are: the factory firmware plus 2 OTA images.
After reset, if
P12 is held high, the heartbeat LED will start flashing
slowly in orange color, if after 3 seconds the pin is still being held high,
the LED will start blinking a bit faster and the LoPy will select the previous
OTA image to boot. If the previous user update is the desired firmware image,
P12 must be released before 3 more seconds elapse. If after 3 seconds later,
the pin is still high the factory firmware will be selected, the LED will flash
quickly for 1.5 seconds and the LoPy will proceed to boot.
The firmware selection mechanism is as follows:
Safe Boot Pin
P12 released during:
|1st 3 secs window||2nd 3 secs window||Final 1.5 secs window|
Safe boot, latest
firmware is selected
Safe boot, previous
user update selected
Safe boot, the factory
firmware is selected
On all of the above 3 scenarios, safe boot mode is entered, meaning that
the execution of both
main.py is skipped. This is
useful to recover from crash situations caused by the user scripts. The selection
made during safe boot is not persistent, therefore after the next normal reset
the latest firmware will run again.
If you have problems with the filesystem you can format the internal flash drive.
There are soft resets and hard resets. A soft reset simply clears the state of the MicroPython virtual machine, but leaves hardware peripherals unaffected. To do a soft reset, simply press Ctrl+D on the REPL, or within a script do:
>>> import sys >>> sys.exit()
A hard reset is the same as performing a power cycle to the board. In order to hard reset the LoPy, press the switch on the board or:
>>> import machine >>> machine.reset()
Factory reset the filesystem¶
If you device’s filesystem gets corrupted (very unlikely, but possible), you can format it very easily by doing:
>>> import os >>> os.mkfs('/flash')
Resetting the flash filesystem deletes all files inside the internal LoPy
storage (not the SD card), and restores the files
back to their original states after the next reset.
2.6 Interrupt handling¶
In Pycom’s ESP32 MicroPython port there are no restrictions on what you can do within an interrupt handler. For example, other ports don’t allow you to allocate memory inside the handler or use sockets.
These limitations were raised by handling the interrupt events differently. When an interrupt happens, a message is posted into a queue, notifying a separate thread that the appropriate callback handler should be called. Such handler would receive an argument. By default it is the object associated with the event.
The programmer can do whatever is needed inside the callback, such as creating new variables, or even sending network packets. Just keep in mind that interrupts are processed sequentially, so try to keep the handlers as quick as possible in order to attend them all in a short time.
Currently there are 2 classes supporting interrupts, there the
Alarm class and the
Pin. Both classes provide the
.callback() method that enables the interrupt and registers the given handler. More details about the usage along with examples can be found in their respective sections.
Currently the interrupt system can queue up to 16 interrupts.
2.7 Pymakr Plugin¶
Here are some basic tips on how to use the Pymakr Plugin to upload code to your devices. This guide is generic for all of our Plugins (Atom, Sublime, etc.) but the images in this chapter will refer to the Atom text editor.
Currently a number of these plugins are under development and may not be available at this time. Pycom is launching the plugin for Atom initally and following up with other platforms as inital releases are completed.
Installing Pymakr Plugin (Atom)¶
For beginners, users getting started with MicroPython & Pycom as well as Atom text editor users, we recommend the Pymakr Plugin for Atom. This section will help you get started using the Atom text editor & Pymakr Plugin.
Please follow these steps to install the Pymakr Plugin:
- Ensure that you have Atom installed and open.
- Navigate to the
Atom > Preferences > Install
- Search for
Pymakrand select the official Pycom Pymakr Plugin.
- You should now see and
Installbutton. Click this to download and install the Pymakr Plugin.
- That’s it! You’ve installed the Pymakr Plugin for Atom.
Initial Configuration (Atom)¶
After installing the Pymakr Plugin, you need to take a few seconds to configure it for the first time. Please follow these steps:
- Ensure that your Pycom board is turned on and connected.
- Connect your computer to the WiFi network named after your board (e.g.
wipy-wlan-xxxx). The password is
- Open Atom and ensure that the Pymakr Plugins are installed.
- In the menu, go to
Atom > Preferences > Packages > Pymakr.
- By default, the Address should be listed as
192.168.4.1. If not, change this to
- The default username and password are
- You settings will be saved automatically.
That’s it for the first time configuration. In the lower portion of the screen,
you should see the console, with the connection process taking place. At the
end of it, you’ll get a ‘Connecting on 192.168.4.1...’ message and a
indicating that you are connected:
Connecting via USB Serial¶
In order to use the Pymakr Plugin with a Pycom device, connected via USB Serial, a couple of settings need to be adjusted. Below are the steps required to find, set and connect to your Pycom device over USB Serial.
To determine the serial address in which your Pycom device is connected, you will need to scan for connected devices on your computer.
Open up your
terminal and type the following command:
$ ls /dev/cu.*
This will print out all of the devices connected to your Mac via the USB serial port. If you are using an expansion board, it should appear in a similar format to this
Open up your
terminal and type the following command:
$ ls /dev/serial/
This will print out all of the devices connected to your Linux computer via the USB serial port. If you are using an expansion board, it should appear in a similar format to this
Start Menu and type
Device Manager. This will open a tool that lists all of the peripherals (connected devices) on your computer. Navigate to
Ports and unfold the dropdown. You should see a device listed as something similar to
USB Device (COM 4). Depending on what you have connected to your machine, the COM Port and name may vary.
You can also find this via
Control Panel > Device Manager > Ports.
Once you’ve worked out what your Pycom device is listed/named, you can add this to the Pymakr Plugin Settings:
Creating a Project¶
The Pymakr Plugins have a feature to sync and run your code on your device. This can be used for both uploading code to your device as well as testing out scripts by running them live on the device. The following steps will get you started.
- In Atom, go to File > Add Project Folder.
- Create a new folder within the prompt and give it a name. Then select open to initialise this as a project folder. You may also use an existing folder if you choose.
- Create two files: main.py and boot.py, if you don’t already have those.
You can also use FTP to download boot.py and main.py from the board to your project folder. This is commonly used when copying large numbers of files to a Pycom board.
The boot.py file should always start with following code, so we can run our python scripts over Serial or Telnet. Newer Pycom boards have this code already in the boot.py file.
from machine import UART import os uart = UART(0, 115200) os.dupterm(uart)
Many users, especially the WiPy users, will want a WiFi script in the boot.py file. A basic WiFi script but also more advanced WLAN examples, like fixed IP and multiple networks, can be found in the WiFi Examples chapter. The script below connects to your network and prints out your device’s local IP address.
from machine import UART import os uart = UART(0, 115200) os.dupterm(uart) wlan = WLAN(mode=WLAN.STA) wlan.scan() wlan.connect(ssid='Your Network SSID', auth=(WLAN.WPA2, 'Your Network Password')) while not wlan.isconnected(): pass print(wlan.ifconfig()) # prints out local IP to allow for easy connection via Pymakr Plugin or FTP Client
Besides the neccesary main.py and boot.py files, you can create any folders and python files or libraries that you want to include in your main file. The Pymakr Plugin will synchronize all files in the project to the board when using the Sync button.
When synchronizing your project to the board, ensure the REPL console is ready. If any programs are running or the board is still booting, synchronization may fail.
Running Your Code¶
If you want to test some code on the module, you can create a new file or open an existing one and then press the
Run button. This will run the code directly onto the Pycom board but it will not upload/sync to the board.
The changes you make to your file won’t be automatically saved to the board upon restarting or exiting the
Run feature, as the Pycom board will not store this code.
For fun, lets try to build a traffic light. Add the following code to the
import pycom import time pycom.heartbeat(False) for cycles in range(10): # stop after 10 cycles pycom.rgbled(0x007f00) # green time.sleep(5) pycom.rgbled(0x7f7f00) # yellow time.sleep(1.5) pycom.rgbled(0x7f0000) # red time.sleep(4)
- Make sure the connection to your board is open in the Pycom Console
- Press the sync button on the top console. Any progress will be shown in the console.
Here is the expected result:
You now have a traffic light in your hands. To stop a running program, use ctrl-c
Cancel button within the console. You can also reboot
the board by pressing the physical reset button.
If your board is running code at boot time, you might need to boot it in safe mode.
MicroPython has an interactive code tool known as the REPL (Read Evaluate Print Line). The REPL allows you to run code on your device, line by line. To begin coding, go to the Pymakr Plugin Console and start typing your code. Start by making the LED change colour.
import pycom # we need this module to control the LED pycom.heartbeat(False) # disable the blue blinking pycom.rgbled(0x00ff00) # make the LED light up in green color
You can change the color by adjusting the hex RGB value.
pycom.rgbled(0xff0000) # now make the LED light up in red color
The console can be used to run any python code, also functions or loops.
print() to output contents of variables to the console for you to read.
Returned values from functions will also be displayed if they are not caught in
a variable. This will not happen for code running from the main or boot files.
Here you need to use
print() to output to the console.
Note that after writing or pasting any indented code like a function or a while loop, you’ll have to press enter up to three times to tell MicroPython that you’re closing the code (this is standard MicroPython & Python behavior).
A few REPL features you may wish to use:
Input history: use arrow up and arrow down to scroll through the history
Tab completion: press tab to auto-complete variables or module names
Stop any running code: with ctrl-c
Copy/paste code or output: ctrl-c and ctrl-v (cmd-c and cmd-v for mac)