Mongoose OS: an IoT firmware framework for ESP32, ESP8266 and STM32

The gap Mongoose OS fills between an RTOS and a cloud SDK

An RTOS gives you tasks and a scheduler. A cloud SDK gives you a client library. Neither gives you a firmware image that can update itself over the air, fall back to the previous image when the update fails, and ship with a configuration store and a device management path already wired in. Mongoose OS is aimed at that middle layer. The README lists over-the-air firmware updates with rollback on failures, remote device access, flash encryption, crypto chip support and ARM mbedTLS tuned for a small memory footprint as the framework's own features rather than things you assemble from parts.

The target audience is narrow and specific. The supported microcontrollers are CC3220, CC3200, ESP32, ESP8266, STM32F4, STM32L4 and STM32F7. If your board is not on that list, the framework does not claim to help you. Within that list, the pitch is that you write application logic in C or JavaScript and let the framework handle networking, storage and update plumbing. The mJS embedded JavaScript engine is part of the repository, which means small logic changes can ship without recompiling C.

It is not a general-purpose embedded platform. There is no claim of POSIX compatibility, no Linux target in the supported list, and no scheduler replacement. Teams that already have a working RTOS integration and only need an MQTT client should look elsewhere first.

How the repository is organised and what that says about the build

The top-level layout is apps/, fw/, include/, libs/, platforms/, src/ and tools/. That split is the clearest statement of the architecture available without building it. Platforms hold the per-chip support, libs hold the reusable components, apps hold the example and ready-to-go applications, and fw plus tools hold the firmware build and flashing machinery. The README refers to ready-to-go apps and libraries and points at the mongoose-os-apps and mongoose-os-libs GitHub organisations for contributed ones, so the intended workflow is composition: pick a platform, pull in libraries, add an app.

The cloud side is integration rather than abstraction. The README names AWS IoT, Google IoT Core, Microsoft Azure, Adafruit IO and generic MQTT servers as built-in. There is no claim of a provider-agnostic layer that makes all of them interchangeable, so switching clouds is closer to a port than a config change. There is also a device management dashboard service at mdash.net, which is a hosted service and therefore a dependency outside the repository.

The project carries partner listings from Amazon AWS, Google Cloud IoT Core, IBM Watson IoT, Microsoft Azure IoT, Texas Instruments, STMicroelectronics and Espressif Systems. Those are statements about commercial relationships, not about code quality, and they should be read that way.

Installing the toolchain and flashing a first ESP32 build

The README does not contain install commands. It points to the Mongoose OS documentation quickstart page at mongoose-os.com/docs/mongoose-os/quickstart/setup.md for setup, and to the support forum for technical questions. Treat that page as the source of truth for the current install steps, because the exact commands are not reproduced in the repository README and inventing them would be worse than sending you to the page that maintains them.

The documentation also names two recommended development kits: the ESP32-DevKitC for AWS IoT and an ESP32 kit for Google IoT Core. If you are starting from nothing, picking one of those removes a class of board-support problems, because they are the configurations the project itself recommends.

What the README does tell you about the build is the language split. Application code is C or JavaScript, and the JavaScript path runs on mJS. A minimal JavaScript app therefore lives in the apps/ area of the repository alongside the C ones, which is the fastest way to see the shape of a Mongoose OS application without reading the framework source. Note that the README does not document rollback behaviour at the command level, only that rollback on failures exists as a feature, so verify the failure path on your own hardware before trusting it in the field.

The release cadence is the real constraint

The most recent release listed is 2.20.0, dated 2021-12-15. Before that, 2.19.1 landed on 2021-02-08 and 2.19.0 on 2021-01-11. The repository's last push was on 2026-07-26, so commits are still arriving, but the tagged release line has been quiet for years. Those two facts are not in conflict and both matter: activity in the default branch is not the same thing as a supported firmware release you can pin.

This changes the adoption question. If you need a framework with a predictable release train and versioned security updates, Mongoose OS in its Community Edition form does not offer that on the evidence of the release list. If you can pin 2.20.0 and accept that it is the version you will be running, the framework's feature set is still coherent.

The second constraint is licensing. The README describes a dual licence: Community Edition under Apache License 2.0 and Enterprise Edition under a commercial licence. The comparison table states that the Community Edition's source code and functionality are limited, with a link to a licensing page, and that technical support for it comes from the forum and Gitter chat rather than from the development team. The README does not enumerate what the Community Edition omits. That gap is the first thing to close before you commit, because a limitation in the update or security path would be disqualifying for a fleet deployment.

Where Mongoose OS is the wrong tool

The clearest wrong-tool case is a project whose chip is not in the supported list. There is no generic HAL promise in the README, and the platform directory structure implies per-chip work. Porting to an unsupported part is a framework contribution, not a configuration exercise.

A second case is a team that only needs a TCP/IP stack or an MQTT client. The README separately links the Mongoose Web Server Library under GPLv2, which is a different product with a different licence and a different scope. If your requirement is a web server on a device, that library is the smaller dependency, and the GPLv2 terms are a different conversation from Apache 2.0.

A third case is cloud lock-in avoidance. The built-in integrations are named vendors plus generic MQTT. If your architecture requires a provider that is not in that list, you are writing the client yourself, and at that point you are using Mongoose OS mainly for its update and configuration machinery. That may still be worth it, but be honest about which part you are buying.

Finally, the README's own framing of the Community Edition as limited in source code and functionality is a signal. Projects that expect the full feature set from an Apache 2.0 download may find that the interesting parts sit behind the commercial licence.

Mongoose OS against FreeRTOS and against rolling your own OTA

The natural comparison is FreeRTOS. FreeRTOS is a kernel: tasks, queues, semaphores, and vendor ports for many chips. It does not ship an OTA update mechanism with rollback, a configuration store, or AWS and Azure integrations. Choosing FreeRTOS means you or your team builds the update path, the provisioning story and the cloud client, and you own the failure modes. Choosing Mongoose OS means accepting its supported chip list and its release cadence in exchange for those pieces already existing.

The comparison is not purely technical. FreeRTOS is a kernel licensed permissively and maintained by a foundation with a broad silicon vendor base. Mongoose OS is a framework from a single vendor, Cesanta, with a dual licence and a commercial tier. If your organisation is uncomfortable depending on one company for the update path of a deployed fleet, that is a legitimate reason to prefer the kernel plus your own OTA, even though it costs more engineering time up front.

A third option sits between them: take the Mongoose Web Server Library, which the README links under GPLv2, and build on it. That gives you the networking layer without the full framework and without the dual-licence question, at the cost of writing the update and provisioning logic yourself. The README does not compare these paths, so the choice rests on how much of the framework's feature list you actually intend to use.

Upgrade cost and licence implications to check before you commit

Upgrading within Mongoose OS means moving between tagged releases, and the tag list ends at 2.20.0 from 2021-12-15. There is no published long-term support branch in the README, and it does not describe an upgrade procedure or a migration guide between major versions. If you adopt, plan on 2.20.0 being your baseline and treat any future tag as a migration project rather than a routine bump.

On licensing, the README is explicit about the split: Community Edition under Apache License 2.0, Enterprise Edition under a commercial licence. Apache 2.0 permits closing the source of your end product, and the comparison table confirms that both editions allow this. The table also states that the Community Edition's source code and functionality are limited, with details on a separate licensing page. That page is where the actual boundary lives, and the README does not summarise it. Whether the limitation affects you depends entirely on which framework features your product depends on.

The README also links a commercial licensing page and a support page for paid options. This is not legal advice and the licence text governs; the practical point is that the Apache 2.0 badge at the top of the README describes one of two editions, not the whole project.

Editorial conclusion

Adopt Mongoose OS if you are targeting ESP32, ESP8266, CC3220, CC3200, STM32F4, STM32L4 or STM32F7 and you want OTA updates, rollback and cloud integrations without writing them yourself. Do not adopt it if your roadmap depends on a release train newer than 2.20.0 from 2021-12-15, or if you need a cloud provider outside the documented list. Before committing, read the licensing page that separates the Apache 2.0 Community Edition from the commercial Enterprise Edition, since the README states the source code and functionality of the Community Edition are limited, and check whether the limit touches the feature you need.

Frequently asked questions

Official sources

1. cesanta/mongoose-os on GitHub
2. Issues
3. Project website
4. README
5. Releases