Serial port troubleshooting

Before initial device provisioning and claiming can take place, you must connect the ESP32 device 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 device, 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 available 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+]

If you have initially provisioned your ESP32, run the following Toit CLI command to read the hardware information of your device

toit serial info

Troubleshoot flashing the ESP32

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

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

  • 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 flashed with the Toit firmware, but is not yet linked to your Toit account. Follow the instructions on the claim page 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>

Troubleshoot serial port connections

Update drivers!

If you are using macOS or Windows, you might need to update the drivers from here and here. Install both drivers, reboot your computer and try to run the Toit CLI serial commands again.

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

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

  • avoid USB dongles if possible.

  • 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 a cellular connection.