Cloud Communication - Subscribe

Cloud Communication

Review: Publishing Events

• Events are messages sent from a Photon 2 to the cloud as often as you choose
• Events are private (viewable by only by you and devices in your account)
• Events can be accessed in Particle console, app, or by other devices (subscribing)

Events in Particle Console

Publish Syntax

Particle.publish(<<EVENT_NAME>>, <<EVENT_VALUE>>); 

Example

Particle.publish("lightValue", "bright"); 
Particle.publish("tempFahr", String(85.9));

• Names and values must always be strings
• Should only publish 1 event / sec (or burst of 4 events in 1 sec)

Events Part 2: Subscribing to Events

• Photon 2 can by notified when a particular event published
  • This is called subscribing to an event
• When the notification arrives, the Photon 2 can then call a function
  • This function is called an event handler
  • Performs any action in response to the event
• Can subscribe to any public events, or any private event generated by devices in your account

Event-Driven Programming Overview

• Photon 2 tells the cloud, “I want to listen for something called an event”
• Later, Cloud tells Photon 2, “The event just happened, and here is some data (variables)”
• Photon 2 then automatically executes the event handler function
  • This seems confusing–WE DO NOT call the event handler function
  • We just define the function body, and Photon 2 calls it when the event arrives

Illustration - Subscription Setup

Illustration - Subscription Setup

Illustration - Event Published

Illustration - Subscription Notification

Illustration - Event Handler Function

Subscribing Process

1. Create an event handler (regular C++ function) to be called when the event arrives
2. Call Particle.subscribe within setup() to register the subscription

Review: Publish Syntax

Particle.publish(<<EVENT_NAME>>, <<EVENT_VALUE>>); 

Example

Particle.publish("lightValue", "bright"); 
Particle.publish("tempFahr", String(85.9));

Subscribing Syntax: Event Handler

void <<EVENT_HANDLER>>(const char* event, const char* data) {

Example

void tempEventHandler(const char* event, const char* data) {
    Serial.println("Just received the event called " +
                   String(event) + " with the value " + 
                   String(data));

Subscribing Syntax: Event Handler

void tempEventHandler(const char* event, const char* data) {

• event is the parameter that will be the event name
• data is the parameter that will be the data sent by the event
• Technically, these are pointers to C-style arrays. For our purposes, we will convert them to String

Subscribing Syntax: Subscribing to an Event

Particle.subscribe(<<EVENT_NAME>>,
                   <<EVENT_HANDLER_C++_FUNCTION>>);

Example

void setup() {
    Particle.subscribe("tempFahr", tempEventHandler);

• You can only subscribe events published in your account

Important Note

• The exercises that follow describe public events
• As of Fall 2020, public events have been discontinued in Particle cloud
• You can only publish private events and subscribe to private events in your Particle account

Exercise

Exercise

• Subscribe to public event called ITP348_color_change_event
• The data of this event will be a number from 0-3. Use this number to change the color on your LED below
  • 0 is white, 1 is green, 2 is magenta, 3 is yellow, 4 is red

Lab Goal

• Working in pairs, have an “open door” on one student’s device change the LED color on the other student’s device

Lab Part 1:

Lab Part 1:

• Create an enum called DoorState with the values OPEN and CLOSED. Make a global variable called myDoor to track your switch
• When the magnetic switch is opened or closed, change the state of myDoor
• Publish public cloud event with the data doorIsOpen or doorIsClosed when myDoor changes. Note only one publish should occur every time door is opened or closed
• Your name should be ITP348/Door/<<YOUR_INITIALS>>

Lab Part 2:

• Create event handler
• Register a subscriber for the your partner’s student’s event ITP348/Door/<<THEIR_INITIALS>>
• Change the RGB colors based on their door status
  • Red means “door is open”
  • White means “door is closed”

Documentation

• Particle Cloud API
• Publishing Events
• Cloud Variables
• Cloud Functions
• Subscribing to Events