Maker.io main logo

Controlling IoT Hardware on the Particle Photon

2016-03-29 | By Maker.io Staff

Photon

The Internet of Things is gaining in importance with ever-increasing access to the internet. The Photon allows you to connect the board to the Internet using a built-in Wi-Fi chip and this opens up the many possibilities with the Photon.

The following example will show you how to control things over the Internet using Particle functions. Usually, programming devices that access the internet can be quite complex and time consuming. Luckily the Photon uses a very simple method of using Particle functions within the sketch that either push or pull data to the web. In this example we will look at creating a simple sketch to turn an LED on or off using the Internet; this will help you understand how the Photon cloud works as well as introduce Particle functions.

A function command associates itself with your Particle device and allows you to command it to do something. Whenever it receives a Particle command, it then runs a small script within your sketch and does something. Sending commands to the Photon board actually requires you to send a HTTP POST request to the Photon.

You will need the following components for this example, they are provided in the Photon kit:

Wire up the LED to the Photon board as shown in the breadboard layout diagram below.

Figure 1: Connecting an LED to the Photon

Image of Connecting an LED to the Photon

Login to the Particle build https://build.particle.io and load up the following sketch:

int led1 = D0;
void setup()
{

   pinMode(led1, OUTPUT);

   Spark.function("led",ledToggle);

   digitalWrite(led1, LOW);

}

void loop()
{

}

int ledToggle(String command) {

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

Let's take a closer look at what is happening in this sketch example. The first part defines the variable led1 for digital pin D0, so whenever we call led1 we are actually calling pin D0. Labeling the pin makes it easier to know which pin you are using and allows efficient debugging. This is also the pin that we have connected our LED to so we can turn it on and off. The setup function defines led1 as an output pin so the Photon board knows how to handle it when we send a command to the pin. The second line is where we declare our function that we can call through the Internet:

Spark.function("led",ledToggle);

This is the code that sets up the function, giving it the name "led." The second parameter is the name of the function in our program to run when the led function is called over the Internet. Before we actually start turning the LED on or off, we need to make sure that the LED is first in an off state, using the following command to write the status to the LED:

digitalWrite(led1, LOW);

We keep the loop function part of the program empty because we have created a separate function to catch the led command and we do not need to keep listening for it in the loop function. When the ledToggle function is called as a result of receiving a message from the Internet, it receives a string as a parameter. In the HTTP request that we will send to the Photon board, we will make sure that we either turn the LED on or off using the correct parameter. If the function received a value that is either on or off, it will return 1 to indicate a successful command received. If the command sent is unsuccessful, then it will return a value of -1, indicating it has failed the checking process.

Something to also consider is the security process of actually sending commands to the Photon board. This is an important process, as you do not want your device open to anyone on the Internet to start sending ghost commands to your Photon board. Certain measures can take place when you send your commands to the Photon board. The Photon board requires up to two tokens to help secure your device.

The first token is your device's unique identifier - each of your devices will have this unique token number to help identify your device, especially when you are using several boards at the same time. You can find your device's ID by checking your device in the Particle build integrated development environment (IDE) and selecting your Particle device, as shown in Figure 2.

Figure 2: Particle Device ID

Image of Particle Device ID

The second token that you will require is linked to your Particle account rather than the device. You can find this token ID from the Setting menu in the Particle IDE, where you will see your access token, as shown in Figure 3.

Figure 3: Particle access token ID

Image of Particle access token ID

At any point you can generate a new unique access token if required; this is a good measure in case someone has accessed your token. You will need this token ID to send Web requests, so make a note of this token for later. You should now have something that looks like the following:

Device ID=55ff74062678501139071667

Access Token=cb8b348000e9d0ea9e354990bbd39ccbfb57b30

At this stage you can go ahead and upload the sketch to the photon board using the Particle cloud.

Now let’s create an interface through a web page, to send commands to the Photon board. Create a new html document and input the following HTML code:




Tell your device what to do!

Turn the LED on.
Turn the LED off.

Edit the code in the HTML document so that "your device id goes here" is your actual ID and"your access token" is your access token. You can open up a standard text editor to save this code as an .html document so that you can open it in your Web browser. Go ahead and open the .html document in your browser - you should be presented with a simple form that allows you to select either on or off.

Figure 4: Webpage interface to turn an LED on or off

Webpage interface to turn an LED on or off

When you click the Do it! button you are posting information to the URL https://api.particle.io/v1/devices/your-device-ID-goes-here/led?access_token=your-access-token-goes-here. The information you are giving is the argument value ON or OFF. This parses through the spark.function that we created. When you send the information, you will also get some information back from the page once sent that gives the status of your device and lets you know that the post was successfully sent to the Photon board. If you want to go back, just click the back button in your browser.

Summary

This is a great basic example of how to use the Particle and how to control things using the Internet. You can easily see how useful this is to create other projects such as switching a relay or driving some motors on a robotics project.

TechForum

Have questions or comments? Continue the conversation on TechForum, DigiKey's online community and technical resource.

Visit TechForum