Light a IOT LED from web with Particle Photon

What we will do

We build an IOT LED or internet of things led that can be turned on and off real-time from a website using button or link. We will code it in Particle from particle’s online IDE and upload the code directly on the board. This process is called Over The Air (OTA) upload. When we upgrade our software or operating system that the same thing happens to our phone OS. We can also connect the Particle microcontroller to the computer with USB cable and upload the code just like we do for another processor like Arduino. But for this post, we will do OTA firmware upload. For that we will use Particle coding almost like Arduino or C code and the in the web part we will use Javascript, Jquery, and Ajax to build our IOT LED.

Circuit Connection for IOT LED

First thing’s first. Let’s set up the circuit like above pictures. We have two LEDs (IOT LEDs). One is red and another is green. The negative (shorter) pin of the green LED is connected to ground via a resistor and the positive (longer) pin is connected to D0. Similarly, the negative (shorter) pin of the red LED is connected to ground via a resistor and the positive (longer) pin is connected to D0. I used 500 ohms(green, black, brown). Any resistor between 200ohm and 1K can be used.

Tinker App, Particle device library, Particle Cloud SDK and Device Firmware

Tinker is the default firmware in the micron-controller when shipped the particle. The purpose of the firmware is to communicate (send the signal and receive values) by the particle app that installed on the phone. Here are the iOS and Android download links. If you want the code for particle app for the photon, here is the link. Now, we need to keep in mind that Tinker is not the device's system firmware. It is just like other firmware like we are going to be write in few moments. Now if we want to build our own mobile app what we need to do is:

1. We can see and download the Particle Mobile App (that communicates with the Tinker firmware) and modify, add and delete as necessary or we can do step 2 and step 3


2. We need to download the particle device setup library for iOS  or Particle Device Setup library for Android to connect and communicate the Particle devices (photon or core) with our app, for example sending WiFi credential using SmartConfig or Soft AP. SmartConfig is setting up WiFi configuration for TI (texas instrument) product like CC3000 (nowadays it is used for other WiFi processor also) and Soft AP is more like a general term — Software enabled Access Point.


3. Then we need the Particle iOS Cloud SDK or Particle Android Cloud SDK to communicate with the device from App over particle cloud. So, Particle Setup Library is local communication and Particle Cloud SDK is over the cloud communication. Particle Cloud SDK is used to manage user session, claiming/disclaiming device, reading pin or sending a command over the cloud etc.


4. Now as I said, system firmware is not the Tinker app. The system firmware is the embedded Operating system built by Particle for the photon. The photon automatically shipped with the pre-programmed bootloader, system firmware, and Tinker. I am not quite sure why Particle confused this in their doc [The doc I am seeing is dated Dec 25, 2015]. If you look closely the app for android or iOS is called particle not tinker. You can see the system firmware here. We need to be an ST-link programmer to modify or update the firmware. Tinker uses this firmware library and function on top of the firmware. Why I am telling that is because when you connect to the device for the first time, you can see it would ask to flash the tinker and the device will show as "online, non-tinker." Device system firmware includes firmware API to build your own embedded firmware, Soft AP/SmartConfig libraries/function etc. Tinker app is not officially exposed. There could be some community contribution like this which should be something like Tinker (not exactly, I think). But we can see all the tinker binaries for different particle devices here.

There is a good description of the firmware function here and an explanation of the working difference between Particle Cloud SDK and device library is here.

Enough talking. Let's get into work.

Soft AP configuration

Download the Particle App. Just Follow the self-explanatory steps. The steps should be:

1. Opening the app and Logging in or signing up for an account with Particle.


2. Go to the WiFi settings of the phone.


3. There should be a WiFI network something like Photon-XXX. Connect to that network.


4. Come back to the Particle App. It will recognize the device  and gave a name like Photon-XXX. Once connected you will have the option to change the name.


5. After the device is connected it will show it as non-tinker. If you click on the device name it will ask whether you want to flash the tinker or not. We don't want to flash tinker because we want to download our own firmware of IOT Led. After Connecting to the WiFi using the Particle App, we are not going to the "tinker" part of the mobile App. So, the work of the mobile part is pretty much done here.  The device can store up to five networks.

Load the program/firmware from particle online/web IDE

Now we are going to write the embedded code for particle and load it OVA (over the air). We can load the code locally by connecting USB like we do for other micro-controllers like Arduino. But for this case, we will load OVA and it is easier.

1. Go to http://build.particle.io. You need to login or signup. You should already have an account if you set up device through particle App. Anyway, log in and you will see the web IDE. It should be looked like this:
   
   
   


2. The IDE is already waiting for new embedded code to be written


3. The code that we would write is:

int led1 = D0;
int led2 = D1;

void setup()
{

// Here's the pin configuration
pinMode(led1, OUTPUT);
pinMode(led2, OUTPUT);

// We are also going to declare two Spark.function(s) so that we can turn the LED on and off from the cloud.
Particle.function("led1",led1Toggle);
Particle.function("led2",led2Toggle);
// 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);
}
// Since we're waiting for input through the cloud,
// we don't actually need to put anything in the loop

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

// We're going to have two functions for our two leds that get called when a matching API request is sent
// This is the led1Toggle and led2Toggle function we registered to the "led" Spark.function earlier.

int led1Toggle(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);

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

return 0;
}
else {
return -1;
}
}

int led2Toggle(String command) {
if (command=="on") {

digitalWrite(led2,HIGH);
return 1;
}
else if (command=="off") {

digitalWrite(led2,LOW);
return 0;
}
else {
return -1;
}
}

The code is commented out and described properly. So, I leave the explanation with the comment.

4. The HTML and CSS including the code particle code above are in this repository: https://github.com/knsakib/IOT-LED-with-Particle-Photon
For the Toggle button CSS, I took help from this site: https://proto.io/freebies/onoff/
The CSS code in the repository. For two LEDs green and red, we have written two on click events redOnChangeCheckbox and greenOnChangeCheckbox which will set the variable paramStr="on" or paramStr="off" based upon the checkbox is checked or not. Depending which events is occurring(red or green) it will set the variables setFunc = "led1" (green led) and setFunc = "led2" (red led). For example, I am showing only one on click function here:

function greenOnChangeCheckbox (checkbox) {
setFunc = "led1";
if (checkbox.checked) {
paramStr = "on";
}
else {
paramStr = "off";
}
var requestURL = "https://api.spark.io/v1/devices/" +deviceID + "/" + setFunc + "/";
$.post( requestURL, { params: paramStr, access_token: accessToken });
}

5. Finally, the page looks like https://codepen.io/knsakib/pen/GYvwGm