Mongoose OS quick start quide
A 12-minute guide to turn your device into a mobile-controllable, updatable, remotely manageable, secure, configurable product.
1. Download and install mos tool
Mongoose OS uses
mos tool for various tasks:
building firmware, flashing firmware,
managing device, provisioning device on cloud services, and so on.
|MacOS||First, install brew utility. Then execute the following to start a Web UI:
brew tap cesanta/mos
|Ubuntu Linux||Note: Linux version starts UI in a browser window.
sudo add-apt-repository ppa:mongoose-os/mos
|Arch Linux||Note: Linux version start UI in a browser window.
git clone https://github.com/cesanta/mos-tool
|Generic MacOS/Linux||Note: starts UI in a browser window.
curl -fsSL https://mongoose-os.com/downloads/mos/install.sh | /bin/bash
2. Start mos tool
Make sure your device is connected via the USB to your workstation.
Completing previous section should leave you with the
mos Web UI running:
Note: if you like using command prompt / terminal instead of the UI,
you can execute
mos commands in a command prompt instead.
The Web UI appears only when
mos tool is started without arguments.
On Windows and Mac, closing the Web UI window also terminates the
On Linux, the Web UI is started in a browser, so to stop it, close the
browser window and pressing
Ctrl-C in a terminal where
mos is running.
3. USB-to-Serial drivers
If you have your device connected via the USB, the UI can still complain about the unavailable ports like this:
The most usual reason for this is a missing USB-to-Serial driver. Below are the links to the driver installation pages. Install the driver, and re-insert your device into the USB.
- Silabs drivers for Espressif boards
- CH43x drivers for Espressif boards
- FTDI drivers for CC3200, CC3220
In a "Choose port" dropdown, at least one port must appear.
NOTE: on some Mac computers, the port might not show up even after the driver is installed. The possible reason could be the extension policy, the fix is covered in this issue
4. Create new app
In the UI, select your board from the dropdown menu. Then, press
to create a new app. That will paste the following command:
mos clone https://github.com/mongoose-os-apps/demo-js app1
Press Enter. That is going to clone
demo-js repo into the
Notice how current directory changes to
5. Build app firmware
Make sure the board is selected. Type
mos build and press Enter.
That starts a build process that takes up to a minute to complete.
When the command finishes, the built firmware will be located at
As you can see, we did not make any changes to the app - we'll do that later.
6. Flash firmware
Make sure the port is selected in the dropdown menu.
mos flash and press enter. That will flash a built firmware to the device:
When flashing completes, the firmware starts to write logs to the serial console. Notice how new messages start to appear in the right window. The window autoscrolls to the bottom, unless you scroll up manually to see some previous logs.
7. Configure WiFi
mos wifi WIFI_NETWORK_NAME WIFI_PASSWORD. Use your own
network name/password. Press enter. On the serial console, you'll see how
the device reboots after saving new configuration settings, joins the WiFi
network, gets the IP configuration, and synchronises time with SNTP server:
8. Add device to the mDash management dashboard
- Login to the mDash at https://dash.mongoose-os.com/.
- Click on "Add new device" button. That'll create a new device.
- Click on a "Token" link to copy the device's access token to the clipboard:
- Go back to the mos tool, type command (change TOKEN to your copied token) and press enter:
mos config-set dash.enable=true dash.token=TOKEN
Notice that the device started to print messages
to the serial console. It sends this message to the dashboard, reporting
its state to the device shadow
(read more about device shadows).
Notice that the device became online on mDash, and how the device shadow updates every second, incrementing its version number:
Click on the "+" sign to expand the shadow. Scroll it down and see how the reported "uptime" metric updates every second. "Uptime" is the amount of time since the last power-on or reboot:
Click on a device name to see a detailed management console for the device: general information, real-time notifications, configuration editor, file editor, device shadow editor, and an RPC service call window. We won't study all these management tools now though, so proceed to the next step.
9. Enable mobile app
Click on the "Mobile app" menu, and click on a checkbox to enable mobile app. Enter your email address in the text box and press on "Send invitation" button:
On your mobile phone, open you inbox, open an email from mDash:
10. Control your device from the mobile app
Click on the link in the invitation email. This will bring you immediately to the PWA (Progressive Web App). It is available only for those who has the link, because the app access token is embedded inside the link.
Notice how the reported device state is displayed on the mobile app.
uptime metric is displayed as a read-only value. An
however, is rendered as a toggle button:
Pressing the button turns is on, changes the device shadow key
true, and lights on an LED on a device:
11. Make changes to the firmware
Click on the folder icon on the bottom left corner. That opens a system
file browser in the current app directory. Open
fs/init.js in your
LED on to
MY LED on and save:
Then, rebuild the firmware with
12. Update firmware over-the-air
Now let's update our device with the new firmware over the air.
Go to the mDash, click on "Devices" top menu item to see the device list. Select a device, click on "OTA update selected" button, then click on "Choose firmware .zip file":
Navigate to the freshly built
fw.zip file, then notice how the
progress bar appears showing the OTA progress:
During the OTA process, the device receives chunks of new firmware from the cloud, and serial console displays that:
Eventually, the device reboots with the new firmware and we could see the changed message in the serial console:
It's time to move on to more advanced topics - learn how to add support to different hardware peripherals, write logic in both C/C++ and JS, use API reference, send data to the databases/analytics engines like Firebase. Proceed to the advanced guide.