If you are making changes to Espruino itself, you need a way to quickly build and test it. This tutorial shows you how to do that on the Bangle.js 2 watch.
We will build Espruino both for a real Bangle.js 2 and the eumulator that is built into the Web IDE. It is always recommended to test on real hardware, but you can use the emulator if you don't have a watch, or if you're just trying things out and plan to test on the real watch later.
You'll first need to compile Espruino. The recommended way to do this is via the GitHub action. To use it, you must push your changes to a branch on GitHub, then you can start a GitHub action that will compile Espruino for you:
Actions
tab.Workflows
click Firmware Build
.Run Workflow
.DFU
and emulator
builds. This will make the workflow run faster.Run Workflow
.BANGLEJS2
or EMSCRIPTEN2
build under Jobs
to see logs from the build process.Summary
.Artifacts
section to find the builds you need.BANGLEJS2
file to download the firmware for a Bangle.js 2 watch.EMSCRIPTEN2
file to download the emulator for a Bangle.js 2 watch.You can read more about this method and other methods of compiling at https://github.com/espruino/Espruino/blob/master/README_Building.md
The GitHub method is recommended because it works on any machine and builds the firmware in a reproducible manner. If you choose to compile on your local machine, it might be configured incorrectly which can break your build in various ways that are hard to debug.
If you upload bad firmware, you can potentially brick your watch. There are a few things you can do to minimise this risk.
If the app loader refuses to upload your firmware, don't try to force it by using a different method. Chances are your firmware is bad and you need to fix it.
If there are any new build errors or warnings, fix them before trying to upload the firmware to your watch.
The watch uses something called the DFU loader to flash new firmware. Try to not make any changes to code that references DFU
, that way if you upload broken Espruino firmware, it is still possible to recover your watch because the DFU is intact and can load a new firmware file.
If you are making a lot of unstable changes, consider testing in the emulator first. You can brick the emulator as much as you want, and then when the firmware seems to work in the emulator, there is a better chance that the firmware will not brick your watch.
To upload the firmware, use the Banglejs App Loader.
Connect
button in the app loader and follow the promptFirmware Update
and open it by clicking the hamburger iconAdvanced
sectionUpload
The upload takes a few minutes to complete, then the watch needs to flash the new firmware and reboot. The flash is complete when your normal watch face is displayed.
For this, you need to have a local copy of the Web IDE. The source code is available on GitHub: https://github.com/espruino/EspruinoWebIDE
Unzip the EMSCRIPTEN2
file you just downloaded, it should contain a file called emulator_banglejs2.js
. Replace the existing emulator file with the new one at EspruinoWebIDE/emu/emulator_banglejs2.js
.
Now make sure you have the necessary dependencies installed. You need to have Node installed, then from the Web IDE repository run the command:
npm install
Now you can start the Web IDE locally with the command:
npm run web
Check the terminal output to find a link that looks something like http://localhost:3000
, then open it in a browser.
Now you should be able to use the Web IDE with your custom emulator firmware.
This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.