Open-Smartwatch OS runs a small C firmware on an ESP32 watch

A firmware for a specific watch, not a general purpose OS

The Open-Smartwatch Operating System is a firmware project written in C, and the scope is set by the hardware it targets. The project is GPL-3.0 licensed, the default branch is master, and the last push was on 2026-09-27.

The build system is PlatformIO, and the README is essentially a build and flashing guide. The prerequisites are PlatformIO Core or PlatformIO IDE, the packages listed in scripts/requirements.txt, and, for LUA scripting support in the LIGHT_EDITION_DEV_LUA environment, SWIG, which the README notes is available in most package managers with brew install swig or apt install swig.

There is a detail in the prerequisites that will cost you time if you miss it. The repository contains binary data such as schematics and images, so git-lfs must be installed, and the README is explicit that cloning without git-lfs results in missing or broken files. The clone command is:

$ git clone --recurse-submodules https://github.com/Open-Smartwatch/open-smartwatch-os.git

The recursive submodule flag is not optional either, and the troubleshooting section names the symptom: Arduino_TFT.h: No such file or directory means you did not clone with the --recursive-submodules flag. So the same missing dependency produces two very different errors depending on which piece you forgot.

The build itself is one command:

$ pio run -t upload

And the -e flag selects a specific environment from platformio.ini when you want to compile for a particular model. The README also gives a VS Code path, opening the cloned directory with code open-smartwatch-os, and the repo has a .vscode/ directory to match.

The branch convention is worth internalising. The master branch is a stable version and develop is the beta version, and the recommendation is to upload master except if you want to help by testing the next release or need very new features.

The serial console is a real shell on the watch

One of the more useful things in the project is that the watch exposes a command line over the serial port, and it is not a debug print.

The command is pio device monitor, and the README says that in this serial console you can, besides much more, configure the watch, and that you type help to get started. The listing in the README shows the command set:

OSW > help
Available commands:
  configure - enter configuration mode
  help      - show this help
  hostname  - show the device hostname
  lock      - lock the console
  reboot    - warm-start the device forcefully
  time      - show current UTC time
  wipe      - format NVS partition and reset configuration

Two of those deserve attention. wipe formats the NVS partition and resets the configuration, which is the escape hatch when a watch is in a bad state. And configure enters configuration mode, which is the interactive path for setting the things in the config file.

The configuration model is the interesting part, and it is unusual enough to be worth understanding. There is an include/config.h.example file that you rename to include/config.h and adapt to your requirements, and the README says that config is only applied once after you wiped the flash of the watch or changed the config-version number in osw_config.h. The parenthetical is doing real work: the settings are written into non-volatile storage on first boot and are not re-read on every boot, so changing the header alone does nothing until you wipe or bump the version number.

That design is what lets the watch remember its identity, its name and its display settings without a filesystem, and it is also what makes a configuration change look like it did not take. The console's configure command and the wipe command are the two ways to work with it.

Screenshot capture turns UI work into a loop you can script

The screenshot facility is the feature that changes how you work on the user interface, because it removes the photograph of a physical watch from the loop.

The mechanism is a raw screen server that runs in the background on the watch and reports over serial, with a message like Started RAW ScreenServer under http://.../api/screenserver. Enabling it takes a build flag, adding -D RAW_SCREEN_SERVER to the build flags in platformio.ini, then building, flashing and rebooting the watch.

The procedure is three steps. Connect and wait for the server to start, then run bash fetchScreen.sh with the watch IP and an output filename to download the raw image buffer and convert it to png, then run bash composeScreen.sh to create the image with a surrounding smartwatch overlay, in the light edition. The fast way bundles both into scripts/screen_capture/createScreenshot.sh, taking the watch IP and a screenshot name, with the captured file landing in a screenshot/ folder inside the open-smartwatch-os directory.

The requirements are modest: Wi-Fi has to be able to connect, you need bash and ImageMagick for the helper scripts, curl must be installed if it is not already, and you need the feature flag enabled. The scripts directory in the repository holds them.

The images in the README show the result, an analog watchface and a digital one, which is the point of the overlay. A raw framebuffer dump on its own is a rectangle of pixels, and the composed image places it in a watch body so a screenshot in a bug report looks like a watch rather than a stray image file. The project ships both watchfaces as screenshots, which doubles as a visual regression reference.

The emulator runs the OS on your machine

The OS can be executed as a regular program on your machine, and the README explains the motivation directly: this saves you time compiling for the watch and flashing the OS every time you make a minor change, for example while developing the UI or a game that does not explicitly depend on the watch hardware.

The emulator is built with CMake, using the CMakeLists.txt file at the top of the repository, and the emulator/ directory holds it. The top level also has a data/ directory, an img/ directory for images, include/ for headers, lib/ for libraries, sd/ for SD card content, src/ for the source, scripts/ for the helper scripts and the PlatformIO requirements, and docs/.

The README is honest about what the emulator costs you. The limitations come from having to hack and reimplement some of the Arduino-specific libraries and their conflicting simplifications, and the note adds that it may be necessary to extend those extensions down the road, since the authors likely missed that one specific function you try to use.

That is the correct trade for a firmware project of this kind. The alternative is a build and flash cycle for every UI tweak, which is slow enough to change how you work, and the cost is a compatibility layer that is good enough for most code and occasionally surprising.

The CI workflows mirror the two build targets. There is a test-OSW workflow for the watch, a test-EMULATOR workflow for the desktop build, plus test-FEATURE, test-OS and an astyle auto-format workflow. Having the emulator built in CI is what keeps the two from drifting apart.

Releases, flashing gotchas and where to look for help

The release history is slow and dated, which is worth weighing before you commit to the project. v0.17.1 and v0.17.2 both came on 10 November 2024, and v0.18.0 on 14 January 2025. The last push was on 2026-09-27, so there is activity on the repository, but the newest tag is more than a year old, and the branch model is the release model here, since the README tells you to upload master for a stable build and develop for the beta.

The flashing procedure has its own gotcha, and it is the one that catches first time users. The troubleshooting entry for Failed to connect to ESP32: Timed out waiting for packet header says you did not hold down BTN1, the FLASH button, and then tap the RESET button on the watch while platform.io was trying to connect. That is a manual step in the loop, and it is a consequence of the ESP32 boot mode needing to be selected with a button held down.

For anything beyond that, the README points to a wiki page for troubleshooting and to the project website for documentation, and it opens by asking readers to read the documentation on the website. The repository has a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a docs/ directory, plus a .gitattributes and .gitmodules, and the .github/ directory holds the workflow definitions that the badges point at.

One more workflow detail is worth knowing. The README says to add the respective flags to platformio.ini to compile the examples or other applications that are excluded by default, and to look into src/apps/examples to get started. So the example applications are not built by default, which keeps the default firmware image small, and turning one on is a matter of adding a flag rather than editing a project file.

Editorial conclusion

Open-Smartwatch OS suits a maker building a watch on the Open-Smartwatch hardware who wants an ownable firmware with a serial console and a desktop emulator for UI work, and it is the wrong tool if you need a consumer smartwatch app or a general purpose RTOS. Before you flash it, read the flashing procedure, because the README explains that connecting to the ESP32 requires holding BTN1 and tapping RESET while PlatformIO tries to attach, which is the step that trips up first time users. Verify first that you have git-lfs installed before cloning, since the repository contains binary data and a clone without lfs produces missing or broken files rather than a clear error.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Open-Smartwatch/open-smartwatch-os on GitHub
3. Project website
4. README
5. Releases