Win32::AmbientOrb

This page describes a Perl module I wrote to support a serial-port controlled Ambient Orb. See the Original Post for details.

If you just want to get the package, you can download it directly or grab a PPD.

Manipulate an Ambient Orb through a serial port

• NAME
• SYNOPSIS
• EXAMPLE
• DESCRIPTION
• EXPORTED HASHES
• METHODS
• AUTHOR

NAME

Win32::AmbientOrb – Manipulate an Ambient Orb through a serial port

SYNOPSIS

  use Win32::AmbientOrb;

EXAMPLE

  use Win32::AmbientOrb qw(:ALL);

  my $port = "COM1:";
  Win32::AmbientOrb::Port($port); #set port to COM1
  InitializePort();               #set serial port settings
  PagerIgnore(1);                 #don't listen to the pager network

  # go straight to red
  my @red = (176, 0, 0);
  DirectColor(\@red);

  # quick transition from blue to red
  my @blue = (0, 0, 176);
  TransitionColor(\@blue, \@red, 20, 5);

  # slow transition from red to blue
  TransitionColor(\@red, \@blue, 50, 100);

  # clean up
  CloseOrb();

DESCRIPTION

The Win32::AmbientOrb module lets you manipulate an Ambient Orb connected to a Win32 machine through a serial port.

It uses Win32::SerialPort for serial port communication.

EXPORTED HASHES

Two hashes are exported by default, %OrbColor and %OrbRGB.

%OrbColor

Maps from color names to Color IDs useful for ColorAnim( ). Available color names are:

 • Red          => 0
 • LightRed     => 1
 • DarkOrange   => 2
 • Orange       => 3
 • LightOrange  => 4
 • DarkYellow   => 5
 • Yellow       => 6
 • LimeGreen    => 7
 • PaleGreen    => 8
 • GreenMinus3  => 9
 • GreenMinus2  => 10
 • GreenMinus1  => 11
 • Green        => 12
 • GreenPlus1   => 13
 • GreenPlus2   => 14
 • PaleAqua     => 15
 • Aqua         => 16
 • DarkAqua     => 17
 • Cyan         => 18
 • DarkCyan     => 19
 • LightBlue    => 20
 • SkyBlue      => 21
 • BlueMinus2   => 22
 • BlueMinus1   => 23
 • Blue         => 24
 • DeepBlue     => 25
 • VeryDeepBlue => 26
 • Violet       => 27
 • Purple       => 28
 • LightPurple  => 29
 • Magenta      => 30
 • MagentaPlus1 => 31
 • MagentaPlus2 => 32
 • MagentaPlus3 => 33
 • MagentaPlus4 => 34
 • MagentaPlus5 => 35
 • White        => 36

%OrbRGB

Contains the mapping of color ids to RGB arrays useful for DirectColor( ).

METHODS

Port( [$port] )

Sets or returns the port that the Ambient Orb is connected to. Default is COM1:

InitializePort( )

Initializes the serial port for communication with the Ambient Orb. Settings are:

 • BAUD: 19200
 • PARITY: N
 • DATA: 8
 • STOP: 1

ClosePort( )

Cleans up the port object.

ColorAnim( [$color], [$animation] )

Changes the color of the Orb using the default color and animation settings. Colors are listed above in %OrbColor Animations are 0-9

        ANIMATION
 • 0 almost imperceptibly slow
        ...
 • 7 very fast
 • 8 crescendo effect
 • 9 heartbeat effect

DirectColor( \@rgb )

Sets the orb instantly to the color specified in the 3-element array @rgb. Red, green and blue values should be between 0 and 176.

TransitionColor( \@rgb0, \@rgb1, $steps, $wait )

Performs a slow transition from the color in @rgb0 to the one in @rgb1. Sets the orb instantly to the color specified in the 3-element array @rgb0, then sends $steps updates, one update every $wait milliseconds until it reaches the color specified in @rgb1. Red, green and blue values should be between 0 and 176.

PagerIgnore( $ignore )

Instructs the orb not to listen to the pager network. If you don’t call this, the orb will keep changing its color to reflect whatever channel it was listening to before you plugged in the serial port.

AUTHOR

Andy Allen

Orb Walkthrough

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::AmbientOrb
  ppm 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).

Installing Perl and Packages

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   ###########################
 3   # installOrbService.pl
 4   ###########################
 5   use Win32::Daemon;
 6   my $svcName = 'AmbientBuild';
 7   %Hash = (
 8       name    =>  $svcName,
 9       display =>  $svcName,
 10      description => 'Ambient Build Monitor',
 11      path    =>  'c:\\perl\\bin\\perl.exe',
 12      user    =>  '',
 13      pwd     =>  '',
 14      parameters =>'c:\\Progra~1\\AmbientOrb\\orbService.pl',
 15  );
 16
 17  my $action = $ARGV[0];
 18  if (lc($action) eq '-i') {
 19      if( Win32::Daemon::CreateService( \%Hash ) ) {
 20          print "Successfully added.\n";
 21      }
 22      else {
 23          print "Failed to add service: ",
 24           Win32::FormatMessage(Win32::Daemon::GetLastError()),
 25           "\n";
 26      }
 27  }
 28  elsif (lc($action) eq '-u') {
 29      if( Win32::Daemon::DeleteService( "", $svcName ) ) {
 30          print "Successfully removed.\n";
 31      }
 32      else {
 33          print "Failed to remove service: ",
 34           Win32::FormatMessage(Win32::Daemon::GetLastError()),
 35           "\n";
 36      }
 37  }
 38  else {
 39      print "Unknown action ",
 40      "(use -i for install, -u for uninstall).\n";
 41  }

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.

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.

Ambient Orb Setup

This page describes the process of hooking an Ambient Orb up to show a real-time information using the Ambient Hardware Developer’s Kit.

Previous Work

The Orb provides a great, at-a-glance indication of build status for a continuously integrated software project. The subjects of Continuous Integration and its benefits are discussed in a number of other places, so I won’t cover them here. Likewise, the use of an Orb using the Ambient Web API is covered admirably by Michael Swanson, so you can read that there.

Problems

The two problems I found were:

1. Update lag

   The Ambient pager network does not change the color of an orb for 10 – 30 minutes. I can break a build in seconds. An ideal system would indicate the status of software builds in real time with no lag.

2. Integration of multiple software projects

   I work in a shop that produces a lot of different projects at a time. We currently have eleven builds managed by CruiseControl.NET. Using NAnt events as described elsewhere did not provide an easy way to measure how many builds were successful moment-by-moment.

Solution

Lucky for me, the first problem can be solved with hardware. As a software guy, I love when that happens. Ambient produces a Hardware Developer’s Kit. You put an Orb on one end and a serial port on the other, and you’re in business: you can update the orb instantly to any color you like.

Unfortunately, the cable is only 3 feet long, making the orb’s location a bit constrained. This was easily solved with a cheap 50-foot serial cable. As a bonus, the $45 (with shipping) HDK frees me from the $80/year subscription to Ambient’s developer channel, so the hardware investment will pay for itself within the first year.

To have the Orb reflect the status of multiple software projects all at once, I polled the CruiseControl.NET server. For now, I’m using a screen scrape of the CruiseControl dashboard. With a little gumption, I could probably poll the same port that CCTray uses.

Keeping in mind that I might not always use CruiseControl as my CI solution, and that I might change the way I poll it for build status, I thought it would be nice to keep those changes insulated from the core orb updating service.

I’m a native speaker of Perl, so that’s the language all of this is in. I used Win32::Daemon by Dave Roth to create a Windows service in Perl. The service talks on the serial port using Bill Birthisel’s Win32::SerialPort package and updates the colors using my Win32::AmbientOrb package.

How to Do It Yourself

This Walkthrough describes how to set up the whole system.