Skip to content

Getting started to Sushi IoT Framework

1. Get the firmware

In the Sushi-IoT-Framework download page there is a table with all the releases for the supported boards. To get the latest features and fixes, it's recommended to use the latest stable version available.

2. Flash the firmware

Flashing the firmware can vary depending on the specific board you are using (in that case please check the producer documentation for more details).

We document here 2 options to flash the firmware that can fit on ESP32DevKitC-V4 and most ESP32 boards.

2.1. Flash by ONLINE tool

Espressif provides an online tool that, using modern browser functions, can connect to your board via USB/COM port.
The online tool is probably the easiest way to flash the firmware, but it's a "young" feature and depending on your system/browser/chip version may not work.
If you have troubles, do not waste too much time on it; switch to the OFFLINE procedure, which is more reliable across all conditions.

Steps

  1. Plug your ESP32 board via USB into your PC.
  2. Open the ESP Flash Tool in the browser.
  3. Select 115200 as baud rate. Higher baud rates can cause issues; if you experience problems like "Error: No serial data received", switch to 115200.
  4. Click "Connect" in the "Program" section and select the ESP32 board COM port. In the console, you should see the chip model and other info if the device is properly connected.
  5. Start the board in boot mode (only if the program interface does not appear automatically).

    On the board: press the boot button, hold it, then press and release the reset button. If the step is successful, the web interface should display "Connected to device:" with all the buttons to program the board.

  6. Press "Erase Flash" (recommended, especially for the first firmware load).
  7. Select the firmware file (use the button on the right, not "Add"), set the Flash address to "0", and press "Program".

Troubleshooting

  • If "Error: No serial data received" appears, use the lowest baud rate (115200).
  • If you see "flash corruption" in REPL after firmware download, reinstall the firmware using "Erase Flash".
  • If the chip is detected but Erase/Program fails, it is probably not in BOOT mode. Boot mode is automatic if the chip is blank/new; otherwise, follow step 5 carefully to reset the device into boot mode.

Tip: For every retry, refresh the tool page to start clean, and possibly unplug/replug the device.

2.2. Flash by OFFLINE tool

Download the official Espressif tool for your system: ESPTOOL.
For example, here you can get the .exe version of the tool.
This is an easier alternative compared to the Python ".py" version of the tool, which you can find here.
If you use "esptool.py" replace "esptool" with "esptool.py" in all the following commands.

Erase the chip

This is required especially when you are flashing the firmware for the first time.

esptool erase_flash

Flash the firmware file

esptool write_flash 0x0 FIRMWARE.bin

Where "FIRMWARE" is the firmware .bin file that you downloaded. See Sushi-IoT-Framework firmware download.

Troubleshooting

  • esptool fails to detect the correct COM port: specify it with the "--port" option in front of the command.
esptool --port PORTNAME ...

Where PORTNAME:
- On Linux, usually something like /dev/ttyUSB.
- On Mac, usually something like /dev/cu.usbmodem01.
- On Windows, usually something like COM5.

If these steps don't work, consult the esptool documentation from Espressif:

2.3. Test the firmware

After successfully loading the firmware, you can quickly check that everything is working by connecting to the MicroPython REPL.

You have two options:

  • Serial tool: connect with any serial terminal to the USB port.
    See the coding section of the manual for details.
  • Web tool: use the online COM monitor provided by Espressif on the same page as the ESP Flash Tool.

Steps for the web tool:

  1. If you previously used it to flash the firmware, refresh the page.
  2. In the Console section, set the baud rate to 115200, click Start, and select the COM port of your board.
  3. On the device, press the RESET button.

If everything works, you should see the device boot and the MicroPython REPL:

...
MicroPython 495ce91-dirty on ... Sushi firmware framework on ... with ESP32
Type "help()" for more information.
>>>

3. Setup and Wi-Fi connection

This step is optional if you plan to start coding the device through the USB REPL interface.

When the firmware is freshly flashed, the board starts Wi-Fi in access point mode.
By scanning available networks, you should see an SSID like "Sushi-..." (the suffix is the device MAC address).

You can connect your PC or smartphone to this Wi-Fi network and open the web interface at:
http://192.168.1.100

⚠️ Use http://, not https:// — HTTPS is supported but not enabled by default.

Default network settings:

  • SSID: "Sushi-..."
  • Password: (empty)
  • IP address: "192.168.1.100"
  • User: "root"
  • Password: "1976"

From the web interface, you can adjust the base system settings and OPTIONALLY configure the device to connect to your Wi-Fi network.
For more details about the Sushi-IoT-Framework web interface, see the system setup section.

4. Start coding

Once the device is configured, you can start coding with your preferred MicroPython interface.
In this guide, the examples use Thonny, but several alternatives are available.

For more details, see the coding section.