Microchip Quick Start

Last updated: April 9, 2017

Getting Started

This tutorial covers the IOT Ethernet Monitoring Kit from Medium One and Microchip.  It will walk you through the process of connecting your kit to Medium One’s cloud services and mobile app.  Once connected, you will be able to extract and analyze data from 4 different types of sensors:  air quality, barometric pressure and temperature, motion, and humidity. Utilizing our pre-built workflows, you will get weekly and daily reports on your sensor data, check whether your device is offline, and send smart notifications to your mobile device.

What You Will Need

  • Microchip IOT Ethernet Monitoring Kit with sensor

  • Medium One cloud project
    • Visit https://mediumone.com/microchip/activate to activate the kit.
    • You will use the information from the activation email in subsequent steps.
    • An example of information that would come in an activation email is below.  We will refer to this information throughout this document.
      • Last 6-digit Mac: 123456
      • For the Board:
        • Project MQTT ID: PPPPPPP
        • Project MQTT ID: PPPPPPP
        • User MQTT ID: MMMMMM
        • API Key: XXXXXX
        • API Password: NNNNNNNN
        • Device Name: sprinkles
      • For the Mobile App:
        • API Key: XXXXXX
        • Login: admin
        • Password: QQQQQQQQ
  • iOS mobile app

Update Latest Firmware

Follow these instructions to update to the board latest firmware before proceeding.

Connecting Your Board to your Medium One Account

The board is connected via ethernet network to the internet.  Your network will need to support DHCP to assign an IP address, have the TCP port 61620 open, and support Bonjour services.  Bonjour is used to locate the device by host name.  If that is not enabled, you should still be able to find the device on your router’s DHCP client list to obtain it’s IP address.

Connect your sensor to the board by plugging it into the mikrobus.  Make sure you match the pin names.  

image06

Connect ethernet cable and USB power cable and switch on the power.  You should see a blinking blue LED (D5) when it’s ready to be configured.  

image08

Next, make sure your computer is on the same network and connect to this Kit Configuration page at URL such as this: http://123456_iot-e.local/ (where 123456 are the last 6 digits of the MAC address provided by your board.  It’s can also be found on a sticker on the board.)

Note:

  • If the page doesn’t load, locate the IP address of the board and you can access it directly. http://<ip_address_of_board>

If you click the link in the activation email, this page will have the fields automatically filled in.  You can also fill out the form manually with the information from the email.  Click “Connect” when ready.  The Kit Configuration page should look like this:

image09

Notes:

  • The device name is arbitrary. You can change it anytime by coming back to the Kit Configuration page.  The device name is used to identify the device from the mobile app.
  • Visit the Kit Configuration page again to check on the connectivity status.
  • If the board was previously configured, you will see the previous device data there.
  • To reset the board to the factory image, restart the board by pressing SW2 and SW3. After releasing, wait until you see a blinking blue LED (D5) which means that the board is ready to be configured again.
  • The sensors are configured to send data once per 10 minutes or when a 15% change in value is detected.  The board separately sends self-check data to the cloud data streams once every 10 minutes. This is used to detect the location of the board and online connectivity health.  It is possible to modify the sensor sample rate or sensitivity level.  Contact us for more sample scripts on how to accomplish this.

Connecting iOS App to View Device and Data

Launch the mobile app on your iOS device.  Enter the API key, login and password from your activation email.  Note: the API key specifies your Medium One project. It is possible to have multiple Medium One projects.

You should see your device appear on the App:

image10

Click on the device. You should see additional details such as location and network information.  You can also control the board’s LEDs create Board Alerts:

image04

If you click on the sensor activity tab at the bottom of the screen, you can visualize analytics and history.

image11

You can also create Sensor Alerts specific to the connected sensor.

image15

Tour of Medium One Cloud Project

Upon the activation steps described above, a Medium One project is provisioned with a series of flexible functions that allow the developer to view data, edit workflows and perform various management functions.  Only a small subset of the functionality is touched upon here.  For further reference, see docs.mediumone.com.

Dashboards and Analytics

Once you have connected your device, you can visualize data using Medium One’s dashboard and analytics.  Log into your Medium One web portal with the credentials you received in your Welcome email.  

image12

Let’s display some data:

  • In the navigation bar on the left, click on the Dashboard.
  • From the widget selector at the bottom of the page, click on “Single User Real Time Events Log”.
  • From the widget selector at the bottom of the page, click on “Single User GeoPoint Chart” to display the location of the device.
  • From the widget selector at the bottom of the page, click on “Single User Table” to display the past data in tabular form.
  • For example, to see all events where the motion was detected, in the Table widget configuration, select raw:motion_detected and you can filter with this tag being true.

Click on a button on the board.  You should see an event appear in the Real Time Events Log.  Wave your hand on the motion sensor.  By default the motion sensor will not sense new motion if prior activity was detected within the past 10 minutes.  For this configuration, refer to the “More about sensors and how they are configured” guide.

You can also save and build your own custom dashboard views.

How Medium One Workflows Work

Your Medium One project is preconfigured and loaded with workflows for this kit.  Click on Workflow Studio on the left navigation bar.  You will see preset workflows developed for this application.  

Medium One workflows allow you to build python apps that are triggered in real-time by the individual sensor events.  They support powerful cloud services that are called as libraries (python modules) from your python application.  Learn more about our workflows and basic tutorials on our website at docs.mediumone.com

To view our workflow, click on Workflow Studio.  Here, you’ll see a series of workflows created for this kit.  

They include the following capabilities:

  • Monitoring sensor data to trigger notifications
  • Create aggregate views for mobile app
  • Processing normal ranges for each board and sensor type
  • Location change detection
  • Offline sensor detection
  • Build weekly and daily reports
  • Broadcast commands to the board

As an example, let’s open the Air Quality Monitor workflow. Here you will see 3 boxes.  The green box is the data tag that triggers the workflows.  In this case, every time that an event is received in the raw data stream with the air_quality key present, this workflow will execute.  The blue box is the programmatic Python module, and the orange box is the data collection where the output event is stored.

image07

Double click on Base Python (blue box) and you’ll see the python code to monitor the air quality.  image03

On the right toolbar, you’ll see a list of triggers, python templates, debugger and revision control.  

image14

Each workflow includes ample comments to guide you through the details.  Feel free to experiment with modifications and build your own.

Notes

  • Workflows can be daisy chained and can operate on unstructured json data.
  • Medium One offers services to build custom workflows.
  • All workflows are run in the context of an API Basic User.

Tour of Mobile App

The Mobile app allows you to do the following:

  • Visualize each connected device and control LEDs on the boards
  • Visualize daily, weekly and monthly historical data for each sensor
  • Create Board Alerts (detect offline or change in location)
  • Create Sensor Alerts (limit-based or outside of normal automatically detected range)
  • Receive notifications (push notifications coming soon)
  • Subscribe to daily or weekly reports via email

Sensor Section

image04

The mobile app connects to Medium One’s API via REST and is able to gather data for each device.  Each device has a list of notifications triggered by rules set in the app.

Board Alerts are based on the board activity independent of the connected sensor.  In fact, you can connect just the board without a sensor.  There are two types of alerts: Detect Offline and Outside of Range.  

Detect Offline will send a notification when the board is offline for a set period of time.  A reconnect notification is sent if the board comes back online.

Outside of Range sends a notification if the board changes location.  The location of the board is based on its IP address.  Note: the accuracy of the location is only up to the city level since it’s based on the IP address.

If you click on a sensor you can see charts (today, week or month view).

You can also Create Alerts for a specific Sensor such as values or activity in a given range.  

If you have more than one sensor, it’s recommended to create a new user (see Add a new device) below.

Notifications Section

This is an aggregate of all the notifications across the connected devices.  An example of such notifications:

image10

Reports Section

Here you can subscribe to daily or weekly reports.  An email report is generated for each connected device.  The email is sent to the email address used to activate the device.  Sample email is shown here:

Untitled

Other IOT Ethernet Monitoring Kit Information

Protocols and Security

The board and device communicate with Medium One cloud project over MQTT with TLS security, using both publish and subscribe topics.

The mobile app communicates with Medium One cloud project via REST over HTTPS.

User Configuration

The following identities are provisioned with the IOT Ethernet Monitoring Kit:

Web Admin users

  • This is the developer account used to access Medium One’s web portal, access all data in the project and build workflows.
  • The Web Admin User that created the project also receives email reports by default.  This can be changed through the Daily Reports workflow.
  • The user ID is the email address filled in the Activation web form with initial password received in the welcome email.

API users for the sensor boards

  • Each board or sensor is associated with a unique API user (login_id).
  • This user’s role is referred to in the Medium One documentation as API Basic User.
  • Each API Basic User has the access permissions only to the data associated with that user.
  • To manage these users, click on Setup -> Manage Users.  Here you will see a list of existing API users.

API users for Mobile App

  • The project comes with the user “admin”, and the initial password provided in the activation email.
  • This user’s role is referred to in the Medium One documentation as API Business user.
  • This is the authorized user that has access to view all device data across all devices associated with the project.
  • To manage this user, click on Setup -> Manage Administrators in Medium One’s portal.
  • Additionally, API Basic User “stats” is used in communication between the app at the cloud project.  The data associated with the “stats” user are various statistics collected across all sensor boards.

Connecting Multiple Sensor Boards to a Mobile App and Medium One Project

The app allows you to display and control multiple sensor boards.  You can add them to an existing Medium One cloud project as well as the Mobile App.  Here are the steps:

  • Add a new API Basic User dedicated to the new sensor board
    • In Medium One’s portal, click on Setup -> Manage API users, then click on Add.
    • For example, the new API user could be named “device2”.
    • Note the new user’s MQTT ID and password as these will be needed on the Kit Configuration page of the new board.
  • Connect to the Kit Configuration page of the new board as before (eg. http://123456_iot-e.local/), with slightly different information:
    • Use the same Project MQTT ID, API Key, and Device Name as before.
    • Use the new user’s User MQTT ID and API Password.
    • Select the appropriate Sensor Type for this sensor board.

Re-configuring a board for a new project

A sensor board can be reconfigured to be connected to another project with the following steps:

  • Clear a sensor board configuration by pressing and holding down switches S2 and S3, and switching the board power off and on.  Keep holding S2 and S3 depressed while you see green LEDs flashing in a rotating pattern until you see a blue LED D5 turn on.
  • Go to the Kit Configuration page (eg. http://123456_iot-e.local/) and fill out the form and submit.

What’s Next

Medium One is a powerful data compute platform that enables developers to build flexible, scalable applications.  You can explore the platform independently, but we also love to engage with developers, discuss unique applications and help solve fun, challenging data problems.  For further information, please contact us at support@medium.one.

Author: David Thai