Using mchelper

« Return to page index

How to use mchelper (Make Controller Helper)

Getting Started

An overview of what mchelper does.

mchelper (Make Controller Helper) is an application that runs on your desktop and helps work with your Make Controller(s).  The main functions it serves are:

• Send manual commands to the Make Controller over USB and Ethernet.
• Provide a quick glance of some of the board's important properties.
• Upload new firmware to your Make Controller.
• Provide a bridge for Flash movies (or other XML based apps) to communicate with the Make Controllers currently connected.

The very first step, of course, is to download mchelper - check the Downloads page for the latest version.  This guide assumes that:

• You're running mchelper 2.5.0 or later on your computer.
• You're running Heavy 1.6.0 or later on your Make Controller.
  

Main View

The main view in mchelper shows:

• A list of connected Make Controllers - on the left, this window shows all Boards (both USB and Ethernet), showing first their name and then their location.  The icon indicates whether a board is connected via Ethernet or USB, and the IP address of the board is listed.
  
• The activity window - shows a transcript of all the messages going to and from the boards.  Each message includes the time it was sent or received, the contents of the message, and either its destination or source.
  
• The text entry line, at the bottom, is where to type new OSC messages to the board.  Either press the "Send" button to send it, or simply press return.  Messages get sent to the board that's currently selected in the list on the left, so first click on the board you'd like to send the message to, then enter your message and send it.  For more info about OSC and what kind of messages you can send - check out the OSC tutorial.
  

The mchelper main view

Messages in the dialog window are color-coded to indicate where they came from:

Board Actions

In the list of Boards on the left, you can right click them to see more options to interact with them.  These options are also available from the Board menu item.

If the board is running an OSC-enabled application (like Heavy), you can:

• reset the board - the board will reboot itself and start running agin
• prepare the board to have a new application loaded - click 'erase board' and the board will erase itself, disconnect, then reconnect as an "unprogrammed board" ready to have a new application loaded onto it.  If you have a v1.0 Controller Board (v1.1 or later is ok), this will not work and you'll need to manually short the erase pins to prepare it for upload.
• view the Inspector - see below.
  

Inspector

The mchelper Inspector

The Inspector provides a quick look at some of the important pieces of information about the currently selected board:

System

• Name - each Make Controller can be given a unique name.  This field is editable within mchelper - simply type in a new name.
• Serial Number - each Make Controller should have a unique serial number.  This is used mainly to create a unique Ethernet address for each board - boards on the same network must all have different serial numbers to work properly.  This field is editable - simply type in a new serial number.
• Version - shows the version of the firmware running on your Make Controller, "Heavy 1.6.2", for example.  This is not editable.
• Free Memory - shows the free memory available on your board.  This is not editable, and is usually only helpful as a diagnostic when writing your own programs for the Make Controller.

Network

• IP address - the network address of the currently selected Make Controller.  This is editable - type in a new address to set it.  However, if DHCP is selected this will have no effect.
• Router - the address of the router the board is currently using.  This is editable - type in a new rounter to set it.  If DHCP is selected this will have no effect.
• Mask - the currently selected board's network mask.  This is editable - type in a new mask to set it.  If DHCP is selected this will have no effect.
• OSC Listening Port - the port that the board is listening on for incoming OSC messages.
• OSC Sending Port - the port that the board will send outgoing OSC messages on.
• DHCP - whether the board is using DHCP.  DHCP allows the Make Controller to automatically get an address when connected to a network.  This is generally recommended, unless you're connecting the Make Controller directly to your computer.

Each of these properties corresponds to an OSC message that you can send manually to the board if you like.  The Inspector is a convenience for viewing and editing some of the most common ones.

Uploading New Firmware

Load a new program onto your Make Controller, either to update it or to run a program of your own creation.

New firmware (which must take the form of a .bin file) is uploaded onto the Make Controller Kit via USB. These can be downloaded from the MakingThings site, or you may create them yourself.

The first step is to get the board into upload mode, so it's ready to accept a new app - this process depends on whether you're running an OSC-enabled application (like Heavy) or something else.

OSC Erase

If you're running at least Heavy 1.6.0 and your Controller Board is version 1.1 or later, you can erase the board simply by right clicking on the board in the Boards list and selecting 'erase board'.  Once you've done this, the your board should drop off the Boards list and come back momentarily as an Unprogrammed Board.  At this point, double-click on the board, or select Uploader from the Board menu to bring up the Uploader dialog. 

Manual Erase

If your board is not running an OSC-enabled app or it's earlier than version 1.1, you need to erase it manually.  This is also the way to erase a board that is not responding to the above method.  

There are just a few steps:

• You'll need to make contact between the two pins labeled ERASE on the Application or Interface Board - these are located near the top left corner of the Controller Board, and the labels might be pretty small!.  Connect these pins with any piece of metal (screwdriver, paper clip, etc) to erase it.  If you're doing this often, it might be convenient to connect a pushbutton between these two pads so you can use it to erase your board.
• Unplug and replug the board to reset it.  When you plug it back in, the board should pop up in the list on the left as an Unprogrammed Board.  Double click on it, or select Uploader from the Board menu to bring up the Uploader dialog.

Upload Dialog

The mchelper Uploader dialog

Platform Specific Notes

Windows

On Windows, you need to install USB drivers twice:

• the first time the board is plugged in while it's running heavy.
• the first time the board plugged in when it's in upload mode.

For each of these cases, the device manager will pop up alerting you that new hardware has been detected.  Tell it to install automatically and it should be able to find the appropriate drivers. It will also warn you that the driver is not certified - this just means that nobody has paid Microsoft the fee they require to prevent that dialog from coming up!  Press "continue anyway" and all is well.

As of 06/2009 we don't have support for uploading new firmware on Vista 64-bit.  Other Windows platforms are supported, but Atmel (the chip manufacturer) has not yet released support for this yet.  We're currently working with them to try and get this together!

OS X

As of 10.5 (Leopard), changes were made to the USB system that require an extra setup step.  In the mchelper download, install the OS X Uploader package which will allow you to upload new firmware successfully to your board.  It's best to do this before plugging your board in.

Next Steps

Once you've uploaded new firmware, the Uploader dialog will close.  If the board does not appear momentarily in the Boards list, try disconnecting and then reconnecting your board.

Once it shows up in the list of boards, you may want to give the board a quick test to confirm it's working.  A good way to do this is to send an OSC message from the "Dialog" view.  When the board pops up in the list on the left, try typing

/appled/0/state 1

and then hitting return, or pressing the Send button.

You should see one of the LEDs on the Application Board light up. Then, if you send

/appled/0/state 0

you should see it turn off.  If you're using an Interface Board you don't have any appleds, so you can send a message like

/led/state 1

instead.  You should see the green LED on the Controller Board light up for a moment before resuming its normal blink pattern.

Connection to Flash

mchelper can connect to Flash (and other desktop applications) to communicate with the Make Controller.

Mchelper can also connect to Flash and route messages to and from any of the connected boards to your Flash movie.  For full documentation on using the Make Controller Kit with Flash, check:

• The Flash tutorial.
• The Flash library reference.

mchelper will listen on a given port for connections from Flash movies.  By default, this is port 11000.  You can change this by clicking:

• File -> Preferences (Windows)
• mchelper -> Preferences (OS X)

and editing the "Listen for incoming XML server connections" port.

Some messages coming through mchelper from Flash.

Explanation