You are here: Home → Documentation → Tutorials → Flash (ActionScript 2.0 and 3.0)
In This Section
Log in


Forgot your password?
New user?
 
Document Actions

Flash (ActionScript 2.0 and 3.0)

Note: Return to tutorial view.

Use the Make Controller with Adobe Flash.

Overview

A description of how the Make Controller communicates with Flash, and a list of required downloads.
FlashFlash has always been a powerful and easy to use tool for graphics, animation and interactivity. With the introduction of ActionScript, it has also become a powerful development tool. When paired with the Make Controller Kit, ActionScript developers have an excellent resource to easily create beautiful and complex visuals coupled with physical interaction.

The Make Controller Kit can communicate with Flash via OSC, a popular protocol used in a wide variety of environments and devices. If you've never used OSC before, check out the OSC tutorial.

Since Flash can't directly connect to the Make Controller via network or USB, we'll use mchelper (Make Controller Helper) to connect to the Make Controller over the network and USB, and format communication with the board into XML that can be fed in and out of Flash. Note that you need to use mchelper 2.0 or later in order to use it with Flash.

Two libraries exist for use with Flash - one for ActionScript 2.0 (AS2), and one for ActionScript 3.0 (AS3).  The libraries provide the same functionality, but they each adapt to the style of their respective languages. 

Which version should I use?

If you're running Flash 8 or earlier, you'll be using AS2.  If you're running Flash CS3 or later, you have the option to use either AS2 or AS3.  The AS2 library requires at least Flash MX 2004 7.2.



Downloads

First you'll want to download and install mchelper 2.0 or later if you haven't already.  Head to the Downloads section to do this.

While you're there, grab the latest Flash download package for either AS2 or AS3. There are several items in the download:

ActionScript 2.0
  • MakeController-AS2-v1.0.mxp will install the Flash library so it can be used in your applications.
  • The examples directory contains several sample .fla files that will get you started quickly.

To install the Flash classes, simply double click MakeController-AS2-v1.0.mxp, and the Macromedia Extension Manager will install the files for you. If If your Flash installation somehow did not include the Extension Manager, you can download it here.

ActionScript 3.0
  • MakeController-AS3-v1.0.zip contains the AS3 library.  If you're using Flash, you'll need to drag these to the appropriate location.
    • On Windows, drag the com directory to
    C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\ActionScript 3.0\Classes
    • On OS X, drag the com directory to 
    /Applications/Adobe Flash CS3/Configuration/ActionScript 3.0/Classes
If you're using Flex or some other tool, you'll need to consult the documentation for where to install these files.
  • The examples directory contains several sample .fla files that will get you started quickly.


Other Setup

  • You should be running Heavy 1.2.0 or later on the Make Controller.  If you're not sure, you can always open up mchelper, look at the Summary tab with your board selected, and look at the version.  If you're not sure how to upload a new program to your Controller, check this tutorial.
  • If you're connecting to your board via Ethernet, it's easiest to connect it to your network and let it automatically get an address.  If you're connecting the Controller directly to your computer via Ethernet, check this tutorial on how to configure that.

Examples

Here we get our feet wet and go over some of the example files.

The easiest place to jump in is with a couple of the example files.  We won't go over all of them here, but we'll take a look at a few to help get started.  Remember as we're going along, the documentation for the Flash libraries can be found at:


Before running any of the examples, be sure to start up mchelper.  Once you start your Flash movie, you should see a message notifying you that a new XML connection has been made.  When you close your movie, you'll see a message telling you about that as well.

By default, all the OSC messages from your Flash movie will show up in the mchelper window, and all messages back from the boards will as well.  This is good for getting started and debugging - it makes it easy to see exactly which messages are going where - but, when you're running a movie that's sending lots of messages, mchelper can start to slow down printing all those messages to the screen.  In these cases, you'll probably want to hide these messages. 

In the mchelper menu, click View -> Hide OSC messages to turn these off and speed things up.  You can always turn them back on whenever you need.


SingleLED.fla

Perhaps the simplest example file is SingleLED.fla - we'll start with that.  SingleLED.fla has one checkbox that we will use to turn LED 0 on the Application Board on and off.

The first thing we'll want to do is create an instance of McFlashConnect, which we do, naming it mcflash. We tell it to connect to mchelper in the onLoad( ) function, although we could do this right where we create it as well.

We use onBoardArrived( ) to set our default board to any board that is connected to mchelper.  If you need to communicate with a particular board, you'll need to add some logic to do that.

Once we know which board we're sending to, we can get down to business.  In SingleLED.fla, we're monitoring the state of our checkbox and if it ever changes, then we send a message with the new state, on or off, to LED 0 on the Controller. 
SingleLED
If the checkbox has changed, send a new message.

How do we know what kind of message to send?  The name of the LED subsystem on the board is appled - Application LED. There are 4 LEDs, numbered 0 - 3, and they have a state - whether they're on or off. The argument that comes after the address sets the value of state. So we create an OSC message in the form /subsystem/device/property argument, "/appled/0/state 1" or "/appled/0/state 0" in this instance.

Each frame, we check each frame whether the checkbox value has changed. If it has, we send the appropriate message to the board using mcflash.send().


AnalogIn.fla

Next we'll go over the AnalogIn.fla example to see how we get information back from the board.  There are 2 ways to get messages back from the board.  One way is to ask for it whenever we need it.  This is fine if you're just asking for values every now and then, but if you're going to be reading messages all the time, you'll probably want to use the autosend feature.  To do this, first you need to choose whether you want the Make Controller to send messages to you over USB or Ethernet.  If you want Ethernet, send it the message
/system/autosend-udp 1
The board will send messages wherever it last received a message from.  If you want USB, send the message
/system/autosend-usb 1
Next, decide how often you want the Make Controller Kit to send you messages.  We'll have it look every 10 milliseconds, or 100 times a second.  To do this, send the message
/system/autosend-interval 10
Lastly, turn the analog inputs autosend on.  We'll turn on autosend for all 8 of the analogin channels by sending the message
/analogin/*/autosend 1
Now, anytime the value changes on one of your inputs, the Make Controller will send you a message.  If you use this approach, you can remove the messages in the onEnterFrame but otherwise, we can send a request for the analogin values every frame, and then draw those values to the screen.  Read on below to see how to deal with the incoming messages. 

We take the same approach as in the SingleLED.fla example to create McFlashConnect and set our default board.

Now, each frame we send the message /analogin/*/value, with no arguments, to ask for all the analog in values.  As you will have seen in the OSC tutorial, the * is a wildcard which means "all of".  And the fact that our arguments array is empty means that we are asking for a value from the board, instead of sending it a value.  You can always increase the frame rate of your movie to get values back more often from the board.
Analogin
Process each of the analogin messages.

messages we're interested in.  The value of the message will be in the first element of the OscMessage's args Array.  Then, for each of the 8 analogins, we set the height of the meter on the stage and write the value to the dynamic text box underneath it with the new value.


Bundles.fla

The Bundles.fla example goes over how to use the bundle feature of OSC.  OSC bundles are a way to send more than one OSC message to the Controller at once.  Using OSC bundles can make your movie more efficient since it will not be sending a separate packet for each message, decreasing traffic between your movie and the board.  In this example, we'll show how to build up a bundle of messages, and then send it once we have 3 messages in it.

Once again, we take the same approach to create McFlashConnect and set our default board.
Bundles
Monitor the checkboxes and send our OscBundle once we have 3 messages.

We have 4 checkboxes on the stage, one for each LED on the Application Board.  Each frame, we check to see if any of these have been toggled and if they have, we create a new OscMessage and add it to our OscBundle.  The OscBundle is just a normal Array, and we use its push( ) method to add new elements onto the end of it.  Once 3 messages have been added, we send it out using sendBundle( ).  After sending it, we empty out the OscBundle so we start our count over.

For another example of bundles, take a look at the LEDchaser.fla example.

Concepts

A review of some helpful concepts in using the Make Controller with Flash.

There are a couple general concepts worth going over here to help you along in using the Flash libraries.


General

The main object in the Make Controller Flash library is McFlashConnect.  This is the object that makes a connection to mchelper and handles all the messages going back and forth between our Flash movie and the connected Make Controllers.

McFlashConnect can notify us of several events that we might want to know about:

  • Our movie successfully connected to mchelper
  • Our movie did not successfully connect to mchelper
  • A new board was connected
  • A message from a board arrived
  • A board was disconnected
  • mchelper closed the connection with our movie
We can also send messages from our movie to the Make Controller via McFlashConnect.



Finding Boards

When a Flash movie starts up, mchelper will send it a list of boards that are currently connected.  We need to tell McFlashConnect which one of them we want to send messages to.

It's usually pretty easy to use the onBoardArrived( ) method to set which board we want to send our messages to.  If we just want to send our messages to any board that comes along, we can take the board that just arrived, and set it as our default board using setDefaultBoard( ).  Now, whenever we send a message using send( ), the message will be sent to that default board.
mcflash.onBoardArrived = function( board:Board )
{
  mcflash.setDefaultBoard( board );
}

However, it's possible that more than one Controller might be out there, and we'll want to specify which one we're sending to.  If you connect your board both by USB and Ethernet, it will show up as two boards in mchelper - a USB board and an Ethernet board.  So, one way we can decide which board we want to use is to check the type of the board. 
mcflash.onBoardArrived = function( board:Board )
{
  if( board.type == "USB" )
    mcflash.setDefaultBoard( board );
}

This would only set a board as our default board if it were a USB board.  Alternatively, we can check the location of the board to see which board it is.  If we look over at mchelper and see the IP address for our board is 192.168.0.121, then we can make sure we use that board as our default board as follows:
mcflash.onBoardArrived = function( board:Board )
{
  if( board.location == "192.168.0.121" )
    mcflash.setDefaultBoard( board );
}

If this doesn't make sense for your situation, you can ignore the incoming board messages and just find a board by address or location using getBoardByIPAddress( ) or getBoardByUSBLocation( ).  Internally, McFlashConnect will maintain a list of which boards are connected, and you can always use these methods to find a particular board.  You might use them as follows:
var myEthernetBoard:Board = mcflash.getBoardByIPAddress( "192.168.0.121" );
mcflash.sendToBoard( "/appled/*/state", [1], myEthernetBoard );

 


Multiple Boards

If you're using multiple boards, you'll want to use the ToBoard( ) variants of the send methods in order to send messages to a particular board.  
var myEthernetBoard:Board = mcflash.getBoardByIPAddress( "192.168.0.121" );
var anotherBoard:Board = mcflash.getBoardByIPAddress( "192.168.0.120" );
mcflash.sendToBoard( "/appled/*/state", [1], myEthernetBoard );
mcflash.sendToBoard( "/appled/*/state", [0], anotherBoard );

When receiving a message, you can check which board the message came from by comparing the OscMessage's from property to a Board's location property.  
onMessageIn( msg:OscMessage )
{
  if( msg.from == myBoard.location )
  {
    // then do something here...
  }
}

 

Multiple Instances of Flash

If you have several computers running Flash, and you want them all to receive messages from any boards connected to mchelper, this is now possible.  Any messages that would normally be sent to your Flash movie from mchelper will be sent to all connected Flash movies.  Note that this requires mchelper 2.2.0 or later.

Imagine we have 3 computers, each running a Flash movie that wants to get info from a Make Controller.  We want to run a single instance of mchelper on one of those computers, and then connect to mchelper from each of the Flash movies.

We need to know the IP addresses of our computers in order to get this to work.  Say, for example, that our 3 computers have the addresses

  • 192.168.0.100 (this is the computer also running mchelper)
  • 192.168.0.110
  • 192.168.0.120

So, for the computer at 192.168.0.100, we don't need to change anything since the Flash movie will by default connect to mchelper running on the same computer.  On the computers at 192.168.0.110 and 192.168.0.120, we need to tell them to connect to mchelper at 192.168.0.100.

Do this right after you create your instance of McFlashConnect.  The code will look like

var mcflash:McFlashConnect = new McFlashConnect( );
mcflash.mchelperAddress = "192.168.0.100";

Now once you call mcflash.connect( ), you should see in mchelper that new connections were made from 192.168.0.110 and 192.168.0.120 once you fire up the movies on those computers.

 

Security

The Flash security model has some rather strict requirements, and one of them has to do with connecting to an XMLSocket, which is how Flash connects to mchelper.  This most often happens if you've created a movie that you're running standalone - if you get errors that Flash is not able to open an XML connection, right-click and go to Options -> Advanced -> Global Security and configure your trusted directory to allow for connections to mchelper.
 

Next Steps

Steal elements of these examples and implement them in your own movies - expand them into more exciting interactive movies.

The model of sending messages, from the LEDcontrol file, and reading messages, from the analogin file, can be easily applied to the other subsystems of the Make Controller - see the OSC reference and explore some of the other devices on the Make Controller via Flash.