Notes from Sand Hill


XTension Tech Notes

Sandhill Crane

Subject: Scripting ADB I/O analog inputs to the XTension database.
Applicability:All versions of XTension after 1.0
Contributor:Michael Ferguson

Sampling and processing values of analog channels of the ADB I/O
with XTension and AppleScript.

The ADB I/O from the Beehive fits neatly on the Apple Desktop Bus of any MacSE and all models after. It provides the ability of controlling and monitoring switches, etc, which are not X-10 compatible, and at 'sample rates' which far exceed what is possible with X-10.

Although there is much more to say about the ADB I/O, for the purpose of this technote, we're going to look only at the four 'ports' which are 'analog' inputs. Each of these 'ports' is connected to some external sensor which measures something like temperature or humidity etc.


Sampling of the channels can be accomplished from within XTension by setting up a scheduled event which periodically executes a script which reads the values directly from the ADB I/O.

If however you need to sample the values more often than once per minute, you could create a situation where XTension is overly bothered with the sampling to serve other devices and the human interface.

By creating and launching an autonomous 'applet' in parallel with XTension, you can have it do the continuous sampling and only pass significant changes to XTension. Thus XTension will not be quite as bothered, and channels can easily be sampled at a rate of 5 to 10 samples per second.

Although the following example shows the latter approach, the code within the 'applet' could be just a script which is scheduled to execute periodically.

The physical setup and technical description of the ADB I/O and analog measurements are discussed in another technote. This note will focus on the interaction between a AppleScript 'applet', the ADB I/O, and XTension.

In every application, the data from the analog sensor is in raw form. It must be 'translated' into degrees before it can be displayed in a meaningful form to a human.

This example performs simple scaling with the line/slope formula :
(y = mx + b) or the processed data = raw data * scaling factor + offset)

Using this formula, it is easy to translate the 0 to 255 raw counts from a temperature sensor into degrees F or C and on a scale above and below zero for example.

Let's say that a semiconductor temperature sensor is linear between -25 and +100 degrees Celsius. With 255 raw counts, each count would equal approximately 1/2 degree C.

With a scaling factor of 2, and an offset of -25, we can get a reasonable processed data value in degrees C.

Now for the example :

Here we'll assume that you have 4 temperature sensors ( like the LM34 ), and they are each connected to one of the four analog ports of the ADB I/O, and that the ADB I/O has been properly installed.

We need four new items in the XTension database named and configured so :

TEMP 1 - dimmable, no address, description = ADB I/O port B channel 1
TEMP 2 - dimmable, no address, description = ADB I/O port B channel 2
TEMP 3 - dimmable, no address, description = ADB I/O port B channel 3
TEMP 4 - dimmable, no address, description = ADB I/O port B channel 4

Now either create the units and type in the following text by hand, or you can download a file that contains an XTension 'plug-in' and the 'applet' already done for you. You will of course have to 'unstuff' it, and then import the plug-in ( "justemps" ) into XTension via the "Database..Import" feature...

Download the ADB I/O plug-in NOW
After downloading and unstuffing, the plug-in
becomes an applescript 'applet' named "fourAnalogs" :

STOP ! This need not be geeky.
You do not have to understand this script,
you can just download and 'import' the 'plug-in'.
The plug-in creates the database units and scripts.

Sorry about the size but it looks like this in Apple's Script Editor....

analog applet

and here's what each of the four TEMP x units
will look like after you import the 'plug-in'....


Now, with XTension already running, and the ADB I/O connected, start up the applet "fourAnalogs" by double-clicking it. Note that this could be done from a startup script in XTension.

You can now hold one of the temperature sensors in your hand and see the corresponding value go up and down in the XTension database, but it will most likely be 'screwey'.

You must now 'tweak' the scaling and offset values of each sensor ( Fields SF and Bias in the CMST in the 'applet' ) for a more calibrated result. Don't forget the other technote for more detail about the setup.

Enhancing this example :

Exceptional limit violations can be handled by another pair of values, another string value and a flag in the CMST, and additional code in the script.

You would want to have a 'high limit' and a 'low limit' expressed in raw counts, and you need a flag which says 'unit is outside limits' or not.

Thus, only when a temperature goes above or below these limits, is a message sent to XTension which stimulates some 'reactive control logic'.

The 'unit is outside limits' flag should be set accordingly with each sample, and thus prevents sending the exception message multiple times while the unit remains out of limits.

Note that 'chattering' is limited by the "significant change" value, but it is possible to have a situation where the value is oscillating around one of the exception limit points. The process should be somewhat self-limiting in that each event elicits a message to XTension before proceeding to the next sample.

You might want to instanciate a 'hysteresis' function which would limit the notifications in the above case.

The example is written in such a form that it should be easy both to make changes in the code and in the format of the CMST. It should also be easy to see how to add more channels and ADB I/O units by another entry in the CMST for the responsible 'unit' number.

By modifying the code to be a periodic script which is scheduled by XTension, you can create a system which doesn't take so much execution time, perhaps for more slowly-changing measurements.

You could also modify the script so that the ADB I/O is on one Mac, and XTension runs on another. You need only specify the machine and maybe zone in the "tell application" process.

In a multi-Mac situation, you would also want to have 'verb handlers' in the applet which served commands from XTension to turn on or off the discrete output channels of the local ADB I/O units.

You might also want to throttle the sample rate of certain sensors. Since it is just as easy to read 4 analog values at once as it is to read one, it is probably sufficient to assign a 'sample rate' to a single ADB I/O unit rather than to individual channels.

The applet running on a remote machine might also be simply driven by a scheduled event within XTension. Thus some measurements might be sampled and reported as above, but others might be explicitly polled by control sequences within XTension.

You might want to see the more detailed : analog processing technote which goes further into the setup and calibration of analog sensors.

Any comments or corrections to this app note would be appreciated.

Additional help is available on our website:
Or directly to Michael and Paul Ferguson at: 407-349-5960
Or mail to Sand Hill Engineering Inc. Box 517 Geneva FL 32732
All icons, graphics and text copyright 1997 Sand Hill Engineering Inc.