XBeeClient - an extremely easy to use XBee library for Gadgeteer

XBeeClient for Gadgeteer makes it extremely easy to add XBee wireless to your Gadgeteer projects. The API is designed to be simple yet powerful enough to make any XBee task a couple of lines of code. It makes testability a first class citizen and part of the user experience making it easy to get up and running. A MAJOR goal is an API so simple that it can be used in High School.

Project URL: http://XBeeClient.Codeplex.com

The best way to get the design document is by downloading the source, its in the solution folder. The document is also included with the Release files.

Please review the Getting Started Guide. Code review as well.

Please provide feedback on the codeplex project site. This project is open to contribution. Although this project is fully functional, there are numerous interesting problems left to solve, for example sending very large messages from the camera (hundreds of thousands of bytes).


For clarity, is this exclusively for mesh networks on Series 2 Xbees, rather than point-to-point on series 1? I don’t have any Xbees myself but the ‘shopping list’ link only mentions series 2.

Yes, just series 2 in API mode. It would be nice to support the series 1, and also to support AT mode, I’m guessing that 90% of the time folks just want to send a small string message. The important design consideration is getting the API right (clear, consistent, and usable).

Have you guys took a taken at this set of libraries developed by our community members:

Yes. The XBeeClient is driven by principles that didn’t belong in the XBee project (shot down in flames, unfortunately). First is ease of use, so easy it can be used in High School classroom settings, and easy to use for the Einsteins as well. Second is testability, built in tests that make it easy to diagnose what happened, and Third is API design and accompanying technical design documentation peer reviewed. Enabling the High School students to incorporate wireless in their projects is super important to me, so this drove me to write this library. Like the GHI touch screen and cameras, with the same eventing model and one line of code to use experience. I wrote part of the Kinect ADK and the design principles are consistent (and similar to the GHI module experience). The XBeeClient project requires developers of new features to submit their technical design document for peer review so the API stays consistent. High School students will always be able to easily use this library.

We are planning to integrate the code I told you about in our sdk for net gadgeteer. How about if you considered working with that projects contributors on enhancing the code and provide simpler interface so the community gain one perfected set of libraries?
But thank you for your contribution. I’m sure the community will like it?

I agree with Joe. There aren’t enough of you XBee experts out there. You should be putting yours heads together to create something magical.

Please point me to where exactly have your suggestions/ideas been flamed out (I don’t know if this is the right way to say). From the beginning of the project we were open to any contribution and constructive criticism. The main API was discussed on codeplex but you didn’t participate. In my opinion XBee API has to offer more than just sending and receiving strings between two nodes, becuase this can be done using Noridcs. Here we are using 16$+ chips so we need to be able to use their power. Of course you are right that many people will still use them to do basc stuff and i think if the current API is too complex for them, it can be adjusted. I have read the main xbee topic on tinyclr and no contributions regarding this from you as well. It’s a shame becuase you must have spent some time on your own library (and the documentation). That power could have been put into making one great library. I have analyzed your code and there are things that i would be strongly aginst (like XBee.SendPicture method) but It’s obvious that you know how to code. Now we end up having two libraries and confusing people.


In my opinion XBee API has to offer more than just sending and receiving strings between two nodes, becuase this can be done using Noridcs. Here we are using 16$+ chips so we need to be able to use their power. Of course you are right that many people will still use them to do basc stuff and i think if the current API is too complex for them, it can be adjusted. That power could have been put into making one great library. [/quote]

I’m sure that many people would use the advanced features But speaking for myself, I would like a simple API, as for my needs are simple - and that sounds like this is Paul’s target audience as well.

My use case: I want to eventually make an autonomous bot that will roam a mile or so for from home. The XBees would be used to transmit telemetry data - position, heading, speed, other readings. The ability to send images periodically would also be great. I would just have 2 XBees in my network - home and bot.

That’s part of the double edged sword of opensource.

I guess we are thinking on two different layers. For me a method Send(byte) is sufficient for the core XBee class. Something like SendPicture, SendMP3 etc that would trigger events like PictureReceived, MP3Received could be done with another layer in my opinion. This is my opinion.

Nevertheless look here how slow it will be to send a picture using XBee:


It’s just not designed to stream large blocks of data. One packet can be aprox. 100 bytes and the more hops occurs in the traversal the bigger latency (due to ack and node discovery). Digi says XBee max data rate is 250 Kbps. The actual data rate is however limited to the uart baudrate you can set in the xbee and in FEZ.

So what prevents anybody from writing a wrapper class that simplifies the existing API? What prevents anybody from making suggestions about how existing code could be refactored to be simpler? These are rhetorical questions, as the answer is obviously nothing.

You are correct. Someone like me however, I don’t know enough about the underlying technology (or the other use cases) to offer suggestions – or potentially know the best way to wrap it up.

Quite frankly, I’m coming from a place of very little knowledge of the XBee technology and the various uses of it. Also while I am aware that a great effort has been put forth to make a robust API and this one from Paul, I don’t know the differences between the two. From the community effort I see the discussions and they are going way over my head (partly because I have no experience with these devices). So when a thread says that an API is designed with ease of use in mind, that appealed to me.

There’s a place for both APIs (what little I know about them). My use case is simple and others are more complex. When you start working on a project, the person selects, imo, what better fits their needs.

If I were working on a commercial project, then I would likely want the more robust API, and I would take the time learn it better. But again for me and my hobby case, plug&play is very appealing, at least to start of with.

@ mhectorgato - my response was directed more at PaulMineau. I quoted you to illustrate my point. You can participate by asking questions and making suggestions. A fresh perspective is welcome, regardless of skill level.

@ PaulMineau - this forum is fortunately very free of flame wars. Attempting to create them by making exaggerated statements like this is counterproductive.

I haven’t used XBees myself (yet), but I note that the GHI Xbee Adapter does have Gadgeteer drivers, which look to be providing access to serial communications working at a string or byte array buffer level. What is the shortcoming of this supplied driver that has inspired two competing efforts to extend it? Is the supplied driver perhaps only suitable for point-to-point comms with the Series 1 XBees and so both xbee.codeplex and xbeeclient.codeplex are trying to support series 2 with more complex multi-point networking? Or is it maybe that the serial comms in the driver are really meaning communications between gadgeteer and the Xbee chip, rather than between two points, leaving the programmer with some work to do to set up a connection with commands sent to this serial port? From what I’ve read the series 2 ones sound more complicated to configure. If so, maybe Hector’s basic PC-to-robot use case might be already better met with series 1 Xbees and the GHI standard supplied driver?

I make this interjection in the hope someone will really clarify what these libraries are for and why they’re needed over and above what GHI have supplied - particularly since there’s nothing in the adapter’s product page to warn a purchaser that it’s only compatible with certain types, or that additional software might be required.

Thank you guys all of you for the positive feedback. I think this will help us and the community to use Xbee. As I mentioned before, the XBee libraries contributed by the community are going to be integrated in our SDK and we will make sure they got useful interface to the user.

the motivation behind XBeeClient are three personas: Einstein, Elvis, and the High School student. Einstein is a wizard that can write entire APIs and advanced algorithms on his/her own, Elvis has technical chops, and may not be familiar with .NET (e.g. coming from Arduino).

Most people will simply want to use the Series 2 in AT mode at first, and also use the Series 1. XBeeClient doesn’t have that yet because I started with Series 2 in API mode, but the library absolutely should support that.

Hopefully developers will step up to the plate and add this but if not, I’ll do it over the weekend of June 9/10. There is some overhead that is required: adding your design to the Technical Design Specification, short test plan, adding tests to the Interactive Console, and then of course the actual coding.

The series 1 support is critical. For the High School student, imagine that she works through a unit on wireless. For XBee she starts with Series 1, and advances to Series 2 in API mode. The experience is critical: she uses the Interactive Console which tells her what hardware she has and configuration. She runs tests for what she wants to have, and the tests tell her what she has to do, for example, using XCTU to set the PANID. If she calls a method that isn’t supported, for example using Series 1 and sending a message to a specific node, the exception that is thrown is all part of the experience and described in the Technical Design Specification.

It seems to me that you could accomplish this quite easily using facades that would simplify the one powerful driver to varying degrees as you step through the stages of learning without actually having to have a single driver that makes everyone happy.

In my opinion, a driver should be as small and fast as possible, leaving more advanced stuff to some SDK at a higher level. It should only expose the needed low-level methods/functions that are really mandatory.

Then, in the software chain, comes the SDK which, in this example, would provide high level methods/properties to deal with Series1 or 2 or both. Even the SDK could be split in small chunks so that one wouldn’t have to bother with Serie 2 code in his Serie 1 application.

@ Bec a Fuel - and @ ianlee74
thanks for the design conversation!

I was looking for the first time at the Series 1 manual here - http://www.sparkfun.com/datasheets/Wireless/Zigbee/XBee-Manual.pdf
it looks like sending AT and API commands is the same as for series 2. For example, series 1 API frames have the start delimeter, two bytes for length, and then API Identifier, and then payload. Different than series two in that there is no Frame ID. So there’s alot of shared code with some differences. Patterns that can be used: facade, template, what else?

The only specific AT command that the XBeeClient offers at a high level is ND (Node Discovery), through the DiscoverNodesAsync method. To execute an AT command, there’s the SendATCommandAsync method. My thought here is that advanced things like getting voltage level or MY or whatever, they could call this method with the 2 chars for the command (e.g. ‘MY’) and any payload as a byte array. similarly the response you get a byte array. I like this approach because it makes the design easier. but they have to look up in the manual what the payload is and have to work with tiny byte arrays.

I like the idea of having device specific drivers with a facade over the top.