Web serial

Use the Serial option in the web-based Toit console for communicating with the ESP32 via a serial connection.

You can provision a serially connected ESP32 with the Toit firmware and settings directly in the browser. Monitor the serial output of the ESP32, and in the case the connection is lost, you can reinstall the ESP32 with the Toit firmware and settings.

Normally, you will communicate with the ESP32 over WiFi or cellular connection, but for the initial setup of the ESP32, the serial connection is a requirement.

For debugging purposes, the serial connection is convenient. Use the serial connection only if there are no other options and the ESP32 is physically available.


Note that the serial options are only available in Google Chrome and Windows Edge browsers.

If you have difficulties connecting your hardware via web serial, please read the troubleshoot guide or use the Toit CLI instead for the serial communication.

Connect via the browser

Navigate to the Serial page in the Toit console. Plug the ESP32 with a USB cable to a serial port on your computer, and press the button go get started.

In the serial port dialog, choose the port to connect to. On Linux and macOS, it can sometimes be difficult to figure out which serial port to choose from the list, but doing a check of which ports are available in the list when the ESP32 is physically disconnected followed by a check with it being connected, will make it more clear which serial port to choose.

Screenshot Serial page in the Toit console
Screenshot Serial page in the Toit console

If the serial connection succeeds and the web serial API detects the ESP32 correctly, you can now communicate with it over the serial connection in the browser.

Web serial provision

If the ESP32 has not been provisioned before with the Toit firmware, settings and hardware ID, the Provision button is enabled on the page, and it's possible to start the initial provisioning of the ESP32 from here.

In the provision dialog, set the WiFi credentials to be used for initial WiFi settings. The latest released version of the Toit firmware will be installed on the ESP32 by default, unless you choose a different version from the drop down menu.

If the ESP32 is able to get online during the provisioning process, in other words that the ESP32 is in the range of the WiFi with the credentials given as parameters to the provisioning, then the ESP32 will automatically be claimed which means it will be added to your project in the Toit console, and will be visible in the list of devices when the provision process has finished.

If the automatic claiming fails during the provisioning steps, you must manually claim the ESP32, before you can start using the device in the Toit console. First, note the hardware ID of the provisioned ESP32. Then, navigate to the Devices page in the Toit console and press the Claim button. Paste the hardware ID and provide an optional device name in the dialog, and press Claim. The ESP32 must be online before this step can take place.

When provisioning and claiming have completed with success, find the new device in the list of devices in the Toit console.

Web serial monitor

View the serial output of the hardware directly in the browser by pressing the Monitor button.

Web serial reinstall

The Reinstall button will reinstall the ESP32 with the latest released Toit firmware and settings. This option is never needed for operating a Toit device, but can be a great tool for debugging or recovering a lost device.

If the device is operating as expected, this means that the device is online and connected to the Toit console, navigate to the device page in the Toit console where you can continue configuring the device and run Toit code on it, monitor logs and much more.

Trouble with web serial?

If you have trouble with the serial connection to the ESP32 via the web browser, please visit the troubleshoot section.

Try to unplug the ESP32 physically from your computer and plug the USB cable into the serial port again, and try to connect the ESP32 using the Serial page in Toit console.