Microchip Quick Start
Last updated: June 1, 2017
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 can 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
Sensor is optional but recommended for the best experience.
Visit http://www.microchipdirect.com/ProductSearch.aspx?keywords=dm990101 for the list of Microchip development boards that Medium One supports.
Visit https://mediumone.com/microchip for a list of supported sensors.
Medium One cloud project
Visit https://mediumone.com/microchip/activate to activate the kit. You will use the information from the activation email you receive in subsequent steps. For MAC address, put the last 6 digits on the white sticker on your board.
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
iOS mobile app
Step 1: Update Latest Firmware
Follow these instructions to update to the board latest firmware before proceeding.
Step 2: Activating a Medium One account
Activate an account here. For MAC address, put the last 6 digits on the white sticker on your board.
You will receive an email that contains your project credentials.
Step 3: Connecting Your Board to Medium One
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, written in small text on both the sensor and the board.
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.
Next, make sure your computer is on the same network and connect to this Kit Configuration page at URL. It will be in the form: http://123456_iot-e.local/ (where 123456 are the last 6 digits of the MAC address, found on the sticker on the board.). The easiest way to get to this page is by clicking on the link in the activation email you’ve received from Step 2.
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:
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.
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.
Step 4: 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.
Let’s display some data:
In the navigation bar on the left, click on the Dashboard. You should see two widgets here, “Single User Real Time Events Log” and “Single User GeoPoint Chart.”
If you want to see the past data in tabular form, click on the “Single User Table” widget from the widget list at the bottom of the page. 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. You can learn more about different dashboard widgets in this documentation.
Click on a button on the board. You should see an event appear in the Real Time Events Log. If you have the motion sensor plugged in, wave your hand in front of it. 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.
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
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.
Double click on Base Python (blue box) and you’ll see the python code to monitor the air quality.
On the right toolbar, you’ll see a list of triggers, python templates, debugger and revision control.
Each workflow includes comments to guide you through the details. Feel free to experiment with modifications and build your own.
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.
Step 5: 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:
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:
If you click on sensor activity at the bottom of the devices screen, you can visualize analytics and history of the given sensor.
You can also create Sensor Alerts specific to the connected sensor on this page.
There is more information about the app below under “Tour of the Mobile App.”
Step 6: 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
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.
This is an aggregate of all the notifications across the connected devices. An example of such notifications:
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:
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 firstname.lastname@example.org.
Appendix A: 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.
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.