ipm package: smart-monitoring

Overview

A generic Smart Monitoring system for tracking sensor data on gateways at multiple locations, configuring alerts, and managing users and security.

This is an ipm package, which contains one or more reusable assets within the ipm Community. The 'package.json' in this repo is a ipm spec's package.json, here, which is a superset of npm's package.json spec, here.

Browse ipm Packages

Setup

Getting Started

• Go to smart-monitoring Portal and sign up as a new User for the system
  • This user will automatically be granted Authenticated role permissions
  • Once in the portal, you can visualize and utilize all elements within the portal with the provided mock data

Security

• Define your security model by specifying permissions for various Roles.
• Add employees into the system as Users and assign them Roles to grant them permissions.

Edges

• Define and configure your gateways in the Edges table that will be housing sensors

Devices

• Define your sensors in the Devices table, specifying the Edge each belongs to

Alerts

• Define rules for alert configurations that will be used when processing sensor data to send alerts via test, email, or through internal messages to designated employees.
• Structure for Rules: { "sensor_id": "111111", "operator": "GT", - "GT"(greater than), "LT"(less than), "EQ"(equal) "value": "32", "property": "sensor_reading" }

Usage

Sensor data can be published via MQTT from edge to platform at topic: sensor/{sensorName}/_platform(used for data in smart_monitoring portal) or from platform to edge at topic: sensor/{sensorName}/_broadcast (used fro data in smart_monitoring_edge portal). This will trigger a code service that handles the data. It is responsible for detecting and signaling alerts, as well as storing sensor and alert data in history collections.

Message payload structure is as follows (notice all values are strings): { "edge_id": "first_edge", "sensor_message": { "batteryLevel": "100", "dataValue": "10", "sensorID": "111111", "signalStrength": "10", "messageDate": "2019-01-01T00:00:00Z" } }

Assets

Code Services

• createAlertConfiguration: creates a new alert configuration in AlertConfigurations
• createEmployee: creates a new employee in Users
• createLocation: creates a new locations in Locations
• createSensor: creates a new sensor in Devices
• createSensorType: creates a new sensor type in SensorTypes
• deleteAlertConfiguration: deletes an alert configuration
• deleteLocation: deletes a locations
• deleteSensor: deletes a sensor
• deleteSensorType: deletes a sensor type
• getAlertConfigurations: fetches alert configurations
• getAlertHistory: fetches alert history
• getAlerts: fetches alerts
• getAlertTypes: fetches alert types
• getEmployees: fetches employees
• getHistoryForSensors: fetches sensor history
• getLocations: fetches locations
• getSensors: fetches sensors
• getSensorTypes: fetches sensor types
• processSensorMessage: process sensor data when triggered by publishing to sensor/{sensorName}
• sendMessage: sends text, email, or internal MQTT message
• updateAlert: updates an alert
• updateAlertConfiguration: updates an alert configuration
• updateEmployee: updates an employee
• updateLocation: updates a location
• updateSensor: updates a sensor
• updateSensorType: updates a sensor type

Code Libraries

• checkAlertViolated: uses Rules stored in alert configuration to determine if alert should be sent
• Mailgun: sends emails via Mailgun REST API
• MailgunConstants: store constants to be used by Mailgun
• TwilioConstants: store constants to be used by TwilioSMSLib
• TwilioSMSLib: sends a text message using Twilio's REST API

Collections

• AlertConfigurations
• AlertHistory
• Alerts
• AlertTypes
• Locations
• sensors_data
• SensorTypes

Portals

mobile_alerts

• send messages and view/acknowledge alerts from a mobile device

smart_monitoring

• Home Page: view locations, send, configure, and acknowledge alerts, view and send messages, view sensor data by location/edge groupings, view historical sensor data

• Alerts Page: view, edit, delete, and create alert configurations

• Sensor Analytics Page: view historical sensor data filtered by edge2sensor relationships and timeframes

• Admin Pages: view, edit, delete, and create Sensors, Edges, Sensor Types, Locations, and Employees

API

Functions

checkAlertViolated(alertConfig) ⇒ string | boolean

createAlertConfiguration(alertConfiguration) ⇒ string | Array.<CreateAlertConfigurationResp>

createEmployee([employee], [employees]) ⇒ string | CreateEmployeeResponse

createLocation(location) ⇒ string | Array.<CreateLocationResponse>

createSensor(sensor) ⇒ string | Array.<CreateSensorResponse>

createSensorType(sensor_type) ⇒ string | Array.<CreateSensorTypeResp>

deleteAlertConfiguration(item_id) ⇒ string | Array.<DeleteAlertConfigResp>

deleteLocation(location_id) ⇒ string | Array.<DeleteLocationResp>

deleteSensor(sensor_id) ⇒ string

deleteSensorType(sensor_type_id) ⇒ string | Array.<DeleteLocationResp>

generateSyntheticSensorData()

Generate sensor data for demo purposes. This will run on Edge only. To be run on a timer with no user permissions.

Publishes an MQTT message on TOPIC_BASE

getAlertConfigurations([configuration_id], [type_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertConfigResp>

getAlertHistory([alert_id], [type_id], [configuration_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertConfigResp>

getAlertTypes([pageNum], [pageSize]) ⇒ string | Array.<GetAlertTypesResp>

getAlerts([alert_id], [type_id], [configuration_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertsResp>

getEmployees([employee_id], [email], [pageNum], [pageSize]) ⇒ string | Array.<GetEmployeesResp>

getHistoryForSensors(sensor_ids, startTime, endTime) ⇒ string | Array.<GetHistoryForSensorsResp>

getLocations([location_id], [pageNum], [pageSize]) ⇒ string | Array.<GetLocationsResp>

getSensorTypes([sensor_type_id], [pageNum], [pageSize]) ⇒ string | Array.<GetSensorTypesResp>

getSensors([sensor_id], [sensor_type_id], [edge_id], [pageNum], [pageSize]) ⇒ string | Array.<GetSensorsResp>

sendMessage(messageTypes, userEmails, payload) ⇒ string

updateAlert(alert, item_id) ⇒ string | UpdateAlertResp

updateAlertConfiguration(alertConfiguration, item_id) ⇒ string | UpdateAlertConfigResp

updateEmployee(employee, email) ⇒ string

updateLocation(location, location_id) ⇒ string | UpdateLocationResp

updateSensor(sensor, sensor_id) ⇒ string | UpdateSensorResp

updateSensorType(sensor_type, sensor_type_id) ⇒ string | UpdateSensorTypeResp

Typedefs

Mailgun

Mailgun - Send emails via Mailgun REST API

callback : function

This callback is displayed as part of this Library.

Twilio : Object

Sends a text message using Twilio's REST API.

CheckAlertConfig

AlertRule

CreateAlertConfigurationReq

CreateAlertConfigurationResp

NewUser

User

Employee

CreateEmployeeResponse

Location

CreateLocationResponse

Sensor

CreateSensorResponse

SensorType

CreateSensorTypeResp

DeleteAlertConfigResp

DeleteLocationResp

DeleteSensorTypeResp

GetAlertConfigResp

GetAlertHistoryResp

GetAlertTypesResp

GetAlertsResp

GetEmployeesResp

GetHistoryForSensorsResp

GetLocationsResp

GetSensorTypesResp

GetSensorsResp

SensorMessage

SensorPayload

UpdateAlertReq

UpdateAlertResp

UpdateAlertConfigReq

UpdateAlertConfigResp

UpdateEmployeeReq

UpdateLocationReq

UpdateLocationResp

UpdateSensorReq

UpdateSensorResp

UpdateSensorTypeReq

UpdateSensorTypeResp

checkAlertViolated(alertConfig) ⇒ string | boolean

Kind: global function
Returns: string - Errorboolean - ruleViolated

Library to determine whether or not a rule is violated.

Param	Type	Description
alertConfig	CheckAlertConfig	Alert configuration to to check for violation.

createAlertConfiguration(alertConfiguration) ⇒ string | Array.<CreateAlertConfigurationResp>

Kind: global function
Returns: string - ErrorArray.<CreateAlertConfigurationResp> - Array of new item ids Service for creating new alert configurations in AlertConfigurations collection

Param	Type
alertConfiguration	CreateAlertConfigurationReq

createEmployee([employee], [employees]) ⇒ string | CreateEmployeeResponse

Kind: global function
Returns: string - ErrorCreateEmployeeResponse - Service for creating new employees in Users table

Param	Type	Description
[employee]	NewUser
[employees]	Array.<NewUser>	Array containing multiple new user objects in the format above

createLocation(location) ⇒ string | Array.<CreateLocationResponse>

Kind: global function
Returns: string - ErrorArray.<CreateLocationResponse> - Service for creating new locations in Locations collection

Param	Type
location	Location

createSensor(sensor) ⇒ string | Array.<CreateSensorResponse>

Kind: global function
Returns: string - ErrorArray.<CreateSensorResponse> - Service for creating new sensors in the Devices table

Param	Type
sensor	Sensor

createSensorType(sensor_type) ⇒ string | Array.<CreateSensorTypeResp>

Kind: global function
Returns: string - ErrorArray.<CreateSensorTypeResp> - Service for creating new sensor type in SensorTypes collection

Param	Type
sensor_type	SensorType

deleteAlertConfiguration(item_id) ⇒ string | Array.<DeleteAlertConfigResp>

Kind: global function
Returns: string - ErrorArray.<DeleteAlertConfigResp> - Service for deleting an alert configuration from AlertConfigurations collection

Param	Type
item_id	string

deleteLocation(location_id) ⇒ string | Array.<DeleteLocationResp>

Kind: global function
Returns: string - ErrorArray.<DeleteLocationResp> - Service for deleting a location from Locations collection

Param	Type
location_id	string

deleteSensor(sensor_id) ⇒ string

Kind: global function
Returns: string - Service for deleting a sensor from Devices table

Param	Type
sensor_id	string

deleteSensorType(sensor_type_id) ⇒ string | Array.<DeleteLocationResp>

Kind: global function
Returns: string - ErrorArray.<DeleteLocationResp> - Service for deleting a sensor type from SensorTypes collection

Param	Type
sensor_type_id	string

generateSyntheticSensorData()

Generate sensor data for demo purposes. This will run on Edge only. To be run on a timer with no user permissions.

Publishes an MQTT message on TOPIC_BASE

Kind: global function

getAlertConfigurations([configuration_id], [type_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertConfigResp>

Kind: global function
Returns: string - ErrorArray.<GetAlertConfigResp> - Service for fetching alert configuration from AlertConfigurations collection

Param	Type	Description
[configuration_id]	string	To query for specific configuration by item_id
[type_id]	string	To query for configurations of specific type
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getAlertHistory([alert_id], [type_id], [configuration_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertConfigResp>

Kind: global function
Returns: string - ErrorArray.<GetAlertConfigResp> - Service for fetching alerts from Alert collection regardless of is_active status

Param	Type	Description
[alert_id]	string	To query for specific configuration by item_id
[type_id]	string	To query for configurations of specific type
[configuration_id]	string	To query for a specific configuration
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getAlertTypes([pageNum], [pageSize]) ⇒ string | Array.<GetAlertTypesResp>

Kind: global function
Returns: string - ErrorArray.<GetAlertTypesResp> - Service for fetching alert types from AlertTypes collection

Param	Type	Description
[pageNum]	number	pagination
[pageSize]	number	For pagination

getAlerts([alert_id], [type_id], [configuration_id], [pageNum], [pageSize]) ⇒ string | Array.<GetAlertsResp>

Kind: global function
Returns: string - ErrorArray.<GetAlertsResp> - Service for fetching alerts from Alert collection with is_active status of true

Param	Type	Description
[alert_id]	string	To query for specific configuration by item_id
[type_id]	string	To query for configurations of specific type
[configuration_id]	string	To query for a specific configuration
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getEmployees([employee_id], [email], [pageNum], [pageSize]) ⇒ string | Array.<GetEmployeesResp>

Kind: global function
Returns: string - ErrorArray.<GetEmployeesResp> - Service for fetching employees from Users table

Param	Type	Description
[employee_id]	string
[email]	string
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getHistoryForSensors(sensor_ids, startTime, endTime) ⇒ string | Array.<GetHistoryForSensorsResp>

Kind: global function
Returns: string - ErrArray.<GetHistoryForSensorsResp> - Service for fetching a range of sensor history for one or multiple sensors

Param	Type	Description
sensor_ids	Array.<string>	Sensors to include in query
startTime	string	string Beginning of time range in ISO 8601 format
endTime	string	string Beginning of time range in ISO 8601 format

getLocations([location_id], [pageNum], [pageSize]) ⇒ string | Array.<GetLocationsResp>

Kind: global function
Returns: string - ErrorArray.<GetLocationsResp> - Service for fetching locations from Locations collection

Param	Type	Description
[location_id]	string
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getSensorTypes([sensor_type_id], [pageNum], [pageSize]) ⇒ string | Array.<GetSensorTypesResp>

Kind: global function
Returns: string - ErrorArray.<GetSensorTypesResp> - Service for fetching sensor types from SensorTypes collection

Param	Type	Description
[sensor_type_id]	string	To query for sensor types by item_id
[pageNum]	number	For pagination
[pageSize]	number	For pagination

getSensors([sensor_id], [sensor_type_id], [edge_id], [pageNum], [pageSize]) ⇒ string | Array.<GetSensorsResp>

Kind: global function
Returns: string - ErrorArray.<GetSensorsResp> - Service for fetching sensors from Devices table

Param	Type	Description
[sensor_id]	string	To query for sensors by name
[sensor_type_id]	string	To query for sensors by item_id of type
[edge_id]	string	To query for sensors by edge_key of edge
[pageNum]	number	For pagination
[pageSize]	number	For pagination

sendMessage(messageTypes, userEmails, payload) ⇒ string

Kind: global function
Returns: string - Tally of errors for each type of message

Service that sends text, email, internal, or combination to designated employees

Param	Type	Description
messageTypes	Array.<string>	Indicates the types of messages ("sms", "email", "internal") to send
userEmails	Array.<string>	Email addresses of users to send message to
payload	string	Message to send

updateAlert(alert, item_id) ⇒ string | UpdateAlertResp

Kind: global function
Returns: string - ErrorUpdateAlertResp - Service that updates an alert in Alerts collection

Param	Type
alert	UpdateAlertReq
item_id	string

updateAlertConfiguration(alertConfiguration, item_id) ⇒ string | UpdateAlertConfigResp

Kind: global function
Returns: string - ErrorUpdateAlertConfigResp - Service that updates an alert configuration in AlertConfigurations collection

Param	Type
alertConfiguration	UpdateAlertConfigReq
item_id	string

updateEmployee(employee, email) ⇒ string

Kind: global function
Returns: string - Error Service that updates an employee in Users table

Param	Type
employee	UpdateEmployeeReq
email	string

updateLocation(location, location_id) ⇒ string | UpdateLocationResp

Kind: global function
Returns: string - ErrorUpdateLocationResp - Service that updates a location in Locations collection

Param	Type
location	UpdateLocationReq
location_id	string

updateSensor(sensor, sensor_id) ⇒ string | UpdateSensorResp

Kind: global function
Returns: string - ErrorUpdateSensorResp - Service that updates a sensor in Devices table

Param	Type
sensor	UpdateSensorReq
sensor_id	string

updateSensorType(sensor_type, sensor_type_id) ⇒ string | UpdateSensorTypeResp

Kind: global function
Returns: string - ErrorUpdateSensorTypeResp - Service that updates a sensor type in SensorTypes collection

Param	Type
sensor_type	UpdateSensorTypeReq
sensor_type_id	string

Mailgun

Mailgun - Send emails via Mailgun REST API

Kind: global typedef

Param	Type	Description
apikey	string	API Key found in Mailgun Console (https://www.mailgun.com/)
domain	string	Domain ex. mg.yoursite.com, provided by Mailgun
originEmail	string	origin address from which to send emails, provided by Mailgun

Mailgun.send(body, subject, recipient)

Kind: static method of Mailgun

Param	Type
body	string
subject	string
recipient	string

callback : function

This callback is displayed as part of this Library.

Kind: global typedef

Param	Type
err	Object
resp	Object

Twilio : Object

Sends a text message using Twilio's REST API.

Kind: global typedef

Param	Type	Description
user	string	Twilio API account ex. "BC218b72987d86855a5adb921370115a20"
pass	string	Twilio API passcode ex. "4579ac6ba4fae7b452c03c64aeae40e7"
sourceNumber	string	Origin phone number of text message, ex "(+1 512-713-2783)"

Example

var twconf = TWILIO_CONFIG;
var twilio = Twilio(twconf.USER, twconf.PASS, twconf.SOURCE_NUMBER);

Twilio.sendSMS(text, recipientNumber, callback)

Send SMS message

Kind: static method of Twilio

Param	Type	Description
text	string	text body
recipientNumber	string	Formatted phone number ex. "(+1 339-987-2816)"
callback	callback	ex. function(err, data){}

Example

var twconf = TWILIO_CONFIG;
var twilio = Twilio(twconf.USER, twconf.PASS, twconf.SOURCE_NUMBER);

twilio.sendSMS(text, recipientNumber, function(err, data) {
  if (err) {
    resp.error(err);
  }
  resp.success(data);
});

CheckAlertConfig

Kind: global typedef
Properties

Name	Type
rules	Array.<AlertRule>
disabled	boolean

AlertRule

Kind: global typedef
Properties

Name	Type
sensor_id	string
operator	string
value	string
property	string

CreateAlertConfigurationReq

Kind: global typedef
Properties

Name	Type
name	string
type_id	string
rules	Array.<Rule>
contacts	Array.<string>
priority	string
disabled	boolean
message	string

CreateAlertConfigurationResp

Kind: global typedef
Properties

Name	Type
item_id	string

NewUser

Kind: global typedef
Properties

Name	Type
user	User
employee	Employee

User

Kind: global typedef
Properties

Name	Type	Description
email	string	Email address of new user
password	string	Password for new user

Employee

Kind: global typedef
Properties

Name	Type
first_name	string
last_name	string
locations	Array.<string>
phone_number	string
photo	string

CreateEmployeeResponse

Kind: global typedef
Properties

Name	Type
email	string
password	string

Location

Kind: global typedef
Properties

Name	Type	Description
name	string
description	string
icon	string
location_type	string	Corresponds to item_id of a LocationType
lat	string
long	string

CreateLocationResponse

Kind: global typedef
Properties

Name	Type
item_id	string

Sensor

Kind: global typedef
Properties

Name	Type	Description
name	string
description	string
sensor_label	string	Readable label to display as name of sensor
sensor_type_id	string	Corresponds to item_id of a SensorType
edge_id	string	Corresponds to name of an Edge in Edges table

CreateSensorResponse

Kind: global typedef
Properties

Name	Type
active_key	string
allow_certificate_auth	boolean
allow_key_auth	boolean
certificate	string
description	string
enabled	boolean
keys	string
name	string
state	string
type	string

SensorType

Kind: global typedef
Properties

Name	Type	Description
name	string
description	string
data_type	string	Data type of sensor's data value
attributes	string	Special character corresponding to data value provided
icon	string
isProbe	boolean	Whether or not sensor is a probe

CreateSensorTypeResp

Kind: global typedef
Properties

Name	Type
item_id	string

DeleteAlertConfigResp

Kind: global typedef
Properties

Name	Type
count	number

DeleteLocationResp

Kind: global typedef
Properties

Name	Type
count	number

DeleteSensorTypeResp

Kind: global typedef
Properties

Name	Type
count	number

GetAlertConfigResp

Kind: global typedef
Properties

Name	Type
contacts	Array.<string>
item_id	string
disabled	boolean
message	string
name	string
priority	string
rules	Array.<Rule>
type_id	string

GetAlertHistoryResp

Kind: global typedef
Properties

Name	Type
type_id	Array.<string>
is_active	string
configuration_id	boolean
sent_date	string
acknowledge_date	string
target_users	string

GetAlertTypesResp

Kind: global typedef
Properties

Name	Type
item_id	string
name	string
description	string
icon	string

GetAlertsResp

Kind: global typedef
Properties

Name	Type
type_id	Array.<string>
is_active	string
configuration_id	boolean
sent_date	string
acknowledge_date	string
target_users	string

GetEmployeesResp

Kind: global typedef
Properties

Name	Type
email	string
creation_date	string
first_name	string
last_name	string
phone_number	string
locations	Array.<string>
photo	string
pin	string

GetHistoryForSensorsResp

Kind: global typedef
Properties

Name	Type
batter_level	number
edge_id	string
item_id	string
reading_time	string
sensor_id	string
sensor_reading	string
signal_strength	number

GetLocationsResp

Kind: global typedef
Properties

Name	Type
location_type	string
icon	string
name	string
description	string
lat	string
long	string
address	string

GetSensorTypesResp

Kind: global typedef
Properties

Name	Type
item_id	string
name	string
description	string
icon	string

GetSensorsResp

Kind: global typedef
Properties

Name	Type	Description
allow_certificate_auth	boolean
allow_key_auth	boolean
battery_level	number
certificate	string
created_date	number	Epoch format
description	string
device_key	string
edge_id	string
enabled	boolean
has_keys	boolean
last_active_date	number	Epoch format
name	string
reading_time	string	ISO 8601 format
sensor_label	string
sensor_reading	string
sensor_type_id	string
signal_strength	number
state	string
system_key	string
type	string

SensorMessage

Kind: global typedef
Properties

Name	Type	Description
batteryLevel	string
dataValue	string	Sensor reading to be processed
sensorID	string	Name of sensor from Devices table
signalStrength	string
messageDate	string	Stringified ISO 8601 date

SensorPayload

Kind: global typedef
Properties

Name	Type	Description
edge_id	string	Name of edge
sensor_message	SensorMessage

UpdateAlertReq

Kind: global typedef
Properties

Name	Type	Description
[is_active]	boolean
[type_id]	string
[configuration_id]	string
[sent_date]	string
[acknowledge_date]	string
[target_users]	Array.<string>	Array of users to be contacted when alert is violated

UpdateAlertResp

Kind: global typedef
Properties

Name	Type
count	number

UpdateAlertConfigReq

Kind: global typedef
Properties

Name	Type	Description
[name]	boolean
[type_id]	string
[rules]	Array.<Rule>	Rules to indicated when alert has been violated
[contacts]	Array.<string>	Employees to contact on violation
[message]	string
[priority]	string	"High", "medium", or "low" to indicate which types of messages to send
[disabled]	Array.<string>

UpdateAlertConfigResp

Kind: global typedef
Properties

Name	Type
count	number

UpdateEmployeeReq

Kind: global typedef
Properties

Name	Type	Description
[first_name]	boolean
[last_name]	string
[locations]	Array.<string>	Array of location ids from Locations collection
[phone_number]	Array.<string>
[photo]	string
[pin]	string

UpdateLocationReq

Kind: global typedef
Properties

Name	Type
[name]	string
[location_type]	string
[icon]	string
[description]	string
[address]	string
[lat]	string
[long]	string

UpdateLocationResp

Kind: global typedef
Properties

Name	Type
count	number

UpdateSensorReq

Kind: global typedef
Properties

Name	Type	Description
[enabled]	boolean
[description]	string
[edge_id]	string	Name of sensor's edge
[sensor_reading]	string	Most recent reading from sensor
[battery_level]	number
[signal_strength]	number
[reading_time]	string	ISO 8601 format
[sensor_type_id]	string	Id of sensor type from SensorTypes collection
[sensor_label]	string	Readable label of sensor to be displayed in portal

UpdateSensorResp

Kind: global typedef
Properties

Name	Type	Description
allow_certificate_auth	boolean
allow_key_auth	boolean
created_date	number	Epoch format
device_key	string
edge_id	string
enabled	boolean
last_active_date	number	Epoch format
name	string
reading_time	string	ISO 8601 format
sensor_label	string
sensor_type_id	string
state	string
system_key	string
type	string

UpdateSensorTypeReq

Kind: global typedef

Param	Type	Description
[name]	string
[description]	string
[data_type]	string	Data type of sensor's data value
[attributes]	string	Special character corresponding to data value provided
[icon]	string
[isProbe]	boolean	Whether or not sensor is a probe

UpdateSensorTypeResp

Kind: global typedef
Properties

Name	Type
count	number