Electric Circuits

Having a basic conceptual understanding of electric circuits is very helpful, so students can better understand how to correctly connect the parts in their IoT electronics kit (and how to troubleshoot connection issues) – however, it is NOT required:

• Atoms and Electrons

• Static Electricity vs. Current Electricity

• Conductors vs. Insulators

• Closed Circuit vs. Open Circuit

• Voltage, Current, and Resistance

• Series Circuit vs. Parallel Circuit

Being able to solve quantitative equations involving circuits (Ohm's Law, etc.) is NOT required.

The IoT tutorials will provide a limited explanation of circuits, which should be sufficient for using the IoT kit to create devices.

Physical Computing

Previous experience building and programming devices using an Arduino electronics kit – such as a robotics kit, etc. – is very helpful. However, it is NOT required. The IoT tutorials will assume that students have no prior experience in building or programming physical computing devices.

Arduino

Previous experience and familiarity with the following Arduino development concepts is very helpful before programming IoT device apps – however, it is NOT required:

• Variables – declaring data type (int, float, boolean, String, etc.) and name (unique identifier), assigning and changing values, converting data type, global vs. local scope

• Program Functions – setup() function, loop() function, creating custom functions, calling a custom function, passing arguments into a function, returning value from a function

• Input/Output Functions – such as: pinMode(), digitalRead(), digitalWrite(), analogRead(), analogWrite(), tone(), etc.

• Libraries and Objects – including external library file in device app, constructing new object using defined class in library, using object properties and methods

• Comparison Operators – such as: >, <, ==, !=, etc.

• Logical Operators (NOT, AND, OR): !, &&, ||

• Conditional Statements using if and else

• Loops – such as: for, while, etc.

Web Development

Previous experience and familiarity with these web development concepts is highly recommended before programming IoT web apps – however, mastery is NOT required:

HTML

• Tag syntax for common HTML elements – such as: <div>, <h1>, <h2>, <p>, <span>, <a>,<img>, <button>, <input>, <ul>, <li>, etc.

• Nesting of HTML elements within other elements

• Use of class and id attributes for HTML elements

• Loading external files – such as: CSS style sheets, JavaScript files, images, other web pages, etc.

CSS

• CSS selectors for HTML elements, classes, and ids

• Common properties used in styles – such as: background-color, color, font-size, margin, padding, border, width, height, display, etc.

JavaScript (including jQuery)

• Variables – declaring names (unique identifiers), assigning and changing values, data types (numbers, strings, boolean, etc.), global vs. local scope

• Functions – creating functions, calling a function, passing arguments into a function, returning value from a function

• Objects – constructing new object using defined class, using object properties and methods

• Comparison Operators – such as: >, <, ==, !=, etc.

• Logical Operators (NOT, AND, OR): !, &&, ||

• Conditional Statements using if and else

• Loops – such as: for, while, etc.

• Events – such as: onclick, onchange, etc.

• jQuery selectors for HTML elements, classes, and ids

• jQuery syntax for basic functions – such as: .html(), .show(), .hide(), .addClass(), .removeClass(), etc.

In this second tutorial, you'll program a "Hello World" app for your IoT device.

Tutorial Goals

The goals of this second tutorial are to help you:

• Verify your Photon device connects to Wi-Fi and the Particle Cloud service

• Understand how to use Particle Build to create Photon device apps

• Create a Hello World app to learn how to program your Photon device

What is a Hello World app?

When learning a new programming language, the first step that many people take is to create what is called a "Hello World" program. Traditionally, this program simply displays the text "Hello World" on the screen and only requires a few lines of code. The purpose is to demonstrate that you can create a simple yet functional program in the new coding language. It's the first step before creating more complex programs.

However, your Photon circuit board does not have a built-in screen. Your Photon kit does have a micro OLED screen that can be connected to the Photon – but that would require connecting 7 different jumper wires and coding a more complex app. Eventually, you'll be able to do this – but we need something much simpler for your first Photon app.

The good news is your Photon circuit board has a built-in blue LED light (D7) that can be controlled by your device's app. You won't have to connect any extra parts or wires yet – and you can program a simple app that makes the built-in LED blink on and off repeatedly, as a way of saying "Hello World."

Wiring Programming Language

All the apps that run on your Photon device will be coded using Particle's version of the open-source Wiring programming language framework for microcontrollers.

The Particle firmware on your Photon runs a modified version of the Wiring language with a few minor differences, as well as some additional methods (functions) customized for the Photon hardware.

One example of a minor difference:

• In the original Wiring language, the analogRead() method reads the value of an analog input pin and returns the value as an integer (whole number) between 0-1023.

• In the Particle firmware, the analogRead() method does the same thing but returns the value as an integer between 0-4095 (providing a higher level of precision).

The Particle firmware contains additional methods (functions) that are not part of the original Wiring language. For example, there are methods which are used to make the Photon interact with Particle Cloud. There are methods which can be used to control built-in hardware components on the Photon circuit board (such as the Wi-Fi module, RGB light, etc.).

Let's start your Photon to verify it connects to Wi-Fi and Particle Cloud.

Power On Photon

Start your Photon by powering on the circuit board:

• Connect a power cable into the barrel jack or Micro-USB port on the circuit board, and connect the other end of the cable to a power source (such as: battery, computer USB port, etc.).

Once the circuit board has power, you should see its red Power LED light turn on.

You should also see the RGB LED light turn on – it will blink green while the Photon automatically tries to connect to Wi-Fi.

Once the Photon has successfully connected to Wi-Fi and Particle Cloud, the RGB LED will be cyan (light blue) and "breathing" (slowly blinking).

How does Photon connect to Wi-Fi?

When your Photon is powered on (or restarted), it will automatically try to connect to a Wi-Fi network. It does this by using its saved list of Wi-Fi logins (network names and passwords). Every Photon can be programmed to store login information for up to 5 different Wi-Fi networks.

A brand new Photon will not have any Wi-Fi logins saved yet. However, the Photon provided to you by your teacher will most likely already have a Wi-Fi login programmed into it.

What is Particle Cloud?

Once your Photon is connected to Wi-Fi, the Photon will automatically try to connect to Particle Cloud, which is a cloud service that Particle provides for all of its microcontroller devices. All of your Photon's internet communications are routed through Particle Cloud.

Particle Cloud can be used to:

• Code and store all your different Photon device apps (using Particle Build code editor)

• Update the app stored on your Photon device

• Update the firmware on your Photon device

• Send and receive data between your Photon device app and your web app

• Manage your Photon device remotely

In this first tutorial, you'll become familiar with your team's IoT electronics kit.

Tutorial Goals

The goals of this first tutorial are to help you:

• Understand the features of your Photon circuit board (pins, ports, buttons, LED lights)

• Identify the other components in your Photon kit and their purposes (inputs, outputs, connectors, and cables)

• Understand how to create electronic circuits by connecting components to the Photon circuit board (using power pins, I/O pins, jumper wires, and breadboard)

Photon Kit

This guidebook is tailored for an IoT electronics kit called the SparkFun Inventor's Kit for Photon, which will simply be referred to as the Photon kit.

SparkFun is a company that sells products to help people build and program electronics devices. Photon is a Wi-Fi enabled microcontroller (small computer) from a company called Particle that sells IoT hardware and services that help inventors and other companies create their own IoT products.

SparkFun created its own Photon kit by incorporating the Photon P1 microcontroller into an easy-to-use circuit board and packaged it with a set of inputs, outputs, wires, and other parts to help you start inventing your own IoT devices. It is also possible to purchase additional parts (sensors, motors, etc.) that can be used with this Photon kit.

This IoT Code Guidebook is a supplement the .

What's in this Guidebook?

This guidebook contains a series of IoT code tutorials to help you get familiar with using your IoT electronics kit to build smart devices and program apps for them.

In addition, this guidebook contains coding references to help show and explain how to create a device app and web app that interact with each other through the internet. There are also references that show and explain how to connect specific inputs and outputs to your device and how to add code in your device app to control the inputs and outputs.

Finally, this guidebook also contains links to external resources, such as an online code editor (web IDE) for creating your device app, programming language references, and additional experiments for learning how to use your IoT kit.

Your IoT Electronics Kit

This guidebook is tailored for an IoT electronics kit called the , which will simply be referred to as the Photon kit.

SparkFun sells a variety of other sensors and outputs that can be used with the Photon kit. If possible, it is highly recommended to add an to the kit for more design possibilities.

Copyright and License

Copyright © 2016-2021 Michael Frontz and Jim Lyst, Indiana University School of Informatics and Computing at IUPUI

This material is part of the high school computer science curriculum developed for the program, an award-winning community partnership in central Indiana that is broadening student participation in computing and helping students develop the skills essential for success in the 21st century workplace. The iDEW program is managed by the .

This work is licensed under a . You are free to use, share, or adapt this material for noncommercial purposes as long as you provide proper attribution and distribute any copies or adaptations under this same license.

Next you'll add a command in your app code to designate the LED pin as an output.

Set Pin Mode for LED

A variety of inputs and outputs can be connected to the I/O pins on your Photon circuit board. Your app code needs to identify which I/O pins are being used and whether each of these pins will be used for an input or output. This is referred to as setting the pin modes.

You'll need to set the pin mode for the built-in LED that you'll be using. Add this code to your app by inserting it within the setup() function (between the curly braces):

pinMode(LED, OUTPUT);

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D7, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to D7).

2. The mode value, which can be INPUT, INPUT_PULLUP, or OUTPUT. Your Photon uses this value to change the electrical behavior of the pin, so the pin can either receive signals from an input or send signals to an output. In this case, the mode was set to OUTPUT because your app will be sending "on" and "off" signals to the LED light.

At this point, your app code should look similar to this:

int LED = D7;

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

void loop() {

}

Notice that the pinMode() statement shown in the app code above is indented (using the tab key). This is a useful practice when adding code statements within curly braces because it helps make the code easier to read and understand – especially if your app contains many code statements nested within each other.

Verify Your App Code

The Particle Build code editor does NOT check your code syntax as you type, so be sure to periodically verify your code to check for errors.

Verify your app code by clicking the Verify icon in the left navigation bar. (Particle Build will first save your code before verifying it.)

While Particle Build is verifying your code, it will display the message "Compiling code" in the status bar at the bottom of the code editor panel. When the verification process is complete, the status bar will indicate the results:

• If your code compiled without any errors, the status bar will display a success message.

• If your code contains an error, the status bar will display an error message with a description of the error and a link to the specific line number in your code where the error was detected (though sometimes the root cause of the error occurs on a previous line). You'll want to fix the error and then try verifying your code again.

You'll add a variable in your app code to represent the built-in LED light.

Add Global Variable for LED

Your "Hello World" app will make the Photon's built-in blue LED light turn on and off in a blinking pattern. This will be accomplished by sending separate "on" and "off" signals to the LED's pin.

Each I/O pin on the Photon circuit board is identified by a pin number (such as: A0, A1, A2, D0, D1, D2, etc.). In this case, the Photon's built-in blue LED light is connected to pin D7 (via internal circuitry).

When coding a Photon device app, you will typically create a global variable to store a pin number for each input or output connected to your Photon. This will help make your code easier to understand because the variable names help identify each input or output.

You'll need to create a global variable to store the pin number of the built-in LED. Add this code statement to your app by inserting it (as a separate line of code) before the setup() function:

int LED = D7;

This code statement does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this case, the variable will be called LED. You get to decide what to name your variables. Choose names that will make sense to anyone reviewing your code.

3. It assigns a value to the variable. In this case, the variable's value will be equal to D7, which is the pin number for the Photon's built-in LED light.

Notice that this code statement ends with a semi-colon. Typically, each code statement in your app will end with a semi-colon. The semi-colon separates code statements, similar to how periods separate sentences in written English.

• The exceptions to ending with a semi-colon are certain statements (such as functions, conditionals, loops, etc.) that use curly braces to enclose other code statements. However, within the curly braces, each code statement ends with a semi-colon.

Although you can actually list multiple code statements on the same line (because their semi-colons will separate them), each code statement is traditionally listed on its own separate line to make it easier to read the code.

Save Your App Code

The Particle Build code editor does NOT autosave your work as you type, so be sure to periodically save your code.

Save your app code by clicking the Save icon in the left navigation bar.

Tips for Naming Variables

You get to decide what to name each variable in your app's code. However, here are a few rules and recommendations to help you name your variables:

RULES

• Each global variable must have a unique name.

• A variable's name cannot be one of the keywords in the Wiring programming language.

• Variable names must be one word (no spaces allowed).

• Variable names can contain lowercase letters, uppercase letters, numbers, and certain special characters (such as underscores, etc.) – but the name cannot start with a number.

RECOMMENDATIONS

• Make each variable's name concise yet descriptive, so it will be easy to read and understand.

  • Example of variable name that's concise yet descriptive: button

  • Example of variable name that's too concise: b

  • Example of variable name that's too descriptive: greenbuttonthatturnslighton

• If your variable name combines multiple words, you can make the name easier to read by either using an underscore between words – or using "camelCase" (lowercase letters, but new words start with an uppercase letter).

  • Examples of variable names using underscores: red_light, motion_sensor

  • Examples of variable names using camelCase: redLight, motionSensor

• If you have multiple inputs or outputs of the same type (multiple LED lights, multiple buttons, etc.), add an adjective or number to their variable names to help identify them in your app code.

  • Examples of variable names with adjectives: redLED, blueLED

  • Examples of variable names with numbers: button1, button2

Let's title your new app template, and learn about the basic code structure for Photon device apps.

Title Your App

In the Code menu panel, you'll notice that your current app doesn't have a title yet.

It's recommended to give each app a unique title. Particle Build will allow you to save different apps that have the same title – but this could get confusing, so try to use unique app titles.

NOTE: You cannot have any blank spaces in an app's title. If you want to visually separate words in your app's title, just use a hyphen or an underscore.

Enter hello-world as your app's title.

You'll see the app's title show up in the "My Apps" list.

Photon App Structure

Your code editor should show the basic structure for a new Photon device app:

Setup Function

Every Photon device app must have one (and only one) setup() function. You can add lines of code between this function's opening and closing curly braces.

The setup() function will run one time when your app first starts (which is when your Photon is first powered on – or is restarted using its Reset button).

The code added within the setup() function typically sets pin modes for the device's inputs and outputs, initializes settings for certain inputs and outputs, or performs other "setup" actions that need to occur at the start of the program.

Even if you didn't add any code within the setup() function, your app must still have this function.

Loop Function

Every Photon device app must have one (and only one) loop() function. You can add lines of code between this function's opening and closing curly braces.

After the setup() function is done running, the loop() function will start to run. When all the code within the loop() function has been performed, the loop() function will automatically run itself again. It keeps running in an endless loop (until the device is restarted or powered off).

The code added within the loop() function performs the main tasks of your program.

Even if you didn't add any code within the loop() function, your app must still have this function.

Other Sections of App

Besides having the required setup() and loop() functions, your Photon device apps will typically have some or all of the following:

• Comments

• Libraries

• Global Variables

• Custom Functions

Comments

Comments are optional notes that you can insert to help explain or clarify portions of the code to anyone reviewing the program. Comments can be or .

Any comments in the app are ignored when the program is compiled and uploaded to your device.

Libraries

Some device apps might include (i.e., import) one or more library files. A library is a file of pre-built code that provides additional functions that your program can utilize. For example, certain inputs and outputs have their own code library with functions to make it easier to control the input or output.

Particle Build has a Libraries menu where you can search for existing libraries (or upload your own library file that you've created). When you select a library to be added to your app, Particle Build will automatically insert an statement for the library at the beginning of your app code.

Global Variables

Your device app will typically have code that declares global variables which store data used in your program's functions, such as pin numbers for sensors, etc.

Global variables are usually listed before the setup() function (to make it easier to read the code).

Custom Functions

You can also add your own custom functions to your device app. Each custom function must have a unique function name.

Custom functions are used to contain code that performs specific tasks or subtasks. Custom functions are optional, but they can help break up your code into smaller modules that are easier to understand (and easier to re-use). So rather than listing all your main program code within the loop() function, you can subdivide some or all the code into custom functions.

The code within a custom function is only run if and when that custom function is "called" (by listing the function's name) within the setup() or loop() function. A custom function can also be "called" within another custom function.

Custom functions are usually listed after the loop() function (to make it easier to read the code).

Next you'll flash your "Hello World" app to your Photon device to run the app.

Flash App to Photon

Be sure your Photon is powered on and connected to Wi-Fi and Particle Cloud.

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar. (Particle Build will first save and verify your code before flashing it.)

Your Photon will download the app from Particle Cloud over Wi-Fi and store the app in your Photon's flash memory. While this is occurring, you should see that the RGB light on your Photon's circuit board will blink pink.

Once the download is complete, your Photon will automatically restart itself. You'll see the RGB light on your Photon blink green while it tries to reconnect to Wi-Fi. Once your Photon has reconnected to Wi-Fi and Particle Cloud, the RGB will be "breathing" cyan (light blue).

Confirm App Works

Once your Photon has downloaded the new app and restarted, your new app will automatically start running:

• Confirm that the blue D7 LED light on your Photon's circuit board blinks on and off in a repeating pattern (with the light turning on for 1 second and then turning off for 1 second).

If so, then you've successfully programmed the "Hello World" app for your Photon device. Your teacher may want to see your Photon device to confirm that your team's app is working.

Your Photon kit includes a motion sensor that uses passive infrared (PIR) light to detect movement in the surrounding environment up to 10 feet away.

In this step, your team will connect the motion sensor to your Photon circuit board using the breadboard.

You'll need these components:

• Motion sensor (with 3-pin connector)

• 3 jumper wires (use different colors to help identify them; it may help to match the sensor wires)

Follow these instructions explaining how to connect the motion sensor. The sensor can be connected to almost any I/O pin, but connect it to the D3 pin (which will be different from the wiring diagram).

Physical buttons that people can push are used as inputs on many different types of devices. Your Photon kit should have a set of 4 push buttons with different cap colors: red, yellow, green, and blue.

In this step, your team will connect a push button to your Photon circuit board using the breadboard.

You'll need these components:

• 1 push button (could be any color, but use same color as your LED)

• 2 jumper wires (use two different colors to help identify them)

. The button can be connected to almost any I/O pin, but connect it to the D2 pin (which will match the wiring diagram).

LEDs (light-emitting diodes) are small, bright, long-lasting, energy-efficient lights. Your Photon kit has a set of LED lights with different bulb colors: red, yellow, green, and blue.

In this first step, your team will connect an LED light to your Photon circuit board using the breadboard.

You'll need these components:

• 1 LED light (any color)

• 1 resistor

• 2 jumper wires (use two different colors to help identify them)

. The LED can be connected to almost any I/O pin, but connect it to the D0 pin (which will match the wiring diagram).

Next, you'll create a web app that will interact with your Smart Security device through Particle Cloud.

Your web app will consist of an HTML file namedindex.html, a CSS file named style.css, and a JavaScript file named script.js.

Remember that Particle Build is only used to code your Photon device app. You'll need to use a different code editor to create the HTML, CSS, and JS files for your web app. Consult your teacher to determine which code editor will be most appropriate to use for your web app files.

Add Starter HTML

, and paste it into a blank HTML file named index.html.

The starter HTML contains blank lines where you'll add custom HTML for your specific web app.

Add Custom HTML

Copy this HTML, and paste it into the blank lines within the <body> of your starter HTML code:

Preview Web App

If you preview the web app at this point, it's very plain (because there's no CSS in the style.css file) and it doesn't function yet (because there's no JS in the code.js file).

Next, you'll add the CSS for your web app's stylesheet.

Add CSS

Copy this CSS, and paste it into a blank CSS file named style.css:

As you can see, this CSS has style declarations for 4 types of elements in your HTML:

1. The CSS for body styles the <body> section in your HTML.

2. The CSS for .card styles elements in your HTML that have class="card". The <div> element has this class.

3. The CSS for .light-on styles any elements in your HTML that have class="light-on". Currently, no elements have this class. However, your web app JS will add this class to the <div> element if your light is turned on (changing the card's background color to yellow) and will remove this class if your light is turned off (changing the card's background color back to gray).

4. The CSS for button styles the <button> element in your HTML.

Preview Web App

If you preview the web app at this point, you can see how the CSS has changed the appearance of the web app, but it still doesn't function yet (because there's still no JS in the code.js file).

Here are references for how to connect and code each physical output in your SparkFun Photon kit:

Here are references for how to connect and code each physical input in your SparkFun Photon kit:

• (not standard part of SparkFun Photon kit, but your teacher may have added it)

Now that your Photon is connected to Wi-Fi and Particle Cloud, your team will log in to Particle Build, the code editor that will be used to create your "Hello World" app.

What is Particle Build?

Particle Build is an online code editor (web IDE) provided by Particle. Particle Build is part of the Particle Cloud platform. You will use Particle Build to code and store all your Photon device apps.

The Photon device itself can only store and run one app at a time. However, you can create and save multiple apps in Particle Build. When you need to update the specific app stored on your Photon device, you'll do this in Particle Build – and your Photon will download the new app over Wi-Fi.

Your team will need a Particle account to log in to Particle Build. However, your teacher will most likely provide your team with an existing Particle account login (email & password) that's already associated with your specific Photon device. Every Photon has a unique device ID it uses to communicate with Particle Cloud, and each device ID can only be associated with one Particle account.

Log In to Particle Build

One person on your team should log in to Particle Build using your team's Particle account login.

Once you're logged in, you'll see the Particle Build code editor, which defaults to the "Code" menu and shows a blank app template.

User Interface

The user interface for Particle Build is divided into 4 sections:

• On the far left is a vertical navigation bar with icons.

• On the middle left is a menu panel showing options for the current navigation selection.

• On the right side is the code editor panel showing the code for your current app.

• On the bottom of the code editor panel is a horizontal status bar that displays messages.

Navigation Bar

If you hover your mouse pointer over an icon in the navigation bar, the icon's name will be displayed. Here is a summary of the navigation icons from top to bottom:

Toggle the Menu Panel

The middle menu panel can be toggled between "show" and "hide" by clicking the same navigation icon repeatedly.

In the left navigation bar, click the Code icon.

The middle menu panel will become hidden.

Click the Code icon again to show the menu panel again.

In general, you'll probably want to keep the menu panel shown – but if you want extra space for your code editor panel, you can temporarily hide the menu panel.

View Devices Menu

In the left navigation bar, click the Devices icon.

The middle menu panel will list your Particle devices. You should see a device name listed under P1 (because your device is a Photon P1). Your device's connection status is shown as a colored dot to the right of its name. If your device is connected to Wi-Fi and Particle Cloud, the dot should be cyan (light blue) and "breathing" (slowly blinking) – just like the RGB LED on your Photon circuit board.

Click the drop-down arrow to the right of the device's connection status dot. This will show additional information about your device:

• You'll see the device ID, which is a unique ID used by your device to interact with Particle Cloud. Later when you create web apps to interact with your device, you'll need your device ID.

• You'll see the firmware version that is currently saved on your device. If an updated version is available, your device's firmware will be automatically updated the next time you flash an app.

Signal Device

If you wanted to double-check your device and its connection (imagine you had multiple devices), an easy way is to signal it from Particle Build.

Click the Signal button. Particle Cloud will send a signal to your device over Wi-Fi. Your Photon's RGB LED will respond by cycling through a rainbow of colors.

Click the button again to stop signaling your device. Your Photon's RGB will return to breathing cyan.

Return to Code Menu

In the left navigation bar, click the Code icon to return to your list of apps.

In this fourth tutorial, you'll modify your "Smart Light" device into a "Smart Security" device and program new apps for the device.

Tutorial Goals

The goals of this fourth tutorial are to help you:

• Gain further experience by creating another practice IoT device and programming its apps

• Become better prepared to create your own IoT device and apps for your team project

Smart Security System

For decades, security systems have been used to monitor homes and businesses for emergencies (burglary, fire, flood, etc.). These systems use some combination of: motion sensors, door/window sensors, glass break sensors, video cameras, smoke detectors, flood sensors, etc. Today, many security systems are being connected to the internet to offer additional features.

You'll create a prototype of a Smart Security device by modifying your Smart Light device (which has an LED light and push button) to add a motion sensor and a speaker:

• The LED light will be used to indicate whether the security system is currently "armed" (LED is on) or "disarmed" (LED is off).

• The push button will be used to switch the security system between "armed" and "disarmed" mode. (The button will simulate a security system's keypad, which is used to enter a numeric passcode. For this prototype device, you'll simply press the button to toggle the system between modes, as if you had correctly entered a passcode.)

• The motion sensor will detect whether something is moving within the surrounding area.

• The speaker will be used to produce an alarm sound if motion is detected.

You'll use a copy of your Smart Light device app as starter code for your Smart Security device app. You'll modify the existing code controlling the LED and button before adding new code to control the motion sensor and speaker.

You'll also program a web app that interacts with your Photon over the internet to perform these tasks:

• Monitor the security system's current mode ("armed" or "disarmed")

• Remotely toggle the security system between "armed" or "disarmed" mode

• Receive an event notification if the security system detects motion

• View the date and time of the last motion event detected

Next, you'll add code in your Smart Security device app to control the speaker.

The basic steps to control a speaker in your app code are:

1. Declare a global variable to store the I/O pin number for the speaker.

2. Set the pin mode for the speaker pin in the setup() function.

3. Use tone() statements to produce sounds.

Global Variable for Speaker

Declare a global variable to store the I/O pin number for the speaker by adding this code statement before the setup() function:

int speaker = D1;

If you connected your speaker to a different I/O pin other than D1, then modify this code statement to list the correct pin number for your speaker.

Set Pin Mode for Speaker

Set the pin mode for your speaker pin by adding this code statement within the setup() function (between the curly braces):

pinMode(speaker, OUTPUT);

Produce Tone using Speaker

The speaker will be used to produce an "alarm sound" if the motion sensor detects motion.

The tone() method is used to produce a sound of a specific frequency (pitch) for a specific duration of time. The speaker can produce tones ranging in frequency from 20Hz (very low pitch) to 20KHz (very high pitch), covering the full range of sounds that humans can hear.

Add this code statement within your checkMotion() custom function (inside the curly braces of the if statement that checks the value of motionState – add the code before the delay()):

tone(speaker, 1000, 250);

The tone() method requires three parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D1, etc.) or a variable that stores a pin number. In this case, the variable named speaker is listed.

2. The frequency for the tone, which can be an integer value (whole number) or a variable that stores an integer. The value can be between 20-20000 hertz. Lower numbers will have a lower pitch, while higher numbers will have a higher pitch. In this case, the frequency will be 1000 hertz, which will be a "less annoying" pitch than what an alarm sound would typically use.

3. The duration for the tone, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds that the tone will be played (1000 ms = 1 second). In this case, the duration will be 250 ms (0.25 seconds), which will be a much shorter duration than what an alarm sound would typically use.

Flash App to Device

Be sure your Photon device is connected to Wi-Fi and Particle Cloud.

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar. (Particle Build will first save and verify your code before flashing it.)

Once your Photon has downloaded the new app and restarted, the updated app will start running:

• Press the button to "arm" your Smart Security device. (This simulates having entered a passcode into a keypad to arm the device.) The LED light should turn on when the device is in "armed" mode. Confirm that the speaker produces an alarm sound when motion is detected. The sensor should be able to detect motion in the environment up to 10 feet away.

• Press the button again to "disarm" the device (the LED should turn off). Because of the 2 second delay required when motion is detected, you may have to press the button more than once (or hold the button down slightly longer). Once the device is in "disarmed" mode, confirm that motion near the sensor does not produce an alarm sound.

In this third tutorial, you'll create a "Smart Light" device and program its apps.

Tutorial Goals

The goals of this third tutorial are to help you:

• Practice connecting physical inputs and outputs to your Photon device

• Program a Photon app that controls your device's physical inputs and outputs

• Program a web app that interacts with your Photon device through Particle Cloud

What is a Smart Light?

The Philips Hue smart light bulb was introduced in 2012. Today, there are several companies that offer smart light bulb systems.

From the outside, a smart light bulb looks like a regular light bulb. However, what seems like a simple light bulb is actually a full-fledged IoT device: inside the bulb are multiple LED lights wired to a microcontroller circuit board that connects to your Wi-Fi network.

The smart light interacts with a mobile app that allows you to control an individual light or a group of lights. The mobile app might offer features such as:

• Remotely turn the light(s) on or off

• Set automatic timers to turn the light(s) on or off at specific times

• Adjust the brightness of the light(s)

• Change the color of the light(s)

• Sync the light(s) to music, movies, or games

• Control the light(s) using a voice assistant (such as: Alexa, Siri, etc.)

For this tutorial, you'll create a prototype of a Smart Light device using one LED. Your device will include a button to manually turn the light on or off. You'll program a Photon device app to control the LED using the button. You'll also program a web app that interacts with your Photon device over the internet to monitor the light's status and to allow you to remotely turn the light on or off.

Your last step is to modify the "Hello World" app, as some extra practice.

Modify App Code

In Particle Build, modify the code within the loop() function to change the LED blinking pattern. Here are some possible options your team could choose:

• Make the D7 LED blink faster

• Make the D7 LED blink slower

• Make the D7 LED blink in a different pattern (such as two quick blinks followed by a longer pause)

Add Comment

It's recommended to add a comment at the very beginning of your code to list a title for your app, plus any other information that might be helpful to you or to anyone else reviewing the program code.

For example, this comment could list your app's title, your team's information (team name and/or team members), your teacher's name, and your class period.

Add a block comment at the beginning of your app code before the setup() function:

/*
Hello World Test
Team Info
Teacher - Class Period
*/

Modify this comment to list your specific information. Check with your teacher to find out if there is other information that should be listed within this block comment.

Flash Modified App

Flash your modified app to your Photon to confirm it does what you intended it to do.

Your teacher may want to see your modified app code running on your Photon.

Download Copy of App

If you need to download a copy of your app code to your computer in order to submit it to your teacher, there are two different download icons shown in the Code Menu panel:

1. The first icon (cloud with download arrow) to the right of "Current App" is used to download the compiled version of the app (firmware binary).

2. The second icon (angle brackets with download arrow) to the right of "Files" is used to download a zip file containing your app source code (.ino file).

Click the second download icon to download a zip file containing your app source code:

In this case, the zip file will be named hello-world.zip. You'll need to uncompress the zip file to get your app source code file, which will be named hello-word.ino. If necessary, this .ino file can be opened in a text editor on your computer.

Going Further

In the next tutorial, you'll start connect an input and output to your Photon to create a "Smart Light" device.

Your Photon kit includes a small speaker that can produce tones or play simple music (note by note).

In this step, your team will connect the speaker to your Photon circuit board using the breadboard.

You'll need these components:

• Speaker

• 2 jumper wires (use different colors to help identify them)

​Follow these instructions explaining how to connect the speaker. The speaker can be connected to any I/O pin capable of PWM, but connect it to the D1 pin (which will be different from the wiring diagram).

Circuit Board

The SparkFun Photon kit contains a printed circuit board (PCB) that incorporates the Particle Photon P1 microcontroller, which will act like the “brain” of your IoT device. This circuit board also has various pins, ports, buttons, and LED lights. SparkFun refers to this circuit board as the Photon RedBoard (because of its color).

You can connect various inputs (such as: sensors, buttons, etc.) and outputs (such as: motors, lights, etc.) to the pins on the circuit board to create a device. Then you can control your device by programming an app that will run on the Photon microcontroller.

SparkFun Photon RedBoard

• Photon P1 Microcontroller

• Input/Output Pins

• Power Supply Ports and Pins

• Buttons

• LED Lights

Photon Microcontroller

A microcontroller is a small computer on a single integrated circuit that contains a processor (CPU), memory, storage, and programmable input/output pins. The Photon microcontroller also has an integrated Wi-Fi chip and antenna, which makes it great for IoT devices.

Photon P1 Tech Specs

• CPU: 32-bit 120Mhz ARM Cortex M3

• Memory: 128KB RAM

• Storage: 1MB Flash

• Wi-Fi: 2.4GHz 802.11b/g/n

Compared to the tech specs of a "regular" computer, a microcontroller is much less powerful – it has a slower processor, less memory, and less storage. This is because microcontrollers are used in devices that have dedicated functions (such as: automobile engine control systems, medical devices, office machines, appliances, etc.). These dedicated devices typically don’t require as much computing power.

Firmware and Device App

A microcontroller is controlled by its firmware, which acts as its operating system. Periodically, your Photon will need to update its firmware. If this is necessary, the firmware update will occur automatically when you download a new app to your Photon over Wi-Fi.

A microcontroller is designed to store only one app, which will run automatically. If you need to change your Photon device's app, the new app has to be downloaded over Wi-Fi (and will replace the old app). You will have to code the apps for your Photon – though you'll get some practice and help to do so.

Particle Cloud

When the Photon is powered on, it will automatically try to connect to Wi-Fi (using a programmed list of Wi-Fi network logins). Once the Photon is connected to Wi-Fi, it will automatically try to connect to Particle Cloud, which is a cloud service that Particle provides for all of its microcontroller devices. All of the Photon's internet communications are routed through Particle Cloud.

Particle Cloud can be used to:

• Code and store all your different Photon device apps (using online Particle Build code editor)

• Update the app stored on your Photon device

• Update the firmware on your Photon device

• Send and receive data between your Photon device app and your web app

• Manage your Photon device remotely

Input/Output Pins

The Photon circuit board has numerous I/O pins used to connect various inputs (such as: sensors, buttons, etc.) and outputs (such as: motors, lights, etc.). These I/O pins have small plugs that allow you to easily connect (and disconnect) the wires for inputs and outputs.

Digital Pins

The circuit board has a set of digital pins labeled as: D0, D1, D2, D3, D4, D5, D6, D7. Digital pins are used to connect inputs or outputs that use binary values (such as: HIGH or LOW, etc.). For example:

• Digital Input: A motion sensor detects either "motion" or "no motion."

• Digital Output: A LED light can be set to be "on" or "off."

Analog Pins

The circuit board has a set of analog pins labeled as: A0, A1, A2, A3, A4, A5. Analog pins are used to connect inputs or outputs that use a range of values (such as: 0-255, etc.) For example:

• Analog Input: A photocell can detect a range of values based on the amount of light measured.

• Analog Output: A speaker can produce a range of tones that have different frequencies.

Analog Output Using PWM

Any analog pin can be used for analog inputs. However, only certain pins can be used for analog outputs. (Confusingly, some of the pins capable of analog output are labeled as digital pins.)

The Photon uses (PWM) to make a digital output signal (which has only two values: HIGH or LOW) act like an analog output signal (which has a range of values). Certain outputs (such as: speaker, servo motor, etc.) require a connection to an I/O pin capable of PWM.

These Photon pins can be used as analog outputs using PWM: A4, A5, D0, D1, D2, D3, RX, TX, WKP.

Special Pins

The circuit board also has I/O pins with "special" labels. Most of these "special" pins are used to connect with parts that require specific data communication protocols:

• SPI Pins: SS/A2, SCK/A3, MISO/A4, MOSI/A5

  • SPI stands for "Serial Peripheral Interface"

  • For example, a Micro OLED display would be connected using the SPI pins.

• I2C Pins: SDA/D0, SCL/D1

  • I2C stands for "Inter-Integrated Circuit"

  • For example, an accelerometer would be connected using the I2C pins.

• UART Pins: RX, TX

  • UART stands for "Universal Asynchronous Receiver-Transmitter"

  • For example, a fingerprint scanner would be connected using the UART pins.

However, any of these "special" pins can also be used as "regular" I/O pins.

Power Supply Ports and Pins

The Photon circuit board must receive power from an external power source (such as: USB, battery, or outlet). The Photon circuit board will then supply power to any connected inputs and outputs.

Power Supply Ports

The Photon circuit board can receive power through either one of its power supply ports:

• Barrel Jack: A barrel jack adapter can be plugged in to provide power from an external supply such as a battery, outlet, etc.

• Micro-USB: A Micro-USB cable can be plugged in to provide power from a computer's USB port, USB charger, etc.

Power Supply Pins

The Photon circuit board can supply power to connected inputs and outputs through these pins:

POSITIVE PINS

• I/O Pins: These pins can supply 3.3 volts (by reducing the incoming voltage from the USB or barrel jack power source). Certain inputs and outputs (but not all) get their power from an I/O pin.

• 3.3V: This pin supplies 3.3 volts (by reducing the incoming voltage from the USB or barrel jack power source).

• V-USB: If a power source is connected to the Micro-USB port, this pin supplies ~5 volts.

• VIN: If an external power supply is connected to the barrel jack, this pin supplies the same voltage as the external supply (which could range from 4.5-15 volts). For example, if a 9V battery adapter were plugged into the barrel jack, this pin would supply 9 volts. If a USB adapter were plugged into the barrel jack, this pin would supply ~5 volts.

NEGATIVE PINS

• GND: This pin acts as the ground (negative terminal) when powering inputs and outputs. The Photon circuit board has 3 available GND pins.

A breadboard can be used to connect multiple inputs and outputs to the same power supply pins. Section 1.3 of this tutorial will explain how this works.

Buttons

The Photon circuit board has two built-in buttons used for special purposes:

• Mode: This button is used to switch your Photon between different modes such as: Connected, Listening, Safe, and Device Firmware Upgrade. Normally, you will not need to use this button.

• Reset: This button can be used to restart your Photon – forcing it to reconnect to the internet and restart its device app. Occasionally, you might use this button to restart your app.

LED Lights

The Photon circuit board has three built-in LED lights:

• Power: This red LED indicates the Photon is receiving power (from the barrel jack or USB). If this LED is off, then no power source is connected (or the Photon device is damaged).

• RGB: This LED changes its to indicate the current mode and connection status of the Photon device.

• D7: This blue LED is connected to the D7 pin and can be controlled by your Photon device app, which can be helpful for testing purposes.

Normal RGB Patterns

Whenever you connect a power source to the Photon (or restart it using the Reset button), the Photon should power on, connect to Wi-Fi, connect to Particle Cloud, and start running its device app.

During this startup process, the RGB color will change from green to cyan (light blue) and the RGB activity will change from "blinking" (fast blinking) to "breathing" (slow blinking).

Whenever the device app or firmware on the Photon is updated, the RGB will blink pink during the download and installation. Once the update is complete, the Photon will automatically restart itself.

Other RGB Patterns

If your Photon device displays one of these other RGB patterns, then the Photon has encountered an issue or has been placed into a different mode. Consult your teacher to troubleshoot your device.

More Info

The provides more details about this circuit board.

Electronic Circuits

Each input and output connected to your Photon circuit board must form an , which is a continuous path that conducts electricity from the positive (+) terminal of a power source, through the input or output, and back to the negative (-) terminal of the power source.

Electronic vs. Electric

An electronic circuit is a special type of electric circuit. Here are the two key differences:

1. VOLTAGE & CURRENT

The current in an electric circuit could be only a few volts, or it could be hundreds of volts (or more). Some electric circuits operate on , while others use .

Electronic circuits always operate on low voltage direct current.

2. PURPOSE

Electric circuits transfer electricity to components (such as: light bulbs, motors, etc.) that transform some of the electrical energy into other types of energy (such as: light, motion, etc.) in order to perform a useful physical task.

Electronic circuits have special components with that use electrical signals to process and transfer information.

The electronic circuits in your IoT devices will actually do both: they will perform a useful physical task by processing and transferring information.

Parallel Circuits

Each input and output connected to your Photon should have its own circuit – i.e., its own separate path to conduct electricity without having to travel through another input or output. These are called parallel circuits. Using parallel circuits has these advantages:

• Parallel circuits ensure each input and output receives its full voltage from the circuit board (because the voltage is not being split with another input or output on the same circuit).

• Parallel circuits allow each input and output to be independently controlled by the circuit board.

For each parallel circuit, most of the conductive path will consist of jumper wires and the breadboard (via its internal metal strips). The rest of the conductive path will include the input or output itself (via its internal wires or circuitry) and the circuit board (via its power pins, I/O pins, and other internal circuitry).

Power for Circuit Board

The power for your circuits will be supplied by the Photon circuit board, which itself must receive power from another source.

The Photon circuit board can receive power through either one of its power supply ports:

• Barrel Jack: A barrel jack adapter can be plugged in to provide power from an external supply such as a battery, outlet, etc.

• Micro-USB: A Micro-USB cable can be plugged in to provide power from a computer's USB port or a USB charger.

Power for Inputs and Outputs

The Photon circuit board can supply power to inputs and outputs through these pins:

Positive Pins

• I/O Pins: These pins can supply 3.3 volts (by reducing the incoming voltage from the USB or barrel jack power source). Only certain inputs and outputs will get their power from an I/O pin.

• 3.3V: This pin supplies 3.3 volts (by reducing the incoming voltage from the USB or barrel jack power source).

• V-USB: If a power source is connected to the Micro-USB port, this pin supplies ~5 volts.

• VIN: If a power source is connected to the barrel jack, this pin supplies the same voltage as the external source (which could range from 4.5-15 volts). For example, if a 9V battery with adapter were plugged into the barrel jack, this pin would supply 9 volts. If a USB adapter were plugged into the barrel jack, this pin would supply ~5 volts.

Negative Pins

• GND: This pin acts as the ground (negative terminal) when powering inputs and outputs. The Photon circuit board has 3 available GND pins.

Breadboard

A breadboard has a large number of additional pins (plugs) that are useful for connecting inputs and outputs to your circuit board. First, your inputs and outputs connect to pins in the breadboard, and then jumper wires are used to help connect those breadboard pins to specific pins on your circuit board.

One purpose of using a breadboard is it allows you to connect multiple inputs and outputs to some of the same power supply pins – while still ensuring each input and output has its own parallel circuit.

For example, the Photon circuit board has only one V-USB pin to supply 5V of power, but your device might have multiple inputs and outputs that require 5V – so the breadboard can be used to allow these components to share this one V-USB pin.

Anatomy of Breadboard

To understand how a breadboard works and is used, you need to understand the "anatomy" of your breadboard. The image on the left below shows an external view of your breadboard, while the image on the right shows what's inside the breadboard:

First, let's examine the external view of your breadboard. While the breadboard might seem like one large rectangle of holes, it actually consists of 4 smaller rectangular sections:

1. On the far left is a power rail consisting of two columns of pins: one column is labeled as positive (+) and the other column is labeled as negative (-).

2. In the left center is a set of terminal strips consisting of rows of pins: each row is numbered (from 1-30) and the pins within each row are lettered (from A-E).

3. In the right center is another set of terminal strips consisting of rows of pins: each row is numbered (from 1-30) and the pins within each row are lettered (from F-J). Notice there is a divide between the left set of terminal strips and the right set of terminal strips.

4. On the far right is another power rail consisting of two columns of pins: one column is labeled as positive (+) and the other column is labeled as negative (-).

Inside the breadboard, there are metal strips underneath the pin holes. The image of the internal view shows these metal strips – and makes it easier to visualize the 4 separate sections of the breadboard. (The red arrows are pointing to the metal strips under the power rails.)

When you plug a wire into a breadboard pin, the wire makes contact with the specific metal strip underneath that pin hole location. If another wire is plugged into another pin along the same metal strip, the metal strip will allow electricity to be conducted between the wires. If the wires are touching different metal strips, then the wires are NOT connected to each other.

These metal strips inside the breadboard act like additional wires. While these metal strips may be "hidden" inside your breadboard, they become part of your circuits as you connect inputs and outputs.

Here are some examples to help explain further how the terminal strips and power rails work:

TERMINAL STRIPS

• If you were to plug a wire into pin A of row 1 and then plug another wire into pin E of row 1, these wires would be connected because they're touching the same metal strip.

• If you were to plug a wire into pin A of row 1 and then plug another wire into pin F of row 1, these wires would NOT be connected because they're touching different metal strips. Remember that the terminal strip rows on the left and right sides are separate from each other.

• If you were to plug a wire into pin A of row 1 and then plug another wire into pin A of row 2, these wires would NOT be connected because they're touching different metal strips. Remember that the terminal strip rows are separate from each other.

POWER RAILS

• If you were to plug a wire into a pin of the positive (+) column of the left power rail and then plug another wire into another pin in the positive (+) column of the left power rail, these wires would be connected because they're touching the same metal strip.

• If you were to plug a wire into a pin of the positive (+) column of the left power rail and then plug another wire into a pin of the negative (-) column of the left power rail, these wires would NOT be connected because they're touching different metal strips.

• If you were to plug a wire into a pin of the positive (+) column of the left power rail and then plug another wire into a pin of the positive (+) column of the right power rail, these wires would NOT be connected because they're touching different metal strips.

Connecting Inputs and Outputs

Certain inputs or outputs can be connected directly to pins on the Photon circuit board. However, in most cases, you'll need to use the breadboard to help connect some (or all) of your inputs and outputs.

Each input or output has at least 2 wires that must be connected (one for positive and the other for negative). Some inputs or outputs have additional wires used for sending or receiving signals.

The wires for inputs and outputs connect to the pins of different terminal strips. Then jumper wires are used to connect each of these terminal strips directly (or indirectly) to its corresponding power pin or I/O pin on the Photon circuit board.

Here are two basic rules for connecting inputs and outputs to the breadboard:

• Different wires for the same component should NOT connect to pins in the same terminal strip. For example, the temperature sensor has 4 wires that should connect to different terminal strips.

  • Jumper wires are the only exception to this rule: a jumper wire is supposed to share a terminal strip with a wire of an input or output in order to connect it directly (or indirectly) to its corresponding power pin or I/O pin on the circuit board.

• Wires for different components should NOT connect to pins in the same terminal strip. For example, the wires of a push button and LED light should connect to different terminal strips.

  • are the only exception to this rule: a resistor is supposed to share a terminal strip with a wire of an input or output because the purpose of the resistor is to limit the amount of electric current flowing through the input or output to prevent damaging them. The LED lights and photocell (light sensor) in your Photon kit require the use of resistors.

Connecting Power Rails

Think of each power rail like a power strip you might use at home or school: you first have to plug the power strip into an outlet, and then the power strip can provide power to other devices plugged into it. Since your breadboard has two power rails (far left and far right), it's like having two power strips.

Some IoT devices won't need to use either power rail on the breadboard. However, most IoT devices will use one of the power rails. A few IoT devices might need to use both power rails (e.g., if your device has multiple components needing 3.3V as well as multiple components needing 5V).

In order to use a power rail on the breadboard to supply power to inputs or outputs, you must first use jumper wires to connect the power rail to power pins on the Photon circuit board:

• The positive (+) column of the power rail would connect to a positive (+) pin on the Photon board (such as the 3.3V pin, V-USB pin, or VIN pin – do NOT connect a power rail to an I/O pin).

• The negative (-) column of the power rail would connect to a negative (-) pin on the Photon board (i.e., any one of the GND pins).

Sometimes you might only need to connect the negative (-) column of a power rail. This is because every input and output needs to connect back to GND (and there are only 3 GND pins available on the Photon board). Since certain inputs and outputs use their I/O pin as their voltage source (+), sometimes it might not be necessary to connect and use the positive (+) column of the power rail.

Once a power rail has been connected to power pins on the Photon circuit board, you can use jumper wires to connect multiple inputs and outputs to this same power rail:

• Use a jumper wire to connect the terminal strip for the ground (-) wire of the input or output to any negative (-) pin in the power rail.

• For inputs or outputs that don't get power from their I/O pin, use a jumper wire to connect the terminal strip for the power (+) wire of the input or output to any positive (+) pin in the power rail (as long as the power rail is supplying the correct voltage required by the input or output).

More Info

SparkFun has tutorials that provide more information about circuits and breadboards:

Next, you'll modify your app code to make the button toggle the LED on or off with each button press – similar to how a light switch normally works.

Global Variable for LED Status

You'll add a global variable that track the LED's current status ("off" or "on"). Whenever the button is pressed, this variable will be checked, in order to toggle the LED to the opposite status.

Declare a global variable to store the LED's status by adding this code statement before the setup() function:

This code statement declares a variable named lightStatus which has a data type of , which is the data type used for storing text. The initial value of this variable is made equal to "off".

Turn Off LED in Setup

Since the lightStatus was initially set to "off", let's be sure the LED is turned off when the app starts by adding this code statement within the setup() function (after setting the LED pin mode):

Custom Function to Toggle LED

Let's create a custom function named toggleLight() that will be "called" (performed) whenever the button is pressed.

The toggleLight() custom function will check the current value of lightStatus ("off" or "on") and then toggle the LED and lightStatus to the opposite status.

Add the toggleLight() function after the loop() function (after its closing curly brace):

Now you can "call" (perform) this custom function whenever the button is pushed. A function is "called" by simply listing the function's name as a code statement.

Replace all the existing code within the loop() function (everything inside its curly braces) with this code instead:

Now when the button is pressed, the toggleLight() function will be called, performing the code within that custom function.

Notice that a brief delay() of 175 milliseconds was included. This is necessary to give people just enough time to release the button after pressing it:

• If there is no delay (or the delay is too brief), the device will seem unpredictable because the loop() will repeat so quickly that it toggles the light multiple times for the same button press.

• If the delay is too long, the device will seem unresponsive because the button has to be held down longer before the button press is detected.

So this delay() value shouldn't be too brief or too long – it needs to be just right. A value between 150-200 ms should work well for most people. You can test your button's behavior, and then adjust the specific value higher or lower to make your button seem more responsive.

Flash App to Device

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar.

Once your Photon has downloaded the app and restarted, the updated app will start running:

• Confirm that the LED light toggles between "on" and "off" each time the button is pressed. (If you hold the button down, you'll see the LED continuously toggles between on and off.)

You may notice that occasionally a button press isn't detected immediately. This is normal because there will be occasions when you press the button while the Photon happens to be in the middle of the delay() period. However, if the button seems very unresponsive, you can adjust the delay() value in your app code, and then flash the updated app to your device to test the new value.

At this point, your Photon device should be operating similar to a normal light that can be switched on and off.

Next, you'll use your Smart Light device app as starter code for your Smart Security device app. The LED and button code in the two apps will be nearly identical – you'll just make a few minor changes. After that, you'll be ready to start adding new code for the motion sensor and speaker.

Log In to Particle Build

One person on your team should log in to using your team's Particle account login.

Once you're logged in, you should see a new app template in the code editor. (If not, just click the "Create New App" button in the Code menu panel.)

Title New App

Enter smart-security as your app's title.

Copy Smart Light Code

You'll use your smart-light app as starter code for your smart-security app:

1. The Code menu panel lists all your saved apps under "My apps." Click on your smart-light app to load its code into the code editor panel. (If the Code menu panel is not visible, just click the Code icon in the left navigation bar to show the Code menu panel.)

2. In the code editor panel, select all the existing code in your smart-light app, and copy it.

3. In the Code menu panel, click on your smart-security app listed under "My apps" to load it into the code editor panel. (If the Code menu panel is not visible, just click the Code icon in the left navigation bar to show the Code menu panel.)

4. Select all the existing code in your smart-security app, and then replace it by pasting in the copied code from your other app.

Save your smart-security app code by clicking the Save icon in the left navigation bar.

Modify App Code

The LED and button code in the Photon app will remain essentially the same. You'll just make some minor changes to the lightStatus variable and toggleLight() function:

1. Change the name of lightStatus to deviceMode. There should be 6 places in the code where this change needs to be made.

2. The possible values for lightStatus were "off" or "on". Find the 3 places in the code where "off" is listed, and change each one to "disarmed" instead. There is 1 place in the code where "on" needs to be changed to "armed" instead.

3. Change the name of toggleLight to toggleMode. There should be 4 places in the code where this change needs to be made.

4. In the comments at the top of the code, change Smart Light Device to Smart Security Device.

These modifications do not change how the code functions – it just makes the code make more sense when you read it, since this app will control a Smart Security device (instead of a Smart Light).

Flash App to Device

Be sure your Photon device is connected to Wi-Fi and Particle Cloud.

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar. (Particle Build will first save and verify your code before flashing it to your device.)

Once your Photon has downloaded the new app and restarted, the updated app will start running:

• Confirm that the device still functions like the Smart Light did: the LED light should toggle between on and off each time the button is pressed. When the LED is turned on, it indicates the security system is in "armed" mode. When the LED is turned off, the security system is "disarmed."

In the next steps, you'll add code for the motion sensor and speaker to made the security system fully functional when it's "armed."

Next, you'll add code in your Smart Light device app to control the LED using the push button.

The basic steps to use a push button in your app code are:

1. Declare a global variable to store the I/O pin number for the button.

2. Set the pin mode for the button pin in the setup() function.

3. Use a digitalRead() statement to check whether the button is currently pressed, and add code statements that should be performed if the button is pressed (or not pressed).

Global Variable for Button Pin

Declare a global variable to store the I/O pin number for the button by adding this code statement before the setup() function:

If you connected your button to a different I/O pin other than D2, then modify this code statement to list the correct pin number for your button.

Set Pin Mode for Button

Set the pin mode for your button pin by adding this code statement within the setup() function (between the curly braces):

Turn On LED If Button Pressed

The digitalRead() method is used to check whether a button is currently pressed.

The digitalRead() method will return a value of either LOW or HIGH:

• LOW indicates that the button is currently pressed.

• HIGH indicates that the button is NOT currently pressed.

A variable named buttonState will store the value returned by the digitalRead() method.

An will be used to turn on the LED if the button is being pressed (if buttonState has a value equivalent to LOW).

An will be included to turn off the LED if the button is not being pressed.

Replace all the existing code within the loop() function (everything inside its curly braces) with this code instead:

Flash App to Device

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar.

Once your Photon has downloaded the app and restarted, the updated app will start running:

• Confirm that the LED light that you connected to your Photon circuit board turns on when you press (and hold) the button – and turns off when the button is released.

Of course, nobody would want to continually press a button to keep a light turned on – however, this is a good way to verify that your button is connected correctly. In the next step, you'll modify the app code so the LED light toggles on or off with each button press.

Troubleshooting Issues

If the LED does not turn on when the button is pressed, then there is a mistake in your app code – or a mistake in your wiring connection – or a mistake in both.

If the LED light is turned off and pressing the button has no effect, then verify that one of the button's legs is connected (via a jumper wire) to the same I/O pin number that is assigned to the button variable in your app code. If necessary, change either your wiring or your code, so the pin numbers match. If you revised your code, flash the updated app to your device.

If that still doesn't solve the issue, then double-check all your button wiring by referring back to the connection instructions.

Next you'll add commands in your app code to turn the LED on and off in a repeating pattern.

Turn On LED

Your app can receive signals from inputs using the digitalRead() or analogRead() methods, depending on whether the values being received will be digital or analog.

Your app can send signals to outputs using the digitalWrite() or analogWrite() methods, depending on whether the values being sent will be digital or analog.

The LED can be controlled as a digital output that is either "on" or "off".

You'll need to send an "on" signal to the LED pin. Add this code to your app by inserting it within the loop() function (between the curly braces):

The digitalWrite() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D7, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to D7).

2. The signal value, which can be HIGH or LOW. Your Photon uses this value to send an electrical signal through the pin: HIGH is a signal of 3.3 volts which represents "on," while LOW is a signal of 0 volts which represents "off." In this case, the signal was set to HIGH because you want to turn on the LED light.

Add Time Delay

You'll want to leave the LED turned on for a short amount of time before you send the "off" signal.

Because the Photon's app code runs very fast, there will be certain situations where you'll want to insert delays into the code, in order to allow time for certain events to occur. Typically, these delays are intended to give people time to perceive the event and/or respond to the event.

Your app can use the delay() method to insert a time delay. It acts like a timer that makes the app wait before performing the next line of code.

You'll need to add a delay after the LED has been turned on. Add this code to your app by inserting it (as a separate line of code) within the loop() function (after the digitalWrite() statement):

The delay() method requires one parameter inside its parentheses:

• The time value, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds for the delay (1000 ms = 1 second). In this case, the delay was set to 1000 ms (1 second).

Turn Off LED

Next, you'll send an "off" signal to the LED pin. Add this code to your app by inserting it (as a separate line of code) within the loop() function (after the delay() statement):

You can see that the second parameter in this digitalWrite() statement was set to LOW, which represents "off" for a digital output.

Add Another Delay

When all the code within the loop() function has been performed, the loop() will automatically repeat itself. Since the first line of code in your loop() turns on the LED, you'll want to add another delay to leave the LED turned off for a short amount of time before the loop() repeats itself.

Add this code to your app by inserting it within the loop() function (after the second digitalWrite() statement):

Now, the code within your loop() function should perform these tasks (in order):

1. Turn On LED light

2. Wait 1 second

3. Turn Off LED light

4. Wait 1 second

5. Repeat

Physical Inputs

Your Photon kit includes these physical inputs, which can be connected to your circuit board:

• Push Buttons – detects if button is being pushed (kit has red, yellow, green & blue buttons)

• Trimpot Dial – detects position of dial (can be turned clockwise or counter-clockwise)

• Motion Sensor – detects if something is moving in nearby environment

• Magnetic Switch – detects if something is open or closed (such as door, window, etc.)

• Photocell (Light Sensor) – measures amount of light in environment

• Humidity & Temperature Sensor – measures relative humidity & temperature of air

• Soil Moisture Sensor – measures amount of moisture in soil (or similar material)

• Accelerometer – measures acceleration or tilt in 3 dimensions; can also detect taps or bumps

The following is not a standard part of the Photon kit, but your teacher may have added it:

• Ultrasonic Sensor – measures distance to nearest object

Physical Outputs

Your Photon kit includes these physical outputs, which can be connected to your circuit board:

• LED Lights – produces light (kit has red, yellow, green & blue LED lights)

• Speaker – produces sound (tone) at any frequency from 20Hz to 20kHz

• Servo Motor – rotates to any angle from 0° to ~180°

• Micro OLED Display – displays text and simple graphics in monochrome

Connectors

Your Photon kit includes these components to help connect inputs and outputs to your circuit board:

• Breadboard – provides additional pins to help connect and power your inputs and outputs

• Jumper Wires – help connect inputs and outputs to pins on breadboard and circuit board

• Resistors – help limit electric current for certain inputs or outputs (such as LED lights, etc.)

Power Cables

Your Photon kit will include one or more cables to provide power to your circuit board:

• USB to Micro-USB Cable – powers circuit board by connecting to USB port or charger

• 9V to Barrel Jack Adapter – powers circuit board by connecting to 9V battery

Only one power source (Micro-USB or Barrel Jack) needs to be connected.

More Info

The product page for the SparkFun Inventor's Kit for Photon provides links to details about each part included in the kit. (Click the "Includes" tab on the product page to see the links to the parts.)

Next, you'll add the CSS for your web app's stylesheet.

Add Starter CSS

​Copy this starter CSS for your web app, and paste it into a blank CSS file named style.css.

Add Custom CSS

Copy this CSS, and add it after your starter CSS:

.card {
    width: 250px;
    margin: 0 auto 20px;
    padding: 10px;
    color: black;
    background-color: white;
    border: 2px solid #aaa;
    border-radius: 10px;
    box-shadow: 0px 4px 8px rgba(0,0,0,0.2);
}

#motion-alert {
    display: none; /* hide until motion event notification */
    color: white;
    background-color: #ff3333; /* red */
}

/* CSS to change Checkbox Input into Toggle Switch */
.switch {
  position: relative;
  display: inline-block;
  width: 60px;
  height: 34px;
}

.switch input {
    display:none;
}

.slider {
  position: absolute;
  cursor: pointer;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: #ccc; /* gray when unchecked */
  -webkit-transition: .4s;
  transition: .4s;
}

.slider:before {
  position: absolute;
  content: "";
  height: 26px;
  width: 26px;
  left: 4px;
  bottom: 4px;
  background-color: white;
  -webkit-transition: .4s;
  transition: .4s;
}

input:checked + .slider {
  background-color: #00cc00; /* green when checked */
}

input:focus + .slider {
  box-shadow: 0 0 1px #00cc00;
}

input:checked + .slider:before {
  -webkit-transform: translateX(26px);
  -ms-transform: translateX(26px);
  transform: translateX(26px);
}

.slider.round {
  border-radius: 34px;
}

.slider.round:before {
  border-radius: 50%;
}

Your CSS should now have style declarations for several HTML elements:

1. The CSS for body styles the <body> section of your HTML.

2. The CSS for .card styles elements in your HTML that have class="card". There are 2 <div> elements that have this class. The first <div> will be a "card" displaying information about your security system (current mode, toggle switch for mode, and time of last motion event). The second <div> will be a "card" displaying a pop-up notification when motion is detected.

3. The CSS for #motion-alert styles elements in your HTML that have id="motion-alert". The second <div> has this id name and will be hidden (display: none). When a motion event notification is received, your web app JS will use jQuery to briefly show this "card" and then hide it.

4. The rest of the CSS (for .switch, .slider, and input) changes the checkbox input in your HTML to look and act like a toggle switch.

Preview Web App

If you preview the web app at this point, you can see how the CSS has changed the appearance of the web app, but it still doesn't function yet (because there's still no JS in the code.js file).

If you click your toggle switch, it will change appearance using CSS (but it requires JS to fully function).

Next, you'll use the "Hello World" app as starter code for your "Smart Light" device app. You'll use this code to verify that you connected the LED correctly.

Log In to Particle Build

One person on your team should log in to Particle Build using your team's Particle account login.

Once you're logged in, you should see a new app template in the code editor. (If not, just click the "Create New App" button in the Code menu panel.)

Title New App

Enter smart-light as your app's title.

Copy Hello World Code

You'll use the hello-world app as starter code for your smart-light app:

/*
Hello World Test
Team Info
Teacher - Class Period
*/

int LED = D7;

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

void loop() {
    digitalWrite(LED, HIGH);
    delay(1000);
    digitalWrite(LED, LOW);
    delay(1000);
}

1. Copy the "Hello World" code above.

2. In the code editor panel, select all the existing code in the smart-light app, and then replace it by pasting in the copied code.

Save your smart-light app code by clicking the Save icon in the left navigation bar.

Modify App Code

You'll need to make a few changes to the app code:

1. Modify the comment block: Change Hello World to Smart Light Device, and be sure your team info, teacher's name, and class period are correctly listed.

2. Modify line 7 that declares the LED variable: Change the variable's value from D7 to D0 (or whichever pin number your LED is connected to). This will allow your app to control your LED.

Flash App to Device

Be sure your Photon device is connected to Wi-Fi and Particle Cloud.

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar. (Particle Build will first save and verify your code before flashing it to your device.)

Once your Photon has downloaded the new app and restarted, the updated app will start running:

• Confirm that the LED light that you connected to your Photon circuit board blinks on and off in a repeating pattern (with the light turning on for 1 second and then turning off for 1 second). The blue D7 light should be turned off.

Troubleshooting Issues

If the LED light that you connected is not blinking, then there is a mistake in your app code – or a mistake in your wiring connection – or a mistake in both.

If the blue D7 light is blinking, then check your app code to verify whether you changed the pin number assigned to the LED variable. If necessary, revise your code, and flash the updated app to your device.

Otherwise, verify that the LED light's positive leg (the bent leg) is connected (via a jumper wire) to the same I/O pin number that is assigned to the LED variable in your app code. If necessary, change either your wiring or your code, so the pin numbers match. If you revised your code, flash the updated app to your device.

If that still doesn't solve the issue, then double-check all your wiring by referring back to the connection instructions.

Next, you'll modify your Smart Security device app to allow a web app to interact with your Photon through the internet.

Particle Cloud

Remember that all your Photon's internet communications are routed through Particle Cloud, which provides these ways for your web app to interact with your Photon device:

1. A web app can get the value of a Photon device variable

2. A web app can call a custom function on a Photon device

3. A web app can get event notifications from a Photon device

The web app that you'll be creating for your Smart Security device will perform these tasks:

1. The web app will display whether the security device is currently armed or disarmed. The web app will do this by getting the value of the deviceMode variable in your Photon device app.

2. The web app will display a toggle switch that can be clicked to remotely toggle the security device between armed and disarmed mode. The web app will do this by calling the toggleMode() function in your Photon device app.

3. The web app will display a notification if the security device detects motion while the device is armed. The web app will also display the date and time when a motion event was last detected. The web app will do this by receiving event notifications sent from your Photon device app.

You'll need to add some code to your Photon device app to allow it to interact with your web app.

Share Variable and Function

Your Photon app should have existing code statements from your Smart Light app which you modified that will share the deviceMode variable and toggleMode() function through Particle Cloud.

Be sure the following code statements are already listed within the setup() function (do not add this code again if it already exists):

Particle.variable("deviceMode", deviceMode);
Particle.function("toggleMode", toggleMode);

Send Event Notification

Your Photon device app can send an event notification using theParticle.publish() method. This will create a "cloud event" in Particle Cloud that will stream the event notification to your web app.

By default, Particle Cloud will clear each cloud event after 60 seconds to prevent your web app from receiving outdated notifications.

An event notification can be sent with or without data:

• An event notification sent without data acts like a simple alert that the event occurred.

• An event notification sent with data will include additional information as a text string (up to 255 characters).

Particle Cloud will allow your Photon device to send about 1 event notification per second. If your device sends event notifications more frequently than this, Particle Cloud will intentionally slow down your event stream (with a 4-second delay), which can cause issues with your web app performance.

To prevent this, include a delay() of at least 1 second after a Particle.publish() statement (because a 1-second delay added by you is better than a 4-second delay added by Particle Cloud).

For your Smart Security device, your Photon app should send an event notification (without additional data) whenever the motion sensor detects motion.

Send an event notification through Particle Cloud by adding this code statement within your checkMotion() custom function (after the tone() statement but before the delay() statement):

Particle.publish("motion");

The Particle.publish() method requires a parameter for the cloud event name, which can be up to 63 characters in length. The name must be listed within double quotation marks. In this case, "motion" will be the name of the cloud event.

Since your code already has a delay() statement on the next line for the motion sensor, this existing delay() will also prevent your Photon app from sending event notifications too frequently.

Flash App to Device

Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar.

Once your Photon has downloaded the app and restarted, the updated app will start running. You shouldn't notice any changes in the device's behavior, but your Photon app will now send a "motion" event notification to Particle Cloud every time motion is detected while the device is armed.

Next, you'll add code in your Smart Security device app to control the motion sensor.

The basic steps to use a motion sensor in your app code are:

1. Declare a global variable to store the I/O pin number for the motion sensor.

2. Set the pin mode for the motion sensor pin in the setup() function.

3. Use a digitalRead() statement to check whether the sensor detects any motion, and add code statements that should be performed if motion is detected (or not detected).

Global Variable for Sensor

Declare a global variable to store the I/O pin number for the motion sensor by adding this code statement before the setup() function:

int motion = D3;

If you connected your motion sensor to a different I/O pin other than D3, then modify this code statement to list the correct pin number for your motion sensor.

Set Pin Mode for Sensor

Set the pin mode for your motion sensor pin by adding this code statement within the setup() function (between the curly braces):

pinMode(motion, INPUT_PULLUP);

Add Function to Check Sensor

The digitalRead() method is used to check whether the sensor currently detects any motion.

The digitalRead() method will return a value of either HIGH or LOW (which are treated as if they were int values):

• HIGH indicates that motion is NOT currently detected.

• LOW indicates that motion is currently detected.

A variable named motionState will store the value returned by the digitalRead() method.

An if statement will be used to perform a set of actions if motion is detected (if motionState has a value equivalent to LOW).

You'll add a custom function named checkMotion() that will contain all this code.

Add this checkMotion() custom function after the loop() function (you can add it before or after the toggleMode() function):

void checkMotion() {
    int motionState = digitalRead(motion);
    
    if (motionState == LOW) {
        // add code to do something if motion detected
        
        delay(2000); // wait 2 seconds before checking sensor again
    }
}

Inside the if statement, you'll need to add code to do something if motion is detected. In the next step of this tutorial, you'll add code here to make an "alarm sound" using the speaker. Later, you'll also add code to send an event notification to the web app that you'll be creating.

You'll notice that a delay() of 2 seconds is performed when motion is detected. This delay is needed to allow the sensor to capture a new "snapshot" of the environment before checking the sensor again.

Call Function in Loop If Armed

The checkMotion() function will only be performed if it is called within another function, such as the loop() function. However, the motion sensor should only be checked if the device's mode is currently set to "armed".

Add this code within the loop() function (after the closing curly brace of the existing if statement that checks the value of buttonState):

    if (deviceMode == "armed") {
        checkMotion();
    }

This code will only call the checkMotion() function if the value of deviceMode is equivalent to "armed".

Save your smart-security app code by clicking the Save icon in the left navigation bar.

Your Photon device app can send event notifications to your web app through Particle Cloud. The event notification can also include data (in the form of a text string).

For example, your Photon device could monitor a building using motion sensors. If a sensor detects motion, an event notification could be sent to your web app to alert you. The notification could also include data, such as the location of the specific motion sensor that was triggered.

Your Photon device app will use the Particle.publish() method to send an event notification through Particle Cloud. The event notification can also include additional data (as text).

A "cloud event" will be created that sends the event notification to your web app.

Your web app will use the particle.getEventStream() method to start listening for event notifications streamed through Particle Cloud.

By default, Particle Cloud will clear each cloud event after 60 seconds. This is to prevent your web app from receiving outdated notifications.

Photon Device App

Your Photon device app will use the Particle.publish() method to send an event notification through Particle Cloud to your web app. The event notification can be sent with or without data.

Particle Cloud will allow your Photon device to send about 1 event notification per second. If your device sends event notifications more frequently than this, Particle Cloud will intentionally slow down your event stream (with a 4-second delay), which can cause issues with your web app performance.

To prevent this, include a delay() of at least 1 second after a Particle.publish() statement (because a 1-second delay added by you is better than a 4-second delay added by Particle Cloud).

Send Event Without Data

An event notification can be sent without any additional data. It acts like a simple alert of a specific event or condition occurring.

Add this code (be sure to modify) in your Photon app wherever an event notification should be sent (typically somewhere in the loop() function or a custom function):

Particle.publish("cloudEvent");
delay(1000); // 1 second delay after publishing event

In this case, the Particle.publish() method has just one parameter inside its parentheses:

1. The cloud event name, which can be up to 63 characters in length. The name must be listed within double quotation marks. Change "cloudEvent" to the actual name that you want to use.

Send Event With Data

Alternatively, an event notification can be sent with additional data in the form of a text string.

Add this code (be sure to modify) in your Photon app wherever an event notification should be sent (typically somewhere in the loop() function or a custom function):

Particle.publish("cloudEvent", "data");
delay(1000); // 1 second delay after publishing event

In this case, the Particle.publish() method has two parameters inside its parentheses:

1. The cloud event name, which can be up to 63 characters in length. The name must be listed within double quotation marks. Change "cloudEvent" to the actual name that you want to use.

2. The event data, which is a text string that can be up to 255 characters in length. You can directly list the data as text within double quotation marks, or you can list the name of a String variable that stores the data. Change "data" to the actual text data (or String variable name) that should be sent with the event notification.

Web App JS

Your web app JS will use the particle.getEventStream() method to start listening for event notifications streamed through Particle Cloud.

Add this code (be sure to modify) in your web app JS:

particle.getEventStream({ deviceId: myDevice, name: "cloudEvent", auth: myToken }).then(function(stream) {
  stream.on('event', function(feed) {
    // add code to do something when event notification received
    // any text data received is stored as: feed.data
    
  });
});

The particle.getEventStream() method requires your Photon device ID, the name of your cloud event, and your Photon access token:

1. myDevice is a global variable in your web app JS that should store your Photon device ID

2. "cloudEvent" is the name of your cloud event that you want to receive notifications from. The name must be listed inside double quotation marks. Be sure to change "cloudEvent" to the actual name of your cloud event.

3. myToken is a global variable in your web app JS that should store your Photon access token

If an event notification includes any data, this text data gets temporarily stored in a local variable called: feed.data

You will need to add code within the particle.getVariable() method to do something when an event notification is received – and if applicable, do something with the text stored in feed.data.

For example, you could add code to:

• Display a message in your web app (by using jQuery to modify the HTML)

• Change the style of your web app (by using jQuery to modify the CSS)

• Save the text data in your web app (by assigning its value to a JS global variable)

Next, you'll create a web app that will interact with your Smart Light device through Particle Cloud.

Your web app will consist of an HTML file namedindex.html, a CSS file named style.css, and a JavaScript file named script.js.

Particle Build is only used to code your Photon device app. You'll need to use a different code editor to create the HTML, CSS, and JS files for your web app. Consult your teacher to determine which code editor will be most appropriate to use for your web app files.

Add HTML

Copy this HTML, and paste it into a blank HTML file named index.html:

This HTML does three main things:

1. It loads a CSS stylesheet file.

2. It loads three JavaScript files.

3. It displays a "card" with the light's name, the light's status, and a button that can be clicked to remotely toggle the light on or off.

LOAD CSS STYLESHEET

In the <head> section, line 7 of the HTML has a <link> tag to load a CSS stylesheet file. The CSS stylesheet will be used to modify the appearance of certain HTML elements in your web app.

At the moment, your web app CSS file named style.css is either blank or hasn't been created yet.

LOAD JAVASCRIPT FILES

At the bottom of the <body> section, lines 16-18 of the HTML contain <script> tags to load three JavaScript files into your web app:

1. Particle API JS library: particle.min.js

2. jQuery JS library: jquery.min.js

3. Your web app JS file: script.js

The contains methods to allow your web app to interact with your Photon device through Particle Cloud. You'll use Particle methods in your web app JS file.

The contains methods that make it easy to modify the content and style of your web app by dynamically changing its HTML and CSS. You'll use jQuery methods in your web app JS file.

At the moment, your web app JS file named script.js is either blank or hasn't been created yet.

DISPLAY CARD FOR LIGHT

In the <body> section of your web app, lines 10-15 of the HTML display an <h1> heading and then a <div> section that will become a "card" displaying the following information:

1. The name of the light, which is simply named Light 1 in this case, but this could be changed to something more specific such as Desk Light, Hall Light, etc.

2. The status of the light, which has been displayed using the placeholder text of Connecting.... Once the web app has connected to Particle Cloud, your web app JS will dynamically change this placeholder text to display the actual light status as either ON or OFF.

3. A button to toggle the light on or off, which has been given a placeholder label of Wait. Once the web app has connected to Particle Cloud, your web app JS will dynamically change this button label to either Turn Off (if the light is currently on) or Turn On (if the light is currently off).

Preview Web App

If you preview the web app at this point, it's very plain (because there's no CSS in the style.css file) and it doesn't function yet (because there's no JS in the code.js file).

In order for your web app to interact with your Photon device through Particle Cloud, you'll need to complete the following preparation steps:

1. Your web app HTML file needs to load several JS files (such as: Particle API JS library, etc.).

2. Your web app JS file needs to create a new Particle() object.

3. Your web app JS file needs to declare variables to store your Photon device ID and access token.

Once these steps have been completed, you'll be ready to add code in your web app JS to read device variables, call device functions, and get device event notifications.

Load JS Files

Your web app HTML file (index.html) should include <script> tags to load these JavaScript files:

1. Particle API JS library: particle.min.js

2. jQuery JS library: jquery.min.js

3. Your web app JS file: script.js

The contains methods to allow your web app to interact with your Photon device through Particle Cloud. You'll use Particle methods in your web app JS file.

The contains methods that make it easy to modify the content and style of your web app by dynamically changing its HTML and CSS. You'll use jQuery methods in your web app JS file.

Option 1: Load from CDN

If possible, use a content delivery network (such as or ) to load the Particle API JS library and jQuery JS library.

Your web app JS file will be loaded as a local file from your web app folder (where your HTML and CSS files are located).

Add this to your web app HTML file within the <body> section (just before the closing </body> tag):

Option 2: Load Local Files

Alternatively, you could download local copies of the Particle API JS library and jQuery JS library. You will want the minified version of each file (min.js), which has a smaller file size. If necessary, consult with your teacher to be sure you obtain the correct files.

Place the copies of the files into your web app folder (where your HTML and CSS files are located).

Add this to your web app HTML file within the <body> section (just before the closing </body> tag):

Be sure the file names listed in the <script> tags match the file names in your web app folder.

Create Web App JS File

Be sure your web app folder contains a JavaScript file named: script.js

This web app JS file will contain your JavaScript code to interact with your Photon device through Particle Cloud. Your JS code will also dynamically modify your HTML and CSS to display updated information from your Photon device.

Create Particle Object

The Particle API JS library defines a class called Particle() that can be used to create an object variable with built-in methods (functions) to interact with a Photon device through Particle Cloud.

Your web app JS code must create a new Particle() object, and assign it to a global variable, which is typically just named particle.

Add this code statement at the beginning of your web app JS code:

Device ID & Access Token

In order for a web app to interact with a Photon device through Particle Cloud, the web app must provide a correct device ID and access token with each request. This ensures your web app communicates with the correct device – and prevents unauthorized apps from communicating with your device.

Your web app JS code will declare global variables to store your Photon device ID and access token. You'll get their values from your Particle Build account.

Add this code towards the beginning of your web app JS code, and then modify it:

Your Photon's unique device ID is listed in the Devices menu of your Particle Build account:

1. Click the Devices icon in the left navigation bar.

2. In the Devices menu panel, click the drop-down arrow to the right of your Photon device name.

3. Select and copy the device ID.

4. Paste the device ID into your JS code as the value for myDevice (the device ID must be listed within quotation marks).

Your Photon's unique access token is listed in the Settings menu of your Particle Build account:

1. Click the Settings icon in the left navigation bar.

2. In the Settings menu panel, select and copy the access token.

3. Paste the access token into your JS code as the value for myToken (the access token must be listed within quotation marks).

What's Particle Build?

​Particle Build is an online code editor (web IDE) provided by Particle. Particle Build is part of the Particle Cloud platform. You will use Particle Build to code and store all your Photon device apps.

The Photon device itself can only store and run one app at a time. However, you can create and save multiple apps in Particle Build. When you need to update the specific app stored on your Photon device, you'll do this in Particle Build – and your Photon will download the new app over Wi-Fi.

Your team will need a Particle account to log in to Particle Build. However, your teacher will most likely provide your team with an existing Particle account login (email & password) that's already associated with your specific Photon device. Every Photon has a unique device ID it uses to communicate with Particle Cloud, and each device ID can only be associated with one Particle account.

One person on your team should log in to Particle Build using your team's Particle account login.

Once you're logged in, you'll see the Particle Build code editor, which defaults to the "Code" menu and shows a blank app template.

The user interface for Particle Build is divided into 4 sections:

• On the far left is a vertical navigation bar with icons.

• On the middle left is a menu panel showing options for the current navigation selection.

• On the right side is the code editor panel showing the code for your current app.

• On the bottom of the code editor panel is a horizontal status bar that displays messages.

Navigation Bar

If you hover your mouse pointer over an icon in the navigation bar, the icon's name will be displayed. Here is a summary of the navigation icons from top to bottom:

Toggle the Menu Panel

The middle menu panel can be toggled between "show" and "hide" by clicking the same navigation icon repeatedly.

In general, you'll probably want to keep the menu panel shown – but if you want extra space for your code editor panel, you can temporarily hide the menu panel.

The small speaker included in the Photon kit can produce tones or play simple music (note by note). The speaker can produce tones ranging in frequency from 20Hz (very low pitch) to 20KHz (very high pitch), covering the full range of sounds that humans can hear.

How to Connect Speaker

A speaker is a part, meaning there is one way to correctly connect its positive and negative terminals. If a polarized part is connected incorrectly (by switching the positive and negative), the part may not work or could become damaged.

The speaker in your Photon kit has a positive leg and a negative leg. These can be identified by labels on the bottom of the speaker:

Also, there is a positive symbol ( ⊕ ) printed on the side of the speaker to identify which side has the positive leg. This allows you to verify the polarity while the speaker is plugged into a breadboard.

Requires PWM Pin

The positive leg of the speaker must be connected to an I/O pin capable of (PWM), which is a process used to make a digital output signal (which has only two values: HIGH or LOW) act like an analog output signal (which has a range of values).

These Photon I/O pins are capable of PWM output: A4, A5, D0, D1, D2, D3, RX, TX, WKP.

Connect to Breadboard

To connect a speaker to your Photon using the breadboard, you will need:

• Speaker

• 2 jumper wires (use different colors to help identify them)

Here are the steps to connect the speaker to your Photon using the breadboard:

1. Insert the positive and negative legs of the speaker into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the positive leg of the speaker. Plug the other end of this jumper wire into a PWM-capable I/O pin on the Photon circuit board.

3. Plug one end of the other jumper wire into the same terminal strip row as the negative leg of the speaker. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail on the breadboard (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect a speaker:

Keep in mind that your connection can look different than this example diagram:

• Your speaker legs could be inserted into different row numbers on the breadboard. (The example connects the negative leg to row 3 and the positive leg to row 5.)

• Your speaker legs could be inserted into a different column on the breadboard. (The example connects the LED legs into column F of the terminal strip rows.)

• The positive leg of your speaker could connect to a different I/O pin capable of PWM output. (The example connects to the D2 pin.)

• The negative leg of your speaker could connect (through a jumper wire) either to a different GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins.)

How to Code Speaker

The basic steps to control a speaker in your app code are:

1. Declare a global variable to store the I/O pin number for the speaker.

2. Set the pin mode for the speaker pin in the setup() function.

3. Use tone() statements to produce sounds.

Global Variable

You should declare a global variable to store the I/O pin number that the speaker is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the speaker to a different pin number).

Add this code statement (modify if necessary) before the setup() function:

This line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called speaker. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D2. If necessary, modify this value to match the actual I/O pin that your speaker is connected to.

Set Pin Mode

You need to set the pin mode for the speaker to be used as an output.

Add this code statement (modify if necessary) within the setup() function:

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named speaker is listed. If necessary, change this to match the variable name for your speaker.

2. The mode value, which will always be OUTPUT for a speaker.

Produce Tone

The tone() method is used to produce a sound of a specific frequency (pitch) for a specific duration of time. The speaker can produce tones ranging in frequency from 20Hz (very low pitch) to 20KHz (very high pitch), which covers the full range of sounds that humans can hear.

Add this code statement (modify as necessary) to your app within the setup() function, loop() function, or a custom function:

The tone() method requires three parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D2, etc.) or a variable that stores a pin number. In this example, a variable named speaker is listed. If necessary, modify this to match the variable name for your speaker.

2. The frequency for the tone, which can be an integer value (whole number) or a variable that stores an integer. The value can be between 20-20000 hertz. Lower numbers will have a lower pitch, while higher numbers will have a higher pitch. In this example, the frequency will be 2000 hertz. Modify this value to the frequency you want for your sound.

3. The duration for the tone, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds that the tone will be played (1000 ms = 1 second). In this example, the duration will be 250 ms (0.25 seconds).

Continuous Tone

If you want to produce a continuous tone that keeps playing, you can either use a negative value for the duration – or you can leave out the duration parameter entirely:

To turn off a continuous tone, use the noTone() method when you're ready to stop the sound:

Your Photon device app can share a variable through Particle Cloud, so your web app can get the value of the variable.

For example, your Photon device app could measure the temperature of a room using a sensor, store the measurement in a variable, and share this variable's value through Particle Cloud, so your web app can get the variable's value and display it.

Your Photon device app will use the Particle.variable() method to share the value of a device variable through Particle Cloud.

A "cloud variable" will be created to store the value of your device variable. Whenever the value of your device variable changes, the value stored in the cloud variable will be automatically synced to match.

Your web app will use the particle.getVariable() method to get the value of your cloud variable.

Photon Device App

Your Photon device app will use the Particle.variable() method to share the value of a device variable through Particle Cloud by creating a cloud variable.

Add this code statement (be sure to modify) within the setup() function of your Photon app:

The Particle.variable() method requires two parameters inside its parentheses (in this order):

1. The cloud variable name, which can be up to 12 characters in length. If possible (for simplicity), make your cloud variable name match your device variable name. However, the cloud variable is allowed to have a different name. The cloud variable name must be listed within double quotation marks. Change "cloudVar" to the actual name that you want to use for the cloud variable.

2. The Photon device variable name, which is the variable in your Photon device app whose value will be shared in Particle Cloud. Change deviceVar to the actual name of the variable in your Photon app that you want to share.

Particle Cloud will let your Photon device share up to 20 cloud variables at one time. Each of your cloud variables in Particle Cloud has to be given a unique name (up to 12 characters in length).

If your Photon device app needs to share multiple variables, use a separate Particle.variable() statement for each device variable being shared.

Allowed Data Types

NOTE: The only data types that are allowed to be shared as cloud variables are:

• int (whole numbers)

• double (decimal numbers)

• String (text, up to 622 characters)

Be sure each Photon device variable being shared as a cloud variable uses one of these data types.

Web App JS

Your web app JS will use the particle.getVariable() method to get the value of a Photon device variable stored as a cloud variable in Particle Cloud.

Add this code (be sure to modify) in your web app JS:

This code adds a custom function named webFunction() to your web app JS. This custom function contains a call to the particle.getVariable() method, which will also contain code you'll add to perform action(s) based on the variable value returned by Particle Cloud.

Be sure to change webFunction() to the actual name that you want to use for this JS function. For example, if the function is supposed to get the value of a temperature variable from your Photon device, you might name the function something like: getTemperature()

The particle.getVariable() method requires your Photon device ID, the name of your cloud variable, and your Photon access token:

1. myDevice is a global variable in your web app JS that should store your Photon device ID

2. "cloudVar" is the name of your cloud variable, which must be listed inside double quotation marks. Be sure to change "cloudVar" to the actual name of your cloud variable.

3. myToken is a global variable in your web app JS that should store your Photon access token

When Particle Cloud returns the value of your cloud variable, this value gets temporarily stored in a local variable called: data.body.result

You will need to add code within the particle.getVariable() method to do something with the value stored in data.body.result.

For example, you could add code to:

• Display the value in your web app (by using jQuery to modify the HTML)

• Change the style of your web app based on the value (by using jQuery to modify the CSS)

• Save the value in your web app (by assigning the value to a JS global variable)

Set Interval to Get Variable

If your web app needs to continuously monitor the value of a cloud variable, you can use the window.setInterval() method to automatically call (perform) a function at a set time interval (such as every 0.5 seconds, etc.).

Add this code statement (be sure to modify) near the top of your web app JS:

The window.setInterval() method requires two parameters inside its parentheses (in this order):

1. The name of the function to be called, which will be the name of the custom function in your JS that contains the particle.getVariable() method for the variable you need to continuously monitor. The custom function's name should be listed without a set of parentheses. Change webFunction to the name of your custom function.

2. The time interval between calls, which will be the amount of time between each call to the function. The time interval is specified in milliseconds (1000 ms = 1 second). In this case, the interval was set to 2000 ms (2 seconds). Change this value to an appropriate time interval for your web app.

Getting Multiple Variables

If you want to get the values of multiple cloud variables at the same time, you can include separate calls to the particle.getVariable() method within the same custom function:

If your web app needs to get different cloud variables at different times, then create separate custom functions to get each cloud variable individually:

All the apps that run on your Photon device will be coded using Particle's version of the open-source Wiring programming language framework for microcontrollers.

The Particle firmware on your Photon runs a modified version of the Wiring language with a few minor differences, as well as some additional methods (functions) customized for the Photon hardware.

Photon App Template

When you create a new device app in Particle Build, a basic app template is provided that consists of an empty setup() function and an empty loop() function:

void setup() {​

}

​void loop() {​

}

If you want an app template that provides more guidance, you can replace the default app template with the code below, which has some comments to explain each major section of your app:

/*
Team Name
App Title
*/

// global variables - store pin numbers and other data used in functions


// setup() function runs one time when app first starts - set pin modes, etc.
void setup() {

}

// after setup() finishes, loop() function runs repeatedly - main tasks of app
void loop() {

}

// custom functions - tasks or subtasks usually called within loop() function

Setup Function

Every Photon device app must have one (and only one) setup() function. You can add lines of code between this function's opening and closing curly braces.

The setup() function will run one time when your app first starts (which is when your Photon is first powered on – or is restarted using its Reset button).

The code added within the setup() function typically sets pin modes for the device's inputs and outputs, initializes settings for certain inputs and outputs, or performs other "setup" actions that need to occur at the start of the program.

Even if you didn't add any code within the setup() function, your app must still have this function.

Loop Function

Every Photon device app must have one (and only one) loop() function. You can add lines of code between this function's opening and closing curly braces.

After the setup() function is done running, the loop() function will start to run. When all the code within the loop() function has been performed, the loop() function will automatically run itself again. It keeps running in an endless loop (until the device is restarted or powered off).

The code added within the loop() function performs the main tasks of your program.

Even if you didn't add any code within the loop() function, your app must still have this function.

Other Sections of App

Besides having the required setup() and loop() functions, your Photon device apps will typically have some or all of the following:

• Comments

• Libraries

• Global Variables

• Custom Functions

Comments

Comments are optional notes that you can insert to help explain or clarify portions of the code to anyone reviewing the program. Comments can be single-line or multi-line blocks.

It's a good idea to have at least one comment at the beginning of your app code to provide a name and/or description of your app.

Any comments in your app are ignored when the program is compiled and uploaded to your device.

// Comments are notes to yourself or others reading your code
// Each single-line comment starts with two forward slashes
​
/*
A multi-line comment block starts with a forward slash and asterisk
You can include as many lines of notes in the block as you need
A multi-line comment block ends with an asterisk and forward slash
*/

Libraries

Some device apps might include (i.e., import) one or more library files. A library is a file of pre-built code that provides additional functions that your program can utilize. For example, certain inputs and outputs have their own code library with functions to make it easier to control the input or output.

Particle Build has a Libraries menu where you can search for existing libraries (or upload your own library file that you've created). When you select a library to be added to your app, Particle Build will automatically insert an #include statement for the library at the beginning of your app code.

Global Variables

Your device app will typically have code that declares global variables which store data used in your program's functions, such as pin numbers for sensors, etc.

Global variables are usually listed before the setup() function (to make it easier to read the code).

Custom Functions

You can also add your own custom functions to your device app. Each custom function must have a unique function name.

Custom functions are typically used to contain code that performs specific tasks or subtasks. Having custom functions in your app is optional, but they can help break up your code into smaller modules that are easier to understand (and easier to re-use). So rather than listing all your main program code within the loop() function, you can subdivide some or all of the code into custom functions.

The code within a custom function is only run if and when that custom function is "called" (by listing the function's name) within the setup() or loop() function. A custom function can also be "called" within another custom function.

Custom functions are usually listed after the loop() function (to make it easier to read the code).

Resources

If you want to learn more about programming your Photon device, consult these references:

• Wiring Programming Reference

• Particle Firmware Reference

Your Photon device app can share a custom function through Particle Cloud, so your web app can call the function to make it run on your Photon device.

For example, your Photon device app could share a custom function that toggles an LED light on or off, so your web app would be able to call this function to remotely turn the light on or off.

Your Photon device app will use the Particle.function() method to share a custom function through Particle Cloud.

A "cloud function" will be created that acts like a reference to the custom function in your device app.

Your web app will use the particle.callFunction() method to make the custom function run on your Photon device by calling its cloud function reference.

Photon Device App

Your Photon device app will use the Particle.function() method to share a custom function through Particle Cloud by creating a cloud function. In addition, you will also need to modify the custom function to work with Particle Cloud.

Share Device Function

Add this code statement (be sure to modify) within the setup() function of your Photon app:

Particle.function("cloudFunc", deviceFunc);

The Particle.function() method requires two parameters inside its parentheses (in this order):

1. The cloud function name, which can be up to 12 characters in length. If possible (for simplicity), make your cloud function name match your device function name. However, the cloud function is allowed to have a different name. The cloud function name must be listed within double quotation marks without parentheses after its name. Change "cloudFunc" to the actual name that you want to use for the cloud function.

2. The Photon device function name, which is the custom function in your Photon device app that will be shared through Particle Cloud. List the function name without parentheses after its name. Change deviceFunc to the actual name of the custom function in your Photon device app that you want to share.

Particle Cloud will let your Photon device share up to 15 cloud functions at one time. Each of your cloud functions in Particle Cloud has to be given a unique name (up to 12 characters in length).

If your Photon device app needs to share multiple functions, use a separate Particle.function() statement for each device function being shared.

Modify Device Function

In order to share a custom function in your Photon device app with Particle Cloud, the custom function must be modified to do the following:

• The custom function must accept a String parameter when the function is called.

• The custom function must return an integer value when the function is performed.

For example, a typical custom function in your device app would have this generic format:

void deviceFunc() {
    // code statements to be performed by function
}

The code for this custom function would need to be modified to accept a String parameter (i.e., text) and return an integer value (i.e., whole number). Here's a modified version of the function:

int deviceFunc(String data) {
    // code statements to be performed by function
    return 1;
}

Here are the 3 modifications that were made to the custom function:

1. String data is listed inside the parentheses after the function name. This represents the parameter that the function will accept: String is the data type for the parameter (i.e., text) , and data is the name of a local variable that will receive and store the parameter value (text string). If desired, you could use a different variable name other than data.

2. int is listed in front of the function name (instead of void), which indicates the function will return an integer value (whole number).

3. The code statement return 1; is included inside the function (at the end before the closing curly brace), which will return an integer value of 1. This is the simplest way to have the function return a value.

Calling Device Function

Once a custom function in your Photon device app has been modified to be shared through Particle Cloud, your Photon app (and your web app) must include a text parameter when calling the function.

If the custom function doesn't actually do anything with the parameter, then this text string parameter can be any text – even an empty text string of "" will work.

For example, in your Photon app, a code statement to call the custom function would be:

deviceFunc("text");

• deviceFunction represents the name of the custom function. Change this to the name of your custom function.

• "text" represents the text string being passed into the function as a parameter. If this text parameter isn't actually used within the function, then it can be any text string enclosed within double quotation marks – even an empty text string of "" will work.

Using String Parameter

As stated previously, the Photon device function being shared through Particle Cloud must accept a String parameter. The function doesn't actually have to do anything with this text data (other than receive it when the function is called).

However, depending on what your custom function does, the text string passed into the data parameter could be used to decide what action(s) are performed within the custom function.

For example, imagine you created a custom function named turnLight() to turn an LED light either on or off based on the value of a text string passed into the function as a parameter:

int turnLight(String data) {
    if(data == "on")
        digitalWrite(LED, HIGH);
    }
    else if(data == "off") {
        digitalWrite(LED, LOW);
    }
    return 1;
}

To turn on the LED, your Photon app (or your web app) would call turnLight() and include"on" as the parameter. In your Photon app, the code statement would be: turnLight("on");

To turn off the LED, your Photon app (or your web app) would call turnLight() function and include "off" as the parameter. In your Photon app, the code statement would be: turnLight("off");

Web App JS

Your web app JS will use the particle.callFunction() method to make a custom function run on your Photon device by calling its cloud function reference in Particle Cloud.

Add this code (be sure to modify) in your web app JS:

function webFunction() {
    particle.callFunction({ deviceId: myDevice, name: "cloudFunc", argument: "text", auth: myToken });
}

This code adds a custom function named webFunction() to your web app JS. This custom function contains the particle.callFunction() method.

Be sure to change webFunction() to the actual name that you want to use for this JS function. If helpful, you could use the same name as the Photon device function being called. For example, if the JS function is supposed to call a function named toggleLight() in your Photon device app, you could also name the JS function as toggleLight().

The particle.callFunction() method requires your Photon device ID, the name of your cloud function, an argument (a String parameter for the Photon function), and your Photon access token:

1. myDevice is a global variable in your web app JS that should store your Photon device ID

2. "cloudFunc" is the name of your cloud function, which must be listed inside double quotation marks. Be sure to change "cloudFunc" to the actual name of your cloud function.

3. "text" is the String parameter that will be passed into the Photon device function. If this text parameter isn't actually used within the Photon function, then it can be any text string enclosed within double quotation marks – even an empty text string of "" will work.

4. myToken is a global variable in your web app JS that should store your Photon access token

Calling JS Function

Your web app will need a way to call the JS function which contains the particle.callFunction() method that makes a function run on your Photon device.

One common way to do this is to add a button in your web app HTML that can be clicked by the user. The button should have an onclick event attribute that will call the JS function (which will in turn call your Photon function).

Add this to your web app HTML file within the <body> section where you want the button to appear:

<button onclick="webFunction()">Button Label</button>

• Change webFunction() to the name of the JS function to be called when the button is clicked. This should be a JS function that contains a particle.callFunction() method.

• Change Button Label to whatever text you want displayed in the button as its label. Be sure to use a label that will make sense to the user.

NOTE: You could use a different HTML element other than a button. Just be sure it will be clear to the user that the element is "clickable" (and it's clear what will happen when it is clicked).

The motion sensor included in your Photon kit uses passive infrared (PIR) light to detect movement in the surrounding environment up to about 10 feet away.

How to Connect Motion Sensor

The motion sensor has a 3-wire JST connector with 3 pins for plugging into a breadboard. (If the end of your connector doesn't have 3 metal pins, attach the JST right angle connector included in your kit.)

To connect a motion sensor to your Photon using the breadboard, you will need:

• Motion sensor (with 3-pin JST right angle connector)

• 3 jumper wires (use different colors to help identify them; it may help to match the sensor wires)

Here are the steps to connect the motion sensor to your Photon using the breadboard:

1. Insert the 3 pins of the motion sensor connector into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the sensor's black wire. Plug the other end of this jumper wire into an I/O pin on the Photon circuit board.

3. Plug one end of a second jumper wire into the same terminal strip row as the sensor's white wire. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

4. Plug one end of a third jumper wire into the same terminal strip row as the sensor's red wire. Plug the other end of this jumper wire into either the VIN pin or V-USB pin on the Photon circuit board (or to a positive power rail on the breadboard that is connected to VIN or V-USB). If your Photon is being powered through the barrel jack, connect to the VIN pin. Otherwise, if your Photon is being powered through the Micro-USB port, connect to the V-USB pin.

Here's a wiring diagram showing a possible way to connect a motion sensor:

Keep in mind that your connection can look different than this example diagram:

• Your motion sensor pins could be inserted into different row numbers. (The example connects the sensor pins to rows 16-18 on the left side of the breadboard.)

• Your motion sensor pins could be inserted into a different column of the breadboard. (The example connects the sensor pins into column A of the terminal strip rows.)

• Your sensor's black wire could connect (through a jumper wire) to a different I/O pin. (The example connects to the D0 pin.)

• Your sensor's white wire could connect (through a jumper wire) to either to a different GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins.)

• Your sensor's red wire could connect (through a jumper wire) to either the VIN pin or V-USB pin (or to a positive power rail that's connected to one of these pins). (The example connects directly to the V-USB pin.)

How to Code Motion Sensor

The basic steps to use a motion sensor in your app code are:

1. Declare a global variable to store the I/O pin number for the motion sensor.

2. Set the pin mode for the motion sensor pin in the setup() function.

3. Use a digitalRead() statement to check whether the sensor detects any motion, and add code statements that should be performed if motion is detected (or not detected).

Global Variable

You should declare a global variable to store the I/O pin number that the motion sensor's data wire is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the motion sensor to a different pin number).

Add this code statement (modify if necessary) before the setup() function:

int motion = D0;

This line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called motion. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D0. If necessary, modify this value to match the actual I/O pin number that your button is connected to.

Set Pin Mode

You need to set the pin mode for the motion sensor to be used as an input.

Add this code statement (modify if necessary) within the setup() function:

pinMode(motion, INPUT_PULLUP);

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named motion is listed. If necessary, change this to match the variable name for your button.

2. The mode value, which will always be INPUT_PULLUP for a motion sensor.

Check If Motion Detected

The digitalRead() method is used to check whether the sensor currently detects any motion.

Add this code (modify as necessary) to your app within the loop() function or a custom function:

int motionState = digitalRead(motion);

if(motionState == LOW) {
​    // add code to do something if motion detected
​
    delay(2000); // wait 2 seconds before checking sensor again
}

In the first code statement, a local variable named motionState is declared that will have a data type of int (integer). This variable is made equal to whatever value is returned by the digitalRead() method. You can change the name of this variable, but it will make sense if it's similar to the variable name used for the motion sensor pin number.

The digitalRead() method requires one parameter insides its parentheses:

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, the variable named motion is listed. If necessary, change this to match the variable name for your motion sensor's pin number.

The digitalRead() method will return a value of either HIGH or LOW (which are treated as if they were int values):

• HIGH indicates that motion is NOT currently detected.

• LOW indicates that motion is currently detected.

The condition listed inside the parentheses of the if statement checks whether the value of motionState is equivalent to LOW:

• If this condition is true, the code within the curly braces of the if statement will be performed. You will need to add code statements within the curly braces that perform the actions you want.

• If this condition is false (because the motionState is HIGH), the code within the curly braces will NOT be performed. Optionally, you can add an else statement to perform a different set of code statements when motion is not detected.

IMPORTANT: You will notice that a delay() of 2 seconds is included when motion is detected. This delay is needed to allow the motion sensor to capture a new "snapshot" of the environment before checking the sensor again.

The defining feature of an IoT device is its ability to send and receive information through the internet. This allows an IoT device to interact with other apps or other IoT devices. For this project, you'll be creating a web app that interacts with your Photon device through the internet.

All of your Photon's internet communications are routed through the Particle Cloud service, which offers these ways that a web app can interact with a Photon device through Particle Cloud:

1. A web app can get the value of a Photon device variable

2. A web app can call a custom function on a Photon device

3. A web app can get event notifications from a Photon device

In order to make your Photon device interact with your web app, you'll need to add special code to both your Photon device app and your web app:

• The Particle firmware on your Photon device has built-in cloud functions to allow your device to interact with a web app through Particle Cloud. You'll need to add code statements using these cloud functions in your Photon device app.

• There is a Particle API JavaScript library that provides methods (functions) to allow your web app to interact with your Photon device app through Particle Cloud. You'll need to load this JS library in your web app's HTML file, and then add code statements using the library's methods in your web app's JavaScript file.

Your Photon kit includes a that can be used to detect whether a door, window, drawer, box, etc. is open or closed.

The switch consists of two pieces, and it can detect whether these two pieces are close to each other:

1. The piece with the wires contains a that moves in response to the presence or absence of a magnetic field.

2. The other piece without the wires contains a magnet, so it can activate the reed switch when the two pieces are close to each other.

If the two pieces of the magnetic switch are within 20 mm (0.75 inches) of each other, the switch detects that it's "closed" – otherwise, the switch will detect that it's "open."

These magnetic switches are commonly used in security systems for doors and windows, but they are also used in many other products. For example, a doorbell uses a magnetic switch to detect when it is being pressed. Magnetic switches are also used in many laptops and tablets to detect when the lid/cover is open or closed, in order to automatically wake up the device or put it to sleep.

How to Connect Switch

The reed switch (the piece with the wires) will be connected to the Photon. Then the reed switch will be attached to a stationary edge near something that opens (such as: door, window, drawer, etc.). For example, the reed switch could be attached to the edge of a door frame – but not to the door itself.

The magnet (the piece without wires) would be attached to the object (door, window, etc.) that actually moves when opened. The two pieces of the magnetic switch should be positioned so they are very close together (no more than 0.75 inches apart) when the object (door, window, etc.) is closed.

To connect a magnetic switch to your Photon using the breadboard, you will need:

• Magnetic Switch

• 2 jumper wires (use different colors to help identify them)

Here are the steps to connect the magnetic switch to your Photon using the breadboard:

1. Insert the two wires of the magnetic switch into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as one switch wire. Plug the other end of this jumper wire into an I/O pin on the Photon circuit board.

3. Plug one end of the other jumper wire into the same terminal strip row as the other switch wire. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail on the breadboard (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect a magnetic switch:

Keep in mind that your connection can look different than this example diagram:

• Your magnetic switch wires could be inserted into different row numbers on either breadboard side. (The example connects the switch wires to rows 17-18 on the left side of the breadboard.)

• Your magnetic switch wires could be inserted into a different column on the breadboard. (The example connects the switch wires into column A of the terminal strip rows.)

• Your magnetic switch could connect (through a jumper wire) to a different I/O pin. (The example connects to the D0 pin on the Photon circuit board.)

• Your magnetic switch could connect (through a jumper wire) either to a different GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins on the Photon circuit board.)

How to Code Switch

The basic steps to use a magnetic switch in your app code are:

1. Declare a global variable to store the I/O pin number for the switch.

2. Set the pin mode for the switch pin in the setup() function.

3. Use a digitalRead() statement to check whether the switch is currently open or closed, and add code statements that should be performed depending on the result.

Global Variable

You should declare a global variable to store the I/O pin number that the switch is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the button to a different pin number).

Add this code statement (modify if necessary) before the setup() function:

This line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called magSwitch. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D0. If necessary, modify this value to match the actual I/O pin number that your switch is connected to.

Set Pin Mode

You need to set the pin mode for the magnetic switch to be used as an input.

Add this code statement (modify if necessary) within the setup() function:

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named magSwitch is listed. If necessary, change this to match the variable name for your magnetic switch.

2. The mode value, which will always be INPUT_PULLUP for a magnetic switch.

Check Switch

The digitalRead() method is used to check whether a magnetic switch is currently open or closed.

Add this code (modify as necessary) to your app within the loop() function or a custom function:

In the first code statement, a local variable named switchState is declared that will have a data type of int (integer). This variable is made equal to whatever value is returned by the digitalRead() method. You can change the name of this variable, but it will make sense if it's similar to the variable name used for the switch pin number.

The digitalRead() method requires one parameter insides its parentheses:

1. The I/O pin number, which can be the actual pin number (such as: D2, etc.) or a variable that stores a pin number. In this example, the variable named magSwitch is listed. If necessary, change this to match the variable name for your switch's pin number.

The digitalRead() method will return a value of either HIGH or LOW (which are treated as if they were int values):

• HIGH indicates that the magnetic switch is currently open.

• LOW indicates that the magnetic switch is currently closed.

The condition listed inside the parentheses of the checks whether the value of switchState is to HIGH:

• If this condition is true, the code within the curly braces of the if statement will be performed. You will need to add code statements within the curly braces that perform the actions you want when the magnetic switch is open.

• Otherwise, if this condition is false (because switchState is LOW), the code within the curly braces of the else statement will be performed. You will need to add code statements within the curly braces that perform the actions you want when the magnetic switch is closed.

Alternatively, you could check for just one condition (either HIGH or LOW) without including an else statement to perform actions for the opposite condition.

​

The RHT03 sensor in your Photon kit can measure the relative humidity and temperature of the air.

How to Connect RHT03 Sensor

To connect the RHT03 sensor to your Photon using the breadboard, you will need:

• RHT03 Humidity and Temperature Sensor

• 3 jumper wires (use different colors to help identify them)

The RHT03 humidity and temperature sensor has 4 metal legs. The front side of the sensor has openings to allow air in.

If you were looking at the front of the sensor and the sensor legs were numbered left to right as 1-4, the wiring connections would be:

Here are the steps to connect the RHT03 sensor to your Photon using the breadboard:

1. Insert the four metal legs of the sensor into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the power leg of the sensor. Plug the other end of this jumper wire into the 3.3V pin or a 5V pin (VIN or V-USB) on the Photon circuit board (or to a positive power rail on the breadboard connected to 3.3V, VIN, or V-USB). If your Photon is being powered through the barrel jack, connect to either the 3.3V pin or VIN pin. Otherwise, if your Photon is being powered through the Micro-USB port, connect to either the 3.3V pin or V-USB pin.

3. Plug one end of a second jumper wire into the same terminal strip row as the data leg of the sensor. Plug the other end of this jumper wire into any I/O pin on the Photon circuit board.

4. Plug one end of the third jumper wire into the same terminal strip row as the ground leg of the sensor. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect the RHT03 humidity and temperature sensor (ignore the wiring for the light sensor):

Keep in mind that your connection can look different than this example diagram:

• Your RHT03 sensor legs could be inserted into different row numbers. (The example connects the RHT03 sensor legs to rows 1-4 on the right side of the breadboard).

• Your RHT03 sensor legs could be inserted into a different column of the breadboard. (The example connects the RHT03 sensor legs into column H of the terminal strip rows).

• Your RHT03 sensor could connect (through a jumper wire) to a different I/O pin. (The example connects the RHT03 sensor to the D3 pin.)

• Your RHT03 sensor could connect (through a jumper wire) directly to the 3.3V pin or a 5V pin (VIN or V-USB) – or it could connect to a positive power rail on the breadboard that's connected to the 3.3V pin or a 5V pin.

• Your RHT03 sensor could connect (through a jumper wire) either directly to a GND pin or to a negative power rail that's connect to a GND pin. (There are three available GND pins.)

How to Code RHT03 Sensor

The basic steps to control the RHT03 humidity and temperature sensor in your app code are:

1. Include the SparkFun RHT03 library in your app.

2. Declare a global variable to store the I/O pin number for the RHT03 sensor.

3. Create a RHT03 object assigned to a global variable called rht.

4. Use the rht.begin() method to start the RHT03 sensor in the setup() function.

5. Use a sequence of rht.update(), rht.humidity(), and rht.tempF() statements to get new humidity and temperature readings.

Include Library

Your Photon app must include a code library that will allow you to control the RHT03 sensor.

1. In Particle Build, click on the Libraries icon to open the Libraries menu panel.

2. Type rht into the search field. Select the result called: SparkFunRHT03

3. Click the button to "Include in Project"

4. Select the title of your Photon app, and then click the "Confirm" button

Particle Build will automatically insert this #include statement at the beginning of your app code:

Global Variables

You should declare a global variable to store the I/O pin number that the RHT03 sensor's data leg is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the motion sensor to a different pin number).

You will also need to create an object using the RHT03 class in the included library, and assign this object to a global variable.

Add this code statement (modify if necessary) before the setup() function:

The first line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called rhtData. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D3. If necessary, modify this value to match the actual I/O pin number that your sensor is connected to.

The second line of code creates a new object using the RHT03 class, and assigns the object to a global variable named rht.

Start Sensor in Setup

The rht.begin() method is used to start the RHT03 sensor, which will automatically set its pin mode.

Add this code statement within the setup() function to start the RHT03 sensor:

The rht.begin() method requires the sensor's I/O pin number. In this case, the global variable named rhtData stores this value. If you used a different name for the global variable storing your RHT03 sensor pin number, then insert that name instead.

Get Sensor Readings

The rht.update() method is used to get new sensor readings for the relative humidity and temperature of the air.

If the update is successful, the rht.update() method will return a value of 1 (which is equivalent totrue). Then you can use these other rht methods to get the updated values for the relative humidity (%) and temperature (in Fahrenheit or Celsius):

• The rht.humidity() method returns the relative humidity of the air as a value between 0-100, representing a percentage. A higher number means the air is more humid (has more water vapor).

• The rht.tempF() method returns the temperature of the air in degrees Fahrenheit – while the rht.tempC() method will return the temperature of the air in degrees Celsius.