{"id":15305117,"url":"https://github.com/eddyverbruggen/nativescript-particle","last_synced_at":"2025-07-02T22:34:26.024Z","repository":{"id":57308679,"uuid":"146579570","full_name":"EddyVerbruggen/nativescript-particle","owner":"EddyVerbruggen","description":"🕹 Control your https://particle.io devices from NativeScript","archived":false,"fork":false,"pushed_at":"2019-07-27T19:58:17.000Z","size":2401,"stargazers_count":20,"open_issues_count":2,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T23:13:06.326Z","etag":null,"topics":["iot","nativescript","nativescript-plugin","particle","particle-electron","particle-io","particle-photon"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EddyVerbruggen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-29T09:49:27.000Z","updated_at":"2024-05-30T16:04:11.000Z","dependencies_parsed_at":"2022-08-29T04:52:47.720Z","dependency_job_id":null,"html_url":"https://github.com/EddyVerbruggen/nativescript-particle","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-particle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-particle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-particle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-particle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-particle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975328,"owners_count":21192210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iot","nativescript","nativescript-plugin","particle","particle-electron","particle-io","particle-photon"],"created_at":"2024-10-01T07:59:17.273Z","updated_at":"2025-04-14T23:13:25.034Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NativeScript Particle plugin\n\n[![NPM version][npm-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[build-status]:https://travis-ci.org/EddyVerbruggen/nativescript-particle.svg?branch=master\n[build-url]:https://travis-ci.org/EddyVerbruggen/nativescript-particle\n[npm-image]:https://img.shields.io/npm/v/nativescript-particle.svg\n[npm-url]:https://npmjs.org/package/nativescript-particle\n[downloads-image]:https://img.shields.io/npm/dm/nativescript-particle.svg\n[twitter-image]:https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social\u0026label=Follow%20me\n[twitter-url]:https://twitter.com/eddyverbruggen\n\n\u003cimg src=\"https://github.com/EddyVerbruggen/nativescript-particle/raw/master/demo/app/images/particle-logo.png\" width=\"250px\" alt=\"Particle.io logo\"/\u003e\u003cbr/\u003e\n\n## Prerequisites\nHop on over to [the Particle.io store](https://store.particle.io) and order any or all of their cool devices.\n\n\u003e While developing this plugin and the [demo app](demo/) I used a [Photon Kit](https://store.particle.io/collections/photon) and it was a joy to work with.\n\u003e\n\u003e Thanks, [Brandon Satrom](https://twitter.com/BrandonSatrom) for sending one over!\n\n## Installation\n```bash\ntns plugin add nativescript-particle\n```\n\n## iOS 12+ setup\niOS 12 and up requires you to enable 'Access WiFi Information' for your App ID [here](https://developer.apple.com/account/ios/identifier/bundle).\n\nAlso, add this to your `App_Resources/iOS/app.entitlements` (mind the name!) file:\n\n```xml\n\u003ckey\u003ecom.apple.developer.networking.wifi-info\u003c/key\u003e\n\u003ctrue/\u003e\n```\n\nThe [demo app](demo) has this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n  \u003ckey\u003ecom.apple.developer.networking.wifi-info\u003c/key\u003e\n  \u003ctrue/\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n## Demo app\nIf you want to just play with your Particle device without writing code yet,\nfollow these steps to install the demo app I've created with NativeScript Core:\n\n```bash\ngit clone https://github.com/EddyVerbruggen/nativescript-particle\ncd nativescript-particle/src\nnpm i\nnpm run demo.ios # or demo.android\n```\n\n\u003e Tip: If you get tired entering your login credentials every time you log in, set the [`PARTICLE_USERNAME` and `PARTICLE_PASSWORD` properties to reflect your own](https://github.com/EddyVerbruggen/nativescript-particle/blob/618dea7d0a5d3c1cd9cb287e70142375547faa60/demo/app/main-view-model.ts#L7-L8).\n\nWant to see the demo in action? Check out [this short video 📺](https://www.youtube.com/watch?v=c49mXdduyMo).\n\n## API\nAll examples below assume you have these imports and instantiated the `Particle` class:\n\n```typescript\nimport { Particle, TNSParticleDevice, TNSParticleEvent } from \"nativescript-particle\";\nconst particle = new Particle();\n```\n\n### `startDeviceSetupWizard`\nTo 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! 😎\n\n```typescript\nparticle.startDeviceSetupWizard()\n    .then(isSuccessful =\u003e console.log(\"Wizard success? \" + isSuccessful));\n```\n\n### `login`\nCommunication between your app and a device is HTTP (REST) based,\nso the first step is authenticating yourself with the Particle Cloud:\n\n```typescript\nparticle.login(\n    {\n      username: \"my-particle-username@mydomain.com\",\n      password: \"my-particle-password\"\n    })\n    .then(() =\u003e console.log(\"Login successful\"))\n    .catch(error =\u003e console.log(`Login error: ${error}`));\n```\n\n### `loginWithToken`\nAlternatively, you can login with an access token.\n\n```typescript\nparticle.loginWithToken(\"the_token\");\n```\n\n### `logout`\nOnce 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.\n\nThere's no reason not to because it couldn't be easier:\n\n```typescript\nparticle.logout();\n```\n\n### `publish`\nPublish an event from your app to the Particle Device Cloud.\n\n```typescript\nparticle.publish(\n    \"ledStatusApp123\", // the event name\n    \"ON\", // the event data (string)\n    true, // isPrivate (default true)\n    30 // ttl (default 60)\n);\n```\n\n### `subscribe`\nSubscribe to the firehose of public events, plus the private events published by devices one owns.\nYou really want to use a unique prefix, otherwise you'll receive a lot of data (not only from your own devices!).\n\n```typescript\nparticle.subscribe(\n    \"ledStatusApp123\",\n    (event: TNSParticleEvent) =\u003e console.log(`Got a ledStatus event for App 123 from the Particle Cloud: ${JSON.stringify(event)}`));\n```\n\n### `unsubscribe`\nTo stop receiving published events, unsubscribe from the events. Make sure the prefix is equal to the one you previously subscribed with.\n\n```typescript\nparticle.unsubscribe(\"ledStatusApp123\");\n```\n\n### `listDevices`\nMake sure you've claimed a device in your Particle account, then do this to list them in your app:\n\n```typescript\nparticle.listDevices()\n    .then((devices: Array\u003cTNSParticleDevice\u003e) =\u003e {\n      if (devices.length === 0) {\n        console.log(\"No devices have been claimed in this account.\");\n      } else {\n        console.log(\"Devices fetched.. now do something neat with 'em.\");\n      }\n    })\n    .catch(error =\u003e console.log(`Error fetching devices: ${error}`));\n```\n\nThe returned list of `TNSParticleDevice` objects has these properties and functions:\n\n| Property | Type | Description |\n| --- | --- | --- |\n| id | `string` | The unique ID of this device. |\n| name | `string` | The given name of this device. |\n| status | `string` | The current status of the device, usually `normal`. |\n| connected | `boolean` | Whether or not the device is currently connected.. |\n| type | [`TNSParticleDeviceType`](https://github.com/EddyVerbruggen/nativescript-particle/blob/618dea7d0a5d3c1cd9cb287e70142375547faa60/src/particle.common.ts#L1-L10) | One of `Unknown`, `Core`, `Photon`, `P1`, `Electron`, `RaspberryPi`, `DigistumpOak`, `RedBearDuo`, `Bluz`. |\n| functions | `Array\u003cstring\u003e` | The list of functions currently available on the device. You can invoke these with `callFunction` (see below). |\n| variables | `Array\u003c`[`TNSParticleDeviceVariable`](https://github.com/EddyVerbruggen/nativescript-particle/blob/618dea7d0a5d3c1cd9cb287e70142375547faa60/src/particle.common.ts#L38-L41)`\u003e` | The list of variables currently available on the device. You can get their values with `getVariable` (see below). |\n\n#### `\u003cdevice\u003e.rename`\nYou can change the device name right from your app! 💪\n\n```typescript\nconst myDevice: TNSParticleDevice = null; // you got this from 'listDevices'\n\nmyDevice.rename(\"rocket_bubble\")\n    .then(() =\u003e console.log(\"Device renamed\"))\n    .catch(error =\u003e console.log(`Error renaming the device: ${error}`));\n```\n\n#### `\u003cdevice\u003e.callFunction`\nYou can invoke any of the `functions` you discovered on the device.\n\nAs an example let's assume you've flashed [this code tutorial](https://docs.particle.io/guide/getting-started/examples/photon/#read-your-photoresistor-function-and-variable) to your device,\nso there's a `led` function which takes 1 argument: the value must be either `\"on\"`, or `\"off\"`:\n\n```typescript\nconst myDevice: TNSParticleDevice = null; // you got this from 'listDevices'\n\nmyDevice.callFunction(\"led\", \"on\")\n    .then(result =\u003e console.log(`Result: ${result}`))\n    .catch(error =\u003e console.log(`Error in callFunction: ${error}`));\n```\n\nWhat if you have a function which takes multiple arguments? Let's assume you're using the [tinker app](https://docs.particle.io/guide/getting-started/examples/photon/#tinker) and want to set `\"D7\"` to `\"HIGH\"` via the `\"digitalWrite\"` function:\n\n```typescript\nmyDevice.callFunction(\"digitalWrite\", \"D7\", \"HIGH\")\n    .then(result =\u003e console.log(`Result: ${result}`))\n    .catch(error =\u003e console.log(`Error in callFunction: ${error}`));\n```\n\n#### `\u003cdevice\u003e.getVariable`\nGetting a variable is quite similar to `callFunction`.\n\nLet's say you have a variable named `\"analogvalue\"`, then this will give you the current state of that variable:\n\n```typescript\nconst myDevice: TNSParticleDevice = null; // you got this from 'listDevices'\n\nmyDevice.getVariable(\"analogvalue\")\n    .then(result =\u003e console.log(`Result: ${result}`))\n    .catch(error =\u003e console.log(`Error in getVariable: ${error}`));\n```\n\n#### `\u003cdevice\u003e.subscribe`\nYou can get notified in your app in case an app on one of your devices publishes an event.\n\nTo 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:\n\n```typescript\nconst myDevice: TNSParticleDevice = null; // you got this from 'listDevices'\n\nmyDevice.subscribe(\n    \"my-prefix-\",\n    (event: TNSParticleEvent) =\u003e console.log(`device event: ${JSON.stringify(event)}`));\n```\n\n#### `\u003cdevice\u003e.unsubscribe`\nTo stop receiving published events from your devices, unsubscribe from the events. Make sure the prefix is equal to the one you previously subscribed with.\n\n```typescript\nmyDevice.unsubscribe(\"my-prefix-\");\n```\n\n#### `\u003cdevice\u003e.unclaim`\nRemoves this device from your account.\n\n```typescript\nmyDevice.unclaim();\n```\n\n## Thanks!\n[markoImake](https://github.com/markoImake) for adding a few [very cool features](https://github.com/EddyVerbruggen/nativescript-particle/pull/2).\n\n\nHappy IoT'ing! 🕹🤖🚪🖲💡📸🎙⛈🚦🛎🔊\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-particle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-particle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-particle/lists"}