|
PRODUCTS
|
|
||||||
 |
|
Max/MSP |
|
|
| A guide to Teleo and Cycling 74's Max/MSP: |
|
|
|
|
|
||||||||||||||||||||||
|
|
||||||||||||||||||||||
|
INTRODUCTION |
Cycling 74's (http://www.cycling74.com) Max is a graphical programming environment which is ideal for controlling Teleo Systems. People who have never programmed before can give their systems behaviors with Max in a very short time. In addition, there is a huge range of objects both provided with Max and available separately. MSP and Jitter packages, for example, permit the easy integration of real world mechanisms with complex sound (MSP) and video (Jitter) processing objects.
The following describes the Max environment in some detail. The intention is to provide a very quick introduction to Max as it might be used with Teleo products. The definitive Max Tutorials are provided by Cycling '74 (http://www.cycling74.com) on their documentation page (http://www.cycling74.com/products/dldoc.html). These are excellent documents and should be referred to for a detailed introduction.
Programs are constructed in Max by creating intercommunicating groups of objects. Each object is passed information, does a small portion of the overall work and sends the results on. This model is called dataflow. A simple Max program is presented below.
Sample Max ProgramYou can see, some numbers are connected to a Max object, +. The + object adds the numbers together and sends the answer on to the next object. The > object compares incoming values and outputs a 1 if the left number is greater than the right number. Since 8 + 6 is indeed greater than 10, you see the > object has sent a 1out.
You can immediately see some of the enormous advantages to Max:
- you can program by laying out objects and linking them up
- you can mix user interface and program elements easily
- you can see what a program does just by looking at it and knowing what the objects do
- no mystical processes to get the program into runnable form
- programming with Max is fun
The task of programming in general amounts to thinking about the behavior you wish you program and breaking it up into smaller pieces. Max makes this easy by having hundreds of objects available to you that perform the functions that other programmers have found useful. Programmers need never learn the intricacies of C / C++ / Java syntax, compilers, etc. What you do need to learn, however, beyond the basics of the environment and programming fundamentals is what objects are available and what they do.
|
MAX/MSP SETUP |
1. Install Max2. Download and install the Teleo Max externals, (http://www.makingthings.com/teleo/products/downloads/max_externals.htm). When you download and expand the .sit file you'll see a folder on your desktop. Inside this are three sub-folders: Externals, Extensions, Help. Put the contents of the Externals folder into the Max externals folder. Put the Extensions content into the System extensions folder and the Help contents into the max-help folder.
3. Depending on your OS - you may have to perform some extra steps to install the FTDI driver. See the ReadMe that is included in the .sit file.
|
THE MAX ENVIRONMENT |
When you first run the Max program, you might see the MIDI setup dialog. This presents the options for sending and receiving MIDI data. If you are using Max by itself, or with the Teleo set, you won't need to worry about this. You can either CANCEL or OK out of this.
The Max Window appears next. This is the window that Max uses to record messages for the user.
Max Window (OS X) Next, select File, New, Patcher. A new window will appears in which you can write Max programs. When it first appears it will be Locked. This means that the window is in a mode to run programs and allow users to interact with them. Under OS X, the window looks like the image below.
When you want to write programs you need to unlock the Patcher by pressing the Lock / Unlock Button.
 |
| Locked Patcher Window (OS X) |
Under OS 9, the Lock / Unlock Button is on the other side and is indicated by the padlock icon.
 |
| Locked Patcher Window (OS 9) |
Once the Patcher is unlocked, the program in the window can be modified. As part of this process, the Palette is revealed. The palette provides a way to select some of the more frequently used objects.
 |
| Unlocked Patcher Window (OS X) |
The palette is very similar under OS 9.
 |
| Unlocked Patcher Window (OS 9) |
The patcher window can be locked again by the same process.
|
MAX PROGRAMMING BASICS |
In this section, we'll go over some of the basic concepts that you'll need in order to program with Max.
Objects perform the bulk of the work in Max programs. Objects exist to perform a huge variety of functions: mathematical, musical, presenting user interface, and, with Teleo, interfacing with the real world.
Create an Object by selecting the Object Box from the palette.
Selecting the Object Box from the Palette Once the Object Box tool has been selected from the Palette, click in the main area of the Patcher Window to place a new Object.
Creating a New Object Once the object location is set, Max presents the New Object dialog. This dialog presents some of the possible Max objects that can be created. Double-clicking on the item corresponding to the object will cause it to be made. Scroll down to see the whole selection.
The New Object dialog can be sidestepped by clicking in the blank Object once it is placed. The name of the desired object can be entered directly into the object. You may need to do this later for Teleo Objects.
For our tutorial, we'll start with the Metro object. Select it by scrolling down the right hand list and double-clicking on the appropriate item. The fact that the name "Metro" is short for "Metronome" gives a clue as to what it does - it generates messages at regular intervals.
Metro Object Visually, objects have several parts as highlighted below.
Object PartsThe parts are as follows:
The Object Name is the name of the object.
Inlets represent places for information to get into the Object.
Outlets represent places for information to get out of the Object.
The Resize Handle allows the object's size to be changed.
The Metro object is used a lot in Max programs to provide regular messages to trigger other processes. To get this working, we'll need to place another two objects.
We'll need two Button objects. The Button Object is frequently used, so it appears on the main palette. Click on the appropriate icon to enable Button Object placement, then click in the window to place it.
The Button Object is on the Palette Place two Buttons, one above the Metro's left inlet, and the other one below the left outlet.
Metro with two buttons You can see from the appearance of the button objects that they share some features with the Metro object, but instead of a name, they have a graphical component.
To make a functional program we need to make connections between all the objects we've made. This is done by drawing lines between objects' outlets and inlets.
Place the mouse over the outlet (lower black block) of the top Button object. Immediately the outlet expands and the status bar on the bottom of the window names the object and says what the outlet does. When you click the outlet, and move the mouse, you are then able to see a connection ready to be made.
Ready to Connect When the mouse is brought over the leftmost inlet of the Metro, the inlet expands to indicate its readiness to be connected to and the status bar indicates the name and other information. When the mouse is clicked over the inlet, the connection is made.
Connection Between Button and Metro One thing about the connection mode which can be slightly frustrating is leaving it without making a connection. If once you have started to draw out a connection, you then decide you don't want to any more, click on some part of the window with the Command key down and the connection mode will be cancelled. We often found ourselves wishing the Escape key did this, but it doesn't seem to.
If you ever need to make connections that go around an object or if you're the kind of person who can't abide non orthogonal lines, you can click in the window while you're dragging the connection out. Each click will add a corner to the connection.
Deviant Connection To continue with our program, the connection process can be repeated to connect the outlet of the Metro to the top of the lower button.
Connection Between Metro and Button Now we have the beginnings of a program. In Max there is no specific action the programmer needs to take to make the program work. Everything's running as soon as it's placed and connected.
UI objects (e.g the Button), however, do not accept input until the Patcher window is locked. Locking the Patcher hides the object palette, leaves the set of connected objects and activates the input functions of the UI elements.
Locked Patcher
Notice that there are subtle differences in the way the various objects are rendered when the Patcher is in Locked and Unlocked state like Inlets and Outlets become less prominent, Objects are rendered in gray, etc.
Once the patch has been locked, try clicking on the upper button.
Clicking the Upper Button What you will see is the button activating under your mouse, and then, almost immediately, the lower button will activate too.
What's happening? When you clicked on the upper button, it sent a message to the Metro object via the connection you made. The Metro object then commenced producing its messages - sending regular messages out from its outlet. Each of these messages is sent via the second connection you made to the lower button (which now functions as an indicator). When the lower button receives a message, it illuminates for a short time. If however, the button receives another message before it goes off, its internal timer is reset and it stays on. With repeated rapid messages, the button will stay solidly illuminated.
To actually see a flash with every message we need to slow the Metro down a bit. There are two ways to do this: with arguments and with messages. Let's look at the argument method first.
An argument is a further specification or command given to an object to make changes to the way it operates. Arguments are given to Max objects by extending the object's name line to include extra information. In this case, if a numerical argument follows the "metro" name, the number is interpreted by the metro object as a period in milliseconds the metro should adopt.
Add an argument by first unlocking the patch, then position the mouse in the Metro's name area and click. The whole name highlights. Click again on the end of the word, or use the right arrow to get the cursor to the end of the object name. Now type "1000" preceded by a space. When you're done click outside the object and you should see something like the image below.
Adding an Argument to the Metro Object The argument you've now supplied to the Metro object tells it that you want a new Metro object to be created with a period of 1000ms - or one second. You can confirm this when you return the Patcher to Locked and click on the upper button again. Now you'll see the lower button flash once per second.
Max makes it easy to add arguments at the time objects are created. After the object is chosen from the New Object Dialog, Max sets the object up and leaves the cursor positioned in the object ready for the user to supply arguments.
The other way to change the Metro's time period is that you can send a message into its right inlet. One way to do this is with a Message Box. To do this, once again unlock your Patcher to reveal the object palette.
Selecting the Message Box Click on the mesage box icon. When you next click on the window, a message box will be created where you click. Place the message box and enter the value "500" into it. Connect it up by clicking on the outlet of the message box and then clicking on the right inlet of the Metro.
Adding a Message Box When you go back into Locked mode and click on the Message Box, you'll notice the flashing of the yellow block happen every 500ms - or twice a second.
The Message Box is a good way to send fixed messages into an object. Note that the message will not be sent until it is activated in some way.
Another way to send a message is the Number Box. The Number Box is another very frequently used object you can get from the palette. Use a Number Box to get a number that you can easily change into a Max Object.
Selecting the Number Box Place the Number Box and connect it to the same right inlet of the Metro. You may need to do a little re-arranging to make it all fit nicely. You can move objects by clicking on them and dragging. As you move objects around, all connections stay connected.
Adding a Number Box When the Patcher is locked again, you'll be able to click on the Number Box and type values into it. You can also click on the Number Box and drag up and down to change the value. Trying values between 500 and several thousand will convince you that the Metro is changing its period every time it's sent a new number.
Note that there are now two objects (the Number Box and the Message Box) connected to the right inlet of the Metro. This might seem to present a conflict, but two connections converging on a single inlet indicate two possible sources for data. The Metro will respond only to the last message sent, so if the Message Box is clicked and the value 500 is sent to the Metro, then the previous period will be replaced by 500. Then if a new number is sent from the Number Box to the Metro that number is adopted by the Metro.
Now it would be good to start to do something more interesting with the output of the Metro. To do this we can begin by removing some of the existing program.
Selecting Objects and Deleting them. Next, create a new Counter object the same way we created the Metro object - by selecting the Object Box from the palette and chosing "counter" from the New Object dialog.
Adding the Counter Object Once the Counter object is placed you'll see that it has quite a few inlets and outlets. We'll just be using a few here.
Now add another Number Box - you can either select, copy and paste the one that is already in the Patcher or just grab a new one from the Palette. Then connect the outlet from Metro and connect it to the leftmost inlet of the counter, and connect the leftmost outlet of the counter to the inlet of the Number Box. When you're done you should see something like the following.
Metro with Counter As soon as you connected the Counter up to the Number Box, you will have seen numbers counting up. That's what counter does: it counts messages it receives and outputs the result. The Number Box, now acting as a display object, displays the number it receives.
With the Patcher locked again, you can again experiment with changing the period of the Metro. Since the results of the fast moving counter are easy to see, you can set the Metro time period all the way down to 1ms.
This program fragment gives you an idea of the compositional nature of programming in Max - the idea of each object performing some small function and then passing its results on.
The Counter object will just keep counting upwards forever unless we tell it otherwise. To change this we can set the minimum and maximum values we want the counter to assume. With these in place, it will count up to the maximum, reset to the minimum and start up again.
The Counter Minimum and Maximum inlets are its two rightmost. Counter will adjust its internal minimum and maximum values when it receives messages on these ports. We can provide these messages in any way we like. Most convenient for now will probably be more Number Boxes.
Counter with Limits Set This Patcher will repeatedly count from zero up to ten.
It is very important to understand how data flows in a Max program. Objects send data to each other in units called messages. The diagram below shows the program we've been developing with a diagramatical representation of the messages that flow.
Messages in the Running Program When we clicked on the top button to start things going, the button object sent a bang message to the Metro object. The bang message is used throughout Max as a trigger to all kinds of different activities. The arrival of the bang message triggered the Metro to start working. Once the Metro is triggered and is running, it regularly sends bangs out of its outlet at the Metro's current rate. In our program, these outoing bangs are sent to the Counter.
The Counter is designed to count bangs arriving into its leftmost inlet. Each time it receives one, the Counter updates its internal count and sends the count out of its leftmost outlet in a number message.
In Max messages can contain text, numbers, and lists made up of numbers.
One of Max's very nicest features helps with one of the most difficult problems in Max - remembering how to use an Object.
When the Patcher is unlocked, click on the Metro object. Click on Max's Help menu. The Help menu contains Help on "metro". Select this. You will see a full window appear with a great deal of information about the Metro object. The best thing about these Help windows is that they are actually Max Patchers, and so therefore can be manipulated and cut and pasted into your own programs.
Metro Help Window There are hundreds of Max Objects - both included in Max and available for free or for a fee. Major object sets are described below:
MSP - MSP is the Max Audio extensions library. These objects permit the loading, manipulation and playback of audio.
Jitter - is a new set of Max Objects for video and 3D graphics applications. People have frequently used Jitter and Teleo to build interesting projects. See the Jitter page at the Cycling '74 website (http://www.cycling74.com)
In addition, Max comes with a great deal of helper objects. Check out Select, Route, Print, Gate, Delay, Pipe and so on, all of which are documented in the Tutorials and Reference Guides.
This has been a very brief overview of programming with Max. As mentioned above, the definitive Max documention is provided by Cycling '74 (http://www.cycling74.com) on their documentation page (http://www.cycling74.com/products/dldoc.html). These are excellent documents which will guide you to advanced programming techniques.
A vibrant community of artists, musicians and others have created a large number of objects, hardware extensions and general know-how, much of which is available on the Cycling '74 Community Page.
|
TELEO OBJECTS |
As you might expect, the way we have chosen to provide access to Teleo Modules in Max is to provide a series of Teleo Max Objects. Some modules (e.g. the Teleo 10A Motor Controller Module) have only a single Max object associated with them others might have many (e.g. the Teleo Multi IO Module).
Firstly, ensure Max and the Teleo objects are correctly installed. Then follow the instructions in the Hardware Setup Guide.
Your computer will be connected as directly as possible to the Intro Module via a USB cable. Do not plug the USB cable into the computer indirectly via a hub or via the Mac keyboard.
Then a Teleo Network Cable will connect the Intro Module to any additional modules you include in your set up.
The system should be powered and the green LED's on the Teleo modules should be blinking about once per second.
Let's look at how you can use Teleo to get data in from the outside world. Connect some kind of sensor to the Multi IO's Analog In 0 device. See the Analog In section of the Teleo Multi IO Module User Guide for more details. The Analog In 0 device is marked A0.
Then create a Teleo Object , t.mio.ain to monitor that sensor and connect a floating point number box up to its leftmost outlet. See the t.mio.ain documentation for details. What you'll see if you've connected it all up correctly is a number in the number box that changes as the sensor reads different values.
How does this work? The diagram below shows a little of how this happens:
Teleo Input Device The first step in this process is the sensor provides a change in voltage to the Analog In device on the Multi IO. This voltage is read by the processor and converted into a number. At regular intervals, any change in this number is wrapped up in a message addressed to the Intro Module and is sent out onto the Teleo Network. The Intro Module picks up the message, ensures that it was received intact and then sends the message on via USB to the computer. The Teleo Max library picks up the message, decides which Max object should get it and delivers the message appropriately. The Max object (in this case, t.mio.ain) then turns the message into a Max message and sends it out on the leftmost port. From there the Max program can do whatever it likes with the information.
All this happens automatically, all you have to do is place the t.mio.ain object and hook it up. Max and the Teleo System does the rest.
The output process is almost as simple. To see how this works, hook some kind of device up to the PWM 0 connector (named P0 on the board) of the Intro Module. See the PWM section of the Teleo Intro Module User Guide for more details.
Then create a t.intro.pwm object and connect a number box to its leftmost inlet to provide control over the motor or light you connected. See the t.intro.pwm documentation for details. Now when you change values in the number box, the motor gets faster or slower or the light gets brighter or dimmer.
The diagram below shows how this works internally using a motor as an example device:
Teleo Output Device The sequence is begun by a new number arriving into the t.intro.pwm's leftmost input. The Teleo object takes this number and forms it into a message addressed to the PWM 0 device on the Intro module. The message is sent to the Teleo Network via USB and the Intro Module picks the message up, unpacks it and makes the appropiate change to the PWM signal being sent to the motor.
Each Teleo Module has one or more associated Max objects that permit the appropriate level of control over the devices the module provides.
Each of these max objects provides a different kind of facility. Here's a guide to help you choose which one is right for your application
If you want to: Then Use: Monitor the opening and closing of a switch or pushbutton. t.intro.din from the Intro Module Read the digital output of a chip running at 5V. If the chip runs at less than 5V check its datasheet to see how to interface it. t.intro.din from the Intro Module Monitor a sensor with variable output like temperature, light, magnetism, etc. t.intro.ain from the Intro Module Activate and deactivate a light with total current < 2A. If the current is >2A, use the output to switch a relay. t.intro.dout from the Intro Module or t.dout from the Digital Out Module Activate and deactivate a motor in one direction total current < 2A. If the current is >2A, use the output to switch a relay. t.intro.dout from the Intro Module or t.dout from the Digital Out Module Control the digital input of some piece of electronic equipment. Use a pull-up resisitor. t.intro.dout from theIntro Module or t.dout from the Digital Out Module Control the speed of a motor drawing less than 2A. Motor will not reverse - only run in one direction. t.mio.pwm from the Intro Module Control the brightness of a light drawing less than 2A. t.mio.pwm from the Intro Module Control the speed of a motor with continuous current of 2A or less both forwards and in reverse. Use limit switches, position sensors, use available brake, etc. t.mc2 from the 2 x 2A Motor Controller Control the speed of a motor with continuous current of 10A or less both forwards and in reverse. Use limit switches, position sensors, use available brake, etc. t.mc10 from the 10A Motor Controller Control the position of a Hobby Servo motor. t.servo from the Servo Module In many cases there are more than one device of a particular kind on a module. For example there are four Analog In devices on the Intro Module, six Digital Out devices on the Digital Out Module, two Motor Controllers on the 2x2A Motor Controller Module and so on.
The way we have arranged the Teleo Max objects is to permit them to accept an argument which specifies which device is being referred to. In the diagram below, the t.dout external which provides access to the functionality of the Digital Out Module is passed an argument (n) which specifies which Digital Out device the object refers to. The Digital Out Module actually has twelve Digital Out devices, so n may range from 0 to 11.
If the argument is omitted, the 0 device is assumed.
Teleo Module DevicesEach module on a Teleo Network must have a unique address for messages to be delivered properly. If you are just using an Intro Module you will never have to worry about this at all. Even if you are using more than one active module - say an Intro Module and a Servo Module you still don't have to worry since every module comes from the factory with an address that is the same as the Module's type. So the Intro Module will have one address (3) and the Servo Module will have another (5).
The time when addressing is an issue is when you need to use more than one of a single kind of module. For example, you might want to control more than 12 solenoids or LED's requiring you to use multiple Digital Out Modules. The problem is that each one of these Digital Out modules comes from the factory with a default address of 8, so they'll all have the same address and messages won't be able to be sent to them reliably.
To deal with this situation, we provide a simple procedure to change a modules's address.
1. A new address is chosen. Any unused address between 2 and 63 may be used. It would be wise to avoid the default addresses of any Teleo modules, but there is no conflict if that module is not used on this particular Teleo Network.
2. Create Teleo Max object for any device on that module is created, with the additional parameter of the new address. e.g. if a second Digital Out module is to be added at address 10, you might create the object:
t.dout @address=10
3.Connect a Max message box with the message t.address.set to the leftmost inlet of the t.dout object.
4. Press and hold the push button on the module for around 3 seconds, until you see the LED flashing rapidly.
5. Once the rapid flashing starts the button can be released,
6. Send the Max message by clicking on the message box. The LED should cease flashing rapidly and should return to its normal rate of about once a second. In addition, the Max window will say something like "setting address to 30".
Although one particular device might be used to send the t.address.set message to the module, the address affects all devices on that module. There is only one, common address for the entire module.
As you might have picked up in the procedure above, you can explicitly address a module on the network by adding the address attribute as shown below:
Teleo Module Addresses In this example there are five Teleo Digital Out Modules on the network, each of which has had its address changed as indicated.
Addresses work independently of devices as you can see from the following examples:
t.dout refers by default to the first (i.e. number 0) digital out device on the Digital Out Module at the default Digital Out address (8) t.dout 5 @address=10 refers to device 5 on a Digital Out Module at address 10 t.dout @address=11 refers to the first device (0) on the Digital Out Module at address 11.
| copyright © 2002-2004 MakingThings LLC |
