A great way to add wireless control to your Make Controller projects is using the XBee wireless modules from MaxStream.  These are cheap (starting at $19), powerful little modules that are easy to work with.  Some of the of the feature highlights:

• Great range - up to 300 ft. (clear line of sight) for XBee and up for 1 mile (clear line of sight) for XBee Pro modules.
• 9 input/output lines for analog and digital IO
• Low power for long battery life - < 50 mA when working hard, < 10 uA when sleeping
• Easy serial interface
• 65,000 network addresses for each of 16 address channels - you can have LOTS of these boards in a network if you want
• Easy to integrate with the Make Controller:
  • MakingThings XBee Board plugs right into the Make Controller Kit, and has small form factor for remote sensing/control
  • Communicate easily with the modules via OSC or directly from your Make Controller programs

Disclaimer - there will be some soldering involved in getting this set up.  There are a number of different ways to use these wireless modules, so really the only way to allow for the widest range of possitibilities is to rely on you to select and put together the things you need.  Otherwise, we're imposing some situation that you might not need or want to pay for.  We know this is a little bit of a pain for people who don't/can't solder, but after some deliberation we decided it was the best way to go.

Disclaimer #2 - in order to make use of all the functionality in this guide, you'll need to make sure you're running the latest version of the XBee firmware, which does not usually come pre-installed.  You can use the Make Controller to upgrade it, but it requires a computer running Windows.  But don't worry - it's just a one time operation, so you can borrow your friend's computer and be on your merry way!  See the how-to here for details.

Shopping List

The general list of things we'll need is:

• The XBee module itself
• An adapter board to fit it onto the Make Controller or other breadboards
• Additional connectors and components if we want to connect sensors or other devices directly to the XBee modules

 

XBee Modules

Firstly, you'll need to purchase a pair (or more) of XBee modules - you need to have one for each of the devices you want to communicate between.

Because MaxStream doesn't let just anybody (ie MakingThings) distribute their modules, you'll have to buy the modules themselves elsewhere.  There are two options for the modules - the normal version and the Pro version.  Both will work just fine - there are just a few differences. 

The normal version has a range of 100 feet indoors, and 300 feet outdoors (clear line of sight).  The Pro version has a range of 300 feet indoors, and 1 mile outdoors (clear line of sight).  The Pro version also consumes a bit more power than the normal version.

Part numbers

• XBee (normal) module - $19, part # XB24-AWI-001-ND at www.digikey.com
• XBee Pro module - $32, part # XBP24-AWI-001-ND at www.digikey.com

Note - there are a couple different antenna options for each module.  The basic ones listed above should be fine, but you can browse them at DigiKey if you're so inclined.

Other Stuff

MakingThings provides a few products to make it easy to work with the XBee modules - the XBee Interface Board and the XBee Connector Pack. 

You'll definitely want to get an XBee Interface Board (or make your own) for each XBee module, while you'll only need the Connector Pack if you want to connect sensors and devices directly to the XBee module.

Next, we'll get into how to physically connect your modules, and then how to configure and use them.

Note - this tutorial contains lots of concepts and reference material.  If you're feeling impatient, you might just want to jump to the sample setup page to get started, then come back and fill in the blanks.

This part of the tutorial will be based on MakingThings products - the XBee Interface Board, and the XBee Connector Kit.  If you're using other parts, it shouldn't be too hard to adapt the info to fit your situation.  First we'll go over how to assemble the XBee Board, then how to connect some sensors to it.  Click on any of the images for a larger, more detailed version of them.

Interface Board

The MakingThings XBee Interface Board converts the pin spacing on the XBee modules to standard 0.1" spacing, which makes it easy to plug it into the Make Controller Kit serial port, or your own breadboards.  It also allows you to put a power circuit on the board for when you want to run it off batteries or some other power source.  If the board is just plugged into the Make Controller Kit, it can be powered from there and doesn't require any additional components. 

To plug the XBee module into the XBee Interface Board, it's highly recommended to solder the small 10-position headers in the Interface Board.  It's possible to solder the XBee module directly into the Interface Board, but you'll usually want to be able to plug/unplug it, so the sockets are the way to go.  These go into the smaller, inner rows of pads on the Interface Board, as shown below.

Additional Connectors & Components

So now we want to set an XBee board up so we can plug some devices into it.  The MakingThings XBee Connector Pack provides a handful of parts to actually get the XBee module connected to your Make Controller Kit and some other sensors. 

If you want to connect any additional sensors directly to the XBee module, you'll also need to solder in the regulator and capacitors included in the XBee Connector Pack.  These go down at the bottom of the board in the spots labeled IC1 (a 3.3V regulator), C1 and C2 (0.1 uF capacitors). We need these because the XBee modules run at 3.3V and we need to convert the voltage (9V, others) of any batteries you use to power it.  To do this, insert the regulator as shown below, and two capacitors.  Make sure that the long leg of your capacitors is plugged into the right-hand side. 

Now, we need to solder some connectors onto the board as well.  This step might vary depending on your setup.  It's possible to solder headers (male) onto the bottom of the board so you can then plug it into another breadboard. 

In this example, we're going to solder sockets (female) onto the topside of the board so we can plug sensors directly into them.  The MakingThings XBee Connector Pack has a 14-position socket, which goes along the right side with all the inputs, and an 8-position socket that goes along the left side with the power connector and others.  See the image below for an example of these sockets all plugged in successfully.

Lastly, we need to get a sensor plugged in there!  For this example we'll just take a potentiometer since that's pretty simple.  The MakingThings XBee Connector Pack also comes with some headers that will fit with the provided sockets.  You'll probably want to snip these headers into just the number of connections you need for each sensor.  We'll snip out a 3-position strip since our potentiometer has 3 wires that we need to connect.  Solder the tips of the wires onto the short side of the headers. 

That's it!  If you have more sensors to plug in, you can split the power connections between them as shown in this how-to.  If your sensors are particularly power hungry, you'll need to use a larger battery.  There are lots of battery options at places like SparkFun.com.  Look for something that supplies a voltage needed by any sensors you want to use, but it shouldn't be anything much higher than 9 volts, ideally.

Note - the VREF pin on the XBee module is by default connected to 3.3V on the XBee board.  This is usually convenient since the board runs at 3.3V.  In the cases where you want some other reference voltage for your inputs, you can snip the trace between the two pads (labeled VREF) in the middle of the board, and connect whatever you like to the VREF pad.

This page jumps straight into setting things up, without too much explanation.  The following pages go into more detail on some of the concepts involved, but the hope is that this should get you up and running quickly.

For this example, we'll assume that we're using 3 XBee modules - 1 receiver module connected to the Make Controller, and 2 remote modules with sensors connected.  The concepts here can easily be adapted to work with more than 2 remote modules. 

We're assuming that the modules are wired up, as described in the previous sections.  After that, the basic outline is as follows:

1. Configure the remote modules.  To configure them, we'll need to plug them into the Make Controller.  Then once they're configured, we'll disconnect them and send them on their way.
   
2. Configure the receiver module.
3. Start listening and reading the data.

Note - as we're cruising along, remember the reference for all XBee OSC info can be found here and here.

Configure the remote modules

For each of the remote modules, we'll want to:

• Set their address, so we can tell them apart
• Configure which inputs they should be reading
  
• Set how often they should read the inputs

To configure an XBee module it must be connected to the Make Controller's serial port, as shown in the Plugging In section.  Then, remember that we need all our boards to be in packet mode - otherwise, it won't respond properly to any of our other messages.  To do that, send the message

/xbeeconfig/packet-mode 1

Set the address

The specific address you choose doesn't matter too much, but you should remember which address you've given to which board, so you know which messages are coming back from it.  I always like to put a little sticker on the module itself with the address I gave it, just so I don't get confused later.  We'll set the address of our first module to 12 - so, send the message

/xbeeconfig/address 12

Configure the inputs

On our first module, we're just connecting a single sensor to analog in 0.  So, we need to set the XBee module to read In0 as an analog in.  To do this, send the message

/xbeeconfig/io0 2

Note that along the right side of the XBee board, all the inputs are there, labeled AD0 - DI8.   The input's number corresponds to the io property that we'll use to configure it.  The value that comes after that specifies whether that input is an analogin (2), a digital in (3), or disabled (0).  So, to set input 8 to disabled, we'd send the message

/xbeeconfig/io8 0

Set the sample rate

Now we need to set how often the module should read In0.  We'll set it to read every 50 milliseconds.  To do that, send the message

/xbeeconfig/samplerate 50

If you ever want your board to stop sending messages altogether, just set the sample rate to 0.

Lastly, and very importantly, we need to remember to save all the configuration changes we've made to the module.  Otherwise, it will revert to its defaults when it reboots.  To save the changes, send the message

/xbeeconfig/write 1

If something doesn't seem to be working quite right, you can always read back any of these settings to be sure.  Now, repeat these steps for any additional modules you have, but make sure to give them different addresses.

Configure the Receiver Module

There's not too much to do with the receiver module.  But, make sure it's in packet mode.  Again, once you plug it in, send the messages

/xbeeconfig/packet-mode 1
/xbeeconfig/write 1

Start Listening and Reading the Data

The last step is to start reading in the XBee messages.  To do this, the easiest thing is to use autosend.  This way whenever a message from an XBee module arrives, the Make Controller will make an OSC message out of it and send it back to us.  To do this, 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

or if you want USB, send the message

/system/autosend-usb 1

Next, decide how often you want the Make Controller Kit to check for new 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 XBee autosend on.

/xbee/autosend 1

Now, you should have the sensors plugged into the remote XBee modules and the receiver module plugged into the Make Controller.  If you've done everything successfully, you should see a bunch of messages streaming into mchelper that look like

/xbee/io16 12 31 1023 0 0 0 0 0 0 0

This is a message back from one of the remote modules.  As is explained in the OSC reference, the first two numbers are:

1. the address of the module that sent the message (12 in the example above)
2. signal strength (31 above)
   

The next 9 numbers are the values from the 9 IO pins on the XBee module.  So, this is a message back from the board that we gave address 12, and 1023 is the value from the sensor that we have plugged into In0 on that module.

Admittedly, seeing all that data streaming into mchelper is not all that helpful.  But, it is a good way to confirm that we're getting messages back from the modules.  Now you're ready to head into your environment of choice and start reading all sorts of XBee goodness.

The XBee modules have two modes of operation:

1. Transparent serial port mode.  This mode is the simplest - you send data over a Make Controller's serial port to an XBee module which sends that data wirelessly to another XBee module, also presumably connected to a Make Controller, which can then read the data from the serial port.  So, it's like a big, wireless serial connection between the two Make Controllers, hence the name.  Clever, eh?
   
2. Packet mode.  If you want to actually send messages to the XBee module itself, however, you need a way to distinguish that from data that should be sent transparently.  There are a few different kinds of packets, but we'll most concern ourselves here with IO packets and command packets.  IO packets are what an XBee module sends when it has sampled its inputs.  Command packets are used to set some configuration option for the module itself.  Packet mode is nice because then we get to see a bunch of important information about each packet - who it came from, the signal strength, and things like that.
   

We'll be using the modules pretty much exclusively in packet mode.

Receiving Packets

For the most part, incoming packets aren't too interesting if they just show up at your XBee module - unless they're directly controlling its output pins, for example.  Otherwise, you'll want to get the info in the incoming packet to the Make Controller and/or up to your computer.  If you're doing this in firmware, all you need is the XBee_GetPacket( ) function.  Over OSC, however, you have a couple options:

1. You can periodically send the Make Controller a request for new packets.  If any have arrived, since you last asked they'll be sent back to you.  Unfortunately, the problem with this is that the Make Controller only has room to hang onto a couple of packets at a time - any packets that arrive after it's full will be lost.  To get around this,
   
2. You can use the autosend capability.  The Make Controller itself will constantly be checking for new packets and when one arrives, it will send it out automatically.  To do this, turn autosend on by sending the message
   

   /xbee/autosend 1

   Then, you need to set how often you want the Make Controller to check for new messages, and whether to send it over Ethernet (Udp) or USB.
   

   /system/autosend-interval 10
   /system/autosend-usb 1
   

   So we just set it to check for new messages every 10 milliseconds (100 times a second) and to send those messages over USB.  If we wanted them to be sent over Ethernet, we would send the message
   

   /system/autosend-udp 1

There are 9 IO pins on the XBee module, abeled AD0-AD6, DIO7 and DI8.  AD0 - AD6 can be set as digital or analog inputs, DIO7 can be a digital in or out, and DI8 can only act as a digital in.

Pins can be set to one of 5 values:

• 0 - Disabled
• 2 - Analog Input
• 3 - Digital Input
• 4 - Digital Out High/On
• 5 - Digital Out Low/Off

In OSC, use the /xbeeconfig/io properties to do this - just append the number of the input pin onto the io part of the message.  For example, to configure AD4 as an analog in, we'd send the message

/xbeeconfig/io4 2

Note that we added the 4 on the end of io and used 2 to specify that it should be an analog in. 

To do this in firmware check the XBeeConfig_SetIO( ) function.

Sample Rate

If an XBee module's sample rate is set to anything greater than 0, it will read all its input pins at that rate and send a message with the values.  Once you turn the sample rate on, properly addressed modules will receive IO packets from that module.  To set the sample rate to once every 10 milliseconds via OSC, send the message

/xbeeconfig/samplerate 10

To do this in firmware check the XBeeConfig_SetSampleRate( ) function. 

Once you've set some values, try reading them back to make sure you can communicate successfully with the module.  If this doesn't even work, go back and check your work - bad connections are always a likely suspect.

As was previously mentioned, there are all sorts of additional configuration options for the XBee modules.  It's not practical to reproduce the entire manual in this tutorial, but you can download it from our datasheets section. 

There are 3 values that allow you to organize your XBee module address space:

1. Individual module addresses
2. PAN (Presonal Area Network) IDs
3. Channels

For two modules to communicate, they must be on the same channel, have the same PAN ID and the destination address of the sender must match the address of the receiver.

Each XBee module has its own unique address, as well as a destination address that it sends its messages to.  The destination address can specify a single destination or it can be a broadcast address, which will be received by all XBee modules within range.  The broadcast address is 65535 (0xFFFF in hex). 

If you only have a couple modules, you'll probably never need to change the PAN ID or channel.  But if you're in an evironment with a bit more traffic, you might want to be sure that nobody else's messages are getting mixed up with yours, so this offers a nice option for that.

Unique  and Broadcast Addresses

XBee modules can be used with 16-bit addresses or 64-bit addresses.  16 bits already gives you 65536 possible unique values, but hey you never know when you might need number 65537, right?  Any time a module's address is less than 0xFFFE, it will use 16-bit addresses.  When the module's address is set to 0xFFFF or 0xFFFE, it will use a 64-bit address derived from its internal serial number.

There are 2 values that configure the destination address - DH (Destination High) and DL (Destination Low).  If DH is set to 0, as it is by default, the board will send to a 16-bit address.  To send broadcast messages, which will be received by all modules on that channel and PAN, set DH 0x0000FFFF to and DL to 0x00000000 (default value).

There are a few usual suspects that will eliminate the majority of all problems. 

The first is connections, connections, connections.  It's worth going back over your solder joints, reheating them if necessary, and confirming that there are no shorts.  Especially on any sensors that you've wired onto the 0.1" headers. 

If you're getting funny readings out of your sensors, make sure the power supply to your XBee module is OK.  The best way to do this is with a multimeter - set it to DC volts and confirm it reads 3.3V when you connect between GND and 3.3V, and whatever your power supply is when you connect between GND and V+.

Lastly, it's easy to configure the settings on your XBee module and then forget to save them.  Then when you plug it back in, it reverts to its previous settings, behaving differently than you expect.  Plug the XBee module in question back into the Make Controller and read back the settings to verify they're as you expect.  If you need to, write them again and save them this time!

That should take care of the most common issues.  Otherwise, please post to the forum for more help.  Good luck!