Demonstration of Use of ADB I/O from Macromedia's Director

Stephen Wilson, Professor, Conceptual Information Arts Program, SFSU

Beehive's ADB I/O interface box allows creation of events that read sensors and control devices.  Care must be taken in the electronics of hooking up sensors and devices or the box and computer can be damaged.  Please be sure to read the ADB I/O manual.

Steve Wilson Director sample  (binhex.88k)   (be sure to get ADBIO xcmds from professor or from Beehive xcmds)

1.  Macromedia's Director requires an extra piece of software to allow it to communicate with the ADB I/O interface box.  In Director these supplementary pieces of software are called X-tras, Xobjects, or XCMDs (X-commands).  These are called an "Xlibrary" in Director.   The special software must be placed in the X-tras folder near the Director application or in the same folder as the Director movies you create.  Beehive provides the XCMD file.   You must install it on the computer you are working with or no acccess to the interface box will be possible.

2.  Open Xlib:  In your Director movie you must open the Xlibrary before you use it.  Typically this script is placed in the StartMovie handler.  The  example below shows the script.  Note the name in the script must exactly match the name of the XCMD file name.  When the movie is over, it is customary to close the X-library in the StopMovie handler.  Typing "showXlib" in the message window will list all the Xtras Director knows about.  ADBIO should show up if it has been successfully loaded. Also the Xlibrary needs to be in the right folder or the openXlib command won't work.  you would substitue a different routine if using another interface box like the cnx.

 -- "OpenXLib" is needed for the XCMD
 -- The whole pathName is needed if the XCMD file is not in
 --  the same folder as the movie.

on StartMovie
  -- opencnx   -- substitute this if using cnx box (see sample for code)
end StartMovie

on openadbio
  openXlib "ADB I/O XCMDs"
  configureIt (a routine I wrote - see below item 3)
end openadbio

on StopMovie
  closeXlib "ADB I/O XCMDs"
  --closecnx  -- swithch to this if using cnx
end StopMovie

3. Configure the Ports of ADB-IO box:  The box has two ports (A and B) with each having 4 channels.  Port A's channels  can each be configured as digital in or out.  Port B's channels can each be configured as analog in, digital in, or digital out (there are some limitations on combinations in port B - See the ABBIO manual for more details.) Your Director script must set the configurations before you access them.  If the configuration will stay the same throughout the event, you might configure it in the startMovie handler.  If the configuration will change during your movie, you can build in the configuration commands throughout the script.  In this example, I wrote a demo routine which I arbitraily called "configureIt".  It is called from the StartMovie handler.

Loading Xlibary of the ADBIO XCMD adds the new command to Director called ConfigureADBIO. It takes 6 parameters.  Each must be enclosed in quotations and separated by commas.  The first tells which ADBIO box is intended.  (The system can deal with 4; The default is 1). The second parameter tells which port is being configured - A or B.  The next 4 tell what function should be assigned to each element.  The example below called from startMovie would configure port A as 4 digital out elements (for example to control relays).  It would configure port B as 4 analog in elements (for example to read photocells). You could configure the ports for other functions - for example port A could be set up for digital in.

on configureIt
  -- called by the startMovie handler - see above
  ConfigureADBIO "1","B",  "analog in", "analog in", "analog in", "analog in"
  ConfigureADBIO "1", "A", "digital out", "digital out", "digital out", "digital out"
end configureIt
4.  Accessing the analog input:  Once the Xlibrary is open and the box is configured, Director also has available a new function called getADBIO(unit #,port).  This function allows Director to read values of voltages present at the input ports of the ADB-IO box. You use the phrase  put getADBIO( "1", "B") into variable.  The function sets the variable equal to four lines with a pattern that names the input and its current value - for example, "analog in, 230".  Here is a sample of what a variable might be worth after executing the line:
analog in,20
analog in,249
analog in,240
analog in,239

5. Analog Input - Sample of polling the input channels:  The routine below would contatntly update the values of variables arbitrarily named a1,a2,a3,a4.  It sets them as global variables and then uses the getADBIO function to obtain the current values.  Since it knows the results come back in four lines, it uses Director's abiltiy to extract parts of the line.  It puts the current 4 line results of the getADBIO function into a variable arbitraily named temp.  For example it knows the first line of the variable called temp would read something like analog in, 20.  In Director, text separated by commas are called items. The words analog in would be item 1 and the value 20 would item 2.   Thus it extracts the second item of line 1 (the value 20) and puts into a variable arbitrarily named a1.  This is the current value if channel 1.  It does this for each of the other channels.  Since these are global variables, they can be used anywhere else in Director that makes sense.

To force Director to constantly update the routine is placed in the on Idle handler (which executes even if users are taking no action).   For clarity the polling is separated into a subroutine called eadadbioAnalog that is called from the idle.  It also uses  a variable called updateflag to enable the updating to be turned off.  Some script in Director would need to explicity set updateflag = 1 to turn on the polling.

on idle
  global updateflag
  if updateflag = 1 then readadbioAnalog
end idle

on eadadbioAnalog
  global a1,a2,a3, a4
  put getADBIO( "1", "B") into temp
  put temp into member "constant"
  put item 2 of line 1 of temp into a1
  put item 2 of line 2 of temp into a2
  put item 2 of line 3 of temp into a3
  put item 2 of line 4 of temp into a4
end eadadbioAnalog

5.1 Simiulator:  If no interface box is available you can still design the movie by using simulators.  In the example, there are four text boxes representing each of the analog input values.  You type any value from 0-255 into each box.  If you switch the readAnalog to readSimulator routine then the global values a1,a2,a3,a4 follow the simulator rather than the interface box. You could do similar things with the digital input values.

on idle
  global analogflag
  if analogflag = 1 then

    --readSimulator   --- use this if not really attached

    --readcnxAnalog  -- use this if using cnx box -- deactivate the others
    --readadbioAnalog    -- use this if using adbio box -- deactivate the others
  end if
end idle

on readSimulator
    global a1,a2,a3,a4
     set a1 = field "a1sim"
      set a2 = field "a2sim"
      set a3 = field "a3sim"
      set a4 =field "a4sim"
end readSimulator

6 Digital Input:  Reading digital input values would work in a similar fashion.  The configuration would need to set the channels of port A or B. (Note that the interface box comes by default with relays in the channels of Port A.  The relays cannot read inputs and would need to have a device called an optoisolator substituted - see the manual).  Port B's channels could be used for digital in.

ConfigureADBIO "1", "A", "digital in", "digital in", "digital in", "digital in"

Then the extraction routine could work the same way.  The results on the lines of the variable returned by the getADBIO( "1", "A") would read something like digital in, high.  You would need to script Director to extract the high term and put it into a global variable that  you could use anywhere in Director.

7. Digital Output:  The interface box is capable of sending digital signals out.  When attached to appropriate electronic devices such as relays or digital interfaces. This capability can integrate control of devices with multimedia works.  Your script must configure the channels of port A or B for output.  For example.

 ConfigureADBIO "1", "A", "digital out", "digital out", "digital out", "digital out"
Then you must place script commands at appropriate places in your event to send the signals out.  Once the Xlibrary is loaded Director has a new command available called SetADBIO. This command takes several parameters to indicate device#. port, channel, value to be set, and delay time.  For example the following would set channel 1 of port A to high for 30 tenths of a second (3 seconds).  The delay time is optional and only works for prot A.  This command would make channel 1 high (activated) for 3 seconds and then drop back to low (unactivated).  The convention on port A is that high means the relay is closed and low means it is open.
SetADBIO  "1", "A", "1", "high","30"
You can use digital shorthand to set all the channels at once. Digital numbers from 0 to 15 can represent a pattern of 1's and 0's and thus each channel would not need to be indicated. For example the following line would set channel 1 and 2 to high and 3 and 4 to low. The integer 3 is represented in binary numbers as 0011.  The digit at the far right represents channel 1 and the digit at the far left represents channel 4. The SetADBIO command knows if no other parameters follow to interpret the integer as a digital pattern.
SetADBIO  "1", "A", 3
Here are some example binary equivalents and their results on the channels.
4 = 0100 = channel 3 high, all others low        15 = 1111 = all channels high
10=1010 = channel 4/2 high, others low           9  = 1001 = channel 4/1 high, others low

Basic examples of using the ADB-IO capabilities in Director movies

Example 1:  Moving balls and sounds respond to changing light levels
This example shows how colored balls on the screen could respond in real time to changing light levels out in the world.  The physical setup requires the ADB-IO interface box to be connected to 2 inexpensive photocells.  The photocells are electronic devices that read the light shining on them and change their electrical resistance.  The ADB-IO box is electronically built to report the levels of voltage at its inputs which are affected by the changing resistance. With appropriate physical arrangements of lights and sensors, the photocell could read movement of hands or persons.

This example assumes the basic ADBIO X-CMDs have been loaded (items 1,2,3 above) and the ADB-IO box port B must be configured to read analog in (item 4  above).  It also assumes that you have created the on Idle handler and constantUpdate routine that constantly reads the values seen at the sensor channels in port B. (Item 5) These routines are placed in the movie script so they are constantly active and available to routines throughout your Director movie.  The constantUpdate routine puts the values of sensor channel 1 into a global variable I arbitraily named a1 and the values of sensor channel 2 into global variable called a2

The example script is put in each of the frame scripts of every frame in the relevant section of the movie.  a1 and a2 are constantly updated to reflect light levels by the constantUpdate routine.  This routine sets the vertical level of the red ball (sprite 3) to correspond to the light level of sensor 1 by using the line set the locv of sprite 3 = a1+50. It sets the vertical level of the blue ball (sprite 4) to correspond to the light level of sensor 2 by using the line set the locv of sprite 4 = a1+50.   The +50 is introduced so that even when there is 0 light level the ball will only go up to the beginning of the black line which was arbitraily set at vertical position 50.  The next lines of the script illustrate how sound levels could also be mapped to light levels.  For example the line set the volume of sound 3 = a1 will make the volume of sound 3 change with light levels at sensor 1. 

The if statements using the soundbusy(3) and soundbusy(4) are necessary to make Director keep repeating the sounds when they are done.  It assumes you have created a sound file called "redsound.aiff" and "bluesound.aiff" to be assoicated with the movement of the balls and that you have chosen to play them in sound channels 3 and 4.  See the tutorials elsewhere on this site if you need background in Lingo.

on exitframe 
  global a1,a2
  set the locv of sprite 3 = a1+50 
  set the locv of sprite 4  = a2+50 
  set the volume of sound 3 = a1 
  set the volume of sound 4 = a2 
  put a1 into member "a1indicator" 
  put a2 into member "a2indicator" 

  if soundbusy(3) = false then 
    soundplay file "redsound.aiff" 
  end if 

  if soundbusy(4) = false then 
    soundplay file "bluesound.aiff" 
  end if 


(**note this not active example because of hardware)
If your light levels did not move the full range between 0 and 255 you would need to build in a conversion rotuine to covert the sensor values a1 and a2 into more relevant screen location values- for example, if the sensors only returned values from 40 to 160 but you wanted to move more than location pixels 40 to 160.  This line would accomplish the expansion of the 120 sensor value change range to 480 screen pixel range. Each a1 value would be multiplied by the ratio of the full screen range to the sensor possible range.  In this example, a sensor reading of 100 would be multibplied by 4 and place the ball at screen location 400 instead of the 100 position if the sensor value would be used directly.

set newredloc = 480/(160-40) * a1


Example 2:  Turning virtual and physical lights on and off
In this example, moving a mouse into each of the images of a light bulbs makes the screen image of that light appear to go on.  It also turns on the physical relay controlling a real light controlled through the ADBIO interface box.  Moving a mouse out of the light bulb image on the screen appears to turn off the screen light and the physical light by turning off the relay. 

To use this script, one must have loaded the xcmd and configured the interface box for digital output as described in items 1,2, and 3 above.  There are 2 cast members - one showing a light off (called member "lightoff") and the other showing a light on (called member "lighton").  There are 4 sprites - each controlling a different light.  There are sprite behavior scripts attached to each of them. 

When the mouse enters the sprite, a mouseEnter script changes the cast member to member "lighton" - giving the appearance of illumination.  It also beeps and sends the command to turn on the ADBIO relay.  When the mouse leaves the sprite a mouseLeave script changes the cast member to member "lightoff" - giving the appearance of turning off.  It also sends the command to turn off the ADBIO relay.  (The Script is slightly different for each sprite - the 3rd parameter for the relay SetADBIO command changes to refer to channel 2,3,or 4 as is appropriate.

on mouseEnter me
  set the member of sprite the spriteNum of me = 
member "lighton"  (really on 1 continuous line) 
   SetADBIO  "1", "A", "1", "high"
end mouseEnter

on mouseLeave me
  set the member of sprite the spriteNum of me = member "lightoff"
   SetADBIO  "1", "A", "1", "low" 
end mouseLeave

(**note this not active example because of hardware)


More information about the course exploring the artisitic use of these capabilities is available at the description of the Trio of Experimental Technologies Course Description.
Stephen Wilson, Professor, Art, Conceptual/Information Arts Program, San Francisco State University
Information about the Conceptual/Information Arts program    (415) 338-2291   swilson@sfsu.eduWilson web page
Copyright, Stephen Wilson, 1999 - You are free to use the text as long as you attribute source and do not use them commercially.