Manual:Modules/User Module Engine

From MSure

Jump to: navigation, search

The purpose of this module is to extend the usage area of MSure by allowing users to write their own modules while still keeping things relatively simple.

'Simple' means that basic programming skills are required if you want to write your own user module.

A user module ('UM' for short) is written in C# and is run inside the User Module Engine ('UME' for short). A subset of the messages/events in MSure are passed to these UMs which in turn execute a specific action. A UM may also send certain predefined messages back to MSure to request certain actions to be performed by other modules.

MSure does not enforce any limitations on what an UM can do. The UM will run as the same user (Local System) as MSure and as such the same security restrictions apply.

Before you can use any UMs, the User Module Engine must be configured. Below is the minimum configuration required. 

<?xml version="1.0" encoding="utf-8"?>
<ModuleConfig xmlns:xi="http://www.w3.org/2001/XInclude" xml:base=".">
   <CoreConfig>
      <Alias>UserModuleEngine</Alias>
      <ClassName>UserModuleEngine</ClassName>
   </CoreConfig>
   <UserModuleEngine>
      <ReferencedAssemblies>
         <Assembly>System.dll</Assembly>
         <Assembly>System.Xml.dll</Assembly>
         <Assembly>System.Core.Dll</Assembly>
         <Assembly>System.Xml.Linq.dll</Assembly>
      </ReferencedAssemblies>
   </UserModuleEngine>
</ModuleConfig>

At start-up, the UME will look for .cs-files in the folder <installation path>\UserModules. During installation a file named UserModule.cs will be placed in this directory. This file contains the base class for all UMs and the UME will only accept UMs that inherit from this class. Note that this file is not included when the UMs are compiled, it is only there as a reference for UM-developers.

During compilation, the UME needs a list of reference assemblies (.dll-files), i.e. a list of files with existing functionality. This is what the ReferencedAssemblies and each Assembly element are for. At least one assembly must be specified and this is usually System.dll, which contains the most basic features required by any C#-code. There is no need to specify assemblies that ships with MSure; these are included automatically.

If any errors are encountered during the compilation, a log file will be written in the <installation path>\UserModules folder. It will tell you what is wrong.

Contents

Writing your own User Modules

Writing a UM will require more or less programming skills depending on what you want to do; but even the most simple UM requires some knowledge of C# programming.

However, the design of the EMU has been tailored to make writing UMs as easy as possible, while keeping all possibilities open, so it is fairly easy even for a novice to get started. (It is safe to say that it is harder to find all the existing functionality in the .NET framework than to write a UM!)

The most basic UM consists of a single class that inherits from the existing UserModule class (source: <installation path>\UserModules\UserModule.cs). The UserModule class implements default methods for all UM-supported events and by overriding these, the UM can implement specific functionality.

In the <installation path>\UserModules\Examples folder, some simpler and some more advanced User Module examples exists. Depending on your system configuration, these may or may not work without modification.

Please note that any unhandled exceptions in a UM will cause MSure to quit unexpectedly, with a message in the Windows event log similar to

.NET Runtime version : 2.0.50727.3053 - Application ErrorApplication has generated an exception that could not be handled.

It is therefore imperative that you encapsulate all code that may throw an exception within 
try {} catch(Exception ex) {}
clauses. 
Unhandled exceptions are logged to a file named Exception.log in MSure's installation directory before the application terminates.

User Module Utilities

A User Module Utility, or UMU for short, is a utility class with a specific purpose. To access the UMUs you need to include the following code at the top of you UM source file: 

using Com.Pmalmberg.MSure.Modules.UserModules.Utility;

UMUMail

UMUMail is used to send e-mails through an SMTP server.

Example code: 

UMUMail mail = new UMUMail( this, "server.com", 2525 );
mail.SetCredentials( "user", "password" );
mail.Send( "from@server.com", "to@server.com", "This is the subject", "This is the message body" );

An example User Module for sending mail is shipped with MSure, see the file Mail.cs in the examples folder.

UMUTellstick

UMUTellstick is used to control devices through a Tellstick device. See Manual:Utilities/Tellstick Global Storage for how to configure your system to allow MSure to use the Tellstick.

Example code: 

UMUTellstick stick = new UMUTellstick( this );
UMUTellstick.Device myWallsocketSwitch = stick.GetDevice( "Office wallsocket" );
myWallsocketSwitch.On();

An example User Module for UMUTellstick exists, and is named TellstickControlledByTemperature.cs 

Note: The Tellstick driver currently only supports 32-bit OS.

Note: The Tellstick driver, including the current 2.0 version has memory leak issues and your
system will eventually run out of memory. Telldus has been notified of this and when a new driver
is available, MSure will be updated to use that one.

UMUSunTime

The UMUSunTime class can be used to determine the time of sunrise and sunset for a specific location, using the computer's current time zone. 

UMUSunTime sun = new UMUSunTime( this, 59.540636772839086, 18.08421384626598, 1 );
LogInfo( "Sunset: " + sun.Sunset );
LogInfo( "Sunrise: " + sun.Sunrise );

The UMUSunTime class constructor takes four arguments:

  • First: Reference to the parent User Module
  • Second: Global position latitude in degrees. Latitude is positive for North and negative for South.
  • Third: Global position longitude in degrees. Longitude is positive for East and negative for West.
  • Fourth: The local UTC offset (f.e. +1 for Brussel, Kopenhagen, Madrid, Paris).

A usage example is available in the TellstickControlledBySuntime.cs file.

Existing User Module Examples

CDTrayTemperature

This User Module is a simple example of how to open/close the CD-tray when a temperature reaches/falls to a certain temperature.

DisplayingTemperatures

This user Module is a simple example of how to display temperatures on a LCD-display connected to the 1-Wire network and also how to use the switches on the Swarts-LCD device.

FTPGraphs

This user module can transfer generated graphs to a remote FTP server. It can operate in two modes:

  • Batch mode, where multiple graph files are sent at a specified interval
  • Immediate mode, where each graph file is sent as soon as it has been generated

LCDExample

Another example to display texts on a LCD-display.

Mail

A simple example on how to send a mail in response to a temperature event.

UMRSSFeed

UMRSSFeed is used to create a RSS feed of the data logged by MSure.

To make this work a change has to be made in the RSSFeed.cs file.

Find the following: 

// Where shall the file be written?
private const string file = @"C:\program files\Apache Software Foundation\Apache2.2\htdocs\rss.xml";

and change C:\program files\Apache Software Foundation\Apache2.2\htdocs\rss.xml to your location.

Temperatur.nu Reporter

This User Module is used to report the current temperature to Temperatur.nu, a site that gathers temperatures from all over Sweden.

To use this User Module, you must first register with the Temperatur.nu site to obtain a location and id-number. Once you have them, you need to update the following lines in the TemperaturNuReporter.cs file so that they match your configuration. 

//////////////////////////////////////////////////////////
// These are the only settings that you should change
//////////////////////////////////////////////////////////
 
// Set this to the name of your location
 
string locationId = "yourLocationId";
 
// Set this to the id given to you by Temperatur.nu
string reportId = "0";
 
// Set these to the labels of your temperature sensors
// In case you want to use the lowest value of two or more sensors,
// use specify multiple labels like this:
//  { "sensorLabel", sensorLabel2, sensorLabel3 }
private string[] sensorLabel = new string[] { "sensorLabel" };
 
//////////////////////////////////////////////////////////
// End user settings
//////////////////////////////////////////////////////////

Image:i.gif The following section has to be added in your configuration under section <ReferencedAssemblies>: 

<Assembly>System.Web.dll</Assembly>

SimpleBeepingExample

A simple example on how to trigger an audio signal based on an event.

SwitchExample

A simple example on how to set the states of 1-Wire switches.

TellstickControlledByTemperature

Shows how to control a device through a Tellstick based on a temperature reading from a 1-Wire device.

Visual C# 2008 solution

A Visual C# 2008 solution is shipped with MSure. You can find this in the <installation path>\UserModuleProject folder. Opening the file UMRunner.sln using Visual C# Express (free development tool from Microsoft) you can build your own User Modules. You then have the entire power of the .NET framework, in addition to the utilities provided by MSure, at your finger tips.

The solution provides the means to run and debug your user modules as if they were running within the User Module Engine on your target machine.

Please read the comments and instructions in the source!

Retrieved from "http://www.msure.se/wiki/index.php5?title=Manual:Modules/User_Module_Engine"
Personal tools