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:
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.
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.
Starting the demo will start monitoring events and set up the product you have selected.
Tell me more about what was set up
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 growth 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.
You will normally use the Add Devices button in the devices tab in the console to do this in your real products.
This control shows the status of devices in your product fleet. It's similar to the devices tab in your product in the console.
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.
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
setColorevent to all devices in the product
- A publish to the group-specific event, such as
groupa/setColor. This event will trigger all devices in
groupato set their status LED color.
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.
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.
Tell me more the device firmware
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.
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.
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.
If you are done using this tutorial, you can clean up the things that were created during this tutorial.