UnimotionPlugin - Apple Mac OS X Dashboard widget plugin to read sudden motion sensors


UnimotionPlugin is an Apple Mac OS X Dashboard widget plugin for reading the sudden motion sensors found on Macbook Pros, Macbooks, Powerbooks and iBooks. It is based on the excellent Unimotion C library by Lincoln Ramsay, hosted at unimotion.sourceforge.net

UnimotionPlugin allows you to read data from the Sudden Motion Sensor found it Apple Mac laptops. This sensor can measure the orientation and movement of your laptop. Dashboard widget developers are now easily able to read the SMS data via javascript to build widgets that have an awareness of an Apple laptops orientation and movement.


The latest compiled universal binary download of this bundle is available at

Building from source

The project is hosted on Github github.com/matth/UnimotionPlugin To build from source you will need Xcode installed.

  1. Clone the git repo
         git clone git://github.com/matth/UnimotionPlugin.git
  2. Open the Xcode project and build
         open plugin/UnimotionPlugin/UnimotionPlugin.xcodeproj
  3. If you have rake installed then a Rakefile has been setup to aid compilation.
         rake build_plugin # Builds the UnimotionPlugin.bundle
         rake build_wdgt   # Builds the example Seismometer widget

Example Widget: Seismometer

The example application is an imitation seismometer, it plots movement on the X, Y and Z axis using data from the Unimotion plugin. This is demonstrates a simple use of the plugin, it could also be used to control games, sounds, etc.


Follow these instructions to use the widget plugin within your own dashboard widgets.

  1. Firstly copy the directory UnimotionPlugin.bundle into your widget’s root directory.
  2. Once in place you must reference this in your widget’s Info.plist file so it gets loaded in correctly.
  3. Add the following keys to your Info.plist:
  4. The plugin should now be loaded into your widget, the following statement should return true.
         if (typeof UnimotionPlugin != 'undefined')

You can now use the plugin’s API from your javascript code

The Javascript API


This will return an integer representing the sudden motion sensor hardware found.

        Return values :

        0 = No hardware found
        1 = Powerbook
        2 = iBook
        3 = High Res. Powerbook
        4 = Macbook / Macbook Pro


This will refresh the readings from the sudden motion sensor


Returns a floating point number representing the last reading from the X axis


Returns a floating point number representing the last reading from the Y axis


Returns a floating point number representing the last reading from the Z axis

Developing your widget in a browser

It’s often preferable to develop your widget in the browser, in this situation the plugin shall not be available. The below code set’s up a ‘mock’ representation of the plugin so you can continue development in the browser.

        // For browser testing, where UnimotionPlugin doesn't exist
        if (typeof widget == 'undefined') {

          var UnimotionPlugin = function() {

                function randomNum() {
                  var num = Math.random();
                  if (Math.random() > 0.5) {
                    num = num * -1;
                  return num;

                return {
                  'refreshData' : function() {},
                  'readX' : randomNum,
                  'readY' : randomNum,
                  'readZ' : randomNum,
                  'detectSms' : function() {
                    return 4; // Hardware you want to represent



UnimotionPlugin License


Copyright (C) 2009 Matt Haynes

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see www.gnu.org/licenses/

Unimotion C libraries License

Please see plugin/UnimotionPlugin/unimotion/LGPL.txt

Fork me on Github