Function and publish demo

This is an interactive tutorial that show the difference between functions and subscribing to Particle events on-device, and how you can use these techniques to send commands to remote devices.

Use a function to set the status LED color of a single device.
Use a published event to set the status LED color of all devices in your fleet.
Use device groups to set the status LED color of a subset of your device fleet.

To fully experience the demo, you should have two or more devices of the same type. Both cellular and Wi-Fi devices are supported, however this demo does not work with the Tracker and isn't useful if your device does not have a visible status LED.

If you're interesting in having devices trigger external services, see the webhook demo.

In order to use this tutorial, you must be logged into your Particle account:

Cloud setup

Select a product

You should typically start with a product. You'll eventually need one to scale, and it makes it easier to group devices.

This demo requires a product, and each product can only have a single device platform, so you must select that first.

Device platform:
Create new product
Use an existing product

You can find all of your sandbox products in the productsTab in the Particle console.

There is no charge for creating products in your free developer sandbox and there is no limit on the number of products, though there is a limit to the number of devices in the free plan.

Start demo

Starting the demo will start monitoring events and set up the product you have selected.

Product setup

Start Demo to set up the product configuration.

Tell me more about what was set up

Add devices to product

Whenever you have a product, you must add devices to it. When you scale, you will typically add all of the devices in your order at once, as you will be emailed a list of the Device IDs in your order. In the basic and enterprise plans, just adding the Device ID to the product does not affect billing; billing only starts the first time the device connects to the Particle cloud.

For this demo, you can just select existing devices from your developer sandbox to use in this tutorial. If you do not have a device yet, you can skip this step and use the Test feature to show how the webhook works without a device.

Start Demo to add devices to your product.

You will normally use the Add Devices button in the devices tab in the console to do this in your real products.

Your device fleet

This control shows the status of devices in your product fleet. It's similar to the devices tab in your product in the console.

Start Demo to see the devices in your product.

The online column shows a green checkbox if the device is online and connected to the Particle cloud.
The firmware column shows a green checkbox if the device has product firmware and has come online at least once. When you onboard your first device, you have to manually request the firmware be flashed to it. Click the Flash link to do this.
The development column checkbox shows if the device has the Mark as Development device flag set. You can also change the state using this checkbox. You normally should leave this turned off.
Use the groupa and groupb checkboxes to set some devices to groupa and some to groupb. A device can be in more than one group, if desired. Clicking the checkbox changes the state in the cloud and if the device is online, reconfigures it in a few seconds. If the device is offline or in sleep mode, it will get the current device group settings from the cloud after it comes online.

Testing

The test firmware updates the status LED color of the device on request from the cloud in several situations:

A function call to the specified device
A publish of the setColor event to all devices in the product
A publish to the group-specific event, such as groupa/setColor. This event will trigger all devices in groupa to set their status LED color.

Functions

Start Demo to interact with it.

This control will set the status LED of the specified device to the specified color for 10 seconds.

Functions are directed at a single device, by its Device ID. This is good when you want to control a single device at a time.

You can only call functions when the device is online. If the device is turned off or in sleep mode, the function call will fail with an error.

Unlike publish, however, the error indicates that the function was or was not handled. With publish, there is no indication to the caller whether any device received the publish.

Publish

Start Demo to interact with it.

This control will set the status LED of all devices or certain device groups to the specified color for 10 seconds.

Publish goes out to zero or more devices. This is handy when you need to broadcast to many devices, or a selection of devices, at the same time.

The downside is that you don't know whether any devices received the publish, and if the device is offline, the publish is lost forever and the device will not receive it later.

Device firmware

Tell me more the device firmware

These are the header files.

Particle.h file is used in all .cpp files to include the standard Particle features.
DeviceGroupHelperRK.h is a library used to handle device groups.
SetColor.h is file that handles updating the RGB status LED. It's included in the source to this project.

#include "Particle.h"

#include "DeviceGroupHelperRK.h"
#include "SetColor.h"

This is recommended for all applications:

SerialLogHandler logHandler;
SYSTEM_THREAD(ENABLED);

All products must include the version number, and increment it when creating a new product firmware version to upload to the console. This is an integer, not a semver.

PRODUCT_VERSION(1);

This is a forward declaration of a C++ function. When you use a .cpp file (as opposed to a .ino file) you must include forward declarations for function you use before the implementation.

void groupCallback(DeviceGroupHelper::NotificationType notificationType, const char *group);

Global variables, which will be described below when they are used.

int firmwareVersion = (int) __system_product_version;
SetColor setColor;

The setup() function is called at boot. This firmware creates a variable called "FunctionPublishDemo01". This is useful because it makes it easy to see what product firmware is flashed to a device from the console.

void setup() 
{
    // This variable is used to more easily identify which product firmware is running
    Particle.variable("FunctionPublishDemo01", firmwareVersion);

This registers a function ("setColor") and subscribes to the "setColor" event. Even though they share a name, they're independent.

setColor.function("setColor");
setColor.subscribe("setColor");

This sets up the Device Group Helper library.

It retrieves the device groups at boot (this uses 2 data operations). This uses a product webhook.
It calls a function when the device groups are retrieved
It also registers a function to allow the device groups to be set from the cloud. The demo website uses this to update groups immediately after changing them.

DeviceGroupHelper::instance()
    .withRetrievalModeAtStart()
    .withNotifyCallback(groupCallback)
    .withFunction("setDeviceGroups")
    .setup();

The loop() function is called 1000 times per second. This firmware just gives time to the setColor pseudo-library and the actual device group helper library. You would probably have more things in your actual firmware.

void loop() 
{
    setColor.loop();
    DeviceGroupHelper::instance().loop();
}

This function is called from the device group helper library when the device groups are retrieved.

void groupCallback(DeviceGroupHelper::NotificationType notificationType, const char *group) {
    switch(notificationType) {
    case DeviceGroupHelper::NotificationType::UPDATED:
        {

The most important part is handing update.

Remove all previous subscriptions.
Resubscribe to the setColor event. This affects all devices in the fleet.
For each device group the device is subscribed to, also subscribe to "groupName/setColor". This is used to set the status LED color of all devices in a device group.

Log.info("updated groups");
Particle.unsubscribe();
setColor.subscribe("setColor");
auto groups = DeviceGroupHelper::instance().getGroups();
for(auto it = groups.begin(); it != groups.end(); it++) {
    String groupName = (*it).c_str();
    String subEvent = String::format("%s/setColor", groupName.c_str());
    Log.info("subscribing to %s", subEvent.c_str());
    setColor.subscribe(subEvent);
}

Also note the contents of the project.properties file. To include a library, you must include it in project.properties and include any relevant header files.

Event log

This control shows the same information that is shown in the events tab in your product so you don't need to switch between multiple windows.

Published events show up here, but function calls and variable requests do not, as they are not events.

Start Demo to begin listening for events in your product.

Device logs

If you have your Particle device connected by USB to your computer (Windows, Linux, Mac, or Chromebook), and you are using the Chrome web browser, you can monitor your device's USB serial debug log from this interactive control. You can also use particle serial monitor from the Particle CLI if you prefer. Both are optional, but are good for troubleshooting.

Open in Workbench

The recommended development environment for Particle firmware is Particle Workbench. To open this project in Workbench:

Use the Download Full Project (*.zip) option in Device Firmware, above.
Extract the zip file on your computer.
Open Visual Studio Code
Use the File - Open option to open the directory you just extracted. Make sure you open the directory, not a single file in it.

Most operations are in the command palette (Ctrl-Shift-P on Windows and Linux, Command-Shift-P on Mac). Some useful commands:

Particle: Login Log into your Particle account.
Particle: Configure Project for Device Set the type of device and the version of Device OS you want to use.
Particle: Cloud flash Compile the project and flash it to a device OTA.
Particle: Cloud compile Compile the project and download the .bin file.

Clean up

If you are done using this tutorial, you can clean up the things that were created during this tutorial.

You must Start Demo to retrieve product information before it can be cleaned up.

Log in using:	Username and Password Access token
Username (Email):
Password:
Maximum time to stay logged in:
Access token: