WebSocket (ws) / WebSocket Secure (wss) TLS

To enable WebREPL see WebREPL: a prompt over-wifi and WebREPL: web-browser interactive prompt

See WebSocketDevice development setup

Steps to enable WebSecureREPL mode

  1. Put wss_repl.py and wss_helper.py in the device: to do this use update_upyutils command as:

$ upydev update_upyutils

This will upload :

  • sync_tool.py

  • nanoglob.py

  • shasum.py (to enable dsync)

  • upylog.py

  • upynotify.py

  • uping.py

  • upysh.py (to enable dsync)

  • upysecrets.py (to enable random WebREPL passwords generation)

  • upysh2.py (to enable ‘tree’ and ‘du’ command)

  • wss_repl.py (to enable WebSecureREPL)

  • wss_helper.py (to enable WebSecureREPL)

  1. Generate ROOT CA ECDSA private key and self-signed ROOT CA certificate then upload the ROOT CA certificate to the device:

    To generate the key do:

    $ upydev kg ssl CA -tfkey

    -tfkey option is to send the ROOT CA certificate to the device.

    This will ask to set a passphrase, Do not forget it because it will be needed to generate HOST and device keys/certificates

  2. Generate HOST ECDSA private key and ROOT CA signed HOST certificate :

To generate the key do:

$ upydev kg ssl host

This will ask for the ROOT CA key passphrase to sign HOST certificate and then set another passphrase for HOST key, Do not forget it because it will be needed to log into WebSecureREPL

  1. Generate device ECDSA private key and ROOT CA signed device certificate then upload them to the device:

    To generate the key do:

    $ upydev kg ssl -tfkey

    -tfkey option is to send the key/cert to the device (so use this if connected directly to the AP of the device or a “secure” wifi e.g. local/home) If not connected to a “secure” wifi upload the key (it is stored in upydev.__path__) by USB/Serial connection.

    This will ask for the ROOT CA key passphrase to be able to sign device certificate.


It is possible to generate device key and CSR (Certificate Signing Request) in device itself using mpy-mbedtls. Upydev will check if mbedtls and x509 modules are available and use them to generate the key and sign the CSR. Then this CSR is sent to host computer and used to generate the device certificate signed by the ROOT CA key. Finally the signed certificate is transferred to the device.

At this point there should be in the host verify locations path upydev.\__path__:
  • ROOT CA key/cert pair

  • HOST key/cert pair

  • device cert.

And in the device:
  • ROOT CA cert

  • device key/cert pair.


This setup of ROOT CA–>HOST/device certificate chain enables TLS mutual authentication, and if the ROOT CA key/cert pair is exported to another host, it can generate its own HOST key/cert pair so it can perform a TLS mutual authentication too. This enables multihost support.

  1. Enable WebSecREPL/WebSecureREPL in device

Replace import webrepl for import wss_repl and webrepl.start() by wss_repl.start(ssl=True), in boot.py or main.py.

After these steps WebSecureREPL or WebREPL over wss is now available:

$ upydev shl

Or if the global group UPY_G is configured already, any device in the global group can be accessed with this mode using:

$ upydev shl@[DEVICE]


mbp@cgg:~$ upydev shl@esp_room1
Enter passphrase for key 'HOST_key@6361726c6f.pem':
WebSecREPL with TLSv1.2 connected
TLSv1.2 @ ECDHE-ECDSA-AES128-CCM8 - 128 bits Encryption

MicroPython v1.18-165-g795370ca2-dirty on 2022-03-01; 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@esp_room1:~ $


Once WebSecREPL is enabled, device configuration can be updated with host passphrase as -p [password]:[passphrase] so it’s not needed for logging anymore.

$upydev config -t esp_room1.local -p mypasswd:mypassphr -@ esp_room1 -gg

WebSecureREPL protocol