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)

Follow these instructions explaining how to connect the button. 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 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:

int button = D2;

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):

pinMode(button, INPUT_PULLUP);

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 if statement will be used to turn on the LED if the button is being pressed (if buttonState has a value equivalent to LOW).

An else statement 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:

    int buttonState = digitalRead(button);
    
    if(buttonState == LOW) {
        digitalWrite(LED, HIGH);
    }
    else {
        digitalWrite(LED, LOW);
    }

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 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:

String lightStatus = "off";

This code statement declares a variable named lightStatus which has a data type of String, 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):

digitalWrite(LED, LOW);

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):

void toggleLight(){
    if (lightStatus == "off") {
        digitalWrite(LED, HIGH);
        lightStatus = "on";
    }
    else {
        digitalWrite(LED, LOW);
        lightStatus = "off";
    }
}

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:

    int buttonState = digitalRead(button);
    
    if (buttonState == LOW) {
        toggleLight();
        delay(175); // wait before trying to read button again
    }

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.

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.

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 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:

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 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).

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

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).

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

Particle Cloud

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

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

1. The web app will display whether the LED light is currently turned on or off. The web app will do this by getting the current value of the lightStatus variable in your Photon device app.

2. The web app will display a button that can be clicked to remotely turn the LED light on or off. The web app will do this by calling the toggleLight() function in your Photon device app.

You'll need to add some code to your Photon device app that will allow your web app to get the value of the lightStatus variable and to call the toggleLight() function.

Share Device Variable

In order for a web app to get the value of Photon device variable, your Photon device app must share the variable through Particle Cloud using the Particle.variable() method.

Share the lightStatus variable through Particle Cloud by adding this code statement within the setup() function of your Photon app:

This Particle.variable() code statement creates a "cloud variable" that stores the value of your Photon device variable. Whenever the value of the device variable changes in your Photon app, the value stored in the cloud variable will be automatically synced to match.

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. In this case, "lightStatus" will be the name of the cloud variable (which matches the device variable name).

2. The Photon device variable name, which is the variable in your Photon app whose value will be shared in Particle Cloud. In this case, you're sharing the value of the lightStatus variable.

Share Device Function

In order for a web app to call a function that runs on your Photon device, your Photon device app must share the function through Particle Cloud using the Particle.function() method.

Share the toggleLight() function through Particle Cloud by adding this code statement within the setup() function of your Photon app:

This Particle.function() code statement creates a "cloud function" that is a reference to the custom function in your Photon device app. Whenever your web app calls the cloud function, the corresponding device function in your Photon app will automatically be called.

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. In this case, "toggleLight" will be the name of the cloud function (which matches the device function name).

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. In this case, you're sharing the toggleLight function in your Photon app.

Modify Device Function

A Photon device function that is shared through Particle Cloud must do the following:

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

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

Currently, the toggleLight() function does not do these things – but you can easily modify the function to work with Particle Cloud with these minor changes:

1. Change toggleLight() to toggleLight(String data). This adds a parameter inside the parentheses that will be accepted when the function is called: String is the data type for the parameter (a text string), and data is the name of a local variable that will store the parameter value (the text string). If desired, you could use a different name other than data.

2. In front of the function name, change void to int. This indicates that the function will return an integer value (whole number), instead of no value (which is what void represents).

3. Add the code statement return 1; inside the function at the end before the closing curly brace. This code statement will return an integer value of 1 whenever the function is performed. This is the simplest way to ensure the function returns an integer value.

Your custom function should look like this now:

You might notice that there aren't any code statements within the curly braces of the toggleLight() function that actually use the data parameter variable. That's actually okay – the function does have to accept a String parameter, but it doesn't have to use the parameter inside in the function.

However, depending on what a custom function is supposed to do, the text string passed into the data parameter could be used to decide what action(s) are performed within the custom function. In this case, you won't do that, but it is an option that's available.

Modify Call to 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 string when calling the function.

In your Photon app, there's just one code statement that calls the toggleLight() function. Inside the loop() function, there is an if statement that calls the toggleLight() function when the button is pushed (buttonState == LOW):

• Inside this if statement, change toggleLight(); to toggleLight("data");

In this case, "data" will be the text string passed into the parameter when this function is called. However, since this function doesn't actually do anything with the parameter value, this text string could be any text listed within double quotation marks – even an empty text string of "" would work.

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 visible changes in the device's behavior, but your Photon app will now be sharing the lightStatus variable and toggleLight() function with Particle Cloud.

• Confirm that the LED light still toggles between "on" and "off" each time the button is pressed.

Next, you'll add JavaScript code to allow your web app to interact with your Photon device through Particle Cloud. Remember that the web app will perform these two tasks:

1. The web app will display whether the LED light is currently turned on or off. The web app will do this by getting the current value of the lightStatus variable in your Photon device app.

2. The web app will display a button that can be clicked to remotely turn the LED light on or off. The web app will do this by calling the toggleLight() function in your Photon device app.

Create Particle Object

The Particle API JS library defines a class named Particle() which you'll use to create an . An object is a special type of variable that has its own methods (functions) and properties (variables).

Copy this JavaScript code statement, and paste it into a blank JS file named script.js:

This will create a new Particle() object and assign it to a global variable named particle. Your web app JS will use this object's methods to interact with Particle Cloud.

Add Device ID & Access Token

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

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

Add this JS code to your script.js file, and modify it to list your Photon device ID and access token:

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).

Get Device Variable

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 JS code to your script.js file:

This adds a custom function named checkLights() to your JS. Inside this custom function is a call to the particle.getVariable() method.

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

1. myDevice is the global variable that stores your Photon device ID

2. "lightStatus" is the name of the cloud variable whose value you want to get.

3. myToken is the global variable that stores your Photon access token

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

In your Photon device app, the lightStatus variable has a value of either "on" or "off". Therefore, in your web app JS, data.body.result will also be one of these values.

Inside the particle.getVariable() method are JS and jQuery code statements (lines 4-13 above) that were added to perform actions based on the value returned for the Photon variable.

• $("#light1") targets the HTML element with id="light1" which is the <div> element that represents the "card" displaying the information for the light. The jQuery statements either add or remove the light-on CSS class (which changes the card's background color to yellow).

• $("#light1-status") targets the HTML element with id="light1-status" which is an <h2> element. The jQuery statements change this element's HTML to list either ON or OFF.

• $("#light1-button") targets the HTML element with id="light1-button" which is the <button> element that can be clicked to remotely turn the light on or off. The jQuery statements change this element's HTML to list either Turn Off or Turn On as the button's label.

Set Interval to Get Variable

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

Add this JS code statement to your script.js file:

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

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

2. The time interval between calls, which will be the amount of time between each call to the JS function. The time interval is specified in milliseconds (1000 ms = 1 second). In this case, the interval was set to 200 ms (every 0.2 seconds).

Call Device Function

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

Add this JS code to your script.js file:

This adds a custom function named toggleLight1() to your JS. Inside this custom function is a call to the particle.callFunction() method.

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

1. myDevice is the global variable that stores your Photon device ID

2. "toggleLight" is the name of the cloud function that you want to call (which will call its corresponding function in your Photon device app)

3. "data" 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 the global variable that stores your Photon access token

Test Web App

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

Refresh your web app, and test it with your Photon device to make sure they interact correctly:

• Verify that your web app displays the current status of your Smart Light. Use the push button connected to your Photon device to turn the LED light on or off. Verify that your web app updates automatically to show the correct light status.

• Verify that your web app can remotely turn your Smart Light on and off. Click the button in your web app, and verify that your Photon device automatically toggles the LED light on or off.

Going Further

In the next tutorial, you'll modify your "Smart Light" device into a "Smart Security" device by adding a motion sensor and speaker to your existing LED light and push button. Then you'll program a new Photon app and new web app for the modified device.