• Stars
    star
    121
  • Rank 281,560 (Top 6 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 8 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

JS Library for the Particle API

particle-api-js

JS Library for the Particle Cloud API for Node.js and the browser

Build Status

Installation | Development | Conventions | Docs | Examples | Building | Releasing | License

Installation

particle-api-js is available from npm to use in Node.js, bower or jsDelivr CDN for use in the browser.

Npm

$ npm install particle-api-js

Bower

$ bower install particle-api-js

jsDelivr CDN

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/particle-api-js@8/dist/particle.min.js">
</script>

Development

All essential commands are available at the root via npm run <script name> - e.g. npm run lint. To view the available commands, run: npm run

How to run your tests

The Agent integration tests (source) depend on a real HTTP api backend and a valid Particle access token. Be sure to set relevant environment variables to avoid test failures. You can prefix commands test commands like this PARTICLE_API_BASE_URL=<url> PARTICLE_API_TOKEN=<token> npm test

npm test runs the tests.

npm run coverage shows code coverage

npm run test:browser runs tests in a browser via karma.

npm run test:ci runs tests in the exact same way CI system does

How to write scripts that execute against local code changes?

Source code lives in the ./src directory and is built for release via the npm run build command. To create a simple script file to test your changes, follow these steps:

  1. create a js file on your local machine: touch my-api-test.js (somewhere outside of the root of this repo)
  2. within your test js file, init the api client like so:
const ParticleAPI = require('./path/to/particle-api-js'); // Make sure to substitute to correct path
const api = new ParticleAPI();
  1. add in any api calls, etc required to validate you changes
const devices = await api.listDevices({ auth: '<particle-auth-token>' });
console.log('MY DEVICES:', devices);
  1. run it: node ./path/to/my-api-test.js

NOTE: Requiring the root directory works via the main field specified in Particle API JS' package.json file (docs)

How to name npm scripts

npm scripts are the primary means of executing programmatic tasks (e.g. tests, linting, releasing, etc) within the repo. to view available scripts, run npm run.

when creating a new script, be sure it does not already exist and use the following naming convention:

<category>:[<subcategory>]:[<action>]

our standard categories include: test, lint, build, clean, docs, package, dependencies, and release. top-level scripts - e.g. npm run clean - will typically run all of its subcategories (e.g. npm run clean:dist && npm run clean:tmp).

npm itself includes special handling for test and start (doc: 1, 2) amongst other lifecycle scripts - use these to expose key testing and start-up commands.

sometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.

Conventions

  • npm scripts form the developer's API for the repo and all of its packages - key orchestration commands should be exposed here
  • document developer-facing process / tooling instructions in the Development section
  • plan to release your changes upon merging to main - refrain from merging if you cannot so you don't leave unpublished changes to others
  • avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates
  • test files live alongside their source files and are named like *.test.js or *.spec.js
  • if the linter does not flag your code (error or warning), it's formatted properly
  • avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts
  • todo comments include your last name and are formatted like: TODO (mirande): <message>

Docs & Resources

First, read the documentation for Particle API JS on the Documentation website. It contains examples to get started.

For more details, read the API reference on GitHub.

Examples

There are many snippets of using Particle API JS on the Documentation website and some complete examples in the GitHub examples directory.

Building

Make your changes to the files in the src directory, then from the project directory run:

$ npm run build

The dist directory will contain the compiled and minified files that can be included in your project.

Run tests to make sure your changes are good:

$ npm test

Update the API docs with your changes:

$ npm run docs

Releasing

See the release process in the RELEASE.md file.

License

Copyright © 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See LICENSE for details.

More Repositories

1

device-os

Device OS (Firmware) for Particle Devices
C++
1,040
star
2

thermostat

A place for all things related to ye olde Spark Thermostat Hackathon
Ruby
717
star
3

spark-server

UNMAINTAINED - An API compatible open source server for interacting with devices speaking the spark-protocol
JavaScript
440
star
4

core

Hardware design files for the Spark Core, a tiny Wi-Fi development kit.
Eagle
367
star
5

sparkjs

DEPRECATED - Use particle-api-js instead
JavaScript
216
star
6

particle-cli

Command Line Interface for Particle Cloud and devices
JavaScript
212
star
7

photon

Hardware design files for the Photon, Particle's Broadcom BCM43362 Wi-Fi development kit.
180
star
8

spark-cli

DEPRECATED: Renamed to particle-cli. See https://github.com/spark/particle-cli
JavaScript
160
star
9

docs

Documentation for Particle
JavaScript
143
star
10

spark-protocol

Node.JS module for hosting direct encrypted CoAP socket connections
JavaScript
91
star
11

android-app

Spark Android App
Java
91
star
12

electron

89
star
13

hardware-libraries

Particle parts for computer-aided design (CAD)
81
star
14

shields

Repo for shield files for the Particle boards
C++
70
star
15

spark-sdk-ios

DEPRECATED Particle iOS Cloud SDK. Use -->
Objective-C
52
star
16

ElectronAssetTracker

Library for the Electron Asset Tracker!
C++
52
star
17

awesome-particle

A curated list of awesome things related to Particle
48
star
18

warsting

WarSting: A wardriving Hobbit sword
Arduino
45
star
19

particle-android

Particle Open Source for Android
C
38
star
20

examples

Spark Core app examples to make it easier to rock out with your Spark Core.
Arduino
36
star
21

InternetButton

Library for the Internet Button shield
C++
35
star
22

softap-setup-js

Particle SoftAP Setup for JavaScript
JavaScript
35
star
23

app-notes

Technical application notes for hardware and software designs and best-practices.
32
star
24

local-communication-example

Particle annotated example
JavaScript
32
star
25

boron

Hardware design files for Particle Boron
31
star
26

xenon

Hardware design files for Particle Xenon
28
star
27

uber-library-example

The first Spark firmware library. To exemplify naming conventions and required files.
C++
27
star
28

socket

Hardware design for the Spark Socket.
25
star
29

example-app-ios

Barebones example Swift iOS app demonstrating how to use the ParticleSetup / SDK cocoapod libraries
Swift
25
star
30

argon

Hardware design files for Particle Argon
25
star
31

xmastree

🎄 Happy Holidays from Particle 🎄
JavaScript
23
star
32

particle-tinker-app-ios

iOS Particle Tinker App
Swift
23
star
33

spark-setup-android

Former home of the Particle Device Setup library for Android
Java
23
star
34

particle-agent

Agent supervising the Particle firmware on the Raspberry Pi
Ruby
21
star
35

particle-cloud-sdk-ios

Official Particle Cloud SDK for iOS
Objective-C
20
star
36

gcc-output-parser

gcc error parsing library
JavaScript
19
star
37

particle-iot.github.io

Spark open source site at http://particle-iot.github.io/
HTML
19
star
38

spark-setup-ios

(DEPRECATED) Spark device setup library - Soft AP Cocoapod/Carthage lib for iOS
Objective-C
19
star
39

lwip

A fork of https://git.savannah.nongnu.org/git/lwip.git
C
19
star
40

google-cloud-datastore-tutorial

A demonstration of how to store Particle device data in Google Cloud Datastore
JavaScript
18
star
41

tracker-edge

Particle Tracker reference application
C
18
star
42

ble-group-library

C++
18
star
43

particle-pi-camera

Repo to host the Particle Pi Camera project
C
14
star
44

beacon-scanner-library

A library for scanning BLE beacons
C++
14
star
45

vorono-iot-lamp

Arduino
13
star
46

cloud-debug

Troubleshooting tool for Particle cellular and Wi-Fi device connectivity
C++
13
star
47

PowerShield

The Power Shield library provides functions to use the on-board MAX17043 fuel gauge via I2C
C++
12
star
48

particle-windows-sdk

Particle Cloud SDK for Windows apps
C#
12
star
49

rc-car-ios

Spark RC car iPhone app
Objective-C
12
star
50

twitter-magnet

C++
11
star
51

tinydtls

C
11
star
52

debugger

Design files for the CMSIS-DAP debugger
11
star
53

node-red-contrib-particle-official

Official Node-RED Particle nodes
HTML
11
star
54

esp32-ncp-firmware

ESP32 firmware for the Argon
C++
10
star
55

nrf5_sdk

C
10
star
56

Particle-PID

PID control library for Particle, adapted from br3ttb/Arduino-PID-Library
C++
10
star
57

ethernet-wing

Hardware design files for the Particle Ethernet Wing
9
star
58

mff2-to-4ffnano

Flex PCB design for MFF2 to 4FF Nano SIM card adapter
8
star
59

electron-powersupply

Place to host the design files for experimental power supply boards for the Electron
Eagle
8
star
60

freertos

https://svn.code.sf.net/p/freertos/code Git mirror
C
8
star
61

ble-gateway-library

A library to aggregate BLE peripheral data
C++
8
star
62

node-mbed-dtls-client

node DTLS client wrapping mbedtls
C++
7
star
63

spark-tinker

Tinker plugin for spark javascript module
JavaScript
7
star
64

firmware-buildpack-builder

A set of scripts building `buildpack-particle-firmware` Docker image out of `firmware` repository
Shell
7
star
65

wordclock

Arduino
7
star
66

rgb-pixel-clock

7
star
67

tracker-hardware

Tracker evaluation board and carrier board public repository for CAD files
7
star
68

particle-photon-setup-ios

Particle device setup library for iOS and Cocoapod & Cathage dependency format
Objective-C
6
star
69

lwip-contrib

A fork of git://git.savannah.nongnu.org/lwip/lwip-contrib.git
C
6
star
70

air-quality-kit

Source for the Particle Air Quality Monitoring Kit
C++
6
star
71

docs-tutorials

Tutorials, sample code, and sample designs used in the documentation (docs.particle.io)
6
star
72

device-os-flash-util

Device OS Flashing Utility
JavaScript
6
star
73

pixel-tweets

Stream tweet events and convert them to pixel data for a Spark Internet Button!
C++
6
star
74

som-eval-board

Hardware repository for the M.2 SoM evaluation board
6
star
75

particle-library-manager

Node library for managing libraries in the cloud and on local disk
JavaScript
5
star
76

particle-usb

A library for accessing Particle USB devices
JavaScript
5
star
77

particle-app-windows

The Particle Tinker app for Windows Phone
C#
5
star
78

google-maps-device-locator-examples

JavaScript
4
star
79

gps-ublox

Support for u-blox NEO-M8U with paired NMEA parser
C++
4
star
80

makerkit

C++
4
star
81

buildpack-hal

Buildpack for modern (HAL) Particle firmware
Shell
4
star
82

particle-windows-devicesetup

Particle Device Setup SDK for Windows apps
C#
4
star
83

buildpack-raspberrypi

Buildpack for Particle firmware running on the Raspberry Pi
Shell
4
star
84

device-os-protobuf

Message format definitions for Device OS
JavaScript
4
star
85

e-series-evaluation-board

Hardware repository for the E series evaluation board
4
star
86

particle-workshops

Workshops designed to teach the basics of IoT development with the Particle ecosystem
C++
4
star
87

model_gauge

MAX17043 FuelGauge Custom Model Configuration
C++
4
star
88

gsm0710muxer

C++
3
star
89

realtek_ambd_sdk_public

Realtek Ameba-D SDK
C
3
star
90

mesh-rc-cars

Gateway and endpoint firmware for mesh-networked RC cars
C++
3
star
91

windows-device-drivers

USB Drivers for Particle devices
C++
3
star
92

RelayShield

Library for the Photon Relay Shield
C++
3
star
93

binary-version-reader

a node.js module to parse versions and information from system modules and firmware for any particle device
JavaScript
3
star
94

particle-swift

Swift 3.0 Package for interacting with Particle Cloud services
Swift
3
star
95

device-os-test-runner

Device OS Test Runner
JavaScript
3
star
96

gps-nmea-parser

Generic GPS NMEA parser for embedded systems (https://github.com/MaJerle/gps-nmea-parser)
C++
3
star
97

firmware-cicd-examples

Example firmware projects with CI/CD using GitHub Actions
C++
2
star
98

softap-emulator-js

implements the device-side of the soft-ap protocol
JavaScript
2
star
99

b-series-rs232

Hardware design repository for B Series to RS232 bridge
2
star
100

cloud

A place to discuss issues, enhancements, features for: API, Cloud Compiler, Web IDE (Build), Webhooks, Console, and Device Setup
2
star