III. Adding Internet: Intro. to Functions

Overview

This project will allow you to control your LED from the Internet!

Goals

  • Introduce basic cloud-based services.
  • Work with string parsing.
  • Start using a REST API

Recommended Preparation

  1. Complete the previous Blinky Project
  2. Find out about functions. Review Particle.function()
  3. Learn a little about POST methods.
  4. Learn about the Particle Console

Part 1: Responding to the Cloud

This example comes directly from Particle’s Control LEDs over the `net example. You’ve already completed the Intro and Setup. You just need to add a little more Code. Either replace your existing code with the following, or create a new file, or open the “WEB-CONNECTED LED” example app:


// CODE COPIED FROM https://docs.particle.io/guide/getting-started/examples/photon/#code-1
// Also available as the "WEB-CONNECTED LED" in the Example Apps section of your Particle Apps panel.
// ----------------------------------- 
// Controlling LEDs over the Internet
// -----------------------------------

/* First, let's create our "shorthand" for the pins
Same as in the Blink an LED example:
led1 is D0, led2 is D7 */

int led1 = D0;
int led2 = D7;

// Last time, we only needed to declare pins in the setup function.
// This time, we are also going to register our Particle function

void setup()
{

   // Here's the pin configuration, same as last time
   pinMode(led1, OUTPUT);
   pinMode(led2, OUTPUT);

   // We are also going to declare a Particle.function so that we can turn the LED on and off from the cloud.
   Particle.function("led",ledToggle);
   // This is saying that when we ask the cloud for the function "led", it will employ the function ledToggle() from this app.

   // For good measure, let's also make sure both LEDs are off when we start:
   digitalWrite(led1, LOW);
   digitalWrite(led2, LOW);

}


/* Last time, we wanted to continuously blink the LED on and off
Since we're waiting for input through the cloud this time,
we don't actually need to put anything in the loop */

void loop()
{
   // Nothing to do here
}

// We're going to have a super cool function now that gets called when a matching API request is sent
// This is the ledToggle function we registered to the "led" Particle.function earlier.

int ledToggle(String command) {
    /* Particle.functions always take a string as an argument and return an integer.
    Since we can pass a string, it means that we can give the program commands on how the function should be used.
    In this case, telling the function "on" will turn the LED on and telling it "off" will turn the LED off.
    Then, the function returns a value to us to let us know what happened.
    In this case, it will return 1 for the LEDs turning on, 0 for the LEDs turning off,
    and -1 if we received a totally bogus command that didn't do anything to the LEDs.
    */

    if (command=="on") {
        digitalWrite(led1,HIGH);
        digitalWrite(led2,HIGH);
        return 1;
    }
    else if (command=="off") {
        digitalWrite(led1,LOW);
        digitalWrite(led2,LOW);
        return 0;
    }
    else {
        return -1;
    }
}

Program your Photon!

Part 2: Testing your Code via the App

  1. If you haven’t already done so:
    1. Install the Particle.io app:
    2. Open the App and log in to your Particle.io Account.
  2. Use the App to send commands to your LED:

Part 3: The Internet of the Thing

To be able to interact with your “Things” from the web, you’ll have to:

  1. Get the Access Token associated with your account.
  2. Get the ID of the “thing” you want to interact with.
  3. Use these (the token and ID) in a webpage that sends commands to the “thing”. This example uses a simple, non-secure webpage and HTML POST methods.

Creating the WebPage

This example includes your Access Token and your Device ID in readable HTML. It should only be on secure machines. Posting it publicly would allow anyone to interact with your device!!!

Create a new file using a text editor. Make its extension be .html and paste the following HTML in it:

<!-- Replace your-device-ID-goes-here with your actual device ID
and replace your-access-token-goes-here with your actual access token-->
<!DOCTYPE>
<html>
  <body>
  <center>
  <br>
  <br>
  <br>
  <form action="https://api.particle.io/v1/devices/your-device-ID-goes-here/led?access_token=your-access-token-goes-here" method="POST">
    Tell your device what to do!<br>
    <br>
    <input type="radio" name="arg" value="on">Turn the LED on.
    <br>
    <input type="radio" name="arg" value="off">Turn the LED off.
    <br>
    <br>
    <input type="submit" value="Do it!">
  </form>
  </center>
  </body>
</html>

(Code is an excerpt from Particle’s Control LEDs over the `Net example)

Adding your Access Token to the code.

  1. Open the Particle.io Build Page and select Settings:
    Settings
  2. Copy the Access Token and paste it into the HTML file in place of the your-access-token-goes-here placeholder on the 10th line.
    Token

Adding the ID of the “thing”

  1. Open the Particle Console
    Console
  2. Select the My Devices Tab, Copy the Device ID for your Photon, and Paste it into the HTML file in place of the your-device-ID-goes-here placeholder on the 10th line.
    Console

Trying It

  1. Save the HTML file.
  2. Open it in a browser and try it out!

Going Further

  1. Add a blink command that will make the LED blink.
  2. Add a fadeOn N command, where the parameter N is a number indicating the total time for the fade to take (in milliseconds). Hint: Review the features of the String Class to separate and parse the integer value.
  3. Add an onIn N command, where the parameter N is a number indicating how long until the light should turn on from when the command is received. Hint: Review the features of the Timer Objects.
  4. Add a complementary offIn N.
  5. Tracing, (i.e., using log messages from print statements to understand the execution of code), is one of the most valuable debugging techniques for the Photon. Learn how use the Serial object to see debugging messages.
  6. Add a onAt N command, where the parameter N indicates the UTC time at which the light should turn on. The Photon includes functions to Synchronize the Time and get or set properties of current time. Pay close attention to time zone and daylight savings time. (Seriously consider using log messages to help debug your work!)

ACM Curriculum

Reference

See Particle’s Blink an LED Code Example


Tweet