Cloud Communication - Subscribe

Cloud Communication

iot_cloud

Review: Publishing Events

  • Events are messages sent from an Argon 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

1569446342143

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

  • Argon can by notified when a particular event published
    • This is called subscribing to an event
  • When the notification arrives, the Argon 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

  • Argon tell the cloud, “I want to listen for something called an event”
  • Later, Cloud tells Argon, “The event just happened, and here is some data (variables)”
  • Argon 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 Argon 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

Updated: