NativeScript Particle plugin
Prerequisites
Hop on over to the Particle.io store and order any or all of their cool devices.
While developing this plugin and the demo app I used a Photon Kit and it was a joy to work with.
Thanks, Brandon Satrom for sending one over!
Installation
tns plugin add nativescript-particle
iOS 12+ setup
iOS 12 and up requires you to enable 'Access WiFi Information' for your App ID here.
Also, add this to your App_Resources/iOS/app.entitlements
(mind the name!) file:
com.apple.developer.networking.wifi-info
The demo app has this:
com.apple.developer.networking.wifi-info
Demo app
If you want to just play with your Particle device without writing code yet, follow these steps to install the demo app I've created with NativeScript Core:
git clone https://github.com/EddyVerbruggen/nativescript-particlecd nativescript-particle/srcnpm inpm run demo.ios # or demo.android
Tip: If you get tired entering your login credentials every time you log in, set the
PARTICLE_USERNAME
andPARTICLE_PASSWORD
properties to reflect your own.
Want to see the demo in action? Check out this short video 📺.
API
All examples below assume you have these imports and instantiated the Particle
class:
;;
startDeviceSetupWizard
To help registering devices to your account (and avoid having to use the Particle CLI) you can add devices to your account right from your app! 😎
particle.startDeviceSetupWizard .thenconsole.log"Wizard success? " + isSuccessful;
login
Communication between your app and a device is HTTP (REST) based, so the first step is authenticating yourself with the Particle Cloud:
particle.login .thenconsole.log"Login successful" .catchconsole.log`Login error: `;
loginWithToken
Alternatively, you can login with an access token.
particle.loginWithToken"the_token";
logout
Once done interacting with your device(s) it's best to log out as this will do a little cleanup in the plugin and underlying SDK.
There's no reason not to because it couldn't be easier:
particle.logout;
publish
Publish an event from your app to the Particle Device Cloud.
particle.publish "ledStatusApp123", // the event name "ON", // the event data (string) true, // isPrivate (default true) 30 // ttl (default 60);
subscribe
Subscribe to the firehose of public events, plus the private events published by devices one owns. You really want to use a unique prefix, otherwise you'll receive a lot of data (not only from your own devices!).
particle.subscribe "ledStatusApp123",console.log`Got a ledStatus event for App 123 from the Particle Cloud: `;
unsubscribe
To stop receiving published events, unsubscribe from the events. Make sure the prefix is equal to the one you previously subscribed with.
particle.unsubscribe"ledStatusApp123";
listDevices
Make sure you've claimed a device in your Particle account, then do this to list them in your app:
particle.listDevices .then .catchconsole.log`Error fetching devices: `;
The returned list of TNSParticleDevice
objects has these properties and functions:
Property | Type | Description |
---|---|---|
id | string |
The unique ID of this device. |
name | string |
The given name of this device. |
status | string |
The current status of the device, usually normal . |
connected | boolean |
Whether or not the device is currently connected.. |
type | TNSParticleDeviceType |
One of Unknown , Core , Photon , P1 , Electron , RaspberryPi , DigistumpOak , RedBearDuo , Bluz . |
functions | Array<string> |
The list of functions currently available on the device. You can invoke these with callFunction (see below). |
variables | Array< TNSParticleDeviceVariable > |
The list of variables currently available on the device. You can get their values with getVariable (see below). |
<device>.rename
You can change the device name right from your app! 💪
; // you got this from 'listDevices' myDevice.rename"rocket_bubble" .thenconsole.log"Device renamed" .catchconsole.log`Error renaming the device: `;
<device>.callFunction
You can invoke any of the functions
you discovered on the device.
As an example let's assume you've flashed this code tutorial to your device,
so there's a led
function which takes 1 argument: the value must be either "on"
, or "off"
:
; // you got this from 'listDevices' myDevice.callFunction"led", "on" .thenconsole.log`Result: ` .catchconsole.log`Error in callFunction: `;
What if you have a function which takes multiple arguments? Let's assume you're using the tinker app and want to set "D7"
to "HIGH"
via the "digitalWrite"
function:
myDevice.callFunction"digitalWrite", "D7", "HIGH" .thenconsole.log`Result: ` .catchconsole.log`Error in callFunction: `;
<device>.getVariable
Getting a variable is quite similar to callFunction
.
Let's say you have a variable named "analogvalue"
, then this will give you the current state of that variable:
; // you got this from 'listDevices' myDevice.getVariable"analogvalue" .thenconsole.log`Result: ` .catchconsole.log`Error in getVariable: `;
<device>.subscribe
You can get notified in your app in case an app on one of your devices publishes an event.
To suppress noise you can filter those events by supplying a prefix, in this case my-prefix-
, so events like my-prefix-temp
or my-prefix-sensorOn
are caught:
; // you got this from 'listDevices' myDevice.subscribe "my-prefix-",console.log`device event: `;
<device>.unsubscribe
To stop receiving published events from your devices, unsubscribe from the events. Make sure the prefix is equal to the one you previously subscribed with.
myDevice.unsubscribe"my-prefix-";
<device>.unclaim
Removes this device from your account.
myDevice.unclaim;
Thanks!
markoImake for adding a few very cool features.
Happy IoT'ing! 🕹🤖🚪🖲💡📸🎙⛈🚦🛎🔊