Problem

You'd like to use mchelper to communicate with the Make Controllers it's connected to from a program or script you're writing on your desktop/laptop.

This requires that your programming environment supports TCP socket connections and XML creation/parsing.  These are, of course, common in most programming languages/environments.  This is how we've connected Flash to mchelper, so you can take a look at the source code to that for an example.

Solution

Firstly, you'll want to make sure you can make a connection to mchelper from your program.  If mchelper is running on the same machine as your program, you'll want to open up a TCP connection at localhost on port 11000.  You can change which port number mchelper listens on in the mchelper preferences, but 11000 is the default.  If you've connected successfully, you should see a corresponding message in mchelper.

Once your connection is open, mchelper has only a few kinds of XML messages that it will send.  I'll list them here and go into them in more detail below.

• OSC packet - an OSC packet with one or more OSC messages has arrived from a board.
  
• Board arrival - a board has been connected to mchelper.
  
• Board removal - a board has been removed from mchelper.
• Board info - when a board's info has changed.  IP address, name, etc.

OSC packet

An OSCPACKET specifies the ADDRESS and PORT that it came from, and then has a list of one or more MESSAGE elements in it.  Each OSC message contains a NAME and zero or more ARGUMENT elements.  Each ARGUMENT element specifies its TYPE, which can be i (integer), f (float), s (string) or b (blob).  The argument's VALUE holds the actual data. 

Example

<OSCPACKET ADDRESS="192.168.0.200" PORT="10000">
  <MESSAGE NAME="/analogin/0/value">
    <ARGUMENT TYPE="i" VALUE="768"/>
  </MESSAGE>
  <MESSAGE NAME="/analogin/7/value">
    <ARGUMENT TYPE="i" VALUE="1023"/>
  </MESSAGE>
</OSCPACKET>

<OSCPACKET ADDRESS="COM7" PORT="0">
  <MESSAGE NAME="/analogin/0/value">
    <ARGUMENT TYPE="i" VALUE="768"/>
  </MESSAGE>
</OSCPACKET>

Board Arrival

A BOARD_ARRIVAL message is sent when a new board is connected, or when you've just connected to mchelper.  It contains 1 or more BOARD elements, each of which specifies the TYPE of the board, which can be USB or Ethernet, and the LOCATION of the board.  The board's location will be unique - an IP address for Ethernet boards and a USB device location for USB boards. 

Example

<BOARD_ARRIVAL>
  <BOARD TYPE="Ethernet" LOCATION="192.168.0.200"/>
  <BOARD TYPE="USB" LOCATION="COM7"/>
</BOARD_ARRIVAL>

Board Removal

A BOARD_REMOVAL message provides the same information as a BOARD_ARRIVAL message, but indicates that a board has been disconnected from mchelper.

Example

<BOARD_REMOVAL>
  <BOARD TYPE="Ethernet" LOCATION="192.168.0.200"/>
  <BOARD TYPE="USB" LOCATION="COM 7"/>
</BOARD_REMOVAL> 

Board Info

A BOARD_INFO message indicates that some configuration of the board has changed.  It contains one or more BOARD elements that specify the board's NAME, LOCATION, and SERIALNUMBER.

Example

<BOARD_INFO>
  <BOARD NAME="My Make Controller" LOCATION="192.168.0.200" SERIALNUMBER="12345"/>
</BOARD_INFO>

Discussion

Please share any scripts that you've created!