-
Notifications
You must be signed in to change notification settings - Fork 5
Home
This wiki details how to get the bluetooth coffee scale working by:
- installing MicroPython firmware on the ESP32 board
- installing the coffee scale firmware (i.e. python scripts) on the ESP32
- and finally calibrating the coffee scale so it provides accurate readings
❗ Steps below were performed on macOS. Please let me know how this can be done in a Windows environment
Getting started with MicroPython on the ESP32
Getting a MicroPython REPL prompt
This can be done in multiple ways, e.g.
1. Download the code repository directly from GitHub:
https://github.com/Nkawu/coffee-scale-firmware/archive/refs/heads/main.zip
# unarchive the zip file
unzip coffee-scale-firmware-main.zip -d coffee-scale-firmware2. Install the repository using git command line tools:
git clone https://github.com/Nkawu/coffee-scale-firmware.gitBoth these methods will create a folder named coffee-scale-firmware
There are several ways of achieving the steps below, I found using the python library esptool.py to be the most convenient to flash the ESP32 and using ampy to upload MicroPython scripts (AKA scale firmware). This assumes python3 is available on your computer.
1. Create the python virtual environment (optional):
# change into the scale repo firmware folder
cd coffee-scale-firmware
# create virtual environment for the firmware repo
python3 -m venv env
# activate the virtual environment
source env/bin/activate
# first time only - upgrade pip
pip install --upgrade pip❗ IMPORTANT: after using the python virtual environment, remember to deactivate it
deactivate2. Install esptool & ampy:
pip install --upgrade esptool adafruit-ampy1. Download the MicroPython firmware for your ESP32 board from https://micropython.org/download/esp32/
esp32-idf4-20200930-unstable-v1.13-77-g0fd0eb00a.bin was originally used for the scale. esp32-idf4-20200902-v1.13.bin is known to work, and later versions should also work.
# download MicroPython ESP32 firmware
export ESP32_MPBIN=esp32-idf4-20200902-v1.13.bin
wget https://micropython.org/resources/firmware/${ESP32_MPBIN}2. Connect the ESP32 to your computer
3. Get the serial port for the board and save it to the environment:
esptool.py flash_idOutput should look similar to this:
# D1 Mini
# Serial port /dev/cu.usbserial-01C010F8
# Chip is ESP32-D0WD (revision 1)
# Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
# Crystal is 40MHz
# MAC: 10:52:1c:76:10:88
# Manufacturer: 5e
# Device: 4016
# Detected flash size: 4MB4. Look for "Serial port" in the output, copy and save it to an environment variable ESP32_PORT:
export ESP32_PORT=/dev/cu.usbserial-01C010F85. Backup then erase the current ESP32 firmware, download and flash the MicroPython firmware:
❗ You will not be able to flash the MicroPython firmware if you do not erase the current flash!
# 1 - backup ESP32 factory 4MB firmware
esptool.py --port ${ESP32_PORT} read_flash 0x0 0x400000 esp32_fw_backup-4M.bin
# 2 - erase the ESP32 flash
esptool.py --chip esp32 --port ${ESP32_PORT} erase_flash
# 3 - program new ESP32 MicroPython firmware
esptool.py --chip esp32 --port ${ESP32_PORT} --baud 460800 write_flash --compress --flash_mode dio --flash_freq 40m 0x1000 esp32-idf4-20200902-v1.13.binIf you wish to have your scale connect to WiFi, e.g. to use WebREPL, add your WiFi credentials to boot.py script in the firmware folder. Update the following line:
# Enter WiFi parameters here
wlan.connect('*SSID*', '*PASSWORD*')If no WiFi connection is required (this is not required for the scale to function as it uses BLE), comment out the following line:
# do_connect()To upload the source files to the microcontroller, either use WebREPL or ampy.
1. Configure ampy:
Create a file name .ampy in the firmware folder on your computer, so you don't have to use parameters for every command:
# Please fill in your own port, baud rate, and delay
AMPY_PORT=/dev/cu.usbserial-01C010F8
AMPY_BAUD=115200
# Fix for macOS users' "Could not enter raw repl"; try 2.0 and lower from there:
AMPY_DELAY=0.52. Install scale "firmware" (i.e. the MicroPython scripts in the firmware folder of the downloaded repo):
# List contents of a folder on the ESP32
ampy ls
# copy the scale firmware scripts to the ESP32
ampy put firmware /
# confirm all the scripts (the "lib" folder) is on the ESP32
ampy ls
ampy resetAt this point the scale should be fully assembled (or the weight measurement part at least). Calibration involves running the calibration.py script in the firmware from a MicroPython REPL prompt (stands for Read Evaluate Print Loop) and completing several steps with a 5 second pause inbetween each step.
❗ YOU WILL NEED A CALIBRATED 100g WEIGHT TO ACCURATELY CALIBRATE THE SCALE!!!
The ESP32 will need to be connected to the computer via USB for this step. While the screen utility is used below, there are as usual several ways to get a REPL prompt.
https://docs.micropython.org/en/latest/esp8266/tutorial/repl.html
1. Connect to the ESP32 REPL prompt:
screen ${ESP32_PORT} 115200At this point you may need to press Ctrl-C to get to a prompt. The screen utility is a little tricky to use, here are some main commands:
# Ctrl-a, \ - Exit screen and terminate all programs in this screen
# Ctrl-a, k - "kill" screen
# Ctrl-a, d - "minimize" screen and screen -r to restore it
2. Run the calibration script:
exec(open('calibrate.py').read())❗ Be ready to execute the steps, they come fast! Here is sample output:
*** Remove weight
(Take 10 readings with empty scale)
>>> Empty reading [1]: 448516.2
*** Empty average: 448546.9
*** Place 100g weight
(Take 10 readings with the 100g weight on the scale)
>>> 100g reading [1]: 644976.4
*** 100g average: 644999.4
*** Remove weight
(Calculate scale factor)
*** Calculated scale factor is 1964.525
*** Replace 100g weight: L- R+ button adjust scale factor
>>> Measured weight is 100.014g
(click L button e.g.)
Decrease scale factor to 1963.525
>>> Measured weight is 100.024g
Once you have the Measured weight reading exactly 100g, take the calibration factor and update the _CALIBRATION_FACTOR constant definition in the main.py script in the firmware folder:
"""Main file running on the scales ESP32."""
...
### constants ###
...
_CALIBRATION_FACTOR = 1963.525 # scale calibration factorSave the script, then upload to the ESP32 using ampy:
ampy put firmware/main.pyDisconnect the scale from your computer - it should be 100% functional at this point!