Mango M2M concepts

Below is a general overview of how this application works, and design concepts that users should know. Helpful details can be found throughout the application using contextual help, indicated by the help icon (). Click on this icon wherever it appears to get more information on the feature you are using.

Application overview

Functionality in this application is primarily accessed using the controls in the header. Depending on the permissions granted to your user account, you will see various icons underneath the application logo. When you hover over these icons with your mouse, you will see an overlay message with a short description of what the icon is for.

Beside the header controls at the right-hand side of the header is the username of the user who is currently logged in.

When your application has an active alarm, you will see a flashing flag icon () and an associated description near the center of the header area. The colour of the icon will indicate the severity of the alarm:

• Information
• Urgent
• Critical
• Life safety

You can click on the icon or the description to go to the list of active alarms.

Data types

There are five supported data types:

• Binary (aka boolean) values have only two states, referred to in the system as the zero value and the one value. You can use a text renderer to convert the display of binary values to whatever alternate labels you need, such as "on/off", "high/low", "started/stopped", etc.
• Multistate values have multiple distinct states. (Strictly speaking, the binary type is a special case of a multistate.) Values are primitively represented as integers (e.g. 0, 1, 2, 7, ...), but, like binary values, you can use a text renderer to convert these values to appropriate text representations such as "on/off/disabled", "cool/heat/off", or anything else.
• Numeric (aka analog) values are decimal values represented in the system with a floating point variable. Temperature, humidity, price, and altitude are examples of numeric values. Text renderers can be used to determine display features like how many decimals places to display, whether to separate thousands (with commas or dots), and whether a suffix should be displayed (e.g. °F, kW/h, moles, etc). Range renderers can be used to convert ranges of numeric values into text labels.
• Alphanumeric values are simply strings of characters, such as the O/S description of an SNMP source.
• Image values are binary representations of image data. They are stored in files on the host file system (i.e. not in the database) and are cached in memory as necessary for performance purposes. Renderers can be used to create scaled images - such as thumbnails - for presentation.

Data sources

Data sources are fundamental to the operation of this application. A data source is a "place" from which data is received. Virtually anything can be a data source, insofar as the communications protocol is supported by the application. Here are some examples:

• If you have a Modbus network accessible via RS232, RS485, TCP/IP, or UDP/IP, you can create a Modbus data source that will poll the network for data on an interval you can define.
• If you have equipment or an application that can send data over HTTP you can start an HTTP receiver data source that will listen for incoming connections and route the data to the appropriate points.
• For hardware that supports SNMP, start an SNMP data source. Values can be polled on an interval schedule, or traps can be received for report-on-exception.
• Data can be read and updated in a SQL data base external to the system.
• Data can be generated either randomly or predictively using a Virtual data source.

Data values that are received or collected by a data source are stored within data points.

Data points

A data point is a collection of associated historical values. For example, a particular point might be a temperature reading from a room, while another point could be the humidity reading from the same room. Points can also be control values, such as a switch to turn a piece of equipment on or off.

There are many attributes that are used to control the behaviour of points. Primarily, there is the concept of a point locator. Locators are used by data source to determine how to "find" the data for the particular point. For instance, a SQL data source has attributes including where to find the database instance; point locators for the data source indicate the table and field names with which to find specific values. The logical separation of data source and data point attributes depends on the communication protocol in question.

Data points attributes also determine many other aspects of the point, such as its name, how it should be logged (all data, changes in value only, or not at all), how long to keep logged data, how to format values for display, and how to chart values.

You can also configure data points with event detectors, which are used to detect conditions of interest in the point's values (eg. value has been too high for too long, is too low, changes too often, doesn't change at all, etc).

Points can be arranged into a hierarchy, or tree, to simplify management and display by using the Point Hierarchy functionality.

Monitoring

Monitoring of points within the system can be done in two ways. You can use the watch list to dynamically create tabular lists of points including their values, last update times, and charts of historical information (if the point is configured to support this). Values and charts are updated in real time without having to refresh your browser window. Charts of multiple points can also be displayed on demand.

You can also create graphical views of points using drag and drop functionality to position graphical representations of points on an arbitrary background image. Animated images can be used to create highly dynamic visualization of system behaviour, and, like the watch lists, values are updated in real time without a browser refresh. These views can subsequently be marked as "public", so that they can be reused on public web sites.

Control

Control of external systems can also be acheived for points that can be set (aka writable or output). A settable point can be set to a user-defined value, such as a thermostat setting or equipment control switch. Both watch lists and graphical views provide simple means by which to input a value to set. The point locator for the settable point determines how the data source sets the value within the external equipment.

Events

An event is the occurance of a defined condition within the system. Both system-defined and user-defined events are available. System-defined events include data source operation errors, user logins, and system startup/shutdown. User-defined events include point event detectors (see "event detectors" above), scheduled events, and compound events which detect conditions over multiple points using logical statements. There are also "audit events", which are raised when users make changes (additions, modifications, deletions) to runtime-affecting objects including data sources, data points, point event detectors, scheduled events, compound event detectors, and event handlers.

Once an event has been detected, it is acted upon by handlers. An event handler is a user-defined behaviour that is to be performed upon the raising of a particular event, such as sending an email or setting the value of a settable point.

Application icons

• Data source
• Data point
• Chart
• Set point
• Watch list
• Graphical view
• Refresh
• Event detector
• Compound detector
• Scheduled event
• Event handler
• Alarm
• User
• User comment
• Report
• Mailing list
• Publisher
• Warning
• Logout

Alarm sounds

Mango can play sounds when alarms are active. By default, alarm sounds are played for urgent, critical, and life safety alarms (i.e. not for information alarms), but sounds for each alarm type can be controlled individually. To enable particular alarm sounds, valid mp3 files must exist at the following locations:

• <mango_home>/audio/information.mp3
• <mango_home>/audio/urgent.mp3
• <mango_home>/audio/critical.mp3
• <mango_home>/audio/lifesafety.mp3

To disable a sound, remove the associated sound file. A library of sounds can be found in the <mango_home>/audio/lib folder.

Graphics

Mango ships with a small graphics library which can be found in the <mango_home>/graphics folder. Each sub-folder represents an image set. The contents of the sub-folder include all of the images in the image set, as well as an optional properties file called info.txt. (Examples can be found in the graphics directories that ship with Mango.) This property file contains name/value pairs with the following names (all of which are optional):

• name: The name that will be used to describe the image set in the user interface. If not provided this will default to the folder name.
• width: The width of the images. (All images are expected to be the same size.) If not provided the width of the first image will be used.
• height: The height of the images. (All images are expected to be the same size.) If not provided the height of the first image will be used.
• text.x: The position of text relative to the left edge of the image, in pixels. If not provided this defaults to 5.
• text.y: The position of text relative to the top edge of the image, in pixels. If not provided this defaults to 5.

Once you are using an image set in your views do not rename its folder! The folder name is used internally as the identifier of the image set.

Image files are sorted alphabetically by name. Names are case sensitive. Name/value pairs are separated with '='. Lines beginning with '#' are considered comments. 'Thumbs.db' files are ignored. Archive files (zip, gz, tar, etc) cannot be used since the images files have to be accessible to the web server. Image sets are loaded upon system startup, so any changes require a restart.

To have future versions of Mango ship with your preferred graphics, please contribute them to Serotonin Software. Please support open source software.

Remote views

Public mango views can be accessed from other web sites by simply putting an iframe into your pages. For example, the Mango home page uses the following code to display a small thermostat view:

<div style="position:relative;width:80px;height:150px">
<iframe frameBorder="0" style="position:absolute;width:450px;height:300px" scrolling="no" allowTransparency="true"
        src="http://mango.serotoninsoftware.com/test/public_view.htm?viewId=3"></iframe>
</div>

Absolute positioning and transparency is used to allow the display of charts and component controls without scrolling or HTML adjustment, but is optional. The 'viewId' parameter is the internally generated id of the view to be displayed, but can be substituted with the 'viewName' parameter and the view's name as the value. (However, do not subsequently alter the name of the view without updating this reference.)