2. Tools & Features

2.1 Intro

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.

Contents

2.2 Main Features of Pycom Modules

All members in the current family of Pycom modules are powered by the ESP32, offering:

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.

Datasheets

If you want to find out how things are connected, visit the datasheets section. Here you’ll find the datasheets for all of our products.

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 main.py.

To use the REPL, you must connect to the LoPy either via telnet, 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:

  • user: micro
  • password: python

See 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.

Note

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-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.
  • Ctrl-E enters ‘paste mode’ that allows you to copy and paste chuncks of text. Finish using Ctrl-d

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

or:

$ screen /dev/tty.usbmodem* 115200

Note

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 quit command:

  • create ~/.screenrc
  • add bind q quit

This will allow you to quit screen by hitting CTRL-A Q.

On Linux, you can also try picocom or minicom instead of screen. You may have to use /dev/ttyUSB01 or a higher number for ttyUSB. And, you may need to give yourself the correct permissions to access this devices (eg group uucp or dialout, or use sudo).

Windows (PuTTY)

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 WLAN.AP mode), 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 /flash, 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:

  • url: ftp://192.168.4.1
  • user: micro
  • password: python

See 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:

ftp> passive

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.

FileZilla settings

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: Only use 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.

Filezilla 1 Filezilla 2

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 P12 (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 boot.py and 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.

Reset

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 boot.py and main.py 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.

Note

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.

Supported Editors/IDEs:

Drivers (FTDI):

Note

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.

Atom Text Editor

Please follow these steps to install the Pymakr Plugin:

  1. Ensure that you have Atom installed and open.
  2. Navigate to the Install page, via Atom > Preferences > Install
  3. Search for Pymakr and select the official Pycom Pymakr Plugin.
  4. You should now see and Install button. Click this to download and install the Pymakr Plugin.
  5. 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:

  1. Ensure that your Pycom board is turned on and connected.
  2. Connect your computer to the WiFi network named after your board (e.g. lopy-wlan-xxxx, wipy-wlan-xxxx). The password is www.pycom.io
  3. Open Atom and ensure that the Pymakr Plugins are installed.
  4. In the menu, go to Atom > Preferences > Packages > Pymakr.
  5. By default, the Address should be listed as 192.168.4.1. If not, change this to 192.168.4.1.
  6. The default username and password are micro and python, respectively.
  7. You settings will be saved automatically.
Pymakr Plugin settings

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 >>> prompt, indicating that you are connected:

Pymakr Plugin REPL

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.

Mac OS

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 /dev/cu.usbserial-XXXXXXXX.

Linux

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 /dev/cu.usbserial-XXXXXXXX.

Windows

Open your 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.

Note

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:

Pymakr Plugin USB Serial Device

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.

Pymakr Plugin Overview
  • 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.

Note

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.

Warning

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.

Warning

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.

Coding Basics

For fun, lets try to build a traffic light. Add the following code to the main.py file:

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:

Traffic light

You now have a traffic light in your hands. To stop a running program, use ctrl-c or the Cancel button within the console. You can also reboot the board by pressing the physical reset button.

Warning

If your board is running code at boot time, you might need to boot it in safe mode.

Console (REPL)

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.

Pymakr Plugin REPL while-loop

Use 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

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)