Mongoose OS

Mongoose OS is an open source Operating System for the IOT, supporting ESP32, ESP8266, STM32, TI CC3200 (Amazon AWS IoT integrated). Code in C or JavaScript.  Time to give it a go! Updated (gutted) June 02, 2017.

Some time ago I tested Mongoose OS, early days and I had a lot of difficulties.  This blog is a partial re-write because I see no reason to leave information lying around that is well out of date – there is a lot of that on the web already – and the current setup is MUCH easier to use than before.  I have to tell you that the version changed as I was writing this so make sure you have the latest mos.exe

So the context for this is ESP8266 and ESP32 – as a veteran C programmer who has taken on Node-Red like a new religion, I’m starting to really like programming in JavaScript. Up to now,  many the interpreted languages I’ve seen for the ESP8266 seem to eat up all the RAM – or have other limitations – so I keep looking. I played with another JavaScript recently which seemed to have very little storage for programs…I’ve also been playing with microPython – but the current stumbling block on that is the MQTT implementation does not seem to be 100% reliable – and for me, reliable WIFI and MQTT is the starting block.

So – Mongoose – on a Windows 10 PC at least (they support other operating systems but I only have the one), you go to their site and download a program called MOS.EXE.   I put it on my desktop.  It wants a folder for its stuff so I made one on the desktop called “mos”.  You may choose to do things differently. I put the actual MOS.EXE program into my c:\windows folder.  The docs suggest that somewhere.

So assuming you have an ESP8266 in an FTDI of some sort, or, depending on the board simply plugged into a USB lead, ready to program up – in my tests I used a bog-standard ESP-12 – I do not recommend even considering the earlier boards such as ESP-01 with limited FLASH (512K) – just too restrictive and anyway, ESP12-based boards are usually dirt cheap. My Wemos D1 was only a couple of pounds from AliExpress.


I opened a DOS box and ran “mos” – and a browser opened in Windows – with the above control panel in it. I followed the instructions after telling it what chip I’m using and what COM port… from the command line on the desktop (don’t worry this is not command line stuff generally)

I also told it about my WIFI and the software went off and created a new chip, ready to run with an example program in it.  This is SO very different to the earlier versions which involved messing around on the command line.

In my case for one board when doing the above I held GPIO0 low on reset to put the board into programming mode – it may be that whatever board you are using handles that using DTR… which Mongoose supports – kind of like the Arduino IDE does.

From there on it was plain sailing – I tried their example of a button press triggering an MQTT message… realising there was no reference to my MQTT broker in their script – in “prototyping mode”  I hit the configuration tab in the web UI and in the middle of THAT (device config) (simple view)… was the MQTT setup. If you’re using a public MQTT then life is easier as you don’t have to make changes – you can use their default – but I like to use my own.

No reference to ports so I put my MQTT address as “” – added username and password and saved the config – the UI uploaded that to the board and rebooted it. I could see in the console message that all was working well.

I set my MQTT client on the PC to subscribe to /devices/# and noted that the light on the ESP8266 board was flashing (which if you look at the example code they default to – it is supposed to). I shorted the relevant pin – in this case the connector marked D3 – to ground and sure enough – just as the Mongoose interface confirmed I had published a message – it appeared on my MQTT client.

Now, sending an MQTT message is one thing – but does the MQTT recover from lost connections – and more importantly does it re-subscribe?  Well, I spoke to Sergey Lyubka and he says absolutely YES. If true this is a really good start!!!

So is Mongoose OS any use? After all we can program these boards in Arduino IDE or in C using the SDK and you can write BIG programs in C without worrying too much about storage?

Well, I’m only at the start of this but if you look at their site it looks like they handle OTA, temperature sensors and other stuff already and once you get past any starting hurdles – it takes seconds to try a sample program and if you are comfortable with Javascript – you might find this useful.

Right now in the setup there is only one access point name – a backup one would be nice… also I note that I2C is set up automatically on GPIO12 and GPIO14 but you CAN disable it – just as you CAN enable SPI – all in the setup.

I did all of this again on my ESP32 board and that worked just as well – however my £6 ESP32 board does not have a LED connected to a pin – so I had to wire up a LED – and that worked well.

if you’re into Javascript –  this Mongoose OS  quick look is not a definitive “yes this is a winner” but more just an enthusiastic introduction.  Comments welcome.

working Mongoose

So very much to learn but i have made contact with Sergey Lyubka of Mongoose – and I’ve let him know of small issues I’ve encountered ( like what looks like an error but isn’t in the image above – bottom right panel) – expect more updates soon. This looks well worth progressing. It is worth noting that the FREE RAM in this example on an ESP8266 is considerably more than the FREE RAM I encountered when play with microPython. Of course on an ESP32 there will be a lot more but as the ESP8266 is very cheap – it is important that this has enough resources.

With MQTT working an examples of how to read and write ports – that’s one hell of a start..


41 thoughts on “Mongoose OS

  1. Hi Peter –

    Thanks for sharing your experiences with Mongoose. I just starting evaluating it last week (on the ESP8266) and so far I am very impressed. Seems very stable and has most of the basic WiFi framework and development functionality I have been looking for (and trying to create and stabilize myself using Arduino libraries). My next steps are to run stress tests and collect stats on HTTP and Websocket connections (latency, max connections, up time, etc).

    – Joe

  2. The other apps are at:

    My sticking point is I tried this:
    at the bottom is the AWS IoT button example:

    You’re supposed to push the button and receive an email. I’ve watched through the console and I get an email saying I need to click on the link to confirm my subscription. Which says my email address is right and it can get to me. I click the link and says confirmation successful. However after that I push the button and no email. I hope to get this going as this would be a great framework to do some more IoT work. Everything I’ve seen mostly is people doing basic stuff with little to no security. This do that and a ton more. After spending time here and there over the last 3 days I’m starting to lose interest and I don’t want to. I may have to delete everything and stat again from scratch.

    I don’t think I should have to get a degree in AWS services to make this work. I’d like to get back to the code and make it do something else. Nothing like getting stuck on a “Hello World” type example to drive you nuts.


    1. Hi Michael –

      Any luck? I am going to try the ESP32 AWS demo later this week. I am currently evaluating Mongoose with the ESP8266. Connecting to AWS is one of my next steps. Please post your progress and I will do the same.

      Thanks for sharing …

      – Joe

      1. Joe,
        I’m currently going back to start at square one. I removed all the settings in AWS services I could find and try again. Thinking maybe I missed some step somewhere. The initial setup didn’t take that long. So maybe you will have better luck. I’m hoping I can get to set mine up again in the next couple of days to see.


      2. Joe,
        Honestly not sure what I did any different. I removed everything and started from scratch. Anyway I’m getting the email notifications now.

        So at least I can start to learn what makes everything work. Also build on this one that I have working.

        OH, if you get a chance. Load the Amazon Kindle app. They a half dozen Amazon AWS services documents that are free that explains each of the services used in the example. AWS IoT, Lambda, CloudWatch, Cloud Formation, Simple Notification Service.

        1. Hi Michael –

          Thanks for the update and Kindle reference.

          I just received a few ESP32 IoT kits and plan to get them up and going next week. In addition to the IoT capabilities, I am excited to test out the general ESP32 features and improvements over the ESP6288 (especially the ADC and BL/BLE).

          Do you know about Amazon FreeRTOS? – According to Amazon, ESP32 support is ‘coming soon’. Espressif announced their plan for support a few weeks ago – I will continue using Mongoose in the near term but will keep my eye on Amazon FreeRTOS – can’t ignore an offering from biggest company in the world!

          – Joe

          1. Joe,
            Yeah. It’s a bit confusing. I’m not sure what the holdup is. But also I know the Amazon ESP-IDF is built on FreeRTOS. As I understand it Mongoose OS is not an OS per-se. It basically a user space. What I don’t know is when you flash the ESP32 in the case of this AWS IoT button example what it’s built on. I would think FreeRTOS but not sure. I haven’t read enough on the API part of it or the code to see how it’s built. If I can find anything out I’ll let you know.


            1. Progress Report …

              The ESP32 IoT kit is working out great. Button presses successfully subscribe to AWS and can be seen on my AWS Console page. I am currently exploring the numerous other AWS IoT Services and features (Core, Device Management, OTA, Logging, Shadows, Analytics, Defender, etc). More to come …

  3. Hi,
    I am new to mongoose-os. I have working with esp32 from past few days for my home automation project. I have tried running mosquitto on pi board and it is working fine.
    Is there any way to run mosquitto mqtt server on esp32 with mongoose-os so that I don’t need to use any cloud services.
    This video shows about implementing mqtt server on esp8266

    Thank you.

    1. So the limits on an ESP8266 are obvious – RAM – not enough of it – best I’ve seen is 20 clients and other limitations the one that supports that many clients doesn’t currently have username and password protection. The ESP32 could allow for many more clients and support a wider range of options but you have to be very careful here. There are several fully equipped boards like Orange Pi Zero which can easily run (and all of mine do) Mosquitto and a ton of other software and they are barely more expensive than the ESP32. The ESP8266 has 2 things in it’s favour – size and cost. As soon as you take away one of those then you have to ask yourself why you would struggle. So for example for a few pounds more than an ESP32, I get Mosquitto, Node-Red, Apache, Ha-Bridge, a ton of utilities, hardwired Ethernet.. and more.

    1. The description doesn’t really seem to SAY a lot about what it actually DOES… so you can talk to Mongoose via MQTT… I should hope so – and then?

      1. Hmm, good point. I’ll take a note on that.
        One should get familiar with Mongoose OS first, then define an RPC function (in C or JavaScript) that does something (with hardware pins etc.). The node has the ability to call your (or built-in) RPC functions. That’s it. It’s a bit low level node but very essential.
        For example you’d created an RPC handler that measures room’s temperature. You can use the node to “tell” the device to measure it and then return the results.
        Also you can use the GPIO RPC service to read/write/configure esp’s pins.
        I’ll add some examples to node’s description for sure. Thanks Peter!

  4. So a quick update for everyone – I noticed an update for Mongoose in email…. I was using the ESP32 for something else… and loaded up the new update. This time was a different experience… the dropdown included the right serial port – I selected that. I selected ESP32, filled in WIFI details – and that was it – it went off, flashed the chip and I was up and running with their demo which flashes a light and waits for a pin to be grounded before sending off an MQTT message.

    Of course my board does not have a standard led on a pin – it just has a static power pin – so I added to the serial output the pin number – plugged in a LED and lo and behold a flashing LED. I then noted a new simple mode in the MOS web interface – and filled in my MQTT details including username and password – and pressed another button.

    Seconds later everything was working on my board and on my MQTT broker. I don’t think I’ve ever seen such an easy setup. Couple of error messages I did not understand – and I’ve reported them – but the actual code is sitting here working a treat.

    Chuffed that this was so simple, I took a brand new WEMOS ESP8266 board, restarted MOS and again it showed serial ports including the one for the ESP8266. I selected that, selected ESP8266 and pressed a button.. Again within seconds I had a working board – this time with a flashing light. The MQTT is also working on the ESP8266 but I’ve not tested reliability.

    It is very late so I think a re-look at this over the weekend.

    1. Agreed. I received some Lolin32 boards from Wemos yesterday and just had to install the driver and mos to get started. It couldn’t get any easier than this.

  5. I’ve been playing with these on and off.

    Home Nine

    “It runs JavaScript and supports npm, which means scripts to control it can be built with Node.js.”

    Whilst playing with it, I got introduced to Atom and Platformio, which also works great for Arduino code development – check this out

    In other works, the same IDE experience for all devices and differing languages – I know its not Mongoose, but just another take on things “dev”

  6. I found it a quick way to get one’s feet wet with a ESP32. All the examples I tried ran nicely. However, the MQTT Sub example kept disconnecting.
    I let it send random ADC reads to my MQTT server every 5 seconds for two days without a hitch.

    1. That’s encouraging, Bruce, looking forward to getting my ESP32 in the post… worrying however about the disconnects. Do let us know if you find a reliable way to stop that – absolutely no use unless it is completely reliable.

      1. {
        “clean_session”: true,
        “client_id”: “esp32”,
        “enable”: true,
        “keep_alive”: 60,
        “pass”: “”,
        “reconnect_timeout_max”: 60,
        “reconnect_timeout_min”: 2,
        “server”: “”,
        “ssl_ca_cert”: “”,
        “ssl_cert”: “”,
        “ssl_cipher_suites”: “”,
        “ssl_key”: “”,
        “ssl_psk_identity”: “”,
        “ssl_psk_key”: “”,
        “user”: “”,
        “will_message”: “”,
        “will_topic”: “”
        mqtt_global_connect MQTT connecting to
        mgos_mqtt_ev MQTT Connect (0)
        mgos_mqtt_ev MQTT Disconnect
        mqtt_global_reconnec MQTT connecting after 14515 ms
        mqtt_global_connect MQTT connecting to
        mgos_mqtt_ev MQTT Connect (0)
        mgos_mqtt_ev MQTT Disconnect
        mqtt_global_reconnec MQTT connecting after 29763 ms
        mgos_fs_get_handler Sending conf0.json
        mqtt_global_connect MQTT connecting to
        mgos_mqtt_ev MQTT Connect (0)
        mgos_mqtt_ev MQTT Disconnect

        My MQTT test server is running on the 192.168.11 segment with no passwords or other security. Strictly for in house testing.
        Other clients are subscribed without issue.

        1. Thank you. We were testing agains AWS IoT, Hive MQ,, Google MQTT servers. No issues.

          What server software you’re using, and what MQTT protocol version?

          Actually, I suggest starting a thread at

        2. Have you made sure that you don’t have more than one device with the same MQTT client ID? That certainly produces the problem you are seeing there.

          1. I am familiar with the situation you describe. This was quite different. However, I’m happy to report that the issue has disappeared.
            I finally got back to this project after a detour and uploaded the latest, July 4 MOS environment.
            The ESP32 is running perfectly! No MQTT dropping issues. A couple of other little oddities. i.e. not reporting ‘free ram’ correctly, have all been cleared up.
            This all seems very solid.
            Now, waiting for Bluetooth………

    1. It is, Antonio. most likely the issue was merely leaving the ports on automatic and the author has written back to say this will be investigated.

  7. Looks interesting Pete.

    Have you also taken a look at ESPeasy @ ?. It supports tons of sensor, ota, has built in rules and is Arduino based.
    I tend to flash all my modules with this now. Use Openhab version of mqtt for generic mqtt brokers.

    1. Hi Tony – most of these systems are in development and are fairly basic. I’m merely experimenting to see which are most likely to succeed.

      For my own control at home in the UK and here in Spain, I mostly I use my own software all under Node-Red control. I also use Tasmota for the Sonoff devices mainly as that is where his focus is and he can manage OTA on limited FLASH devices (if they’d put 4MB of FLASH in the Sonoffs I’d use my own software).

      As a reminder, this works on the ESP8266, has a Node-Red node to work with it and can control Dallas chips, DHT11 and DHT22, has digital inputs and outputs as well as the analog input, runs relays, LEDS, RGB LEDs (both serial and PWM offering eye-compensated colour and hue control), BMP280 and BME280, Seed OLED, PCA9685 PWM, ADS1115, GY30, Hitachi displays, port expansion and a lot more as well as working with Nextion displays and handling two access points with automatic fallover and unlike the general ESP-Arduino software, for storage of data it uses multiple copies for failure recovery. All of that is detailed in the blog here with articles covering the development of this as it happened.

      However, occasionally it pays to look up and see what others are up to and that is why I’m having a look at Mongoose. Up to now I’ve found only limited examples but I’m hoping that people will write in to show me where all the other examples are hiding. Meanwhile of course I keep finding ways to improve my setup such as the new Amazon Polly which I’m writing about as we speak.

      Someone pointed me to ESPEasy some time ago and while it offers a few ready-programmed peripherals there is little there to to attract me right now.

      I do like the idea of programming in Javascript instead of C, though I suspect that either RAM or FLASH will ultimately become a bottleneck – too early to tell with Mongoose – it does however raise the prospect of easy initial entry into the world of the ESP32 and I have some of these on the way from China right now – so worth more than a glance perhaps.

        1. its is good that there are a number of devs working on it now. The guys producing plugins are also very active.

          I developed my own code a couple? of years ago for my “IoTBox” but once the programming novelty wears off I found it was easier to use this :-).

          Javascript on the esp does look interesting though!.

          (Pete – I have used your Homecontrol code as well – thanks for making it!. I noticed on Letscontrolit that someone has used your nextion board and written a module for it)

      1. Hi Peter, thank you very much for writing this article, very well explained and super easy to understand. I was wondering why you like the idea of programming in Javascript instead of C. We’re considering running our lights on the ESP32, I’m looking forward to hearing all about your tests and what you think of it.

        1. Language choice depends on application.I use C for most things but JavaScript handling of JSON is light years better than doing it in C. Other than that I have no preference.

          1. Personally I’m some way from exhausting ESP8266 capacity so ESP32 not on my urgent need list though sometimes the program RAM on the EDP8266 could benefit from less Espressif library bloat.

    2. +1 here

      ESPeasy and lately their new version 2 (mega) is my absolute favourite.
      Using it with domoticz and Thingspeak, flashed to many different Sonoff devices, using sensors with nodemcu boards and all working absolutely amazingly. With rules you have so much power to simply customize a device and get so much done. The fail-over (second) wifi setting is a great new feature. I am supporting the dev on patreon as I hope this project is going to grow and be around for years to come. It basically removed any need for custom software and programming my ESPs as I can do almost everything around the house using ESPeasy.

      All that said, I’m here as I’m installing Mongoose on my ESP32 … it never hurts to see what out there 😉 But again, if you haven’t tried ESPeasy, or used it years ago, give it a shot!

      Btw. Thank you Peter for all your work you put into this web. Many times I get stuck reading on and on. I love that you approach things with a keen eye and describe your experience/opinion thoroughly. Also that you update your articles. It must take a lot of time and it is rare and appreciated!

      1. As you mention it I’ve just been updating an old article about gauges in which I made a lot of progress with gauges for Node-Red Dashboard. I thought it worth getting rid of the (at the time) headline grabber about a competition which is of course no longer valid. I’e renamed the article “Gauges and NR Dashboard” to make it easier to find.

      2. That’s exactly how I do my programming but with ESP-GO – all the work is done in Node-Red… but I’ve added improvements to ESP-GO to allow more flexible use of IO snd only this week (not yet published) created what will be called ESP-GO-3 – leaving ESP-GO in place using SDK 2.1 as now. The new version uses the as-yet only-on-GIT Espressif SDK 3.1 Non-OS – and I got back a whole 5k of RAM ensuring room for future expansion – thanks to help from guys at Espresssif forum – but that needs much testing – and I need to remember how to start and populate a new repository on BitBucket.

Comments are closed.