Serial port troubleshooting

Before initial hardware provisioning can take place, you must connect the ESP32 to a computer with a serial connection - like a USB cable.

If you have problems connecting your ESP32 to your computer, the Toit CLI offers some commands to help you back on track setting up the ESP32 with Toit.

CLI serial commands

Connect your ESP32 with a USB cable to your computer. List the serial ports currently in use on your computer by running the following command with the Toit CLI

toit serial ports

For example, if exactly one serial port, called /dev/ttyUSB0, is currently in use, the output of the command will look like this

$ toit serial ports

In order to set the default serial port to use in the Toit CLI serial commands that talk to your hardware, run the following command

toit serial port use <port>

Using the example above, run the command

toit serial port use /dev/ttyUSB0

to set the default port in all toit serial commands in the Toit CLI.

Pro-tip for provisioning

If you have not set a default serial port to use, and there are multiple serial connections active on your computer, the toit serial provision command will prompt you to choose one of the serial ports in order to continue the provision command using the correct port.

To get the default serial port in use, run the command

toit serial port get

You can monitor the serial output of the ESP32 with the command

toit serial monitor

The monitor command can be stopped by Ctrl+c

If you have initially provisioned your ESP32, run the following Toit CLI command to read the hardware information via serial output:

toit serial info

Troubleshoot provisioning the ESP32

Some hardware models need physical interaction with the device during initial provisioning - like pushing a button. If provisioning doesn't work, consult the documentation for your ESP32.

  • if you have timeout problems when provisioning, some hardware models require you to hold down BOOT button.

  • if your device wasn't able to connect via WiFi to the Toit cloud during the provisioning, it is not yet claimed. In this state the device is provisioned with the Toit firmware, but is not yet linked to your Toit account. Follow the instructions here to manually claim the device once it has managed to go online.

  • if the provision command fails during the first part of the provisioning process, the hardware ID (if any) is written to the local disk if possible and will be reused the next time the command is executed on the same computer.

  • if the provision command fails, consider trying with a lower baud rate (here half the default baud rate):

toit serial provision --baud 460800 -p wifi.ssid=<SSID> -p wifi.password=<password>

Install drivers

If you are using macOS or Windows, you might need to install or update the following two drivers on your computer:

  1. The Virtual COM Port driver (VCP) from here

For Windows, there is also a setup executable available for download.

  1. The USB to UART Bridge VCP driver from here.

For Windows, install the CP210x Universal Windows Driver. For macOS, install the CP210x VCP Mac OSX Driver.

Install both drivers, reboot your computer and you are ready to talk to your ESP32 via a serial port.

Troubleshoot: serial port connections

If you have trouble connecting your ESP32 device with your computer via a serial connection

  • try updating your drivers. If you are using Windows or macOS, make sure your drivers are up to date (install them from here and here).

  • try a different serial port on your computer and run the toit serial ports CLI command again to detect the correct serial port to use in the commands.

  • try to disconnect all other serial connections, if any, from your computer, to be sure to only have the ESP32 connected to your computer as the only one.

  • try to plug in the hardware with a USB cable directly into your computer instead of using a USB hub in between.

  • if you are on Linux, make sure you are in the dialout group as explained here.

  • be sure to use the correct type of USB cable to connect with when provisioning your ESP32, in other words a cable for both data and power, and not only for power usage.

  • always set the default serial port to be used in the serial CLI commands with toit serial port use <port> in order to avoid mistakes when talking with your device on a serial connection.

Device connections

When the ESP32 has been initially provisioned with WiFi credentials, the ESP32 device is connecting to the network via WiFi, and the serial connection is purely for debugging the device if WiFi connection is lost. In other words, you can plug the ESP32 into another power source and communicate with the ESP32 over WiFi from now on. Later on you can always add other connection types, like cellular connection.

Troubleshoot: Unreachable device

If your ESP32 is misconfigured in any way, for example if it does not have valid WiFi connection settings, reinstall the ESP32 with the Toit firmware and WiFi settings via a serial connection, by connecting it with a USB cable to your computer, and run the toit serial reinstall command with the appropriate WiFi connection settings provided.

toit serial reinstall -p wifi.ssid=<SSID> -p wifi.password=<password>

The reinstall command reinstalls Toit firmware and settings via the serial port without changing its hardware certificate or hardware ID.