SparkFun will be closed May 25, 2015 for Memorial Day. Orders placed after 2pm on Friday the 22nd will ship out on Tuesday. Thanks!
Synapse SNAP modules are unlike anything I've ever had the chance to play with before (word of caution: I freaking love these modules, and I can't hide it, but I'll try not to be too hyperbolic in this tutorial). If you smash together a microcontroller with an XBee, and then load it with a network operating system that mesh networks and interprets Python scripts, you'll be on the right track. Then, add in over-the-air programmability, and remote function calls from any similar module. Finally, give it access to Python scripts running on your computer, so you can set up web utilities, and do anything a normal Python script can (send email, tweet, check baseball scores, play music, and other Python scripts ad infinitum...).
Looking to add any amount of awesome we can to our catalog, SparkFun has recently started carrying a couple of the Synapse SNAP modules. We've got the RF266, which has the same pinout as your standard XBee, making it XBee-breakout-board-compatible.
And there's the SM700 - a beefy SNAP module built on a 32-bit ARM7 processor, with 96kB of RAM, 46 GPIOs, 2 UARTs, and a 12-bit ADC. We mount it onto an Arduino-shield-compatible board, fully break it out, so you can get the most out of this nifty module.
As I've explored with SNAP, I've discovered a few points of confusion, and generally important topics that I'd like to emphasize in this tutorial. Don't consider this the end-all-be-all Synapse SNAP tutorial, but more of a hints/quickstart guide. Synapse provides tons of great resources for their SNAP modules, so if you're really looking for in-depth documentation, I'd definitely recommend checking both those and their forums out.
SNAP stands for Synapse Network Appliance Protocol, and it refers to the operating system running on Synapse's SNAP modules. It's what makes a run-of-the-mill, wireless-enabled microcontroller something (more) special. The operating system works behind the scenes to accomplish three tasks: IEEE 802.15.4 networking, hardware abstraction (controlling the i/o, low-level microcontroller stuff, etc.), and Python script (SNAPpy) interpretation.
Often I find myself comparing SNAP to Arduino (it's just so popular these days I really can't help it). Though the SNAP modules are definitely a step up from Arduino in terms of complexity, they also share some similarities. While Arduino boards can make embedded system prototyping super-quick and easy, Synapse modules exist to make embedded wireless prototyping equally painless. Both platforms support a variety of processors and architectures. Even when it comes to the most basic of functions (setting pins high/low, input/output, etc.) they're somehwhat similar.
But, then again, they're pretty wildly different; especially when it comes to firmware. SNAP scripts are written in a Python-like language, and everything they do is event-driven. As you play with them, you'll find that SNAPs really require a different approach to programming.
I'm going to write this tutorial from the perspective of going from the Arduino world to the SNAP world. So, basically, don't get too mad at me for comparing it to Arduino from time-to-time.
Portal is the home base for Synapse SNAP modules. You'll use Portal to write SNAPpy scripts, and upload them to SNAP modules. You can also use it to view the complete mesh network, get detailed information on each module, and change their configuration parameters.
I usually groan when I'm forced to use proprietary development software - it's usually bulky (no I don't want to download your 1GB IDE!), and just generally feels sluggish - but Portal's different (you do have to sign up for their forum to download it, but that's mostly painless). It's only about 32MB, free (-as-in-beer), runs smoothly, is well laid-out, and is simple to use. I also think it subconsciously stirs up some unrelated, video-game-playing memories, which makes me like it even more.
The UI's very customizable,you can drag-and-drop panes wherever you like. The windows I find most useful are:
Synapse has a comprehensive manual for Portal, I'd recommend you check out. Go to the Help menu within Portal and select Portal Reference Manual to check it out.
Obviously, you'll need at least one SNAP module, but two or more would probably help with that whole wireless thing. Each Synapse module works as a standalone microcontroller, but you won't get much use out of its integrated transceiver unless you've got something else for the module to talk to.
So you've got a couple SNAP modules, but how do you pair them with Portal and your computer? You need a bridge...
To integrate a SNAP module with a computer running Portal, you need a bridge (usually UART-to-USB) to interface it with your computer. Once you have a bridge from your computer to a SNAP module, you can use that module to communicate with - not to mention upload code to - any other SNAP modules in range.
Every SNAP module has a UART, that's what you'll use to set up communication between SNAP and computer. Here are the methods I'd recommend for the modules we currently stock:
Bridging an RF266 to your computer: The RF266 is probably the cheaper option, and makes more sense to be the computer's piggy-back. It shares the same footprint as an XBee, so you can plug it into any XBee breakout board we carry. Like, oh, I don't know, maybe the XBee USB Explorer?
Insert the RF266 as in the picture above, the blue antenna should be heading away from the USB cable. Now, hit the Connect Serial Port button in Portal. After a few seconds of searching you'll probably be greeted with this:
The RF266 comes with an AT Command Interpreter script on it which makes it act much like an XBee. Unfortunately, this script uses the UART and interferes with Portal's attempts to communicate with it. In order to use this module with Portal's serial port, you've got to erase the script:
If successful, Portal will ask if you want to erase another RF266. No thanks. Now try to connect to the same port. You should get some happy news in the form of "Found SNAP Bridge on COMX". If so, click Connect.
If you immediately get spammed with messages like this (you might not, my Windows XP system does, but my Windows 7 machine does not):
I'd recommend changing a few settings in the Preferences dialog, under the File menu. Something like this:
Disabling the automatic updates means you'll have to manually PING and refresh the nodes, but I prefer that to the endless timeout messages. Just get used to clicking the Refresh Node Information button in the Node Info window.
Bridging an SM700 pyXY to your computer: You can also bridge one of our SM700 pyXY modules to your computer, by connecting a 3.3V FTDI Basic up to the board's six-pin FTDI header (or any other 3.3V UART-to-USB/RS232 bridge).
As with the RF266, you may need to erase any scripts on the module before you can use it via the serial port. Follow the same process as above, except select SM700 as the Platform on the Erase SNAPpy Image dialog. Again, you'll have to manually reset the board by shorting the RST pin to GND momentarily when prompted (sorry! Maybe a reset button for future board revisions?).
With a SNAP Bridge connected, you should be able to hit Broadcast PING and search out for other SNAP modules out there.
If this is your first experience with Python, I'd like to apologize in advanced. Python rules. It's an addiction. But it also ruins other languages for you. Get too used to Python and you'll forget what a semicolon or curly bracket even looks like. Also, this:
If you're coming from Arduino, or similar C/C++/Java languages, it'll probably take a while to get used to Python. But, at least, there's a LOT of documentation out there to help you get started.
Here are a few hints to hopefully make your transition smoother:
You should keep in mind that the language that runs on SNAP modules - SNAPpy - is a subset of Python, not exactly Python. It has a few limitations that the standard Python does not. These one's really stuck out to me:
That's not all, but it's most of what I ran into. For a complete list, check out section 4 of the SNAP Reference Manual (under the Help menu in Portal).
Keep in mind that scripts that run in Portal are completely-and-totally Python. You have access to any Python library that exists. Using RPCs from your SNAP module to Portal, you still have access to the full power of Python.
Like Arduino, every pin on a Synapse module has a specific pin number. Consult the relevant datasheet, or in the case of the SM700 pyXY board, the pin numbers are silkscreened on the board.
These are the SNAPpy functions I found most useful when I started using Synapse modules:
Basic I/O functions:
Wireless/communication specific functions:
Other useful functions:
Aside from having to learn Python, probably the most major change in going from Arduino/C programming to SNAPpy is getting used to event-driven programming. There's no loop function in SNAPpy scripts (though there's sort of a setup), instead events trigger functions. The triggerable events of SNAPpy include startup, timer-driven interrupts (1ms, 10ms, 100ms and 1s), input pin transitions, and serial data inputs. Each of these events is given a specific "HOOK" identifier, as follows:
To make use of a hook, you have to attach a procedure handler to it. To attach a procedure to a hook use @setHook(), and then define the procedure immediately after. For example, to create a function named blink() that's called every 1s, do something like this:
@setHook(HOOK_1S) def blink(): pulsePin(blinkPin, 500, True) # pulse active high blinkPin for 500 ms
Some hooks pass parameters, which you may need to use to figure out exactly why the hook was called. For example, if you're monitoring 2 or more button inputs, you can use HOOK_GPIN to trigger an interrupt when a pin transition occurs. HOOK_GPIN passes two parameters - pinNum and isSet - to indicate which pin made the hook call, and whether it's high or low.
@setHook(HOOK_GPIN) def pinChange(pinNum, isSet): if (pinNum == switch1Pin) if (isSet == 1): writePin(led1Pin, True) else: writePin(led1Pin, False) if (pinNum == switch2Pin): ...
As you program, keep in mind that with event-driven programming (really interrupt handlers in general) you should effort to make your interrupt routines as fast and efficient as possible.
Let's jump straight into some code. Whenever you're working with a new platform, it's essential that you know how to blink LEDs. So here's a little "Hello, world" script:
But, that's pretty boring. You're not making any use of the wireless capabilities of SNAP. So lets add a second SNAP module that makes a call to the first's blink procedure. This'll show how you can make use of mcastRpc.
Also, make one modification to the blink script: delete the entire HOOK_1S and the callblink procedure. That way there are no local calls to blink. This'll make the LED-blinking completely dependent upon the mcast'ing module. This is a great pair of scripts if you're doing some distance testing (speaking from experience here).
Oh, and an unrelated shoutout to Pygments for helping to generate that HTML-ized Python code. Good stuff.
I think one last, really neat thing Portal has going for it is your computer running Portal counts as a SNAP node, and it can participate in the SNAP network. This means, provided you're computer's internet-connected, your in-range SNAP modules can access to the world-wide-web. So, you can use the modules to send emails, check/post to twitter, and perform a world of other internet-related actions. Anything a Python script can do, your SNAP modules can too.
You upload scripts to the Portal computer just like you would any other SNAP device. It should show up in the "Node Views" tab along with the rest of the nodes. Your Portal computer is assigned an address (defaults to 00.00.01) just like the rest of your modules. So your modules can make rpc's to that address.
One important difference between scripts running on your computer and those on your SNAP modules is scripts on your computer can run actual Python (not SNAPpy). So, first of all, that means you'll need to download and install Python. Head over here to grab Python; I'd recommend 2.7.3 over 3.x.x.
Once you've installed Python, you need to tell Portal where the libraries you just installed reside. Go to Options and then Configure Python Library Directory.... Then point that to the Lib directory in your new Python install. Then you'll have to restart Portal.
Now, try uploading this script to the Portal node:
That script is designed to work for gmail. I'm sure it could be modified easily to work with other webmail services. You'll need to replace firstname.lastname@example.org, with your actual email a couple times (the ones beginning with from_email and server.login). And you'll also need to replace yourpassword with your actual password (yeah...plantext...bleh).
Now any module on your network can send emails! Just send an rpc like:
rpc("\x00\x00\x01", "sendEmail", "email@example.com", "My SNAP Stuff Works", "I DON'T know why I'm sending you an email. My SNAPs are working! (Blame Jim).")
Stick that in a HOOK_GPIO and you can remotely trigger emails by pressing a button!
You can also try testing the function from within Portal. If you're on the Node Info screen (get there by double clicking a Node) for the Portal node, you can click on the sendEmail(to, subject, body) procedure and manually fill out all the parameters. Make sure you put double-quotes around each parameter.
So, thanks for reading my info-dump of Synapse SNAP stuff. Hopefully this is enough to get your brain-gears turning. I can't wait to see what awesome stuff you makers can do with SNAP. I think it's a really powerful platform.
Here are some other resources I'd recommend checking out:
If you've got any questions, or if I've made any errors, or if you just want to tell me how awesome I am, please post in the comments below. Bye SparkFunions!
tl;dr ('cuz I know it's too long): I think SNAP is pretty swell. You should play with it if you get a chance!