ABOUT TELEO PRODUCTS SERVICES NEWS
PRODUCTS DOCUMENTATION TELEO USER GUIDE	Teleo Flash Class Library User Guide A guide to Teleo programming with Macromedia's Flash   Introduction Setup Teleo Flash Classes note: Compatible as of Flash MX 2004 (ActionScript 2.0). Earlier versions of Flash not supported.

Flash has always been an incredible presentation layer tool. With recent releases it has become in addition a powerful application development tool. Teleo arose out of a need to provide easy modular electronic capability to a wide variety of people. The combination permits people to create stunning graphics and complex behaviors coupled to real world interaction.

Teleo itself is described in detail in the Teleo User Guide. The purpose of this document is to describe the process by which Flash can be used to exchange data with Teleo.

Each of the Teleo Classes is documented separately in the Teleo Flash Class Reference.

People will most often first start with the Teleo Starter Kit. This set comes with a power supply, USB cable and a Teleo Introductory Module. The Teleo Introductory Module has several inputs and outputs to which many different kinds of sensors and actuators can be connected.

There are two distinct ways that Teleo and Flash can work together. In its most simple form, Flash can be running on a computer that is directly connected to the Teleo Project.

In a more elaborate setup, one perhaps more familiar to Flash users, the Teleo project is connected to a Server which is in turn connected to a desktop.

In both cases, the Flash application connects to a server program, the Teleo XML Server from MakingThings, that in turn communicates with the Teleo hardware.

A simple example serves to illustrate how easy it is to connect devices to the system. With the Teleo XML Server running in the background, connecting a potentiometer up to the Analog In 0 input of the Teleo Introductory Module, and the Intro Module up to a computer permits a simple demonstration:

If a MovieClip is created on the stage and named, the following code produces an image on screen with rotational speed controllable by the potentiometer.

import com.makingthings.*;

var ain:TIntroAin = new TIntroAin( 0 );

tPiece.onEnterFrame = function()
{
   var v:Number = ain.getValue();
   tPiece._rotation += v - 16;
}

The preceding code is the entire ActionScript code needed to get data into the Flash application. An explanation of all the aspects of programming Teleo will come in the next few sections.

The code above produces the following.

There are a small number of steps to install the Teleo Flash system.

0. Before you start

If your operating system is Windows, do not make the USB connection between the Teleo system and your computer until you have installed the FTDI USB Driver

1. Downloading

Download the components from the MakingThings website

FTDI Driver (Windows and Mac only)
Teleo XML Server
Teleo Flash Class Library

http://www.makingthings.com/products/downloads

2. Installing the USB driver

See USB driver installation notes for your operating system

3. Connect the Teleo System to your computer via the USB cable

(If you are a Windows or Mac user install the USB driver first - see 2 above)

4. Apply power to the Teleo system

Do this by plugging the power cord into the Teleo Introductory Module, and the power supply into an AC outlet.

5. Run the Teleo XML Server

The exact procedure depends on your operating system. See the readme notes for the exact details.

Under Linux, for example, you type

./TeleoXMLServerLinux 9999

The number specified after the program name specifies the port the server is to listen on. If you omit the port, the default (50000) is used.

6. Install the Teleo Flash Class Library

The first decision is to decide whether to use the Extension Manager package or plain .zip archive with the source in it. The Teleo Flash Class Library is source code only (i.e. no other resources) so placing the files manually is a reasonable thing to attempt.

Zip File

Download the teleo_v_1_0.zip file
Unzip it into the place you wish it to reside
If necessary, add the desstination to the class path in the IDE so the IDE can find the classes.

Extension Manager Package

Download the teleo_mxp_v_1_0.zip file
Unzip it to a temporary location
Double-click on the file (assuming the mxp file association is setup) or if it is not, open the Extension Manager and select the file to install.

7. Play

Connect sensors or actuators to the Teleo Introductory Module

Download some of the sample files, or write your own.

Networks, Modules, Devices & Properties

Modules are the physical boards that attach to the Teleo Network. To function correctly, each has its own unique address. The actual numerical addresses for regular modules can range from 3 - 63, and the address of a module can be changed with a simple procedure.

One module on the network is the Controller. This Controller is either the interface to the main computer or it is the main computer in the system. All of the housekeeping and many of the data messages that modules generate are sent to the Controller. Future versions of the Teleo product will permit there to be 0 or more Controllers on a single network, but currently this number is limited to one.

Each module has one or more autonomous devices. These devices are indexed from 0 to n - 1, where n is the number of devices on the module. For example, the Teleo MultiIO Module has 14 devices: 4 Analog In, 4 Digital In, 4 Digital Out and 2 PWM devices - each of which functions completely autonomously.

Properties

Each Device present on a module has Properties which control the behavior of the device in some cases and report information back in other cases.

Proxies

Proxies are the software objects that represent Teleo Devices. When you create a Teleo Proxy, you provide for your application an opportunity to set and get properties on that device and also to receive updates.

The concepts are illustrated below. Here a project has been built that has a motor and a potentiometer. The motor might power a rotating display of some kind and the potentiometer is set up to control the speed of rotation.

First the two proxies (p & m) are constructed. The first, p, is an instance of the TIntroAin (com.makingthings.TIntroAin, more precisely). The name TIntroAin is formed in the same way that many of the Teleo Proxy names are: The "T" indicates Teleo, the "Intro"indicates that it's a device on the Intro Module and finally, the "Ain" indicates that the device is the Introductory Module's Analog In. You'll notice also that there's a number passed into the constructor. This number indicates that the device of interest is plugged into the Ain0 terminal on the Intro Module. (See the Teleo Starter Kit User Guide).

Once the proxy is created, its properties may be read and written using standard getters and setters of the form:

proxy.getProperty( );
proxy.setProperty( );

Each of the Teleo Proxies derives from the root class TeleoProxy. This class provides some of the more generic functions that each proxy might be expected to have - like the getBound( ) function which returns whether there actually is a real hardware device connected to the proxy.

Using Proxies 0 - Preliminaries

Before anything can be done, the Teleo XML Server must be running on the machine that has the Teleo system connected. This is done from a command line as follows:

Windows	TeleoXMLServerWin32.exe [port number]
Mac OS X	TeleoXMLServerMacOSX [port number]
Linux	TeleoXMLServerLinuxX86 [port number]

When the XML Server is running you will see reassuring messages saying where the server found the USB device that is connected to the Teleo System.

To use the Teleo Flash class library, (assuming it has been installed correctly as outlined above), the first thing you need to do is to include the MakingThings flash library. Do this with the following line:

import com.makingthings.*;

The default XML Server runs on your local system on port 50000. If you set it up this way, you may begin to create proxy objects immediately. If your server is either on another machine, or you assigned it a port other than 50000, you will need to tell the Teleo Flash library how to find it. This is done via a static method on the TeleoProxy object.

TeleoProxy.TeleoConnectorCreate( "192.168.0.52", 50002 );

TeleoProxy, as we discussed above, is the parent class for all the proxy classes. TeleoConnectorCreate( ) is a static method on that class, which means you can call it whenever you like without even needing an instance of TeleoProxy. If your server is running on localhost and is listening on port 50000, then you do not have to do this step, it is done automatically for you.

The next step is to create the proxy itself. This is easily done. For devices on the Teleo Introductory Module the proxy needs to be created and the device number passed into the constructor. For example, creating a proxy for the Analog In device is done as follows:

var ain:TIntroAin = new TIntroAin( device_number );

For devices on other Modules, the pattern is exactly the same, except that in addition to the device number the module address is passed in as a parameter to the constructor. The address is not needed for devices on the Introductory Module since the Introductory Module's address can not be changed. For example a VideoMove device proxy would be constructed as follows:

var video:TVideoMove = new TVideoMove( device_number, address );

Using Proxies 1 - Using Getters and Setters

With the proxy created, it may immediately be used to get and set data. The form for getters is as follows:

proxy.getValue( );

The getter functions return immediately with the latest value that their proxy has received. It does not send a message all the way to the hardware and wait for a return value from the hardware. The value the proxy has is refreshed every time it changes at the hardware level.

Symmetrically, the form of the setters is as follows:

proxy.setValue( value );

The setter function causes the value to be sent to the hardware when it is called, although the function returns as soon as the request is dispatched to the server.

Using the Teleo Proxies this way makes information exchange available to and from the hardware in a very convenient manner provided it is convenient for the application to check the critical values. For example, in the code below, there is something that needs to change every time the frame is entered (namely the rotation of the tPiece movie clip).

_root.onEnterFrame = function( )
{
     tPiece._rotation += ain.setValue( ) - 16;
}

In many situations, this is not suitable at all. What is really needed is something more passive.

Using Proxies 2 - Using Update Methods

The easiest way to be informed when an event occurs is to assign the update methods on the Proxy. This looks like the following:

ain.onValue = function( value:Number )
{
    // do something here with the new value
}

This technique is very handy in the case of infrequent updates - the machine wastes no time polling for information that is mostly not there.

There are many cases when this kind of update is perfectly acceptable, but it has some flaws: namely it doesn't do too well in a truely object oriented programming environment. Assigning a class method to the onProperty member of the proxy has the alarming effect of running the class' method in the context of the proxy.

Using Proxies 3 - Subclassing

The method most frequently used in OOP to handle the problem of what to do with calls that have to emerge from objects is to use subclassing. In this method the Proxy is subclassed by your code, so that the object you're writing actually becomes a Proxy object. It gets informed of data updates by overriding the onProperty( ) methods.

import com.makingthings.*;

class MySubclass extends TIntroAin
{ 
    // ....

    // Override the onValue function 
    public function onValue( value:Number )
    {
        trace( "Subclass incoming value:" + value );
         // Implementation that does something with value
         // ...
    } 

    // ....
}

After the class is defined, it may be used as a TIntroAin with your extra code.

var mySubclass:MySubclass = new MySubclass( 1 );

Using Proxies 4 - EventBroadcaster-based Callbacks

The event mechanism most familiar to Flash programmers is the EventBroadcaster or its earlier precursors. Teleo Proxies support this method of requesting and receiving events.

The first step is to create a function on the listener of the appropriate name that will serve to receive the updates.

_root.onTIntroAinValue = function( event:Object )
{
	trace( "New Value" + event.value );
}

The next step is to connect the class to the proxy so that it receives the events.

ain.addEventBroadcasterListener( "onTIntroAinValue", myClass );

After the class is connected to the proxy, it will now receive all the relevant updates along with any other instance that registers. Note that the pattern for the event name is onT[proxyname][property] rather than on[property] so that events from MakingThings objects do not collide with each other.

Using Proxies 5 - Interface-based Callbacks

Another method frequently used in OOP to handle the problem of getting information efficiently to objects that are not known by the caller is to rely on interfaces. The information receiver implements an interface known to the caller and then registers itself with the caller.

The first step is to make sure the interface is properly implemented on the class that needs to receive the updates.

import com.makingthings.*;

class MyClass implements TIntroAinCallback
 { 
    // ....
  
    // The TIntroAinCallback Interface implementation
    public function tIntroAinOnBound( tIntroAin:TIntroAin, bound:Boolean ) { }
    public function tIntroAinOnPeriod( tIntroAin:TIntroAin, period:Number ) { }
    public function tIntroAinOnResolution( tIntroAin:TIntroAin, resolution:Number ) { } 

    public function tIntroAinOnValue( tIntroAin:TIntroAin, value:Number )
     {
         trace( "Value:" + value );
         // Implementation that does something with value
         // ...
     }

    // ....
}

The next step is to connect the object to the proxy so that it receives the events.

var myClass:MyClass = new MyClass( );
               
ain.addInterfaceListener( myClass );

After the instance is connected to the proxy, it will now receive all the relevant updates along with any other instances that register.

This is a very robust way of making sure that the correct instances get the information needed, but it does require a little more investment of time and energy to create classes that have the correct interface implementation.

It also has the advantage of permitting the class that implements the interface to derive from whatever it likes. The interface doesn't force the inheritance hierarchy to start with com.makingthings.TeleoProxy.

Finally, the interface method represents a very efficient way to get information around, no objects are created, and no EventBroadcaster lists searched.

Property Inspectors

Along with every proxy class, there is a corresponding inspector. This inspector allows the developer (and the user if this is desirable) to see and change the properties of the proxy. The inspectors hold a reference to their target proxies, and subscribe to the proxy's events.

The Inspectors are implemented entirely in code, so there are no library symbols to load in order to make them work.

Constructing a Property Inspector is very simple.An Introductory Module Analog In proxy, ain is constructed as follows,

var ain:TIntroAin = new TIntroAin( 0 );

An inspector may be created on it by the following code:

viewer = new TIntroAinInspector( _root, ain );

The name of the inspector is formed by appending "Inspector" onto the end of the basic proxy name. It takes the movie clip which will server as its parent and the proxy it will monitor as constructor parameters. When it comes up it will present each of the proxy's properties and permit the writable ones to be altered.

The inspector created above looks like the following.

In addition to providing access to the properties of the proxy, the inspectors provide graphical feedback of the state of the connection to the proxy. The two glyphs on the title bar reflect the state of the proxy that the inspector is connected to (Proxy Glyph), and whether the proxy is connected to a physical module (Module Glyph).

To illustrate how this works, the image below is a fragment of the the Teleo Motor Controller 10 Amp - Property Inspector (TMC10Inspector). Note that the Proxy Glyph is illuminated while the module glyph is not. This means that the proxy is created and running, but it is not connected to an actual module. Read only properties are set to their defaults, and writable values may be changed. Since there is no connected hardware, the value changes are queued until the module is bound.

While the module is in this state, the inspector may be put into Simulation mode, where it will accept changes made to the read only properties, in addition to the writable ones. This permits the software using the proxy to be exercised even when there is no hardware connected. This is useful for demos and for sample code. When the Inspector is in Simulate mode, its background turns red.

Once the hardware is found, the Module Glyph is illuminated, and any queued changes to writable properties are sent.

In the examples above, Inspectors can be constructed without specifing a proxy. This is useful when a general inspector is wanted that can be re-pointed as desired.

viewer = new TIntroAinInspector( _root );
viewer = new TIntroAinInspector( _root, null );

The physical appearance of the Inspector is different when no proxy is specified. Note that both the Proxy and Module glyphs are dimmed.

When a legal address and device pair are specified by the user, the create button is displayed indicating that the proxy may be created.

When this button is pressed, the proxy is created. If the proxy is bound to a real device the Module glyph is illuminated.

Inspectors have very few methods. They can be hidden and revealed by calling

setVisible( visible:Boolean );

Inspectors can also be put into Simulator mode by calling

setProxySimulate( simulate:Boolean );