Particle Documentation

Here you'll find the documentation for the Particle platform, including the Particle Device Cloud, Photon, Electron, and Spark Core.

To view this documentation, visit our website, where the documentation is hosted.

Local Hosting

This documentation uses a fabulous tool from the folks at Segment called Metalsmith. Metalsmith is a static site generator that builds static HTML sites from source material in other formats; in this case, Markdown and Handlebars.

To set up a server running at http://localhost:8080, follow the installation instructions below...

NOTE: Any changes made to the source content should be automatically picked up by the browser via livereload.

Bare-metal Hosting

Device Setup

To host this documentation locally, you'll need Node.js and npm (see the engines section of package.json for the exact versions):

If you don't have node.js installed, you can download the installer (LTS recommended) from nodejs.org.

Once you have Node.js set up, navigate to the docs directory on your machine, and use the following commands:

Install Dependencies

To install any other necessary dependencies, run:

npm install

Spell checking

To check the spelling of all Markdown files, run:

npm run spell

This is a good idea when you edit any .md files because it not only checks regular spelling, but it will flag if you don't capitalize and spell things exactly like the rest of the docs. For example: U.FL, Wi-Fi, etc..

Actually, these two files are currently skipped because something in the files confuse the spelling checker and cause it to lose track of word breaks and then things fail horribly:

• src/content/reference/asset-tracking/tracker-edge-firmware.md
• src/content/reference/device-os/firmware.md

Testing

If you are making non-trivial changes, it’s a good idea to check links using the crawler. This takes a number of minutes to run:

npm test

If errors are reported, fix them and run the test again. The second time it will be much faster because it will have cached many of the lookups.

Link checking is not done on commits or pull requests due to the variable amount of time it takes and that it may randomly fail, making it hard to publish at a specific time.

Running locally

npm start

Once the output stops,

Generate PDF datasheets

npm run pdf-generation

Containerized Hosting

If you have Docker installed, then you can simply run the following commands to get started...

$ cd <particle-iot/docs>/
$ scripts/docker-server.sh --help

usage: particle-docs [--build] [--deploy] [--run-tests] [--spell-check]

Build, test and deploy a local documentation server.

  -b, --build           Build and install documentation packages.
  -d, --deploy          Launch documentation server at https://localhost:8080.
  -h, --help            Display this help and exit.
  -s, --spell-check     Run the spell-checker to verify spelling and update dictionary file.
  -t, --run-tests       Run CI tests.

NOTE: If no options are specified, then ALL options will be selected.

NOTE: Containerized hosting is currently only available on Linux devices. Mac is has an open issue involving localhost, and Windows has not been tested at this time.

The containerized version is not regularly used. It will probably work, but is not guaranteed to.

Command line tools

The scripts directory contains a number of maintenance tools. They all share the dependencies in the top-level package.json, so a single npm install in the top of the repository is all that's needed. Run them from the top of the repository using npm run. To pass options to a tool, put them after --:

npm run library-tool -- --generate

Command	Description
npm run api-rename-section	Rename a section of the Device OS API reference (interactive)
npm run carriers-update	Update docs Markdown when carriers.json is updated
npm run export-md	Export a docs page to Markdown (--dest is relative to the top of the repository)
npm run fake-data	Generate fake data (device IDs, serial numbers, ICCIDs) for testing
npm run fix-links	Fix links within the docs
npm run fix-tracker-hex	Fix hex files for the Tracker device
npm run library-tool	Particle library tester and data generating tool (see below)
npm run map-fix	Update the world map SVG
npm run menu-json-upgrade	Upgrade menu JSON files
npm run move-page	Move a docs page and add redirects (interactive)
npm run pin-info-update	Fix up the pinInfo.json file
npm run pinmap-diagram	Generate pinmap diagram SVG files
npm run power-consumption	Parse the power consumption reference manual (put the HTML export in scripts/power-consumption/power.html)
npm run release-update	Update release notes and device restore binaries for new Device OS releases
npm run ticket-forms	Extract ticket forms and fields from the Zendesk guide (requires the ZENDESK_AUTH environment variable)
npm run title-case-fixer	Fix capitalization of Markdown headers
npm run update-app-notes	Update the application notes tiles from the marketing website (requires Node.js 20 or later)

The scripts/ticket-processor tool runs on a different server, so it is not part of the top-level package. It has its own package.json and is run from its own directory using npm install and node app.js.

Access token

The library-tool and release-update tools need a Particle API access token. Copy scripts/config.example.json to scripts/config.json (which is not committed to git) and edit it:

{
    "accessToken": "xxx"
}

Shared code for reading this file is in scripts/lib/script-config.js.

Library tool

npm run library-tool -- --fetch-library-list --download-libraries --test-builds --generate

Options:

• --fetch-library-list Downloads the library list from the API instead of using data/libraryList.json
• --download-libraries Downloads any missing libraries to data/libraries
• --test-builds Tests any libraries that have not been built. Build status is stored in data/libraryData.json
• --generate Generates data files in the docs repository (this also does --generate-index)
• --generate-index Generates an abbreviated index of libraries in src/assets/files/libraryIndex.json

These are in the scripts/LibraryTool directory. Note that data/libraries and data/libraryList.json are not committed to github, as they are huge and can be regenerated if needed. The build status in data/libraryData.json is stored.

Updating Production Documentation

When updated documentation is pushed to the master branch, it is automatically pushed to Amazon S3 by Circle CI.

Organization

The majority of the content herein is stored in the src/content directory as a set of Markdown files. Assets such as images and javascript are stored in the src/assets directory.

Structuring your content

The docs dynamically generate a table of contents for navigation purposes based on the headers (i.e. ###) that you use on each page. It is important to note that order and hierarchy matters when you are designing the organization of content on your page. Your page should include the following:

• 1 h1 at the top of the page that will serve as the title of the page. You can even copy the title directly from the front-matter of the markdown file like this: # {{title}}

• As many h2s (##) as you'd like to serve as the section headers for the page.

• Underneath every h2, if applicable, as many h3s (###) as you'd like to serve as sub-sections within the section. These will appear as nested within the navigation on the left.

Note that there are only 2 levels of navigation that will appear in the table of contents. h4s and below will not appear in the table of contents.

Redirects

When moving pages around or defining the default page for a section, add redirect links to redirects.json.

Attributions

Some of this documentation is derived from the Arduino documentation, as the Arduino/Wiring language and libraries are used extensively on the Spark Core.

This documentation was originally built using Flatdoc, an awesome tool for building beautiful documentation from simple Markdown files. We have made many modifications since, but the inspiration remains.

Contributions

This documentation is managed by Particle, but supported by the community. We welcome contributions such as:

• Edits to improve grammar or fix typos (run npm run spell for automated spell check)
• Edits to improve clarity
• Additional annotated examples for others to follow
• Additional content that would help provide a complete understanding of the Particle platform
• Translations to other languages

Making a contribution is as simple as forking this repository, making edits to your fork, and contributing those edits as a pull request. For more information on how to make a pull request, see GitHub's documentation.

License

These files have been made available online through a Creative Commons Attribution-ShareAlike 3.0 license.

You are welcome to distribute, remix, and use these files for commercial purposes. If you do so, please attribute the original design to Particle both on the website and on the physical packaging of the product or in the instruction manual. All derivative works must be published under the same or a similar license.