Skill Level: Any Skill Level

Quick and easy start with connecting a microcontroller to IBM Watson IOT in under 20 minutes! Step by step tutorial.


  1. One of the supported development boards: STM32 B-L475E-IOT01A, STM32 NUCLEO-F746ZG, ESP32 Devkit-C, ESP32 PICO-D4-KIT, ESP8266 NodeMCU, TI CC3220SF LaunchPad.
  2. Windows, Mac or Linux laptop.
  3. USB type A to Micro-B USB cable to supply the power to the development board, and to program it from the laptoop.
  4. 2.4GHz b/g/n WiFi access point connected to the Internet (accessible via SSID/Password).
  5. Mongoose OS.


  1. Install Mongoose OS on your MCU

    Complete Quickstart Guide steps 1-7 inclusive (it takes less than 10 minutes): https://mongoose-os.com/docs/quickstart/setup.md

    As a result, Mongoose OS will be installed on your device and it will be connected to the Internet.Mongoose OS installation

  2. IBM Cloud Quick Setup

    Provision your device to IBM Watson:

    mos watson-iot-setup

    This does not require any credentials and will set up the device for QuickStart cloud dashboard connectivity. With QuickStart dashboard, you will be able to send data from the device at a limited rate but device management (sending commands to the device) is not available.

    Note: in order to make a button press to send events,

    • Mongoose OS RPC support should be disabled by
      mos config-set rpc.mqtt.enable=false
  3. IBM Cloud Account setup

    If you already have an IBM Cloud account and a cloud orgaization set up (you can register for a free trial here) you can use mos to add a device to your org.

    You will need to obtain app access credentials for mos to use:

    • In the left side pane og your Watson IoT Platform dashboard select Apps
    • Click the Generate API Key button in the upper right corner
    • For description, enter any meaningful text – e.g. “MOS CLI tool” and click Next
    • For Role select Standard Application
    • Copy the API Key and Authentication Token and use them on the mos command line:
      $ mos watson-iot-setup --watson-api-key a-bcdefgh-qwertyio --watson-api-auth-token "tokengoeshere"
      Using port /dev/ttyUSB0
      Connecting to the device...
      esp8266 1AFE34A5930F running demo-c
      Org ID: bcdefgh
      Device ID: esp8266_A5930F
      Checking device type "mos"...
      Creating device "esp8266_A5930F"...

      Updating config:
      device.id = esp8266_A5930F
      watson.client_id = d:bcdefgh:mos:esp8266_A5930F
      watson.enable = true
      watson.host_name = bcdefgh.messaging.internetofthings.ibmcloud.com
      watson.token = SECRET
      Setting new configuration...
      Saving and rebooting...

    Note: As with other flags, values can be specified as environment variables: `MOSWATSON_API_KEY and MOS_WATSON_API_AUTH_TOKEN`._

    Invoked with no additional flags, as above, mos will use device type mos (will be created if necessary) and device ID derived from platform and the device’s unique ID (usually MAC address) and a random auth token. Additional flags can be provided to override these defaults:

    • –watson-device-type – specifies device type
    • –watson-device-id – specifies device id
    • –watson-device-auth-token – specifies device auth token instead of generating a random one
    • –watson-api-host-name – use this host name for API calls instead of ORG_ID.internetofthings.ibmcloud.com
    • –watson-messaging-host-name – use this host name for device connections instead of ORG_ID.messaging.internetofthings.ibmcloud.com
  4. Video demonstration

    Please check out this 6 minutes video outlining firmware build, network configuration, IBM Watson IoT Quickstart provisioning: https://youtu.be/Uzyere6_WlE

Join The Discussion