DEV-12887

Page 1 of 40   Electric Imp Breakout Hookup Guide impRoduction The Electric Imp is a deviously awesome development platform. Disguised as an every day SD card, the imp is actually a unique combination of microprocessor and WiFi module. The imp makes connecting any device to the Internet a breeze. Looking to catch on with this “Internet of Things” fad? The imp is an excellent place to start. The Electric Imp card and imp002 Breakout Board In this tutorial, we’ll be explaining how to use the imp card with one of our Breakout Boards as well as the imp002 breakout board. You will have the choice of which platform to use (the imp card or the imp002). First, we’ll cover how to hook up the hardware end of the imp and imp002. Following that we’ll head over into the firmware domain, programming the imp to blink LEDs and read analog and digital inputs. The last code example shows off the coolest part of the imp: controlling hardware over the Internet! Required Materials You have a choice to make! You can either use the imp card and Breakout Board, or you can use the imp002 Breakout Board. If you want to use the imp card, you will need an imp card and the Electric Imp Breakout Board. Page 2 of 40 Electric Imp  WRL-11395 SparkFun Electric Imp Breakout  BOB- 12886 3 If, on the other hand, you want to use the imp002, you will need the Electric Imp imp002 Breakout Board. SparkFun Electric Imp imp002 Breakout  BOB- 12958 2 Aside from one of those platforms, we’ll use a few common electronics parts you may already have. Here’s a wishlist of everything else we’ll be using. NOTE: The 2-pin jumper is only required for the Electric Imp Breakout Board. Electric Imp Hookup Guide SparkFun Wish List Jumper - 2 Pin PRT-09044 SparkFun USB Mini-B Cable - 6 Foot CAB-11301 Breadboard - Translucent Self-Adhesive (Red) PRT-11317 Rotary Potentiometer - Linear (10k ohm) COM-09288 Resistor Kit - 1/4W (500 total) COM-10969 LED - RGB Diffused Common Cathode COM-09264 LED - Basic Red 5mm COM-09590 Mini Pushbutton Switch COM-00097 Jumper Wires Standard 7" M/M Pack of 30 PRT-11026 Page 3 of 40 Break Away Headers - Straight PRT-00116 Mini Photocell SEN-09088 In addition to those items, you’ll also need the following non-SparkFun materials: • • • • Wireless network with Internet access Electric Imp planner account (sign up is free/easy) Electric Imp planner website pulled up in your web browser SmartPhone w/ the Electric Imp app (Android or iOS) Tools There will be some soldering involved. The Breakout Board does not come with header pins soldered on, which you’ll need in order to interface with the imp’s I/O pins. You’ll need a simple soldering iron and a bit of solder (If you’ve never soldered before, this is a great place to start! The solder points are easy, through-hole jobs). Before We Begin This tutorial builds upon some basic electronics concepts. If you aren’t familiar with any of the topics below, consider reading through that tutorial first: • • • • • How to Solder - Through-hole How to Power a Project Voltage Dividers Pulse Width Modulation Light-emitting Diodes Aside from the imp’s programming language, Squirrel, there will be a variety of coding languages used in later parts of this tutorial – primarily HTML and Javascript. Don’t worry if you’re not too familiar with those, as the examples aim to be short, sweet, and easy-to-modify. Let’s start by overviewing the imp hardware itself. It’s hard, at first, to wrap your head around the fact that this little, module is actually a powerful WiFienabled microcontroller platform. About the imp Card It may look like an everyday SD card, but the imp is much, much more. It's a WiFi-enabled microprocessor. It’s programmable over the air. It’s got GPIOs, UARTS, I2C and SPI interfaces, pulse-width-modulation, digital-toanalog and analog-to-digital converters. Basically, it’s what you’d get if you smushed an ARM microprocessor and a WiFi module down into a tiny SDcard-sized package. Page 4 of 40 The imp provides an easy, integrated way to connect almost any hardware device to Internet services. It is well suited to be the backbone of your Internet-enabled project, whether you’re remotely controlling your electric blanket or triggering an irrigation system via a web browser. Connecting your imp to a wireless network and programming it is a simple, streamlined process. The Hardware: 6 Wondrous I/Os The imp is basically made of pure awesome. But, if we lift the hood of awesomeness for a moment, we can talk a bit about the imp's hardware. The platform of the imp is a Cortex-M3 microprocessor. Just like any microprocessor, the imp has a collection of input and output pins, each with unique functions. There are six addressable I/O pins – not as many as an Arduino, but it makes up for it in terms of functionality. The imp has three UARTs, two I2C and SPI interfaces, and two DAC outputs; plus each pin can act as an ADC input and PWM output. imp pin table from Imp's Pin Mux's Page Pin #UART1289 UART57 UART12 I2C89 I2C12 SPI257 SPI189 DACADCPWM 1 CTS TX SCL SCLK Yes Yes Yes 2 RTS RX SDAMISO Yes Yes 5 TX SCLK Yes Yes Yes 7 RX MOSI Yes Yes 8 TX SCL MOSI Yes Yes 9 RX SDA MISO Yes Yes Of course, each of those pins can also be used as a simple inputs (with or without pull-up resistors) or outputs, sinking/sourcing up to 4mA each. Also in that tiny SD package is a WiFi module, an antenna, and a light sensor. We’ll find out why the light sensor is critical in the coming pages. The imp is a 1.8-3.3V device, supplying it any more voltage than that can be harmful. It can require up to 400mA (worst-case), but it’ll usually pull about 80mA (even 5mA in a power-save mode). The IDE All code written for the imp is done online, in a browser-based integrated development environment (IDE). Everyone can (freely) create their own account on the IDE, where both your programs and your imps are kept safe Page 5 of 40 and secure. There are certainly pros and cons to this “always online” approach (though you can write and save every program locally, and upload it when you’re ready). Still, it seems like a good solution for this type of platform. Code in the IDE is divided into two halves: the imp device, and the agent. Code in the device half is code that actually runs on your imp. The agent is a process living on Electric Imp’s cloud server. It can communicate with both your imp, and the outside Internet world. We’ll dig further into the differences between these two components later. The Language: Squirrel Firmware for the imp is written in a language called Squirrel. Squirrel is an object oriented language similar to Javascript, but unlike most embedded system programming languages we’ve encountered (namely Arduino). Entering imp development from the world of Arduino may be somewhat jarring. There are no loop() or setup() functions, instead most actions are event or timer-driven. There are tons of great examples on Electric Imp’s wiki page, and if you're truly interested in learning Squirrel, check out the Squirrel homepage. There’s also the Electric Imp API to familiarize yourself with. These are functions and libraries used to perform actions with the imp’s GPIO pins and other hardware functionality. About the Breakout In order to use an imp, two pieces of hardware are required: the imp card and the impee. An impee is the piece of hardware that houses the imp. Aside from having a standard SD socket for the imp to slide into, the impee also needs to provide power to the imp, and do something with the imp’s I/O pins. Our impee for this tutorial is as simple as it gets…a breakout board. Page 6 of 40 Top and bottom views of the imp breakout. The imp breakout provides the bare minimum you should need to add an imp to your project. There’s an SD socket, a step-down voltage regulator, and every I/O pin of the imp is broken out to a 0.1"-spaced header. Powering the Breakout A big chunk of the circuitry on the Breakout board is a 3.3V TPS62172 step-down regulator (and the inductor/capacitors supporting it). This regulator allows for input voltages anywhere between 3.3V and 17V (voltages in the upper end of that range may produce some heat). It can support up to 500mA of continuous current. There are three power inputs on the board, all of which, are fed into the onboard 3.3V regulator: • “VIN” header - This standard 0.1" header feeds directly into the 3.3V regulator. • Battery input - These are the pins and pads labeled “+” and “-”. The footprint of the two through-hole pins matches up to a PTH 2-pin JST connector, which mates with our LiPo batteries (or AA batteries). This input needs to be selected using the jumper (see below). • USB mini-B connector - This power input should feed a clean, 5V source into the breakout board’s regulator. The USB voltage supply can come from either a mini-B cable connected to your computer or a USB wall adapter. This input needs to be selected using the jumper (see below). Setting the Jumper To use either the battery or USB power inputs, a jumper must be set on the board. To use the jumper, first solder a 3-pin male header to the jumper pins. Then use a 2-pin jumper to span from the middle pin, to whichever of the two inputs you’d like to use. In this image, the jumper is set to apply USB power to the imp breakout. A JST connector was soldered to the battery input pins, in case we want to use a LiPo to power the board. The Breakout’s Schematic Page 7 of 40 There are three main components to the breakout board: a TPS62172 stepdown regulator (U2), the Electric Imp socket (U1), and the ATSHA204 authentication chip (U3). Electric Imp Breakout Schematic. Click the image to get a larger picture, or click here to view the schematic as a PDF. Pinout All of the imp’s GPIO pins are broken out to the 0.1"-spaced header, along with a few related power pins: • GND - Common pin for input voltage • VIN - Input voltage supply fed into regulator • PIN1 - imp pin 1 (UART1289 CTS, UART12 TX, I2C12 SCL, SPI189 SCLK, DAC, ADC, PWM) • PIN2 - imp pin 2 (UART1289 RTS, UART12 RX, I2C12 SDA, SPI257 MISO, ADC, PWM) • PIN5 - imp pin 5 (UART57 TX, SPI257 SCLK, DAC, ADC, PWM) • PIN7 - imp pin 7 (UART57 RX, SPI257 MOSI, ADC, PWM) • PIN8 - imp pin 8 (UART1289 TX, I2C89 SCL, SPI189 MOSI, ADC, PWM) • PIN9 - imp pin 9 (UART1289 RX, I2C89 SDA, SPI189 MISO, ADC, PWM) • CD - Card detect. This signal will connect to GND whenever a card is inserted into the socket. • 3V3 - 3.3V output from regulator • GND - Common ground ID Chip There’s actually one more piece of hardware required of the impee: an ID chip, which provides each impee with a unique identification code. This means that every impee you encounter should include an Atmel ATSHA204 authentication chip. The imp automatically interfaces with this chip every time it boots up, so it can identify which impee it’s plugged into. This actually turns out to be pretty awesome, because the program that an imp runs depends on what impee it’s plugged into. If you had two impees in your house – say controlling an irrigation system and another controlling a coffee machine – one, single imp would run two different programs depending on which machine it was plugged into. You shouldn’t ever have to fuss with the ID chip. In fact, you can forget we ever said anything about the ATSHA204! About the imp002 Breakout The imp002 is a solder-down module version of the original imp card. We have done the hard work of creating a breakout board for you. Now, you just need one board instead of 2 to get started with the electric imp! Page 8 of 40 We recommend you read the About the imp section to learn what is in the imp, what the Planner is, and a brief overview of the Squirrel language. Like the imp card, the imp002 module contains an embedded ARM Cortex-M3 microprocessor, an onboard WiFi module, and antenna. The Hardware: 12 Glorious I/Os We have broken out 12 I/O pins from the imp002 module to standard 0.1" headers. Much like the imp card, these pins can be used for a variety of functions. imp002 pin table from Imp's Pin Mux's Page Pin UART1289 UART57 UART12 UART6E UARTB I2C89 I2C12 SPI257 SPI189 DACADCPWM # A Yes B RX Yes C Yes D E RX 1 CTS TX SCL SCLK Yes Yes Yes 2 RTS RX SDAMISO Yes Yes 5 TX SCLK Yes Yes Yes 6 TX 7 RX MOSI Yes Yes 8 TX SCL MOSI Yes Yes 9 RX SDA MISO Yes Yes Powering the imp002 Breakout The imp002 Breakout Board contains a 3.3V TPS62172 step-down regulator (and the inductor/capacitors supporting it). This regulator allows for input voltages anywhere between 3.3V and 17V (voltages in the upper end of that range may produce some heat). It can support up to 500mA of continuous current. There are three power inputs on the board, all of which, are fed into the onboard 3.3V regulator: • “VIN” header - This standard 0.1" header feeds directly into the 3.3V regulator. • Battery input - These are the pins labeled “+” and “-” as well as the JST connector, which mates with our LiPo batteries (or AA batteries). • USB mini-B connector - This power input should feed a clean, 5V source into the breakout board’s regulator. The USB voltage supply can come from either a mini-B cable connected to your computer or a USB wall adapter. Page 9 of 40 NOTE: There is a voltage selector circuit on the imp002 Breakout Board that will automatically use whichever voltage is higher: battery or USB. Be aware that the circuit does NOT charge the battery, it just prevents current flowing back into the source with the lower voltage (i.e. a short). The imp002 Breakout’s Schematic There are a number of circuits used to support the imp002, all of which can be found on the imp002 Breakout Board. electric imp imp002 Breakout Schematic. Click the image to get a larger picture, or click here to view the schematic as a PDF. • Input Voltage Source Selection - automatically switches between USB and battery input (whichever voltage is higher) • Pin Breakout - Power and I/O pins from the imp002 module • DC/DC converter - the TPS62172 buck regulator and supporting components • Input Voltage Measurement - the jumper can be soldered to allow VIN measurements on PIN A • imp002 module - the imp module and decoupling capacitors • Status LED - the red/green LED required by the imp to display its status (connecting, error, etc.) • BlinkUp - Light sensor for sending WiFi credentials to the imp002 module Pinout All of the imp’s GPIO pins are broken out to the 0.1"-spaced header, along with a few related power pins: • • • • • • • GND - Common ground VIN - Input voltage supply fed into regulator PIN_A - imp002 pin A (ADC) PIN_B - imp002 pin B (UARTB RX, ADC) PIN_C - imp002 pin C (PWM) PIN_D - imp002 pin D PIN_E - imp002 pin E (UART6E RX) Page 10 of 40 • PIN_1 - imp002 pin 1 (DAC, UART1289 CTS, UART12 TX, I2C12 SCL, SPI189 SCLK, DAC, ADC, PWM) • PIN_2 - imp002 pin 2 (UART1289 RTS, UART12 RX, I2C12 SDA, SPI257 MISO, ADC, PWM) • PIN_5 - imp002 pin 5 (UART57 TX, SPI257 SCLK, DAC, ADC, PWM) • PIN_6 - imp002 pin 6 (UART6E TX) • PIN_7 - imp002 pin 7 (UART57 RX, SPI257 MOSI, ADC, PWM) • PIN_8 - imp002 pin 8 (UART1289 TX, I2C89 SCL, SPI189 MOSI, ADC, PWM) • PIN_9 - imp002 pin 9 (UART1289 RX, I2C89 SDA, SPI189 MISO, ADC, PWM) • VDDA - ADC reference voltage. Connected to 3.3V by default. • 3.3V - 3.3V output from regulator • GND - Common ground IMPORTANT: If you disconnect the VDD/VDDA jumper, you MUST bring up the VDD (3.3V) power before bringing up the VDDA reference voltage. Additionally, if VDDA is greater than VDD (3.3V), it might cause damage to the imp002 module. Hardware Hookup The hardware hookup approach in this guide is just one of many ways to use the board. The breakout is made to be a versatile extension of the imp. You can connect whatever you want to the imp pins, and power the board however your project requires. Solder Headers In order to do much with the input/output capability of the imp, you’ll need to solder to the broken out pins. If you want to use the imp Breakout with a breadboard or perfboard, 0.1" male headers make for a good choice. Depending on your application, you could swap the headers with wire, female headers, screw terminals, or a variety of other connectors. We’re going to solder male headers into the board, so we can use it with a breadboard later on. Pins soldered onto the imp Breakout Board Pins soldered onto the imp002 Breakout Board Apply Power Page 11 of 40 Depending on what you want to use for your power source there are a few options here. You could use the on-board USB connector. Or you could solder down a 2-pin JST connector, and plug battery (LiPo or AA) into the board to make it mobile. If you go with either of those options on the imp card Breakout, you’ll also need to set the jumper (the imp002 Breakout will automatically select the higher voltage). Note how the jumper is set. We’re using USB to power the imp in this picture. No need to set a jumper on the imp002 Breakout Board! We’re using USB to power the imp002 here. Alternatively, you can apply power straight to the headers labeled “VIN” and “GND”. This pin bypasses the jumper and goes straight to the regulator. Plug in the imp! If you have the original imp card, plug the imp card in so the suspicious little imp logo is facing up. If you’ve got power to the board, once plugged in, the imp should start blinking orange. If there’s no blinking on the card, it’s probably not getting any power. Double-check that the jumper is set correctly. If you have the imp002, the status LED should start blinking orange as soon as you apply power. What’s all that blinking signify? How do we get the imp connected to our wireless network? Read on! BlinkUp Blink Codes The imp has an internal red/green LED, which is used to tell the world what state it’s currently in. If you’ve just plugged the imp in, and haven’t told it how to get on your WiFi network, it should be blinking orange (red/green simultaneously). Here are the rest of the codes to look out for: imp blink codes (from the imp blinkup guide) Color Orange Speed 1 Hz imp State No WiFi settings Page 12 of 40 Green Red Red Red, Orange, Off Orange, Red, Off Single Pulse Triple-pulse 1 Hz Successfully received configuration via Blinkup. Failed to receive configuration via Blinkup. Attempting to connect to WiFi. 1 Hz Getting IP address (via DHCP). 1 Hz Got IP address, connecting to server. Green 0.5 Hz Red None 2 Hz Connected to cloud (turns off after 60 seconds). Connection lost, attempting to reconnect. Normal operation Let’s make that LED blink green! Time to send a BlinkUp. BlinkUp To get your imp connected to your WiFi network as well as the online imp servers, you need to go through the process Electric Imp calls commissioning. There’s a great write-up on the commissioning process over on Electric Imp’s Getting Started page. Here’s the gist of it, as well as a few tips. Before you begin, you’ll need to make an Electric Imp account by visiting the IDE page. Updating the imp with your WiFi credentials is a unique process. The imp card has a built-in light sensor, looking out of the little window on the short, flat edge of the imp. The imp002 has an external light sensor built into the breakout board. The light-sensor can be used to process small amounts of precisely modulated data in the form of a blinking light. The light sensor is just behind the translucent window on the edge of the imp card. The light sensor on the imp002 is located to the left of the module, with the lable “BU” (for BlinkUp). To generate this blinking light, you need the Electric Imp app installed on your smartphone (iOS or android). Go download that app if you haven’t already! Follow the directions in the app, and prepare to update the imp with your WiFi network. Then, when your settings all look correct, hit the Send BlinkUp button. Quickly place the screen of the phone as close to the imp’s light sensor as possible. Page 13 of 40 Avert your eyes! Unless you enjoy staring into bright, white strobing lights. Similar warnings about white strobing lights. If all goes well, there should be a very short green blip of the LED, followed by a few blinks of red and orange. When the imp starts blinking green once a second, you know you’ve got your imp commissioned yay! Troubleshooting If you’re imp isn’t yet in the blinky green phase, use the LED blink codes to find out where it’s failing. Here are some recommended steps, depending on the failure point: • Connecting to the server (orange, red, off) - Make sure there’s no firewall blocking the imp’s way to the Internet (and make sure your WiFi network has an Internet connection in the first place). • Getting IP address via DHCP (red, orange, off) - Double check your WiFi password. • Attempting WiFI connection (red) - Double check your WiFi network name (SSID). If all of the above are set correctly, try sending the BlinkUp one more time. We’ve found that it helps to close out all other app, or even try resetting your phone if it continues to fail. More troubleshooting information can be found on Electric Imp’s site. Example 0: Hello World Now that your imp is commissioned, it’s time to upload your first bit of code! As with any new development platform, our first goal is to make sure we can make an LED blink. If you can make an LED blink, you’re well on your way to spinning motors or communicating with sensors. Using the IDE To begin, go to Electric Imp IDE, and log in if you haven’t already. Page 14 of 40 If your Electric Imp was successfully commissioned, you should see your imp device appear under Unassigned Devices on the left-hand side. Click the Create New Model button. In the name field, type “Hello, blink” for the name of our model. Check the box next to our device under Unassigned Devices. Click Create Model. Now, on the left side, you should see a new tab called Hello, blink. Select than, then click your imp name. This is the standard view of the imp IDE. It’s split into three sections: 1. Agent – This is code that runs external to your imp, in the cloud. You can offload server tasks, like HTTP requests, here. There are built in functions to aid in communication between imp and agent. 2. Device – This is the code that your imp runs. This is where you do all of your hardware control, like writing pins high and low, or reading inputs. 3. Log – This is where messages and errors are printed (using the server.log() function). Now we’re ready to load some code and blink some LEDs! The Circuit The circuit for this example is very simple. We only need to connect an LED to pin 1. Don’t forget your current-limiting resistor (330 Ω)! imp circuit Page 15 of 40 imp002 circuit Any of the imp’s I/O pins would work for this example. After working with the code, see if you can modify it to blink on other pins (or all of them!). Hello, blink Code We’ll only be working with the Device portion of the IDE right now. Copy and paste the code below into the middle section of your window. Page 16 of 40 /* Hello, Blink     by: Jim Lindblom     SparkFun Electronics     date: October 31, 2013      license: Beerware. Use, reuse, and modify this code howeve r you see fit.     If you find it useful, buy me a beer some day!     This is an Electric Imp hello, world blink sketch. It'll bl ink an LED     connected to pin 1, once every second.  */ //////////////////////////////////////// // Global Variables                   // //////////////////////////////////////// ledState = '0') && (colorNibble = return colorNibble ­     }  else if ((colorNibble >= return colorNibble ­     }  }  'a') && (colorNibble  tags, with id s like “pin1”, “pin2” etc. But they’re blank. Remember those, they’ll come in handy. The real magic here is happening in the poll() function in the area up top. This function sets up an AJAX) request to the Electric Imp agent. If the request succeeds, function(agentMsg) is executed. This function parses the JSON message received from the agent, and Page 39 of 40 dynamically updates the data in our blank tags defined below. poll() is set to be called every pollRate (defaulted to 1000) milliseconds. Whew! Hopefully all of this stuff is easy enough to pattern-match and modify as you please. To make some other information stream to the webpage, you have to: 1. Edit the imp Device code to send the desired data to the agent. Use the agent.send() function to do this. 2. Edit the Agent code in two places: 1. Read the data in from the imp in the device.on() function. 2. In an HTTP request handler, send the data out as a JSON string. 3. Add something in the AJAX success function to look for the correct JSON “key” and “value” combination. Then do something with that data. 4. Add a location in the HTML body to show the data. E.g. Give it a try! It sounds like a lot of work, but most of the constructs are already there for you to quickly add new displayable data. You could print the imp’s measured RSSI, or do some math on the analog input reading to turn it into a voltage. Resources & Going Further Now that you know how to hook up the imp and its Breakout, what project will you be making with it? Will you be adding to the “Internet of Things”? Need some inspiration? Check out some of these products and projects: Wireless Arduino Programming with Electric Imp Weather Station Wirelessly Connected to Wunderground Reprogram your Arduino from anywhere in the world using the Tomatoless Boots wireless bootloader with the Electric Imp. Build your own open source, official Wunderground weather station that updates every 10 seconds over Wifi via an Electric Imp. Arduino Wireless Communication via the Electric Imp Pushing Data to Data.SparkFun.com How to communicate between an Electric Imp and Arduino using serial. A grab bag of examples to show off the variety of routes your data can take on its way to a Data.SparkFun.com stream. Page 40 of 40 If you’re looking to interface an imp with an Arduino, check out the Electric Imp Shield. We’ve also written a tutorial on communicating via serial between the imp and Arduino. Resources The folks at Electric Imp have loads of great resources on their wiki. Among the many links on that page, these ones stand out for being extra helpful: • Electric Imp API Reference - Here you’ll find all of the imp-specific functions. • Electric Imp Developer Forums - There’s a wealth of knowledge in the imp community. If you’ve got a question, search for an answer here, or start a new topic. • imp Card Datasheet - A good datasheet for the imp (now called the imp001). You’ll find electrical characteristics here, along with other useful info. • imp002 Datasheet - The datasheet for the imp002 module. If you’re still left with imp-related questions, try consulting their forums. https://learn.sparkfun.com/tutorials/electric-imp-breakout-hookup-guide/all 11/10/2015