EZIOXtra Documentation

bcchang.com / ezio / EZIOXtra Documentation

About the EZIO Board

The EZIO Board is a microcontroller experimentation board created by Michael Rodemer and Ed Bennett. It can be used to interface a computer with external electronics, sensors, motors, lights, etc. The EZIO Board is used around the world by electronic artists and designers for installations, robotics, and experiments in physical computing. It has digital inputs for attaching switches, buttons, or any other kind of on/off signal. It also has analog to digital converters for attaching sensors which can respond to varying amounts of light, heat, pressure, etc.

The EZIO attaches to the computer through the serial port. Many newer computers have USB ports instead of serial ports, but the EZIO can also be used with USB to Serial converters.

The EZIO Board can be used with any programming language that can access the serial port, and with programs like MAX/MSP and Director through plugins. The EZIOXtra adds scripting commands to Director to control the board.

About the EZIOXtra

The EZIOXtra is a Director plugin for Director 7 and higher. It is available for Mac OS 9, for Mac OSX, and for Windows.

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 2 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.

Installing the EZIOXtra

Command Reference

The EZIOXtra adds new functions to Lingo and Javascript in Director. They are accessed through a scripting object, created with the 'new' command. To test out these commands, you can just try them from the message window. The usual method is to create one Xtra object as a global variable in your startMovie script, and use it throughout the movie. In most cases, the same commands can be used in either Lingo or in Javascript; Javascript just needs a semicolon at the end of each line.

new ()	findPorts ()	initSerial ()	closeSerial ()
readLine()	a2d ()	readLineAll ()	a2dAll ()
writeLine ()	pwm ()	readPort ()	writePort ()

Initializing the Xtra

XtraObject new xtra ("EZIOXtra")

Creates a new script Xtra object.

ezio = new xtra ("ezioxtra")

Usually, you'll want to make the xtra object a global variable so you can use it throughout the movie.

 -- Lingo

  global ezio

  ezio = new xtra ("EZIOXtra")

  //Javascript

  _global.ezio = new 
  xtra ("EZIOXtra")

To use the Xtra, install it in the Xtras folder of the Director application. in OSX, it goes in Applications/Macromedia Director MX 2004/Configuration/Xtras. This makes the Xtra available to any Director movie on your computer. If you don't have access to this folder, you can also make your movie load the Xtra when it runs:

 global ezio

  openXLib ("EZIOXtraOSX")

  ezio = new xtra ("EZIOXtra")

portlist findPorts ()

Return a list of available serial ports.

 -- Lingo 

portlist = ezio.findPorts () 

  put portlist 

  -- ["Bluetooth-PDA-Sync","P#1USA28X1.1","P#2USA28X1.2"]

In this example, the computer returns 3 serial ports: 1 is a Bluetooth device, 2 and 3 are the ports on a Keyspan Twin USB->Serial adapter. On some computers, you might also see "Internal Modem" listed; on others, you'd only see the two Keyspan ports. Serial ports created by other USB->Serial adapters (for example, by Belkin) would have other names. This is important because you have to know the port number when calling initSerial (). The easiest way to manage it is to write your script on the computer you plan to use for your project; if you want to make your code more robust, you could either make it read the port number from a configuration file or give the user a choice of available ports when the program runs.
You can also use these specific names in the initSerial() function.

error initSerial (port)

open a serial port to initialize communication with the EZIO board. You must call initSerial before using any other EZIO functions!
There are three ways to choose the port: by number, by name, or by generic name. The function returns 0 if there were no errors, and an error code if there was an error.

Initializing by Number

This is the simplest form of the command. The ports are counted in the order that you see them in the list returned by findPorts (). For example, on a Mac that has serial ports, findPorts () will return:

["Printer Port","Modem Port"]

So, if you have the EZIO plugged into the printer port, you'd say:

err = ezio.initSerial (1)

And for the modem port,

err = ezio.initSerial (2)

On a USB Mac, ports 1 and 2 might be the corresponding ports on the keyspan adapter.
However, you might have other serial devices, like an internal modem or Bluetooth device. So if findPorts () returns this:

["Bluetooth-PDA-Sync","P#1USA28X1.1","P#2USA28X1.2"]

Then initSerial(1) would actually try to open the Bluetooth wireless sync, instead of the serial port you want. Instead, you would say initSerial (2).

Initializing by Name

The problem is basically that the USB->Serial adapter ports will have different numbers depending on what other devices are on your computer. Instead of initializing by number, you can also initialize by name:

err = ezio.initSerial ("P#1USA28X1.1")

Initializing by generic name

Finally, you can use the generic names "modem" and "printer" to open the serial port:

err = ezio.initSerial ("modem")

This will look for a port named either "Modem Port","USB Modem", or anything beginning with "P#2USA28X".

error closeSerial ()

closes the serial port. You MUST call this function at the end of your movie! Forgetting to call closeSerial () can leave the serial port stranded and unaccessible the next time you run your movie. With USB adapters, you can fix this by just unplugging it and plugging it back in, though on older computers you might have to reboot the whole machine. Usually you want to put this in your stopMovie function.

INPUT

value readLine (lineNumber)

reads one of the digital input lines, and returns either 0 or 1. lineNumber is a number from 1 to 10, as labeled on the EZIO board.

-- Lingo
global ezio
d1 = ezio.readLine(1)
put d1
if (d1 = 0) then 
  put "Line 1 is ON"
else 
  put "Line 1 is OFF"
end if

// Javascript
d1 = _global.ezio.readLine(1);
put (d1);
if (d1==0) 
  put ("Line 1 is ON");
else
  put ("Line 1 is OFF");

To use one of the digital inputs, wire a switch between it and Ground on the EZIO Board. When the switch is open, readLine() returns 1. When the switch is closed, readLine () returns 0. The 1 or 0 corresponds to the electical level at the input - +5V or Ground.
This is kind of counterintuitive, but has to do with how the electronics on the board work. When you don't have any circuitry attached to the digital inputs, they're "pulled high," or attached to +5V. When you close the switch between the input and Ground, it pulls the input low.
Why is this? If the inputs were built the other way (left floating low, and turned on by pulling high), they would be more susceptible to circuit noise and static electricity.

value a2d (lineNumber)

Reads one of the Analog to Digital inputs on the board, and returns a value from 0 to 255.
lineNumber ranges from 1 to 8.

-- read line 1
a1 = ezio.a2d (1)

-- read line 2
a2 = ezio.a2d (2)

valuelist readLineAll ()

Reads all 10 digital input lines and returns them in a list.

-- Lingo
global ezio
inputs = ezio.readLineAll ()
put inputs
-- [1, 1, 0, 1, 0, 0, 1, 1, 1, 0]
lines 3,5,6, and 10 are on.

You can then access the numbers in the list individually, or use a loop to process them all at once:

// Javascript
// make 2 cast members: one picture of a lightbulb, and one a picture of it turning on.
// put "lightbulb off" into sprites 1 through 10.

inputs = _global.ezio.readLineAll ();
for (i=1;i<=10;i++)
{
  if (inputs[i]==0) 
    sprite(i).member = "lightbulb on";
  else
    sprite(i).member = "lightbulb off";
}
_movie.go(_movie.frame);

valuelist a2dAll ()

Read all the analog to digital converters and return a list of 8 values.


// Javascript
// change heights of sprites based on analog inputs

inputs = _global.ezio.a2dall ();
for (i=1;i<=8;i++)
{
    sprite(i).height = inputs[i];
}
_movie.go(_movie.frame);

value readPort ()

Read the first 8 digital input lines as a single byte (0-255).

OUTPUT

writeLine (line,value)

Turn one of the digital output lines on or off. line is from 1 to 10. value is 1 to turn the line on, and 0 to turn it off. The example below would be used in a behavior to turn line 1 on when you click on a sprite, and turn it off when you release the mouse.


--Lingo
global ezio
on mousedown
  ezio.writeLine(1,1)
end

on mouseup
  ezio.writeLine(1,0)
end

//Javascript
function mouseDown ()
{
  _global.ezio.writeLine (1,1);
}
function mouseUp ()
{
  _global.ezio.writeLine(1,0);
}

pwm (line, duty cycle)

Pulse-width modulation, or PWM, is used to approximate a varying output. To change the brightness of a light, you would want to change the amount of current flowing through it. PWM simulates this effect by rapidly turning the light on and off, faster than the eye can see. The ratio between the amount of time the light is on and the amount of time it's off determines how bright the light appears to be.

writePort (value)

Write a single byte (0-255) out on the first 8 digital output lines.