Photon Publish and Subscription Events

This post introduces the use of the Particle.publish() and Particle.subscribe() methods to enable photon devices to communicate via the Particle Cloud.

Particle.publish()

The Particle.publish() command allows you to trigger an event through the Particle Cloud. This means that any hook, application or device that is registered to listen to the event will be notified when it is called.

Calling Particle.publish() when the device is not connected to the cloud will not result in an event being published. This is indicated by the return success code of false. This in turn enables some form of notification to be made if the publish event fails.

Currently, a Particle device can publish at rate of about 1 event/sec, with bursts of up to 4 allowed in 1 second. A back to back burst of 4 messages will take the device 4 seconds to recover.

// Send an event by name
Particle.publish(const char *eventName);
Particle.publish(String eventName);
// Send data via a named event
Particle.publish(const char *eventName, const char *data);
Particle.publish(String eventName, String data);
// Return values
boolean (true or false)
// Example usage
bool success;
success = Particle.publish("button-pressed");
if (!success) {
// triggered if event publish failed
}

Code 1: The Particle.publish() Method

Code 1 above demonstrates (descriptive) the use of the Particle.publish() command.

Particle.subscribe()

The Particle.subscribe() command allows you to register or subscribe for a notification from a specific Particle.publish() event. This allows devices to talk to each other very easily.

Events received via the subscription are passed to a handler function; itself registered when the subscription is made.

A subscription handler (code 2) must return void and take two arguments, both of which are C strings (or const char *).The first argument is the full name of the published event. The second argument (which may be NULL) is any data that came along with the event.

void setup()
{
Particle.subscribe("button-pressed", handler);
Serial.begin(9600);
}
void handler(String event, String data)
{
Serial.print(event);
Serial.print(", data: ");
if (data)
{
Serial.print(data);
else
Serial.print("NULL");
}
Serial.println();
}

Code 2: The Particle.subscribe() Method

As with Particle.publish(); the Particle.subscribe() command returns a bool indicating its success. A subscription can be registered when the device is not connected to the cloud. In this instance the subscription will be automatically registered with the cloud next time the device connects.

A device can register up to 4 event handlers. This means you can call Particle.subscribe() a maximum of 4 times; after that it will always return false.

A Worked Example

The following example demonstrates the use of both the publish and subscribe commands by allowing for a button press and release on one device to trigger the turning on and off of a LED on situated on a separate device.

The Push-Button Circuit

Figure 1 shows a simple push-button circuit. The Photons D6 pin is connected to one leg of the push-button. That same leg of the button connects through a pull-down resistor (here 10K ohm) to ground. The other leg of the button connects to the Photons 3v3 supply.

Figure 1: A simple push-button circuit

When the push-button is open (unpressed) there is no connection between the two legs of the push-button, so the pin is connected to ground (through the pull-down resistor) and we read a LOW. When the button is closed (pressed), it makes a connection between its two legs, connecting the pin to 5 volts, so that we read a HIGH. This means that we can use the change from HIGH to LOW to trigger our Publish event.

The LED Output Circuit

Figure 2 shows a simple LED Circuit. The Photons D3 pin is connected to the positive leg of the LED via a 22K resistor. The negative leg is then simply connected to ground. Use of the resistor is to prevent the LED from burning out.

Figure 2: A simple LED output circuit

This setup enables us to control the LED by sending either a HIGH or LOW value to the pin. This in turn means that we can then use the values received via the subscription to determine whether we set the pin LOW or HIGH and thus effectively turning the LED ON or OFF.

The (Push-Button) Publish Code

The following code block provides the full source code for the push button event publisher. All the code does is read the pin connected to the push button (D6) each loop. If the button is down then a down event (“on”) is published. If up, then an up (“off”) event is published.

The flag “pressed” is used to ensure that only the first trigger and release of the button is counted.

// Register the pin that the button is
// connected to
int buttonPin = D6;
// Register and Initialise a flag to hold
// current state.
bool pressed = false;
// Register a delay period to slow things
// down if needed.
int period = 100;
// Perform the program setup
void setup()
{
// Set the button pin as an input
pinMode(buttonPin, INPUT);
// Set the pressed flag to false
bool pressed = false;
// Set the initial state of subscriber
// to off just in case.
Particle.publish("ledToggle", "off");
}
// Loop through the program
void loop()
{
// Check to see if the button is pressed
// or not. The use of flags ensures that
// only a singular event is called for
// each state.
if(digitalRead(buttonPin) == LOW)
{
// The button is released. Check against the flag
// to see if it has already been set. If so return.
if(pressed == false)
return;
// The flag has not been set so set it now.
pressed = false;
// Publish the off event.
Particle.publish("ledToggle", "off");
}
else if(digitalRead(buttonPin) == HIGH)
{
// The button is pressed. Check against the flag
// to see if it has already been set. If so return.
if(pressed == true)
return;
// The flag has not been set so set it now.
pressed = true;
// Publish the on event.
Particle.publish("ledToggle", "on");
}
// Use a delay to slow down the loop; thus allowing
// time for operations to complete.
delay(period);
}

Code 3: The (Push-Button) Publish Code

The (LED Output) Subscribe Code

The subscription code is much simpler than that of the publish code. All we are doing here is initialising the led pin (D3) as an output, and then setting it to LOW. We then subscribe to the event ledToggle and pass the handler myHandler at the same time.

The following code block provides the full source code for the led subscription.

int led1 = D3;
void setup()
{
// Set both LED pins as outputs
pinMode(led1, OUTPUT);
// Set both LED's to off by writing
// LOW to the pin.
digitalWrite(led1, LOW);
// Register the subscription and assign
// a handler for it
Particle.subscribe("ledToggle", myHandler);
}
// The handler for the subscription
void myHandler(String event, String data)
{
if(data == "on")
digitalWrite(led1, HIGH);
if(data == "off")
digitalWrite(led1, LOW);
}
view raw LedSubscribe.ino hosted with ❤ by GitHub

Code 4: The (LED Output) Subscribe Code

The handler is triggered each time the event is Published and depending on if the data sent equates to “on” or “off” the status of the LED is updated accordingly.

Figure 3: Both circuits working together

The above image (Figure 3) shows the system in action. As the button is pressed; the other circuits LED lights.

A copy of the full source code can be found here.

A copy of this post published via the IoST Project can be found here.

«

This post introduces the use of the Particle.publish() and Particle.subscribe() methods to enable photon devices to communicate via the Particle Cloud.