This page goes through how to set up your serial-controlled orb. The sections are: What You Will Need Connecting the Hardware Installing Perl and Required Packages Creating a Color Script Installing the Service Web-Connected Orbs Other Uses For the Orb

You Will Need:

HARDWARE

A Windows XP or 2003 Server host
An Ambient Orb (or several)
A Hardware Developer's Kit from Ambient (one per orb)
Long enough serial cables to put the orb where you want.

SOFTWARE

Perl (I used ActiveState). I've included ppm commands below.
Aldo Calpini's Win32::API package ppm install Win32-API
Dave Roth's Win32::Daemon package ppm install http://roth.net/perl/packages/Win32-Daemon.ppd
Bill Birthisel's Win32::SerialPort package I didn't use a ppd, I installed it the old-fashioned way (as described in the README, but you could try finding a ppd with a Google search
Win32::AmbientOrbppm install http://powerfulmojo.com/tools/ppm/Win32-AmbientOrb.ppd
The service files in AmbientOrbService.zip

Connecting the Hardware

Plug the serial exension cable (if you're using one) into your serial port.
Plug the HDK into the serial extension cable
Plug the Orb into the HDK.
Plug the Power adapter (supplied with the Orb) into the HDK.

The orb will go through its regular power-up routine, then start displaying the DJIA channel (or whatever it was most recently tracking).

Install Perl and get all of the packages above installed in the order listed. If you use the ppm commands provided, it will link the modules' documentation right into your html documentation so you can see how to use everything. You will only be using Win32::AmbientOrb directly. It depends on Win32::SerialPort (which depends on Win32::API), and we will need Win32::Daemon to get it up and running as a service.

Creating a color script

The service will need a script to tell it what color to turn the orb. A color script can be written in just about any language, it just has to print an integer to the console representing the correct color. Possible colors are:

0	Red	24	Blue
3	Orange	27	Violet
6	Yellow	30	Magenta
12	Green	35	Red-Magenta
18	Cyan	36	White

You can use any integer between 0 and 36. The ones I didn't list work out about like you'd expect (i.e. 9 is yellowish-green). My color script is in Perl and is available below. A blue orb means all builds are successful, a red orb means at least one build is failed, and a yellow orb means the CruiseControl server was unreachable.

Here is an example of a (very simple) batch file color script:

@echo 24

It's not very interesting, because it just returns the code for "blue." The default script looks like this:

 1   #!perl
 2   use strict;
 3   use LWP::Simple;
 4
 5   my $color = getColor();
 6   print $color;
 7
 8   sub getColor {
 9       my $color = 6;
 10      for (my $retry = 0; $retry < 3; $retry++) {
 11          if ($color == 6) {
 12              sleep 1 if ($retry > 0);
 13              $color = getColorRequest();
 14          }
 15      }
 16      return $color;
 17  }
 18
 19  sub getColorRequest  {
 20      my $color;
 21      my $dashboard = get('http://cchost/ccnet');
 22      if ($dashboard) {
 23          if ($dashboard =~ />Fail/) { $color = 0; }
 24          else { $color = 24; }
 25      }
 26      else {
 27          $color = 6;
 28      }
 29      return $color;
 30  }

It is a little more interesting: it makes a request to a server named cchost and searches the response for the word "Fail." If it finds it, at least one build is failed and the orb should be red. If no builds are failed, the orb should be blue. In the event that the server is unavailable, it will retry the request twice more, but if it still can't reach cchost it will turn the orb yellow.

Installing the Service

Now that the orb is hooked up and you've got your color script written, here's how to install the service to make it go.

Put the files in place

Create a folder named C:\Program Files\AmbientOrb and copy everything in this .zip into it: AmbientOrbService.zip. Put your color script in the same folder.

Install the Service

You will need the script installOrbService.pl (or one like it) to install the AmbientBuild Windows Service on your host.

 1   #!perl
 2   use strict;
 3   use LWP::Simple;
 4
 5   my $color = getColor();
 6   print $color;
 7
 8   sub getColor {
 9       my $color = 6;
 10      for (my $retry = 0; $retry < 3; $retry++) {
 11          if ($color == 6) {
 12              sleep 1 if ($retry > 0);
 13              $color = getColorRequest();
 14          }
 15      }
 16      return $color;
 17  }
 18
 19  sub getColorRequest  {
 20      my $color;
 21      my $dashboard = get('http://cchost/ccnet');
 22      if ($dashboard) {
 23          if ($dashboard =~ />Fail/) { $color = 0; }
 24          else { $color = 24; }
 25      }
 26      else {
 27          $color = 6;
 28      }
 29      return $color;
 30  }

You only need to run this script once to install the service. It takes one argument: -i for install or -u for uninstall, then prints a short status message indicating whether the action was successful.

Line 14 points to the script that will be started when the Windows Service starts. That's our orbService.pl script. If you write your own Windows Service, you would put its pathname here, using the short pathname (with no spaces). If you fill out a username and password in lines 12-13, the script will run as that account. If you leave it blank, it will run as System.

Note that line 14 should contain the orbService.pl script as written, not your color script.

Configure the Service

The service looks for a file named orbService.config, which can have any of the following values. If a value is not specified, it will use the default listed.

KEY

Default Value

Description

colorScript

C:\Program Files\AmbientOrb\ccnetWeb.pl

prints orb color code to STDOUT

webOrbs

[n/a]

serial #s of other orbs, comma-separated, no trailing comma

port

COM1

serial port to use

logFile

C:\Program Files\AmbientOrb\orb.log

verbosity

1

0 = silent, ..., 3 = garrulous

maxLogLines

10000

maximum lines to leave in log file

pollingInterval

30000

wait between updating the orb (ms)

sleepTime

2000

between processing service messages (ms)

waitForStop

20000

how long to expect service stop to take (ms)

errorColor

0

color to use on colorScript error (0-36)

errorAnim

5

animation on colorScript error (0-9)

While the service is running, changes to this configuration file will be automatically loaded the next time the script checks its messages (within 2 seconds by default). If you leave the service configured as shown, it will run the ccnetWeb.pl script every 30 seconds.

Web Orbs

In my environment, we have three orbs and only two HDKs. The service is installed on both hosts with HDKs attached, but that leaves one orb out of the loop. To update it, one of the servers is also configured to update the orb using its webOrbs configuration parameter. This orb is updated using Ambient's Web Developer API.

Other uses

This service was written to make it easy to monitor anything using an Ambient Orb. With a different color script and polling interval, you could make it monitor just about anything. During testing I had it monitor hockey scores, crude oil prices, and network traffic (not all at the same time). If you do something like that, I'd like to hear about it, so please let me know.

#!perl
###########################
# installOrbService.pl
###########################
use Win32::Daemon;
my $svcName = 'AmbientBuild';
%Hash = (
    name    =>  $svcName,
    display =>  $svcName,
    description => 'Ambient Build Monitor',
    path    =>  'c:\\perl\\bin\\perl.exe',
    user    =>  '',
    pwd     =>  '',
    parameters =>'c:\\Progra~1\\AmbientOrb\\orbService.pl',
);

my $action = $ARGV[0];
if (lc($action) eq '-i') {
    if( Win32::Daemon::CreateService( \%Hash ) ) {
        print "Successfully added.\n";
    }
    else {
        print "Failed to add service: ",
         Win32::FormatMessage(Win32::Daemon::GetLastError()),
         "\n";
    }
}
elsif (lc($action) eq '-u') {
    if( Win32::Daemon::DeleteService( "", $svcName ) ) {
        print "Successfully removed.\n";
    }
    else {
        print "Failed to remove service: ",
         Win32::FormatMessage(Win32::Daemon::GetLastError()),
         "\n";
    }
}
else {
    print "Unknown action ",
    "(use -i for install, -u for uninstall).\n";
}