guidetoezio.html

Guide to Using EZIO board to read sensors and control devices

Stephen Wilson, Professor, Conceptual Information Arts Program, SFSU

NOTE - Revised script 3/19/2003 - should work - incorporates simulator for when no board there

Overview

Most computers do not come with any ability to read sensors or control devices (other than the mouse, keyboard, and screen) These other abilitities can be added with the use of special hardware and software. Often these are called IO Ports. The addition of these abilities will become increasingly important in the future as artists begin to explore physical and ubiquitous computing. This guide is a step-by-step guide to using a device called the EZIO board The EZIO is a multifunction IO board developed by art professor Michael Roedemer at the University of Michigan. It works with both Macintosh and PC computers. Using it is somewhat complex and requires several steps. Here are the steps involved in using it with Director.

I. Convert RS-232 to USB. The EZIO board uses a old protocol for communicating with the computer called RS-232 serial communication. Most computers now use USB. You need special hardware and software to convert.it.
II Add serial communication xtra to Director: Director is not capable to comunicating with serial devices without a special Xtra.
III Add the ezio initialization and communication commands to Director: The ezio board works by having director send special commands to the board via the serial communication xtra.
IV Hook up devices and sensors to the EZIO board: The EZIO board is an electronic device capable of communicating with a wide variety of sensors and devices. This guide will focus on simple devices such as photocells, switches, and relays.
V Set up scripts to read sensors and to activate events. Arrange for a simulator script that allows development when not hooked up to the EZIO board. Give samples of routines to read sensors and write to ports.

Notes on the development of the EZIO board: Micheal Rodemer is an artist and art professor at the University of MIchigan who works with computer controlled installations. He and Ed Bennett worked together to develop this flexible, inexpensive interface for computer control. Much of this guide was derived from materials provided by Rodemer in the documentaiton of the EZIO board. Here are some links:

I Convert RS-232 to USB

There are several devices on the market that convert RS232 to USB. They plug into the computer via a USB connector and then have a serial plug on the other side for the rs-232 link. The EZIO board has 2 serial cable outputs (one for mac and the other for PC) This guide will illustrate by focusing on the Keyspan converter. There are similar devices available for the PC.

In order to use it you must install the special driver software that comes on the cd with the device. The computer will not be able to talk to converter without this software. You will also need to set the parameters in the keyspan serial assistant control panel. With the keyspan you can leave most of the settings at their default. The keyspan has serial ports - usb::1 and usb::2. The example bleow shows the control panel that controls the keyspan device. In the example below, note that usb1 is mapped to a port name "Printer Port USB". You will need that port name in the xtra that allows director to talk to serial devices.

II Add serial communication xtra to Director:

The EZIO board sends and receives commands via RS-232 communication. It uses an xtra for deirector to send serial communicati0on. This example uses Geoff Smith's SerialXtra which you must place in yor Xtra directory. If you use other serial communication xtras, you will probably need to adjust the commands.

-- Do not delete this Movie Script! Nothing will work!!
-- Director for Windows EZ I/O script
-- Version 1.3beta april 23, 2001
-- fixes serial comm problems with handlers that return results
-- modifications by Olof Bendt for it to work in Director8 with Geoff Smith's Serial Xtra
-- just install the Xtra as usual, instead of the .dll file supplied with the EZIO
-- distribution.
--
-- ===============================================================================
-- Copyright 1997, The Regents of the University of Michigan. All rights reserved.
-- Developed at the University of Michigan School of Art and Design
-- by Michael Rodemer and Ed Bennett
-- ===============================================================================
-- ===============================================================================
-- the following gets Director ready to do serial communication with the microcontroller
-- on the interface board. It MUST be present fo any of the other scripts associated
-- with the board to work!
-- Also, you must have Geoff Smith's SerialXtra in yor Xtra directory
-- ===============================================================================
-- this routine checks if you have already intiialized the serial xtra
-- if not, you need to initialize by setting a global variable arbitraily called port
-- you will need to refer to that name in many of the other routines
-- equal to the result of new (xtra "SerialXtra" "Printer Port USB") command
-- note that the second parameter is the name of the port
-- that you set with the keyspan control panel
-- next it sets the baudrate (which is the speed of communication)
-- it could be other rates (check the documentation of the xtra)
-- you would call this routine from the startmove handler
on startsensors
global port
if port=Void then
port = new (xtra "SerialXtra" "Printer Port USB")
port.setBaudRate(57600)
end if
end

III Add the ezio initialization and communication commands to Director:

NOTE: you should use the routines described in section 5 below to access the read and write routines rather than these direct calls
Those routines allow easy use of the simulator when there is no board

The EZIO board comes with several routines for using its various capabilities. The capabilities include the following:

Reading the voltage state at each of the digital input ports (eg a button pushed or not)
Writing a voltage level to each of the digital output ports (eg a +5 volt signal or low volt signal)
Reading the analog voltage at each of the analog input ports ( a relative value from +5 to 0)

The EZIO board is looking for a string of characters including a letter and one of more values to tell it what to do. Each of these routines compose the proper sequence of commands and then send them out the serial port. These routines should be put in the script at the movie level. They will be repeatedly called as you attempt to check the input status of the various digital and analog ports and output digital signal levels to the output ports.

Read an Analog Voltage

-- A2D will read a voltage between 0 and 5 Volts
-- (use the 5V available on the board) and return its value,
-- expressed as a number between 0 and 255
-- you get access to its value by setting a variable equal to its result
-- for example A3 = A2D(3) would set the variable A3 = current analog voltage

on A2D lineNo --valid line numbers are 1-8
global port
port.FlushInputBuffer()
port.WriteNumber(65) -- write a capital "A"
port.WriteNumber(lineNo-1) -- write the line number
repeat while (port.CharsAvailable())<1)
end repeat
return port.ReadNumber() -- reads result from board
end

Read a voltage level at the digital input ports.

-- readLine returns a 0 or 1 to indicate the state of a single line,
-- with "1" being "high" and "0" being "low"
-- set z4 = readLine(4) would set the variable z4 = to the voltage state at the input line 4

on readLine lineNo -- valid line numbers are 1 through 10
global port
port.FlushInputBuffer() -- this clears out anything left in the receive buffer
port.WriteNumber(114) -- write a small "r"
port.WriteNumber(lineNo-1) -- write the line number
repeat while (port.CharsAvailable())<1)
end repeat
-- this forces Director to wait for the result, preventing errors such as
-- the same result coming back twice in spite of changed lineNo or value
return port.ReadNumber() -- return state
end

Control the voltage level at digital output port

-- writeLine turns a single line on or off, "1" being "on," "0" being "off"
--writeLine 2, 1 would turn on output port 2
-- writeLine 3, 0 would turn off output port 3

on writeLine lineNo, onOff -- valid line numbers are 1 through 10
global port
port.WriteNumber(119) -- write a small "w"
port.WriteNumber(lineNo-1) -- write the line number
-- internally, the chip starts numbering lines at 0
port.WriteNumber(onOff) -- write zero or one
end

Other commands: - write or read all 8 digital ports at once using digital values from 0 -255. Control the pulse width modulator motor controller

-- ===============================================================================
-- writePort will cause a pattern of ons and offs on digital output lines 1 through 8 on the board
-- depending on the value of the variable "state"

on writePort state -- valid values for state are 0-255
global port
port.WriteNumber(87) -- write a capital "W"
port.WriteChar(state) -- write the state
end

-- ===============================================================================
-- readPort returns a value between 0 and 255 for the 8-line port
-- comprised of digital input lines 1 through 8 on the board

on readPort
global port
port.FlushInputBuffer() -- this clears out anything left in the receive buffer
port.WriteNumber(82)
repeat while (port.CharsAvailable())<1)
end repeat
-- this forces Director to wait for the result, preventing errors
return port.ReadNumber() -- return state
end

-- ===============================================================================
-- PWM turns a line on and off rapidly (more than 18,000 times a second),
-- varying the ratio of the time the line is off to the time it is on.
-- Valid input values are from 0 (always off) to 1023 (always on)

on PWM lineNo, onTime -- valid line numbers are 1 or 2
global port

-- the following code makes two 8-bit numbers
-- out of the 10-bit number (0-1023) passed to PWM as an argument,
-- passing two characters to the board one after the other
put 0 into temp
if (onTime-512>=0) then
    put (temp+2) into temp
    put (onTime-512) into onTime
end if
if (onTime-256>=0) then
    put (temp+1) into temp
    put (onTime-256) into onTime
end if
put temp into hiBite
put onTime into loBite
port.WriteNumber(80)
port.WriteNumber(lineNo)
port.WriteNumber(hiBite)
port.WriteNumber(loBite)

end

IV Hook up devices and sensors to the EZIO board:

You must undertake some minor electronics to make the sensors and actuators work. The EZIO board has all the relevant hookups and care must be taken or the board coutd be damaged. This guide, based on the Roedemer materials, shows how to do basic hookups. It includes:

How to hook an analog sensor such as photocell
How to hook up a digital input such as a switch
How to hook up a digital output to control a device such as a relay

Hooking up Analog Sensors

The analog input needs a reference resistor. The potenitometer provides that and allows find tuning. In the illustration the sensor being read is a photresistor. Any other analog variable resistor could be used. The a/d converter compares the resistance of the pot and the photoresistor.

Hooking up Digital Input Ports

The digital input can be anything that allows or retards flow of current. One side of the switch/whatever is hooked up to the negative groud reference voltage port on the EZIO board. The other side is hooked up to the digital input port.

Hooking up Digital Output

V Set up scripts to read sensors and to activate events.

Here are some samples that show how to use the ezio board and provide for a simulator when there is no ezio board.

--================= intro
-- use a variable called ezflag to indicate if pluged into the board
-- script will use that variable thoughout to redirect to simulator if not plugged in
-- the ezio board init routines will be called if it = 1
-- the digital and analog input values will be fetched from the board if ezflag = 1
-- otherwise he digital and analog input values will be fetvched from simulator
-- use these routines for all calls to the board and the simulator will be seamless
-- !!!! don't change the member numbers or sprite numbers of the simulator and indicators!! the routines assume they are where they are
--
-- initsensorlists is routine to reset all values
-- digital in
-- readdiginput q is the basic routine to read a specific digital input port (q)
-- fakediginl= fake simulator digitial input port values list
-- curdiginl = list of current values at all digitial input ports (real & simulator)
--see other routines below
-- analog in
-- readAnainput q s the basic routine to read a specific analog input port (q)
-- fakedanainl= fake simulator digitial input port values list
-- curanainl = list of current values at all digitial input ports (real & simulator)
--see other routines below
-- ditigal out
-- writedigout q,val
-- digoutlist = list of current values at all digital output ports
--see other routines below
--===============start routines
on startmovie
global ezflag
if ezflag = 1 then
    startsensors
end if
initsensorlists
end startmovie
-- these are the lists that will store the values of sensors and outputs
on initsensorlists
global fakedanainl,curanainl
global fakediginl,curdiginl
global digoutlist
fakedanainl =[]
curanainl=[]
fakediginl = []
curdiginl=[]
digoutlist =[]
end
--====================== idle routines to check values at the board
-- take out the comments to force regular updates of input sensor readings
-- also take out comments to force write to output sensors

on idle
--updateinputs -- uncomment this to have automatic updates in input ports
end idle

-- this calls routines to read analog and digital in
-- the called routines get it from the board if ezflag =1
-- otherwise they get it from the simulator
on updateInputs
readalldigin
readallanin
end updateInputs

--==================== read digital in
-- this is the basic routine to read values at digital input ports
-- if ezflag = 1 then pluged into ezio board
-- go get all digitial input values and update the curdiginl variable
-- if ezflag not = 1 then go get value from fake simulator buttons not board
-- assumes 8 buttons that toggle between on/off state
-- and they set a fakediginl list variable with the values
-- q = parameter which tells which input port to check
-- builds a list that keeps record of state of input ports
on readdiginput q -- read digital input for each port
-- global ezflag, diginlist, fakediginlist
global ezflag, fakediginl,curdiginl
if ezflag = 1 then -- get it from ezio board
    temp = readLine(q)
    setat(curdiginl,q,temp)
else
    temp = getat (fakediginl,q)   ------ simulator
    setat(curdiginl,q,temp)
end if
-- update the display of current digital in
st = 70 -- member 81 to 88 are the current analog indicators
member(st+q).hilite = temp
end
on readalldigin   -- loop through all 8 digital input
global ezflag
repeat with q = 1 to 8
    readdiginput q
    if ezflag = 1 then
      starttimer -- put in delay so can settle for real readings
      repeat while the timer < 20
      end repeat
    end if
end repeat
end

on fakedigitalin
-- update the lists of fake in and current in
global fakediginl,curdiginl
st = 40 -- fake digital in
repeat with n = 1 to 8
    if member(st+n).hilite = 1 then
      setat (fakediginl,n,1)
      setat (curdiginl,n,1)
    else
      setat (fakediginl,n,0)
      setat (curdiginl,n,0)
    end if
end repeat
readalldigin
end
-- resetall digital in
on resetalldigitalin
global fakediginl,curdiginl
st = 40 -- fake digital in
repeat with n = 1 to 8
    member(st+n).hilite = 0
    if member(st+n).hilite = 1 then
      setat (fakediginl,n,1)
      setat (curdiginl,n,1)
    else
      setat (fakediginl,n,0)
      setat (curdiginl,n,0)
    end if
end repeat
readalldigin
end if

--======================== read analog in
-- This is basic routine to read analog input
-- it determines if an ezio board is pluged in
-- otherwise it gets values from fakedanainl variable set in the simulator
-- if ezflag = 1 then pluged into ezio board
-- go get all real analog input values and update the curanainl list variable
-- if ezflag not = 1 then go get value from fakedanainl list set in the simulator
-- assumes 8 fields that can have any value between 0 and 255
-- q = parameter which tells which analog input port to check
-- builds a list that keeps record of state of input ports
on readAnainput q -- does one readings
global ezflag
global fakedanainl,curanainl
if ezflag = 1 then -- get it from ezio board
temp = A2D(q)
setat(curanainl,q,temp)
else
temp = getat (fakedanainl,q) -- simulator
setat(curanainl,q,temp)
end if
-- update the display of current analog in
st = 80 -- member 81 to 88 are the current analog indicators
member(80+q).text = string(temp)
end readAninput

-- loops through all by calling readdiginput with q = 1 to 8
on readallanin
global ezflag
repeat with q = 1 to 8
readAnainput q
if ezflag = 1 then
starttimer -- put in delay so can settle for real readings
repeat while the timer < 20
end repeat
end if
end repeat
end readallanin

-- routine to take all the fake simulator values and enter them into the system
-- update the lists of fake analog in and current analog in
-- members 51-58 = fake analog in
on fakeanalog
global fakedanainl,curanainl
st = 50
repeat with n = 1 to 8
q = member(n+st).text
setat (fakedanainl,n,q)
setat (curanainl,n,q)
end repeat
readallanin -- update the current readings
end fakeanalog
-- reset all analog
on resetallanalogin
global fakedanainl,curanainl
st = 50
repeat with n = 1 to 8
q = 0
member(n+st).text= "0"
setat (fakedanainl,n,q)
setat (curanainl,n,q)
end repeat
readallanin -- update the current readings
end
--====================== ditial output
-- basic routine to write out value to digital output port
-- either 0 for off or 1 for on - toggle the button
-- only sends to indicator if there is no ezboard
--** note there are really 10 digital output - this only does 8 of them
-- change background of indicator in all cases
on writedigout q,val
global ezflag, digoutlist
if ezflag = 1 then -- send to ezio board
writeline q,1
end if
-- in both situations adjust list
-- and change color to indicate it is on
setat(digoutlist,q,val)
st= 60
if val = 1 then
member(st+q).backcolor = 34
else
member(st+q).backcolor = 0
end if
end

-- see what buttons indicate
-- send digital out to board if ezboard there

on writealldigout
st = 60
repeat with q = 1 to 8
if member(st+q).hilite = 1 then
writedigout q,1
else
writedigout q,0
end if
end repeat
end

-- sets all digital out to off (0)
on resetdigout
st = 60
repeat with q = 1 to 8
member(st+q).hilite = 0
writedigout q,0
end repeat
end
--============== make simulator and indicators visible
-- make fake simulator visible or invisible (q= 0 or 1)
on fakevis q
repeat with n = 24 to 44
sprite(n).visible = q
end repeat
end
-- indicator visile
on indicatorvis q
repeat with n = 46 to 72
sprite(n).visible = q
end repeat
end