The Make Controller Kit is a great way to extend your Max/MSP applications into the real world by interfacing with sensors, motors, lights, and other electronic devices.  The Make Controller communicates with Max via OSC, a popular protocol used between otherwise disparate environments and devices. This guide will walk through how to set up to read sensors and control output devices from Max/MSP with the Make Controller Kit.

There are two ways to communicate with the Make Controller from within Max:

• via an Ethernet connection, using Max's built-in udpsend and udpreceive objects.
• via USB, using MakingThings' mc.usb external.

Both approaches use OSC, and you can use either or both of them at any given time.

 

Setup

There are a few things to download and install before we get going.

• Confirm you've uploaded and are running Heavy, the firmware on the Make Controller Kit.  You can download it here and follow this how-to to upload it.
• Download the OpenSoundControl and osc-route objects from CNMAT here, as they aren't included in the standard Max distribution.
• If you plan on communicating with the Make Controller via USB, download the mc.usb external - [ Windows ] [ OS X ].

Drop the external objects into your externals directory within your Max installation, follow any other instructions from each of the downloads, and we should be all set.

If you haven't already, check the OSC tutorial for a rundown on how messages to and from the board are structured.  OSC isn't too complicated, and it will be crucial to working with board in Max.

Controlling an LED on the Application Board is one of the simplest things to do from Max, making it an excellent first thing to try. The name of the LED subsystem on the board is appled - Application LED. There are 4 LEDs, num    bered 0 - 3, and the property of theirs that we're concerned with here is their 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

to turn the LED on, and

/appled/0/state 0

to turn the LED off.

Now, we'll take a look at how to send these messages to the board over USB, and over Ethernet.

Via USB

---

Note - you should only place a single mc.usb object in your entire patch.  You can easily get info in and out of it using the send and receive objects if it's not convenient to connect it to other parts of your patch by patchcord.

Set up a simple patch as is shown below.  With just these couple of objects, we can send messages to the board to turn an LED on the Application Board on and off.  When you place the mc.usb object into your patch and connect the Make Controller Kit to your computer, you should see a message in the Max window that mc.usb connected to your board successfully.

There are two ways to get messages back from the board.  One is to ask the board each time you want a message.  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.  If you want to use the manual style, jump down to that section. 

Autosend

First, 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.  Read on below to see how to deal with the incoming messages.

Manual Reads

To manually read an analog input, we need to send an OSC message to ask for the current value, and the board will send an OSC message back with the value. Unlike the OSC messages sent to the LEDs, an OSC message asking to read a value will not have an argument on the end of it.

The name of the analog input subsystem is analogin, there are 8 devices numbered 0 - 7, and they have a value. 'Read' messages have the form /subsystem/device/property, with no argument.  So, our message to read analog input 7, the trimpot, will look like

/analogin/7/value

Note there's no argument after our address, so the board will know it's a read, and not a write.  We expect the board to send back a message like

/analogin/7/value 925

so we know the value of analogin 7 is 925.

Via Ethernet

We're going to set up to read analog in 7 10 times a second, or once every 100 milliseconds.  To do this we'll use the metro object to send out our message as often as we want.

There are a handful of externals that make it easy to use the Make Controller in Max.  Note that all the externals aside from mc.usb are simply Max abstractions that make it easy to form the correct OSC messages.  You can always form the OSC messages yourself - the list can be found here.

Externals

mc.usb mc.analogin mc.appled mc.digitalout	mc.dipswitch mc.servo mc.motor mc.stepper

mc.usb

mc.usb is the base object that connects to the Make Controller Kit and sends/receives messages to and from it. If you want to communicate with the Make Controller over USB in Max, you need just one of these somewhere in your patch.  It can be helpful to connect send and receive objects on either side of it to get messages to and from the other mc objects, as opposed to connecting them all with patch cables.

Input
Messages sent in the left (and only) inlet will be sent to the Make Controller.  These should be formatted as OSC messages.

Output
Messages coming out of the left (and only) outlet of mc.usb are OSC messages from the Make Controller.   You can either route these yourself, or send them straight to one of the other mc objects which will filter out the messages that it cares about.

 

mc.analogin

mc.analogin receives messages from either the mc.usb or udpreceive objects, filters them, and outputs the values for each of the analog inputs on the Make Controller Kit.

Input
The left inlet expects messages from a udpreceive object and the right inlet expects messages from mc.usb.  If the messages coming in don't contain any analogin information, nothing will come out the outlets.

Output
The 8 outlets correspond to the 8 analog inputs on the Make Controller Kit, numbered 0-7 from left to right.  These will output an int when an analogin value comes back from the board.

 

mc.appled

mc.appled accepts on/off signals (as from a toggle) to turn the LEDs on the Application Board on and off.

Input
Each of the 4 inlets, 0-3 from left to right, correspond to the 4 LEDs on the Application Board.  A 1 will turn them on and a 0 will turn them off.

Output
The properly formatted OSC messages that can be sent either to an mc.usb or udpsend object, which will in turn send the message to the board.

 

mc.digitalout

mc.digitalout accepts on/off signals (as from a toggle) to turn the digital outputs on the Application Board on and off.

Input
Each of the 8 inlets, 0-7 from left to right, correspond to the 8 digital outputs on the Application Board.  A 1 will turn them on and a 0 will turn them off.

Output
The properly formatted OSC messages that can be sent either to an mc.usb or udpsend object, which will in turn send the message to the board.

 

mc.dipswitch

mc.dipswitch receives messages from either the mc.usb or udpreceive objects, filters them, and outputs the values for each of the channels of the DIP switch on the Application Board.

Input
The left inlet expects messages from a udpreceive object and the right inlet expects messages from mc.usb.  If the messages coming in don't contain any dipswitch information, nothing will come out the outlets.

Output
The 8 outlets correspond to the 8 channels of the DIP swtich on the Application Board, numbered 0-7 from left to right.  These will output a 0 when a channel is off and 1 when a channel is on. 

 

mc.motor

mc.motor controls the speed and direction of up to 4 DC motors connected to the Application Board.  mc.motor has 4 inlets which correspond to 4 possible motors connected to the Application Board, numbered 0-3 from left to right.  Check the DC motor how-to for how to use a servo motor with the Make Controller.

Input
Ints will set the speed of the motor - the range 0 - 1023 represents stopped to full speed.  A 'direction x' message will set the direction - the 'x' should be a 1 to set the direction to forward and 0 to set it to backward.

Output
The properly formatted OSC messages that can be sent either to an mc.usb or udpsend object, which will in turn send the message to the board.

 

mc.servo

mc.servo controls the speed and direction of up to 4 servo motors connected to the Application Board.  mc.servo has 4 inlets which correspond to 4 possible servos connected to the Application Board, numbered 0-3 from left to right.  Check the servo how-to for how to use a servo motor with the Make Controller.

Input
Ints will set the position of the servo - the range 0 - 1023 is the 'safe' range, which won't hard your motor but you can get a full 180 degrees of rotation using the range from -512 to 1536.  A 'speed x' message will set the speed - the 'x' should be within the range 0-1023.

Output
The properly formatted OSC messages that can be sent either to an mc.usb or udpsend object, which will in turn send the message to the board.

 

mc.stepper

mc.stepper controls the speed and direction of up to 2 stepper motors, either bipolar or unipolar, connected to the Application Board.  mc.stepper has 2 inlets which correspond to 2 possible stepper motors connected to the Application Board, numbered 0-1 from left to right.  Consult the stepper motor how-to for a description of how to use stepper motors with the Make Controller Kit.

Input
A variety of messages can be used to control the stepper motors:

• An int will set the position requested.
• A 'position' message will send a request to the board for the current position of the motor
• A 'speed x' message will set the motor's speed to 'x', which should be an int from 0-1023.
• A 'duty x' message will set how much power the motor is using to 'x', which should be an int from 0-1023.
• A 'bipolar x' message will configure whether the Make Controller tries to drive a unipolar or bipolar motor.  When 'x' is 1, it will drive a bipolar motor and when it is '0' it will drive a unipolar motor.
• A 'halfstep x' message will configure whether the Make Controller tries to drive in halfstep mode or not.  When 'x' is 1, it will drive in halfstep mode, and when it is '0' it will drive in normal step mode.

Output
The properly formatted OSC messages that can be sent either to an mc.usb or udpsend object, which will in turn send the message to the board.

 

 

 

So what next?  Now that you've got the basics of sending and receiving messages, you're ready to get down to business.  You'll probably want to browse the list of all the OSC messages that the Make Controller Kit knows how to respond to, and experiment with including them in your patches. Check the OSC reference for the master list of messages, and have at it!

Troubleshooting

---

Perhaps things didn't go all that smoothly.  Here are a few common things to double check.

• If you're communicating via Ethernet, make sure you haven't left mchelper open at the same time.  It will try to listen to the same port that Max will, and only one at a time will work.
• If you're communicating over Ethernet, make sure you can successfully communicate with the board over the network in mchelper before attempting it in Max.  This can sometimes be tricky depending on your setup, and it's usually best to strip down to just mchelper and the board to get it working.
• Make sure you've downloaded, unpacked, and installed the external objects (mc.usb and the OSC objects) properly.  Carefully follow the directions included with each of those downloads, and go back and reinstall if you're having any issues.
  

If you're still stuck, post to the forum, or come chat on IRC in #makingthings on irc.freenode.net and ask for help.