Getting started

If using a device with no MicroPython preinstalled (esp8266, esp32) first follow MicroPython getting started from official docs to see how to install it for the first time.

After that the device should be up and running for the next step.

Requirement

Needs REPL to be accessible:
> Wireless Devices:
> Serial Devices:
  • USB: Connected through USB data cable.

1

This is still experimental and for esp32 requires ble_advertising.py, ble_uart_peripheral.py, ble_uart_repl.py to be uploaded to the device. These scripts can be found in upyutils directory and they come from micropython examples. Finally to enable it add the following to main.py:

import ble_uart_repl
ble_uart_repl.start()

Create a configuration file

Save the address and password/baudrate of a connected device so this won’t be required for future interaction.

Note

If device address is unknown use $ upydev scan [OPTION] where OPTION can be -sr for SERIAL, -nt for WiFi or -bl for Bluetooth Low Energy.

e.g.

$ upydev scan -sr
Serial Scan:
SerialDevice/s found: 2
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                  PORT                   ┃               DESCRIPTION                ┃          MANUFACTURER          ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃     /dev/cu.usbmodem387E386731342       ┃   Pyboard Virtual Comm Port in FS Mode   ┃          MicroPython           ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃         /dev/cu.SLAB_USBtoUART          ┃  CP2104 USB to UART Bridge Controller    ┃          Silicon Labs          ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Upydev will use local working directory configuration unless it does not find any or manually indicated with -g option which is the global configuration flag.

  • To save configuration in working directory:

$ upydev config -t [DEVICE ADDRESS] -p [PASSWORD/BAUDRATE]

where ADDRESS must be a valid :

  • IP / HOSTNAME 2 ,

  • SERIAL ADDRESS 3,

  • MAC ADDRESS/ UUID 4

e.g.

# WiFi
$ upydev config -t 192.168.1.53 -p mypass

# SERIAL
$ upydev config -t /dev/tty.usbmodem387E386731342

# BLE
$ upydev config -t 9998175F-9A91-4CA2-B5EA-482AFC3453B9
2

IP can be a valid dhcp_hostname e.g. esp_dev.local (must be set with e.g. nic.config(hostname="esp_dev"))

3

-p is set to 115200 by default, so it is not necessary unless using a different baudrate

4

It will depend on OS system (e.g. Linux uses MAC format ‘XX:XX:XX:XX:XX:XX’, and macOS uses UUID format ‘XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX’)

Default device name is upydevice, to set a custom name use -@ flag as

$ upydev config -t 192.168.1.53 -p mypass -@ mycustomdevice

To check configuration upydev or upydev check

$ upydev
Device: mycustomdevice
Address: 192.168.1.53, Device Type: WebSocketDevice

Or to get more information if the device is online

$ upydev -i
Device: mycustomdevice
WebSocketDevice @ ws://192.168.1.53:8266, Type: esp32, Class: WebSocketDevice
Firmware: MicroPython v1.19.1-285-gc4e3ed964-dirty on 2022-08-12; ESP32 module with ESP32
(MAC: 30:ae:a4:23:35:64, RSSI: -45 dBm)
  • To save configuration globally use -g flag: $ upydev config -t [DEVICE ADDRESS] -p [PASSWORD/BAUDRATE] -g

    e.g.

    $ upydev config -t 192.168.1.53 -p mypass -g
    
  • To save configuration in a global group use -gg flag: $ upydev config -t [DEVICE ADDRESS] -p [PASSWORD/BAUDRATE] -gg -@ mydevice

    e.g.

    $ upydev config -t 192.168.1.53 -p mypass -gg -@ mydevice
    
  • [Optional]

Use register command to register a device as a shell function. This defines the function in ~/.bashrc or ~/.profile

$ upydev register -@ mydevice
function mydevice() { upydev "$@" -@ mydevice; }
function _argcomp_upydev() { _python_argcomplete upydev; }
complete -o bashdefault -o default -o nospace -F _argcomp_upydev mydevice
$ source ~/.profile

Now mydevice will accept any args and pass them to upydev, as well as autocompletion of args, e.g.

$ mydevice
Device: mydevice
Address: 192.168.1.53, Device Type: WebSocketDevice

Or if the device is connected. 5

$ mydevice -i
Device: mydevice
WebSocketDevice @ ws://192.168.1.53:8266, Type: esp32, Class: WebSocketDevice
Firmware: MicroPython v1.19.1-285-gc4e3ed964-dirty on 2022-08-12; ESP32 module with ESP32
(MAC: 30:ae:a4:23:35:64, Host Name: mydevice, RSSI: -45 dBm)
5

Check this using ping or probe, e.g.

$ mydevice ping
PING mydevice.local (192.168.1.53): 56 data bytes
64 bytes from 192.168.1.53: icmp_seq=0 ttl=255 time=5.303 ms
64 bytes from 192.168.1.53: icmp_seq=1 ttl=255 time=218.701 ms
64 bytes from 192.168.1.53: icmp_seq=2 ttl=255 time=39.224 ms
64 bytes from 192.168.1.53: icmp_seq=3 ttl=255 time=62.249 ms
^C
--- mydevice.local ping statistics ---
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 5.303/81.369/218.701/81.835 ms

$ mydevice probe
Reaching mydevice...
mydevice    -> WebSocketDevice @ mydevice.local -> OK [✔]

Finally to enter device shell-repl mode do:

$ upydev shl@mydevice
shell-repl @ mydevice
WebREPL connected
WARNING: ENCRYPTION DISABLED IN THIS MODE

MicroPython v1.19.1-285-gc4e3ed964-dirty on 2022-08-12; ESP32 module with ESP32
Type help() for more information.

- CTRL-k to see keybindings or -h to see help
- CTRL-s to toggle shell/repl mode
- CTRL-x or "exit" to exit
esp32@mydevice:~ $

or if the device is registered

$ mydevice shl
shell-repl @ mydevice
WebSecREPL with TLSv1.2 connected
TLSv1.2 @ ECDHE-ECDSA-AES128-CCM8 - 128 bits Encryption

MicroPython v1.19.1-285-gc4e3ed964-dirty on 2022-08-12; ESP32 module with ESP32
Type help() for more information.

- CTRL-k to see keybindings or -h to see help
- CTRL-s to toggle shell/repl mode
- CTRL-x or "exit" to exit
esp32@mydevice:~ $

Note

To enable WebSocket over TLS or wss check WebSocket (ws) / WebSocket Secure (wss) TLS

Once the device is configured see Usage documentation to check which modes and tools are available.

Or if you are working with more than one device continue with the following section to create a group configuration.

Create a GROUP file

Make a global group of uPy devices named “UPY_G” to enable redirection to a specific device so next time any command can be redirected to any device within the group

Use mkg as $ upydev mkg UPY_G -g -devs [NAME] [ADDRESS] [PASSWORD/BAUDRATE/DUMMY] [NAME2]... 6

to create and add more than one device at once. e.g.

$ upydev mkg UPY_G -g -devs esp_room1 192.168.1.42 mypass esp_room2 192.168.1.54 mypass2
6

Every device must have a name, address and password/baudrate/dummy data (in case of ble) so the args can be parsed properly.

or use config and -gg flag as mentioned above to add one device at a time.

$ upydev config -t 192.168.1.42 -p mypass -gg -@ esp_room1
WebSocketDevice esp_room1 settings saved in global group!

$ upydev config -t 192.168.1.54 -p mypass -gg -@ esp_room2
WebSocketDevice esp_room2 settings saved in global group!

To see the devices saved in this global group, use gg.

$ upydev gg
GROUP NAME: UPY_G
# DEVICES: 2
┣━ esp_room1    -> WebSocketDevice @ 192.168.1.42
┗━ esp_room2    -> WebSocketDevice @ 192.168.1.54

Now any command can be redirected to one of these devices with the -@ 7 option :

$ upydev info -@ esp_room1
WebSocketDevice @ ws://192.168.1.42:8266, Type: esp32, Class: WebSocketDevice
Firmware: MicroPython v1.12-63-g1c849d63a on 2020-01-14; ESP32 module with ESP32
(MAC: 80:7d:3a:80:9b:30, RSSI: -51 dBm)
7

Option -@ has autocompletion on tab so hit tab and see what devices are available

Note

To add or remove devices from this group use mgg, and -gg flag which is the same as -G UPY_G.

  • Add $ upydev mgg -gg -add [NAME] [PASSWORD] [PASSWORD/BAUDRATE/DUMMY] [NAME2]...

  • Remove $ upydev mgg -gg -rm [NAME] [NAME2]...

  • [Optional]

Finally use register command to register a group as a shell function. This defines the function in ~/.bashrc or ~/.profile

$ upydev register devsg -@ pybV1.1 espdev oble
#UPYDEV GROUP devsg
function devsg() { upydev "$@" -@ pybV1.1 espdev oble; }
function _argcomp_upydev() { _python_argcomplete upydev; }
complete -o bashdefault -o default -o nospace -F _argcomp_upydev devsg
$ source ~/.profile

Now devsg will accept any args and pass them to upydev, as well as autocompletion of args, e.g.

$ devsg
Device: pybV1.1
Address: /dev/tty.usbmodem3370377430372, Device Type: SerialDevice

Device: espdev
Address: espdev.local, Device Type: WebSocketDevice

Device: oble
Address: 00FEFE2D-5983-4D6C-9679-01F732CBA9D9, Device Type: BleDevice
$ devsg -i
Device: pybV1.1
SerialDevice @ /dev/tty.usbmodem3370377430372, Type: pyboard, Class: SerialDevice
Firmware: MicroPython v1.18-128-g2ea21abae-dirty on 2022-02-19; PYBv1.1 with STM32F405RG
Pyboard Virtual Comm Port in FS Mode, Manufacturer: MicroPython
(MAC: 3c:00:3d:00:02:47:37:30:38:37:33:33)

Device: espdev
WebSocketDevice @ ws://192.168.1.53:8266, Type: esp32, Class: WebSocketDevice
Firmware: MicroPython v1.18-42-g30b6ce86b-dirty on 2022-01-27; ESP32 module with ESP32
(MAC: 30:ae:a4:23:35:64, Host Name: espdev, RSSI: -55 dBm)

Device: oble
BleDevice @ 00FEFE2D-5983-4D6C-9679-01F732CBA9D9, Type: esp32 , Class: BleDevice
Firmware: MicroPython v1.18-128-g2ea21abae-dirty on 2022-02-19; 4MB/OTA BLE module with ESP32
(MAC: ec:94:cb:54:8e:14, Local Name: oble, RSSI: -50 dBm)