Skip to content

Flashing Guide

Prerequisites

Before starting, make sure you have the following ready:

✅ VSCode installed

✅ PlatformIO extension installed

✅ Seeed Studio XIAO ESP32S3

✅ USB-C cable (data-capable, not charge-only)

Step 1 — Install Git

Download Git from git-scm.com and run the installer with default settings. Then verify in PowerShell:

git --version

Using Homebrew 

brew install git
Or download from git-scm.com

sudo apt update && sudo apt install git

Step 2 — Clone the Repository

Open a terminal and run:

cd ~/Documents # or wherever you keep projects

mkdir esp32-projects

git clone -b SH1106 https://github.com/mlodedrwale/weighmybru2.git

cd weighmybru2

Step 3 — Open in VSCode with PlatformIO

  1. Launch VSCode
  2. Go to File → Open Folder
  3. Navigate to and select the weighmybru2 folder you just cloned
  4. Click Select Folder
  5. Wait for PlatformIO to initialize — you'll see activity in the bottom status bar

Step 4 — Configure platformio.ini

Check that the platformio.ini in the root of the project matches this:

[env:esp32-s3-devkitc-1]
platform = espressif32@6.12.0
board = esp32-s3-devkitc-1
framework = arduino
monitor_speed = 115200
board_upload.flash_size = 4MB
board_build.filesystem = littlefs
board_build.partitions = huge_app.csv
upload_protocol = esptool
upload_speed = 460800
upload_flags = 
    --chip=esp32s3
    --before=default_reset
    --after=hard_reset
monitor_rts = 0
monitor_dtr = 0
build_flags = 
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DBOARD_HAS_PSRAM
    -Os
    -DCORE_DEBUG_LEVEL=0
lib_deps = 
    robtillaart/HX711@^0.6.0
    https://github.com/me-no-dev/ESPAsyncWebServer.git
    https://github.com/me-no-dev/AsyncTCP.git
    h2zero/NimBLE-Arduino@^1.4.0
    adafruit/Adafruit SSD1306@^2.5.7
    adafruit/Adafruit GFX Library@^1.11.9
    adafruit/Adafruit SH110X@^2.1.14

Step 5 — Apply Code Changes

Code Changes

The original WeighMyBru² firmware needs a few small changes to work with the hardware used in this build.

Required Changes

1. Display Controller — config.h (line 20)

Change from:

#define DISPLAY_CONTROLLER DISPLAY_CONTROLLER_SSD1306

To:

#define DISPLAY_CONTROLLER DISPLAY_CONTROLLER_SH1106

2. Display Height — config.h (line 24)

Change from:

#define DISPLAY_HEIGHT DISPLAY_HEIGHT_32

To:

#define DISPLAY_HEIGHT DISPLAY_HEIGHT_64

3. Display Rotation — SH1106Driver.h (line 23)

Change from:

oled.setRotation(2);

To:

oled.setRotation(0);

Display upside down?

If the display appears upside down after flashing, change the value back from 0 to 2.

Optional Changes

Always-On Battery Percentage — DisplayLayout.h

By default the battery percentage is not permanently shown on the display. To add it, find line 152 in DisplayLayout.h:

// display.print("WI");

Add the following block immediately after it:

// BATTERY PERCENTAGE
        display.setFont(&FreeMonoBold9pt7b);
        display.setTextSize(1);
        String batteryStr = String(st.batteryPercent) + "%";

        // Calculate text width for right alignment
        int16_t x1, y1;
        uint16_t w, h;
        display.getTextBounds(batteryStr, 0, 0, &x1, &y1, &w, &h);

        // Right-align: set cursor so the text ends at DISPLAY_WIDTH (128)
        int cursorX = DISPLAY_WIDTH - w - 2;
        display.setCursor(cursorX, 57);

        // Blink if battery < 10%
        if (st.batteryPercent < 10) {
            if ((millis() / 500) % 2 == 0) { // Show only every other 500ms
                display.print(batteryStr);
            }
        } else {
            display.print(batteryStr);
        }

This renders the battery percentage right-aligned at the bottom of the display, and blinks it when the battery drops below 10%.

Step 6 — Connect the Board

  1. Plug the XIAO ESP32S3 into your computer via USB-C
  2. If the board isn't detected, put it into flash mode manually:
    • Hold BOOT while plugging in the USB
    • Press and release RESET
    • Release BOOT

Step 7 — Find Your COM Port

In VSCode, check the blue bottom status bar — the COM port is listed there (e.g. COM3 on Windows, "/dev/ttyUSB0" on Linux).

If it's not visible:

  • PlatformIO sidebar → Devices
  • Windows: Device Manager → Ports (COM & LPT)
  • macOS/Linux: ls /dev/tty*

Step 8 — Build and Upload

  • Click ✓ in the blue bottom bar to build
  • Click → to upload
  1. Click the PlatformIO icon (alien head) in the left sidebar
  2. Expand PROJECT TASKS → esp32-s3-devkitc-1 → General
  3. Click Build to compile the code first
  4. Wait for successful build (check terminal output)
  5. Click Upload
  1. Open PlatformIO terminal: Terminal → New Terminal
  2. Build the project: 
    pio run
  3. Upload to ESP32: 
    pio run -t upload -t uploadfs

Step 8b — Upload Filesystem Image

Don't skip this step

Flashing the code alone is not enough. The web interface files are stored separately in the filesystem. If you skip this step, the scale will flash successfully but weighmybru.local will not be reachable.

After uploading the code, you need to also upload the filesystem image:

  1. Click the PlatformIO icon (alien head) in the left sidebar
  2. Expand **PROJECT TASKS → esp32-s3-devkitc-1 → Platform **
  3. Scroll down and click Upload Filesystem Image
  4. Wait for the upload to complete
pio run -t uploadfs

Once both uploads are done, press the RESET button on the board and weighmybru.local should become reachable after connecting to the scale's WiFi.

Step 9 — Monitor Serial Output

Click the plug icon in the blue status bar, or run:

pio device monitor

Troubleshooting

Upload failing
  • Wrong COM port — check Device Manager and verify platformio.ini
  • Board not in flash mode — retry the BOOT + RESET procedure
  • Driver issue — install ESP32 USB drivers from Silicon Labs
Build errors
  • Missing libraries — they'll be named in the error output; PlatformIO installs them automatically on the next build
  • Wrong board config — confirm your platformio.ini matches the config above exactly
Device not found

List connected devices 

pio device list
On Linux, you might need 
sudo chmod 666 /dev/ttyUSB0  # or your specific device

Post-Flash Setup

  1. Connect to the ESP32's WiFi access point (check serial monitor for details - AP IP :192.168.4.1)
  2. Access the web interface for calibration and configuration
  3. Configure your home WiFi through the web interface

Success Indicators

✅ Build completes without errors

✅ Upload shows "SUCCESS" message

✅ Serial monitor shows boot messages

✅ ESP32 creates WiFi access point (for initial setup)

Your WeighMyBru scale should now be running! Check the serial monitor for the web interface URL and initial setup instructions.

Next Steps — Calibration

With the firmware flashed and the scale booting correctly, the last step is to calibrate the scale.

The calibration process for this build is identical to the original WeighMyBru², so follow the official guide:

👉 WeighMyBru Calibration Guide

Hardcoding WiFi Credentials (Optional)

Only do this if the access point is not showing up

In most cases the scale will create a WiFi access point on first boot and you can configure credentials through the web interface. Only follow these steps if no access point appears and the serial monitor is showing WiFi-related errors on boot.

Step 1 — Open main.cpp

In VSCode, open src/main.cpp and find the #include block at the top of the file. Add these two lines directly after it:

static const char* hardcode_ssid = "YOUR_SSID";
static const char* hardcode_password = "YOUR_PASSWORD";

Replace YOUR_SSID and YOUR_PASSWORD with your actual WiFi network name and password.

Step 2 — Find the WiFi Sleep Lines

Scroll down in main.cpp until you find these two lines (around line 108):

WiFi.setSleep(true);
Serial.println("WiFi power management enabled for battery optimization");

Add the following line immediately after them:

saveWiFiCredentials(hardcode_ssid, hardcode_password);

Step 3 — Re-flash

Save the file, then repeat Step 7 (Build and Upload). The scale will now connect directly to your WiFi network on boot instead of creating an access point.