This IoT Code Guidebook is a supplement the IoT Project Guidebook.

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.

// example code block

void setup() {
​
}
​
void loop() {
​
}

Your IoT Electronics 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 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 ultrasonic sensor 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 Computing by Design high school computer science curriculum developed for the Informatics Diversity-Enhanced Workforce (iDEW) 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 Indiana University School of Informatics and Computing at IUPUI.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. 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.

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

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

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.

Electronic Circuits

Each input and output connected to your Photon circuit board must form an electronic circuit, 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 direct current (DC), while others use alternating current (AC).

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

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

• What is a Circuit?

• How to Use a Breadboard

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.

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 pulse-width modulation (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 color and activity pattern 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 SparkFun Photon RedBoard Hookup Guide provides more details about this circuit board.

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

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:

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

• 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

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

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

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

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:

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.

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

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.

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

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

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

<!DOCTYPE html>
<html>
    <head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Smart Light</title>
        <link href="style.css" rel="stylesheet" type="text/css">
    </head>
    <body>
        <h1>My Smart Lights</h1>
        <div id="light1" class="card">
            <h2 id="light1-name">Light 1</h2>
            <h2 id="light1-status">Connecting...</h2>
            <button id="light1-button" onclick="toggleLight1();">Wait</button>
        </div>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/particle-api-js/7.3.0/particle.min.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
        <script src="script.js"></script>
    </body>
</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 Particle API JS library 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 jQuery JS library 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).

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.

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

body {
    font-family:  Helvetica, Arial, sans-serif;
    font-size: 1em;
    text-align: center;
}

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

.light-on {
    background-color: #ffff99; /* yellow */
}

button {
    width: 100px;
    padding: 10px;
    font-size: 1em;
    color: #444;
    background-color: white;
    border-radius: 10px;
}

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

var particle = new Particle();

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:

var myDevice = "0000"; // Photon device ID
var myToken = "0000"; // Photon 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:

function checkLights(){
    particle.getVariable({ deviceId: myDevice, name: "lightStatus", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        if (data.body.result == "on") {
            $("#light1").addClass("light-on");
            $("#light1-status").html("ON");
            $("#light1-button").html("Turn Off")
        }
        else if (data.body.result == "off") {
            $("#light1").removeClass("light-on");
            $("#light1-status").html("OFF");
            $("#light1-button").html("Turn On")
        }
    }, function(err) {
            console.log("An error occurred: ", err);
    });
}

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.

An if-else statement is used to determine whether data.body.result has a value equivalent to "on" or "off". Then jQuery statements (which start with $) are used to dynamically change the information displayed in the "card" by targeting specific id selectors:

• $("#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:

window.setInterval(checkLights, 200);

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:

function toggleLight1() {
    particle.callFunction({ deviceId: myDevice, name: "toggleLight", argument: "data", auth: myToken });
}

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

The <button> in your web app HTML contains an onclick event attribute that will run this toggleLight1() function whenever the button in the web app is clicked.

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.

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.

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

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.

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:

Particle.variable("lightStatus", lightStatus);

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:

Particle.function("toggleLight", toggleLight);

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:

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

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.

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)

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

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

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

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

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

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

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:

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

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.

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

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

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.

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

What's 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.

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

The 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 , a basic app template is provided that consists of an empty setup() function and an empty loop() function:

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:

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

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.

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.

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:

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 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 do this by receiving event notifications sent from your Photon device app.

Add Starter JS

, and paste it into a blank JS file named script.js.

Add Custom JS

Copy this JS, and paste it after your modified starter JS:

This custom JS does 5 main things:

1. Stores an audio file in a JS global variable named alertSound

2. Sets a time interval to call a JS function named checkMode()

3. Adds a JS function named checkMode() that will get the value of a Photon variable

4. Adds a JS function named toggleMode() that will call a Photon function

5. Starts listening for "motion" event notifications sent by your Photon device

Variable for Audio File

Set Interval to Call Function

The window.setInterval() method will automatically call the function named checkMode() every 500 ms (0.5 seconds).

Get Photon Variable

The function named checkMode() contains a call to the particle.getVariable() method that will get the current value of the "deviceMode" variable in your Photon app.

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

• $("#system-mode") targets the HTML element with id="system-mode". The jQuery statements change this element's HTML to display either ARMED or DISARMED.

• $("input [name=toggle]) targets the <input> element with name="toggle". The jQuery statements change its "checked" property to either true (checked) or false (unchecked), which changes the toggle switch slider position.

Since the window.setInterval() method will keep calling this function every 0.5 seconds, your web app will continuously monitor the current mode of your Smart Security device.

Call Photon Function

The function named toggleMode() contains a call to the particle.callFunction() method that will call the "toggleMode" function in your Photon app to remotely switch your device's mode between "armed" and "disarmed".

Listen for Event Notifications

The particle.getEventStream() method is used to start listening for event notifications sent from your Photon app.

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

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

2. "motion" is the name of the cloud event that you want to receive notifications from

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

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

Code statements added within the particle.getVariable() method will be performed whenever an event notification is received.

In this case, JS and jQuery code statements (lines 29-33 above) were added that will perform these actions each time a new event notification is received:

• Play the alertSound

• Get the current date and time and store it in a variable named dateTime

• Display the value of dateTime in the HTML element with id="event-time"

• Show the HTML element with id="motion-alert", wait for 1500 ms (1.5 seconds), and then fade out the element until it is hidden. This creates a visible "pop-up" notification in your web app.

NOTE: Since your Photon app is sending the "motion" event notification without data, there aren't any JS or jQuery code statements using feed.data (because no text string is being received).

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 mode ("armed" or "disarmed") of your Smart Security device. Use the push button connected to your Photon device to change the device mode. When the LED is turned on, the device is in "armed" mode. When the LED is turned off, the device is "disarmed." Verify that your web app updates automatically to show the correct device mode.

• Verify that your web app can remotely change the device mode. Click the toggle switch in your web app, and verify that your Photon device automatically toggles modes (by checking the LED). It may take up to 2 seconds for the mode to switch due to the delay(2000) in the Photon app.

• While your Smart Security device is in "armed" mode, wave your hand over the motion sensor to trigger a motion event. Verify that your web app displays a motion notification pop-up (which will fade out after 1.5 seconds). Verify the web app displays the correct date and time for the last motion event notification.

Going Further

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

Add Starter CSS

​, and paste it into a blank CSS file named style.css.

Add Custom CSS

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

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

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 Particle API JS library 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 jQuery JS library 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.