Caafs - playground for building IoT solutions with Microsoft Azure

Copyright 2018 [Ivan Emilov]

C.a.a.f.s (Care and Alarms facility systems) is cloud based IoT platform/playground that enables building demos, prototypes, showcases or rapidly customizing of different use cases. With C.a.a.f.s, you are able to:

• Provision and control devices/objects.
• Get simple statistic about devices/objects.
• Set filter to collect only delta data form devices/objects
• Consume live sensor data.
• Set Rules and trigger alarms.
• Send Notifcations based on the rules.
• Manage users.

More details about the application features can be found here.

Applicable for almost every industry but rather suitable and ready to use for the following real life use cases:

• Control facility systems based on threshold monitoring of sensor values
• Trend analysis based on automation triggers
• Notification of temperature irregularities for food services, technical equipment or pharmacy products (like vaccines)
• Notification of humidity irregularities in the plant industry

This web application is also apprpriate for everyone who loves Node.js, is interested in learning Internet of Things and wants to get familiar with Microsoft Azure. Additionally there is a complete free DeviceClient application developed for this platform.

Please feel free to extend and make suggestions how to improve the application. If you find any bugs, do not hesitate to submit the issues

Note: Currently not recommended for production without doing penetration and load tests. Additional facts:

1. based on PaaS services -> low maintenance costs
2. easy to configure and administrate without touching the code -> step by step description
3. scalable -> on demand
4. extendible -> extent for commercial use for everyone who is familiar with Node.js
5. open -> every feature has its API based on Express framework: you are free to develop your own UI or mobile app
6. secure -> uses token based authorization

Table of contents

• Architecture Overview
• Getting Started
  • Prerequisites
  • Deploying and Configuration
  • Run the application locally
  • Run the application on Azure
• Running the tests
• Usage
• Contributing
• Authors
• License

Architecture Overview

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. Before starting, the following azure resources should be deployed and configured:

Prerequisites

• Azure subscription: https://azure.microsoft.com/en-us/free/
• Azure Table/Blob Storage
• Azure IoT HuB
• Cosmos DB with Mongo DB API projections
• SendGrid Account
• Azure WebAPI with App Service plan

Deploy and Configure

Step by step description to deploy and configure the required resources

1. Create Resource Group
2. Create and Configure Storage Account
3. Create and Configure Azure IoT Hub
4. Create and Configure Azure Cosmos DB
5. Create and Configure Azure Sendgrid
6. Create and Configure Azure API App

Run the application locally

1. Install Node.js on your local machine.
2. Clone the repository on your local machine

git clone https://github.com/iemilov/caafs-platform.git

3. Install the required node modules:

npm install

4. Change the configuration parameters in config.js

Copy the whole content from config.js and store it separtely as backup. You will need it in this state for the final cloud deployment. But in order to start the application locally you should replace everywhere the "process.env" part with the real parameters created in the configuratioon steps. For example:

REAPLACE config.connectionString = process.env['endpointIoTHuB'] WITH config.connectionString = connection string from Step 9

5. Start the application:

npm start

If you have done everything correct, you should be able to access the API description on swagger UI on:

localhost:3000/docs

6. Test the application:

After the initial deployment an admin username "[email protected]" is automatic created. In order to use the exposed APIs you will need to get a token first. Make a post request to http://localhost:8001/api/login. You are free to use any tool for testing RESTful APIs. If you want it to test it on the browser go to http://localhost:3000/docs/#!/Users/loginPost an put the following body in the authentication text box: use the initialAdminPassword created in step 13

{
  "username": "[email protected]",
  "password": "intial password"
}

In the response body you should get an answer:

{
        "token": "jwt token" //This token will expire in 24 hours
}

The token expiration time can be changed in auth.js at the bottom of the file:

{
   exp: Math.floor(Date.now() / 1000) + (60 * 60 * 24)
}

From now you can start using the other APIs by using the Authorization paramter in the Header for every request (see example below):

{
        Authorization: Bearer <token you got from the Authentication request>
}

Run the application on Azure

1. Bring the config.js in the initial state with all "process.env" parameters

2. Deploy the code to the local git using the credentials created in Step 14 from the configuration steps (see example below)

git remote add apiapp <Git clone URL from Step 14>
git push apiapp master:master

The first deployment can take several minutes. Once the deployment is finished you should be able to see your API app under the following url:

http(s)://NAMEOFYOURAPIAPP.azurewebsites.net/docs

3. Login through the http://NAMEOFYOURAPIAPP.azurewebsites.net/api/login with the initial username:[email protected] and the initialAdminPassword created in step 13

4. Get the token and start using the other APIs as in Run the application locally

Note: If you test the APIs on the Browser with the Swagger UI please be sure that you load the main url only with http:// and not https://. When using other tools like postman you can use https://

Running the tests

Currently no automated tests are implemented! It is on the project roadmap.

Usage

• Connect real device to the platform
• Device Management
• Authenticate and authorize
• Manage Rules
• Manage Alarms
• Manage telemetry data
• Get activity logs
• Get Statisctic
• Connect web client to consume live data

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

If you like my work, please consider supporting me for maintaining and developing this application.

Authors

• Ivan Emilov
• Contact: [email protected]

License

This project is licensed under the ISC License - see the LICENSE.md file for details