Shapeoko Assembly Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t456

Introduction

SparkFun’s Deluxe Shapeoko kit is a Carbide3D Shapoko 3 in fancy SparkFun red with our open source 3 axis mill driver, the Stepoko.

The full kit. In this picture, the Shapeoko parts have been assembled as per the Shapeoko guide, and the SparkFun kit parts are shown beside it.

Guide Content

This guide directs you to the Shapeoko assembly instructions, then goes through the final steps to add the electronics to the mill.

Required Materials

• Shapeoko assembly instructions - Download and read before unboxing. It works well to print two pages per sheet in order to have a copy on hand, and to save trees.
• A meter or so of spare wire.
• A soldering iron and some solder.
• A multimeter.
• A 2.5mm hex wrench for belt clips.
• Pliers or small adjustable wrench.

Suggested Reading

Stepoko guide - This guide talks about how the Stepoko control electronics works. Important information is also linked below.

Assembly

1. Follow the Shapeoko assembly instructions until you get to the part where controller is added. There are a few differences, for instance the motors in this kit have equal length wires, but nothing too significant.

   Set Aside Some Time It may take about four hours to complete the initial assembly. Once you’ve got it, continue on.

2. Install the Shapeoko into the enclosure. There are 10 4-40 screws for this purpose, but you’ll only need 8. Use a number 1 phillips screwdriver.

   To get the Stepoko into the enclosure, put the ‘port end’ in first.
   Installing the 4-40 screws

3. Install the enclosure to the rail with the terminal connections at the top. Use the extra M6x12mm bolts provided with the Shapeoko.

   Mounting the controller

4. Connect the X and Z axes to the Stepoko. For more information, check the Stepoko guide’s Hardware: Connecting the Motors section.

   • Tin the wire ends with some solder.
   • Identify which pairs of wire are connected inside the motors with your meter.
   • Match the coils to the winding symbols on the Stepoko. Either polarity or A-B position will work, but may make the motors spin the other way. This can be changed in software.
   The X and Z axis are connected.

5. Connect the Y axis. But wait! It has two motors that are wired in parallel.

   If two stepper motors are connected in parallel, they may not spin in the same direction because the internal polarities may not be the same. The solution to this problem is to transpose the colors of one pair of coil wires. This polarity/spin direction problem is compounded by the fact that the motors are mirrored on the mill and actually need to spin different directions.

   Watch the video below go get a basic idea, then work through these steps.

   • Connect short leads to the Y axis terminals.
   • Identify the coils.
   • Group one coil from each motor together by color, except with reversed polarities.
   • Twist the ends to test.
   • Try and move the mill in the Y axis. If it moves smoothly, solder the wires and apply heatshrink/electrical tape, or use wire nuts.
   • If the axis moved roughly, unlike the X and Z axes, filp one of the pairs of coils so that it has the same colors combined, but leave the other reversed. This is because the motor’s coils are not always wired the same internally.
   Take a quick look at this video to see, and hear, how the Y axis when wired incorrectly, and correctly.

6. Set the motor drive currents. Make sure the trimpots are in the center for 1A service until you are more experienced. Or, read up on how the current setting works in the Stepoko Guide’s Hardware: Setting the current section.

   The trimpots are centered for 1 A drive in this photograph.

7. Mount the switch to a free hole on the gantry end plate and solder on leads.

   Here the switch has been mounted and the switch wires are being measured. They go into the two terminals labled E-Stop.
   Soldering on the leads.
   All of the wires are added for this mill setup.

8. Screw in the lid to the enclosure using a number 1 or 2 phillips.

9. Collect your wires and bind with twist ties or zip ties.

   The Y axis wires have been twist tied together here. The X and Z axes are gently pulled out to see how long they are.
   With the X axis moved ofer to one end, I can see that my bound wires have enough slack so that they won’t be pulled on when the carriage moves.

10. Connect the power supply, power cord, and USB cord between your computer and the Stepoko

11. Open up the Universal Gcode Sender, open the Stepoko’s serial port, and select the machine control tab. Set the switch to ‘ON’ and try to move the machine by computer control. If the axis move in the wrong directions to your liking (but of course, up should be positive Z), switch the direction bit field accordingly. Use the Stepoko guide’s Software: Machine Control section for more information about grbl, or check out grbl’s Github wiki for more information on changing settings.

12. Measure know movements and calibrate each axis. See the Stepoko guide’s Firmware: Configuring grbl and Calibrating section for more info.

You’re done!

Resources and Going Further

Here’s some links and projects you may find useful.

• Stepoko Hookup Guide– Read in-depth about the Stepoko.
• The Stepoko GitHub Repository– Schematics and Gcode examples.
• The grbl GitHub Repository– Link to grbl source and wiki, for settings information.
• See this Shapeoko Coaster Project for an example of drawing and milling a complete project.

Or, head back to the The Stepoko and Shapeoko Landing page to see what accessories and tools are available.

Now that you have built your Shapeoko Mill, check out these other SparkFun tutorials to learn how to use the SparkFun Stepoko Control board.

Once you’re familiar with the Stepoko, create your first project by following along with the Shapeoko SparkFun Coaster.

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

Shapeoko Coaster Project a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t457

Introduction

The purpose of this project is to show that milling is a complex, multi-layered and multi-step process. It’s not like printing on paper; there are many small steps involved to get from an idea to an object. But, one must begin somewhere.

This guide is intended to allow someone who’s never milled before make something useful with a mill.

The finished coaster.

Tools needed

• Shapeoko mill (prototype shown in pictures), Stepoko controller, and a trim router
• ¼ inch dual fluted wood router bit (from hardware store)
• ¼ inch, 45 degree engraver bit (from hardware store)
• Drill for drilling and driving screws
• A drill bit to match screw shaft size
• The router chuck tool and adjustable wrench
• A few screws to hold down the material
• Hearing protection
• A computer that can get sawdust on it

Think about cleanup before you begin too. I operated outside but still had to vacuum down the mill and computer afterwards.

Materials

• Stain – I chose Watco Danish Oil
• A Sakura brush pen
• A length of 1x6 Common Board
• Sandpaper
• Paper towels

Software

• Inkscape
• Makercam.com

Suggested Reading

If you have not already, we recommend reading the Shapeoko Assembly Guide and the Stepoko Hookup Guide for a better understanding of how this project came together.

Processing the Toolchain

The first part of the process involves doing the design and CAM work. For this example, Inkscape is used to generate .svg files that are then passed to Makercam.com to do the tool path generation. This section covers what that process looks like.

I start by opening inkscape and figuring out how to make the grid meaningful to me. I set it to ¼ inch and aim for a 3 ½ inch coaster.

Start drawing some shapes!

I realized my grid wasn’t fine enough for the task, so I increased it. I put lines in for each place I want to engrave or cut out. I think I want two rings around the outside with a graphic in the middle, and a few terraced cuts around the parimeter

Now, it’s time to bring in the graphic. Inkscape works great for dealing with vector shapes that don’t have to be any particular size. On the flip side, it’s not so good for working in strict coordinates, like for machining parts.

The SparkFun flame is the obvious demo material! After importing it, it needs to be cleaned up.

Select it, remove the fill, and set the stroke paint to solid. After this, a mini flame can be seen in the middle for no particular reason. Delete what you don’t need.

I thought the flame might look good framed by the two edge circles, so I scaled and slid it around until I was satisfied.

To remove the extra part, select “edit paths by node”, and use the tool bar to clean up the desired points.

At the last moment, I decided I wanted to put another level to the perimeter. I had already made the interior graphics, so I slid up and to the right so I could put another circle around them.

A sketch of the profile helps me decide what cuts need to be done, and in what order

I was developing this thought as I went through the inkscape drawing and came up with the above. Each number is the order of the operations. For the first job, the 1x6 will be planed down to 3/8th inch, and two of the perimeter cuts made. The coaster won’t be free until step 5 which is what I want. The next job will be to change tools and run step 4 to put the graphics on the coaster. Lastly, the perimeter cuts will be finished releasing the part from the stock.

Now that I have an idea of what my workflow will look like, MakerCam is loaded with the .svg file from inkscape, and it appears at the origin because that’s where I drew it. If it’s not, it can be moved.

I’ve selected one ring to show that each line is an independent shape. If different operations happen for different shapes but they’re connected, the CAM software can’t tell them apart.

The first operation will be to plane the ¾ inch stock down to the thickness of the coaster, 3/8 inch. Select the major circle, then select ‘CAM’ then ‘Pocket operation’. MakerCam presents me with a set of parameters that I need to change. I know I’ll be zeroing the machine to the surface of the material, so the stock surface will be 0. I’ll cut down to .375 inches, or -0.375 (because down is negative on the Z axis). Feed rates and depth-per-cut can be set here too. Don’t forget to specify your tool diameter!

Next up is to make a profile operation. This will generate a path around the major circle to hog out the extra material and give the tool some room to work on the other parimeter operations. Really, this just makes the pocket operation a little bigger.

Now, it’s time to make the two profile operations that make the detail on the perimeter. First, a shallow cut on the inner circle, then a deeper cut farther out.

This is the profile for the outer circle.

To make the toolpath for the engraving, select all shapes to engrave (use ctrl-click to multi-select) and choose ‘CAM’ then ‘Follow path operation’. Where a profile operation is used, the path goes outside or inside the line by half a bit width, while ‘Follow path’ goes directly on the line. I will be using a fine pointed engraver for this step so it’s Ok, I can assume the width is small. I’ve set up these parameters to make one pass at almost the complete depth, then finish off with another pass a little deeper to make sure everything is cleaned out.

The final operation is to finish the parameter cut and free the piece from the stock. When the part becomes free, it may bounce around and get chewed up by the tool but I’ll risk it. Using ‘tabs’ is the industry standard way of cutting out most of the part while leaving little bits of material to retain it. Tabs are available in MakerCam, but I haven’t used them.

Now, click ‘CAM’ then ‘Calculate All’ to have the software ponder the operations you have specified and generate the associated tool paths.

After calculating, green paths with arrows appear that show the movement from the top down. Everything looks ok, though our view is obscured by the lack of a third dimension.

Here’s where the Gcode comes into play. Select ‘CAM’ then ‘Export Gcode’ to bring up this window. It allows you select which operations go together, then generate and save a text file. Don’t forget to add “.nc” to the end of the file name for MakerCam! The first job I select will be steps 1, 2, and 3 of my profile diagram, which will include the first pocket, the major profile, and the two detail profiles.

Next up is to export the engraving step on its own. This is because I need to manually change tools, and I can’t do that in the middle of a Gcode job.

The last thing to export is the final perimeter cut.

Now, I have three .nc gcode files! As a sanity check I open them in Universal Gcode Sender, and click the ‘visualize’ button to view the paths in 3D

The first path shows mostly pocketing with a few parimeter paths, just how I want it. If you look closely, you can see how they will create a stepped edge.

The engraving step looks good too. It has two closely spaced cuts that resemble the original graphic.

The final pass to release the part. Notice that when the last cut is made, the part will not be held to the wasteboard anymore and will have be retained with a push-stick for a good cut.

Operating the Mill

Setup

Now that the files look good, it’s time to prepare for the actual work. Gather together all the things you think you’ll need before starting, especially if you’re not working in a shop. This can prevent running for new tools.

The various hand tools and supplies collected for this project, as mentioned in the Introduction.

Of course, you’ll need a mill and computer. Shown here is a Carbide 3D Shapeoko mill with SparkFun Stepoko controller

Operation

Set the material into the mill. Some mills have clamps but for this simple job I drilled holes in the material and screwed it down to the wasteboard.

I’ve left the carriage at about zero so I know the cut path of the job won’t hit the screw heads. An easy way to get it all straight is to eye-ball off the previous liner cuts that develop in the wasteboard over time.

There will be three jobs to run. First, ¼ inch milling, then engraving, then milling again. With the e-stop enabled, the carriage moves freely but doesn’t track motion. We haven’t calibrated to zero yet, so move it up to get to the collet.

The tool is made pretty tight. If it slips up in the collet during operation, the tool may be dull, too loose, or the feed rate is to high.

Now, it’s time to make a zero reference. Once made, this will be zero for all jobs. If everything goes smoothly (don’t plan on it the first time around), the machine will never have to be re-zeroed. If not, you’ll have to use this reference to locate zero again.

The tool can be lightly pressed into materials like plastic and wood to dent and give a mark.

Back on our computer, click ‘Reset Zero’ to tell everybody that the machine is at the new zero. If this doesn’t seem to take, close and reopen the software.

With the machine at zero, switch off the e-stop (turn on the switch). This locks the stepper motors.

Use the machine control tab in Gcode Sender to lift the tool by a know amount. I chose 10mm. This is kind of a sanity check to make sure the machine is working and to get it away from the material.

After the first pass, the first 3 operations are apparent. The mill has been returned to zero.

To switch tools, use the switch to unlock the motion, lift the Z axis without disturbing the X and Y, and re-enable the motion. Now I have some room to work.

Oops! It can be seen here that the black plate, which moves with the tool, will crash into the work surface if I try to run the job.

I loosen the router clamp evenly.

The router is dropped down an inch or so. I had to zero again before running the job.

After running the job, switching the tool back to the mill bit, and running the final perimeter job the part is released. If you watch the video you can see that on the last pass, I hold down the part with a scrap pushstick. Alternately, you can leave tabs in the CAM software so that it doesn’t fly around when on the final cut.

Enjoy a time-lapse video of the three jobs being sent to the mill!

The coaster, right out of the mill.

Finish Work

Finishing work really brings out the design and is pretty easy to do for any woodworking project.

Sand the coaster to your heart’s content! I used a medium grit paper in circular motions, and it came out as good as soft wood can.

Ahh, I’ll take it!

This Danish oil is applied with a cloth or spounge… or paper towel.

The idea is to apply profusely, let sit for 10-15 minutes in the shade, then wipe off the extra.

The coaster is wiped down to remove the excess stain.

Carefully line the engraving with a brush pen such as this one made by Sakura.

The Final Product

The finished coaster! I didn’t really like how the lowest edge turned out. If I want to make a rev B, I’ll go in the toolchain and adjust this circle in about 1/16 of an inch.

And the moment of truth. It coasts my beverage! A success.

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

Stepoko: Powered by grbl Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t414

Introduction

The SparkFun Stepoko is an ATmega328p, Arduino compatible, 3-axis control solution. It’s open source, uses open source firmware and works with an open source Java based cross platform G-Code sending application.

The SparkFun Stepoko, in all its glory.

The simplest installation of it consists of just plugging the stepper motors in, but of course hard work pays off. Handy machine control buttons and locating features can be added at taste to give a mill whichever options are desired.

The Stepoko implemented on a novelty-sized laser cutter, sitting atop a Shapeoko mill also driven by a Stepoko

Features:

• 3 stepper connections
• Full, to 1/8 stepping
• Comes with heatsinks installed!
• Options for input and feedback include E-Stop (emergency stop, or general motor drive switch), Reset, Feed Hold, Cycle Start, Homing Location and Probing.
• Has option for spindle direction and PWM control.
• Can be powered from 12-30V.
• Independent axis current limiting adjustments

Required Materials

• Flat-head Screwdriver
• Power supply
• Stepper motors
• USB type-B cable
• Software:
  • Univeral Gcode Sender
  • A gcode file Github /Examples folder

Suggested Reading

If you still need to assemble your Shapeoko Mill, please consult our Shapekoko Assembly Guide.

• Motor tutorial– This tutorial covers all types of motors. If you’re unfamiliar with stepper motors and how they work, check it out.

Hardware: Overview

The Stepoko is a complicated board. First, let’s take a look at the whole thing, then the various parts will be broken out by function and discussed.

The top side.

Parts of the top side:

• LEDs
  • X, Y, Z Direction – Denotes polarity of movement
  • X, Y, Z Step – Flashes each time the associated channel steps
  • X, Y, Z Limit – Illuminates when a stop switch is active
  • E-Stop – Illuminates when the stop button is active (shows axis lock has been removed)
  • Probe – Illuminates when probe switch is active
  • Step En – Illuminates to show the controller is ready to step its axes
  • Power – Illuminates when the bulk rail is energized. Shows when back emf is also charging the unpowered rail.
  • TX, RX – Shows communication over the USB.
  • Reverse protection – Illuminates when power has been connected backwards – Remove power
• Axis connectors
• Switch connectors
• Switch active polarity switch
• Power connectors
• Uno-type 328p
  • Reset switch
  • USB connection
  • Pin Breakout
• Axis drivers – DRV8811
  • Step switches
  • Heatsinks
• Power regulation
• Fan connection

The bottom side

Parts of the bottom side:

• Arduino pin map
• Arduino pin breakout
• Heatsink

Hardware: The System and Power Supply

The top side

Powering the Stepoko

Stepper motors take a lot more current than most hobby circuits. The Stepoko can supply up to 2.0A each per coil! To get that kind of power, an ordinary wall adapter won’t suffice. Apply 12-30 VDC to either the barrel jack or screw terminals, but not both. Use either a power brick or a Benchtop Supply of some kind. Make sure the supply can generate about 3 times the single-coil current for a 3-axis setup. Because of the switching nature of the stepper motors, the maximum current for a single winding is greater than the total current required to run that motor.

Use the following formula:

For instance, if two channels are used and set to 1A each, a 2A supply is required.

After power is attached, the blue power LED should light illuminate. If it doesn’t, or if the reverse protection LED lights up, remove power and check voltage/polarity of the supply.

The Embedded ATmega328p Microcontroller

The Stepoko is actually an Uno compatible ATmega328p! It’s just an Arduino with a grbl shield attached. This is evident by looking near the USB port where the familiar FTDI, Atmel IC, reset button, and even the SPI 2x3 header can be found. In this area, we’ve even broken out all of the pins that are associated with the microcontroller and power supplies. If you peek at the back of the board, there’s a chart in silkscreen that matches the grbl pin functions to the Arduino pin naming convention. It’s open source! You can do what you want to it.

To use the microncontroller, attach a USB cable and let your computer enumerate the device as it would with an Arduino. After that, you could program it with the Arduino IDE. It comes with grbl 0.9 though, so don’t program it unless you absolutely have to. Even if you revert back to grbl, the grbl settings will be lost and you’ll have to program them all in again.

Connecting the control switches

The Stepoko supports

On the left, the red light indicates that the E-Stop has been pressed (or the switch terminals are open). In this mode, the steppers are not being driven and can be manually moved. On the right, the green light indicates that E-Stop has been deactivated. Power is enabled to the stepper moters and that their rotors are magnetically locked. In this mode, the system has control of the movement.

Hardware: The Stepper Drivers

The stepper drivers consist of three identical circuits, one for each axis. Here, one is shown but the application applies to any of them.

The top side

Parts of a single axis circuitry:

• State LEDs
  • Direction – Denotes polarity of movement
  • Step – Flashes each time the associated channel steps
  • Limit – Illuminates when a stop switch is active
• Stepper Motor Connection
• Axis driver – DRV8811
• Microstepping Control Switches
• Heatsinks – One each on the driver IC and a collective aluminum slug on the backside
• Current control potentiometer

Operation

At the heart of each axis driver is a DRV8811 IC by Texas Instruments. The microcontroller talks to the 8811 by digital control signals (not serial) that: set the direction, enable the motor, and cause a step. Internally, it has a state machine that matches the coil states necessary to get a stepper motor to perform. Modifying the microstepping switches changes that state machine such that the pattern is correct for the microstepping indicated.

The digital portion of the IC operates from 5V by way of the Stepoko’s on-board regulator. This is not enough to drive the motors though. The IC has a separate VIN supply that connects directly to the power jack / screw terminals. Whatever the voltage (12V - 30V) supplied, that voltage will be the driving voltage on the motor coils.

All this work is graciously provided by the grbl software that comes pre-installed, so unless you are building new software, how the 8811 works is really not too important. If you are, the DRV8811 datasheet explains in great detail.

Hardware: Connecting the Motors

The Stepoko is designed to be able to control a multitude of 2-phase stepper motors. These all have two sets of coils that are driven in a particular combination in order to make the motor turn in the correct direction. If this is all new to you, read our tutorial on Motors and Selecting the Right One, in particular the section Stepper Motors. This tutorial has some descriptions of motors with three sets of coils rather than two, but the theory is the same.

The Stepoko can handle a variety of motors by adjusting the current level for the application.

Identifying the Coils

A lot of the time steppers come from a ‘motor box’ on a hobbyist’s shelf, and may not have ratings or part numbers. If there are four wires, chances are it’s a stepper. The coils need to be identified though, so take out a multimeter and look for continuity between wires. If the motor has four wires, with two pairs that have a similar resistance, you’ve found the coils!

Here you can see that the first two random wires measured open, and the second two measured 1.8 ohms. This is a typical large-ish 2 phase stepper.

Alternately, with the datasheet the wires should be indicated. An example datasheet from our general purpose motor shows a simple wiring diagram with the two coils.

Attach the motors

The two coils of the motor correspond with the ‘A’ and ‘B’ terminal pairs on the board. Including the fact that you can put the coils in backwards, there are 8 possible ways to connect two coils! But which one goes where? Don’t even worry about it. If one is backwards, or if coils ‘A’ and ‘B’ are swapped, the motor will just spin in the other direction, which can be set in software.

More worrisome is how to convince the stranded wires get into the terminal blocks and then, stay there after they have been tightened. Tinning the leads can make the whole thing go smoothly.

Left: the wire ends look pretty ratty from the factory. Center: Collect the wire strands by giving them about 180 degrees of twist along the length of the strip. Right: Tin each lead. Apply excess solder to allow the flux to work, and pull the extra solder off with the iron yielding a solid cylinder of wire.

Sometimes the terminal springs are tight from the factory. To help ease connection, back out the termina screw until it’s flush with the terminal block, gently open the contact, and use a tool to push from the tinned end.

Left: Back the screw out until flush. Center: Gently open the contact plate. Right: Help put the wire in with a tool that is choked up near the tinned end. You can’t push a rope!

Hardware: Setting the Current

Before powering up the Stepoko, set the desired current for each attached motor. The current control potentiometer scales the peak drive current from 0 to 2 amperes. There a few methods of setting the current.

Set by ‘Dead Reckoning’

This is the preferred method.

The trimpot can swing through 200 degrees of motion, and covers a range of 2 amps. Turn the trimpot counter-clockwise gently until it hits the stop, then clockwise a number of degrees for the desired current. The example datasheet from the previous section lists the motor as being 0.33 A capable. Set the knob to 33 degrees from counter-clockwise stop.

Use this formula for other motors:

- or -

Set by Test

If you have more experience, you may opt to set the current by feel.

Start by setting all the trimpots to slightly off their counter-clockwise stop. Then, fire up the Universal Gcode Sender software (described later) and connect to the Stepoko. This enables all the motor drivers and will lock their position. Now, attempt to move the motor. If the motor moves easily, carefully turn up the channels and repeat the test until the force required to move the motor (slipping poles) is greater than the expected lateral force exerted by the tool head.

Set by Current-Shunt Measurement

The most scientific method to know a thing is to measure it. To do that, you’ll need a scope and a steady hand.

There are 6 current sense resistors on the Stepoko that can be identified in the schematic, and by finding the larger resistors near the drivers. Each has one end grounded while the other is connected to the active driving circuitry. By adding a probe ground to one end and stabbing the other end, both positive and negative coil current can be measured.

Here an oscilloscope probe has the grabber and alligator clip removed, and is inserted in a coil that contacts the ground part of the probe while the tip fits down into a pin cup that attaches to either end of the current sense resistor. Sometimes this setup is called a ‘Zero Length Probe’.

The resistor itself is 0.1 ohms in resistance. At the max current setting of 2A, and by following ohm’s law, the max voltage read across this resistor is 0.2V, or 200 millivolts. This is quite low. A scope with 8 divisons on the screen has to be set to 50mV per divison so that positive and negative 2A can be read. At this vertical scale, the electromagnetic radiation from the giant current loads of the motor will be picked up by the extra few inches of the probe, which is why a the shortest possible loop of wire at the probe end is desired.

This plot shows the positive and negative cycles of the motor’s coil. Notice that the plateau is at 100mV, or one ampere. The trimpot is centered.

Adjust the plateau average to the rating of the motor.

Hardware: Dealing with Heat

To get the heat out of the driver ICs, the Stepoko comes equipped with three heatsinks on the top and a large aluminum mass on the backside. When setting up the Stepoko, be careful to check the temperature often to make sure it is not too hot to touch. Generally speaking, the harder the motors are driven, the more heat will accumulate on the heatsinks.

Here are a few methods of dealing with the heatsinks.

Provide air space

For small motors or mills that don’t have a large cool mass of metal to wick out the heat, make sure the Stepoko is lofted and that air can passively circulate around the heatsinks.

On my mini-laser cutter, the heatsink has been kept off the wood base

Attach a path for cooling

The intent of the aluminum slug on the backside is to conduct heat to the mill itself for cooling. The height is perfect to pass through a hole cut in the SparkFun Big Red Box enclosure so that the whole thing can be mounted to a thermally conducive surface.

The frame of the Shapeoko mill is large enough that the mill can operate with a strong drive for hours before the frame even starts to get warm.

Add a fan

There is a connection on the Stepoko for attaching a single, or multiple 12V fans. This connection is regulated to 12V and unswitched, so fans connected there will run whenever the Stepoko is powered from 12-30V.

Software and Firmware Overview

Milling is a little more interactive than just sending a job to a printer. After the hours put into modeling, the model files are converted into what’s called G-code by CAM software. Then, the G-code is sent to the mill by some machine control software (in our case, universal G-code sender). The mill itself runs firmware which can interpret what the machine control software is saying and in turn, drives the stepper motors to move the mill. Whew.

This process of walking through various programs is know as a tool chain. This graphic shows each distinct part of the tool chain, though the machine firmware is not usually talked about, and sometimes (in particular for 3D printing) the CAM and gcode sending software are the same.

The solid modeling, design work, and CAM software are not in the scope of this hookup guide, and from here on it is assumed that you have some gcode from somewhere. Several examples exist in the Stepoko github including a 1x1 inch square, a few 10x10 inch squares, and the SparkFun flame.

Software: Machine control (Universal G-code Sender)

Once G-Code files have been created, a program is needed to parse them and issue the commands to the Stepoko. A good open source one that works well with the Stepoko (and all grbl hardware) is Universal G-Code Sender.

As of writing this, 1.0.9 is the latest stable build. Most people will want this as a zip archive rather than having the github source. Download it, unzip it into a directory, and run the batch file for windows, or shell script for mac/linux.

Make sure you are connected to the Stepoko. Once the program is loaded, you can set the connection parameters, and click ‘Open’ to get a connection to the mill. Use 115200 baud and the port that appears when you attach the Stepoko. If all goes well, the grbl firmware will reply with its version number.

This is a view of the gcode sending software, Universal Gcode Sender. The upper most tabs allow you to enter arbitrary gcode, load files, operate the mill in a manual way, and send macro command strings. The lower tabs show terminal output and progression through a gcode file as a table of commands.

Selecting the menu ‘Settings’, ‘Firmware Settings’, then ‘GRBL’ opens this window. This shows the settings currently saved to the Stepoko and allows modification. Once modified, click ‘Save’ to put them in the Stepoko’s ROM. Common settings are covered in the next page.

The File Mode tab.

The Visualizer window.

Firmware: grbl for the Stepoko

The Stepoko is shipped with the latest grbl, (v0.9) as of this writing. The grbl project is highly developed and can be found in github, complete with a wiki that describes in detail what the settings do.

Direct links to the project and wiki:

• grbl Github Repository– Github Project
• grbl github’s wiki– Project wiki

From the grbl github repository:

In our factory, after programming the firmware onto the Stepoko, we put the following settings directly into the ROM of the ATmega328p. These are held even when power is removed, or until they are changed by the user through the serial (or Universal Gcode Sender) interface.

These default settings are appropriate for the Shapoko 3 mill.

Firmware: Configuring grbl and Calibrating

This section covers calibration of the axes. The settings take a parameter of steps required for each millimeter of motion, but factors such as microstepping and mill geometry come into play.

Calibrating

When working with a new motor, a few steps need to be taken to get it moving correctly

• Get the number of steps per revolution
• Decide on microstepping value
• Determine ratio of motor revolutions to carriage motion
• Calculate steps per mm
• Drive the carriage a known distance
• Measure error and apply to settings

The Initial steps/mm Setting

If using a mill with known geometries, you’re in luck! Punch in the steps/mm as given.

If using recycled parts or variable materials (like belts), do some basic math to get an approximate first-setting.

Do This for Each Axis:

While turning the motor, measure the distance traveled in mm. Then, calculate steps per mm based on

For example, with a 20 steps/rev motor that travels 2mm per revolution and 1/8 microstepping,

Now, using the ‘machine control’ tab in Universal Gcode Sender, instruct the mill to move 1 inch (or some number of millimeters). Is it close? Reset the mill, mark the location and repeat. Make a measurement of the true movement.

Now, modify the original setting by a ratio of the expected and measured movement. Another way to think of it is, what’s the percent error?

For my example, I intended to drive 1 inch but actually drove 1.3 inches. I take the original setting of 9.52, multiply by 1/1.3 to get 7.32. After programming the new setting, the movement is dead-on (or bang-on if using mm).

Cutting a Square

If you’ve never used a mill before, start by cutting out a simple shape. For this, the design step will be skipped. We’ll go directly to CAM and use it to put in a basic shape.

The first step is to open MakerCam in a new window. If you have ad blocking software enabled, you may have to disable it.

Makercam first view. I’ve scrolled around until I was able to locate the origin.

Next, use the menu to add a square (or any shape). A window will open that lets you specify some of the parameters.

Enter the desired parameters

The real purpose of the cam software is to determine how to make a real machine do some movement that yields the desired shape remaining at the end of the whole thing. To do this, drop down the CAM menu and select profile. This means the tool will move around the outside of whatever the shape is that’s selected. Other options are engrave, to follow the line exactly, and pocket, which removes all the material inside the shape.

The profile options window

From this window, the cam software takes into account the geometries of the actual mill. Set the tool diameter, safety height (how far above the surface to go before X-Y movement), and step increment. Stock surface is important too, but for now leave it a 0. It can be used for multiple path jobs where one path takes the stock surface down, and the next cuts from that level.

I’ve selected quarter inch depth with eighth inch depth per cut. Hit ‘OK’

Now we need to calculate a path based on the parameters. From the CAM menu, select ‘calculate all’

Now a green line with arrows appears above the part. This shows how the tool will move. This path becomes the gcode, so the next step is to export (again, from the CAM menu). There should only be one path available to select.

Got it? OK, now put MakerCam aside and open Universal Gcode Sender. Then load the file and click visualize. By holding down the mouse button in the visualization window, the view can be rotated.

The visualizer shows that two cuts will be made (sanity check: I did want ¼ inch depth at a rate of 1/8 inch per cut). With the ESTOP function activated (no carriage movement), the job can be run and you can watch the tool head move around the path.

When you’re confident that the mill head has enough room to complete the pass, zero it out, and hit go. Running a couple inches above the table is a good way to build confidence in the job. Be ready to hit the estop if something goes amiss. When you’re good and ready, turn on your active cutting device and let ‘er rip.

Cutting and Engraving a SparkFun Coaster

Squares are alright, and it’s fun to watch the machine move around, but eventually you’ll want to actually cut some real shape out with the mill. I’ve put this Shapoko Coaster Project together to show all the steps of cutting a project with a mill.

This uses open source software for all steps:

• Create design in inkscape
• Create took paths through makercam.com
• Send gcode with Universal Gcode Sender
• Stepoko runs grbl on the mill

Watch a video of the coaster being made below:

Resources and Going Further

This is all the basic information about applying the Stepoko to mills. If you would like more information about a particular step, please comment.

Looking into the future

• McMaster-Carr - Order tools online, as well as any part you would ever need.
• CamBam Software - This CAM software is better than the free one and is reasonably priced. It has a 40 day use trial. I would highly recommend trying it out.

Links mentioned in this hookup guide

• DRV8811– Texas Instruments product page.
• DRV8811 datasheet– Direct link to the driver datasheet.
• Universal G-Code Sender– Github repository.
• grbl Github Repository– Source code.
• grbl github’s wiki– Information on settings.
• MakerCam– Web based CAM software.

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

EL Sequencer/Escudo Dos Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t369

Introduction

The SparkFun EL Sequencer is an Arduino-comptabile microcontroller, with circuitry for controlling up to eight strands of electroluminescent (EL) wire.

Added to your cart!

SparkFun EL Sequencer

33 available COM-12781

The SparkFun EL Sequencer is a board that contains an Arduino-compatible microcontroller, and circuitry for controlling up to…

$34.95

FavoritedFavorite2

Wish List

The Arduino shield version of the Sequencer is the SparkFun EL Escudo Dos, and it can be used with any Arduino Uno footprint-compatible microcontroller.

Added to your cart!

SparkFun EL Escudo Dos

Only 14 left! COM-10878

We've heard you, and made a number of improvements to our EL Shield. The new version adds zero-crossing optoisolated triacs f…

$24.95

5

FavoritedFavorite5

Wish List

Materials Required

To follow along with this tutorial, we recommend you have access to the following materials in addition to your Sequencer or Escudo Dos.

Suggested Reading

If you aren’t familiar with the following concepts, we recommend reviewing them before beginning to work with the EL Sequencer or Escudo Dos.

• Installing the Arduino IDE
• How to Power Your Project
• Battery Technologies
• How to Solder
• AC vs. DC Current

Hardware Overview - Similarities

This section will cover the features that are shared between both the EL Sequencer and the EL Escudo Dos.

External Power Headers

External Power Headers on the EL Sequencer.

There are three power connection points on the Sequencer. The first is the AC In connection, which is the default connection point for any external inverter. The second connection is the DC Out line, which will connect to any inverter that does not have an external power supply. This provides a DC power supply to the inverter from the EL Sequencer itself. The final power connection is the Batt In connection. This allows the user to provide a power supply from a 3.7V lipo battery, or other power supply of 3.5V-16V.

These can be connected via a standard 0.1" 2-pin header, or via the JST connector available on each line. If you ever forget the purpose of these connections, they are clearly labeled on the bottom of the board.

External Power Headers on the EL Escudo Dos.

The power headers on the EL Escudo Dos have the same functionality as the EL Sequencer. However, there is no Batt In header. This is because the power for the Escudo comes from the VRAW line on the connected Arduino or RedBoard.

Channel Headers (HIGH VOLTAGE)

Channel Headers on the Sequencer

Channel Headers on the Escudo Dos

As the silk on the bottom side of the board states, there is high voltage in this area of the board. Care must be given when handling the board in a powered state, to prevent a shock to the user. These channels output the AC current needed to drive the EL wire. This is output at 100+V AC, 4000Hz (dependent on the inverter used). Each channel (A-H) is attached to one digital pin on the ATMega328 (pins 2-9, respectively). Driving the digital pins HIGH triggers the EL wire to turn on.

These can be connected to EL devices (wire, panels, etc.) via a standard 0.1" 2-pin header, or via the JST connector available on each line.

Solder Jumpers

• SJ1 - This jumper allows the user to bypass the LM317 regulator when it’s shorted. This regulator is used for external inverters. If left open, the regulator output voltage can be modified by user-supplied resistors on RA and RB pads. More on that below.

Solder Jumper 1 on the Sequencer.

Solder Jumper 1 on the Escudo.

• SJ2 - This jumper is included as an option for wirelessly uploading of code to the Sequencer via XBee. This feature is experimental, and no guarantees are given for this feature’s functionality.

Solder Jumper 2 on the Sequencer. This jumper is not present on the Escudo.

TRIACs and Optoisolators

The main functionality of the Sequencer/Escudo comes from the TRIACs (Triode for Alternating Current) on-board. The MO3063S TRIAC Optocoupler takes the logic output from the associated ATMega328 digital pin which triggers the Z0103MN TRIAC to open the flow of the AC current from the inverter through the gate to drive the EL channel. This keeps the AC side of the circuit optically isolated from the DC portion of the circuit.

EL Sequencer TRIACs and Optoisolators

EL EscudoDos TRIACs and Optoisolators

Adjustable Voltage Regulator

The LM317 voltage regulator on this board is adjustable based on the resistor values applied to it. By default, this board comes shipped with a 390Ω resistor on R1 and a 240Ω on R2. However, footprints for thru-hole resistors (A and B) have been added for the user to adjust the voltage out to their project needs. You’ll need to remove the SMD resistors first. Then add thru-hole resistors of your choice. See the LM317 Datasheet for more information on which resistor values correspond to which voltage output.

Resistors A and B on the EL Sequencer

Resistors A and B on the EL Escudo Dos

Hardware Overview - EL Sequencer

This section will cover the unique features of the EL Sequencer.

NRF24L01+ Header

This header is designed to interface with an NRF24L01+ module breakout. This provides a 2.4GHz signal to the EL Sequencer, which provides remote control options for the Sequencer at up to a 100m range.

FTDI Header

This is a 5V FTDI header, which is given to provide simple access for reprogramming the ATMega328 via serial connections. This can also be used to have the EL wire triggered via serial data in to the system.

XBee Header

This connection is provided to give users the option of wirelessly connecting the EL Sequencer via XBee. This can be used for mesh networking of several different Sequencers together (this is great for group costume projects), or remote control of the Sequencer.

ICSP Header

This 6-pin header is provided to allow the user to reprogram the ATMega328 on board via an external programmer. This also allows you to reprogram the EL Sequencer without the requirement of the Optiboot loader from the Arduino IDE.

Analog Input Header

The additional analog pins on the ATMega328 are broken out to a standard 0.1" header on the EL Sequencer. This also gives the user the capability to trigger the EL wires from analog inputs (such as a photocell, temperature sensor, or a line sensor ).

Pins A6 and A7 are analog input only. Pins A0-A5 can be used as an analog input or as a digital I/O.

Switches and Reset Button

• XBee to FTDI (far right, center) - This switch changes the RX line from being supplied via the FTDI header or the XBee. If attempting to program the Sequencer via FTDI, this switch must be set to the FTDI side.

• USB/BATT (bottom, center) - This switch changes the power source for the ATMega328. The USB setting allows the ATMega328 to be powered via the FTDI connection, while the BATT setting allows the Arduino part to be powered off of a lipo battery instead.

• Reset Button - Resets the Arduino sketch running on the ATMega328. It pulls the RESET line low, allowing the system to reset.

Hardware Overview - EL Escudo Dos

This section will cover the unique features of the EL Escudo Dos Arduino Shield.

Shield Headers

These headers allow the shield to be connected to any Arduino Uno/Uno R3 compatible board. We will be using the SparkFun RedBoard for this example.

Channel Headers

The EL Escudo also provides a row of 0.1" spaced headers to allow the user to read the signals from the microcontroller to the EL wires. This is beneficial for debugging.

Hardware Hookup

To get started using the EL Sequencer or EL Escudo Dos, there are a few basic steps that must be completed.

Solder Headers

EL Sequencer

At an absolute bare minimum, you must solder 6 pins on the FTDI header. For simplicity’s sake, we recommend using male headers (either straight or right angle as these are compatible by default with the FTDI breakout). This will enable you to program the EL Sequencer via an FTDI breakout board.

If you plan on using an XBee unit with your Sequencer, you will also want to solder XBee Sockets to the board. If you plan on using any additional connectors on the board, you will also want to solder those headers on now. Keep in mind you may also want to trim off any excess header on the bottom of the board if you intend to use this in a wearable application.

EL Escudo Dos

Thanks to the simplified design, you only need to solder Arduino shield headers onto the Escudo. If you want to use any additional components in your project (such as wireless modules or external sensors), you will want to use stackable headers.

Connect the EL Wire

You have 8 channels available on the Sequencer to which you can plug in EL wire, chasing EL wire, or EL panels.

Please check out this tutorial on working with EL Wire specifically, and the current requirements for different types of materials.

Connect the Inverter

Once you have hooked all of your EL wires up, the next step is to hook up the inverter.

• 3V Inverter - If you are using the 3V inverter, you will need to hook up both wire pairs from the inverter to the Sequencer. The black/black wire pair will plug into the AC In JST connector, while the red/black wire pair plugs into the DC Out JST connector.

• 12V Inverter - While using the 12V inverter, there is only one wire pair that will plug into the Sequencer. The red/black wire pair will plug into the AC In JST connector. You will need a separate power supply to run this inverter (such as the 12VDC 600mA Wall Adapter).

Connect the Power Supply

EL Sequencer

If you are using a battery for the power supply, you can connect this to the Batt In JST header without altering the board. Using an external power supply with the 3V inverter will require closing SJ1. You will need to connect that supply to the PTH headers labeled Batt In. Make sure the power supply falls in the range of 3.5V-16V for an external power supply.

EL Escudo Dos

The power supply for the EL Escudo Dos actually comes from the Arduino. We recommend using a 12V wall adapter for powering the Arduino.

Alternatively, if you would like to go wireless, you could use a male barrel jack adapter along with a 12V battery. Typically, however, the EL Sequencer will be a better option for you for wireless applications.

Final Circuit

Once everything is hooked up, your circuit should look something like the following:

Arduino Code

Once you have all of your hardware hooked up properly, it’s time to program your Sequencer to run the EL Wire display as you want. You will need to download the Arduino code in order to follow along with the example.

Download EL Sequencer Example Firmware

You can also download the most up-to-date code from the EL Sequencer GitHub repository.

We will be working with the “SparkFun_EL_Example.ino” example. If you need a review on how to upload Arduino code to your board or using the Arduino IDE, please check our tutorial here. Also, if you are unsure about installing the FTDI drivers, please check out this tutorial.

If using the EL Sequencer:

Plug in your FTDI board to the computer via USB, and insert the FTDI onto the EL Sequencer. Make sure you match up the BLK to BLK and GRN to GRN labels.

When uploading your code, please be sure to select the following settings in the IDE:

• Board: LilyPad Arduino
• Processor: ATMega328
• COM port: Whichever port the FTDI Basic appears on for your operating system.

If using the EL Escudo Dos + RedBoard:

Plug in the RedBoard to the computer via USB. Select the following settings in the IDE:

• Board: Arduino Uno
• COM port: Whichever port the FTDI Basic appears on for your operating system.

Demo Code

This basic demo will cycle through each channel on the Sequencer, one by one, repeating until the system is either reprogrammed or turned off.

In the first section, we must define each pin that we will be using on the ATMega328.

language:c
/*******************Setup Loop***************************/
void setup() {
  // The EL channels are on pins 2 through 9 on the ATMega328
  // Initialize the pins as outputs
  pinMode(2, OUTPUT);  // channel A
  pinMode(3, OUTPUT);  // channel B
  pinMode(4, OUTPUT);  // channel C
  pinMode(5, OUTPUT);  // channel D
  pinMode(6, OUTPUT);  // channel E
  pinMode(7, OUTPUT);  // channel F
  pinMode(8, OUTPUT);  // channel G
  pinMode(9, OUTPUT);  // channel H

//Uncomment the following line if using this on the EL Escudo Dos.
// Pin 10 is a status LED on the EL Escudo.
//  pinMode(10, OUTPUT);

//Pin 13 is the status LED on both the EL Sequencer and Arduino for use with the EL Escudo Dos.
   pinMode(13, OUTPUT);
}

Each pin is declared as an output, which will allow us to drive the channel HIGH or LOW. We will cycle through each channel, turning them on individually, waiting 1/10 second, turning off, and moving to the next channel.

language:c
/*******************Main Loop***************************/
void loop()
{
  int x,status;

  //Step through all eight EL channels (pins 2 through 9)
  for (x=2; x<=9; x++)
  {
    digitalWrite(x, HIGH);   // turn the EL channel on
    delay(100);              // wait for 1/10 second
    digitalWrite(x, LOW);    // turn the EL channel off

//digitalWrite(10, status);   //Uncomment this line if using the EL Escudo Dos
digitalWrite(13, status);   // blink status LEDs
    status = !status;
  }
}

Each time a channel is cycled through, the status LEDs on the board will blink.

Once the code is uploaded, you should see each strand of EL wire light up one by one. If you aren’t seeing that, verify that you have the correct power settings on the USB/Batt switch, and that the inverter is connected properly, switched on (if using the 12V inverter), and that the power supply to the board is properly charged and/or connected.

Going Wireless

If you would like to add wireless capabilities to your project, there’s just a few more steps to get up and running.

• Insert a radio unit: You can either use a paired XBee unit or an NRF24L01+ module. You will need to make sure headers are soldered on for either device. If you need additional information on adding an XBee module, please check out our tutorial here. On the EL Sequencer, you will also need to flip the XBee to FTDI switch to XBee to ensure XBee communication is working properly.

• Update the Code

If using a Series 1 XBee:

Upload the ‘SparkFun_XBee_EL_Sequencer.ino’ sketch to your board. In the first section, the status LED is declared as an output, and the Serial connection is opened at 9600bps.

language:c
//Declare character 'val'
char val;

/*******************Setup Loop***************************/
void setup(){
  Serial.begin(9600); //Begin Serial communication for debugging
  pinMode(13, OUTPUT); //Set pin mode as output for status LED
  val = 'A';// button pressed, therefore sending  letter A

  Serial.println("EL Sequencer's XBee is Ready to Receive Characters");
  digitalWrite(13,LOW); //set Status LED off
  delay(1000); //Wait 1 second
}

The main loop of the code simply waits for the XBee unit to receive the character ‘A’ from a remote XBee unit. If the character is received, the status LED is turned on, and a message is output to the serial terminal.

language:c
/*******************Main Loop***************************/
void loop(){

  //Check if XBee is receiving data from other XBee
  if(Serial.available()){
    val = Serial.read();

    //Check to see if character sent is letter A
    if(val == 'A'){
        digitalWrite(13,HIGH); //turn ON Status LED
        delay(50);
      Serial.println("Character Received");
    }

    else{
      digitalWrite(13,LOW); //turn OFF Status LED
    }
  }
}

If using an NRF24L01+:

You will need to use the RF24 library with the nRF24L01+ boards. We have a tutorial with more information regarding installing this library here.

We recommend using the RF24/examples/Usage/led_remote.ino example sketch. This is already configured to be compatible with the EL Sequencer with 6 channels of EL wire attached and will trigger each channel based on buttons hit on the remote unit.

The EL Sequencer will trigger the channels on and off based on the LED role in the code.

      //
      // LED role.  Receive the state of all buttons, and reflect that in the LEDs
      //

      if ( role == role_led )
      {
        // if there is data ready
        if ( radio.available() )
        {
          // Dump the payloads until we've gotten everything
          while (radio.available())
          {
            // Fetch the payload, and see if this was the last one.
            radio.read( button_states, num_button_pins );

            // Spew it
            printf("Got buttons\n\r");

            // For each button, if the button now on, then toggle the LED
            int i = num_led_pins;
            while(i--)
            {
              if ( button_states[i] )
              {
                led_states[i] ^= HIGH;
                digitalWrite(led_pins[i],led_states[i]);
              }
            }
          }
        }
      }

The code waits until the receiver gets data coming in and then swaps the LED states accordingly (in this case, the LEDs will be replaced with the EL channels).

That’s it!

That’s all you need to do to add wireless capabilities to your EL project. You can now remotely control your EL Sequencer project.

Resources and Going Further

Now that you have your EL Sequencer or EL Escudo Dos up and running, you can start creating your own awesome art displays, interactive costumes, or colorful installations. Making something really neat? Let us know - we’d love to see it!

If you have any feedback, please visit the comments or contact our technical support team at TechSupport@sparkfun.com.

Check out these additional resources for more information and other project ideas.

• MOC3063 Datasheet
• Z0103MN 4Q Triac Datasheet
• LM317 Adjustable Regulator Datasheet
• EL Sequencer GitHub Repository
• EL Escudo Dos GitHub Repository
• EL Wire Burning Man Sign
• EnLightningment
• Setting up an EL display with the EL Escudo Dos
• Heartbeat Straight Jacket
• Safe Jacob’s Ladder

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

FemtoBuck Constant Current LED Driver Hookup Guide V12 a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t430

Introduction

The FemtoBuck is a small-size, single-output constant current LED driver. By default, the FemtoBuck is driven at 330mA. That current can be reduced by either presenting an analog voltage or a PWM signal to the board. It can be increased to 660mA by closing a solder jumper on the board, as described later in this tutorial.

Suggested Reading

Here are some topics you should know before using the FemtoBuck. Have a look if you need more information.

• LEDs
• Resistors
• Voltage
• Current
• Electric Power
• Pulse Width Modulation

FemtoBuck Overview

Connecting the FemtoBuck

For the version 1.2 of the FemtoBuck, we’ve increased the voltage ratings on the parts to allow the input voltage to cover the full 36V range of the AL8805. Note that the supply voltage must be at least 6.0V, and should be at least 2-3V higher than the forward voltage of the LED(s) to be driven.

Since the FemtoBuck is a constant current driver, the current drawn from the supply will drop as supply voltage rises. In general, efficiency of the FemtoBuck is around 95%, depending on the input voltage.

One signal input is provided for dimming control. A ground pin (DGND) is provided to reference against the controlling module for accuracy. Dimming can be done by an analog voltage (20%-100% of max current by varying voltage from .5V-2.5V) or by PWM (so long as PWM minimum voltage is less than .4V and maximum voltage is more than 2.4V) for a full 0-100% range.

Another ground (PGND) pin is available next to the power supply pin to provide a high-current return path. The spacing on the four holes on the input side is 0.1" for standard headers.

The output side has a 0.1" spaced hole pair as well as a 3.5mm spaced hole pair, to allow the user to attach our 3.5mm screw terminals.

The notches on either end of the board allow you to use a zip tie to secure the wires to the board after soldering them down.

The most recent revision has a small solder jumper, highlighted above, that can be closed with a glob of solder to double the output current from 330mA to 660mA. We suggest closing this jumper before soldering headers, terminals, or wires to the nearby holes. Note that it’s very likely that you’ll get some solder on the adjacent resistor pads. That’s perfectly okay. Those pads will be shorted together when you’re done anyway.

Finally, take note of the size of the FemtoBuck. If desired, the entire board can be slid into a piece of 9mm heat shrink tubing to provide insulation and strain relief.

Connecting to an Arduino or Compatible Board

If you have only one or two LEDs, you can connect the FemtoBuck directly to the VIN pin on your Arduino. You will need to power the board from an external supply, as the 5V provided by USB isn’t high enough to power the FemtoBuck (the FemtoBuck won’t turn on below 6V).

If you want more than one FemtoBuck, or if you’ve closed the solder jumper to increase the drive current, you’ll need to add an external power supply. It’s not good to try to run too much current through the traces on the Arduino. Note that the LEDs are wired separately to each FemtoBuck! This is very important; the output of each FemtoBuck must be completely isolated from any other! That means that RGB LEDs with “common” pins (common anode or common cathode) cannot be used with the FemtoBuck!

Multiple LEDs can be connected in series, as shown, and the supply voltage should be at least 2-3V higher than the sum of the forward voltages of the LEDs.

For instance, our blue 3W LEDs have a forward voltage of 3.2V to 3.8V. To be on the safe side, use the highest voltage in the range. If you want to connect four of them, you’d need a power supply of ~17V or greater (3.8V + 3.8V + 3.8V + 3.8V = 15.2V; add 2V of “head room”).

Since 17V is greater than the Arduino can tolerate on its input, we have to provide an external supply for the Arduino as well. This can be the standard 5V USB supply.

Further Increasing Current Drive Strength

If even 660mA isn’t enough current for you, it is possible to increase the maximum current of the FemtoBuck board up to 1A per channel. To do so, replace the current sense resistors with smaller values. To calculate the new value for the resistor, use this formula:

I_LED = 0.1 / R_set

Thus, for a 1A current, you’d want a 0.1Ω resistor. Don’t forget to be wary of current ratings; at 1A, the sense resistor will be dissipating 1/10W, so you probably want a resistor of at least 1/8W rating. The package is a standard 0805.

Resources and Going Further

Consider checking out these other tutorials for more information about concepts in this guide:

• Light - Covers some useful concepts, such as why doubling the current doesn’t appear to double the brightness.
• Diodes - Diodes are a slightly more complex beast than resistors. Our diodes tutorial will help you understand why we need a special device to power them.
• Pico Buck Hookup Guide - Need to control more LEDs? The PicoBuck is just like the FemtoBuck except it has three channels, each capable of providing 350mA. Perfect for controlling high powered RGB LEDS that require control of each color individually.

learn.sparkfun.com |CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

SparkFun Inventor's Kit for Edison Experiment Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t448

Introduction

The SparkFun Inventor’s Kit for Intel® Edison, otherwise known as the Edison SIK, introduces the Edison as a powerful Internet of Things (IoT) platform. The experiments contained within these pages will guide you through programming the Edison using JavaScript and controlling various electronics. Whether you are new to electronics and JavaScript or are looking to take your skills to the next level (to the “cloud!”), this kit is a great starting point.

Included Materials

Here is a complete list of all the parts included in the Edison SIK.

The SparkFun Inventor’s Kit for Intel® Edison includes the following:

• 1x Intel® Edison
• 1x SparkFun Block for Intel® Edison - Base
• 1x SparkFun Block for Intel® Edison - GPIO
• 1x SparkFun Block for Intel® Edison - ADC
• 1x Basic 16x2 Character LCD - White on Black 3.3V
• 1x Mini Photocell
• 1x Temperature Sensor - TMP36
• 1x LED - RGB Diffused Common Cathode
• 20x 100Ω Resistors
• 20x 10kΩ Resistors
• 3x 2N3904 NPN Transistors
• 1x Piezo Speaker
• 1x 10k Trimpot
• 1x USB OTG Cable
• 1x USB microB Cable
• 1x Breadboard
• 1x Intel® Edison Hardware Pack
• 30x Jumper Wires
• 4x Push Buttons
• 1x Screwdriver

If, at any time, you are unsure which part a particular experiment is asking for, reference this section.

Suggested Reading

The following links may help guide you in your journey through the Edison SIK.

• Edison Getting Started Guide - A quick way to program the Edison using the Arduino IDE.
• General Guide to SparkFun Blocks for Intel® Edison - Describes how the Blocks work with the Edison and provides a brief overview of all the available Blocks.
• Intel’s Getting Started Guide - Tutorial on how to get the Edison running with either the Arduino Breakout Board or the Mini Breakout Board.

Each experiment will also have a Suggested Reading section to aid you in understanding the components and concepts used in that particular experiment.

Edison SIK Example Code

Using the Kit

Before exploring the experiments, there are a few items to cover first. If you have completed one of our other Inventor’s Kits before, you should already be familiar with most of the concepts in this section. If this is your first Inventor’s Kit, please read this part carefully to ensure the best possible SIK experience.

Intel® Edison

The Intel® Edison acts as the brain for the kit. The Edison sports a dual-core, 500 MHz Atom Z34XX processor, 1 GB of RAM, and 4 GB of onboard flash storage. It has built-in WiFi and Bluetooth. Those are some impressive statistics, but what does that mean? Well, the Edison is a complete computer in a tiny package. It is even capable of running a Linux operating system! To learn more about the Edison, visit the Edison Getting Started Guide.

Breadboard

Solderless breadboards are the go-to prototyping tool for those getting started with electronics. If you have never used a breadboard before, we recommend reading through our How to Use a Breadboard tutorial before starting with the experiments.

Jumper Wires

This kit includes thirty 7" long jumper wires terminated as male to male. You can use these to connect terminal strips on a solderless breadboard or connect them to the header on the ADC Block.

Screwdriver

We’ve included a pocket screwdriver to aid you in any mechanical portions of this guide. Note that the screwdriver bit can be pulled out from the plastic handle. The bit can be turned around and inserted back into the handle if you need to choose between a Phillips or a flathead driver.

USB Ports

The Edison Base Block has 2 USB ports.

• Console - This port is attached to an FTDI chip that converts USB signals to serial. This allows you to connect to a serial terminal on the Edison. Only the USB microB cable (the 6-foot cable) can fit into this port.
• OTG - OTG stands for On-the-Go, and it means that the Edison can act as a USB host or a USB device. You may plug either the USB microB cable (for using the Edison as a USB device) or the 4-inch USB microA cable (for using the Edison as a USB host) into this port.

Building the Block Stack

Before we can use the Edison in any of our circuits, we must first attach it to the Blocks in the kit. The Blocks stack in a particular order to work best with the kit.

Parts needed

You will need the following parts:

• 1x Intel® Edison
• 1x ADC Block
• 1x Base Block
• 1x GPIO Block
• 1x Edison Hardware Pack

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - ADC

In stock DEV-13327

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

19.9500$14.95

FavoritedFavorite0

Wish List

Added to your cart!

Intel® Edison Hardware Pack

In stock COM-13187

This is a Hardware Pack for the Intel® Edison, with this set you will be provided with increased mechanical strength for sta…

$2.95

7

FavoritedFavorite6

Wish List

Attach the Edison to the ADC Block

Open the Edison Hardware Pack. Put 2 screws through the mounting holes in the Edison, such that the screws' heads are facing up (we’ll call “up” the surface of the Edison with the “Intel® Edison” logo).

Attach 2 standoffs to the screws sticking out the bottom of the Edison. Use the pocket screwdriver to carefully tighten the screws.

Snap the Edison into the socket on the ADC Block. Make sure that the bottoms of the standoffs are protruding through the mounting holes on the ADC Block.

Screw 2 nuts onto the standoffs, securing the Edison to the ADC Block. You can use the pocket screwdriver to hold the screws in place while you tighten the nuts. Go slowly! The nuts can be tightened by hand, but it requires some finesse as they are quite small.

Attach the Base Block

Put 4 screws through the mounting holes on the corners of the ADC Block, such that the screws' heads are facing up (the same direction as the screws securing the Edison).

Attach 4 standoffs to those screws. Use the pocket screwdriver to carefully tighten the screws.

Snap the ADC Block (which has the Edison on top) into the socket on the Base Block. Make sure that the bottoms of the standoffs are protruding through the mounting holes on the Base Block.

Attach the GPIO Block

Attach 4 standoffs to the bottoms of the standoffs that are protruding from the mounting holes on the Base Block.

Snap the Base Block (which has the ADC and Edison mounted on top) into the socket on the GPIO Block. Make sure that the bottoms of the standoffs are protruding through the mounting holes on the GPIO Block.

Screw the remaining 4 nuts onto the standoffs, securing the entire stack of Blocks together.

Flip the entire stack around, and make sure it is in the following order:

1. Edison
2. ADC Block
3. Base Block
4. GPIO Block

Installing the Intel® XDK IoT Edition

The Intel® XDK is Intel’s integrated development environment (IDE) for creating, testing, and deploying mobile apps. We will be using the XDK IoT Edition, which was specifically designed to help users develop Node.js and HTML5 applications for the Intel® Edison and Intel® Galileo.

Download the Installer

The easiest way to install the XDK is to use the Intel® Edison Integrated Installer. This contains the XDK, drivers, and Flashing Tool (to update the Edison Firmware). Follow the link below and download the Installer for your operating system:

Intel® Edison Integrated Installer

Windows

Run the Installer that you just downloaded. You will see a splash screen as it unzips and prepares to install.

Once you get the “Welcome to Intel® Edison” screen, click Next. You might get a screen telling you to install “Java SE Runtime.” Just ignore it, as we will not be developing in Java (JavaScript is not the same as Java!).

Click Next to continue the installation process. The ubiquitous License Agreement will pop up. Feel free to read it (or not).

Select I accept the terms of the license and click Next. You will then be presented with options to install. Deselect Update Image (we will do that separately in the next section), deselect Arduino Software, and select Intel® XDK IoT Edition.

Click Next. On the next screen, make sure that you have enough space to install the programs. Leave the installation directory as default.

Click Next, verify that the installation summary looks correct, and click Next again. Wait a few minutes while the installation completes.

Once the installation process is done, you will see a “Complete” window.

Click Finish. If the Intel® Phone Flash Tool Lite opened during the process, you can leave it open if you wish (we will use it in the next section).

The installer or drivers may ask you to restart your computer.

OS X

The OS X Installer link will download a .tar.gz file. Double-click on that file to extract it. Double-click on the extracted file to run the installer.

Follow the prompts, clicking Next to advance to the next screen. Accept the End User License Agreement when prompted. On the Installation summary screen, click Customize Installation.

Keep the destination folder (/Applications) at the default and click Next. You will be presented with the option to select the components to install. Deselect Arduino Software, and select Intel® XDK IoT Edition.

Click Next and deselect Update firmware image (we will do that manually in the next section).

Click Next and then Install. Wait while the installer downloads. You will then be prompted to install the Phone Flash Tool Lite.

Click Continue and follow the prompts. Once the XDK has finished installing, the XDK can be found under Applications.

Linux

Download the installer, double-click on the file to extract it, and navigate into the directory that it creates.

Double-click on the install.sh script (select Run if prompted) to begin the installer.

If you want the XDK to be available to all users, select Install as root. Otherwise, select Install as root using sudo. Accept the terms of the End User License Agreement, and accept all defaults until you are presented with a summary screen.

Click Customize installation, and accept the default installation directory on the next screen. You will be presented with some installation options.

Deselect Arduino Software, and select Intel® XDK IoT Edition. Click Next.

Deselect Update firmware image, and click Next. There is a chance that your system might be missing some dependencies (e.g. “Dependencies not resolved”).

If so, you will need to open a command prompt and install them using apt-get. For example, I am missing fping, gdebi, and p7zip-full. So, I entered the following commands:

sudo apt-get update
sudo apt-get install fping gdebi p7zip-full

Wait for those to finish installing, and click Re-check on the missing dependencies screen. You should be good to install.

Click Install and wait for the installation to complete (clicking to accept any defaults on prompts). The XDK IoT Edition can be found in /usr/share/applications when the installation is complete.

Updating the Edison Firmware

Most Edisons will ship with an older firmware (perhaps many months out of date). They will either contain bugs or simply not work with the latest version of the XDK IoT Edition. To remedy this problem, we highly recommend updating the firmware on the Edison.

To begin, download the latest firmware. Navigate to Intel’s site using the link below and click to download the latest release of the Yocto complete image.

Intel® Downloads Page

In this example, the latest firmware is “Release 2.1 Yocto complete image”

Once the download is complete, locate the file on your computer, and unzip it.

Updating the Firmware with the Phone Flash Tool

If it is not open already, open the Intel® Phone Flash Tool Lite program that we installed in the last section.

[

Click Browse, and navigate to the unzipped Edison firmware directory. Locate the FlashEdison.json file, and click Open. This will load the firmware into the Phone Flash Tool.

[

Click the Start to flash button. The Phone Flash Tool will tell you to plug in your Edison. Plug the USB micro cable into the OTG Port on the Base Block, and plug the other end into an open USB port of your computer.

The Phone Flash Tool should begin to flash the Edison with a new firmware image.

That’s it! You should see a “Flash success” message in the Phone Flash Tool. If this worked, you can close the Phone Flash Tool Lite, and move on to the next section.

Using the XDK

If you have used other Integrated Development Environments before, the Intel® XDK IoT Edition might look familiar. If not, no worries! We will walk you through how to use the XDK (don’t worry, it’s not very complicated). If you would like to take a look at Intel’s official documentation on the XDK, it can be found here:

Intel® XDK IoT Edition Guide

Starting the XDK for the First Time

Start the Intel® XDK IoT Edition program, and you should be presented with a login screen.

Click Sign Up if you do not already have an Intel Developer Zone Account, and follow the on-screen instructions to create a new account. You will need to accept another Terms and Conditions statement.

The Welcome Screen

Once you have created an account (or not), you will be presented with the welcome screen. In this screen, you can choose an existing project to work on or create a new one.

Click the image above for a larger view.

Creating a Project

To familiarize ourselves with the XDK IDE, we will create a blank project. Click on Templates under the Internet of Things Embedded Application tab. You will see a number of different templates appear that will help you get started with your IoT program. Select the Blank Template.

Click Continue, and you will be presented with a pop-up window to name your project. You can name it anything you want, as we are just using it to explore the IDE right now. To keep all my XDK projects together, I like to use the prefix “XDK_”. I will use “XDK_Blank” for this example.

Click Create. The project screen will greet you with a mostly empty JavaScript file.

The Project Screen

We use the XDK to write code. There are several tools available that help us do that: code examples, syntax completion, a debugging interface, and so on. Once we have finished writing code, we click the Upload button to send that code to the Edison. The Run button then tells the Edison to run the code we just sent to it.

By default, the Yocto image on the Edison contains an “XDK Daemon.” A daemon is a computer program that runs in the background (at least according to Wikipedia). The XDK Daemon begins running as soon as the Edison boots and listens for a connection from a host computer (i.e. one running the XDK IoT Edition). It knows how to receive and store new code, and it will accept commands from the host computer to run, stop, and debug that program.

Connecting to WiFi

We will want connect our Edison to a local WiFi network if we want to program it using the XDK or complete some of the experiments that require Internet access.

Connecting Over Serial

Unplug the USB cable from the OTG port on the Base Block, and plug it into Console port.

If it is not already open, start the XDK, and create a blank project (like we did in Using the XDK). Click on the Serial Terminal tab.

At the very bottom, click the drop-down list for Port and select the Edison device. This will change depending on the operating system. For example, it might be /dev/tty.usbserial-A402IXA0 in OS X, /dev/ttyUSB0 in Linux, or COM78 in Windows. Note that in Windows, you want COMxx[FTDI], not the Standard Serial Port option.

Make sure that the Baud Rate is 115200, Data Bits is 8, Stop Bits is 1, and Parity is “none.” Click Connect, and you should see the Edison’s terminal login appear.

Getting on the Internet

Click in the Serial Terminal window and log in to the Edison:

Username: root

Hit ‘enter’ (there is no password). You should be presented with a root command prompt.

Enter configure_edison --setup. You will be walked through a series of steps. The first will ask you to create a password.

We definitely recommend you set a password! It can be anything you want, so long as you can remember it. If you don’t set a password, evil hackers might be able to control your lights from their car. Or read your emails. That would be bad.

Press ‘enter’ and enter your password again. On the next screen, you will be asked to rename the Edison. You can give it a unique name or just press ‘enter’ to keep the default name. I shall call mine squishy.

The Edison will ask you to confirm the name. Type ‘y’ and press ‘enter’. You will then be asked to set up WiFi. Enter ‘y’ again.

Wait while the Edison scans for networks. You will then be presented with a list of available networks.

Type the number of the network you would like to join and press ‘enter’. Enter ‘y’ to accept the network, and enter the password for that network.

The Edison should automatically connect to the network. Enter ping 8.8.8.8 to try pinging one of Google’s Public DNS servers.

You should see a few responses in the form of “bytes received from 8.8.8.8.” Press ‘ctrl+c’ to stop the pinging. You can get the IP address of the Edison by entering ifconfig.

Under the wlan0 entry, make a note of the inet addr. In my case, it is 10.8.0.171. You can use this to connect to your Edison manually from the IoT Device drop-down menu if, for example, the Bonjour service is not running (if you ran the Installer and accepted all the defaults, Bonjour should have been installed).

Experiment 1: Hello, World!

Introduction

We realize that starting with “Hello, World!” is a cliché in the programming world, but it really is the perfect starting place with the XDK and Edison. We spent quite some time installing the XDK, flashing new firmware, and configuring the Edison. We can test all these things with one line of code!

Parts Needed

You will need the Edison and Block stack that we constructed in Building the Block Stack section.

Suggested Reading

• JavaScript Syntax– Whether you are new to JavaScript or a seasoned developer, you might want to look at how JavaScript statements are structured. For example, JavaScript uses semicolons.
• Oject-Oriented Programming (OOP)– JavaScript relies on objects to get work done. Reading about the history of OOP might be enlightening and entertaining.

Concepts

A Very Light Introduction to Objects

In JavaScript almost everything is an object. What is an object? In the real world, an object is just another word for a thing. A dog, for example, is a type of object.

A dog has properties, such as a breed, a fur color, a name, and so on. Dogs can also do things, like bark, sleep, play, etc.

OK, so how does this translate to the programming world? In most object-oriented languages, an object is a collection of data (bytes stored somewhere on the computer) that has been grouped together and wrapped up in a way that makes for easy access. If we wanted to make a JavaScript version of our dog, we might write something like:

language:javascript
var dog = {
    name: "Roland",
    color: "fawn",
    bark: function() {
        console.log("woof");
    }
};

In this example, we created a variable (as noted by the keyword var) called dog. A variable is a way to store things. In this case, we are storing our object (a collection of properties) in a storage container called dog.

All of the properties for this object are defined between the outside set of curly braces {}. We create a property called name and assign it the value "Roland". If we wanted to get the name of our dog object, we could access that property with:

language:javascript
dog.name;

Calling dog.name results in “Roland”.

In addition to our name and color properties, we also defined a function as a property. If we called

language:javascript
dog.bark();

the dog would do something. Functions are actions! They cause the object to do something. The parentheses () after dog.bark let us know that it is a function. They can also be used to pass parameters to the function, which we will see in a minute. Because bark() is a function inside an object, it is known as a method (functions not part of objects are just called functions).

If we dig into the bark() method, we see that it contains console.log("woof");. console is a special object that is known by most implementations of JavaScript (i.e. it is an object that always exists when we run the program). .log() is a method of the console object. By calling console.log() we can print something to the screen (assuming we have access to some kind of text output console).

"woof" is a parameter, which is a value that is passed to a function. In this case, “woof” is a string (as noted by the double quotes), which is a collection of characters. The function then, ideally, uses that value in its own code. In this case, console.log("woof") prints the word woof to the screen.

Ultimately, calling dog.bark(); prints woof to the screen.

This might be a lot to take in, but never fear! We will revisit these concepts over the course of these experiments. For now, know that objects are containers for properties and methods. We will be using the special console object to output text to the screen.

Hardware Hookup

We won’t need any new hardware. Just connect the USB cable from your computer to the Console Port on the stack you made in Building the Block Stack.

The Code

Open the XDK, and create a new project. Use the Blank Template, and give it an appropriate name (we’ll call this one “XDK_Hello”). If you need a refresher on creating projects, see Using the XDK.

The first thing we want to do is connect to our Edison. To do that, click the drop-down list by IoT Device, and select your Edison device.

You should be presented with a connection screen. Type in the password you set for the Edison in the Password field.

Click Connect. If you get presented with a message claiming that the “Intel XDK Daemon is old” or that you need to sync clocks with the Edison, choose to Update the Dameon or Sync as appropriate and follow the prompts.

Once you have updated, synced, and connected, you should see a message in the console of the Intel XDK IoT tab.

In main.js, add the following line:

language:javascript
console.log("Hello, World!");

Find and click the Upload button.

If you are presented with a message exclaiming that you have “Modified Project Files,” click Save and Proceed.

In the console, you should see the message “Upload Complete.” Press the Run button.

What You Should See

The phrase “Hello, World!” should appear in the console.

If you see this, feel free to celebrate. We’ll wait a moment while you do that.

Why is this simple phrase monumental? Well, it means all our preparing and configuring worked! We wrote a simple program, sent it to the Edison, and had the Edison run it. Cool.

Code to Note

The Console Object

console is a special object that has been pre-defined elsewhere in our JavaScript environment. It outputs to standard output, which is a text display device (real or virtual) for most computer systems.

The Edison relies on Node.js to run JavaScript programs. More information about the console object can be found in the official documentation.

Methods

We mentioned methods briefly in our introduction to objects. In this exercise, we used the .log() method, which takes input in the form of a string (a parameter) and displays it on a new line in the console. The Node.js documentation contains a section on .log().

Comments

There are different ways to make comments in your code. Comments are a great way to quickly describe what is happening in your code.

// This is a comment - anything on a line after "//" is ignored by the computer.

/* This is also a comment - this one can be multi-line, but it must start and end with these characters */

Troubleshooting

• The Edison won’t connect– This is possible if the Edison is not powered or configured properly. See the “Edison won’t connect” section in the Appendix A: Troubleshooting.
• Code will not upload– Make sure the Edison is on the same network as your computer and you have selected your Edison from the IoT Device drop-down menu in the XDK.
• Nothing prints on the console– Make sure that the Edison is connected. Additionally, if you see any errors on the console, read them carefully, as they will often tell where to look in your code (for example, you might have forgotten the quotation marks around “Hello, World!”).
• Nothing works!– Don’t worry! We have an awesome tech support staff to help you out if there is something wrong. Please contact our tech support team.

Going Further

Now that you see how to connect your Edison to the XDK, upload code, and run a program, we will move on to more advanced topics including connecting other pieces of hardware to the Edison Block stack. After each experiment, we will give you a few challenges to try on your own as well as some suggested reading.

Challenges

1. Remember the description of the dog object in the beginning of this chapter? Copy the definition of the dog object (the snippet of JavaScript code) into the XDK. Write some code that has the dog bark (e.g. you will see woof appear in the console). Hint: you will need to use console.log().
2. Using the same dog object example, print out the dog’s name and color to the console.

Digging Deeper

• Node.js official documentation
• Intel’s official getting started with XDK IoT Edition guide
• More on objects in JavaScript

Experiment 2: Pushing Some Buttons

Introduction

In the previous exercise, we tested the connection to the Edison and showed that we could upload code. Now, we can move on to more interesting circuits and examples. In this section, we introduce the humble push button. We connect it to one of the Edison’s general-purpose input/output (GPIO) pins and write some code that does something whenever the button is pushed.

This experiment has 2 parts. Both parts use the same hardware, but each has its own code. We recommend you try them both to get an understanding of the different ways to use button pushes.

Parts Needed

In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x Push Button
• 1x 1kΩ Resistor
• 4x Jumper Wires

The 1kΩ resistor has the color bands brown, black, red, gold

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

Tactile Button Assortment

In stock COM-10302

These tactile buttons are great for all sorts of projects. This assortment comes with 2 of each of 6 different colors for a t…

$4.95

FavoritedFavorite10

Wish List

Suggested Reading

• Switch Basics– How switches and push buttons work.
• Analog vs. Digital– What does it mean to say something is “digital?”
• Resistors– What they do and how to read those funny color bands.
• Pull-up Resistors– How to use resistors to create a default logic level for circuits.

Concepts

Functions

We mentioned briefly in the last section that functions are pieces of code that do things. To make this more clear, a function is a block of code created to perform a particular task. Functions are useful because they can be written once and called many, many times from other parts of code (we call this code reuse).

In our two code examples below, we will write our own functions and then call them. In JavaScript, functions looks like this:

language:JavaScript
function doSomething( /* parameters */ ) {
    /* Things happen here */
}

We know it is a function because we used the function keyword. Thanks for making this explicit, JavaScript. We can also have 0 to any number of parameters in our function. Parameters are variables that are used to store pieces of information passed to the function. For example:

language:JavaScript
function saySomething(thing) {
    console.log(thing);
}

saySomething("Hi");

We first created a function that outputs something to the console. In this case, the function accepts the parameter thing, which becomes a variable. We can access the contents of that variable by writing thing.

Then, we call our function by writing saySomething(). In between the parentheses, we wrote the string "Hi". This string is passed to the saySomething() function as a parameter and assigned to the variable thing. We then print the contents of thing (“Hi” in this example) to the console.

If we wanted to print something else, we could write saySomething("Something else");. And that’s a simple form of code reuse!

Libraries

OK, not THAT kind of library

Libraries are pieces of code that have been packaged up for easy reuse. Often, they are written by someone else (or a group of people).

Node.js (the runtime environment that runs our code on the Edison) uses modules, which are very similar to libraries. Modules are just other pieces of code that we can reuse in our code. In these experiments, we rely heavily on MRAA, which is a library (and subsequent Node.js module) created by Intel and allows us to easily communicate with the hardware pins on the Edison.

We can import the MRAA module with the line

language:JavaScript
var mraa = require('mraa');

With that, all the objects, variables, and functions in the MRAA module are loaded into the variable mraa. We can access those objects, variables, and functions by calling mraa. For example, mraa.Gpio() creates a new GPIO pin that we can access.

The Pull-Up Resistor

We can use a resistor to set a default state of a pin on a microcontroller (or, in this case, the Edison). The pull-up resistor, specifically, sets the state of the pin to a voltage (VCC in the diagram below). For our circuit, we will be using 3.3V as the high voltage. Low will be ground (GND or 0V).

When the switch (or button) is open (as in the diagram), the input pin is VCC. Because little or no current flows through R1, the voltage at the pin is the same (or very nearly the same) as VCC. We will say that the pin is in the “high state” or “logic ‘1’”.

When the switch (or button) is closed, the input pin is the same voltage as GND (0V). The switch creates a short circuit to GND, which causes some current to flow from VCC, through R1, to GND. However, because of the short circuit, the input pin has the same voltage as GND. We will say that the pin is in the “low state” or “logic ‘0’”.

Hardware Hookup

Your kit comes with a bunch of different color push button. All push buttons behave the same, so go ahead and use your favorite color! Follow the Fritzing diagram below.

Fritzing Diagram

Having a hard time seeing the circuit? Click on the Fritzing diagram to see a bigger image.

Tips

The leads across each other on the push buttons are always connected to each other. The leads on the same side are only connected when button is pressed.

Part 1: Polling

The Code

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 2 - Part 1: Pushing Some Buttons
 * This sketch was written by SparkFun Electronics
 * October 27, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * This is a simple example program that displays the state of a button
 * to the console.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA module
var mraa = require('mraa');

// Set up a digital input/output on MRAA pin 36 (GP14)
var buttonPin = new mraa.Gpio(36);

// Set that pin as a digital input (read)
buttonPin.dir(mraa.DIR_IN);

// Call the periodicActivity function
periodicActivity();

// This function is called forever (due to the setTimeout() function)
function periodicActivity() {

    // Read the value of the pin and print it to the screen
    var val = buttonPin.read();
    console.log('Button is ' + val);

    // Wait for 250 ms and call this function again
    setTimeout(periodicActivity, 250);
}

What You Should See

Try pushing the button.

The console should start outputting “Button is 1”, which means that the pin connected to the button is currently in the high state (3.3V, logic ‘1’). When you push the button (hold it down for a second), the console should show “Button is 0”, which means that the pin is in the low state (0V, logic ‘0’).

Code to Note

In JavaScript, functions are objects. Say what? I know it is weird to think about, but they are. The good news is that we can pass functions (like objects) as parameters to other functions. For example, we pass periodicActivity (a function) to setTimeout (another function), which causes periodicActivity to be called every 250 ms (in this example).

Additionally, note that we told MRAA that we want to use pin 36. Pin 36 is defined by MRAA and mapped to GP14, which is the pin definition according to the Edison hardware. Knowing which MRAA pin maps with which GP pin can be confusing, so we crated a nice table in Appendix E. The Edison pinout can be found here.

Part 2: Interrupt Service Routine

The Code

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 2 - Part 2: Interrupt Service Routine
 * This sketch was written by SparkFun Electronics
 * October 27, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * This is a simple example program that prints an incrementing number
 * to the console every time a button is pushed.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA module
var mraa = require('mraa');

// Set up digital input on MRAA pin 36 (GP14)
var buttonPin = new mraa.Gpio(36);
buttonPin.dir(mraa.DIR_IN);

// Global counter
var num = 0;

// Our interrupt service routine
function serviceRoutine() {
    num++;
    console.log("BOOP " + num);
}

// Assign the ISR function to the button push
buttonPin.isr(mraa.EDGE_FALLING, serviceRoutine);

// Do nothing while we wait for the ISR
periodicActivity();
function periodicActivity() {
    setTimeout(periodicActivity, 1000);
}

What You Should See

You should not see anything when you first run the program. Press the button, and the word “BOOP” should appear along with a number. Press the button again, and that number should increment by 1.

Code to Note

Interrupt service routines (ISRs) are important in the world of embedded electronics. It is very similar to JavaScript’s notion of event-driven programming. When a user or some other external force performs an action, the program responds. In this case, whenever a button was pushed, the serviceRoutine() function gets called.

As in the previous polling example, we use a function as a parameter. We pass the function serviceRoutine to the buttonPin.isr() function. We use mraa.EDGE_FALLING to declare that serviceRoutine should be called whenever the pin’s voltage goes from high (3.3V) to low (0V).

Troubleshooting

• The Edison won’t connect– This is possible if the Edison is not powered or configured properly. See the “Edison won’t connect” section in the Appendix A: Troubleshooting.
• Nothing happens when the button is pushed– Double-check the wiring. Often, a jumper wire is off by 1 hole!

Going Further

Challenges

1. Add a second button so that when the first button is pushed, it prints “BOOP” to the console, and when the second button is pushed, it prints “BEEP” to the console.
2. You might have noticed that pushing the button on the second example causes more than one “BOOP” to appear (if not, try pushing the button many times to see if you can get more than one “BOOP” to appear per button push). This is a phenomenon known as bouncing. Modify the Part 2 example to prevent this from happening (known as debouncing).

Digging Deeper

• MRAA GitHub repository
• MRAA JavaScript documentation
• Interrupt service routine

Experiment 3: Blinky

Introduction

Often, blinking an LED is the first step in testing or learning a new microcontroller: a veritable “Hello, World!” of embedded electronics. However, the GPIO Block requires that we introduce a new component, the transistor, into the mix. As a result, we saved the blinky example for the third experiment.

We will connect an LED to the Edison (using the GPIO Block and a transistor). With some JavaScript, we can control that LED by turning it on and off.

Parts Needed

In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x RGB LED
• 1x NPN Transistor
• 1x 1kΩ Resistor
• 1x 100Ω Resistor
• 5x Jumper Wires

The 100Ω resistor has the color bands brown, black, brown, gold

The 1kΩ resistor has the color bands brown, black, red, gold

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

LED - RGB Diffused Common Cathode

In stock COM-09264

Ever hear of a thing called RGB? Red, Green, Blue? How about an RGB LED? These 5mm units have four pins - Cathode is the long…

$1.95

2

FavoritedFavorite5

Wish List

Added to your cart!

Transistor - NPN (2N3904)

In stock COM-00521

These are very common, high quality BJT NPN transistors made by ST Micro. **Datasheet: **[2N3904](http://www.sparkfun.com/da…

$0.5

FavoritedFavorite4

Wish List

Suggested Reading

• Transistors– An introduction to transistors

Concepts

The Transistor

The GPIO Block is not capable of sourcing more than a few milliamps, which is not enough to fully light up an LED. To do that, we will use a transistor. A transistor is a device that can be used to amplify or switch electrical current. We will be using a bipolar junction transistor (BJT), which allows current to flow through the collector and emitter pins whenever a (much smaller) current flows into the base pin.

In this experiment, we will connect the base of the BJT to GP12 on the GPIO Block. When the GP12 pin goes high (3.3V), this causes a little bit of current to flow from GP12 through the base, which turns the transistor on. This allows current to flow from the 3.3V supply (also on the GPIO Block), through the collector, and out the emitter. This current then flows through the 100Ω resistor and LED, turning the LED on.

We can calculate the amount of current flowing through the LED, as we want to make sure it is not over 20mA, as per the RGB LED datasheet. To do that, we need to figure out what the voltage drop across the 100Ω resistor. Starting with 3.3V, we can determine that the voltage across the collector and emitter (Vce) is 0.2V (Vce(sat) in the datasheet) when the transistor is fully on. Again from the LED’s datasheet, we see that that typical drop across the red LED is 2V. As a result, the voltage drop across the resistor can be calculated:

Knowing that the drop across the resistor is 1.1V, we can use Ohm’s Law (V = I x R) to calculate the current flowing through the resistor:

How to Use Logic Like a Vulcan

One of the things that makes the Edison so useful is that it can make complex decisions based on the input it’s getting. For example, you could make a thermostat that turns on a heater if it gets too cold, or a fan if it gets too hot, and it could even water your plants if they get too dry. In order to make such decisions, JavaScript provides a set of logic operations that let you build complex “if” statements. They include:

You can combine these functions to build complex if() statements. For example:

language:c

if ((mode == heat) && ((temperature < threshold) || (override == true))) {
    turnOnHeater();
}

…will turn on a heater if you’re in heating mode AND the temperature is low, OR if you turn on a manual override. Using these logic operators, you can program your Edison to make intelligent decisions and take control of the world around it!

In addition to the comparator ‘==’ and ‘!=’, JavaScript also has the strict comparators ‘===’ and ‘!==’ where the two values being compared need to be the same type (e.g. both a string). See this page to learn more about JavaScript comparators.

Hardware Hookup

Fritzing Diagram

Having a hard time seeing the circuit? Click on the Fritzing diagram to see a bigger image.

Tips

RGB LED

You can use a set of needle nose pliers to bend the LED’s leads and a pair of cutters to fit the LED in the breadboard. Note that there is a flat side on the plastic ring around the bottom of the LED. This denotes the side with the pin that controls the red color. See this tutorial to learn more about polarity.

NPN Transistor

Note that the flat face with the ‘N’ of the transistor in the Fritzing diagram matches up with the flat face (with the writing) of the physical part. With the flat edge facing you, the pins are as follows:

The Code

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 3: Blinky
 * This sketch was written by SparkFun Electronics
 * October 29, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Blink an LED connected to GP12 (need a transistor if using the Base Block).
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA module
var mraa = require('mraa');

// Set up a digital output on MRAA pin 20 (GP12)
var ledPin = new mraa.Gpio(20);
ledPin.dir(mraa.DIR_OUT);

// Global variable to remember the LED state
var led = 0;

// Call this function over and over again
periodicActivity();
function periodicActivity() //
{
    // Switch state of LED
    if (led === 0) {
        led = 1;
    } else {
        led = 0;
    }

    // Turn the LED on
    ledPin.write(led);

    // Wait for 500 ms and call this function again
    setTimeout(periodicActivity, 500);
}

What You Should See

Upload and run the program. The LED should start flashing red.

Code to Note

After we declare the ledPin as an output with mraa.DIR_OUT, we create the variable led that stores the state of the led (‘1’ for on and ‘0’ for off). Because this variable (and similarly mraa and ledPin) is declared outside of any object or function, they are considered global variables, which means they can be accessed by any function, object, etc. in the entire program. In most programming circles, using global variables is considered very bad practice. However, we rely on them in most of our examples because:

1. JavaScript makes creating and accessing global variables very easy. This is not a legitimate excuse, but it does make the examples easier to follow.
2. Most of the examples are simple, 1-file programs where we can keep track of all the global variables. Global variables are still used by embedded programmers, as most embedded programs are relatively small and they allow for different types of CPU, RAM, or storage optimization.

Troubleshooting

• The Edison won’t connect– This is possible if the Edison is not powered or configured properly. See the “Edison won’t connect” section in the Appendix A: Troubleshooting.
• The LED doesn’t flash– Once again, check the wiring. Make sure you are connecting the base of the transistor to GP12 (through a 1kΩ resistor). Additionally, you can add some console.log() statements in the code to see if certain parts are being executed.

Going Further

Challenges

1. Make the LED turn on for 1 second and off for 1 second.
2. Make the LED turn on for 200 ms and off for 1 second.
3. Add a button (like in the previous experiment). Create a program such that the LED turns on only when the button is pushed.

Digging Deeper

• More information about the history, making of, and different types of transistors
• General-purpose input/output (GPIO)
• Accessing GPIO in Linux

Experiment 4: Email Notifier

Introduction

While flashing an LED is not the most interesting activity, we could use the LED as a way to notify us if something is happening. For example, we could turn on an LED if we have a new email. That way, we would know that we needed to check our inbox!

To do this, we will have the Edison log in to an email account, read the number of unread emails, and turn on an LED if it is over 0.

Parts Needed

We’ll be using the same circuit as in the previous example, so you don’t need to build anything new! In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x RGB LED
• 1x NPN Transistor
• 1x 1kΩ Resistor
• 1x 100Ω Resistor
• 5x Jumper Wires

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

LED - RGB Diffused Common Cathode

In stock COM-09264

Ever hear of a thing called RGB? Red, Green, Blue? How about an RGB LED? These 5mm units have four pins - Cathode is the long…

$1.95

2

FavoritedFavorite5

Wish List

Added to your cart!

Transistor - NPN (2N3904)

In stock COM-00521

These are very common, high quality BJT NPN transistors made by ST Micro. **Datasheet: **[2N3904](http://www.sparkfun.com/da…

$0.5

FavoritedFavorite4

Wish List

Suggested Reading

• How Email Works– What actually happens when you send an email
• Callbacks– What is a callback function?

Concepts

External Modules

In the previous few examples, we have been relying on the MRAA module to control various hardware from the Edison. MRAA comes pre-installed on the Edison, so we did not have to perform any extra steps to install it. However, in this example, we will use node-imap, which contains several useful functions for connecting to Internet Message Access Protocol (IMAP) servers and retrieving email.

If we were to log in to the Edison via SSH or serial terminal, we could install Node.js packages (e.g. modules) using the npm command (e.g. npm install imap). However, with the XDK, we can tell the IDE to install necessary modules automatically whenever we upload code. This is accomplished by adding the library name to a list of dependencies in the project. The specifics on how to do this can be found in “The Code” section.

Callbacks

I wonder if caller ID was a feature

A callback is a piece of code (often a function) that is expected to be called by another piece of code at a convenient time. A popular way to use callbacks in web programming is to assign a function to a mouse click event. For example:

language:JavaScript
element.on('click', myFunction);

myFunction() {
    console.log("Hi!");
}

Whenever a user clicks on the web page element (called element in this example), myFunction() gets called. In this instance, myFunction() is the callback, and our assignment, element.on('click', myFunction);, is known as creating an event handler. See here to learn more about the .on() event handler.

Hardware Hookup

The circuit is the same as in the previous experiment.

Having a hard time seeing the circuit? Click on the Fritzing diagram to see a bigger image.

The Code

Create a new project in the XDK. Click on package.json in the files browser on the left pane. Add the line

language:JavaScript"imap": "0.8.16"

under "dependencies". This will tell the XDK to download and install the node-imap v0.8.16 module before running the program.

Copy the following code into main.js. If you are not using Gmail, you can comment out (or delete) the part labeled “Set email credentials (Gmail)”. If you are using Yahoo, you will want to uncomment the part labeled “Set email credentials (Yahoo)”.

Finally, change the <username> and <password> parts to your actual email username and password.

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 4: Email Notifier
 * This sketch was written by SparkFun Electronics
 * October 29, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Connect to an email service and turn on an LED if there are any unread
 * emails.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA and IMAP modules
var mraa = require('mraa');
var Imap = require('imap');

// Set up a digital output on MRAA pin 20 (GP12)
var ledPin = new mraa.Gpio(20);
ledPin.dir(mraa.DIR_OUT);

// It's usually a good idea to set the LED to an initial state
ledPin.write(0);

// Global LED variable to know if the LED should be on or off
var led = 0;

// Set email credentials (Gmail)
// Turn on "Acess for less secure apps" in Google account settings
// https://www.google.com/settings/security/lesssecureapps
var imap = new Imap({
  user: "<username>@gmail.com",
  password: "<password>",
  host: "imap.gmail.com",
  port: 993,
  tls: true
});

// Set email credentials (Yahoo)
/*var imap = new Imap({
  user: "<username>@yahoo.com",
  password: "<password>",
  host: "imap.mail.yahoo.com",
  port: 993,
  tls: true
});*/

// Open the mail box with the name "INBOX"
function openInbox(cb) {
  imap.openBox("INBOX", true, cb);
}

// This is called when a connection is successfully made to the IMAP server.
// In this case, we open the Inbox and look for all unread ("unseen")
// emails. If there are any unread emails, turn on a LED.
imap.on('ready', function() {
    openInbox(function(err, box) {
        if (err) throw err;

        // Search for unread emails in the Inbox
        imap.search(["UNSEEN"], function(err, results) {
            if (err) throw err;

            // Print the number of unread emails
            console.log("Unread emails: " + results.length);

            // If there are unread emails, turn on an LED
            if (results.length > 0) {
                ledPin.write(1);
            } else {
                ledPin.write(0);
            }

            // Close the connection
            imap.end();
        });
    });
});

// If we get an error (e.g. failed to connect), print that error
imap.on('error', function(err) {
    console.log(err);
});

// When we close the connection, print it to the console
imap.on('end', function() {
  console.log("Connection closed.");
});

// Call this function over and over again
periodicActivity();
function periodicActivity() //
{
    // Perform a quick connection to the IMAP server and look for unread emails
    imap.connect();

    // Wait for 10 seconds before checking for emails again
    setTimeout(periodicActivity, 10000);
}

What You Should See

When uploading the code, you might see some notifications that the XDK is downloading and installing npm packages. Just be patient while the packages are installed.

When you run the code, it should connect to your email account and print to the console the number of unread emails every 10 seconds.

I really should get in the habit of checking my emails more often

If you have one or more unread emails, the red LED should come on.

Code to Note

Callbacks

I know that we talked about callbacks in the Concepts section, but now we get to see them in action. The node-imap package heavily relies on them, so it is important to get used to them if you plan to use that package in the future.

imap.on is used several times. This function gets called when something particular happens in our program. These are known as “Connection Events” according to the Application Program Interface (API) documentation. We can define particular connection events using strings.

For example, imap.on('ready', function() {...}); allows us to define a function (as noted by the function() keyword) that is called whenever a successful connection is made with the IMAP server.

imap.on('error', function() {...}); is called if there is a problem making a connection.

imap.on('end', function() {...}); is called whenever the connection with the server is closed.

There is another seemingly odd callback. In our imap.on('ready',...) code, we call openInbox(function(err, box) {...});. A few lines above, we define the openInbox() function, which tells the imap object to open our inbox and then call another function (as denoted by cb for “callback”). This callback function (cb) is the function we defined inside openInbox(function(err, box) {...});. So yes, we call a function that accepts another function as a parameter, which then calls that function as a callback. Don’t worry if this was confusing; it is a bit hard to follow. Knowing how to use the .on() callback functions is the most important part of this exercise.

Error Handling

Being able to appropriately deal with errors is a very useful ability in a program. The example relies on if (err) throw err; to determine if an error has occurred (e.g. could not connect to the IMAP server).

If we dig into the node-imap code, we would likely find a few catch statements. if (err) only executes the second part (throw err) if an err actually exists (not null or undefined). throw stops execution within that loop, function, etc., and program control is passed to the first catch statement it finds within the calling stack (e.g. look for a function that called the callback withing a try/catch statement).

If an error occurs, the node-imap module calls our callback function imap.on('error', function() {...});, which lets us handle the error. In this case, all we do is print the error to the console.

Troubleshooting

• It won’t connect to the IMAP server– This could be caused by several reasons:
  • Make sure your Edison has Internet access
  • Ensure you are using the correct IMAP server settings (Gmail and Yahoo examples are given in the code)
  • Check that your email and password are correct in the code
• The LED won’t come on– As always, double-check the wiring. Make sure you are seeing Unread emails: is appearing in the console, and that number is at least 1. Be patient, as it can take a few seconds for the program to make a connection to the IMAP server.

Going Further

Challenges

1. Have the LED flash rapidly when there are unread emails.
2. Have the LED turn on only when there are unread emails from a particular sender (e.g. a friend or your boss). You will need to carefully read the examples in the node-imap documentation.
3. When you receive a new email, print its contents to the console and flash the LED. Hint: Take a look at the mail(...) callback in Connection Events in the node-imap documentation.

Digging Deeper

• How IMAP works
• Handling errors with try, catch, and throw in JavaScript
• How the throw statement works
• node-imap GitHub repository and documentation

Experiment 5: Web Page

Introduction

We know that we are exhausting this one LED circuit, but it really does prove useful in showing different features of the Edison. Hopefully, it spawns some cool project ideas for you! Just remember, if you can blink an LED, you can connect that output to any number of electrical devices. Relays, for example, are great for controlling more powerful components, like light bulbs, ceiling fans, and toasters. Additionally, going from an output (e.g. an LED) to an input (e.g. a button) is not too difficult.

Now that we have reached out to our email inbox to light an LED, why don’t we serve up a web page that allows us to control that LED? This experiment is divided into 2 parts. In the first section, we will create a basic web page that we can navigate to from any computer on the network. In the second section, we add a button to that page to allow control over an LED attached to the Edison.

Parts Needed

We’ll be using the same circuit as in the previous example, so you don’t need to build anything new! In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x RGB LED
• 1x NPN Transistor
• 1x 1kΩ Resistor
• 1x 100Ω Resistor
• 5x Jumper Wires

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

LED - RGB Diffused Common Cathode

In stock COM-09264

Ever hear of a thing called RGB? Red, Green, Blue? How about an RGB LED? These 5mm units have four pins - Cathode is the long…

$1.95

2

FavoritedFavorite5

Wish List

Added to your cart!

Transistor - NPN (2N3904)

In stock COM-00521

These are very common, high quality BJT NPN transistors made by ST Micro. **Datasheet: **[2N3904](http://www.sparkfun.com/da…

$0.5

FavoritedFavorite4

Wish List

Suggested Reading

• How Web Servers Work– A look at how information is served to your computer when you browse a web site
• Introduction to HTML– HyperText Markup Language (HTML) is a fairly old computer language still in use today to create web pages. We will be using some HTML to make our web page.
• WebSockets– We will use the socket.io module in the second part of this exercise to implement WebSockets. This will allow us to create a connection between the Edison and another computer so we can simple commands (like toggle an LED).

Concepts

Browsing to a Web Page

It’s like a series of tubes!

In simplest terms, when you “browse to a web page,” your computer makes a request to a remote server somewhere on the Internet. The actual server (physical computer) you are accessing can be anywhere in the world (assuming it also has Internet access). The server then sends an HTML file back to your computer, which your browser (Chrome, Safari, Firefox, IE, etc.) parses and displays the HTML elements in a human-readable format.

We will be constructing a very simple web page on our Edison using HTML. We will use the Node.js http module to create this page and host it as a web server from within the Edison. As a result, we can browse to the Edison from any computer on the same network, and it will show us a web page!

WebSockets

WebSockets is another protocol for sending and receiving messages across the Internet (or other networked computers). As long as Transmission Control Protocol (TCP) can be realized on the network, WebSockets can be used to transmit messages. WebSockets is similar to HyperText Transfer Protocol (HTTP) in that they both rely on TCP and are used for transmitting data across a network. However, WebSockets uses far less overhead and can be used for communication between client and server with lower latency than HTTP. See this article to read more about WebSockets vs. HTTP.

In the second part of this experiment, we rely on the socket.io module to handle WebSockets in JavaScript for us. This allows us to create a connection from our browser (on our host computer) to the web server running on the Edison and send messages back and forth. We will use a simple message that causes an LED connected to the Edison to turn on and off.

Hardware Hookup

The circuit is the same as in the previous experiment.

Having a hard time seeing the circuit? Click on the Fritzing diagram to see a bigger image.

Part 1: A Simple Web Page

The Code

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 5 - Part 1: Web Page
 * This sketch was written by SparkFun Electronics
 * November 1, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Serves a very simple web page from the Edison.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the HTTP module
var http = require('http');

// Which port we should connect to
var port = 4242;

// Create a web server that serves a simple web page
var server = http.createServer(function(req, res) {
    res.writeHead(200);
    res.write("<!DOCTYPE html>                                             \<html>                                                      \<head>                                                      \<title>My Page</title>                                  \</head>                                                     \<body>                                                      \<p>This is my page. There are many like it,             \
                    but this one is mine.</p>                               \</body>                                                     \</html>");
    res.end();
});

// Run the server on a particular port
server.listen(port, function() {
    console.log('Server listening on port ' + port);
});

What You Should See

Upload and run the code on the Edison. The console should notify you with Server listening on port 4242. Open a web browser and navigate to http://<Edison's IP address>:4242. You can find the Edison’s IP address from the XDK under the IoT Device: drop-down menu. For example, my Edison had the IP address of 10.8.0.171, so I navigated to http://10.8.0.171:4242 in my browser.

Viewing our web page from the host computer

If you have another computer or a smartphone that is on the same network as the Edison, you can also try navigating to the same page.

Viewing the same web page from a smartphone

Note that we are not using the LED in this part, that’s next!

Code to Note

This example is a special case where we write 2 different languages in one file. While most of our code is JavaScript, we write HTML as one long string as an input to the res.write() function. res is the response of our server, so it sends out the string inside res.write() to the client whenever a request is made. Note that we use the character ‘\’ to separate lines in a string in JavaScript. The ‘\’ is ignored, but it prevents the string from ending when we move to a new line.

HTML uses tags, as noted by the <> characters, to tell the browser how to structure the page and display text. For example, you could put <b> and </b> around some text to make it bold (try it!). In our example, we use <head> to mark the header of the page, which appears in the tab or title bar, and <body> to mark the main part of the page, which is the text that appears in the browser window. To learn more about tags, see here.

Part 2: Web Page Button

The Code

Add "socket.io": "1.3.7" to "dependencies" in package.json, which should look like:

language:JavaScript
{"name": "blankapp","description": "","version": "0.0.0","main": "main.js","engines": {"node": ">=0.10.0"
  },"dependencies": {"socket.io": "1.3.7"
  }
}

In main.js, copy in the following code:

language:JavaScript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 5 - Part 2: Web Page Button
 * This sketch was written by SparkFun Electronics
 * November 1, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Serves a web page that allows users to turn an LED on and off remotely.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA and HTTP modules
var mraa = require('mraa');
var http = require('http');

// Set up a digital output on MRAA pin 20 (GP12) for the LED
var ledPin = new mraa.Gpio(20);
ledPin.dir(mraa.DIR_OUT);
ledPin.write(0);

// Global LED variable to know if the LED should be on or off
var led = 0;

// Which port we should connect to
var port = 4242;

// Create a web server that serves a simple web page with a button
var server = http.createServer(function(req, res) {
    res.writeHead(200);
    res.write("<!DOCTYPE html>                                             \<html>                                                      \<head>                                                      \<title>LED Controller</title>                           \<script src='/socket.io/socket.io.js'></script>         \</head>                                                     \<body>                                                      \<p><button onclick='toggle()'>TOGGLE</button></p>       \<script>                                                \
                        var socket = io.connect('http://" +
                            req.socket.address().address + ":" +
                            port + "');                                     \
                        function toggle() {                                 \
                            socket.emit('toggle');                          \
                        }                                                   \</script>                                               \</body>                                                     \</html>");
    res.end();
});

// Listen for a socket connection
var io = require('socket.io').listen(server);

// Wait for a client to connect
io.on('connection', function(socket) {
    console.log('A client is connected!');

    // Look for the "toggle" message from the client, and toggle the LED
    socket.on('toggle', function() {
        led = led ? 0 : 1;
        ledPin.write(led);
    });
});

// Run the server on a particular port
server.listen(port, function() {
    console.log('Server listening on port ' + port);
});

What You Should See

Like in the previous part, run the code and navigate to http://<Edison's IP address>:4242 with your browser. You should see a button labeled TOGGLE. Push it.

We doubt you will be able to resist the allure of a single button

When you click the button, the LED connected to the Edison should come on. Click the button again, and the LED should turn off.

Code to Note

If you thought HTML inside a JavaScript file was bad, take a look at the code for this example. We have JavaScript inside HTML inside a JavaScript file. Mind = blown. The JavaScript inside HTML is denoted by the <script> and </script> tags. As before, we are constructing one long string to send to the client’s browser. The client’s browser should be able to interpret the HTML and display a simple web page. Additionally, most modern browsers are capable of running JavaScript.

The JavaScript embedded in the HTML actually runs on the client’s browser (not the Edison). src='/socket.io/socket.io.js' requests the socket.io library from the server (assuming the server is running socket.io). var socket = io.connect('http://" + req.socket.address().address + ":" + port + "'); creates a socket.io connection back to the Edison (we get the Edison’s IP address from the client’s request in req and the port from the global port value). We also define function toggle() { socket.emit('toggle'); } that sends the very simple message “toggle” back to the Edison over the socket.io connection. This function is called whenever the button is pushed, as per <button onclick='toggle()'>TOGGLE</button>.

On the server (Edison), serving the web page is accomplished in the same manner as in the first part of this experiment. The difference is we add a socket.io server that listens for incoming socket.io (WebSocket) connections in addition to listening for requests for a web page. We define var io = require('socket.io').listen(server); to listen to connections using the same web page server we created in the beginning of the code. We can then handle incoming socket.io connections with io.on('connection', function(socket) { ... });.

Within the io.on('connection', ... ); code, we define the callback socket.on('toggle', function() { ... });, which listens for the message “toggle” on the socket that we created (the variable socket was passed as a parameter from function(socket) { ... }). In this case, we simply toggle the LED (the ternary operator ? is a shortcut for a simple if statement; read more about it here).

Troubleshooting

• My browser can’t find the web page– Double-check the HTML in your code to make sure it matches the example. Then, make sure your client computer is on the same network (e.g. if the Edison has the IP address 10.8.0.x, then your computer should also have an IP address on the same 10.8.0.x subnet).
• I don’t see a TOGGLE button– If you just completed the first part and are moving to the second part, make sure you refresh the page in your browser to get the new HTML from the Edison.
• Nothing happens when I push the TOGGLE button– Make sure that you are actually connecting to the Edison server (you should see A client is connected! appear in the XDK console). If not, double check the HTML and IP addresses of the Edison and your computer.

Going Further

Challenges

1. Change the web page in part 1 so that it contains the name of your favorite famous scientist and a link to their Wikipedia page (hint).
2. Have the web page button in part 2 change to say “ON” and “OFF” as appropriate to reflect the state of the LED. When you click on the button, it should update to show the LED’s state.
3. We’ve shown you how to make a web page interact with the physical world. Now, it’s your turn to make the physical world interact with a web page. Add a button circuit (see Experiment 2) and have it so that when you push the physical button, a piece of text changes on the website (for example, you could have a counter showing how many times the button was pushed).

Digging Deeper

• Node.js http module documentation
• Socket.io documentation
• HTML tags reference

Experiment 6: RGB LED Phone App

Introduction

In the previous experiment, we used WebSockets to create a connection from a client (browser) to the server (Edison). With them, we can send data back and forth to control a simple LED.

In this experiment, we introduce the concept of Web Apps, which are applications designed to run in a browser. Specifically, we will create an HTML application intended for a smartphone. Because the application is written in HTML, it should be capable of running on most phone operating systems, including iOS, Android, and Windows Phone/Mobile.

Parts Needed

In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x RGB LED
• 3x NPN Transistor
• 3x 1kΩ Resistor
• 3x 100Ω Resistor
• 12x Jumper Wires

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

LED - RGB Diffused Common Cathode

In stock COM-09264

Ever hear of a thing called RGB? Red, Green, Blue? How about an RGB LED? These 5mm units have four pins - Cathode is the long…

$1.95

2

FavoritedFavorite5

Wish List

Added to your cart!

Transistor - NPN (2N3904)

In stock COM-00521

These are very common, high quality BJT NPN transistors made by ST Micro. **Datasheet: **[2N3904](http://www.sparkfun.com/da…

$0.5

FavoritedFavorite4

Wish List

Suggested Reading

• Web App Using Intel® XDK– Creating a simple Web App using the XDK
• Pulse-width Modulation– How PWM works, and how to use to control the brightness of an LED
• JavaScript basics– Introduction to JavaScript in the context of web applications

Concepts

Web App

A web application (or web app for short) is a program that runs on a client’s browser (although, some of the computing may be shared by the server). With the rise of HTML5 and JavaScript, most browsers are capable of running simple (or even complex) programs with these now ubiquitous languages.

Many smartphones have built-in or third-party browsers capable of running HTML5 and JavaScript. As a result, we can write software in the XDK that runs inside a phone’s browser. This allow us to make programs that run across a variety of operating systems and can make network connections (e.g. to the Internet or the Edison). The down side is that some of the phone’s native capabilities (e.g. accelerometer, GPS, camera) are not available to web apps. If we want native functionality, we either need to create a native app, designed specifically for a particular phone or operating system, or we need to make a hybrid app, which combined native functionality and web app portability.

We will cover hybrid apps (with Cordova) in a future exercise.

Web App Libraries

In previous examples, we included libraries by adding the appropriate name and version (usually found from npmjs.com) into the package.json file. This told the XDK to download the Node library, build it (if needed), and transfer it to the Edison along with the other necessary program files.

When building a web app, it is often necessary to include other pieces of code as a library, much like we did with Node modules. However, the XDK does not have a good way of automatically knowing which libraries to find when it comes to web apps. As a result, we will need to manually download the library (often packaged as a .js file) and include it with the project files.

The suggested file structure of a web app looks slightly different from the file structure of the Node.js IoT application. In fact, it looks very much like the suggested file structure for web pages. We will keep HTML (user interface) in index.html, JavaScript in js/app.js, and libraries (usually, third-party .js files) in the js directory.

LED Current

The brightness of an LED is controlled by the amount of current flowing through it. LEDs, generally, have a fixed voltage drop across their anode and cathode. In order to fix the amount of current, we usually need to choose the right resistor for the LED.

In our previous circuit, we used just the red channel of the RGB LED, which we will assume is 1 LED. We found that the red LED has a voltage drop of about 2.0V, and by using a 100Ω resistor and a 3.3V rail, we could get 11mA to pass through the resistor (well below its maximum current rating of 20mA.

Now, we want to add 2 more LEDs into the mix. The green and blue LEDs (all packaged within the same RGB LED housing) have a voltage drop of about 3.2V (according to the RGB LED datasheet). If we connect a 100Ω resistor to each of the green and blue LEDs and connect that to the 3.3V rail through a transistor (like we did for red), we would end up with almost no current flowing through them. They probably wouldn’t turn on!

That can’t happen! So, we need to increase the rail voltage that we are using for the green and blue LEDs (and not for the red channel). We will connect the collector of the transistors for green and blue to the V_SYS rail, which is nominally 4.2V.

Now, we should have some current flowing through our green and blue LEDs. We can calculate that voltage drop across the 100Ω resistor:

With that, we can calculate the current flowing through the resistor (and, as a result, the LED):

8mA is not exaclty the same as the current flowing through the red LED (11mA), so the brightnesses will be different. For our purposes, it will be good enough to demonstrate how to mix red, green, and blue into different colors.

Pulse Width Modulation

In addition to controlling the current, we can also rapidly turn the LED off and on to give the appearance of a dimmer LED. This is known as “Pulse-Width Modulation” (PWM). Note that we are flipping the LED off and on so fast that generally our eyes cannot see the flickering.

We adjust the “duty cycle” of this flipping process in order to control the brightness. Duty cycle just refers to how long our LED stays on in relation to how long it stays off.

The higher the duty cycle (e.g. 75% in the image above), the brighter the LED will appear to be. At lower duty cycles (e.g. 25%) the LED will hardly appear to be on. For a full tutorial on PWM, see Pulse-width Modulation.

In our program, we will rely on the Edison’s built-in PWM functionality (using MRAA’s PWM class) to control the duty cycle of the individual red, green, and blue channels of the LED.

Hardware Hookup

Fritzing Diagram

We build upon the previous, single LED example and add another set of transistors and resistors.

Having a hard time seeing the circuit? Click on the Fritzing diagram to see a bigger image.

Part 1: Simple Web App

Create a Web App

In the XDK, create a new project, and under HTML5 Companion Hybrid or Web App select Templates and Blank. Select Standard HTML5, and click Continue.

Give your new app a name (e.g. “XDK_MyApp”), and click Create. You will notice that the files and folders in the web app template are different from the ones in IoT project templates.

Our code will live in www/index.html and www/js/app.js

Libraries

Similar to loading Node.js modules for code that runs on the Edison, we will rely on JavaScript libraries in our web app. In the first part, we will include jQuery, which makes it easier to select HTML elements (from the index.html page) in our JavaScript (app.js) code and handle events like text entry or button clicks.

Navigate to http://jquery.com/download/ and download the latest, uncompressed version (e.g. “Download the uncompressed, development jQuery 2.1.4”). That will download a .js JavaScript file, which we need to copy into our project.

Navigate to your Downloads directory, and copy the newly downloaded .js file. Then, navigate to your project directory. In the www directory (e.g. <Your XDK Web App Directory>/www), create a directory named lib.

In that directory, create another directory named jquery.

Finally, paste the jQuery JavaScript (.js) file in the jquery directory.

The XDK should now show the jQuery file in the file browser pane (if not, switch to another project and then back to the web app project to reload the file browser).

HTML

Open the index.html file (found in the www directory in the project), and copy in the code below. Don’t forget to save the file (File → Save) when you are done!

language:html<!DOCTYPE html><!--
SparkFun Inventor's Kit for Edison
Experiment 6 - Part 1: Simple Web App
This sketch was written by SparkFun Electronics
November 10, 2015
https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments

Create a some dynamic text that appears when a button is pushed.

Released under the MIT License(http://opensource.org/licenses/MIT)
--><html><head><title>Simple Web App</title><meta http-equiv="Content-type" content="text/html; charset=utf-8"><meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=no"><style>
        @-ms-viewport { width: 100vw ; min-zoom: 100% ; zoom: 100% ; }  @viewport { width: 100vw ; min-zoom: 100% zoom: 100% ; }
        @-ms-viewport { user-zoom: fixed ; min-zoom: 100% ; }           @viewport { user-zoom: fixed ; min-zoom: 100% ; }</style></head><body><!-- Static text --><div><h2>The Button</h2><p><button id="toggle_button">Push Me!</button></p></div><!-- Text that appears on button push --><div id="toggle_text" style="display: none;"><p>Boo!</p></div><!-- Load the various JavaScript files --><script type="text/javascript" src="lib/jquery/jquery-2.1.4.js"></script><script type="text/javascript" src="js/app.js"></script></body></html>

JavaScript

Open the app.js file (found in the www/js directory), and copy in the following code. Don’t forget to save the file (File → Save) when you are done!

language:javascript
/*jslint unparam: true */
/*jshint strict: true, -W097, unused:false,  undef:true, devel:true */
/*global window, document, d3, $, io, navigator, setTimeout */

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 6 - Part 1: Simple Web App
 * This sketch was written by SparkFun Electronics
 * November 10, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Create a some dynamic text that appears when a button is pushed.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Make the toggle text div appear and disappear
function toggleText() {

    // Put in strict mode to restrict some JavaScript "features""use strict";

    // Declare our variables at the beginning of the scope
    var toggleTextEl = $('#toggle_text');

    // Toggle the visibility of the text
    toggleTextEl.fadeToggle();

    // Print the visibility to the console
    console.log("Visibility: " + toggleTextEl.css('visibility'));
}

// Short for jQuery(document).ready() method, which is called after the page
// has loaded. We can use this to assign callbacks to elements on the page.
$(function() {
    "use strict";

    // Assign a callback to the "Push Me" button
    $('#toggle_button').on('click', function(){
        toggleText();
    });
});

What You Should See

To test the program in the XDK’s phone emulator, click on Run My App in the right-side pane. Click on the “Play” symbol (triangle) next to Run in Emulator. The XDK Emulator should boot up and give you a phone-like interface running our web app. Click the “Push Me!” button for a (very insignificant) surprise.

In the top-left pane, you can also select the model of phone you wish to test. It may not be as good as the real thing, but it’s a start!

To test the program on a real phone, we will first need to download and install the Intel App Preview from the appropriate app store. App Preview can be found here for iOS, here for Android, or here for Windows.

In the XDK, go to the TEST tab, and click on the Push Files button. This will upload the project to Intel’s servers, where you will be able to download it on your phone.

On your phone, open the Intel® App Preview app (don’t think about the redundancy too hard). Press the Login button, and enter your Intel® Developer Zone username and password. Press the Server Apps tab on the bottom of the screen to view your uploaded projects (at this point, you should only see one).

Press on your project’s name, and you will be presented with a launch screen.

Press the rather large Play button to start your app.

And that’s it! Your web app is now running on your phone. To exit, tap the screen with three fingers simultaneously.

To build and deploy your app (i.e. run without the App Preview app), navigate to the BUILD tab in the XDK. There, you will see several options on building your app. To build your program as a Web App, click the WebApp button. To learn more about building XDK apps, read this article.

Code to Note

The <html>, <head>, and <body> tags should look very similar to how we created a simple web page in the previous experiment. The difference here is that the HTML is located in a separate file (index.html) than the JavaScript (app.js).

We load the JavaScript file with

language:html<script type="text/javascript" src="js/app.js"></script>

at the end of the body. This allows us to make functions calls to JavaScript as well as have HTML elements be referenced by the JavaScript. For example, we create a button with <button id="toggle_button"> that has the id “toggle_button”. In app.js, we assign an event handler (the function .on()) to the toggle_button element.

To make the HTML-JavaScript communication easier, we rely on the jQuery library. jQuery adds event handling, page manipulation, and animations to JavaScript in an easy-to-use fashion. The syntax might take some time to get used to, but for starters, know that $ is short for the class jQuery. That means $('#toggle_button') is really jQuery('#toggle_button') (i.e. it’s just a shortcut).

The piece of code

language:javascript
$('#toggle_button').on('click', function(){
    toggleText();
});

assigned the function toggleText() to the on click action for the toggle_button HTML element, which we created in index.html.

Finally, "use strict"; is an odd piece of code that sits in the beginning of functions. This line puts JavaScript into “strict mode” running in browsers, which restricts certain functions and is generally considered more “safe.”

Part 2: RGB Color Picker

The Web App

In the previous part, we created a simple web app to demonstrate how web apps work. You might have noticed that we did not use the Edison at all. In this part, we will need to create 2 programs: one that runs on the Edison as a server and one that runs as a client on a smartphone.

Create a new Standard HTML5 app using the Blank Template (just like we did in part 1). Then, we need to add some libraries.

First, download the uncompressed, latest version of jQuery from http://jquery.com/download/. Copy that file (e.g. jquery-2.x.x.js) to <Your XDK Web App Directory>/www/lib/jquery (just like we did in part 1). Create any directories that do not exist.

Second, download the socket.io client library from https://github.com/socketio/socket.io-client (click Download ZIP). Unzip the .zip file, and copy socket.io.js to <Your XDK Web App Directory>/www/lib/socketio.

Third, download the JavaScript tinyColorPicker from https://github.com/PitPik/tinyColorPicker. Unzip the .zip file, and copy jqColorPicker.min.js to <Your XDK Web App Directory>/www/lib/jqColorPicker. Note that we are using the minified) version of the tinyColorPicker library.

You might have to refresh the project in the XDK (i.e. right-click in the file explorer pane and select Refresh File Tree).

In www/index.html, paste in the following code:

language:html<!DOCTYPE html><!--
SparkFun Inventor's Kit for Edison
Experiment 6 - Part 2: Phone RGB LED
This sketch was written by SparkFun Electronics
November 9, 2015
https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments

Runs as a web app on a smartphone. Creates a socket.io connection to the
Edison and sends RGB values.

Released under the MIT License(http://opensource.org/licenses/MIT)
--><html><head><title>Set RGB of Edison</title><meta http-equiv="Content-type" content="text/html; charset=utf-8"><meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=no"><style>
        @-ms-viewport { width: 100vw ; min-zoom: 100% ; zoom: 100% ; }  @viewport { width: 100vw ; min-zoom: 100% zoom: 100% ; }
        @-ms-viewport { user-zoom: fixed ; min-zoom: 100% ; }           @viewport { user-zoom: fixed ; min-zoom: 100% ; }</style></head><body><!-- IP address and port inputs --><div id="connection"><h2>Edison Address</h2><p>Please provide the IP address &amp; port to the Edison</p><p><input id="ip_address" type="text" placeholder="IP Address"><input id="port" type="text" placeholder="Port"></p><p><button id="send_ip_port">Connect</button></p></div><!-- RGB Color Picker --><div id="rgb" style="display: none;"><h2>Color Selector</h2><input id="colorSelector" class="color"></div><!-- Load the various JavaScript files --><script type="text/javascript" src="lib/jquery/jquery-2.1.4.js"></script><script type="text/javascript" src="lib/jqColorPicker/jqColorPicker.min.js"></script><script type="text/javascript" src="lib/socketio/socket.io.js"></script><script type="text/javascript" src="js/app.js"></script></body></html>

Save the file, and in www/js/app.js, paste in the following code:

language:javascript
/*jslint unparam: true */
/*jshint strict: true, -W097, unused:false,  undef:true, devel:true */
/*global window, document, d3, $, io, navigator, setTimeout */

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 6 - Part 2: Phone RGB LED
 * This sketch was written by SparkFun Electronics
 * November 9, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Runs as a web app on a smartphone. Creates a socket.io connection to the
 * Edison and sends RGB values.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Connect to Edison server with socket.io
function connectIP() {

    // Put in strict mode to restrict some JavaScript "features""use strict" ;

    // Declare our variables at the beginning of the scope
    var scoket;
    var ipEl = $('#ip_address');
    var portEl = $('#port');
    var connectionEl = $('#connection');
    var rgbEl = $('#rgb');
    var colorSelectorEl = $('#colorSelector');

    // Attach a socket.io object tot he main window object. We do this to avoid
    // a global socket variable, as we will need it in the colorPicker callback.
    window.socket = null;

    // Connect to Edison
    console.log("Connecting to: " + ipEl.val() + ":" + portEl.val());
    window.socket = io.connect("http://" + ipEl.val() + ":" + portEl.val());

    // If we don't have a connection, disconnect and hide the RGB selector
    window.socket.on('connect_error', function() {
        window.socket.disconnect();
        alert("Could not connect");
        rgbEl.fadeOut();
    });

    // If we do have a connection, make the RGB selector appear
    window.socket.on('connect', function() {
        rgbEl.fadeIn();
        colorSelectorEl.trigger('click');
    });
}

// Short for jQuery(document).ready() method, which is called after the page
// has loaded. We can use this to assign callbacks to elements on the page.
$(function() {
    "use strict" ;

    // Assign a callback to the "Connect" port
    $('#send_ip_port').on('click', function(){
        connectIP();
    });

    // Assign initial properties to the color picker element
    $('.color').colorPicker({
        opacity: false,
        preventFocus: true,
        color: 'rgb(0, 0, 0)',

        // This is called every time a new color is selected
        convertCallback: function(colors, type) {
            if (window.socket && window.socket.connected) {
                window.socket.emit('color', colors.RND.rgb);
            }
        }
    });
});

Don’t forget to save!

Edison Code

Create a new project (Blank template under Internet of Things Embedded Application). This code will run on the Edison. Copy in the following code into main.js:

language:javascript
/*jslint node:true, vars:true, bitwise:true, unparam:true */
/*jshint unused:true */
// Leave the above lines for propper jshinting

/**
 * SparkFun Inventor's Kit for Edison
 * Experiment 6 - Part 2: Edison RGB LED
 * This sketch was written by SparkFun Electronics
 * November 9, 2015
 * https://github.com/sparkfun/Inventors_Kit_For_Edison_Experiments
 *
 * Waits for socket.io connections and received messages to change RGB LED.
 *
 * Released under the MIT License(http://opensource.org/licenses/MIT)
 */

// Import the MRAA and HTTP modules
var mraa = require('mraa');
var server = require('http').createServer();
var io = require('socket.io').listen(server);

// Port
var port = 4242;

// Set up PWM pins
var rPin = new mraa.Pwm(20);
var gPin = new mraa.Pwm(14);
var bPin = new mraa.Pwm(0);

// Enable PWM
rPin.enable(true);
gPin.enable(true);
bPin.enable(true);

// Set 1000 Hz period
rPin.period(0.001);
gPin.period(0.001);
bPin.period(0.001);

// Turn off LEDs initially
pwm(rPin, 0.0);
pwm(gPin, 0.0);
pwm(bPin, 0.0);

// Wait for a client to connect
io.on('connection', function(socket) {
    console.log("A client is connected!");

    // Look for the "color" message from the client and set the LED
    socket.on('color', function(rgb) {
        console.log("RGB(" + rgb.r + ", " + rgb.g + ", " + rgb.b + ")");
        pwm(rPin, rgb.r / 255);
        pwm(gPin, rgb.g / 255);
        pwm(bPin, rgb.b / 255);
    });
});

// PWM needs a "fix" that turns off the LED on a value of 0.0
function pwm(pin, val) {
    if (val === 0.0) {
        pin.write(0.0);
        pin.enable(false);
    } else {
        pin.enable(true);
        pin.write(val);
    }
}

// Run the server on a particular port
server.listen(port, function() {
    console.log("Server listening on port " + port);
});

What You Should See

Upload the Edison code to the Edison and run it. You should see a note in the console, “Server listening on port 4242”. Take note of the Edison’s IP address.

Open the web app project back up and run it in an emulator or your smartphone. You will be presented with a couple of fields for IP address and port number. Enter the IP address of the Edison and 4242 for the port.

Click Connect and the web app should make a connection with the Edison (assuming your phone/emulator and Edison are on the same network). If it was successful, you should see an RGB color selector appear.

Try selecting different colors, and see how the LED connected to the Edison responds!

Code to Note

In the web app, we are using jQuery again to control elements, like in part 1. We rely on fadeIn() and fadeOut() to make the RGB selector appear and disappear. Additionally, we use the alert() function to make a pop-up appear letting the user that the connection failed.

You might have noticed that we used window.socket in connectIP(). The window object is pre-defined as the open window in a browser. It contains all the displayed HTML. As it turns out, we need to access a socket object in the function connectIP() as well as the callback for the RGB color picker. However, socket was never declared as a global variable, and as a result, the color picker callback (convertCallback) does not know about the existence of socket, as it was declared in connectIP(). This is a problem of “scope.”

To solve this issue (and without creating unnecessary global variables), we create a socket object inside the window object (we say that window owns a socket object) with window.socket. Because window is global, we can then access window.socket anywhere in our code! To make sure that the window.socket object exists and has a connection before we use it to send data, we rely on the conditional

language:javascript
if (window.socket && window.socket.connected) {
    ...
}

in convertCallback. That way, we don’t throw any undefined errors when we try to use the socket.

In the Edison code, we use the MRAA Pwm object to control the brightness of the RGB LED, which is created with an MRAA pin number. To find the MRAA pin number, first find the pin number as it is listed on the GPIO Block, and find the associated MRAA pin number in Appendix E: MRAA Pin Table. For example, GP12 is MRAA pin 20.

Troubleshooting

• The web app does not start– Try it in the XDK emulator first. In the emulator, click on the “debug” button (bug icon with an ‘X’ in the upper-left corner), and click on the Console tab to view error messages.
• The web app won’t run on my phone– Your phone might not be supported. If it is an older phone, read about legacy phone support for the XDK.
• The web app won’t connect to the Edison– Make sure the Edison and phone are on the same network (e.g. the phone must be connected to WiFi and on the same subnet as the Edison).

Going Further

Challenges

1. Make a modified email notifier that changes the color of the LED depending on different parameters of your inbox. For example, you could have the LED be green for 1-10 new emails and red for 11+ emails.
2. Add an image to the web app that turns the LED off and back on when you press it (hint).

Digging Deeper

• What is JavaScript “strict mode”
• More about scope
• tinyColorPicker example page

Experiment 7: Speaker

Introduction

Many microcontrollers have the ability to create analog voltages using a digital-to-analog converter (DAC). DACs are incredibly useful for connecting to a speaker (usually through an amplifier) to make sounds.

Many other microcontrollers and computer modules (like our Edison) do not have an onboard DAC. While separate DAC chips can be added, we are often left with using PWM to approximate sounds with a speaker.

In this experiment, we will read musical note information from a file and use that to create PWM signals. We then amplify the PWM signals and feed it to a small speaker that converts those signals to sound.

Parts Needed

In addition to the Edison and Block Stack, you will need the following parts:

• 1x Breadboard
• 1x Piezo Speaker
• 1x NPN Transistor
• 1x 1kΩ Resistor
• 1x 100Ω Resistor
• 6x Jumper Wires

Added to your cart!

Resistor Kit - 1/4W (500 total)

In stock COM-10969

Resistors are a good thing, in fact, they're actually crucial in a lot of circuit designs. The only problem seems to be that …

$7.95

65

FavoritedFavorite35

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - Base

In stock DEV-13045

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

32.9500$24.95

9

FavoritedFavorite10

Wish List

Added to your cart!

Breadboard - Self-Adhesive (White)

In stock PRT-12002

This is your tried and true white solderless breadboard. It has 2 power buses, 10 columns, and 30 rows - a total of 400 tie i…

$4.95

17

FavoritedFavorite13

Wish List

Added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers. **Fea…

$1.5

18

FavoritedFavorite25

Wish List

Added to your cart!

Jumper Wires Standard 7" M/M Pack of 30

In stock PRT-11026

If you need to knock up a quick prototype there's nothing like having a pile of jumper wires to speed things up, and let's fa…

$4.95

18

FavoritedFavorite8

Wish List

Added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.5

5

FavoritedFavorite19

Wish List

Added to your cart!

SparkFun Block for Intel® Edison - GPIO

In stock DEV-13038

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

14.9500$11.95

3

FavoritedFavorite2

Wish List

Added to your cart!

Intel® Edison

In stock DEV-13024

The Intel® Edison is an ultra small computing platform that will change the way you look at embedded electronics. Each Ediso…

$49.95

15

FavoritedFavorite19

Wish List

Added to your cart!

Piezo Speaker - PC Mount 12mm 2.048kHz

In stock COM-07950

This is a small 12mm round speaker that operates around the audible 2kHz range. You can use these speakers to create simple m…

$1.95

5

FavoritedFavorite5

Wish List

Added to your cart!

Transistor - NPN (2N3904)

In stock COM-00521

These are very common, high quality BJT NPN transistors made by ST Micro. **Datasheet: **[2N3904](http://www.sparkfun.com/da…

$0.5

FavoritedFavorite4

Wish List