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.

brew tap cesanta/mos
brew install mos
mos

sudo add-apt-repository ppa:mongoose-os/mos
sudo apt-get update
sudo apt-get install mos
mos

git clone https://github.com/mongoose-os/mos
cd mos-tool/mos/archlinux_pkgbuild/mos-release
makepkg
pacman -U ./mos-*.tar.xz
mos

curl -fsSL https://mongoose-os.com/downloads/mos/install.sh | /bin/bash
mos

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 mos command. 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 Ctrl-n 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 app1 directory. Notice how current directory changes to app1:

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 build/fw.zip. 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. Type 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

Type command 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://mdash.net/.

• Click on "Add device" button. That'll create a new device:

• Click on a gears icon to trigger device management dialog.

• 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
  

A device should become online ("green") on a dashboard:

Click on a gears icons to see a management dialong for a device: general information, 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. 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 favorite editor:

Paste this code snippet, that sends an MQTT message every second:

load('api_timer.js');
load('api_mqtt.js');

Timer.set(1000, Timer.REPEAT, function() {
    let ok = MQTT.pub('test/topic', 'hello from an updated firmware');
    print('mqtt message sent?', ok);
}, null);

Then, rebuild the firmware with mos build.

10. Update firmware over-the-air

Now let's update our device with the new firmware over the air.

Go to the mDash, click on the firmware update icon:

A file dialog should appear. In the file dialog, navigate to the app1/build directory, and choose fw.zip file:

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:

Next steps

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.