Getting Started with PubNub and Particle.io Devices

getting started particle pubnub tutorial

At just under an inch and a half long and three quarters of an inch wide, Particle’s Photon is an easy fix for makers who want a compact, cloud-compatible board for their projects. Because while the small size is a major plus, the real selling point of this little board is the cloud integration that comes with it. Particle has built its boards around the idea that they should be completely compatible with cloud technology, with built-in functions that allow them to easily access existing WiFi or cellular networks. By adding PubNub to that equation, you can easily integrate Particle’s boards into your projects, in a similar manner to the way you would use an Arduino, but with a different IDE and more intuitive cloud integration. With that in mind, this tutorial will show you how to set up the Photon with PubNub and use it to both publish messages and subscribe to channels.

The full code repository is available on GitHub.

Setting Up the Photon

There are two separate ways to set up your Photon: through your computer or through Particle’s app on either IOS or Android. However, in order to integrate PubNub, you’ll have to use Particle’s online IDE, which means it’ll be easier to just set everything up through your computer. But if you want more to explore, feel free to mess around with the app on your own.

Installing Software

After plugging in your device, you’ll need to install Node.js, as it’s how the Particle CLI runs. If you’re working on Windows, you’ll also need to install the Particle Driver. The last thing you’ll need to do is create a Particle account, if you haven’t already. It’s easy to do through the Particle website.

Setting Up with the Command Prompt

The next part of the installation process utilizes your command prompt, so open that up on your computer. Type the following command into the terminal, then input your password when prompted. Keep in mind that if you’re working on a mac you may have to run the program as a root.
npm install -g particle-cli
Make sure you get a success message, like the top image, and not an error message, shown below it.

Next, you’ll need to set up your particle with the following command, then input your Particle username and password when prompted.
particle setup
If you’ve already claimed your device and just want to connect it to WiFi, type particle serial wifi instead of particle setup. This will set up your device on the current WiFi. No matter which command you used, follow the directions in the terminal to connect to your WiFi network, and you’re good to go! You’re ready to start working with the Particle IDE.

Running Your First Particle Sketch

After you’ve set up your Photon, open up the online Particle IDE and you’re ready to start importing libraries and putting together your first sketch.

Writing and Formatting Github Libraries

We’ve already written and formatted the PubNub library so that it can be used in Particle sketches, but for future reference here are some guidelines about how to adjust the format of Github libraries so that they can be imported to Particle.

The .h and .cpp files, as well as the Examples folder, need to be in a folder called Firmware
There needs to be a file called spark.json which lists the name, version, author, license, and description of your libraries in json format
Make sure that you have both LICENSE and README files in the repo

If you follow all those steps, your library should import to Particle without a hitch! Keep in mind that you may have to change some other aspects of the library in order for it to compile properly, depending on how complex it is. A good start is including application.h at the top of your library, as this helps a lot with converting Arduino libraries to Particle.

#include "application.h"

Including the PubNub Library

After opening up your first sketch, the first thing you’ll need to do is include the PubNub library. Click on the Libraries tab in the bottom left, then click Contribute Library. Type in pubnub/particle-pubnub and click Add Repository to include the PubNub library in your sketch. Now, click Include in App and you’re ready to start using PubNub with your Photon.

Publishing and Subscribing

To subscribe or publish to a PubNub channel, the process is virtually identical to the way you would do it in Arduino. I’ll walk through it anyway, because there are some slight changes, but if you’re used to working with Arduino, this should be very familiar to you. First, you need to input your publish and subscribe keys, as well as your channel name.

char pubkey[] = "demo";
char subkey[] = "demo";
char channel[] = "helloworld";

In the setup portion of your code, you need to initialize PubNub, as shown below.

void setup()
{
	Serial.begin(9600);
	Particle.publish("Serial set up");
	PubNub.begin(pubkey, subkey);
}

Then, in void loop(), you have to define your client. In Particle, unlike in Arduino, this client is a TCPClient, not a WiFi or Ethernet client. After that, you can publish a message or subscribe to your channel.

void loop()
{
	TCPClient *client;
	char msg[64] = "{\"photon\":\"on\"}";
	client = PubNub.publish(channel, msg);
	client->stop();
	delay(200);
}

void loop()
{
       TCPClient *client;
       client = PubNub.subscribe(channel);
       while client->connected() {
	    char c = client->read();
	    Serial.println(c);
	}
	client->stop();
	delay(200);
}

And you’re done! To run the sketch, just make sure your Photon is plugged in and connected to WiFi, then click the Flash icon in the top left corner of the screen. It’s that easy!

Debugging Particle Boards

At the moment, debugging Particle boards is pretty tricky since Particle doesn’t have a debugging console included in their IDE. However, there are several other tricks you can use to help with a misbehaving Photon, as well as tools you can use to make sure you are in fact connecting to PubNub.

Putting the Photon into Safe Mode

One cool feature of the Photon is the multicolored flashing LED on the top that gives the user a clue as to what state the hardware is in, which you can decode using this guide from Particle. If the light on your Photon starts flashing red, chances are something is going wrong with the hardware, and the best thing to do is put it into Safe Mode. Do this by pressing both the Reset and the Setup buttons for a few seconds, then release only Reset. Continue holding Setup until the light turns purple, and your device should be in safe mode!

Using PubNub’s Developer Console

To determine whether you’re successfully publishing to a PubNub channel, you can use PubNub’s Developer Console. Simply open up the console, input your subscriber key and channel name, and look to see whether any messages are being published to the channel.

Using Serial Communication

To see whether your Photon is receiving messages, you’ll need to monitor Serial communication. First, add Serial.print statements to your code to show any messages that the Photon receives from PubNub. Then, open up your command prompt and type in the following line to locate the serial port your device is using.

ls /dev/tty.*

Show the serial communication using the screen command and the name of the port that you just looked up – it will have the word usb somewhere in its name.

screen <port> 9600

If your device is receiving messages, you should see them printed to the screen. If not, you’ll need to go back and check your code for errors.

Moving Forward with Particle and PubNub

Now that you know how to use PubNub with the Photon, you can try it out with any of Particle’s other boards by simply importing the PubNub library. All of the boards are essentially Arduino-compatible, so go ahead and try using some of your Arduino programs to explore the different capabilities of the board – controlling hardware, communicating with other devices, or using it as a controller for your IoT projects. With any luck, you’ve just discovered another go-to device for all things IoT.