Addressable RGB LED Music and Sound Visualizer a learn.sparkfun.com tutorial

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

Introduction

Let’s face it: nowadays, most musical performances are complimented by some fancy light shows. Go to any concert, festival, club – they all have a corresponding visual performance or effects. Why not add your own home to that list? Here’s a simple yet effective project to make your very own son et lumière!

All palettes work with every visualization, but, for timeliness, not every combination is shown.

Required Materials

To follow along with this tutorial, you’ll need the following:

Any microcontroller with 3.3V and 5V pins will suffice, any analog potentiometer should work, and any resistor between 300–500 Ω can be used. The resistor and capacitor are not required, but they will help prevent possible damage to the LEDs.

If you’re compiling from the Arduino IDE or similar, you’ll want to snag the the NeoPixel Library since the code used is heavily based on it. If you’re using codebender, it will link the library for you.

Depending on your intent, the trimpot and buttons may not be necessary. The trimpot is only used to adjust the brightness threshold, so, if you want maximum brightness, you don’t have to worry about incorporating it. The three buttons cycle visualizations, color schemes, and shuffle mode respectively, so, if you want to do without those features (and just use shuffle mode all the time), that’s also a possibility.

It is also suggested that you use an Arduino and Breadboard Holder to simplify wiring and to mount the LED strip:

A small notch was cut in the BReadboard Holder to hold a piece of MDF, on which the LEDs are attached.

Recommended Reading

Before embarking upon this tutorial, you may find the following links useful:

• Arduino Sketch Tutorial
• Arduino Reference
• How to use a Breadboard
• RGB Color Model
• Sound Detector Hookup Guide

Since we’re using the NeoPixel library, it may also be a good idea to get familiar with the NeoPixel Documentation.

Assembly

This project requires virtually no soldering! The few exceptions will probably be soldering some pins to the sound detector, and, if you’ve cut a roll of addressable LEDs in the middle, you’ll have to solder some wires to the starting LED’s pins. If you’ve never soldered before, I highly suggest taking a look at this guide.

Below is also a general chart for how the pin(s) on each component should be routed and an accompanying diagram. Before you begin, here are some things to keep in mind:

• Be conscious of the orientation you think would allow the sound detector to take optimal readings for your intentions. Bending the pins to hold the sound detector perpendicular to the breadboard is a recommended option.
• Electrolytic capacitors are polarized, so how they are oriented is important. Make sure to place the side with a white stripe and a negative symbol into a negative current (ground) and the other into positive current.
• Resistors and pushbuttons are not polarized.
• Trimpots are not polarized either, however their middle pin is the analog output, so don’t power that directly.

The pins used in the diagram and the code are in parentheses. If you use a different pin, don’t forget to change it in the code as well:

Sound Detector Notes: The microphone used is not a sophisticated, logarithmic sound receiver like your ear; it is only measuring compressional waves in the air. Consequently, the microphone is more likely to detect and/or prioritize lower-frequency sounds since they require more energy to propagat, and therefore oscillate the air more intensely. Also, a resistor can be placed in the “GAIN” slots to modify the gain. Standard gain should be sufficient for our purposes, but, for more info, visit this tutorial.

The entire circuit should look something like the diagram below.

Fritzing diagram for the circuit as described above. Click the image for a closer look.

Programming

Below is a small sample program to test if everything is connected properly. It only contains one visualizer and one color palette to keep things concise. It doesn’t need buttons since there’s nothing to toggle, but you can still use it to test your potentiometer.

The complete program featured in the video can be found at this GitHub repository.

Things to remember before you compile:

• If you didn’t use a potentiometer, don’t forget to remove all references to the variable knob in the code (ctrl+F will come in handy for that). Otherwise, the program will think you still have a potentiometer that is set to a very low value (i.e. everything will be very dim).
• If you didn’t use buttons, change the initialization bool shuffle = false; to bool shuffle = true;. The code should compile and run properly, but for good practice you should remove all blocks the code says to delete since they reference the BUTTON constants.

Final Touches

With the electronics and the code working, you can now add your visualizer to a variety of enclosures or art pieces. For the final touches on this project, an elk was laser etched on a piece of acrylic. The LED strip was then wrapped around the outer perimeter of the piece.

Add some music, and you have yourself a beautiful piece of interactive art.

Resources and Going Further

To see all the code used int his project, visit the GitHub repository.

• If you want to get really crazy, hackaday demonstrates how to power 1000 NeoPixels with the Arduino’s limited RAM.
• Why not bring your visualizer along with you to a music venue? Mark Easley over at hackster shows us how to integrate some LEDs into your clothes.
• Of course, if you are going to wear it, you may want to consider some portable sources of power. Check out the Sunny Buddy Hookup Guide to learn how to efficiently charge a battery with solar power.

Need more inspiration? Check out these other SparkFun tutorials:

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

Beefcake Relay Control Hookup Guide a learn.sparkfun.com tutorial

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

Introduction

The Beefcake Relay Control Kit is a way to switch loads that could not normally be driven with a microcontroller, such as AC lights, motors, batteries, solenoids, pumps, and more!

The Beefcake Relay Control Kit

This hookup guide talks about safety, takes you through the assembly process of the Beefcake Relay Control kit and shows how to test it using the most basic Arduino sketch.

Suggested Reading

• Through-Hole Soldering– If you’re unfamiliar with soldering, start here.
• Redboard Hookup Guide– New to microcontrollers? Pick up a redboard and start here.
• The Relay Tutorial– Controlling Big, Mean, Devices.
• Beefcake Relay Control Kit GitHub Repo– contains source material.

Saftey and Insulation

This product will potentially be used for mains wiring, so please read this section discussing how much space is required to prevent arcing.

There are a lot of standards out there, like the IEC standards, the UL standards, and the IEEE standards. These cover anything from test techniques, communication interfaces and of course safety. Each country requires a different set of standards for commercially released products, which is an experienced full time position just to make sense of.

The Beefcake Relay Control is a prototyping or component type thing and abides by no standards, but it was designed with safety in mind. Because it’s not a full product though, there is no guarantee that it will be used safely by you, the customer, so please be careful.

Making standards is good for business and compatibility but is also a business itself, so the standards can’t be found for free. However, creative Google searches can reveal the pertinent tables which have obviously come from the standards. Information from the standards have been boiled down to creepage and clearance calculatators for PCBs such as www.creepage.com. These can be used to come up with safe distances.

Play around with the creepage.com calculator, and see how the distances change. This section is intended to inform and not to scare. The terminology is a little odd so here’s a few terms that my demystify the calculator settings.

Functional insulation

Functional insulation is intended to meet the lowest level of isolation for a given voltage. 250VAC is about 1mm.

Basic insulation

This provides a level above nominal to allow surges and other common line disturbances to not cause a breakdown. For 250VAC, 2mm is required.

Double insulation

To make things safe for people to come in contact with, most standards require a second layer so that one can be damaged, and the isolation characteristic is maintained. Of course, this would be twice basic, or 4mm for 250VAC.

Reinforced insulation

Reinforced insulation has the same insulative properties as double, but it is rated to be robust enough to not get cracks and pinholes such that it can be used in place of proper grounding.

Creepage and Clearance

Creepage is defined as the shortest distance between conductive surfaces along the surface of the PCB. It’s easier to conduct along the surface of an object than in free space, so this measure is the distance electrons would have to crawl to get from one conductive thing to another, along the surfaces in between. This will be farther than the clearance requirements.

Clearance is defined as the shortest distance between conductive things (like pads). Or, if there were an arc between the two things, what would the most likely path be?

What this means for the Beefcake Relay Control

Take a look at the PCB with strong lighting through it. The raw fiberglass of the board lets the light through but the copper doesn’t. It’s easy to see the traces and spacing this way.

There is a lot of distance between the high voltage and low voltage sides. There’s enough that you should be able to safely touch anything on the low voltage side, but please don’t. It’s good practice to avoid working with any circuit that is connected to mains.

Peeking inside the relay we can see a good distance between the low voltage windings and the high voltage contacts. This relay is rated to 2500VAC isolation between the coil and contacts, but manufacturing has statistical failure rates, and the user should always be wary of the dangers.

Assembly

The Beefcake Relay Control kit is relatively straight forward to assemble. This section outlines what tools will be needed and shows the assembly process.

Materials

The kit contains the following parts:

• An electromechanical Relay
• 2x Terminal blocks, light gauge for signal and heavy for output
• Coil-active LED
• Bipolar junction transistor (BJT)
• 2x Current limiting resistors
• Flyback arrestor diode
• Zener diode for discharge

Tools

The following tools are recommended.

• A soldering iron with 50 watts of power capability.
• Some solder, either leaded or lead-free.
• A magnifying glass or loupe.
• A vise to hold the PCB as you work.

Building The Beefcake Relay Control

The Beefcake uses standard through-hole techniques. Components will be passed through the holes, soldered, and the leads trimmed. It’s best to start with the shortest components working up to the taller ones. This is so they stay pressed in place while the board is upside down against a work surface.

Start with the resistors. Bend the leads so they form 90 degree angles as close to the resistor body as possible.

Feed them into the place marked 1k. They will sit over the silkscreen box.

Next, bend the diode leads. The diode bodies are shorter, so it’s not necessary to get the bends right close. They should be the same widths as the resistors after bending.

Insert the diodes. The fat diode is the 9.1V zener, and should be marked 4739. Place it over the silkscreen box labled “Zener” with the black band towards the white silkscreen stripe. The smaller diode should be labled 4148 and is a standard high-speed diode. Place it over the box labled N4148 with the black stripe towards the silk stripe.

Now, flip the board, and solder those components forming nice shiny cones around the leads. A weight, like the solder stand, can be used to hold the board, or it can be placed in a vice.

Clip the component leads right at the top of the solder cones.

Next, prepare the BJT. Leave the outer two legs straight. Bend the inner leg in an ’S' curve so that it is spaced evenly from the other two legs in an equilateral triangle.

Fit the BJT and LED into the board, minding that the flat side of the LED matches the flat part of the silkscreen circle.

Solder them in place, and trim the leads.

Attach the screw terminals. Orient them so the apertures face outward. These will stay in pretty well, so flip it and solder in place.

The last component is the relay. The relay has thick leads for current capacity, so they may need a little work getting inserted. Once they are all positioned, it should sit flush with the PCB.

Inserting the relay

The extra copper involved in carrying the current means it can take extra heat to get the solder to flow, but it is very important. A cold solder joint will cause extra resistance. With the recommended Hakko iron set to 700 degrees, there should be no problem, but the iron will have to be held on longer than normal. Feed extra solder if the joint is looking dirty, the flux will come out, and you can scoop away the extra solder with the iron right after.

Notice that the iron touches both the post and the plated through hole heating them up together.

Congratulations! You now have a completed Beefcake Relay Control circuit. Here’s what the final product will look like.

Example: Arduino Control

Now, it’s time to make the relay sing the song of its people. Connect the 5V terminal to 5V power capable of supplying 150mA, the ground to ground, and a signal wire from a digital output to the control pin (CTRL).

A basic example is the blink.ino sketch. Connect the signal pin to digital out 13, which is the same as the LED. Connect Ground to the GND terminal and 5 volts to the 5V terminal as shown below.

Now, as the LED on the microcontroller board blinks, the relay will energize, and the Beefcake’s LED will illuminate. You should hear a pleasant clicking sound every second.

Ahh, so satisfying. But, really this should be used to switch a load. Here I’ve attached 12 gauge solid house wiring into the terminals, which was a pretty tight fit. The terminals are only specified to 14 gauge wire.

If you would like a more permanent installation, go ahead and solder to the large lugs on the edge of the board. This will take even more heat with the large solid copper wires, so be patient.

Here the solder is kinda sticking but really, it’s just blobing up. More heat is needed.

A technique for getting a bit of extra heat in there is to warm up a second iron, blob up a bunch of solder first, the heat with both irons.

Conclusion and Resources

You should now have a relay capable of switching loads from a microcontroller. But what to switch? Motors? Floor lamps? Other relays? It’s up to you!

Here’s a few tutorials to inspire you. They use the Beefcake to switch some fun stuff, including fire.

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

Photon Remote Water Level Sensor a learn.sparkfun.com tutorial

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

Introduction

With the advent of cheap Microcontrollers (MCUs), and especially WiFi-MCUs of late, custom DIY automation of many monotonous tasks and telemetry (remote data collection) is now easily possible.

In this tutorial, we are going to automate a pump for a well based on a remote measurements of a water tank and send weather warnings based on atmospheric pressure readings, as well as collect a bunch of other data. This same type of system could easily be adapted for automated farm/garden watering or other things that need to be turned on and off when some condition is met (like lights in a warehouse/greenhouse at certain times), measured via remote telemetry.

The Problem

My friend, Andre, owns a CSA farm in Boulder, CO called Jacob Springs Farm. They make some tasty meat, milk, and eggs, so, if you’re local, check them out.

The farm sign on 75th and Arapahoe in Boulder, CO and the water tank behind it. You can see the water level is nearly empty, as is typical without any automation/telemetry system in place.

They aren’t legally allowed to run a city water line to the property, so they use a well and their own storage tanks. The pump for the well is manually turned on or off using a twist timer (which is actually only rated for 50% of the pump’s current load), and typically they have no idea how much water is in the tanks (unless they’re empty). I’ve heard hilariously tragic stories of people being in the shower and having the water run out during winter. They have to run out to the barn, all soaped up and in their towel, turn on the water, and wait for the water heater to fill up and heat so they can finish their shower. Other times the water runs out while preparing dinner or doing dishes, and the low water pressure makes for slow going.

The barn with the pump control, and the existing pump control timer.

The water tanks are on one corner of the property (the highest elevation), far from any power outlets, and the pump for the well is at the other end. In order to manage the water system for the farm, I’ve developed this system that measures the water height with an ultrasonic sensor and controls the pump from that data. While I was at it, I added some extra environmental sensors.

Required Materials

This project is two-fold: remote telemetry (measurements) coupled with automated weather warnings, and remote control/automation of a hefty (2 hp) pump. To follow along with this tutorial, you’ll need the following products and tools:

Pump Remote Control Box

For the automation of the pump, you will need:

• 1 contactor to turn on/off the pump, rated for the pump load (3hp, 2200W in this case, but choose the contactor with an appropriate horsepower rating for your application), or a relay if the load is light enough
• 10A relay to control the contactor
• Particle Photon WiFi MCU to control the relay
• Photon ProtoShield
• female headers
• male-male jumper wires
• 5 V power supply for the photon
• box to hold the photon and relay
• PIR sensor to check if someone is near the control box/contactor
• 10 k resistor for the PIR
• a few mounting screws (5), I used #8 1-¼" drywall screws, a DIN rail is more professional
• appropriate wiring for your loads (check here for max amperage for different wire gauges) – I used about 2 ft of 18 AWG for control of the contactor, and about 5ft of 10 AWG for wiring leading to the pump

Some of the supplies used for the pump control box. Not shown here: 10 k resistor, jumper wires, headers, screws, relay, contactor.

Remote Telemetry Box (water height, etc)

The other half of the project is remote data collection. For this, you will need:

• Particle Photon WiFi MCU
• SMA to u.FL cable (may not be necessary if you can get wifi reception without the antenna)
• Duck Antenna (may not be necessary if you can get wifi reception without the antenna), you can also use a cantenna or yagi antenna for longer-range reception
• Photon Battery Shield
• LiPo battery (I used 2000 mAh, but you can go higher or lower capacity depending on budget and how often you want to take measurements)
• solar cell (I used 3.5 W but that’s overkill, just to be safe – if trying to save money, you could use the 2 W)
• CdS photocell
• 1 k resistor for use with the photocell
• BME280 pressure/humidity/temperature sensor
• MaxSonar EZ3 ultrasonic range finder (measures water height), although I recommend the waterproof HRXL for robustness
• box to hold it all
• hookup wire (22 AWG)
• a few mounting screws (2), I used #8 1-¼" drywall screws
• some twine or wire to hold the solar panel down

Most all of the supplies used for the telemetry box.

Here’s a wish list containing all the SparkFun parts used in this project:

Tools

• Drill
• drill bits: ¾", 5/8", ½", 1/8"
• soldering iron, solder, optional: third hand, copper sponge (for cleaning soldering iron tip)
• wire strippers
• hot glue gun and hot glue
• heat gun for shrink wrap (can use hair dryer in a pinch)
• screw driver
• two pairs needle-nosed pliers
• exacto knife
• tape measure
• sledge hammer for driving a grounding rod into the ground

Here’s most of the tools I used (not pictured: copper sponge).

Here’s some other tools I used, and the tools used to cut the headers to size (right).

Other Supplies

• Gore-Tex® repair patch kit (I sourced locally at REI, but also available here)
• acetone or other solvent to remove adhesive from Gore-Tex® patch (may not need this for the Simms patches)
• 2 PG-7 cable glands
• silicone
• small glass piece, I got mine from Hobby Lobby
• AC cord with bare leads for testing contactor
• aluminum foil (for shielding the ultrasonic sensor from static from the plastic water tank)
• grounding rod for grounding the aluminum foil housing (I used ½" 10' EMT conduit)

Other supplies that were used.

Suggested Reading

Before embarking upon this tutorial, you may find the following links useful:

Prepping the Photons

The first thing is to get your Photons prepped and ready to accept firmware over WiFi.

If you have never used the Particle Photon before, you will need to visit the Particle website to learn how to setup a Photon for first time use. You will need to connect it to your local network, pair the device with your free Particle cloud account, and possibly update firmware before you will be ready to upload your first program. All of that information can be found at the following link:

Getting Started with the Photon

Once your Photon setup, you will also need to install the Particle Command Line Interface (CLI) on your computer. This will allow us to watch the serial output from the Photon in our terminal/command console.

Install the Particle CLI

Build the Pump Controller

The contactor/relay idea is used here to control a pump for a well, but could also be used to control a solenoid for a sprinkler/watering system (you’d probably only need a relay in that case), or to switch on lights, motors, or pumps in a structure (greenhouse, warehouse, etc), heavy-duty heaters, or other remote control needs you might have.

Triacs, Contactors, and Relays – Oh My

To begin, let’s discuss the various ways to control AC power.

To switch lighter, resistive AC loads (like a small electric heater), a relay can be used. However, once you need to switch a pump on or off, or another inductive load, a different kind of switch is usually needed. Why? It’s because when inductive loads start up, they exert a huge load–but only temporarily. See this stackexchange question. Using an undersized relay with an inductive load like a pump can be a dangerous proposition; the heat from the start up of an inductive load could eventually fuse the relay contacts together, leaving your pump constantly on and you not even knowing it.

Inrush currents from various electrical things. Source: here.

Here is a video of the contactor I installed in operation and the kWh meter. You can clearly see that when the pump turns on, there’s a huge inrush of current. After that, the current subsides.

A triac is another way to control AC with silent operation, though I won’t go into any details as this project didn’t use any.

For a beefy motor, like a well pump or other industrial sized applications (like turning on the lights in an entire warehouse, etc), you want to use a contactor. These are rated by UL for certain motor loads, like 1 hp (~750 W), 2 hp (~1500 W), etc. In our case, we have a motor that I measured at 1500 W – about 2 hp. Oversizing electrical components is usually the safest bet, so I picked a 3 hp contactor from US Breaker Inc., which had some of the best prices I could find. The datasheet tells us it can handle 3 hp at 120 V. The coil, which controls the contactor, takes about 2 A at startup and about 0.2 A thereafter, so a 10 A relay is more than enough to handle this, plus we can then easily control this from a MCU. The coil runs off of straight-up 120 V, so we don’t need another power supply to control the contactor, just a relay that can switch up to 2 A at 120 V.

The beefy 3 hp contactor I used. This thing is hefty, and should be reliable long-term.

The breaker is rated for 800,000 cycles, which should last about 91 years if the breaker is switched every hour (and it will probably be switched much less often). US Breaker has other contactors that can handle up to 7.5 hp inductive loads (5600 W) at 120 V in case you need more beef.

Electrical Setup

If you’re new to soldering check out this tutorial and practice on some scrap parts before trying the real thing. Solder the relay together, if you’re using the SparkFun Kit. You can find assembly instructions for the relay kit in this hookup guide.

Cut 2 sets of female headers to the correct size (20 units) by first scoring with an exacto knife (I do it on all sides of the headers), then use two pairs of needle-nosed pliers to make a clean break. Score each side a few times to get a deep cut. It will probably take you a few tries to get the hang of it, so don’t get discouraged when the first few don’t work out.

Break headers to the correct size by first scoring with an exacto knife around the perimeter, then using two needle-nosed pliers to make a clean break.

Assemble 3 male-to-male jumpers into a connector for the PIR and relay. There should be a 10kΩ resistor between the 5V (Vin) and dataline for the PIR. The 5V line should be split, one to go to the relay and one to the PIR. Before soldering things together, put some heatshrink on the wires so it is easy to cover up bare wires. After soldering, heat the heatshrink with the heat gun until they tightly grip the wires (don’t heat for more than 5-8 seconds).

I used my third hand tool to help me hold everything in place while I soldered.

Solder the headers to the ProtoShield. Solder the PIR data header to the D7 hole, the Vcc header to the Vin hole, and the GND header to one of the GND holes. Solder another jumper to the other GND hole and one more jumper to the D0 hole for the relay.

Here’s a top view of the completed protoboard. Make sure to plug the Photon in the right direction (use the white guidelines on the board).

Next, test the relay and contactor to make sure everyone’s riding on the gravy train. Connect the GND, Vin, and D0 jumpers to the GND, 5V, and CTRL of the relay board, respectively. Upload the code below (via build.particle.io) to your Photon to test the relay (listen for the clicking every few seconds to make sure it works and watch the LED. You can also test the resistance between the ‘load’ and ‘normally open’ screw terminals on the relay to make sure it goes between 0 and infinity if you wish.

language:c
void setup() {
    pinMode(0, OUTPUT);
}

void loop() {
    digitalWrite(0, HIGH);
    delay(2000);
    digitalWrite(0, LOW);
    delay(2000);
}

Next is the contactor. Hook up some wire from an AC plug to the relay terminal, then from the other relay terminal to the contactor A1 connector, and last the other end of the AC wire to the contactor A2 terminal. Run the relay test again and make sure the contactor is switching. You will definitely notice when the contactor is working, as it clicks on and off with authoritah. You can again use a multimeter to watch the resistance between some of the ’T' and ‘L’ terminals if you wish; it should drop from 1 to 0 when the relay is on.

Circuit diagram of the contactor and relay.

My action shot of the contactor and relay.

Not surprisingly, the beefy contactor is much louder than the relatively cutesy little relay.

Connect the PIR sensor to the Photon: connect the D7 jumper to the signal line (black wire), the Vin to the red wire, and the white wire to GND. There’s a tutorial here explaining more about this sensor, but it’s pretty simple – when motion is detected, the output pin from the sensor pulls low. Power up the Photon, and upload this code:

language:c
void setup() {
    pinMode(7, INPUT);
}

void loop() {
    int pirVal = digitalRead(7);
    if(pirVal == LOW){
        Serial.println("Motion Detected");
        delay(2000);
    }
}

Check to make sure the PIR sets off the alarm when you wave your hand in front of it. You can tell if it’s working because the D7 LED will light up when the alarm is triggered. Additionally, you can type ‘particle serial monitor’ in your terminal/command console (with the Photon plugged into your computer via USB) to watch the serial output from the device, which should print ‘Motion Detected’ when you wave your hand in front of it.

The full circuit diagram of the pump controller. Caution: the colors on your PIR sensor wires may differ form the one in the diagram.

Physical Construction

First, drill a hole in the front of the case for the PIR sensor. The PIR sensor used here has a diameter of about 0.85", or 21.5 mm, so I used a ¾" drill bit and widened the hole with the ½" drill bit. I hot-glued the PIR in there. Add some hot glue on the corners of the board to hold it to the red box. For a more secure job, drill holes, and use 2mm screws and nuts to secure the board to the case.

The hole for the PIR sensor should measure about 0.85".

Next, drill a ½" hole in the side of the case. Drill some 1/8" holes for mounting the ProtoShield and relay, if you want to secure the board with 6-32 screws or a similar size. For ease and quickness, I just hotglued the boards to the box.

String the 5V power supply cord through the ½" hole we drilled in the side of the enclosure, and plug the micro-USB power cord into the Photon. If you want to be more professional, use a PG-7 cable gland to string the wires through. Attach some wires to the relay, leaving enough length to connect to the AC leads in your field installation (I used 18-gauge wire, since this will only be carrying about 0.2A at steady-state). If you drilled mounting holes for the relay and protoboard earlier, secure the boards using screws. Otherwise, use a hot glue gun to attach the boards to the case. Finally, hot glue the wires through the hole for strain relief and to prevent pull-out of the wires from the relay.

Complete setup of the control box and strain relief of the pass-through wires.

Finally, screw the box together with the six screws on top.

Field Installation

Use some screws to attach the box to a wall near your pump and AC leads and some screws as mounting for the contactor, if you’re not going with a DIN rail. I used some extra screws we had laying around, they seem like #8 1-¼" drywall screws, and I drilled shallow 1/8" pilot holes before screwing them in.

The control box and contactor completely mounted.

Once the contactor screws are in, hang the contactor on them, and tighten the screws so that the contactor won’t be rattling around much. Take the contactor back off, attach your wires to the terminals L1, T1, A1, A2, and the GND terminal (you will ideally want a small bolt/nut for this GND connection, seems like 6-32 with ½" length would work). If you’re going to be in a dusty area (for example, we’re in a wood shop) use protection and cover the contactor with plastic, etc. Finally, hook up the wires correctly to the pump and power cord, as shown in the full circuit diagram below.

The full circuit diagram of the pump controller.

Run the relay test program from earlier to verify everything is working.

We’ll come back to data collection and automation of the pump control after installing the remote sensor.

Build the Remote Telemetry Box

Energy Considerations – Battery and Solar Cell Sizing

The plan is to periodically wake up the Photon to take a measurement, then put it into deep sleep if the battery level is not very full. The Photon energy use specs are here. The maximum average WiFi operating current is 100mA, and the maximum deep sleep operating current is 0.1mA. Assuming an on time of 60 seconds and an off time of 5 minutes, we use about 400mAh per day. If we want to have the Photon last for three days without any sunlight (sometimes it can blizzard here for a day or two), we need at least 1200mAh of battery capacity. The nearest battery size available from SparkFun, rounding up, is 2000mAh. However, you can play with the sleep cycle time by copying this spreadsheet and get down to a pretty small battery size. Also, by sleeping the Photon longer at night when there’s less water usage, we can extend the battery life dramatically.

A Watt = V * A, so our 3.5W solar cell providing power at 5V is pushing 0.7A. We should be able to charge our 2000mAh battery pretty quickly (about 3h) under ideal conditions. However, the cell will get dusty, days will be cloudy, etc, so it’s best to oversize when in doubt. If you want to save some bucks, the 2W solar cell should push about 0.4A under ideal conditions.

Physical Construction

Drill ½" holes for the cable gland and pressure/humidity hole on the side of the box you expect to get the least rainfall/water exposure, and a ¼" hole for the antenna on the same side. Drill another ½" hole in the lid of the box for the photocell window. I accidentally installed the antenna on the top of the box, where rain will hit it directly. If you want to mount the battery shield with 6-32 screws, drill some 1/8" holes as well on the bottom of the box. Put silicone around the photocell hole on the cover and press the glass on the outside of the hole. Put silicone around the cable gland hole and the antenna hole, and install both of them.

Drill four holes in the telemetry box: one for the antenna, one for the photocell, one for pressure/humidity equilibration, and one feedthrough for the wires. You will want to put the hole for the antenna on the same side as the cable gland and humidity equilibration hole.

Waterproof Holes

We need a hole to let humidity, pressure, and temperature equilibrate with our BME280 sensor, but we don’t want to let rain water in. The solution I came up with is to use a GoreTex repair patch pad and to use a solvent to get rid of the adhesive on the area that lets humidity through. Most solvents you’ve got laying around should be fine (acetone, mineral spirits, goof-off, ethanol–such as Everclear), but check with this chart before trying any solvents not mentioned here. Take a rag, paper towel or napkin, douse it with some acetone, and rub off the adhesive on the back of the repair patch. This will dissolve the adhesive after a bit of work. When you can touch the spot you’ve treated and don’t feel the sticky adhesive, you’re probably good. I’m not sure if the adhesive lets moisture and pressure through very well or not, as I haven’t tested, but, once the adhesive is removed, it works well.

Use a rag or napkin, etc to remove the adhesive from the center of the Gore-Tex® patch.

Put a bit of silicone around the hole just to make sure it gets sealed well, and apply the patch.

Electrical Hookup

Battery Shield

Solder the four legs of the SMD barrel jack plug to the board, as described here.

Solder the four legs of the barrel jack onto the battery shield. Source: here.

You can test it with the MAX17043 library. Details on using the battery shield are beyond the scope of this project tutorial, as that information can be found in the Battery Shield Hookup Guide.

BME 280 Pressure, Humidity, Temperature

The BME280 can read pressure, humidity, and temperature, so it makes a nice mini weather station. Changes in air pressure are an easy way to predict incoming storms (unless you’re in a more tropical climate, like the gulf coast). We can use some guidelines to classify pressure changes on the hour timescale, and we’ll post that information to a Twitter account. Basically, if pressure is dropping, the rate of the drop indicates how soon a storm is likely on the way. Dropping air pressure usually also means rising wind speeds; rising pressure usually means good weather.

Here’s a table of pressure drop over three hours that we’re going to use to classify our data, referenced from here:

Essentially, if we have a 0.6% change in pressure in three hours, the pressure is changing very rapidly and bad weather may be on the way. We’ll post to a Twitter account and set up text alerts for when pressure is dropping very rapidly. The spreadsheet for the calculations is here, in case you want copy it and mess with it.

Solder some M-M jumpers to the BME280 board, and solder the other ends to GND, 3.3V, and D0/D1 (SDA/SCL) pins on the battery shield, respectively.

The circuit diagram for hooking up the BME280 to the Particle Photon. Note the SDA/SCL pins are D0/D1 on the Photon.

Male-male jumpers have been soldered betwixt the BME280 and the Photon battery shield (I had accidentally soldered to the A4/A5 pins at this point, which are SDA/SCL on Arduino UNO).

Start a new Photon project on www.build.particle.io, include the library “SPARKFUNBME280” (click the ‘Libraries’ icon on the left, search in the box for BME280, click the SPARKFUNBME280 library, click ‘Include in App’, click the name of your app, click ‘Add to App’) and upload this code to your photon to test the sensor:

language:c
/******************************************************************************
I2C_and_SPI_Multisensor.ino
BME280 Particle Photon example

Sensor A is I2C and connected through D0/D1 (SDA/SCL)
******************************************************************************/

#include "SparkFunBME280/SparkFunBME280.h"

BME280 mySensorA;

void setup()
{
    // set up sensor
    mySensorA.settings.commInterface = I2C_MODE;
    mySensorA.settings.I2CAddress = 0x77;
    mySensorA.settings.runMode = 3; //  3, Normal mode
    mySensorA.settings.tStandby = 0; //  0, 0.5ms
    mySensorA.settings.filter = 0; //  0, filter off
    //tempOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.tempOverSample = 1;
    //pressOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.pressOverSample = 1;
    //humidOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.humidOverSample = 1;


    delay(6000); // so you have time to start the serial monitor and see the initial output
    Serial.print("Program Started\n");
    Serial.println("Starting BME280s... result of .begin():");
    delay(10);  //Make sure sensor had enough time to turn on. BME280 requires 2ms to start up.
    //Calling .begin() causes the settings to be loaded
    Serial.print("Sensor A: 0x");
    Serial.println(mySensorA.begin(), HEX);
}

void loop()
{
    //Start with temperature, as that data is needed for accurate compensation.
    //Reading the temperature updates the compensators of the other functions
    //in the background.
    Serial.print("Tempferature: ");
    Serial.print(mySensorA.readTempC(), 2);
    Serial.println(" degrees C");

    Serial.print("Temperature: ");
    Serial.print(mySensorA.readTempF(), 2);
    Serial.println(" degrees F");

    Serial.print("Pressure: ");
    Serial.print(mySensorA.readFloatPressure(), 2);
    Serial.println(" Pa");

    Serial.print("Pressure: ");
    Serial.print(mySensorA.readFloatPressure()*29.529983/100000, 2);
    Serial.println(" inHg");

    Serial.print("Altitude: ");
    Serial.print(mySensorA.readFloatAltitudeMeters(), 2);
    Serial.println("m");

    Serial.print("Altitude: ");
    Serial.print(mySensorA.readFloatAltitudeFeet(), 2);
    Serial.println("ft");

    Serial.print("%RH: ");
    Serial.print(mySensorA.readFloatHumidity(), 2);
    Serial.println(" %");

    Serial.println();

    delay(2000);

}

Type ‘particle serial monitor’ in your command prompt/terminal, and check to make sure the output is reasonable and working.

CdS Photocell

To measure light levels, we’ll use a CdS photocell. We’re going to use a 1 k resistor as a pull-down. Information on how to use a photocell can be found here. Solder the connections as so:

The circuit diagram for hooking up the BME280 and CdS photocell to the Particle Photon. Note the SDA/SCL pins are D0/D1 on the Photon.

The CdS photocell hookup is pretty simple, just 3.3V, GND, and A1.

It ended up being tough for me to place the CdS cell in the glass window because my wires were too short, so leave yourself some extra room with at least eight inches of wiring between the battery shield and the CdS cell.

Test the reading of the photocell with a flashlight, using this code:

language:c
void setup() {
    pinMode(A1, INPUT);
}

void loop() {
    float lightIntensity = analogRead(A1);
    Serial.println(lightIntensity);
    delay(1000);
}

Check the serial output with ‘particle serial monitor’, and make sure the number goes up when you shine a bright light on it. The number should read in the thousands; the range of the Photon analog signal is from 0 to 4095, so make sure the reading isn’t near 4095 unless you’re in broad daylight or close to a bright LED. There’s a nice classification of voltage output levels for different lighting conditions here.

Sensing Distance (Water Height) with an Ultrasonic Sensor

Because air and water have different densities, the water reflects some of the ultrasonic waves sent at it, for example, by something like the MaxSonar-EZ3 sensor (manufacturer’s page here). Again, I recommend the waterproof version for reliability.

To add this part to the telemetry box, first measure the distance from where you will put the telemetry box to where the ultrasonic sensor will go, and cut three sufficient lengths of wire. I used 22 AWG hookup wire and ended up with about 8 to 10 ft of wire. Solder the wires to the GND, +5, and PW holes on the device, by soldering the ends of the wires. Pass the wires through the cable gland, and solder the other ends of the wires to the battery shield: GND, 3.3V (or Vin), and A0.

The circuit diagram for hooking up the MaxSonic ultrasonic sensor, BME280 and CdS photocell to the Particle Photon battery shield. Note the SDA/SCL pins are D0/D1 on the Photon.

The soldered connection between the ultrasonic PW, GND, and 5V (can take 2.5-5V), and the Photon Battery Shield.

Make sure to pass the wires through the cable gland before soldering to the Battery Shield.

Test the device by uploading this code to your Photon:

language:c
float uSperInch = 147; // from datasheet
float distance;
unsigned long duration;

void setup() {
    pinMode(A0, INPUT);
}

void loop() {
    duration = pulseIn(A0, HIGH);
    Serial.print("pulse length: ");
    Serial.println(duration);
    distance = duration / uSperInch;
    Serial.print(distance);
    Serial.println(" in");
    delay(1000);
}

The datasheet from the manufacturer’s page says the pulse width is 147uS/inch, and it seemed to be right around there for me. Double check the readings with a measuring tape though.

Finishing the Telemetry Box

The few last things to do are pass through the solar cell barrel jack, stuff everything in the box (maybe with a little hot glue), and make sure all the external holes look well sealed up.

We have to cut the solar cell wire in two, and, using your wire strippers, strip each wire down. Then pass the wires through the cable gland and solder them back together. I used heat shrink to make the connections clean. The solar cell cable length is very short, so you might want to add some extensions. You could also add enough of an extension so that the box is in the shade (so it doesn’t get too hot, especially if you’re in the desert).

Chop the solar cell cable, put it through the cable gland, and re-attach it.

Finally, connect the battery and the solar cell to the Battery Shield, and put everything in the box as best you can. I hot-glued most things down, but in the sun, things get pretty hot (as we’ll see from the measurements), so the glue tends to un-stick. I did hot-glue the CdS cell to the glass window, and even after it un-stuck (and I reopened the box), it was still pretty easy to put back in the window due to the shape of the glue. Lastly, tighten the six screws down on the top of the box, tighten the cable gland, and maybe put some silicone on the cable gland to make sure it’s good and waterproof.

Here’s everything in the altered box. The extra loops of wire are from the ultrasonic sensor wires.

Field Installation

Put the box and solar cell in a place that’s going to get some sun. String the wires from the box through to the water tank. This is where things get tricky. If you have giant plastic water tanks, like we do, you’ll likely get static electricity buildup that will interfere with the measurements. As long as the sensor isn’t touching the tank (I also covered the sensor in aluminum foil and grounded it with a ground rod), it should be ok. If the tank isn’t plastic, you can drill a 5/8" hole somewhere in the tank. I covered most of the ultrasonic sensor with black electrical tape as a bit of protection.

If your tank is outside, you will probably be getting condensation at times. The waterproof sensor may fix this problem, otherwise, mount the non-waterproof sensor above the tank (with a hole to let the ultrasound pass into the tank) so that condensation won’t be happening on the sensor.

I put black electrical tape on the sensor for some protection and shoved it into the 5/8" hole on top of the water tank.

The water tanks on the property where this was installed are gigantic plastic (polyethylene, probably) tanks. The pump is about a half mile away, and the whole distance is bridged by PVC pipe. Possibly due to this, there seems to some static buildup in the system. As evidence, I’ve felt a massive static field (6-12 inches above the tank) before while climbing on top of the tanks. This appeared to be effecting the ultrasonic sensor, as it would perform great in lab tests, but out in the field it would get wonky after a few measurements (reading values smaller than the minimum distance), and correct measurements would come and go during the day and night. Things seemed to go haywire after the water started flowing for an hour or two–in either direction, in or out.

The other strange thing about this whole deal is when I would plug the photon into my computer, the readings would be OK again, and when I unplugged it, they would go back to being very small and incorrect.

About an hour after the pump was turned on, the ultrasonic measurement went a bit crazy. Then, a few hours later, it settled back down to the accurate reading. The same thing happened the next morning after the water had been flowing out of the tanks for a few hours.

To combat this, I drove a 10ft ½" EMT conduit rod about nine feet into the ground with a sledge hammer. I took a wire and connected one end to the EMT conduit. On the other end, I tied a stainless steel bolt to it and dropped it in the water tank. I also tied a wire around the ultrasonic sensor’s plastic housing and connected it to the EMT rod. It seemed to help somewhat, but still didn’t completely fix the problem.

The DIY grounding rod: before pounding (left) and after (right).

The only way I was able to get the sensor to reliably read water height was to suspend it above the tank, without the plastic housing touching the water tanks. I wrapped the sensor in aluminum foil (except the front face) and attached the ground wire to the foil. I then drilled some holes in a 1.5" aluminum flat bar, attached the bar to the water tank, and attached a grounding wire to the bar. After that, the readings were stable.

However, after a few days, the readings started going haywire. I found there was condensation on the sensor that caused this. If your water tank is outside, mount the sensor above the tank (using something like the metal plate I used), and put a hole in the tank (larger than the sensor diameter), directly below the sensor.

I drilled two 5/8" holes for the two ultrasonic sensors I’m using, a few holes for bolts to hold it to the water tank, and a hole for a grounding wire.

The aluminum bar suspended from the water tank with the sensor in place.

Some people claim plastic can’t be grounded, and they may be right. However, adding a grounding lug at the inlet to the tank may work, although I haven’t tried this.

My installation of the out-of-tank waterproof ultrasonic sensor. The sensor is mounted slightly above the tank, with a hole drilled in the tank. This prevents condensation from interfering with the sensor (only necessary if the tank is outdoors).

Final installation of the telemetry box. I ended up using a yagi antenna (bought from Ebay) to be able to get wifi reception reliably.

Using the waterproof HRXL sensor may completely bypass the static electricity problem; I’m not sure. In any case, it would be a better idea for long-term robustness to use the waterproof sensor.

Finally, you need to know the distance from the bottom of the tank to the front of the sensor, so get out your measuring tape and check that now, and make a note of it. To get the water height, we simply take the total water tank height and subtract the distance read from the ultrasonic sensor.

The Code

The code for this project lives on GitHub. You can find all the latest by following the link below.

Photon Remote Water Level Sensor Code

Minimum Viable Product

In the startup world, a minimum viable product (MVP) is something that gets the job done and nothing more. I’ll give you an example of the MVP for the setup we’ve built here.

Particle Publish and Subscribe

Using the function Particle.Publish(), we can quickly toss up a variable online so other Photons or devices can use it. In this example it will be used to send the water height and let our pump control box know the water height sensor is still online, and it can also be used to send commands, like ‘turn on the pump’, or ‘don’t deep sleep our telemetry Photon quite yet’.

The format of a publish is MQTT-like. A subscription works like a prefix filter. If you subscribe to “foo”, you will receive any event whose name begins with “foo”, including “foo”, “fool”, “foobar”, and “food/indian/sweet-curry-beans”.

I set up my prefix organization and subscribes as so:

language:c
Particle.subscribe("jsf/waterSystem/", eventHandler, MY_DEVICES);

If I want the water height sensor to tell the control box that it’s still online, I would do:

language:c
Particle.publish("jsf/waterSystem/waterTankSensor/online", "true");

You can also use the ‘private’ flag with your publishes, and use the ‘MY_DEVICES’ flag with your subscribes, if you want to improve security.

Depending on your situation, you may be sleeping the telemetry Photon for a long time and only have it on for a few minutes or seconds. In this case, it makes updating the software tough. For that, I created a Python script that senses when the Photon comes online and tells it to wait a bit for a software update. If you want to use it, install Python – I like using Python(x,y) for Windows, and run this script (first install sseclient, requests, and json using pip or easy_install; type ‘easy_install sseclient’ or ‘pip install sseclient’ in your command prompt or terminal for sseclient, requests, and json):

language:python
from sseclient import SSEClient
import requests, re, json

access_token = "YOUR ACCESS TOKEN HERE"
publish_prefix_head = "myFarm" # for subscribing to incoming messages, e.g. myFarm
publish_prefix = "myFarm/waterSystem" # e.g. myFarm/waterSystem
messages = SSEClient('https://api.spark.io/v1/events/' + publish_prefix_head + '?access_token=' + access_token)
r = requests.post('https://api.particle.io/v1/devices/events', data = {"name":publish_prefix + "/waterTankSensor/update", "data":"true", "private":"false", "ttl":"60", "access_token":access_token})
if r.json()['ok']==True:
    print 'successfully sent update request'


with open('recorded messages.txt', 'w') as record:
    for msg in messages:
        event = str(msg.event).encode('utf-8')
        data = str(msg.data).encode('utf-8')
        if re.search('jsf', event):
            dataJson = json.loads(data)
            if event == publish_prefix + '/waterTankSensor/online' and dataJson['data'] == "true":
                r = requests.post('https://api.particle.io/v1/devices/events', data = {"name":publish_prefix + "/waterTankSensor/update", "data":"true", "private":"false", "ttl":"60", "access_token":access_token})
                if r.json()['ok']==True:
                    print 'successfully sent update request'
            if event == publish_prefix + '/waterTankSensor/updateConfirm':
                if dataJson['data'] == 'waiting for update':
                    print 'device waiting for update...'
                if dataJson['data'] == 'not waiting for update':
                    print 'device no longer waiting for update.'

Save the code in a file called ‘updatefirmware.py’, and, once you type ‘python updatefirmware.py’ (from the same directory the file is located in, of course), it will print some messages out. When the device is waiting for an update, it will print ‘device waiting for update…’. Then you can head to build.particle.io, and flash your device.

Telemetry Box

Create a new Photon app on build.particle.io, and include the ThingSpeak library in it (make sure it’s the “ThingSpeak” library, and not the “thingspeak” library–note the capitalization). Right now it shows up as the first result from searching for ‘things’. Also include the SPARKFUNMAX17043 and SPARKFUNBME280 libraries. Here is the full code:

language:c
#include "SparkFunBME280/SparkFunBME280.h"
BME280 mySensorA;
float tempF;
float pressure;
float RH;

#include "SparkFunMAX17043/SparkFunMAX17043.h"
// MAX17043 battery manager IC settings
float batteryVoltage;
float batterySOC;
bool batteryAlert;

#include "ThingSpeak/ThingSpeak.h"
//################### update these vars ###################
unsigned long myChannelNumber = your channel number here;  //e.g. 101992
const char * myWriteAPIKey = "your api key here"; // write key here, e.g. ZQV7CRQ8PLKO5QXF
//################### update these vars ###################
TCPClient client;
unsigned long lastMeasureTime = 0;
unsigned long measureInterval = 60000; // can send data to thingspeak every 15s, but give the matlab analysis a chance to add data too

// ultrasonic distance sensor for water height measurement
float uSperInch = 147; // from datasheet
float distance;
unsigned long duration;
float waterHeight;
//################### update these vars ###################
float totalDistance = 64; // the distance from the sensor to the bottom of the water tank
//################### update these vars ###################

// photocell
float lightIntensity;

// connection settings
STARTUP(WiFi.selectAntenna(ANT_EXTERNAL)); // use the u.FL antenna, get rid of this if not using an antenna
float batterySOCmin = 40.0; // minimum battery state of charge needed for short wakeup time
unsigned long wakeUpTimeoutShort = 300; // wake up every 5 mins when battery SOC > batterySOCmin
unsigned long wakeUpTimeoutLong = 900; // wake up every 15 mins during long sleep, when battery is lower
unsigned long connectedTime; // millis() at the time we actually get connected, used to see how long it takes to connect
unsigned long connectionTime; // difference between connectedTime and startTime

// for updating software
bool waitForUpdate = false; // for updating software
unsigned long updateTimeout = 600000; // 10 min timeout for waiting for software update
unsigned long communicationTimeout = 300000; // wait 5 mins before sleeping
unsigned long bootupStartTime;

// for publish and subscribe events
//################### update these vars ###################
String eventPrefix = "your prefix"; // e.g. myFarm/waterSystem
//################### update these vars ###################

bool pumpOn;

void setup() {
    // Set up the MAX17043 LiPo fuel gauge:
    lipo.begin(); // Initialize the MAX17043 LiPo fuel gauge

    // Quick start restarts the MAX17043 in hopes of getting a more accurate
    // guess for the SOC.
    lipo.quickStart();

    // We can set an interrupt to alert when the battery SoC gets too low.
    // We can alert at anywhere between 1% - 32%:
    lipo.setThreshold(20); // Set alert threshold to 20%.
    // use this to measure how long it takes to connect the Photon to the internet if you're in spotty wifi coverage
    pinMode(A0, INPUT); // ultrasonic distance sensor

    // set up BME280 sensor
    mySensorA.settings.commInterface = I2C_MODE;
    mySensorA.settings.I2CAddress = 0x77;
    mySensorA.settings.runMode = 3; //  3, Normal mode
    mySensorA.settings.tStandby = 0; //  0, 0.5ms
    mySensorA.settings.filter = 0; //  0, filter off
    //tempOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.tempOverSample = 1;
    //pressOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.pressOverSample = 1;
    //humidOverSample can be:
    //  0, skipped
    //  1 through 5, oversampling *1, *2, *4, *8, *16 respectively
    mySensorA.settings.humidOverSample = 1;
    mySensorA.begin();

    ThingSpeak.begin(client);

    Particle.subscribe(eventPrefix, eventHandler);
    Particle.publish(eventPrefix + "/waterTankSensor/online", "true"); // subscribe to this with the API like: curl https://api.particle.io/v1/devices/events/temp?access_token=1234
    bootupStartTime = millis();
    doTelemetry(); // always take the measurements at least once
}

void loop() {
    if (waitForUpdate || millis() - bootupStartTime > communicationTimeout || batterySOC > 75.0 || pumpOn) {
        // The Photon will stay on unless the battery is less than 75% full, or if the pump is running.
        // If the battery is low, it will stay on if we've told it we want to update the firmware, until that times out (updateTimeout)
        // It will stay on no matter what for a time we set, stored in the variable communicationTimeout
        if (millis() - lastMeasureTime > measureInterval) {
            doTelemetry();
        }
            if ((millis() - bootupStartTime) > updateTimeout) {
                waitForUpdate = false;
            }
    } else {
            if (batterySOC < batterySOCmin) {
                System.sleep(SLEEP_MODE_DEEP, wakeUpTimeoutLong);
            } else {
                System.sleep(SLEEP_MODE_DEEP, wakeUpTimeoutShort);
            }
    }
}

void eventHandler(String event, String data)
{
  // to publish update: curl https://api.particle.io/v1/devices/events -d "name=update" -d "data=true" -d "private=true" -d "ttl=60" -d access_token=1234
  if (event == eventPrefix + "/waterTankSensor/update") {
      (data == "true") ? waitForUpdate = true : waitForUpdate = false;
      if (waitForUpdate) {
        Serial.println("wating for update");
        Particle.publish(eventPrefix + "/waterTankSensor/updateConfirm", "waiting for update");
      } else {
        Serial.println("not wating for update");
        Particle.publish(eventPrefix + "/waterTankSensor/updateConfirm", "not waiting for update");
      }
  } else if (event == eventPrefix + "/waterTankPump/pumpOn") {
      (data == "true") ? pumpOn = true : pumpOn = false;
  }
  Serial.print(event);
  Serial.print(", data: ");
  Serial.println(data);
}

void doTelemetry() {
    // let the pump controller know we're still here
    Particle.publish(eventPrefix + "/waterTankSensor/online", "true");

    // water height
    duration = pulseIn(A0, HIGH);
    distance = duration / uSperInch; // in inches
    waterHeight = totalDistance - distance;
    ThingSpeak.setField(1, waterHeight);

    Particle.publish(eventPrefix + "/waterTankSensor/waterHeight", String(waterHeight));

    // BME280
    pressure = mySensorA.readFloatPressure()*29.529983/100000.0;
    ThingSpeak.setField(2, pressure);
    tempF = mySensorA.readTempF();
    ThingSpeak.setField(4, tempF);
    RH = mySensorA.readFloatHumidity();
    ThingSpeak.setField(5, RH);

    // photocell
    lightIntensity = analogRead(A1);
    ThingSpeak.setField(6, lightIntensity);

    // read battery states
    batteryVoltage = lipo.getVoltage();
    ThingSpeak.setField(7, batteryVoltage);
    // lipo.getSOC() returns the estimated state of charge (e.g. 79%)
    batterySOC = lipo.getSOC();
    ThingSpeak.setField(8, batterySOC);
    // lipo.getAlert() returns a 0 or 1 (0=alert not triggered)
    //batteryAlert = lipo.getAlert();

    ThingSpeak.writeFields(myChannelNumber, myWriteAPIKey);
    lastMeasureTime = millis();
}

Variables you should change when you do this:

• eventPrefix (e.g. myFarm/waterSystem; for publish/subscribe events)
• myWriteAPIKey (grab from your ThingSpeak telemetry channel)
• myChannelNumber (from ThingSpeak telemetry channel)
• totalDistance (the distance from the sensor to the bottom of the water tank

I’ve bracketed these variables with:

language:c
//################### update these vars ###################

so you know what you have to change.

Additionally, you can adjust the batterySOCmin and wakeupTimeout variables if you use a different sized battery.

Control Box

Again, include the ThingSpeak library. Use this code, changing variables where applicable:

language:c
#include "ThingSpeak/ThingSpeak.h"
// channel we're writing to
//################### update these vars ###################
unsigned long myWriteChannelNumber = your channel number; // e.g 101223
const char * myWriteAPIKey = "your write API key for the pump controller channel";
//################### update these vars ###################
TCPClient client;
unsigned long lastMeasureTime = 0;
unsigned long measureInterval = 60000; // can send data to thingspeak every 15s, but once a minute is fine

bool pumpOn = false;
float waterHeight = 1000; // we want to make sure the relay isn't falsely triggered on from the get-go
//################### update these vars ###################
float lowerCutoff = 20; // lowest acceptable water height, in inches
float higherCutoff = 42; // highest acceptable water height, in inches
float totalDistance = 64; // the distance from the sensor to the bottom of the water tank
//################### update these vars ###################
int success;
unsigned long relayStartTime;
unsigned long lastSignal = millis();
unsigned long pumpTimeout = 900000; // turn off the pump if haven't heard from sensor in 15 mins
unsigned long pumpOffTime = 3600000; // make sure we don't turn on the pump more than once per hour
long pumpOffTimeStart = -pumpOffTime; // so we can turn on pump when we startup if we need to

// PIR motion sensor
int relayPin = 0;
int PIRpin = 7;
int PIRval;

// for publish and subscribe events
//################### update these vars ###################
String eventPrefix = "myFarm/waterSystem"; // e.g. myFarm/waterSystem
//################### update these vars ###################

void setup() {
    pinMode(relayPin, OUTPUT);
    pinMode(PIRpin, INPUT_PULLUP);
    digitalWrite(relayPin, LOW);

    Particle.subscribe(eventPrefix, eventHandler);

    ThingSpeak.begin(client);
}

void loop() {
    autoPumpControl();
    checkPIR();
    recordThingSpeakData();
}

int relayControl(String relayState)
{
    if (relayState == "on") {
        pumpOn = true;
        digitalWrite(relayPin, HIGH);
        relayStartTime = millis();
        ThingSpeak.setField(1, 1); // our "pump on" field
        return 1;
    }
    else if (relayState == "off") {
        pumpOn = false;
        digitalWrite(relayPin, LOW);
        ThingSpeak.setField(1, 0); // our "pump on" field
        return 1;
    }
    else {
        return 0;
    }
}

void autoPumpControl() {
    if (pumpOn) {
        if (millis() - lastSignal > pumpTimeout) { // if we haven't heard from the water tanks in a while, turn off the pump
            relayControl("off");
        }
    }
    if (waterHeight < lowerCutoff) {
        success = relayControl("on");
    } else if (waterHeight > higherCutoff) {
        success = relayControl("off");
    } else {
        ThingSpeak.setField(1, boolToNum(pumpOn)); // our "pump on" field
    }
}

void checkPIR() {
    PIRval = digitalRead(PIRpin);
    if(PIRval == LOW){
        ThingSpeak.setField(2, 1); // 1 = motion detected, 0 = no motion
    }
}

void recordThingSpeakData() {
    if (millis() - lastMeasureTime > measureInterval) {
        ThingSpeak.writeFields(myWriteChannelNumber, myWriteAPIKey);
        ThingSpeak.setField(2,0); // reset PIR motion sensor field to 'no motion detected'
        lastMeasureTime = millis();
        Particle.publish(eventPrefix + "/waterTankPump/pumpOn", boolToText(pumpOn));
    }
}

String boolToText(bool thing)
{
    String result;
    thing ? result = "true" : result = "false";
    return result;
}

int boolToNum(bool thing)
{
    int result;
    thing ? result = 1 : result = 0;
    return result;
}

void eventHandler(String event, String data)
{
  if (event == eventPrefix + "/waterTankSensor/online") {
      Particle.publish(eventPrefix + "/waterTankPump/pumpOn", boolToText(pumpOn));
  } else if (event == eventPrefix + "/waterTankSensor/online") {
      (data == "true") ? lastSignal = millis() : Serial.println(data);
  } else if (event == eventPrefix + "/waterTankSensor/waterHeight") {
      waterHeight = data.toFloat();
  }
}

Variables you should change when you do this:

• eventPrefix (e.g. myFarm/waterSystem; for publish/subscribe events)
• myWriteAPIKey (grab from your ThingSpeak pump controller channel)
• myWriteChannelNumber (from ThingSpeak pump controller channel)
• lowerCutoff (lowest acceptable water height, in inches)
• higherCutoff (highest acceptable water height, in inches)
• totalDistance (distance from ultrasonic sensor face to bottom of water tank)

I’ve bracketed these variables with:

language:c
//################### update these vars ###################

so you know what you have to change.

Some of the code may be confusing, especially something like

language:c
thing ? result = 1 : result = 0;

This is shorthand for an if-else statement. It’s the equivalent of

language:c
if (thing) {
    result = 1;
} else {
    result = 0;
}

Default Firmware Feature/Bug

There are a few challenges when working with the Photon and its development environment. One of the biggest problems is that sometimes new firmware versions break old code. For example, from the time I developed this original system (Oct 2015) to the time this tutorial was written (Mar 2016), a new firmware version came out (0.4.9), which is incompatible with my old code. The worst part about it is, the Photon sits there blinking a red error message on the LED and is impossible to flash without physically accessing the device. Kind of a pain when it’s on top of a roof and in a watertight enclosure held together by 6 screws (and there’s a bunch of melting snow everywhere).

I think what ended up being broken with the new firmware was the WiFi.selectAntenna() function, which was silly and tiny. Regardless, we want to disable automatic firmware updates for our devices running important tasks like this, so it can keep running for years. To do this, click the ‘Devices’ icon on the left of build.particle.io, click the star (left) and the arrow (right) next to the device we’re going to flash, then choose the 0.4.9 firmware (without Default). Re-flash your device, and it’s good to go. Do this for both the telemetry and control box Photons.

Leaving the firmware on ‘default’ will auto-upgrade and can break your system. Just say ‘no’ to default firmware, and set it to 0.4.9 for this tutorial’s code.

Setting Up the ThingSpeak Channels

The Telemetry Channel

There are many sites out there for storing your IoT data: SparkFun’s phant.io, dweet.io, and my personal favorite, The Mathworks' ThingSpeak. ThingSpeak already has some nice built-in features, like Google visualization plugins, Twitter interfacing, React (which can do something like post a tweet when data meets a threshhold), MATLAB analysis, and more. It’s also open-source.

First, sign up for a ThingSpeak account if you don’t already have one. Next, create a channel by going to Channels->My Channels->New Channel. Click the checkboxes next to each field (1 through 8) and label them:

• Water Height (inches)
• P (inHg)
• pressure change rate (inHg/min)*10⁶
• T (F)
• RH %
• light intensity
• battery V
• battery SOC

Check the box next to ‘Make Public’ if you want other people to be able to view it without needing the read API key. To finish, click ‘Save Channel’.

Now, click “API Keys” in the menu bar that should be around the middle of your screen. Copy the “Write API” key, and put that in your Photon telemetry box code as the myWriteAPIKey variable. Also copy the “Channel ID” number from your ThingSpeak channel page, and set that as the myChannelNumber variable in your Photon telemetry code.

Click on ‘API Keys’ and your keys (that you need in your Photon code) should be right there.

Once you power up your telemetry Photon, you should see the data start getting populated (your ThingSpeak page will auto-refresh every 15-ish seconds).

Now, we’ll set up a Twitter feed to post info on our data, which can be used to send alerts on rapidly dropping pressure (which can signal bad weather). Create a Twitter account, sign in, and go back to your ThingSpeak page. Click on “Apps” on the top menu bar. Click “ThingTweet”, and then “Link Twitter Account”.

Once you’ve linked your Twitter account, go back to the ‘Apps’ page and click on MATLAB analysis. Use this code, changing the API keys and channel ID for your channel:

language:MATLAB
% Calcuclates the pressure difference over the last 3 hours
% writes to channel as long as the time difference between
% the two points is at least 2 hours

% Channel ID to read data from
ChannelID = 101982;
% Pressure Field IDs
PressureFieldID = 2;
PressureChangeID = 3;

% TODO - Put your API keys here:
writeAPIKey = 'your write API key';
readAPIKey = 'your read API key'; % this is only necessary if the channel is private

% Get humidity data for the last 60 minutes from the MathWorks Weather
% Station Channel. Learn more about the THINGSPEAKREAD function by going to
% the Documentation tab on the right side pane of this page.

[pressure, timestamps, chInfo] = thingSpeakRead(ChannelID, 'ReadKey', readAPIKey,  'Fields', PressureFieldID, 'NumMinutes', 180);

[m,n]=size(pressure)
display(m)

if m > 1 % we need at least 2 points to do the calculation
    % Calculate the pressure change
    pressureChange = pressure(end)-pressure([1]);
    % pressure(end) gets us the most recent pressure reading, which is last in the pressure variable (a Matlab matrix)
    display(pressureChange, 'pressure change (inHg)'); % this shows up below when you hit run
    timeDiff = minutes(diff([timestamps([1]), timestamps(end)])); % difference in minutes between the first and last readings
    display(timeDiff);
    pressureChangeRate = pressureChange/timeDiff * 1000000;
    display(pressureChangeRate, 'pressure change rate (inHg/min)*10^6');


    % Write the average humidity to another channel specified by the
    % 'writeChannelID' variable

    % Learn more about the THINGSPEAKWRITE function by going to the Documentation tab on
    % the right side pane of this page.
    if timeDiff > 60.0 % make sure the time difference is at least 1 hour between the points
        for n=1:8 % quite a bit of a hack, but it works
            pause(2); % they don't allow more than 2s pauses (delays) here, and I didn't take the time
            % to figure out how to do a callback, etc
        end
        thingSpeakWrite(ChannelID, pressureChangeRate, 'Fields', PressureChangeID, 'writekey', writeAPIKey);
        display('writing to channel')
    end
else
    display('not enough data in channel yet')
end

Make sure to hit ‘save and run’, and you can check the output below the code area to see it working. Scroll down a bit, click “React”, then set up a react to run on new data insertion. The picture below shows the details for the react, which are:

Screenshots of the Reacts for pressure drop (bad weather approaching) alerts. I actually ended up having the pressure rate of change test frequency being ‘on data insertion’, and the tweets happen every 60 minutes.

Finally, go back to ‘Apps’ one more time to set up some Twitter alerts. Click on ‘React’ and then ‘New React’. Set the values as shown in the picture above, and the table below:

The %%trigger%% is replaced by the value of the field. Hit ‘Save React,’ and you’re good to go.

The Control Box Channel

Set up another ThingSpeak channel, with just two fields set as:

• pump on
• motion detected

The API keys from this will be used in the control box Photon code.

ThingSpeak Google Gauges

Another nice feature of ThingSpeak is the ease with which nice looking graphics can be made (once you get the hang of it). For example, a Google Gauge can be embedded in your ThingSpeak channel (or anywhere else with JavaScript). Unfortunately, ThingSpeak recently disabled JavaScript apps from being on public pages, so this will only work on private views or other custom applications.

The Google Gauge provides a quick way to take in information.

To get this gauge going for the water tank fullness, go to ThingSpeak.com, click Apps->Plugins->New->Google Gauge->Create, and use this code for the JavaScript:

language:javascript<script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js'></script><script type='text/javascript' src='https://www.google.com/jsapi'></script><script type='text/javascript'>

  // set your channel id here
  var channel_id = channel ID here; // eg 101992
  // set your channel's read api key here
  var api_key = 'your readAPI key here';
  // maximum value for the gauge
  var max_gauge_value = 42; // this is the maximum water height from your telemetry code
  // name of the gauge
  var gauge_name = 'Water tank level (%)';

  // global variables
  var chart, charts, data;

  // load the google gauge visualization
  google.load('visualization', '1', {packages:['gauge']});
  google.setOnLoadCallback(initChart);

  // display the data
  function displayData(point) {
    data.setValue(0, 0, gauge_name);
    data.setValue(0, 1, point);
    chart.draw(data, options);
  }

  // load the data
  function loadData() {
    // variable for the data point
    var p;

    // get the data from thingspeak
    $.getJSON('https://api.thingspeak.com/channels/' + channel_id + '/feed/last.json?api_key=' + api_key, function(data) {

      // get the data point
      p = data.field1;

      // if there is a data point display it
      if (p) {
        p = Math.round((p / max_gauge_value) * 100);
        displayData(p);
      }

    });
  }

  // initialize the chart
  function initChart() {

    data = new google.visualization.DataTable();
    data.addColumn('string', 'Label');
    data.addColumn('number', 'Value');
    data.addRows(1);

    chart = new google.visualization.Gauge(document.getElementById('gauge_div'));
    options = {width: 200, height: 200, redFrom: 0, redTo: 20, yellowFrom:20, yellowTo: 50, greenFrom: 50, greenTo: 100, minorTicks: 5}; // customize the red, yellow, and green levels if you want

    loadData();

    // load new data every 15 seconds
    setInterval('loadData()', 15000);
  }

</script>

Don’t forget to change the <title> in the HTML section. Then simply click checkboxes on the channels for which you want the Gauge to be visible. You can drag and drop the Gauge (while viewing the channel) to be anywhere on the page.

Setting Up Text Alerts

If you want to get an alert via text or email when the pressure drops rapidly (or for other data events), it can be done with ifttt.com. Head over there and setup an account, and connect your phone to IFTTT. Click ‘My Recipes’ on the top menu, click ‘Create a Recipe’, then click ‘this’. Search for ‘twitter,’ and click on the Twitter icon. Unfortunately, IFTTT’s “tweet from search” feature seems to be broken, hopefully it’s fixed soon. For now, the best we can do is send a text every time we post a new tweet. This unfortunately means we can’t tweet more mundane things right now, since it would be annoying getting that many texts.

Click on ‘Create a Recipe’ to get started.

Click ‘New tweet by a specific user’, then enter your username after the “@” symbol, similar to “@JSF_auto_farm”. Next, click ‘that’, search for SMS, and click ‘Send an SMS’. I just left the message as the default. Click ‘Create Action’ and ‘Create Recipe’, and that’s it! If you had to create and link accounts for everything to get to this point, it will be much faster next time you want a text alert for some remote measurement.

When IFTTT does eventually get their Twitter search feature fixed, we can use a hashtag to filter our results. After clicking ‘this’, search for ‘twitter’, then choose ‘New tweet from search’. Use this as the search:

“@your_twitter_username” “#rapid_pressure_drop”

replacing your_twitter_username with the one you picked previously.

Alternate: Use Gmail to Send Texts

For the ‘that’ portion, you can also choose Gmail (you will have to link a Gmail account for this step), and click ‘Send an email’. If you want to send a text, you can do it as so:

1234567890@vtext.com

Instructions for using email to send a text with any carrier can be found here. I was having trouble getting the texts to consistently go through via Gmail with IFTTT, so I switched to the straight IFTTT SMS feature.

There are many other ways to set up SMS alerts, such as Twilio, SendGrid, or IOBridge. None of these methods have been tested with this setup yet.

Final Data Analysis

Here’s some data from field testing:

Full Colorado sunlight is bright.

The temp inside the box got up to about 95…when it was 60 out. May have to move this into the shade after all. There were also some strange gyrations going on.

The battery never dropped below 40% over one night. I’m also running two ultrasonic sensors, which draws a bit more power.

The pressure was dropping in the ‘moderate’ regime this day.

Resources and Going Further

For better system reliability (to keep running during Internet outages) you could run the particle cloud locally (which would require more processing to log data on ThingSpeak), use long-range serial radio transceivers (like this one to communicate directly between the Photons), or eventually, just communicate directly between the photons. Don’t forget you can use long-range antennas like yagi antennas to boost your connection range.

If you want to take this further, you can always:

• use an Photon Internet button to remote control the pump
• build an aluminum light-shield (with a hole for the photocell) to keep the box from getting too hot in the summer
• log the humidity and temperature in the tank using this sensor (or others)
• log the water temperature with a sensor
• log water pressure near the pump with a sensor
• log water flow rates with a flowmeters
• alerts for too high or low of temperature (ideal charging temperatures are 32-113 F, and the electrolyte in the batteries starts to decompose at about 160 F) – if you’re in the desert, you might want to get a text if the box is getting hot so you can cover it with a wet shadecloth, or permanantly shade the box with aluminum
• analysis of pump flowrate/water usage using MATLAB processing in ThingSpeak
• analysis of energy use/pump on time with MATLAB processing
• analysis of pump hours run, and alerts when it’s time for maintenance or nearing the pump’s end-of-life
• uptime of photons
• motion sensor alarms late at night with ThingSpeak reacts
• web interface for controlling the pump
• remote control button for pump control
• remote monitoring in the house, etc (OLED, TFT, WS2812 LEDs) for telemetry data

I’ve already created a simple web form that can be used to remotely control the pump, and switch it between manual and auto mode, but it requires a little more coding of the Photons, and serving a web page. Perhaps in a future tutorial I’ll show you how to do these things.

Again, all the code for this project can be found on GitHub.

Photon Remote Water Level Sensor Code

For more Photon fun, check out these other great SparkFun tutorials:

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

ASCII a learn.sparkfun.com tutorial

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

Introduction

If computers operate in binary, then how are we able to store letters and words? To do this, we assign numbers to characters. This is known as character encoding.

Looking at the internals of a simple text document

To understand how character encoding works, let’s create a simple example. First, assign the numbers 1-26 to the English alphabet:

1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w  x  y  z

To write a simple encoded message, we substitute the numbers for the letters. For example, 8 5 12 12 15. By using numbers, we have constructed the word h e l l o.

But to completely capture the English alphabet – including upper and lower-case letters, numbers, and punctuation – we needed more than 26 characters. As a result, the American Standard Code for Information Interchange (ASCII) was created as one of the first character encoding standards for computers.

What You Will Learn

The following topics will be covered in this tutorial:

• A brief history of ASCII
• How to translate decimal, binary, and hexadecimal numbers to ASCII

Suggested Reading

There are a few concepts that you might want to be familiar with before starting to read this guide:

• Binary - Knowing how a computer stores numbers is useful to translating those numbers to characters.
• Hexadecimal - Hexadecimal is often used to express binary numbers in groups of 4 bits.
• Installing Arduino IDE - Arduino is a good way to try printing ASCII characters.

History

The American Standards Association (ASA), now the American National Standards Institute (ANSI), began work on ASCII on October 6, 1960. The encoding scheme had origins in the 5-bit telegraph codes invented by Émile Baudot. The committee eventually decided on a 7-bit code for ASCII.

7 bits allow for 128 characters. While only American English characters and symbols were chosen for this encoding set, 7 bits meant minimized costs associated with transmitting this data (as opposed to say, 8 bits).

The first 32 characters of ASCII were reserved control characters. These characters were used to relay special instructions to other devices, like printers. For example, a user could advance a line, delete a character, and on some devices, ring a bell (such as on the Teletype Model 33 ASR).

ASA published the first version of ASCII in 1963 and revised it in 1967. The last major update to the standard occurred in 1986. ASCII first saw commercial use in the American Telephone & Telegraph (AT&T) TeletypeWriter Exchange (TWX) network.

Teleprinters, like this Teletype Model 33 ASR, were used to send typed messages to one or more other teleprinters across various communication channels (Image courtesy of Arnold Reinhold of Wikimedia Commons)

On March 11, 1968 President Lyndon B. Johnson mandated that all US federal government computers must support ASCII, thus cementing ASCII’s place in American computing history.

Other encoding schemes existed at the time, such as the International Telegraph Alphabet No. 2 (ITA2), but ASCII quickly became the standard for American English encoding. ASCII was the most common encoding found on the Internet until it was surpassed by UTF-8 in 2007.

ASCII Table

To identify a character’s ASCII value, it is common to look it up on an ASCII table. The ASCII table pairs each character to its assigned value between 0 and 127.

Control Characters

Control characters make up the first 32 characters of the ASCII table. These characters are not intended to be printed, instead they are used to send command instructions to another device, such as a printer. Note that we have included the octal representation of the ASCII characters in the off chance that you might be working with a particularly old system (such as the 12-bit PDP-8).

Printable Characters

There are 95 printable characters in the ASCII encoding scheme. Note that the “space” character denotes a printable space (“ ”).

Try It

If you would like to try printing something using ASCII encoding, you can try it out using Arduino. See this tutorial for getting started with Arduino.

Open the Arduino IDE and paste in the following code:

language:c
void setup()
{
  Serial.begin(9600);
}

void loop()
{
  Serial.write(0x48); // H
  Serial.write(0x65); // e
  Serial.write(0x6C); // l
  Serial.write(0x6C); // l
  Serial.write(0x6F); // o
  Serial.write(0x21); // !
  Serial.write(0x0A); // \n

  delay(1000);
}

Run it on your Arduino, and open a Serial console. You should see the “Hello!” appear over and over:

Notice that we had to use Serial.write() instead of Serial.print(). The write() command sends a raw byte across the serial line. print(), on the other hand, will try and interpret the number and send the ASCII-encoded version of that number. For example, Serial.print(0x48) would print 72 in the console.

Also, notice that we used the ASCII character 0x0A, which is the “line feed” control character. This causes the printer (or console in this case) to advance to the next line. It is similar to pressing the ‘enter’ key.

Resources and Going Further

There are many character encoding sets available. The most popular encoding for the World Wide Web is UTF-8. As of June 2016, UTF-8 is used in 87% of all web pages.

UTF-8 is backwards compatible with ASCII, which means the first 128 characters are the same as ASCII. UTF-8 can use 2, 3, and 4 bytes to encode characters from most modern written languages, including Latin, Greek, Cyrillic, Arabic, Chinese, Korean, and Japanese characters.

Knowledge of basic ASCII encoding can be useful when working in serial terminals. See the Serial Terminal Basics to learn how to use some of the many serial terminal programs available.

If you are interested in downloading the ASCII table in image format, click the button below. With an image, you can print it out and hang it on your wall, put it on a coffee mug, or have it printed on a mouse pad.

ASCII Table Images

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

Hazardous Gas Monitor a learn.sparkfun.com tutorial

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

Introduction

Build a portable gas monitor to check for dangerous levels of hazardous gases in your home, community, or on the go and prevent your friends from lighting a cigarette during a gasoline fight.*

This tutorial shows you how to build a web-connected “canary” monitor for three hazardous gases: Liquid Propane Gas (“LPG”), Methane (aka natural gas), and Carbon Monoxide (“CO”). Using the Particle Photon microcontroller, the sensor readings are converted into parts-per-million (“PPM”) and uploaded to the data.sparkfun.com web service.

*Please note that this is solely a movie reference – gasoline fights should probably be avoided in real life.

Check out the video below to see the Hazardous Gas Monitor in action:

Helpful Background Info

1. How to set up the Particle Photon.
2. Pushing data to the data.sparkfun.com web server.
3. New to relays? Check out this a handy reference.
4. Here’s a helpful overview on the N-Channel MOSFET.
5. For powering the Photon, here’s a thorough guide on the Photon Battery Shield.
6. Highly recommended to peruse the datasheets for the three gas sensors.
   1. LPG sensor datasheet
   2. Methane sensor datasheet
   3. CO sensor datasheet

Choosing a Battery

The gas sensors used in this project require a fair amount of current, about 0.17 mA each at 5V. To make the system portable, we’ll need a high capacity battery. One easy, and affordable, option is to use four (rechargeable) AA batteries in series. These batteries will last about 4 hours.

Another option is to use a lithium ion battery (“LIB”). LIBs have a higher capacity than AAs, but typically run at a lower voltage. If you go with this option, you may need to include a correction factor when you calculate the sensor value or boost the battery voltage with a transistor or other component.

Here’s a table that shows the approximate lifetime of a few different battery options.

If all of this sounds confusing, here’s a more thorough tutorial.

Materials

Microcontroller and Accessory Components

• Particle Photon microcontroller
• SparkFun Photon Battery Shield
• One 2000 mAh Polymer Lithium Ion Battery
• Surface Mount DC Barrel Jack
• Barrel jack to USB power supply cable
• One (1) Lamp Switch
• Optional: Male-to-Female JST connector cable

Gas Sensor Circuit

• One (1) Project Case
• One (1) 4 AA battery case
• Four (4) AA Rechargeable Batteries
• One (1) Toggle Switch (SPST switch)
• Piezo Buzzer
• Three (3) Red LEDs
• Three (3) 10 kΩ resistors
• One (1) PCB
• 22 Gauge stranded wire
• Optional: Electrical connectors (3-5)

LPG (MQ6) Gas Sensor

• MQ6 LPG Gas Sensor
• Gas Sensor Breakout Board
• One (1) 4.7 kΩ resistor
• One (1) 5V Voltage Regulator

Methane (MQ4) Gas Sensor

• MQ4 Methane Gas Sensor
• Gas Sensor Breakout Board
• One (1) 4.7 kΩ resistor
• One (1) 5V Voltage Regulator

Carbon Monoxide (MQ7) Gas Sensor

• MQ7 CO Gas Sensor
• Gas Sensor Breakout Board
• One (1) 4.7 kΩ resistor
• One (1) 5V Voltage Regulator
• One (1) 5V SPDT Relay
• One (1) N-Channel MOSFET
• One (1) 10 kΩ potentiometer
• One (1) 10 kΩ resistor

Tools

• Soldering Iron
• Wire cutters/strippers
• Drill
• Screwdriver
• Epoxy (or hot glue)

Build It

Click the image for a closer look.

1. Solder gas sensor breakout boards to gas sensors. Orientation doesn’t matter, just be sure that the silkscreen (aka labels) are facing down so that you can read them (had to learn that one the hard way..). Solder wires to the gas sensor breakout board.

2. Solder three voltage regulators to the PCB board. For each regulator, connect positive battery output to the regulator input, and connect middle voltage regulator pin to ground.

3. Connect the LPG (MQ6) and Methane (MQ4) sensors.

   For each sensor:

   1. Connect H1 and A1 to the output of one of the voltage regulators (recommended to use an electrical connector).
   2. Connect GND to ground.
   3. Connect B1 to Photon analog pin (LPG goes to A0, Methane to A1)
   4. Connect a 4.7 kΩ resistor from B1 to ground.

4. Connect the CO (MQ7) gas sensor.

   Aside: The MQ7 sensor requires cycling the heater voltage (H1) between 1.5V (for 90s) and 5V (for 60s). One way to do this is to use a relay triggered by the Photon (with the aid of a MOSFET and potentiometer) – when the relay is not powered, the voltage across H1 is 5V, and when the relay is powered the voltage across H1 is ~ 1.5V.

   1. Connect GND to ground.
   2. Connect B1 to Photon analog pin (A2). Connect 4.7 kΩ resistor from B1 to ground.
   3. Connect A1 to third voltage regulator output (5V source).
   4. Connect Photon 3.3V pin to positive relay input.
   5. Connect Photon Digital Pin D7 to left MOSFET pin, and a 10 kΩ resistor to ground.
   6. Connect middle MOSFET pin to relay ground pin. Connect right MOSFET pin to ground.
   7. Connect relay Normally Open (“NO”) pin to H1, and the Normally Closed (“NC”) pin to middle potentiometer pin.
   8. Connect right potentiometer pin to ground, and left pin to H1.
   9. Adjust potentiometer resistance until it changes the relay output to ~ 1.5V when the relay receives power.

5. Connect an LED and 10 kΩ resistor to each of the Photon digital pins D0, D1, and D2. Connect buzzer to Photon digital pin D4.

6. Connect toggle switch between battery pack and PCB board power. Recommended to include an electrical connector for the battery pack to make it easier to switch out batteries.

7. Solder wires to Photon Battery Shield breakout.

8. Connect lamp switch between LIB and Photon battery shield – recommended to use an extra JST cable for this to keep the LIB battery cable in tact (and make it easier to install the lamp switch).

9. Build a case for the electronics!

   1. Drill hole for toggle switch on case lid.

   2. Drill 3 holes in the case lid for the LED lights to shine through, and 3 holes for the gas sensors to have air contact. Adhere components on the inside of the lid.

   3. Drill hole in the side of the case for barrel jack USB cord to connect to the Photon Battery Shield.

   4. Drill two small holes on the side of the case for the lamp switch cable. Adhere lamp switch to side of case.

   5. Label the LEDs with its corresponding gas sensor on the outside of the case.

10. Check electrical connections and, if everything is good to go, coat electrical connections in epoxy or hot glue.

Calculate Gas Sensor PPM

Each of the gas sensors outputs an analog value from 0 to 4095. To convert this value into voltage, use the following equation:

Sensor Voltage = AnalogReading * 3.3V / 4095

Once you have the sensor voltage, you can convert that into a parts per million (“PPM”) reading using the sensitivity calibration curve on page 5 of the gas sensor datasheets. To do this, recreate the sensitivity curve by picking data points from the graph or using a graphical analysis software like Engauge Digitizer.

Plot PPM on the y-axis and V_RL on the x-axis, where V_RL is the sensor voltage. There is a lot of room for error with this method, but it will give us enough accuracy to identify dangerous levels of hazardous gases. Estimated error bars are around 20 PPM for the LPG and Methane sensors, and about 5 PPM for the CO sensor.

Next, find an approximate equation for the PPM vs. V_RL curve. I used an exponential fit (e.g. y = e^x) and got the following equations:

LPG sensor: PPM = 26.572*e^(1.2894*V_RL)

Methane sensor: PPM = 10.938*e(1.7742*V_RL)

CO sensor: PPM = 3.027*e^(1.0698*V_RL)

Program It

First, set up a data stream on the data.sparkfun.com service. Next, write a program to read in the analog value of each gas sensor, convert it to PPM, and check it against known safe thresholds. Based on OSHA safety standards, the thresholds for the three gases are as follows:

• LPG: 1,000 PPM
• Methane: 1,000 PPM
• CO: 50 PPM

If you want to get up and running quickly, or are new to programming, feel free to use my code! Use it as-is or modify to suit your particular needs.

language:c
// This #include statement was automatically added by the Particle IDE.
//This library is used to push data to the data.sparkfun.com server.
#include "SparkFunPhant/SparkFunPhant.h"
#include "math.h"

//This code was written by Jennifer Fox <jenfoxbot@gmail.com>
/*
 * ----------------------------------------------------------------------------
 * "THE Coffee-WARE LICENSE" (Revision 42):
 * <jenfoxbot@gmail.com>  wrote this file.  As long as you retain this notice you
 * can do whatever you want with this stuff. If we meet some day, and you think
 * this stuff is worth it, you can buy me a coffee in return.
 * ----------------------------------------------------------------------------
 */

//Variables to push data to data.sparkfun.com host -- Change publicKey[] and privateKey[]
const char server[] = "data.sparkfun.com"; // Phant destination server
const char publicKey[] = "INSERT_PUBLIC_KEY_HERE"; // Phant public key
const char privateKey[] = "INSERT_PRIVATE_KEY_HERE"; // Phant private key

Phant phant(server, publicKey, privateKey); // Create a Phant object

const unsigned long postingRate = 20000; //Post rate to data.sparkfun.com (time in milliseconds)
unsigned long lastPost = millis(); //Keeps track of posting rate


//Define analog pins on Photon to use for sensors
const int LPG = A0;
const int NG = A1;
const int CO = A2;

//Define digital pins on Photon to use for LEDs,  buzzer, and MQ7 (CO sensor) heater
const int LPGled = D0;
const int NGled = D1;
const int COled = D2;
const int buzzer = D3;
const int CORelayPin = D6;
const int COVoltPin = D7;

//Set up raw signal and PPM variables for each gas sensor
int LPGRaw;
int NGRaw;
int CORaw;

int LPGppm;
int NGppm;
int COppm;

//Set safety threshold levels for each  hazardous gas
const int  LPGthresh = 1000;
const int NGthresh = 1000;
const int COthresh = 50;


//Set variables for CO sensor (MQ7) voltage cycle
unsigned long startMillis;
unsigned long switchTimeMillis;
const int CO_5V_Interval = 60000; //60s for 5V interval
const int CO_1_5V_Interval = 90000; //90s for 1.5V interval
bool heaterInHighPhase;

void setup() {
    Serial.begin(9600);

    //Initialize LED and buzzer output pins
    pinMode(LPGled, OUTPUT);
    pinMode(NGled, OUTPUT);
    pinMode(COled, OUTPUT);
    pinMode(buzzer, OUTPUT);

    //Initialize CO sensor heater pins
    pinMode(CORelayPin, OUTPUT);
    pinMode(COVoltPin, OUTPUT);

    //Set start time (for CO sensor heater voltage)
    startMillis = millis();
    turnHeaterHigh();
}

void loop() {
    //Cycle CO sensor (MQ7) heater voltage

    if(heaterInHighPhase){
    // 5V phase - check to switch
        if(millis() > switchTimeMillis) {
        turnHeaterLow();
        }
    }
    else {
    // 1.4V phase - check to switch
        if(millis() > switchTimeMillis) {
        turnHeaterHigh();
        }
    }


    //Read in analog value from each gas sensor -- use function defined below to measure CO sensor at end of voltage cycle
    LPGRaw = analogRead(LPG);
    NGRaw = analogRead(NG);
    CORaw = measureCOSensor();

    //Caclulate the PPM of each gas sensor using the funtions defined below
    LPGppm = LPG_ppm(LPGRaw);
    NGppm = NG_ppm(NGRaw);
    COppm = CO_ppm(CORaw);

    //Serial monitor print for debugging and checking data
    Serial.println(NGRaw);
    Serial.println(NGppm);
    delay(1000);

    //Check gas sensor measurements against safety thresholds
    checkThreshold(LPGppm, NGppm, COppm);

    //Wait to post until ~ 20s has lapsed
    if (lastPost + postingRate < millis()) {
        Serial.println("Reading!");

        postToPhant(LPGppm, NGppm, COppm); //Post gas sensor readings and unit (PPM) to your data stream at data.sparkfun.com

        lastPost = millis();
    }

}

//Functions to calculate PPM from Photon analog reading
//Each equation is determined by visually picking points, plotting PPM v. V_RL, then fitting a trendline to the curve (exponential)
//Calculate LPG PPM
int LPG_ppm(double rawValue){

    double ppm = 26.572*exp(1.2894*(rawValue*3.3/4095)); //Multiply raw analog value by 3.3/4095 to convert to a voltage
    return ppm;
}

//Calculate NG PPM
int NG_ppm(double rawValue){

    double ppm = 10.938*exp(1.7742*(rawValue*3.3/4095));
    return ppm;
}

//Calculate CO PPM
int CO_ppm(double rawValue){

    double ppm = 3.027*exp(1.0698*(rawValue*3.3/4095));
    return ppm;
}


//Function to check PPM reading with maximum safe PPM threshold
//Include a margin of error (currently 10%)
void checkThreshold(int lpgppm, int ngppm, int coppm){
    int led1;
    int led2;
    int led3;

    if (lpgppm >= LPGthresh*0.9){
        digitalWrite(LPGled, HIGH);
        led1 = TRUE;
    }
    else{
        digitalWrite(LPGled, LOW);
        led1 = FALSE;
    }

    if (ngppm >= NGthresh*0.9){
        digitalWrite(D1, HIGH);
        led2 = TRUE;
    }
    else{
        digitalWrite(NGled, LOW);
        led2 = FALSE;
    }

    if (coppm >= COthresh*0.9){
        digitalWrite(D2, HIGH);
        led3 = TRUE;
    }
      else{
        digitalWrite(COled, LOW);
        led3 = FALSE;
    }

    if(led1 | led2 | led3){
        digitalWrite(buzzer, HIGH);
    }

    else{digitalWrite(buzzer, LOW);}


}

//Functions to switch heater voltage on MQ7 (CO) sensor
void turnHeaterHigh(){
  // 5v phase
  digitalWrite(COVoltPin, LOW);
  digitalWrite(CORelayPin, HIGH);

  heaterInHighPhase = true;
  switchTimeMillis = millis() + CO_5V_Interval;
}

void turnHeaterLow(){
  // 1.4v phase
  digitalWrite(COVoltPin, HIGH);
  digitalWrite(CORelayPin, LOW);

  heaterInHighPhase = false;
  switchTimeMillis = millis() + CO_1_5V_Interval;
}

//Function to read CO sensor voltage (just before switching to 1.5V)
int measureCOSensor(){
  unsigned int gasLevel = analogRead(CO);
  unsigned int time = (millis() - startMillis) / 1000;
  delay(time);

  return gasLevel;
}



//Function to post data to data.sparkfun.com host
//Many thanks to Jim Lindblom <jim@sparkfun.com> for the sample code and Phant library.
int postToPhant(int lpg, int ng, int co){

    phant.add("lpg", lpg); //Data stream field name "sensorvalue1"
    phant.add("ng", ng); //Data stream field name "sensorvalue2"
    phant.add("co", co); //Data stream field name "sensorvalue3"

    TCPClient client;
    char response[512];
    int i = 0;
    int retVal = 0;

    if (client.connect(server, 80)) // Connect to the server
    {
        // Post message to indicate connect success
        Serial.println("Posting!");

        // phant.post() will return a string formatted as an HTTP POST.
        // It'll include all of the field/data values we added before.
        // Use client.print() to send that string to the server.
        client.print(phant.post());
        delay(1000);
        // Now we'll do some simple checking to see what (if any) response
        // the server gives us.
        while (client.available())
        {
            char c = client.read();
            Serial.print(c);    // Print the response for debugging help.
            if (i < 512)
                response[i++] = c; // Add character to response string
        }
        // Search the response string for "200 OK", if that's found the post
        // succeeded.
        if (strstr(response, "200 OK"))
        {
            Serial.println("Post success!");
            retVal = 1;
        }
        else if (strstr(response, "400 Bad Request"))
        {   // "400 Bad Request" means the Phant POST was formatted incorrectly.
            // This most commonly ocurrs because a field is either missing,
            // duplicated, or misspelled.
            Serial.println("Bad request");
            retVal = -1;
        }
        else
        {
            // Otherwise we got a response we weren't looking for.
            retVal = -2;
        }
    }
    else
    {   // If the connection failed, print a message:
        Serial.println("connection failed");
        retVal = -3;
    }
    client.stop();  // Close the connection to server.
    return retVal;  // Return error (or success) code.
}

Change the following in the code:

1. Copy and paste your data stream public key to the array called publicKey[].

   const char publicKey[] = "INSERT_PUBLIC_KEY_HERE";

2.Copy and paste your data stream private key to the array called privateKey[].

`const char privateKey[] = "INSERT_PRIVATE_KEY_HERE";`

To monitor the Photon output, use the Particle driver downloaded as described in the “Connecting Your Device” Photon tutorial. Once this is installed, in the command prompt, type particle serial monitor. This is super helpful for debugging and checking that the Photon is posting data to the web.

Be a Citizen Scientist

Now we get to test and employ our gas monitor! Turn the batteries for the gas sensors on using the toggle switch, wait about 3 - 5 minutes, then turn the Photon on with the lamp switch (the gas sensor heater coils take some time to heat up). Check that the Photon is connected to WiFi (on-board LED will slowly pulse light blue) and is uploading data to the server. Also check that the gas sensor readings increase when in proximity to hazardous gases – one easy, and safe, way is to hold a lighter and/or a match close to the sensors.

Once up and running, use the sensor to monitor for dangerous gas leaks around your home, school, workplace, neighborhood, etc. You can install the sensor in one location permanently, or use it to check gas levels in different locations (e.g. SoCal..).

Educator Extension!

This project is a perfect excuse for a hands-on chemistry lesson! Use the monitor to learn the fundamentals of various gases – what kinds of gases are in our environment, how are different gases produced, and what makes some of them hazardous or dangerous.

Study the local environment and use a lil' math to record and plot LPG, Methane, and CO in specific locations over time to see how the levels change. Use the data to help determine what causes changes in the gas levels and where/when gas concentrations are the highest.

Resources & Going Further

Monitor hazardous gas concentrations around your neighborhood or city and use the results to identify problem areas and improve public safety.

Use Bluetooth, or your smartphone WiFi, to connect to the Photon and upload data to the web wherever you are!

Include other sensors, gaseous or otherwise, to create a more comprehensive environmental monitoring system.

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

Electret Mic Breakout Board Hookup Guide a learn.sparkfun.com tutorial

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

Introduction

Ready to add audio to your next project? The SparkFun Electret Microphone Breakout couples an Electret microphone (100Hz - 10kHz) with a 60x mic preamplifier to amplify the sounds of voice, claps, door knocks or any sounds loud enough to be picked up by a microcontroller’s analog to digital converter.

All in one tiny package!

The Electret Mic Breakout translates amplitude (not volume) by capturing sound waves between two conducting plates (one a vibrating diaphragm and the other fixed) in the microphone and converting them into electrical waves. These electrical signals are then amplified and picked up by your microcontroller’s ADC. In this tutorial, we will present two different projects to get you up and running with your next sound reactive project in a snap or a clap.

Materials Required

For this tutorial you will only need a few tools and components.

Added to your cart!

SparkFun RedBoard - Programmed with Arduino

In stock DEV-12757

At SparkFun we use many Arduinos and we're always looking for the simplest, most stable one. Each board is a bit different an…

$19.95

97

FavoritedFavorite59

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

24

FavoritedFavorite24

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

20

FavoritedFavorite37

Wish List

Added to your cart!

Jumper Wires Premium 6" M/M Pack of 10

In stock PRT-08431

This is a SparkFun exclusive! These are 155mm long jumpers with male connectors on both ends. Use these to jumper from any fe…

$3.95

2

FavoritedFavorite4

Wish List

Recommended Reading

If you are not familiar or comfortable with the following concepts, we recommend reading through these before continuing on with the Electret Mic BOB Hookup Guide.

• How to use a Breadboard
• What is an Arduino

Hardware Overview

Hardware

The Electret Mic Breakout Board only has three pins: VCC, GND and AUD. You can power this device from 3.3V to 5V, so it is a great compliment to most microcontroller units. For the amplification, we used Texas Instruments OPA344 rail-to-rail precision amplifier to give you maximum output swing.

Schematic

The gain of the amplifier is set by R5/R4 which is approximately 82V/V. Simulation and testing puts the gain closer to 60V/V.

Click the image for a closer look.

Frequency Response

Click the image for a closer look.

What this tells you is that you will see the same gain across the frequency spectrum that is picked up by the mic (100Hz-10KHz). The input of the amplifier is biased at ½ VCC. The very small AC voltage output by the mic rides on the DC offset and gets amplified through the OPA344. The output from the “AUD” pin is also at ½ the supply voltage, so it can be connected directly to the ADC of microcontroller. In quiet conditions, the ADC will ideally read ½ the full scale or 512 on a 10-bit converter.

Example Circuit and Code

We are going to run through a very simple project to get you started lighting an LED on the RedBoard based on the ADC values picked up by your microcontroller.

This is the Knocker. An LED will light up when a knock is detected.

Make the Following Connections

Electret Mic BOB → RedBoard

• VCC → 5V
• GND → GND
• AUD → A0 (or any analog pin)
• LED+ → 330 ohm resistor → digital Pin 9
• LED- → GND

Open the Arduino IDE and create a new project.

language:c
 /*
 * The Circuit:
 * Connect AUD to analog input 0
 * Connect GND to GND
 * Connect VCC to 3.3V (3.3V yields the best results)
 *
 *  To adjust when the LED turns on based on audio input:
 *  Open up the serial com port (Top right hand corner of the Arduino IDE)
 *  It looks like a magnifying glass. Perform several experiments
 *  clapping, snapping, blowing, door slamming, knocking etc and see where the
 *  resting noise level is and where the loud noises are. Adjust the if statement
 *  according to your findings.
 *
 *  You can also adjust how long you take samples for by updating the "SampleWindow"
 *
 * This code has been adapted from the
 * Example Sound Level Sketch for the
 * Adafruit Microphone Amplifier
 *
 */

const int sampleWindow = 250; // Sample window width in mS (250 mS = 4Hz)
unsigned int knock;
int ledPin = 9;

void setup()
{
   Serial.begin(9600);
  pinMode(ledPin, OUTPUT);
}

void loop()
{
 unsigned long start= millis();  // Start of sample window
 unsigned int peakToPeak = 0;   // peak-to-peak level

 unsigned int signalMax = 0;
 unsigned int signalMin = 1024;

 // collect data for 250 miliseconds
 while (millis() - start < sampleWindow)
 {
   knock = analogRead(0);
      if (knock < 1024)  //This is the max of the 10-bit ADC so this loop will include all readings
      {
         if (knock > signalMax)
         {
           signalMax = knock;  // save just the max levels
         }
      else if (knock < signalMin)
        {
         signalMin = knock;  // save just the min levels
         }
     }
 }
 peakToPeak = signalMax - signalMin;  // max - min = peak-peak amplitude
 double volts = (peakToPeak * 3.3) / 1024;  // convert to volts


Serial.println(volts);
 if (volts >=1.0)
 {
  //turn on LED
  digitalWrite(ledPin, HIGH);
   delay(500);
  Serial.println("Knock Knock");
 }
 else
 {
 //turn LED off
 digitalWrite(ledPin, LOW);
 }
}

Once you have loaded and run the program with your hardware hooked up, you should the LED attached to pin 9 on the RedBoard light up when you knock. Check out the WindBag Alert that uses the same code with just a few additional lines for an additional practice and project inspiration.

The Windbag Alert

Do you have a co-worker that talks too much? Do you want to alert that long-talker in your life of their offenses with the least unassuming desk ornament? Do you like literal translations of bad expressions? Then make yourself a Windbag Alert. This rude little piece of hardware will inflate a bag (one of my doggy doop-doop bags) with the air of your stolen silence.

Here the bag is deflated but the Electret Mic is listening. If ADC values are above a certain threshold for too long the bag will begin to inflate.

Here, someone has been talking for about 30 seconds. They have just a few seconds before the bag fully inflates. The fan kicking on usually stops them dead in their tracks.

But, some people, those people, don’t care. And the bag completely inflates. Alerting that person they are indeed the office Windbag.

Let’s break this thing down. This project is simply a continuation for the LED Blinking project from the previous section.

Hardware

I used a 12V computer fan, because that’s what I had laying around. You can use any fan, even disassemble a hand held cooling fan found at dollar stores. That should eliminate the need for a higher power supply and the fan (+) would be attached to 5V and the source (Emitter) of the transistor would be connected to GND on the Arduino.

I used an old SparkFun box as my project enclosure, which sits on my power supply on my workbench. I wrapped a plastic bag around the computer fan using electrical tape. There is about ½" of space between the box top and fan. I used standoffs there. Make sure there is enough air flow.

Software

language:c
const int sampleWindow = 250; // Sample window width in mS (250 mS = 4Hz)
unsigned int sample;
int Wind = 9;

void setup()
{
  Serial.begin(9600);
  pinMode(Wind, OUTPUT);
}

void loop()
{
unsigned long startMillis= millis();  // Start of sample window
unsigned int peakToPeak = 0;   // peak-to-peak level

unsigned int signalMax = 0;
unsigned int signalMin = 1024;

// collect data for 1 second
while (millis() - startMillis < sampleWindow)
{
      sample = analogRead(0);
    if (sample < 1024)  //This is the max of the 10-bit ADC so this loop will include all readings
    {
         if (sample > signalMax)
        {
            signalMax = sample;  // save just the max levels
         }
         else if (sample < signalMin)
         {
            signalMin = sample;  // save just the min levels
         }
      }
   }
  peakToPeak = signalMax - signalMin;  // max - min = peak-peak amplitude
 double volts = (peakToPeak * 3.3) / 1024;  // convert to volts


Serial.println(volts);
if (volts >=0.5)
{
    //turn on FAN
    digitalWrite(Wind, HIGH);
delay(1000);
  digitalWrite(Wind, LOW);
delay(75);
  digitalWrite(Wind, HIGH);
delay(75);
  digitalWrite(Wind, LOW);
delay(75);
  digitalWrite(Wind, HIGH);
delay(75);
  digitalWrite(Wind, LOW);
delay(75);
  digitalWrite(Wind, HIGH);
delay(75);
   }
  else
  {
  //turn FAN off
 digitalWrite(Wind, LOW);
 }
}

I suggest playing with the delays so you can finely tune your machine to suit your needs.

Resources and Going Further

A quick Google search for “Electret Mic Breakout” will get you going for any type of project you may want to create. Here are a few of my favorites from Instructables.

If you need to add sound to your next project but need something a little more sensitive, robust or a little more useful, I recommend the SparkFun Sound Detector.

Documents

• OPA344 Data Sheet
• Electret Condenser Microphone Data Sheet
• Electret Mic Breakout GitHub Repo

For more audio fun, check out these other great SparkFun tutorials:

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

Battery Babysitter Hookup Guide a learn.sparkfun.com tutorial

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

Introduction

The SparkFun Battery Babysitter is an all-in-one single-cell lithium polymer (LiPo) battery manager. It’s half battery-charger, half battery monitor, and it’s all you’ll ever need to keep your battery-powered project running safely and extensively.

Added to your cart!

SparkFun Battery Babysitter - LiPo Battery Manager

In stock PRT-13777

The SparkFun Battery Babysitter is an all-in-one single-cell Lithium Polymer (LiPo) battery manager. It’s half battery char…

$19.95

FavoritedFavorite11

Wish List

The Battery Babysitter features a pair of Texas Instruments LiPo-management IC’s: a BQ24075 battery charger and a BQ27441-G1A fuel gauge. The BQ24075 supports adjustable charge rates up to 1.5A, as well as USB-compliant 100mA and 500mA options. It also features power-path management, guaranteeing reliable power to your project.

The self-calibrating, I²C-based BQ27441-G1A measures your battery’s voltage to estimate its charge percentage and remaining capacity. The chip is also hooked up to a current-sensing resistor, which allows it to measure current and power! It’s a handy IC to have, especially if you ever need to keep an extra eye on your project’s power draw.

Suggested Materials

You’ll need a few components, accessories, and tools to get the Battery Babysitter up-and-running. The wishlist below includes all of the materials we use in this tutorial:

You can swap the RedBoard out for any Arduinio-compatible development board. Regardless of whether it runs at 3.3V or 5V, 8MHz or 16MHz, any Arduino should work with the Battery Babysitter’s fuel gauge IC.

Likewise, just about any single-cell lithium-polymer battery should work as well. The Battery Babysitter’s charger can be set as low as 100mA or as high as 1.5A, so if your batteries are best charged at 1C, look for LiPo’s with capacities ranging from 100mAh to 1500mAh.

Added to your cart!

Polymer Lithium Ion Battery - 400mAh

In stock PRT-10718

This is a very small, extremely light weight battery based on the new Polymer Lithium Ion chemistry. This is the highest ener…

$6.95

17

FavoritedFavorite18

Wish List

Added to your cart!

Polymer Lithium Ion Battery - 110mAh

In stock PRT-13853

This is a very small, extremely light weight battery based on the new Polymer Lithium Ion chemistry. This is the highest ener…

$4.95

FavoritedFavorite1

Wish List

Added to your cart!

Polymer Lithium Ion Battery - 850mAh

In stock PRT-00341

These are very slim, extremely light weight batteries based on the new Polymer Lithium Ion chemistry. This is the highest ene…

$9.95

9

FavoritedFavorite7

Wish List

Added to your cart!

Polymer Lithium Ion Battery - 1000mAh

In stock PRT-13813

These are very slim, extremely light weight batteries based on the new Polymer Lithium Ion chemistry. This is the highest ene…

$9.95

FavoritedFavorite2

Wish List

Finally, you’ll need a 5V supply to charge the battery, or just connect a USB cable into the on-board USB connector.

Suggested Reading

If you want to read up on some of the theories and concepts that the Battery Babysitter builds upon, check out some of these tutorials before continuing on:

Hardware Overview

For quick reference, here is an annotated diagram of the Battery Babysitter’s most prominent features, connectors, and control circuitry:

Below is a quick summary of the most significant components of the board. We’ll go more in-depth on charging, powering, and gauging in the sections that follow.

Charge Input(s)

As a primary source for battery-charging, the Battery Babysitter provides a micro-B USB port. This USB connector is only used to charge the battery – it will not show up as a USB device or pass any data through the port. (D+ and D- connectors are broken out to test points, though, if you want to change that.)

Alternatively, the External Charge Input port can be connected to any power supply between 4.35 and 6.4V. Keep in mind that the supply may be asked to source upwards of 1.5A, if the charge rate is set that high.

For more information on these two supply inputs, refer to the Battery Charging section of this guide.

Output Power and I²C Interface Headers

On the opposite side of the board sits the end goal of the Battery Babysitter: the voltage supply output. The voltage of this output supply will fall somewhere between 3V and 5.5V, depending on the state of your battery and/or presence of a charge supply. You can connect the rest of your system up to this supply output. For more information on the supply output header, refer to the Power-Path Management section of this guide.

Adjacent to that supply output is the BQ27441-G1A LiPo fuel gauge’s I²C interface. In addition to the standard power and SDA/SCL pins, this header also includes a programmable interrupt output: GPOUT. For more on these pins, and the BQ27441’s I²C interface, check out the LiPo Fuel Gague section.

System Output Enable – ON/OFF Switch

The Battery Babysitter’s ON/OFF switch toggles the “SYSOFF” pin of the BQ24075. It allows you to disconnect the battery from the system output– effectively controlling power to a load when the Babysitter is in battery-powered operation.

There are some “gotcha’s” to look out for with this switch:

• To enable charging, the switch must be in the ON position. Battery charging will be disabled if the switch is off.
• If a charge supply is connected – whether it’s USB or external – the system output voltage will be enabled, regardless of the state of the switch.

Battery Charging

To charge a LiPo battery with the Battery Babysitter, you can either connect a standard USB supply to the micro-B port

…or connect an external source to the V_IN pins. These pins include a footprint for a 2-pin 3.5mm screw terminal jack as well as standard 0.1"-pitch headers.

For normal charging conditiions, the voltage coming into either USB or V_IN should be within 4.35V and 6.4V. The BQ24075 does feature overvoltage protection, which means it can protect against input voltages up to 28V, but any voltage above about 6.6V will cause the charge controller chip to shut off and disable charging.

Charge LED Indicator

The blue CHG LED is connected to the BQ24075’s CHG output. The LED will turn on when the battery is charging and off when charging is complete.

Setting the Charge Current

The 2-position DIP switch on the Battery Babysitter allows you to easily set the charge current to one of three constant-current values. The two switches set EN1 and EN2 of the BQ24075, which the “1” and “2” labels on the switch should match up to.

With EN1 set to off and EN2 set to “ON”, the charge current will be set to 500mA.

Consult the the table below for help setting your charge current. In the table, and throughout this tutorial, a 1 is equivalent to a switch in the “ON” position.

There is also a handy table on the back of the PCB, in case you forget which charge rate you currently have set.

If you’re short on fingernails, a pair of tweezers or a small screwdriver may be helpful for toggling those tiny dip switch sliders.

Customizing the Fast Charge Current (ISET)

Like many charge-controllers, the BQ24075 uses an external resistor to configure the charge current. The chip’s ISET pin is broken out for this purpose. By default, the Battery Babysitter is set to deliver a 1.5A charge current in fast-charge mode. But, by adding a custom resistor, you can drop that down to a more custom-fit charge rate.

The equation below will determine the Battery Babysitter’s fast-charge rate, based on the resistance between ISET and ground (R_ISET):

I_CHARGE = 890 / R_ISET
- or -
R_ISET = 890 / I_CHARGE

R_ISET and I_CHARGE are in units of ohms (Ω) and amps (A), respectively.

I_CHARGE can be set to anywhere between 100mA and 1500mA, which means R_ISET should fall somewhere between 590Ω and 8.9kΩ.

If you’d like to alter the fast-charge current, begin by cutting the ISET jumper on the back of the board.

Then use the equation above to calculate an R_ISET value that will produce your desired charge current. If you want to set the charge current to 1A, for example, try to find a resistor around 890Ω. 1kΩ may be as close as you can get (with one resistor), which will set the charge current to 890mA.

Add the resistor across the unpopulated ISET pin, and solder the legs in.

Finally, make sure the DIP switch pins are set correctly (EN1 = 1, EN2 = 0).

Safety Timer (TMR)

The BQ24075 features a pair of charge timers that can may help prevent damage to a battery: a pre-charge timer and a max-charge timer.

The BQ24075’s safety timers determine how long the BQ27045 can remain in either the pre-charge or fast-charge states, before giving up and shutting down. If a timer expires, the CHG LED will blink at 2Hz, and charging will be disabled. The timer can be cleared by toggling the CE pin from HIGH to LOW.

Setting the Saftey Timers

The length of the safety timers are determined by a resistor (or lack of resistor) connected to TMR. There are three timer-configuring options:

• Disable timer: Connect TMR to ground.
• Default timer: Leave TMR open.
• Custom timer: Connect a 18kΩ to 72kΩ resistor from TMR to ground to configure the timers.

The pre-charge and max-charge timers are set according to the following equations, based on a resistance from TMR to ground – R_TMR. (The calculated times are in seconds, resistance in ohms.)

t_PRECHG = 0.048 × R_TMR
t_MAXCHG = 0.48 × R_TMR

Resistor values between 18kΩ and 72kΩ can be added to set the maximum pre-charge time between 24-36 minutes, and the max-charge timer between 240 and 360 minutes.

As with customizing charge current, if you want to make a modification to the charge timers, you first need to cut the TMR jumper, then add an external resistor between TMR and ground.

Power-Path Management

One of the BQ24075’s most unique features is dynamic power-path management (DPPM), which maintains a reliable output supply as long as either a battery or input supply (V_IN/USB) are present.

The DPPM system can throttle charge current in order to maintain a reliable output supply. In the words of TI, DPPM “reduces the number of charge and discharge cycles on the battery,” and it allows your project to “run with a defective or absent battery pack.”

Footprints for a 0.1" header, 2-pin 3.5mm screw terminal and JST PTH connector are all connected to the power path management output.

Output Voltage Range

The output of the power-path management system is broken out to the “V_OUT” pins, labeled “+” and “-”. This supply output is active as long as either a battery or input supply are connected to the Battery Babysitter. (In the case of the battery-supply, the ON/OFF switch must be ON.) The voltage will swing between 3.0V and 5.5V, depending on the charge of your battery and the voltage/pressence of the input supply.

If the Battery Babysitter is powered by only a battery, the output voltage will usually be 50-100mV below the battery voltage. For example, a battery producing 3.75V might produce an output between 3.65 and 3.74V. A larger load, pulling more current, will create a bigger voltage drop.

If a 5V USB supply and battery are connected to the Babysitter, the output voltage will be somewhere between 3V and 5V, depending on the load, and charge percentage of the battery. If the battery is at, or near, full charge, the output could be as high as 5V. As the load increases, the voltage at the output supply will drop as low as 4.4V.

If your battery is charging, the output voltage will be around 4.3V, but may drop as low as 3.8V depending on the load.

Any load connected to V_OUT should be able to handle a 3-5.5V input, but expect 3.6-5V assuming a healthy battery and USB supply. It's usually a good idea to regulate the output voltage of the Battery Babysitter to 3.3V, or find something that operates within the standard LiPo voltage range.

Power Path Operation Modes

The DPPM system is designed to protect a non-self-regulating charge supply by enforcing a limit on how much current that supply can source. Just as EN1 and EN2 are used to set charge current, they also control the input current limit:

These limits help guarantee that your input supply will not be tasked with sourcing more current than it’s capable of.

If both V_IN (USB or external) and a battery are connected and a load is pulling more than the set input current limit, the pair of supplies will supplement each other– the input supply will source current to the set limit (100mA, 500mA, etc.), and the battery will take care of the rest.

Input Current Limit (ILIM)

An external resistor between the ILIM pin and ground is used to set the maximum input current in DPPM mode. This value is set by the following equation, where resistance is in ohms and current is in amps:

I_LIM = 1550 / R_ILIM

The Battery Babysitter populates this pin with a 1.1kΩ resistor, which sets the input current limit in DPPM mode to about 1.4A.

To customize this resistance value, as with the other charger features, cut the ILIM jumper on the back of the board. Then, calculate your desired current/resistance values, and populate a PTH resistor into the available ILIM resistor footprint.

LiPo Fuel Gauge

The Battery Babysitter’s other predominant component is a BQ27441-G1A LiPo fuel gauge. With a highly sensitive analog-to-digital converter, it can measure a battery’s voltage (mV) and state-of-charge (%). Plus, thanks to an external sense resistor, it can measure current (mA), power (mW), and even estimate remaining capacity (mAh).

The BQ27441 supports I²C, a two-wire serial interface, as its controlling interface. I²C is used to configure the fuel gauge with characteristics like full capacity, and it’s used to read out all of the gauge’s battery measurements.

The fuel gauge also features a programmable interrupt output, broken out to the GPOUT pin. This pin can be configured as either active-high or active-low, and it can be set to trigger when the battery charge falls below a set percentage or when the percentage changes by a set integer value.

Powering the BQ27441-G1A

The BQ27441-G1A LiPo fuel gauge is powered by the LiPo battery. To power its core logic, the fuel gauge regulates the battery voltage down to 1.8V. The 1.8V OUT pin on the side of the Battery Babysitter breaks out the fuel gauge’s 1.8V output supply, but it is meant as more of a voltage reference than a power source.

Although the BQ27441-G1A runs at 1.8V, its I²C and GPOUT pins are tolerant up to 5V. That’s where the VPU pin comes into play. The VPU pin, short for V_PULL-UP, is the pull-up voltage for the open-drain SDA and SCL pins. This pin is an input, and should be connected to the operating voltage of your system – 3.3V, 5V, etc. A voltage supply is required on this pin, unless you have pull-up’s on the I²C bus elsewhere in your project.

Example Hardware Hookup

There are a variety of ways to integrate the Battery Babysitter into your project. Below is an foundational example circuit, which takes care of I²C wiring, but does not power the Arduino from the Babysitter.

Optionally, a wire can be connected from the Battery Babysitter’s V_OUT pin to the Arduino’s 5V pin – powering the Arduino at somewhere between 3.4 and 5.5V. These pins should only be connected when the Arduino is not connected to USB, though; while you’re testing out the I²C interface and using the serial monitor for debugging, it’s best to leave that wire out.

BQ27441 Arduino Library

To make interfacing with the Battery Babysitter’s BQ27441 LiPo fuel gauge as painless as possible, we’ve written an Arduino library to abstract away the unique I²C interface and register interfacing. Head over to the SparkFun_BQ27441_Arduino_Library GitHub repository to download the latest, greatest release, or click the button below to download the library in a ZIP file.

Download the SparkFun BQ27441 Arduino Library!

For help installing the library, check out our Installing an Arduino Library tutorial.

Start Simple: BQ27441_Basic Example

The library includes a handful of examples, which you’re free to explore. To begin, we recommend BQ27441_Basic. Click through File>Examples>SparkFun BQ27441 LiPo Fuel Gauge Arduino Library>BQ27441_Basic to open it up.

Then set your Arduino port/board, and upload away!

After uploading, open up your serial monitor, and set the baud rate to 115200 bps. You should see the Arduino initialize the fuel gauge, and then begin printing some battery stats:

The basic example prints state-of-charge (%), battery voltage (mV), average current draw from the battery (mA), remaining and full capacities (mAh), average power draw on the battery (mW), and the battery’s state-of-health (%). The current and power draws will be negative when the battery is sourcing current, and positive when it’s charging. Try hooking up some power resistors to the Battery Babysitter’s output, or start charging to see how these numbers change.

You can adjust the full capacity value by configuring the BATTERY_CAPACITY variable at the top of the example sketch. For example, by assigning that variable a value of 850, the sketch configures the BQ27441 to calculate the battery state assuming an 850 mAh battery is connected to it.

Using the BQ27441 Arduino Library

Here is a quick primer to incorporating the BQ27441 library into a sketch of your own. First, set the library up by including it. Then – usually in the setup() function – call lipo.begin(). You can check the return value of the begin function, to make sure the Battery Babysitter is connected correctly.

language:c
#include <SparkFunBQ27441.h>

void setup()
{
    Serial.begin(115200);
    if (!lipo.begin())
    {
        Serial.println("Error: Unable to communicate with BQ27441.");
        Serial.println("  Check wiring and try again.");
        Serial.println("  (Battery must be plugged into Battery Babysitter!)");
        while (1) ;
    }
    Serial.println("Connected to BQ27441!");
}

Next, you may want to set the battery’s full capacity using the lipo.setCapacity() function:

language:c
lipo.setCapacity(1000); // Configure BQ27441 to assume a 1000 mAh battery

Expect a short delay – 1-to-2 seconds – before your Arduino completes the execution of this function. The Battery Babysitter’s capacity setting will remain at the set value until it loses power (usually when a battery is disconnected or fully discharged).

After those quick function-calls, you’re ready to read some battery statistics. You can use these functions to read state-of-charge, voltage, remaining capacity, current, power, and more.

language:c
unsigned int soc = lipo.soc(); // Read state-of-charge (in %)
unsigned int volts = lipo.voltage(); // Read voltage (in mV)
int current = lipo.current(AVG); // Read average current (in mA)
unsigned int capacity = lipo.capacity(REMAIN); // Read remaining capacity (in mAh)
int power = lipo.power(); // Read power consumption (in mW)
int health = lipo.soh(); // Read state-of-health (in %)

Now, take those values, and do something with them! Maybe that something is as simple as displaying the battery statistics on a MicroView.

Resources & Going Further

The SparkFun Battery Babysitter and the BQ27441 Arduino Library are both open-source, so there are plenty of resources to go around, including:

• SparkFun Battery Babysitter GitHub Repository
• SparkFun Battery Babysitter Eagle Files
• SparkFun Battery Babysitter Schematic
• SparkFun BQ27441 LiPo Fuel Gague Arduino Library GitHub Repository

If you’d like to learn more about the BQ27441-G1A LiPo Fuel Guage, TI has published an excellent 59-page Technical Reference manual, plus, of course, there’s the datasheet.

For more information on the BQ24075 LiPo charger, the datasheet should have all of the information you might need.

The Battery Babysitter can be incorporated into just about any LiPo-powered project out there. If you’re looking for a little project-inspiration, check out some of these great SparkFun tutorials:

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

Experiment Guide for the Johnny-Five Inventor's Kit a learn.sparkfun.com tutorial

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

Introduction to the Johnny-Five Inventor's Kit

Added to your cart!

Johnny-Five Inventor's Kit

In stock KIT-13847

The Johnny-Five Inventor's Kit (J5IK) is your go-to source for developing projects using the Tessel 2 and the Johnny-Five pro…

$124.95

FavoritedFavorite2

Wish List

The Johnny-Five Inventor’s Kit you have in front of you is your toolkit, and this Experiment Guide is your map. We’re going to dive into the world of embedded electronics, JavaScript, the internet, and the way they come together as the “Internet of Things” (IoT). The Johnny-Five JavaScript framework provides a beginner-friendly way to start building things—quickly. This guide contains all the information you need to successfully build the circuits in all 14 experiments. At the center of this guide is one core philosophy: that anyone can (and should) play around with basic electronics and code.

When you’re done with this guide, you’ll have the know-how to start creating your own projects and experiments. You can build robots, automate your home, or log data about the world around you. The world, in fact, will be your hardware-hacking oyster. Enough inspirational sentiment — let’s get building!

Included Materials

Here are all of the parts in the Johnny-Five Inventor’s Kit for the Tessel 2 (J5IK):

• Tessel 2— The Tessel 2 Single-Board Computer (SBC)
• USB-A to USB micro B— for connecting your computer to the Tessel 2
• Wall Charger (5V, 1A)— Gotta power the Tessel 2 somehow! This charger makes it easy to power your projects!
• Breadboard— This perforated grid is the ticket to easy experimentation with circuits.
• Carrying Case— Take your kit anywhere with ease!
• Jumper wires— These multi-colored wires with pins on each end making connecting things together a breeze.
• Rainbow Pack of LEDs— LEDs are indispensable. Here’s a whole rainbow of ‘em.
• 100 Ohm Resistors— These are just about right for using with LEDs at 3.3V (the voltage we’ll be using for the circuits in this guide)
• 10K Ohm Resistors— These make excellent pull-ups, pull-downs and current limiters (don’t worry if you haven’t seen these terms before)
• Photocell— A sensor that detects ambient light. Also called a photoresistor. Perfect for detecting when a drawer is opened or when nighttime approaches.
• 10KΩ Trimpots— Also known as a variable resistor or a potentiometer, this is a device commonly used to control volume and contrast (it usually has a dial or a slider), and makes a great general user control input.
• Red, Blue, Yellow and Green Tactile Buttons— These fun-to-press buttons give you several colors to choose from.
• RGB LED— Why use an LED that can only be one color when you can have any color?
• SPDT (Single-Pole, Dual Throw) Switch— It’s a switch! You slide it back and forth, and it fits into a breadboard just great.
• Magnetic Door Switch— A mountable magnetic switch used in home automation and security. Great for detecting when a door or drawer is opened!
• BME280 Atmospheric Sensor Breakout— A sensor for detecting temperature, pressure and humidity. It communicates using the I2C serial communication protocol. The header pins are soldered on for you, which makes connecting this to your project nice and easy.
• Soil Moisture Sensor— The name describes it pretty well!
• SparkFun Motor Driver— This nifty little board is perfect for controlling the speed and direction of up to two separate motors.
• Hobby Gearmotor Set— A set of hobby level motors (two of ‘em) with gearboxes set to 120 RPM.
• 7 Segment Display— It’s an LED that lets you display numerals via the combination of lit-up segments, just like an alarm clock from the 1980s!
• 3.3V 16x2 White on Black LCD— This LCD can display 16 characters on two lines with a snazzy white-on-black background appearance. It operates at 3.3 volts (this is the voltage that the Tessel 2 is most comfortable with).
• 74HC595 Shift Register— An integrated circuit (IC) that allows you to increase the number of inputs and outputs you can control from a microcontroller.

Suggested Reading

While you can get through this guide without doing any outside reading, the following tutorials cover the essential core of electronics and circuits and are super useful:

Open Source!

At SparkFun, our engineers and educators are constantly improving kits such as these and coming up with new experiments. We would like to give attribution to Rick Waldron and Bocoup, as he originally started the development of Johnny-Five many years ago. The contents of this guide are licensed under the Creative Commons Attribution Share-Alike 4.0 Unported License.

To view a copy of this license visit this link, or write: Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.

About the Tessel 2

The Tessel 2 is an open-source development board. It runs JavaScript and supports npm, which means scripts to control it can be built with Node.js. It’s a platform for experimenting, tinkering, prototyping and producing embedded hardware, perfect for the Internet of Things.

OK, So What’s a Development Board?

Development boards are platforms for prototyping and building embedded systems. At the heart of (most) development boards is a microcontroller, which combines a processor and memory with IO capabilities. Microcontrollers like the one on the Tessel 2 provide a collection of GPIO (general-purpose IO) pins for connecting input and output devices to. The pins on the microcontroller itself—a chip—are small, too small for human fingers to work with easily (plus you’d need to solder things to them). Development boards instead connect these GPIO pins to pin sockets that are easy to plug things into.

Other common features of boards play a supporting role: connections for programming and communicating with the board, status lights and reset buttons, power connections.

More powerful boards like the Tessel 2 and the well-known Raspberry Pi are sometimes also called single-board computers (SBCs).

Tessel 2’s Features

The Tessel is a mighty little board. Some of Tessel 2’s specifications include:

• 2 USB ports (you can connect cameras or flash storage, for example)
• 10/100 ethernet port
• 802.11 b/g/n WiFi
• 580MHz Mediatek router-on-a-chip (you can turn your Tessel 2 into an access point!)
• 48MHz SAMD21 coprocessor (for making IO zippy)
• 64MB DDR2 RAM, 32MB of flash (lots of space for your programs and stuff)

Working with Tessel 2

Tessel has a set of command-line interface (CLI) tools for setting up and working with the Tessel 2 board. You’ll install these and do a one-time set-up provisioning of your Tessel.

You can write scripts for the Tessel 2 in any text editor, using JavaScript and including npm modules as you desire. A one-line terminal command deploys and executes your script on the Tessel.

Inputs and Outputs

There are two primary sets of pins on the Tessel 2: Port “A” and Port “B”. Each port has 10 pins: two pins for power (3.3V and ground) and eight GPIO pins.

Some pins support different features. You can read details about every Tessel 2 pin, or just keep that info handy for reference later.

Powering the Board

There are multiple ways to power the Tessel 2. We’ll start by using the included USB cable.

Over USB

Connecting to the board directly with USB will allow you to easily modify any circuits and re-deploy code from the comfort of your desk, without having to retrieve your project. This is also handy when you don’t have access to the local network (for deploying code over WiFi).

USB Wall Charger

Once you have completely set up and provisioned your Tessel 2, you can deploy code through your local WiFi network. At some point you’ll itch to make your Tessel free of wires and tethering, but it still needs power. We supplied a 5V USB charger in the J5IK so you can place your project in a semi-remote location around your home or office and deploy code from anywhere on your local network.

USB Battery Pack

USB Battery packs are becoming quite popular as swag and giveaways at events. We collect them like candy because they allow us to power projects with minimal consideration to power management circuitry. If you have one of these handy, just use the included USB cable to plug the Tessel 2 into your battery and away you go! That’s it, simple as pie.

Ports and Pins on the Tessel 2

The Tessel 2 has two IO modules, Port A and Port B. Each port has 8 GPIO (general-purpose I/O) pins. Here’s their naming conventions and what all of them do.

Pin Naming Conventions

The pins on the Tessel 2 are broken out across the two different ports. The naming conventions in code will be referenced with the port letter first and then the pin number of that port. The port letter is not case sensitive! As an example, the first pin on port A would be referred to as pin a0 or A0. Use this table as a reference in terms of the naming of pins.

Pin Capabilities: What Each Pin Can Do

The pins of each port have different functionalities available to them.

Other things to know:

• All eight numbered pins, both ports (16 total), can be used as GPIO.
• Pins 4 and 7 on Port A support analog-to-digital input. All pins on Port B support analog input.
• Pins 5 and 6 on both ports support Pulse-Width Modulation (PWM).
• Pins 0 and 1 on both ports can be used for I2C serial communication.
• Serial TX/RX (hardware UART) is available on both port, pins 5 (TX) and 6 (RX).
• Port B, Pin 7: Supports digital-to-analog conversion (DAC)

The two ports are essentially duplicates, with the following exceptions:

• Port B: All numbered pins can be used for analog input.
• Port B, Pin 7: Supports DAC.

For exhaustive details, see the pin functionality reference chart below:

Software Installation and Setup

Let’s prepare the software side of things so you’re ready to build stuff in this guide. You’ll need to have a few things installed, and you’ll want to set up a project area for your JavaScript programs. So, don’t skip ahead!

Installing Needed Things

You’re going to need:

• A text editor
• Node.js
• A terminal application

Installing a Text Editor: Atom

You will need a text editor in which to edit and save your JavaScript files. This means a plain text editor, not a Word document. If you’ve already got one, like SublimeText, Notepad++, vim, etc., groovy. If not, go ahead and install Atom.

You can use any text editor you like if you already have on installed and are up and running. But, if you have never used a text editor to write JavaScript, HTML, etc. we recommend using Atom. Atom is a free and open source text editor that works on all three major operating systems, is light weight and when you get comfortable…it’s hackable!

Download Atom by heading to the Atom website.

Installing Node.js

Node.js is a JavaScript runtime, that is, it’s software that can execute your JavaScript code. Node.js has special features that support some of the best potentials of the JavaScript programming language, like event-driven, non-blocking I/O. npm is Node’s package manager. It’s a giant repository of encapsulated bits of reusable useful code, called modules, that you can use in your programs. npm will get installed for you when you install Node.js.

Installing Node.js is a straightforward download-and-double-click process. Head on over to the Node.js website. Heads up: You’ll want to select the “LTS” version for download (LTS stands for long-term support). At time of writing, LTS is v4.4.5:

Using a Terminal: Command Line Basics

Working with the Tessel is just like doing web development. But if you’re not familiar with web development, you might want to take a minute or two to get comfortable with some key tools of the trade: the command line (the “terminal”, where you execute commands) and the text editor, where you will work on and save your programs. Tessel’s site has a great resource to help you get started with terminal.

In the context of this tutorial, things that should be run in the command line look like this:

hello i am a command line command!

You’ll see this when you get to the first experiment. But, don’t skip ahead—you’ll need the tools we install in the next step.

Setting up a Project Working Area

Take a moment to set up a working area (directory) where you can put the programs for your Johnny-Five Inventor Kit (J5IK). You’ll also need to initialize the new project with npm and install needed npm modules for both Johnny-Five and Tessel.

You can accomplish all of this by typing (or copying and pasting) the following commands in a terminal:

mkdir j5ik;
cd j5ik;
npm init -y;
npm install johnny-five tessel-io;

Running these commands will generate some output in your terminal. If everything goes smoothly, you’ll see some output about edits to a package.json file, and some additional output as npm installs the needed modules. You may also see a few WARN statements about missing description or repository field. Don’t worry—nothing’s broken.

An example of the kind of output you’ll see (though yours will differ in some particulars):

Wrote to /your/path/j5ik/package.json:
{"name": "j5ik","version": "1.0.0","description": "","main": "index.js","scripts": {"test": "echo \"Error: no test specified\"&& exit 1"
  },"keywords": [],"author": "","license": "ISC"
}

j5ik@1.0.0 /your/path/j5ik
├── johnny-five
└── tessel-io
npm WARN j5ik@1.0.0 No description
npm WARN j5ik@1.0.0 No repository field.

Hardware Installation and Setup

It’s time to get your Tessel 2 set up. The steps we’ll walk through now include:

1. Installing the t2-cli software tool
2. Connecting the Tessel 2 with a USB cable
3. Finding, renaming and provisioning the Tessel
4. Updating the Tessel’s firmware

Installing the Command-Line Tool

You interact with the Tessel 2 using a command-line interface (CLI) tool called t2-cli. This tool can be installed using npm (Node.js' package manager, which gets installed automatically with Node.js).

Type the following into your terminal:

npm install t2-cli -g

The -g piece of that command (a flag) is important—this will tell npm to install the package globally, not just in the current project or directory.

The installation will take a few moments, and you will see a bunch of stuff scroll by that looks sort of like this:

Troubleshooting

Note: If you see any warnings or errors when trying to install t2-cli, the first thing to check is your Node.js version. To do this, type the following command in your terminal:

node –version

You’re aiming for the LTS (long-term support) version of Node.js, which at time of writing is v4.4.5. Learn more about how to upgrade and manage node versions with nvm.

Setting up your Tessel!

Now, time to get your hands dirty and get things up and running! Connect your Tessel 2 to your computer and give it about 30 seconds to boot up.

Once your Tessel 2 has booted (the blue LED will be steady instead of blinking), type the following command into your terminal:

t2 list

The t2-cli tool will look for connected Tessels. Tessels can be connected by USB or over WiFi, but for now, it should spot your single, USB-connected Tessel. You’ll see something like this:

Success! You can now communicate with your Tessel 2!

Naming Your Tessel 2

Giving your Tessel 2 a name is not required to use it, but it’s fun and friendly. To name your Tessel 2 use the following command:

t2 rename [name]

For example we renamed our Tessel 2 “Bishop” by typing following.

t2 rename bishop

The t2-cli tool will respond with the following output:

Double-check it!

t2 list

Connecting Your Tessel 2 to the Internet

If you’ve ever configured and connected other embedded systems to the Internet, the simplicity of this should make you grin.

You’ll need to be connected to your local WiFi network first. To connect your Tessel to a WiFi network, type the following command into your terminal:

t2 wifi -n [SSID] -p [password]

Replace [SSID] with the name of your wireless network (careful! It’s case-sensitive) and [password], well, I be you can figure that out!

You’ll see some output that looks something like the following:

INFO Looking for your Tessel...
INFO Connected to bishop.
INFO Wifi Enabled.
INFO Wifi Connected. SSID: your-network-ssid, password: your-network-password, security: psk2

That’s it! Simple as pie!

You can do a bunch of other stuff with your Tessel and network connectivity. Tessel’s website has in-depth documentation on WiFi connection options.

Troubleshooting

Note: Like Kindles and some Androids, Tessel 2’s don’t play nice with 5GHz WiFi networks.

Provision Your Tessel 2

Your Tessel exists, has a name, and is connected to your WiFi network. The next step is to provision the Tessel. That creates a secure, trusted connection between your computer and the Tessel, whether it’s connected by wire or over the air (WiFi). You’ll need to do this before you can deploy code to the Tessel.

Type the following command in your terminal:

t2 provision

You’ll see something like:

INFO Looking for your Tessel...
INFO Connected to bishop.
INFO Creating public and private keys for Tessel authentication...
INFO SSH Keys written.
INFO Authenticating Tessel with public key...
INFO Tessel authenticated with public key.

Verify it worked:

t2 list

You’ll see your Tessel twice! That’s because it’s connected via USB and WiFi.

INFO Searching for nearby Tessels...
USB bishop
LAN bishop

Great! We have one last setup step.

Update Your Tessel 2

The Tessel community is constantly improving the software and firmware for the Tessel 2. It’s likely that in the time between your Tessel 2’s manufacture and now, the firmware has been updated. To update your Tessel, type the following command in your terminal:

t2 update

The update process can last some time, so I would recommend a snack break or checking up on some news feeds while this happens. When the update is finished you will get the command prompt back, and you are all ready to go with your Tessel 2!

Experiment 1: Blink an LED

Introduction

Making an LED (Light-Emitting Diode) blink is the most basic “Hello, World!” exercise for hardware, and is a great way to familiarize yourself with a new platform. In this experiment, you’ll learn how to build a basic LED circuit and use Johnny-Five with your Tessel 2 to make the LED blink and pulse. In doing so, you’ll learn about digital output and Pulse Width Modulation (PWM).

Perhaps you’ve controlled LEDs before by writing Arduino sketches (programs). Using Johnny-Five + Node.js to control hardware is a little different, and this article will illustrate some of those differences. If you’re totally new to all of this — not to worry! You don’t need any prior experience.

Parts Needed

You will need the following parts for this experiment:

• 1x Tessel 2 and USB cable
• 1x Breadboard
• 1x Standard LED (Choose any color in the bag full of LEDs)
• 1x 100Ω Resistor
• 2x Jumper Wires

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

24

FavoritedFavorite24

Wish List

Added to your cart!

LED - Assorted (20 pack)

In stock COM-12062

We all know that you can never get too many LEDs. Don't worry, we've got you covered. This is a pack of basic red, yellow, bl…

$2.95

6

FavoritedFavorite22

Wish List

Added to your cart!

Jumper Wires - Connected 6" (M/M, 20 pack)

In stock PRT-12795

These are 6" long jumper wires with male connectors on both ends. Use these to jumper from any female header on any board, to…

$1.95

1

FavoritedFavorite6

Wish List

Added to your cart!

Tessel 2

In stock DEV-13841

The Tessel 2 is a development board with on-board WiFi capabilities that allows you to build scripts in Node.js. This Tessel …

$44.95

FavoritedFavorite5

Wish List

Added to your cart!

Resistor 100 Ohm 1/4th Watt PTH - 20 pack

In stock COM-13761

These are 1/4th Watt, +/- 5% tolerance PTH resistors. Commonly used in breadboards and perf boards, these 100 Ohm resistors m…

$0.95

FavoritedFavorite0

Wish List

Suggested Reading

The following tutorials provide in-depth background on some of the hardware concepts in this experiment:

• What is a Circuit?— explains what circuits are and how they work
• Voltage, Current, Resistance, and Ohm’s Law— demonstrates the vital relationships between voltage, current and resistance as described by Ohm’s Law
• LEDs (Light-Emitting Diodes)— the details on how those ubiquitous little lights work
• Resistors– Why use resistors? Learn more about resistors and why they are important in circuits like the ones in this tutorial
• Polarity– Polarity is an important characteristic to pay attention to when building circuits

Introducing LEDs

Diodes are electronic components that only allow current to flow through them in a single direction, like a one-way street. Light-Emitting Diodes (LEDs) are a kind of diode that emit light when current flows through them.

Grab an LED and take a look at it. The longer leg is called the anode. That’s where current enters the LED. The anode is the positive pin and should always be connected to current source. The shorter leg, the cathode, is where current exits the LED. The cathode is the negative pin and should always be connected to a pathway to ground. Many LEDs also have a flat spot on the cathode (negative) side.

If you apply too much current to an LED, it can burn out. We need to limit the amount of current that passes through the LED. To do that, we’ll use a resistor. When you use a resistor in this way to limit current, it is called — surprise! — a current-limiting resistor. With the Tessel 2 board, you should use a 100 Ohm resistor. We have included a baggy of them in the kit just for this reason!

If you’re curious to learn more about how voltage, current and resistance relate to one another, read this tutorial about Ohm’s Law.

Hardware Hookup

Its now the fun part! It’s time to start building your circuit. Let’s take a look at what goes into building this circuit.

Polarity

LEDs are polarized, meaning they need to be oriented in a specific direction when they are plugged in. You don’t want to plug a polarized part in backward!

On the other hand, resistors are not polarized; they’re symmetric, which means they don’t have an opinion about which way current flows across them. You can plug a resistor in facing either direction in a circuit, and it will be just fine.

Plugging Things In

When working with components like resistors, you’ll need to bend their legs at (about) 90° in order to correctly fit into the breadboard sockets. You can trim the legs shorter to make them easier to work with, if you like:

All jumper wires work the same. They are used to connect two points together. All of the experiments in this guide will show the wires with different colored insulations for clarity, but using different combinations of colors is completely acceptable.

Breadboards are vital tools for prototyping circuits. Inside the breadboard there are electrical connections between certain sockets. Power rails— columns on the left and the right of the breadboard — are electrically connected vertically, while terminal rows— rows in the middle of the breadboard — are connected horizontally (note that connections do not continue across the center notch in the breadboard).

You can read a tutorial about breadboards to learn more.

Build the LED Circuit

Each of the experiments in this guide will have a wiring diagram. They’ll show you where to plug in components and how to connect them to your Tessel 2.

Having a hard time seeing the circuit? Click on the wiring diagram for a closer look.

1. Plug the LED into the breadboard, taking care to plug the cathode into row 1 and the anode into row 2. Make sure not to plug it in backward!
2. Connect a 100Ω resistor between the LED’s cathode and ground as shown, spanning the notch in the middle of the breadboard.
3. Use jumper wires to connect the breadboard’s components to the Tessel 2: connect ground (row 1) to the Tessel 2’s Port A GND pin and source (row 2) to the Tessel 2’s Port A, Pin 5.

Using Johnny-Five to Make an LED Blink

Open your favorite code editor, create a file called led.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your led.js file:

language:javascript
var Tessel = require("tessel-io");
var five = require("johnny-five");

var board = new five.Board({
  io: new Tessel()
});

board.on("ready", () => {
  var led = new five.Led("a5");
  led.blink(500);
});

Now for the big reveal! Type — or copy and paste — the following into your terminal:

t2 run led.js

You terminal will display something like this:

And when the program starts up:

What You Should See

Your LED should be blinking:

Exploring the Code

Let’s take a deeper look at what’s going on in the led.js Johnny-Five code.

Requiring Modules

In Node.js, a program can use any number of code modules. Modules are independent chunks of functionality. The software functionality for Tessel and Johnny-Five is contained within modules. We need to tell Node.js to require those modules so that they are available to the program:

language:javascript
var Tessel = require("tessel-io");
var five = require("johnny-five");

Note: For Node.js to be able to find and use the modules, you need to use npm to install for the project. That happened when you set up your working environment—you used npm install to install both the tessel-io and johnny-five modules.

Instantiating Objects

Next, the code needs to instantiate (create) a new object that represents the Tessel 2 board, and assign it to a variable (board) so we can access it later:

language:javascript
var board = new five.Board({
  io: new Tessel()
});

This creates a new instance of a Johnny-Five Board.

Johnny-Five supports many kinds of development boards. The support for some boards is built right in to Johnny-Five, but others — including Tessels — rely on external plugins encapsulated in modules. That’s why the code requires the tessel-ionpm module. Here, we tell Johnny-Five to use a Tessel object for IO when communicating with the board.

Learn more: Working with JavaScript Objects

Listening for Events

JavaScript code statements are typically executed top to bottom, in order, until they’re “done” (the program runs to completion) and nothing is left to do. One of Node.js' great powers is to allow programmers to “schedule” things to happen outside of this simple sequential-then-done flow. A program will terminate if there’s nothing left to do, but there are a number of ways to give the program something to do so that it keeps running.

Because the Tessel 2 board initialization involves hardware and I/O, it takes a few moments—considerably longer than the rest of the led.js script would take to execute. The initialization of the board won’t get in our program’s way—it happens asynchronously, allowing our script to keep executing statements without blocking—but we need to schedule something to happen when the board is ultimately ready.

language:javascript
board.on("ready", function() {
  // ...this will execute when the board emits the `ready` event
});

The code snippet defines a function that will get executed when (‘on’) the board emits the ready event.

Next we need to fill in what that function should do when the board is ready to go.

Learn more: In-depth: JavaScript’s Concurrency Model and Event Loop

Blinking the LED

Once the board is ready, it’s time to configure an LED on Port A, Pin 5 and then tell that LED to blink. In Johnny-Five, that looks like this:

language:javascript
board.on("ready", function() {
  var led = new five.Led("a5");
  led.blink(500);
});

Instances of Johnny-Five’s Led class have some handy tools (attributes and methods) for doing LED things—for example, blink..

This code creates a new Led object and tells it what pin to use (in this case "a5"). Then it tells the LED to blink every 500 milliseconds (half a second). That means the LED will cycle 500ms off, then 500ms on.

Comparing Node.js + Johnny-Five With Arduino Sketches

The structure of Node.js scripts written with Johnny-Five differs from how Arduino sketches are written in the Arduino Programming Language. The following is an example sketch in the Arduino Programming Language that would make an LED blink on and off (assuming that LED was connected to pin 13 of a theoretical board):

language:cpp
void setup() {
  pinMode(13, OUTPUT); // Set up pin 13 as an OUTPUT pin
}

void loop() {
  digitalWrite(13, HIGH);   // turn the LED on (HIGH puts voltage on the pin)
  delay(500);               // wait for a half second
  digitalWrite(13, LOW);    // turn the LED off by making the voltage LOW
  delay(500);               // wait for a half second
}

Arduino sketches have two sections:

1. setup: runs once and is a place for configuring pins and initializing stuff
2. loop: runs over and over and over and over

Another thing you’ll notice is that Arduino code is lower-level, meaning that there are fewer abstractions of specific hardware details. Instead of having an LED object that can do LED-like things (blink, pulse, fade, etc.), you interact directly with the digital pin and write LOW and HIGH states to it.

Between those digital writes, you tell everything to stop and wait for 500 milliseconds (delay). And the thing about delay is: it stops everything. It’s a process-blocking operation. Nothing else can happen while delay, well, delays.

In terms of code complexity, the difference between Johnny-Five and the Arduino Programming Language isn’t too significant when you’re just blinking an LED, but when it comes to pulsing an LED, Arduino sketch code starts getting more complicated.

Pulsing an LED

Now that we’ve covered the basics and some of the lower level technical aspects of Johnny-Five, let’s write a program that pulses the LED. Instead of blinking the LED on and off, pulsing fades the LED smoothly from off to on, and then from on to off again.

Pulse Width Modulation (PWM)

The state of a digital output pin can only be one of two things: LOW or HIGH. That means, at any given exact moment, an LED connected to the pin can only be off or on. We fool the eye into thinking an LED is dimmed to, say, half brightness by using a technique called Pulse Width Modulation (PWM)

With PWM, the pin can be switched between HIGH and LOW very quickly, causing the LED turn on and off, too. This cycle between on and off happens too fast for the human eye to discern. The percentage of time that the pin (with the LED attached) is HIGH (on) over a given period is its duty cycle. A 30 percent duty cycle (on — or HIGH — 30% of the time) will make an LED look like it’s partially lit — dimmer than bright but definitely on. By adjusting the duty cycle over time, we can fake (very convincingly!) an LED fading on and off.

Only certain pins on development boards support PWM. On the Tessel 2, pins 5 and 6 on both ports (A and B) support PWM.

Pulsing an LED With Arduino

Pulsing an LED in an Arduino sketch (Arduino Programming Language) requires more effort than blinking. Much has changed here from the blinking sketch, but certain things remain the same. There is still a process-blocking operation (delay), this time for 30ms on each loop cycle. We can no longer use the digitalWrite() function (it can only write binary LOW or HIGH); instead we’ll need the analogWrite() function for writing PWM values from 0 (0% duty cycle) to 255 (100% duty cycle). There are also now three variables to keep track of: led for the pin number, brightness to track the present brightness state, and lastly fadeAmount which holds the increase or decrease value to be applied to the value of brightness. Whew!

Here’s what that looks like all together:

language:cpp
int led = 9;           // the PWM pin the LED is attached to
int brightness = 0;    // how bright the LED is
int fadeAmount = 5;    // how many points to fade the LED by

void setup() {
  pinMode(led, OUTPUT);
}

void loop() {
  analogWrite(led, brightness);

  brightness = brightness + fadeAmount;

  if (brightness == 0 || brightness == 255) {
    fadeAmount = -fadeAmount ;
  }

  delay(30);
}

It may be hard to get your head around the logic in that program. It’s not that easy to read. It doesn’t scream “pulse an LED” in the way that it expresses itself, does it?

Pulsing an LED With Johnny-Five

Let’s see what pulsing an LED looks like in Johnny-Five. Open your led.js script again. You’ll need to edit one line. Change the line that currently reads:

led.blink(500);

to

led.pulse(500);

No kidding—that’s it! No need to keep track of things, handle scheduling and timing or do arithmetic—instances of Johnny-Five’s Led do it all for you. Like blink, the pulse method takes an argument that is the pulse period in milliseconds. Here is the complete script for your copying-and-pasting convenience:

language:javascript
var Tessel = require("tessel-io");
var five = require("johnny-five");

  var board = new five.Board({
    io: new Tessel()
  });

  board.on("ready", function() {
    var led = new five.Led("a5");
    led.pulse(500);
  });

Remember, to run the script and see your LED pulse, type — or copy and paste — the following command in a terminal:

t2 run led.js

What You Should See

Your LED should be pulsing in 500ms period cycles.

Building Further

Try adjusting the speed passed to the led.blink() and led.pulse() calls. For example: led.blink(1000) or led.pulse(1000) would change the cycles to 1000ms periods.

Reading Further

• JavaScript— the programming language used in these experiments
  • Working with JavaScript objects
• Node.js— JavaScript runtime where your programs will be executed
• Johnny-Five— framework written in JavaScript for programming hardware interaction on devices that run Node.js
• Arduino Programming Language

Experiment 2: Multiple LEDs

Introduction

In Experiment 1 of the Johnny-Five Inventor’s Kit (J5IK), you learned how to blink and pulse a single LED with a Tessel 2. In this experiment, you’ll learn how to control multiple, colorful LEDs with Johnny-Five to create animated variations on a simple “Cylon effect.” This article dives into structuring looping logic for your projects using Johnny-Five and JavaScript fundamentals.

Suggested Reading

The following tutorials provide in-depth background on some of the hardware concepts in this experiment:

• What is a Circuit?– This tutorial will explain what a circuit is, as well as discuss voltage in further detail.
• Voltage, Current, Resistance, and Ohm’s Law– Learn the basics of electronics with these fundamental concepts.
• LEDs (Light-Emitting Diodes)– LEDs are found everywhere. Learn more about LEDs and why they are used in so many products all over the world.
• Resistors– Why use resistors? Learn more about resistors and why they are important in circuits like this one.
• Polarity– Polarity is a very important characteristic to pay attention to when building circuits.

Parts Needed

You will need the following parts for this experiment:

• 1x Tessel 2
• 1x Breadboard
• 6x LEDs (One of each color: red, orange, yellow, green, blue, purple)
• 6x 100Ω Resistor
• 7x Jumper Wires

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

24

FavoritedFavorite24

Wish List

Added to your cart!

LED - Assorted (20 pack)

In stock COM-12062

We all know that you can never get too many LEDs. Don't worry, we've got you covered. This is a pack of basic red, yellow, bl…

$2.95

6

FavoritedFavorite22

Wish List

Added to your cart!

Jumper Wires - Connected 6" (M/M, 20 pack)

In stock PRT-12795

These are 6" long jumper wires with male connectors on both ends. Use these to jumper from any female header on any board, to…

$1.95

1

FavoritedFavorite6

Wish List

Added to your cart!

Tessel 2

In stock DEV-13841

The Tessel 2 is a development board with on-board WiFi capabilities that allows you to build scripts in Node.js. This Tessel …

$44.95

FavoritedFavorite5

Wish List

Added to your cart!

Resistor 100 Ohm 1/4th Watt PTH - 20 pack

In stock COM-13761

These are 1/4th Watt, +/- 5% tolerance PTH resistors. Commonly used in breadboards and perf boards, these 100 Ohm resistors m…

$0.95

FavoritedFavorite0

Wish List

Hardware Hookup

Its now the fun part! It’s time to start building your circuit. Let’s take a look at what goes into building this circuit.

Build the Multiple-LED Circuit

Having a hard time seeing the circuit? Click on the wiring diagram for a closer look.

1. Connect the LEDs to the breadboard. Make sure to connect their cathode legs to sockets in the ground column in the power rail.
2. Plug in the 100Ω resistors in terminal rows shared with the anode legs of the LEDs, spanning the central notch.
3. Connect jumper wires between the resistors and the Tessel 2. You may find it helpful to use colors that correspond to the LED’s color.
4. Use a jumper wire to connect the ground power rail of the breadboard to the Tessel 2’s GND pin.

Lighting Up LEDs Side-to-Side

Open your favorite code editor, create a file called side-to-side.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your side-to-side.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});
board.on("ready", () => {
  var leds = new five.Leds(["a2", "a3", "a4", "a5", "a6", "a7"]);
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();
    leds[index].on();
    index += step;
    if (index === 0 || index === leds.length - 1) {
      step *= -1;
    }
  });
});

Before you run this on your Tessel 2, pause for a moment. Can you tell what the program will do?

Type – or copy and paste – the following command into your terminal and press enter:

t2 run side-to-side.js

Once the program starts up, your multiple-LED circuit should light up in a pattern like this:

Exploring the Code

Before continuing, we recommend that you’ve read Experiment 1: Exploring the Code.

The side-to-side program lights up LEDs in the following pattern:

1. From lowest pin number to highest pin number, turn on one LED at a time every 100 milliseconds, then:
2. From highest pin number to lowest pin number, turn on one LED at a time every 100 milliseconds, then:
3. Repeat from step 1.

Collections of LEDs With the Leds Class

Instead of instantiating each LED as its own object separately using the Led class (as we did in Experiment 1), we can create a single collection that contains all of the LEDs in one swoop:

language:javascript
board.on("ready", function() {
  var leds = new five.Leds(["a2", "a3", "a4", "a5", "a6", "a7"]);
});

Johnny-Five’s Leds constructor takes an Array of pin numbers and creates an Led object for each of them. Each of these Led objects can be accessed and manipulated from the container-like leds object. Instances of the Leds class behave like Arrays but have some extra goodies (they’re described as “Array-like objects”).

Read up on JavaScript Arrays if the concept is new or you’re feeling rusty.

Looping in Johnny-Five

To turn on LEDs one at a time, we need some way of creating a loop that executes every 100 milliseconds. We’re in luck. Board object instances have a loop method that can do just that! Convenient!

language:javascript
board.on("ready", () => {
  board.loop(100, () => {
    // ... This function gets invoked every 100 milliseconds
  });
});

The function (in this case, an arrow function]) passed as the second argument to loop will get invoked every 100 milliseconds. Now, let’s see what needs to happen in that loop.

Lighting Up, Lighting Down

Here’s what we need to accomplish in each invocation of the loop callback function:

language:javascript
board.on("ready", () => {
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();            // 1. Turn all of the LEDs off
    leds[index].on();      // 2. Turn on the "next" active LED
    // ...                 // 3. Determine what the next active LED will be
  });
});

In step one, all LEDs are turned off. Leds instances have an off method that will turn off every Led in its collection. Easy peasy.

The variable index holds the index of the next LED that should get turned on. The initial value of index is 0. Why 0? Each Led in leds can be accessed by its numeric index, like an Array:

The first time the loop executes, index is 0, and it will turn on leds[0], which is the first (red) LED on Port A, Pin 2:

language:javascript
leds[index].on();

Step 3 sets us up for the next time the loop function executes. The value of index needs to be set to the index of the next LED that should turn on. This is what the step variable helps us with. Add step to index to get the index of the next LED to light up:

language:javascript
board.on("ready", () => {
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();            // 1. Turn all of the LEDs off
    leds[index].on();      // 2. Turn on the "next" active LED
    index += step;         // 3a. Add `step` to index
  });
});

At the completion of the first invocation of the loop callback function, index will hold the value 1.

During the second invocation, the second, orange LED (leds[1]) will light up. index will be incremented to 2.

And so on, lighting up red, orange, yellow, green, blue … But then we get to the purple LED (Port A, Pin 7) at index 5. There is no Led element at leds[6], so what do we do now? Well, we can flip the sign of step, changing its value to -1:

language:javascript
board.on("ready", () => {
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();            // 1. Turn all of the LEDs off
    leds[index].on();      // 2. Turn on the "next" active LED
    index += step;         // 3a. Add `step` to index
    if (index === leds.length - 1) { // 3b. If we're at the highest index...
      step *= -1; // ...invert the sign of step
    }
  });
});

Now invocations of the loop callback function will decrease (decrement) the index value, and the LEDs will light up in reverse order. When the index gets down to 0— the first LED — we need to swap the sign of step again:

language:javascript
board.on("ready", () => {
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();            // 1. Turn all of the LEDs off
    leds[index].on();      // 2. Turn on the "next" active LED
    index += step;         // 3a. Add `step` to index
    // If we are at the lowest OR the highest index...
    if (index === 0 || index === leds.length - 1) {
      step *= -1;
    }
  });
});

Using board.loop with the leds can be adapted in various ways to change the way the LEDs light up. Let’s try a few variations.

Variation: One-by-One On, One-by-One Off

Now we’ll light up each LED one at a time and keep them on as we go; the display will loop as:

1. From lowest pin number to highest pin number, turn on each LED and keep it on.
2. From highest pin number to lowest pin number, turn off each LED and keep it off.
3. Repeat from step 1.

Open your favorite code editor, create a file called one-by-one-on-off.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your one-by-one-on-off.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});
board.on("ready", () => {
  var leds = new five.Leds(["a2", "a3", "a4", "a5", "a6", "a7"]);
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off().slice(0, index).on();
    index += step;
    if (index === 0 || index === leds.length) {
      step *= -1;
    }
  });
});

All of the changes are confined to the loop callback function. There’s one line doing much of the heavy lifting here:

leds.off().slice(0, index).on();

This single line turns all of the LEDs off and then turns on all LEDs between 0 and the current index. slice is an Array method that returns a chunk of an array between the start and end indexes provided (leds isn’t an Array, remember, but it acts like one, so it also has a slice method).

As in the previous example, this script will flip the sign on step when it reaches either end of the leds collection.

Run the script by typing – or copying and pasting – the following command in your terminal:

t2 run one-by-one-on-off.js

Once the program starts up, your LEDs circuit should display something like this:

Variation: One-by-One On, Clear and Repeat

Now let’s simplify that same program: light up each pin, one at a time, and then turn them off; the display will loop as:

1. From lowest pin number to highest pin number, turn on each LED and keep it on.
2. Once all the LEDs are on, turn them all off
3. Repeat from step 1.

Open your favorite code editor, create a file called one-by-one-clear-repeat.js and save it in the j5ik/ directory. Type – or copy and paste – the following JavaScript code into your one-by-one-clear-repeat.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});
board.on("ready", () => {
  var leds = new five.Leds(["a2", "a3", "a4", "a5", "a6", "a7"]);
  var index = 0;

  board.loop(100, () => {
    if (index === leds.length) {
      leds.off();
      index = 0;
    } else {
      leds[index].on();
      index++;
    }
  });
});

Again, there is very little to change here, so we’ll skip right to the operations within the call to board.loop(...).

language:javascript
board.loop(100, () => {
  if (index === leds.length) {
    leds.off();
    index = 0;
  } else {
    leds[index].on();
    index++;
  }
});

The semantics for this program are slightly different from the previous examples. Because we’re always lighting LEDs up in the same direction — lowest to highest index — we don’t have to deal with the logic for swapping the sign on a step variable. Instead, a simple increment of the index value on each invocation of the loop callback function is all we need, resetting it to 0 when we run out of LED indexes.

1. If the index equals the number of LEDs in the leds collection,
2. Turn all ledsoff.
3. Set the index back to 0.
4. Else,
5. Turn the led at present indexon.
6. Increment the index.

Type — or copy and paste — the following into your terminal:

t2 run one-by-one-clear-repeat.js

Once the program starts up, your LEDs circuit should display something like this:

Variation: Collision

Changing gears a bit, this next program will light LEDs from the middle, out, and back (there will be two LEDs lit at a time); the display will loop as:

1. From the first to the last and the last to the first, by pin number, light the LEDs one at a time.
2. Repeat from step 1.

Open your favorite code editor, create a file called collision.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your collision.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});
board.on("ready", () => {
  var leds = new five.Leds(["a2", "a3", "a4", "a5", "a6", "a7"]);
  var index = 0;
  var step = 1;

  board.loop(100, () => {
    leds.off();
    leds[index].on();
    leds[leds.length - index - 1].on();

    index += step;

    if (index === 0 || index === leds.length - 1) {
      step *= -1;
    }
  });
});

This example contains logic more in line with the first few variations again — turning on the correct LED and then determining what the next LED’s index will be:

1. Turn all ledsoff.
2. Turn the leds at index and its counterpart on.
3. Update the index with step (either 1 or -1).
4. If index equals 0, or index equals the number that corresponds to the last possible led in the leds collection, flip the sign of step.

Type — or copy and paste — the following into your terminal:

t2 run collision.js

Once the program starts up, your LEDs circuit should display something like this:

Building Further

• Try writing your own algorithms for other patterns not shown here.

Reading Further

• JavaScript– JavaScript is the programming language that you’ll be using:
  • Array
  • Assignment Operators
  • Arrow Functions
• Node.js– Node.js is the JavaScript runtime where your programs will be executed.
• Johnny-Five– Johnny-Five is a framework written in JavaScript for programming hardware interaction on devices that run Node.js.

Experiment 3: Reading a Potentiometer

Introduction

So far the experiments have been focused on output: writing code with Johnny-Five to control the state of one or more LEDs. In this experiment, you’ll learn how to read analog input data from a potentiometer. You’ll learn about how development boards (like the Tessel 2) sample and process analog input and how to use data from analog sources to make things happen. Using data from the potentiometer, you’ll control a bar graph in your terminal, alter the brightness of an LED and control the activity of multiple LEDs.

Suggested Reading

The following tutorials provide in-depth background on some of the hardware concepts in this experiment:

• What is a Circuit?– This tutorial will explain what a circuit is, as well as discuss voltage in further detail.
• Analog to Digital Conversion
• Analog vs. Digital
• Voltage, Current, Resistance, and Ohm’s Law– Learn the basics of electronics with these fundamental concepts.
• LEDs (Light-Emitting Diodes)– LEDs are found everywhere. Learn more about LEDs and why they are used in so many products all over the world.
• Resistors– Why use resistors? Learn more about resistors and why they are important in circuits like this one.
• Polarity– Polarity is a very important characteristic to pay attention to when building circuits.

Parts Needed

You will need the following parts for this experiment:

• 1x Tessel 2
• 1x Breadboard
• 1x Potentiometer
• 1x Standard LED (any color)
• 1x 100Ω Resistor
• 7x Jumper Wires

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

24

FavoritedFavorite24

Wish List

Added to your cart!

LED - Assorted (20 pack)

In stock COM-12062

We all know that you can never get too many LEDs. Don't worry, we've got you covered. This is a pack of basic red, yellow, bl…

$2.95

6

FavoritedFavorite22

Wish List

Added to your cart!

Trimpot 10K with Knob

In stock COM-09806

There are lots of trimpots out there. Some are very large, some so small they require a screwdriver. Here at SparkFun, we jus…

$0.95

6

FavoritedFavorite16

Wish List

Added to your cart!

Jumper Wires - Connected 6" (M/M, 20 pack)

In stock PRT-12795

These are 6" long jumper wires with male connectors on both ends. Use these to jumper from any female header on any board, to…

$1.95

1

FavoritedFavorite6

Wish List

Added to your cart!

Tessel 2

In stock DEV-13841

The Tessel 2 is a development board with on-board WiFi capabilities that allows you to build scripts in Node.js. This Tessel …

$44.95

FavoritedFavorite5

Wish List

Added to your cart!

Resistor 100 Ohm 1/4th Watt PTH - 20 pack

In stock COM-13761

These are 1/4th Watt, +/- 5% tolerance PTH resistors. Commonly used in breadboards and perf boards, these 100 Ohm resistors m…

$0.95

FavoritedFavorite0

Wish List

Introducing Potentiometers

A potentiometer is a resistance-based analog sensor that changes its internal resistance based on the rotation of its knob. The potentiometer has an internal voltage divider, creating a varying voltage on the center pin. The voltage on the center pin changes as the knob is turned. You can use an analog input pin to read this changing voltage.

Hardware Hookup

Its now the fun part! It’s time to start building your circuit. Let’s take a look at what goes into building this circuit.

Build the Potentiometer Circuit

To hook up the potentiometer, attach the two outside pins to a supply voltage (3.3V in this circuit) and ground. It doesn’t matter which is connected where, as long as one is connected to power, and the other to ground. The center pin is then connected to an analog input pin so the Tessel 2 can measure changes in voltage as the knob is turned.

Having a hard time seeing the circuit? Click on the wiring diagram for a closer look.

1. Connect the potentiometer to the breadboard. Connect the potentiometer’s power pins (supply and ground) to the power rail with jumper wires and connect the middle pin to the Tessel 2’s Port A, Pin 7.
2. Connect the LED. Use a jumper wire to connect the Tessel 2’s Port B, Pin 5 through the 100Ω resistor and to the LED’s anode (positive, longer) leg. Connect the LED’s cathode to ground on the power rail. Double-check the legs on the LED to make sure you haven’t plugged it in backward!
3. Use jumper wires to connect the Tessel 2’s 3.3V and GND pins to the breadboard’s power rails.

Reading Analog Sensors With Johnny-Five

Open your favorite code editor, create a file called sensor-basic.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your sensor-basic.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel(),
  repl: false,
  debug: false,
});

board.on("ready", () => {
  var sensor = new five.Sensor("a7");

  sensor.on("change", () => console.log(sensor.value));
});

Type — or copy and paste — the following into your terminal:

t2 run sensor-basic.js

This isn’t particularly interesting, as all it does is output the value of the sensor (integers between 0 and 1023) until the program is interrupted. yawn

You should see something similar to this. Your sensor values (0-1023) being logged in the console.

Exploring the Hardware

Analog Input

For software to be able to work with data coming from an analog sensor, it first needs to be converted from an analog signal (infinite possible values) to a digital signal (discrete set of values). The microcontroller on the Tessel 2 does this analog-to-digital conversion (ADC) for you, sampling the incoming analog voltages and converting them to a range of values between 0 (0V) and 1023 (3.3V). Values in between are quantized to the nearest integer.

Asynchronous I/O

In Experiment 1: Blink an LED, we looked at the asynchronous nature of Node.js runtime, comparing how the Arduino Programming Language’s delay function is blocking, while Johnny-Five’s execution model follows the Node.js convention: non-blocking. Listening for Boardready events is an example of a common asynchronous pattern. Non-blocking I/O is extremely important to the JavaScript-for-hardware story, and the Tessel 2 has an exemplary implementation.

Tessel 2’s support for asynchronous, non-blocking I/O is in its hardware. In addition to the Mediatek chip (that’s where your code executes), it has a second processor (Atmel^® SAMD21) that is responsible for I/O.

The MediaTek processor and the Atmel coprocessor exchange messages representing I/O state. Code that executes on the MediaTek chip (the Linux user space) has asynchronous access to the state captured on SAMD21. For example, if a digital input pin goes HIGH, the SAMD21 sends a message to the MediaTek chip and any code running can elect to consume that message. When code running on the MediaTek chip wants to output values to the SAMD21 to be written to an output pin, it simply sends the message, then keeps going.

The MediaTek chip (green) and the Atmel SAMD21 (blue) allow for Asynchronous I/O on your Tessel 2.

For the purpose of our experiment, it’s helpful to understand that when program code running on the MediaTek chip wants to know the value of an analog input, it sends a request for that information, registers a handler (a function) and continues on. Sometime “later” (likely within a millisecond or two), and always in a different execution turn, the SAMD21 responds with the present value of the input. The registered handler is then invoked with response value. This may happen once or repeatedly, but never causes the program to stop and wait.

Exploring the Code

Notice that the Board constructor call is being passed an object with two properties that we haven’t seen before: repl: false and debug: false. These settings tell Johnny-Five to shut off both the “on-by-default” REPL (Read–Eval–Print Loop, an interactive prompt) and connection debugging output.

Once the board has emitted the ready event, hardware inputs are ready for interaction:

language:javascript
var sensor = new five.Sensor("a7");

The first thing to do is create an instance of the Sensor class, indicating that this sensor is attached to Port A, Pin 7.

language:javascript
sensor.on("change", () => console.log(sensor.value));

Then, a handler function is registered for change events, meaning that anytime the reading changes, the function will be called.

Every time this function is called and the sensor value is displayed, it occurs in a different execution turn than the previous invocation, staying true to the asynchronous, non-blocking model. The handler function for change events simply logs sensor.value. sensor.value is a 10-bit number (0-1023), representing the last successful ADC-processed read from the Sensor object’s associated analog input pin.

Note: The minimum version of Node.js that runs on Tessel 2 supports many ES2015 features, including Arrow Functions, so we’re using those here to simplify the program.

Variation: Sensor Input Graphing

For this experiment, you will be “bar chart graphing” light intensity values in your terminal using the Barcli module:

barcli [bahrk-lee]

Barcli is a simple tool for displaying real-time data in the console. Multiple instances of Barcli can be stacked to show multiple axes, sensors or other data sources in an easy-to-read horizontal bar graph.

In your terminal, make sure you’re inside the working directory (j5ik), then type — or copy and paste — the following command:

npm install barcli

We’ll make our sensor data a little more interesting (than just numbers scrolling by). Let’s visualize it as a graph displayed directly in the terminal. Open your favorite code editor, create a file called sensor-graph.js and save it in the j5ik/ directory.

Type — or copy and paste — the following JavaScript code into your sensor-graph.js file:

language:javascript
var Barcli = require("barcli");
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});

board.on("ready", function() {
  var range = [0, 100];
  var graph = new Barcli({
    label: "My Data",
    range: range,
  });
  var sensor = new five.Sensor({
    pin: "a7",
    threshold: 5 // See notes below for detailed explanation
  });

  sensor.on("change", () => {
    graph.update(sensor.scaleTo(range));
  });
});

Type — or copy and paste — the following into your terminal:

t2 run sensor-graph.js

Once the program starts up, the terminal should display something like this:

Exploring the Code

We’ve now required the Barcli module:

language:javascript
var Barcli = require("barcli");

… which means it can be put to use in your program.

To create a graph, we’ll need an instance of a Barcli object. First, though, we need to define a range of values that are valid for the graph:

language:javascript
var range = [0, 100];
var graph = new Barcli({
  label: "My Data",
  range: range,
});

The graph object is now able to represent values from 0 to 100. However, recall that values coming from the potentiometer will range from 0 to 1023. We’ve got to scale those, too, so that they can be graphed!

The way we’re instantiating the Sensor object looks a bit different from the previous example. Instead of passing the constructor a String identifying the pin, like so:

language:javascript
var sensor = new five.Sensor("a7");

… we’re using the options object form here, which allows us to pass a whole object full of extra information to the constructor:

language:javascript
var sensor = new five.Sensor({
  pin: "a7",
  threshold: 5
});

Let’s talk about that threshold property. It defines how much a sensor’s value needs to change before a change event is emitted. The default value of threshold is 1. As you saw in the first example, any change to the sensor’s value – remember, values range from 0 to 1023 and are whole numbers (integers) – will cause a change event. For this variation, that’s too much sensitivity.

Specifically, we want to define a threshold that will limit the change events to those that are relevant to our range, which is 0-100. Since we’ll be scaling the sensor’s value from 0-1023 to 0-100, we only care about changes of approximately every 10 steps in 1023 (obviously that’s fudging a little, and you’re encouraged to be more precise in your actual programs). The threshold value is exactly half of the approximate step:

• > (value + 5)
• < (value - 5)

Finally, the program replaces the call to console.log(...) with a call to graph.update(...) and passes the result of calling the sensor object’s scaleTo(...) method with the same range as graph is using:

language:javascript
sensor.on("change", () => {
  graph.update(sensor.scaleTo(range));
});

Unpacking the line:

language:javascript
graph.update(sensor.scaleTo(range));

When invocations are nested like this, they proceed from the inside out. First, the sensor object’s 10-bit value is scaled to 0-100 (range) and then that resulting value is passed to the graph object’s update method.

Variation: Using Sensor Input to Create Output

For the final variation of this experiment, you’ll process the sensor readings to control the brightness of the LED in your circuit. Open your favorite code editor, create a file called sensor-input-to-output.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your sensor-input-to-output.js file:

language:javascript
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
  io: new Tessel()
});

board.on("ready", function() {
  var sensor = new five.Sensor({
    pin: "a7",
    threshold: 2
  });
  var led = new five.Led("b5");

  sensor.on("change", () => {
    led.brightness(sensor.scaleTo(0, 255));
  });
});

Type — or copy and paste — the following into your terminal:

t2 run sensor-input-to-output.js

Once the program starts up, LED should display something like this:

Exploring the Code

Again, we’re instantiating a Sensor object to represent the potentiometer, and defining a threshold. This time we’ll set it to 2, because the rounded result of 1023 (the top of the 10-bit sensor range) divided by 255 (the top of the 8-bit brightness range) is 4, and threshold should be set to half of the full step size:

language:javascript
var sensor = new five.Sensor({
  pin: "a7",
  threshold: 2
});

Next, a new instance of the Led class is created, with Pin 5 on Port B:

language:javascript
var led = new five.Led("b5");

+The change event remains the same, but the operation within the handler is updated to call the led object’s brightness(...) method, passing the sensor’s value scaled from its 10-bit input range (0-1023) to the 8-bit output range (0-255) of the led:

 language:javascript
 sensor.on("change", () => {
   led.brightness(sensor.scaleTo(0, 255));
 });

Alternatively, the conversion could have been written as a bit-shifting operation, where the 10-bit value is shifted 2 bits to the right, since brightness(...) expects an 8-bit value (0-255). This bit-shifting operation is the most efficient way to scale the 10-bit analog input value to the 8-bit PWM output value:

language:javascript
0b1111111111 === 1023;
0b0011111111 === 255;
0b11111111 === 255;
(0b1111111111 >> 2) === 255;

And could be applied in our code like so:

language:javascript
sensor.on("change", () => {
  led.brightness(sensor.value >> 2);
});

This snippet means “shift the sensor.value 2 bits to the right” — the two right-most bits are discarded. Voila! An 8-bit number from a 10-bit number.

Building Further

• Experiment with bit shifting in your Node.js console.

Reading Further

• JavaScript– JavaScript is the programming language that you’ll be using:
  • Bitwise Operators and Bit Shifting
  • Assignment Operators
  • Arrow Functions
• Node.js– Node.js is the JavaScript runtime where your programs will be executed.
• Johnny-Five– Johnny-Five is a framework written in JavaScript for programming hardware interaction on devices that run Node.js.

Experiment 4: Reading a Push Button

Introduction

In Experiment 3, you journeyed into the fun world of input by reading data from an analog sensor. This experiment continues that journey, moving now into digital input. You’ll learn how digital input differs from analog input, and you’ll meet a useful new component: the push button (also sometimes called a momentary switch). You’ll learn how to control a single LED with button presses, and then how to control multiple LEDs from multiple buttons.

Suggested Reading

The following tutorials provide in-depth background on some of the hardware concepts in this experiment:

• Switch Basics— Push buttons are a kind of a switch (a momentary switch)
• Pull-up and Pull-down Resistors— Pull-up and pull-down resistors are commonly used in circuits with digital logic

Parts Needed

To complete this experiment, you’ll build two circuits. You’ll need the following parts:

• 1x Tessel 2
• 1x Breadboard
• 2x Standard LED (any color is fine)
• 2x Push Button
• 2x 100Ω Resistors
• 2x 10kΩ Resistors
• 12x Jumper Wires

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

24

FavoritedFavorite24

Wish List

Added to your cart!

LED - Assorted (20 pack)

In stock COM-12062

We all know that you can never get too many LEDs. Don't worry, we've got you covered. This is a pack of basic red, yellow, bl…

$2.95

6

FavoritedFavorite22

Wish List

Added to your cart!

Momentary Pushbutton Switch - 12mm Square

In stock COM-09190

This is a standard 12mm square momentary button. What we really like is the large button head and good tactile feel (it 'clic…

$0.5

4

FavoritedFavorite16

Wish List

Added to your cart!

Jumper Wires - Connected 6" (M/M, 20 pack)

In stock PRT-12795

These are 6" long jumper wires with male connectors on both ends. Use these to jumper from any female header on any board, to…

$1.95

1

FavoritedFavorite6

Wish List

Added to your cart!

Tessel 2

In stock DEV-13841

The Tessel 2 is a development board with on-board WiFi capabilities that allows you to build scripts in Node.js. This Tessel …

$44.95

FavoritedFavorite5

Wish List

Added to your cart!

Resistor 10K Ohm 1/6th Watt PTH - 20 pack

In stock COM-11508

1/6th Watt, +/- 5% tolerance PTH resistors. Commonly used in breadboards and perf boards, these 10K resistors make excellent …

$0.95

FavoritedFavorite3

Wish List

Added to your cart!

Resistor 100 Ohm 1/4th Watt PTH - 20 pack

In stock COM-13761

These are 1/4th Watt, +/- 5% tolerance PTH resistors. Commonly used in breadboards and perf boards, these 100 Ohm resistors m…

$0.95

FavoritedFavorite0

Wish List

Introducing the Push Button

A momentary push button is a kind of switch, closing (completing) a circuit while it is being actively pressed. If you take a push button and look at it, you’ll notice it has four pins, which might seem like a lot of pins. Let’s walk through how the pins are connected to each other.

The four pins on a push button are split into two pairs. Each pin is adjacent to two other pins: the other half of its pair (on the opposite side of the button) and a pin not paired with it (located on the same side). A pin is always electrically connected to the other pin in its pair, but is only connected to the other adjacent pin when the button is actively being pressed. When you press down on the button and get a nice “click,” the button bridges the two sets of pins and allows current to flow through the circuit.

How do you know which pins are paired up? The buttons included in this kit will only fit across the breadboard ditch in one direction. Once you get the button pressed firmly into the breadboard (across the ditch), the pins are horizontally paired. The pins toward the top of the breadboard are connected, and the pins toward the button of the breadboard are connected.

All right, now we have a sense of how a button can complete a circuit, but we need the right kind of circuit for our button. Button presses need to cause a digital input on the Tessel to move between HIGH and LOW logic levels when the button is pressed. The circuits in the two wiring diagrams for this experiment use a 10kΩ pull-down resistor with the buttons to make sure that the Tessel will read the button circuit as LOW (off/false) when the button isn’t pressed and HIGH (on/true) when it is.

Hardware Hookup

Your kit comes with four different colored push buttons. All push buttons behave the same, so go ahead and use your favorite color!

Build the Button Circuit

Having a hard time seeing the circuit? Click on the wiring diagram for a closer look.

1. Connect the pushbutton to the breadboard. It should only fit in one orientation spanning the center notch. Use jumper wires to connect one of the right-hand pins of the button to the ground power rail, through a 10kΩ resistor, as shown. Connect the other pin of the right side of the button to the supply power rail with another jumper wire.
2. Starting from a socket on the same row as the 10kΩ resistor — but on the opposite side of it from the button — connect a jumper wire to the Tessel’s Port A, Pin 0.
3. Plug the LED into the breadboard as shown, making sure the anode (longer leg) is closer to the top of the breadboard. Connect the cathode (shorter leg) to the ground power rail using a jumper wire. Connect the anode, through a 100Ω resistor, to the Tessel 2’s Port A, Pin 5.
4. Connect the Tessel’s +3.3V and GND pins to the breadboard’s power rails, using jumper wires.

Observing a Button With Johnny-Five’s Button Class

Open your favorite code editor, create a file called button.js and save it in the j5ik/ directory. Type — or copy and paste — the following JavaScript code into your button.js file:

language:javascript
var Tessel = require("tessel-io");
var five = require("johnny-five");

var board = new five.Board({
  io: new Tessel()
});

board.on("ready", () => {
  var button = new five.Button("a2");
  button.on("press", () => console.log("Button Pressed!"));
  button.on("release", () => console.log("Button Released!"));
});

Type — or copy and paste — the following into your terminal:

t2 run button.js

What You Should See

When you press the button, your terminal will display the appropriate message:

Console output triggered by button events

Exploring the Code

Using Input to Control Output With Johnny-Five

OK, let’s make this do something a little more interesting before we dive in and look at how it works. Go back to your button.js and either type the changes or copy and paste the following code:

language:javascript
var Tessel = require("tessel-io");
var five = require("johnny-five");

var board = new five.Board({
  io: new Tessel()
});

board.on("ready", function() {
  var led = new five.Led("a5");
  var button = new five.Button("a2");
  button.on("press", () => led.on());
  button.on("release", () => led.off());
});

Type — or copy and paste — the following into your terminal:

t2 run button.js –single

The --single flag tells the T2 CLI to only deploy the single, specified file. This will preserve all other existing code on the Tessel 2 while still deploying your new program changes, which can make the deployment faster.

What You Should See

When you press the button, the LED should light up. When you release the button, the LED should turn off.

Exploring the Code

Once the board has emitted the ready event, we can initialize Led and Button instances to interact with our hardware on the specified pins:

language:javascript
var led = new five.Led("a5");
var button = new five.Button("a2");

The Johnny-Five Button class takes care of processing values from input in order to emit intuitive events for each state of the hardware. We’ve registered handlers for these events: press, hold and release.