This guide will walk you through the process of manually installing OpenShrooly firmware on your Shrooly device using command line tools.

💡 Quick Install: For the easiest installation experience, try our Web Installer - no command line required! Works with Chrome, Edge, and Opera browsers.

Prerequisites

Before starting, ensure you have:

  • A Shrooly device
  • A USB cable for connection
  • ESPTool installed on your computer
  • Basic command-line knowledge

Setting up ESPTool

Windows Setup

  1. Connect your Shrooly device via USB
  2. The device should be recognized as “USB JTAG/serial debug unit”
  3. If not recognized, you may need to install the Silicon Labs CP2102N-A02-GQFN28 UART driver
  4. Download the binary version of ESPTool from the GitHub releases page

Linux Setup

  1. Create a Python virtual environment:
python -m venv esptool-env
source esptool-env/bin/activate
  1. Install ESPTool via pip:
pip install esptool
  1. You can now use the esptool command to interact with your device

Backing Up Original Firmware

Important: Always backup your original firmware before proceeding! This allows you to restore your device if needed.

  1. Check the flash size of your device:
esptool --port /dev/ttyACM0 flash_id

(On Windows, replace /dev/ttyACM0 with your COM port, e.g., COM3)

  1. Backup the full 16MB flash:
esptool --port /dev/ttyACM0 read_flash 0x000000 0x1000000 shrooly_backup.bin

This will create a file called shrooly_backup.bin containing your original firmware. Keep this file safe!

Installing OpenShrooly Firmware

Download the Firmware

  1. Download the latest firmware from one of these sources:

  2. Look for the file named openshrooly-esp32s3.factory.bin

Flash the Firmware

  1. Flash OpenShrooly to your device:
esptool --chip esp32s3 --port /dev/ttyACM0 --baud 460800 write_flash -z 0x0 openshrooly-esp32s3.factory.bin
  1. The flashing process should take about 1-2 minutes

First Boot Configuration

After flashing, your device will start in setup mode:

  1. The device will create a Wi-Fi access point named OpenShrooly-Setup
  2. Connect to this access point from your computer or phone
  3. Open a web browser - you should be automatically redirected to the setup page
  4. Note the MAC address displayed at the top of the page (e.g., 040d98)
  5. Enter your Wi-Fi network credentials and save
  6. The device will reboot and connect to your network
  7. Access your device at http://openshrooly-[MAC].local/ (e.g., http://openshrooly-040d98.local/)

If the .local address doesn’t work, check your router’s device list for the assigned IP address.

Restoring Original Firmware

If you need to restore the original Shrooly firmware:

  1. Ensure you have your backup file (shrooly_backup.bin)
  2. Flash the backup:
esptool --chip esp32s3 --port /dev/ttyACM0 --baud 460800 write_flash -z 0x0 shrooly_backup.bin
  1. The device will be restored to its original state

Troubleshooting

Device Not Recognized

  • Try different USB cables (some cables are charge-only)
  • Install appropriate drivers for your operating system
  • Check device manager (Windows) or dmesg (Linux) for connection issues

Flashing Fails

  • Ensure the correct port is specified
  • Try reducing the baud rate to 115200
  • Make sure no other programs are using the serial port

Wi-Fi Setup Issues

  • Ensure you’re connected to the OpenShrooly-Setup access point
  • Try using a different browser or clear your browser cache
  • If not redirected automatically, try http://192.168.4.1
  • After setup, try both http://openshrooly-[MAC].local/ and the IP address from your router’s device list

Next Steps

Once installation is complete: