The defining feature of an IoT device is its ability to send and receive information through the internet. This allows an IoT device to interact with other apps or other IoT devices. For this project, you'll be creating a web app that interacts with your Photon device through the internet.

All of your Photon's internet communications are routed through the Particle Cloud service, which offers these ways that a web app can interact with a Photon device through Particle Cloud:

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

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

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

In order to make your Photon device interact with your web app, you'll need to add special code to both your Photon device app and your web app:

• The Particle firmware on your Photon device has built-in cloud functions to allow your device to interact with a web app through Particle Cloud. You'll need to add code statements using these cloud functions in your Photon device app.

• There is a Particle API JavaScript library that provides methods (functions) to allow your web app to interact with your Photon device app through Particle Cloud. You'll need to load this JS library in your web app's HTML file, and then add code statements using the library's methods in your web app's JavaScript file.

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

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

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

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

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

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

Photon Device App

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

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

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

Send Event Without Data

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

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

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

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

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

Send Event With Data

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

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

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

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

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

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

Web App JS

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

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

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

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

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

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

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

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

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

For example, you could add code to:

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

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

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

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

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

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

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

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

Photon Device App

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

Share Device Function

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

Particle.function("cloudFunc", deviceFunc);

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

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

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

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

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

Modify Device Function

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

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

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

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

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

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

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

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

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

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

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

Calling Device Function

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

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

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

deviceFunc("text");

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

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

Using String Parameter

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

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

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

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

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

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

Web App JS

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

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

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

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

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

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

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

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

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

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

Calling JS Function

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

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

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

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

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

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

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

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.

Option 1: Load from CDN

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

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

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

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

Option 2: Load Local Files

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

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

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

<script src="particle.min.js"></script>
<script src="jquery.min.js"></script>
<script src="script.js"></script>

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

Create Web App JS File

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

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

Create Particle Object

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

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

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

var particle = new Particle();

Device ID & Access Token

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

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

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

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

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

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

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

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

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

Photon Device App

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

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

Particle.variable("cloudVar", deviceVar);

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

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

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

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

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

Allowed Data Types

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

• int (whole numbers)

• double (decimal numbers)

• String (text, up to 622 characters)

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

Web App JS

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

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

function webFunction() {
    particle.getVariable({ deviceId: myDevice, name: "cloudVar", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        
        
    }, function(err) {
        console.log("An error occurred:", err);
    });
}

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

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

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

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

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

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

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

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

For example, you could add code to:

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

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

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

Set Interval to Get Variable

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

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

window.setInterval(webFunction, 2000);

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

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

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

Getting Multiple Variables

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

function webFunction() {
    // get 1st variable
    particle.getVariable({ deviceId: myDevice, name: "cloudVar1", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        
        
    }, function(err) {
        console.log("An error occurred:", err);
    });

    // get 2nd variable
    particle.getVariable({ deviceId: myDevice, name: "cloudVar2", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        
        
    }, function(err) {
        console.log("An error occurred:", err);
    });
}

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

function webFunction1() {
    particle.getVariable({ deviceId: myDevice, name: "cloudVar1", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        
        
    }, function(err) {
        console.log("An error occurred:", err);
    });
}

function webFunction2() {
    particle.getVariable({ deviceId: myDevice, name: "cloudVar2", auth: myToken }).then(function(data) {
        // add code to do something with value returned as: data.body.result
        
        
    }, function(err) {
        console.log("An error occurred:", err);
    });
}