-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9d1e0d7
commit 53fb052
Showing
1 changed file
with
22 additions
and
85 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,100 +1,37 @@ | ||
| # hello-world | ||
|
|
||
| This firmware project was created using [Particle Developer Tools](https://www.particle.io/developer-tools/) and is compatible with all [Particle Devices](https://www.particle.io/devices/). | ||
|
|
||
| Feel free to replace this README.md file with your own content, or keep it for reference. | ||
|
|
||
| ## Table of Contents | ||
| - [Introduction](#introduction) | ||
| - [Prerequisites To Use This Template](#prerequisites-to-use-this-repository) | ||
| - [Getting Started](#getting-started) | ||
| - [Particle Firmware At A Glance](#particle-firmware-at-a-glance) | ||
| - [Logging](#logging) | ||
| - [Setup and Loop](#setup-and-loop) | ||
| - [Delays and Timing](#delays-and-timing) | ||
| - [Testing and Debugging](#testing-and-debugging) | ||
| - [GitHub Actions (CI/CD)](#github-actions-cicd) | ||
| - [OTA](#ota) | ||
| - [Support and Feedback](#support-and-feedback) | ||
| - [Version](#version) | ||
| # Particle Blueprint: Getting Started - Hello World | ||
|
|
||
| ## Introduction | ||
| Welcome to the **Hello World Blueprint App** for Particle devices! This project serves as a starting point for new users to get acquainted with Particle's IoT platform. It demonstrates a simple yet powerful "Hello, World!" program that connects your Particle device to the cloud, sending real-time messages visible on the Particle dashboard. | ||
|
|
||
| For an in-depth understanding of this project template, please refer to our [documentation](https://docs.particle.io/firmware/best-practices/firmware-template/). | ||
|
|
||
| ## Prerequisites To Use This Repository | ||
|
|
||
| To use this software/firmware on a device, you'll need: | ||
|
|
||
| - A [Particle Device](https://www.particle.io/devices/). | ||
| - Windows/Mac/Linux for building the software and flashing it to a device. | ||
| - [Particle Development Tools](https://docs.particle.io/getting-started/developer-tools/developer-tools/) installed and set up on your computer. | ||
| - Optionally, a nice cup of tea (and perhaps a biscuit). | ||
|
|
||
| ## Getting Started | ||
|
|
||
| 1. While not essential, we recommend running the [device setup process](https://setup.particle.io/) on your Particle device first. This ensures your device's firmware is up-to-date and you have a solid baseline to start from. | ||
|
|
||
| 2. If you haven't already, open this project in Visual Studio Code (File -> Open Folder). Then [compile and flash](https://docs.particle.io/getting-started/developer-tools/workbench/#cloud-build-and-flash) your device. Ensure your device's USB port is connected to your computer. | ||
|
|
||
| 3. Verify the device's operation by monitoring its logging output: | ||
| - In Visual Studio Code with the Particle Plugin, open the [command palette](https://docs.particle.io/getting-started/developer-tools/workbench/#particle-commands) and choose "Particle: Serial Monitor". | ||
| - Or, using the Particle CLI, execute: | ||
| ``` | ||
| particle serial monitor --follow | ||
| ``` | ||
|
|
||
| 4. Uncomment the code at the bottom of the cpp file in your src directory to publish to the Particle Cloud! Login to console.particle.io to view your devices events in real time. | ||
|
|
||
| 5. Customize this project! For firmware details, see [Particle firmware](https://docs.particle.io/reference/device-os/api/introduction/getting-started/). For information on the project's directory structure, visit [this link](https://docs.particle.io/firmware/best-practices/firmware-template/#project-overview). | ||
|
|
||
| ## Particle Firmware At A Glance | ||
|
|
||
| ### Logging | ||
|
|
||
| The firmware includes a [logging library](https://docs.particle.io/reference/device-os/api/logging/logger-class/). You can display messages at different levels and filter them: | ||
|
|
||
| ``` | ||
| Log.trace("This is trace message"); | ||
| Log.info("This is info message"); | ||
| Log.warn("This is warn message"); | ||
| Log.error("This is error message"); | ||
| ``` | ||
|
|
||
| ### Setup and Loop | ||
|
|
||
| Particle projects originate from the Wiring/Processing framework, which is based on C++. Typically, one-time setup functions are placed in `setup()`, and the main application runs from the `loop()` function. | ||
|
|
||
| For advanced scenarios, explore our [threading support](https://docs.particle.io/firmware/software-design/threading-explainer/). | ||
|
|
||
| ### Delays and Timing | ||
|
|
||
| By default, the setup() and loop() functions are blocking whilst they run, meaning that if you put in a delay, your entire application will wait for that delay to finish before anything else can run. | ||
|
|
||
| For techniques that allow you to run multiple tasks in parallel without creating threads, checkout the code example [here](https://docs.particle.io/firmware/best-practices/firmware-template/). | ||
|
|
||
| (Note: Although using `delay()` isn't recommended for best practices, it's acceptable for testing.) | ||
| **Use this blueprint to begin your IoT journey!** Simply follow the instructions to set up, flash, and monitor your device as it comes alive with your first cloud-connected message. | ||
|
|
||
| ### Testing and Debugging | ||
| ## Hardware Instructions | ||
| For this project, you’ll only need a Particle device. Any [Particle MCU Development Board](https://store.particle.io/collections/all-products?filter.p.product_type=Development%20Boards) is supported, so pick one and get started. | ||
|
|
||
| For firmware testing and debugging guidance, check [this documentation](https://docs.particle.io/troubleshooting/guides/build-tools-troubleshooting/debugging-firmware-builds/). | ||
| ## Tutorial - Getting Started | ||
|
|
||
| ### GitHub Actions (CI/CD) | ||
| 1. **Set up your Particle Device** | ||
| Visit [setup.particle.io](https://setup.particle.io/) to configure your device and connect it to your Particle account. This ensures your device is ready to flash the Hello World firmware. | ||
|
|
||
| This project provides a YAML file for GitHub, automating firmware compilation whenever changes are pushed. More details on [Particle GitHub Actions](https://docs.particle.io/firmware/best-practices/github-actions/) are available. | ||
| 2. **Flash the Firmware** | ||
| Using the Particle Developer Tools, open this project in Visual Studio Code or another editor with Particle support. Then, either use the **Cloud Flash** command in Visual Studio Code or run the following command in the Particle CLI: | ||
|
|
||
| ### OTA | ||
| particle flash <device_name> hello-world | ||
|
|
||
| To learn how to utilize Particle's OTA service for device updates, consult [this documentation](https://docs.particle.io/getting-started/cloud/ota-updates/). | ||
| Once flashed, your device will automatically start sending the "Hello, World!" message to the Particle dashboard. You can view it in real time by visiting your [Particle Console](https://console.particle.io). | ||
|
|
||
| Test OTA with the 'Particle: Cloud Flash' command in Visual Studio Code or the CLI command 'particle flash'! | ||
| 3. **Monitor the Device** | ||
| Open a serial monitor to observe the device's output. In Visual Studio Code, access the **Particle: Serial Monitor** command in the command palette, or use: | ||
|
|
||
| This firmware supports binary assets in OTA packages, allowing the inclusion of audio, images, configurations, and external microcontroller firmware. More details are [here](https://docs.particle.io/reference/device-os/api/asset-ota/asset-ota/). | ||
| particle serial monitor –follow | ||
|
|
||
| ## Support and Feedback | ||
| Your device is now running the Hello World app! | ||
|
|
||
| For support or feedback on this template or any Particle products, please join our [community](https://community.particle.io)! | ||
| ## Contributions | ||
| We welcome contributions to this blueprint! If you'd like to suggest changes, please open a pull request in the [Hello World GitHub Repository](https://github.com/particle-iot/blueprint-hello-world). | ||
|
|
||
| ## Version | ||
| ## Change List | ||
| - **v1.0.0**: Initial release. | ||
|
|
||
| Template version 1.0.2 | ||
| ## Supported Hardware | ||
| This blueprint supports all **Particle MCU Development Boards**. For a full list, please visit [Particle's Development Boards](https://store.particle.io/collections/all-products?filter.p.product_type=Development%20Boards). |