Skip to content

Latest commit

 

History

History
1351 lines (890 loc) · 84.8 KB

api.md

File metadata and controls

1351 lines (890 loc) · 84.8 KB
Raw

Table of Contents

Particle

src/Particle.js:17-1274

Particle Cloud API wrapper.

See https://docs.particle.io/reference/javascript/ for examples of using the Particle class.

Most Particle methods take a single unnamed argument object documented as options with key/value pairs for each option.

Parameters

  • options (optional, default {})

constructor

src/Particle.js:25-30

Contructor for the Cloud API wrapper.

Create a new Particle object and call methods below on it.

Parameters

  • options Object Options for this API call Options to be used for all requests (see Defaults) (optional, default {})

login

src/Particle.js:64-73

Login to Particle Cloud using an existing Particle acccount.

Parameters

  • options Object Options for this API call
    • options.username String Username for the Particle account
    • options.password String Password for the Particle account
    • options.tokenDuration Number How long the access token should last in seconds (optional, default this.tokenDuration)
    • options.context

Returns Promise

loginAsClientOwner

src/Particle.js:81-87

Login to Particle Cloud using an OAuth client.

Parameters

  • options Object Options for this API call
    • options.context Object Context information.

Returns Promise

createUser

src/Particle.js:97-103

Create a user account for the Particle Cloud

Parameters

  • options Object Options for this API call
    • options.username String Email of the new user
    • options.password String Password
    • options.accountInfo String Object that contains account information fields such as user real name, company name, business account flag etc
    • options.context

Returns Promise

verifyUser

src/Particle.js:111-115

Verify new user account via verification email

Parameters

  • options Object Options for this API call
    • options.token String the string token sent in the verification email
    • options.context

Returns Promise

resetPassword

src/Particle.js:123-125

Send reset password email for a Particle Cloud user account

Parameters

  • options Object Options for this API call
    • options.username String Email of the user
    • options.context

Returns Promise

deleteAccessToken

src/Particle.js:135-139

Revoke an access token

Parameters

  • options Object Options for this API call
    • options.username String Username of the Particle cloud account that the token belongs to.
    • options.password String Password for the account
    • options.token String Access token you wish to revoke
    • options.context

Returns Promise

deleteCurrentAccessToken

src/Particle.js:147-149

Revoke the current session access token

Parameters

  • options Object Options for this API call
    • options.auth String Access Token
    • options.context

Returns Promise

listAccessTokens

src/Particle.js:158-160

List all valid access tokens for a Particle Cloud account

Parameters

  • options Object Options for this API call
    • options.username String Username
    • options.password String Password
    • options.context

Returns Promise

trackingIdentity

src/Particle.js:171-173

Retrieves the information that is used to identify the current login for tracking.

Parameters

  • options Object Options for this API call (optional, default {})
    • options.auth String The access token
    • options.full Boolean When true, retrieve all information for registering a user with the tracking API. When false, retrieve only the unique tracking ID for the current login. (optional, default false)
    • options.context Object Context information.

Returns Promise<Object> Resolve the tracking identify of the current login

listDevices

src/Particle.js:188-192

List devices claimed to the account or product

Parameters

  • options Object Options for this API call
    • options.deviceId String? (Product only) Filter results to devices with this ID (partial matching)
    • options.deviceName String? (Product only) Filter results to devices with this name (partial matching)
    • options.sortAttr String? (Product only) The attribute by which to sort results. See API docs for options.
    • options.sortDir String? (Product only) The direction of sorting. See API docs for options.
    • options.page Number? (Product only) Current page of results
    • options.perPage Number? (Product only) Records per page
    • options.product String? List devices in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getDevice

src/Particle.js:202-205

Get detailed informationa about a device

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.product String? Device in this product ID or slug
    • options.auth String Access token
    • options.context

Returns Promise

claimDevice

src/Particle.js:214-219

Claim a device to the account. The device must be online and unclaimed.

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID
    • options.auth String Access Token
    • options.requestTransfer
    • options.context

Returns Promise

addDeviceToProduct

src/Particle.js:229-234

Add a device to a product or move device out of quarantine.

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID
    • options.product String Add to this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

removeDevice

src/Particle.js:245-249

Unclaim / Remove a device from your account or product, or deny quarantine

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.deny Boolean? (Product only) Deny this quarantined device, instead of removing an already approved device
    • options.product String Remove from this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

removeDeviceOwner

src/Particle.js:259-262

Unclaim a product device its the owner, but keep it in the product

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.product String Remove from this product ID or slug
    • options.auth String Access Token
    • options.deny
    • options.context

Returns Promise

renameDevice

src/Particle.js:273-275

Rename a device

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.name String Desired Name
    • options.product String? Rename device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

signalDevice

src/Particle.js:286-288

Instruct the device to turn on/off the LED in a rainbow pattern

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.signal Boolean Signal on or off
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

setDeviceNotes

src/Particle.js:299-301

Store some notes about device

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.notes
    • options.context

Returns Promise

markAsDevelopmentDevice

src/Particle.js:312-314

Mark device as being used in development of a product so it opts out of automatic firmware updates

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.development Boolean Set to true to mark as development, false to return to product fleet (optional, default true)
    • options.product String Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

lockDeviceProductFirmware

src/Particle.js:326-328

Mark device as being used in development of a product so it opts out of automatic firmware updates

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.product String Device in this product ID or slug
    • options.auth String Access Token
    • options.desiredFirmwareVersion
    • options.flash
    • options.context

Returns Promise

unlockDeviceProductFirmware

src/Particle.js:338-340

Mark device as receiving automatic firmware updates

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.product String Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

updateDevice

src/Particle.js:357-364

Update multiple device attributes at the same time

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.name String? Desired Name
    • options.signal Boolean Signal device on or off
    • options.development Boolean? (Product only) Set to true to mark as development, false to return to product fleet
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.notes
    • options.desiredFirmwareVersion
    • options.flash
    • options.context

Returns Promise

provisionDevice

src/Particle.js:373-375

Provision a new device for products that allow self-provisioning

Parameters

  • options Object Options for this API call
    • options.productId String Product ID where to create this device
    • options.auth String Access Token
    • options.context

Returns Promise

getClaimCode

src/Particle.js:387-390

Generate a claim code to use in the device claiming process. To generate a claim code for a product, the access token MUST belong to a customer of the product.

Parameters

  • options Object Options for this API call
    • options.iccid String? ICCID of the SIM card used in the Electron
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getVariable

src/Particle.js:411-416

Get the value of a device variable

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.name String Variable name
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

flashDevice

src/Particle.js:427-436

Compile and flash application firmware to a device. Pass a pre-compiled binary to flash it directly to the device.

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.files Object Object containing files to be compiled and flashed. Keys should be the filenames, including relative path, and the values should be a path or Buffer of the file contents in Node, or a File or Blob in the browser.
    • options.targetVersion String System firmware version to compile against (optional, default latest)
    • options.auth String String
    • options.context

Returns Promise

flashTinker

src/Particle.js:445-454

DEPRECATED: Flash the Tinker application to a device. Instead compile and flash the Tinker source code.

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.auth String Access Token
    • options.context

Returns Promise

compileCode

src/Particle.js:465-474

Compile firmware using the Particle Cloud

Parameters

  • options Object Options for this API call
    • options.files Object Object containing files to be compiled. Keys should be the filenames, including relative path, and the values should be a path or Buffer of the file contents in Node, or a File or Blob in the browser.
    • options.platformId Number? Platform id number of the device you are compiling for. Common values are 0=Core, 6=Photon, 10=Electron.
    • options.targetVersion String System firmware version to compile against (optional, default latest)
    • options.auth String Access Token
    • options.context

Returns Promise

downloadFirmwareBinary

src/Particle.js:483-492

Download a firmware binary

Parameters

  • options Object Options for this API call
    • options.binaryId String Binary ID received from a successful compile call
    • options.auth String Access Token
    • options.context

Returns Request

sendPublicKey

src/Particle.js:503-511

Send a new device public key to the Particle Cloud

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.key (String | Buffer) Public key contents
    • options.algorithm String Algorithm used to generate the public key. Valid values are rsa or ecc. (optional, default rsa)
    • options.auth String Access Token
    • options.context

Returns Promise

callFunction

src/Particle.js:523-528

Call a device function

Parameters

  • options Object Options for this API call
    • options.deviceId String Device ID or Name
    • options.name String Function name
    • options.argument String Function argument
    • options.product String? Device in this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getEventStream

src/Particle.js:541-565

Get a stream of events

Parameters

  • options Object Options for this API call
    • options.deviceId String? Device ID or Name, or mine to indicate only your devices.
    • options.name String? Event Name
    • options.org String? Organization Slug
    • options.product String? Events for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise If the promise resolves, the resolution value will be an EventStream object that will emit 'event' events, as well as the specific named event.

publishEvent

src/Particle.js:577-581

Publish a event to the Particle Cloud

Parameters

  • options Object Options for this API call
    • options.name String Event name
    • options.data String Event data
    • options.isPrivate Boolean Should the event be publicly available?
    • options.product String? Event for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

createWebhook

src/Particle.js:604-612

Create a webhook

Parameters

  • options Object Options for this API call
    • options.deviceId String Trigger webhook only for this device ID or Name
    • options.name String Webhook name
    • options.url String URL the webhook should hit
    • options.requestType String HTTP method to use (optional, default POST)
    • options.headers Object? Additional headers to add to the webhook
    • options.json Object? JSON data
    • options.query Object? Query string data
    • options.body String? Custom webhook request body
    • options.responseTemplate Object? Webhook response template
    • options.responseTopic Object? Webhook response topic
    • options.rejectUnauthorized Boolean? Reject invalid HTTPS certificates
    • options.webhookAuth Object? HTTP Basic Auth information
    • options.form Object? Form data
    • options.product String? Webhook for this product ID or slug
    • options.auth String Access Token
    • options.noDefaults
    • options.context

Returns Promise

deleteWebhook

src/Particle.js:622-625

Delete a webhook

Parameters

  • options Object Options for this API call
    • options.hookId String Webhook ID
    • options.product String? Webhook for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

listWebhooks

src/Particle.js:634-637

List all webhooks owned by the account or product

Parameters

  • options Object Options for this API call
    • options.product String? Webhooks for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

createIntegration

src/Particle.js:653-657

Create an integration to send events to an external service

See the API docs for details https://docs.particle.io/reference/api/#integrations-webhooks-

Parameters

  • options Object Options for this API call
    • options.integrationType String The kind of external integration. One of Webhook, AzureIotHub, GoogleCloudPubSub, GoogleMaps
    • options.event String Event that triggers the integration
    • options.deviceId String? Trigger integration only for this device ID or Name
    • options.product String? Integration for this product ID or slug
    • options.auth String Access Token
    • options.settings
    • options.context

Returns Promise

editIntegration

src/Particle.js:673-677

Edit an integration to send events to an external service

See the API docs for details https://docs.particle.io/reference/api/#integrations-webhooks-

Parameters

  • options Object Options for this API call
    • options.integrationId String The integration to edit
    • options.event String? Change the event that triggers the integration
    • options.deviceId String? Trigger integration only for this device ID or Name
    • options.product String? Integration for this product ID or slug
    • options.auth String Access Token
    • options.settings
    • options.context

Returns Promise

deleteIntegration

src/Particle.js:688-691

Delete an integration to send events to an external service

Parameters

  • options Object Options for this API call
    • options.integrationId String The integration to remove
    • options.product String? Integration for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

listIntegrations

src/Particle.js:700-703

List all integrations owned by the account or product

Parameters

  • options Object Options for this API call
    • options.product String? Integrations for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getUserInfo

src/Particle.js:711-713

Get details about the current user

Parameters

  • options Object Options for this API call
    • options.auth String Access Token
    • options.context

Returns Promise

setUserInfo

src/Particle.js:724-732

Set details on the current user

Parameters

  • options Object Options for this API call
    • options.stripeToken String Set user's stripe token for payment
    • options.accountInfo String Set user's extended info fields (name, business account, company name, etc)
    • options.password String Change authenticated user password
    • options.auth String Access Token
    • options.context

Returns Promise

listSIMs

src/Particle.js:746-750

List SIM cards owned by a user or product

Parameters

  • options Object Options for this API call
    • options.iccid String? (Product only) Filter to SIM cards matching this ICCID
    • options.deviceId String? (Product only) Filter to SIM cards matching this device ID
    • options.deviceName String? (Product only) Filter to SIM cards matching this device name
    • options.page Number? (Product only) Current page of results
    • options.perPage Number? (Product only) Records per page
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getSIMDataUsage

src/Particle.js:760-765

Get data usage for one SIM card for the current billing period

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.product String? SIM card for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getFleetDataUsage

src/Particle.js:774-776

Get data usage for all SIM cards in a product the current billing period

Parameters

  • options Object Options for this API call
    • options.product String SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

activateSIM

src/Particle.js:792-802

Activate and add SIM cards to an account or product

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.iccids Array<String> (Product only) ICCID of multiple SIM cards to import
    • options.countryCode String The ISO country code for the SIM cards
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.promoCode
    • options.context

Returns Promise

deactivateSIM

src/Particle.js:812-816

Deactivate a SIM card so it doesn't incur data usage in future months.

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

reactivateSIM

src/Particle.js:827-831

Reactivate a SIM card the was deactivated or unpause a SIM card that was automatically paused

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.mbLimit Number? New monthly data limit. Necessary if unpausing a SIM card
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

updateSIM

src/Particle.js:842-846

Update SIM card data limit

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.mbLimit Array Data limit in megabyte for the SIM card
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

removeSIM

src/Particle.js:856-859

Remove a SIM card from an account so it can be activated by a different account

Parameters

  • options Object Options for this API call
    • options.iccid String ICCID of the SIM card
    • options.product String? SIM cards for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

listBuildTargets

src/Particle.js:868-874

List valid build targets to be used for compiling

Parameters

  • options Object Options for this API call
    • options.onlyFeatured Boolean Only list featured build targets (optional, default false)
    • options.auth String Access Token
    • options.context

Returns Promise

listLibraries

src/Particle.js:898-909

List firmware libraries

Parameters

  • options Object Options for this API call
    • options.page Number Page index (default, first page)
    • options.limit Number Number of items per page
    • options.filter String Search term for the libraries
    • options.sort String Ordering key for the library list
    • options.architectures Array<String> List of architectures to filter
    • options.category String Category to filter
    • options.scope String The library scope to list. Default is 'all'. Other values are- 'all' - list public libraries and my private libraries
      • 'public' - list only public libraries
      • 'private' - list only my private libraries
      • 'mine' - list my libraries (public and private)
      • 'official' - list only official libraries
      • 'verified' - list only verified libraries
      • 'featured' - list only featured libraries
    • options.excludeScopes String list of scopes to exclude
    • options.auth String Access Token
    • options.context

Returns Promise

getLibrary

src/Particle.js:923-925

Get firmware library details

Parameters

  • options Object Options for this API call
    • options.name String Name of the library to fetch
    • options.version String Version of the library to fetch (default: latest)
    • options.auth String Access Token
    • options.context

Returns Promise

getLibraryVersions

src/Particle.js:936-941

Firmware library details for each version

Parameters

  • options Object Options for this API call
    • options.name String Name of the library to fetch
    • options.page Number Page index (default, first page)
    • options.limit Number Number of items per page
    • options.auth String Access Token
    • options.context

Returns Promise

contributeLibrary

src/Particle.js:951-958

Contribute a new library version from a compressed archive

Parameters

  • options Object Options for this API call
    • options.archive String Compressed archive file containing the library sources Either a path or Buffer of the file contents in Node, or a File or Blob in the browser.
    • options.auth String Access Token
    • options.context

Returns Promise

publishLibrary

src/Particle.js:967-970

Publish the latest version of a library to the public

Parameters

  • options Object Options for this API call
    • options.name String Name of the library to publish
    • options.auth String Access Token
    • options.context

Returns Promise

deleteLibrary

src/Particle.js:980-982

Delete one version of a library or an entire private library

Parameters

  • options Object Options for this API call
    • options.name String Name of the library to remove
    • options.force String Key to force deleting a public library
    • options.auth String Access Token
    • options.context

Returns Promise

downloadFile

src/Particle.js:990-1002

Download an external file that may not be on the API

Parameters

  • options Object Options for this API call
    • options.url String URL of the file.

Returns Promise Resolves to a buffer with the file data

listOAuthClients

src/Particle.js:1011-1014

List OAuth client created by the account

Parameters

  • options Object Options for this API call
    • options.product String? List clients for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

createOAuthClient

src/Particle.js:1027-1031

Create an OAuth client

Parameters

  • options Object Options for this API call
    • options.name String Name of the OAuth client
    • options.type String web, installed or web
    • options.redirect_uri String? URL to redirect after OAuth flow. Only for type web.
    • options.scope Object? Limits what the access tokens created by this client can do.
    • options.product String? Create client for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

updateOAuthClient

src/Particle.js:1043-1047

Update an OAuth client

Parameters

  • options Object Options for this API call
    • options.clientId String The OAuth client to update
    • options.name String? New Name of the OAuth client
    • options.scope Object? New scope of the OAuth client
    • options.product String? Update client linked to this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

deleteOAuthClient

src/Particle.js:1057-1060

Delete an OAuth client

Parameters

  • options Object Options for this API call
    • options.clientId String The OAuth client to update
    • options.product String? OAuth client linked to this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

listProducts

src/Particle.js:1068-1070

List products the account has access to

Parameters

  • options Object Options for this API call
    • options.auth String Access Token
    • options.context

Returns Promise

getProduct

src/Particle.js:1079-1081

Get detailed information about a product

Parameters

  • options Object Options for this API call
    • options.product String Product ID or slug
    • options.auth String Access token
    • options.context

Returns Promise

listProductFirmware

src/Particle.js:1090-1092

List product firmware versions

Parameters

  • options Object Options for this API call
    • options.product String Firmware for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

uploadProductFirmware

src/Particle.js:1106-1121

List product firmware versions

Parameters

  • options Object Options for this API call
    • options.file Object Path or Buffer of the new firmware file Either a path or Buffer of the file contents in Node, or a File or Blob in the browser.
    • options.version Number Version number of new firmware
    • options.title String Short identifier for the new firmware
    • options.description String? Longer description for the new firmware
    • options.product String Firmware for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

getProductFirmware

src/Particle.js:1131-1133

Get information about a product firmware version

Parameters

  • options Object Options for this API call
    • options.version Number Version number of firmware
    • options.product String Firmware for this product ID or slug
    • options.auth String Access token
    • options.context

Returns Promise

updateProductFirmware

src/Particle.js:1145-1148

Update information for a product firmware version

Parameters

  • options Object Options for this API call
    • options.version Number Version number of new firmware
    • options.title String? New title
    • options.description String? New description
    • options.product String Firmware for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

downloadProductFirmware

src/Particle.js:1158-1167

Download a product firmware binary

Parameters

  • options Object Options for this API call
    • options.version Number Version number of new firmware
    • options.product String Firmware for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Request

releaseProductFirmware

src/Particle.js:1177-1180

Release a product firmware version as the default version

Parameters

  • options Object Options for this API call
    • options.version Number Version number of new firmware
    • options.product String Firmware for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

listTeamMembers

src/Particle.js:1189-1191

List product team members

Parameters

  • options Object Options for this API call
    • options.product String Team for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

inviteTeamMember

src/Particle.js:1201-1203

Invite Particle user to a product team

Parameters

  • options Object Options for this API call
    • options.username String Username for the Particle account
    • options.product String Team for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

removeTeamMember

src/Particle.js:1213-1215

Remove Particle user to a product team

Parameters

  • options Object Options for this API call
    • options.username String Username for the Particle account
    • options.product String Team for this product ID or slug
    • options.auth String Access Token
    • options.context

Returns Promise

lookupSerialNumber

src/Particle.js:1224-1226

Fetch details about a serial number

Parameters

  • options Object Options for this API call
    • options.serialNumber String The serial number printed on the barcode of the device packaging
    • options.auth String Access Token
    • options.context

Returns Promise