Provided by: platformio_4.3.4-2_all 
NAME
platformio - PlatformIO Documentation
A place where Developers and Teams have true Freedom! No more hardware or software
lock-ins!
• Open source, maximum permissive Apache 2.0 license
• Cross-platform IDE and Unified Debugger
• Static Code Analyzer and Remote Unit Testing
• Multi-platform and Multi-architecture Build System
• Firmware File Explorer and Memory Inspection.
Social: Twitter | LinkedIn | Facebook | Bintray | Community
CONTENTS
What is PlatformIO?
A place where Developers and Teams have true Freedom! No more hardware or software
lock-ins!
Contents
• Awards
• Philosophy
• Technologies
• Problematic
• How does it work?
PlatformIO is a cross-platform, cross-architecture, multiple framework, professional tool
for embedded systems engineers and for software developers who write applications for
embedded products.
Awards
PlatformIO was nominated for the year's best Software and Tools in the 2015/16 IoT Awards.
A native PlatformIO IDE extension for Microsoft ide_vscode editor is the most
rated/reviewed extension with over 800 five-star reviews in the whole Microsoft
Marketplace. It also was installed by over 750,000 unique developers around the world.
Philosophy
PlatformIO's unique philosophy in the embedded market provides developers with a modern
integrated development environment (ide) that works cross-platform, supports many
different software development kits (SDKs) or frameworks, and includes sophisticated
debugging (piodebug), unit testing (unit_testing), automated code analysis (piocheck), and
remote management (pioremote). It is architected to maximize flexibility and choice by
developers, who can use either graphical or command line editors (piocore), or both.
PlatformIO is a must-have tool for professional embedded systems engineers who develop
solutions on more than one specific platform. In addition, by having a decentralized
architecture, PlatformIO offers both new and existing developers a quick integration path
for developing commercial-ready products, and reduces the overall time-to-market.
And it runs on any one of your favorite modern operating systems (macOS, MS Windows,
Linux, FreeBSD).
Technologies
PlatformIO applies the latest scalable and flexible software technology to the embedded
market – an area traditionally served by complex software tools that experienced hardware
engineers have learned over time (often painfully so). Instead, with PlatformIO, users can
be hobbyists or professionals. They can import the classic Arduino "Blink" sketch or
develop a sophisticated low-level embedded C program for a commercial product. Example
code for any supported framework can be compiled and uploaded to a target platform in
minutes.
The build system structure automatically tags software dependencies and applies them using
a modular hierarchy that takes away the usual complexity and pain. Developers no longer
have to manually find and assemble an environment of toolchains, compilers, and library
dependencies to develop applications for a specific target. With PlatformIO, clicking the
compile button will bring in all necessary dependencies automatically. It's analogous to
if you were a furniture designer, and your CAD program had a "build" button that caused a
robot to fetch all the necessary pieces and fasteners and correctly assemble them.
piocore is a unique, developed-from-scratch build system that removes the usual pain of
software integration, packaging, and library dependencies that developers encounter when
they move beyond the bounds of a specific SDK or example embedded application. It can be
used with a variety of code development environments and allows easy integration with
numerous cloud platforms and web services feeds. The user experiences no barriers to
getting started quickly: no license fees, no legal contracts. The user maintains full
flexibility of the build environment because the tools are open source and permissively
licensed (no permission needed to modify them, and no requirement to share changes.)
Problematic
• The main problem which repulses people from the embedded world is a complicated process
to setup development software for a specific MCU/board: toolchains, proprietary vendor's
IDE (which sometimes isn't free) and what is more, to get a computer with OS where that
software is supported.
• Multiple hardware platforms (MCUs, boards) require different toolchains, IDEs, etc, and,
respectively, spending time on learning new development environments.
• Finding proper libraries and code samples showing how to use popular sensors, actuators,
etc.
• Sharing embedded projects between team members, regardless of an operating system they
prefer to work with.
How does it work?
Without going too deep into PlatformIO implementation details, work cycle of the project
developed using PlatformIO is as follows:
• Users choose board(s) interested in projectconf
• Based on this list of boards, PlatformIO downloads required toolchains and installs them
automatically.
• Users develop code and PlatformIO makes sure that it is compiled, prepared and uploaded
to all the boards of interest.
PlatformIO IDE
PlatformIO IDE is the next-generation integrated development environment for IoT.
• Cross-platform build system without external dependencies to the OS software:
• 800+ boards
• 35+ platforms
• 20+ frameworks
• piodebug
• pioremote
• unit_testing
• C/C++ Intelligent Code Completion
• C/C++ Smart Code Linter for rapid professional development
• Library Manager for the hundreds popular libraries
• Multi-projects workflow with multiple panes
• Themes support with dark and light colors
• Serial Port Monitor
• Built-in Terminal with piocore and CLI tool (pio, platformio)
• Built-in piohome.
----
We provide official packages (plugins, extensions) for the most popular IDEs and text
editors.
NOTE:
In our experience, ide_vscode offers better system performance, and users have found it
easier to get started
PlatformIO for VSCode
Visual Studio Code is a lightweight but powerful source code editor which runs on your
desktop and is available for Windows, macOS and Linux. It comes with built-in support for
JavaScript, TypeScript and Node.js and has a rich ecosystem of extensions for other
languages (such as C++, C#, Python, PHP, Go) and runtimes (such as .NET and Unity).
Install PlatformIO for VSCode / Get started .SS PlatformIO for CLion
The CLion is a cross-platform C/C++ IDE for Linux, OS X, and Windows. CLion includes such
features as a smart editor, code generation, code quality assurance, automated
refactorings, on-the-fly code analysis, project manager, integrated version control
systems and debugger.
Install PlatformIO for CLion / Get started .SS PlatformIO Core (CLI)
PlatformIO Core (CLI tool) is a heart of whole PlatformIO ecosystem and consists of
• Multi-platform Build System
• Development platform and package managers
• librarymanager
• ldf
• Serial Port Monitor
• Integration components (ide and ci).
PlatformIO Core is written in Python and works on Windows, macOS, Linux, FreeBSD and
ARM-based credit-card sized computers (Raspberry Pi, BeagleBone, CubieBoard, Samsung
ARTIK, etc.).
PlatformIO Core provides a rich and documented Command Line Interface (CLI). The other
PlatformIO-based software and IDEs are based on PlatformIO Core CLI, such as pioide. In
other words, they wrap PlatformIO Core with own GUI.
NOTE:
Please note that you do not need to install PlatformIO Core if you are going to use
pioide. PlatformIO Core is built into PlatformIO IDE and you will be able to use it
within PlatformIO IDE Terminal.
If you need PlatformIO Core commands outside PlatformIO IDE, please
piocore_install_shell_commands.
Demo
Contents
• "Blink Project"
• Used in demo
• Platform Manager
• Used in demo
• Library Manager
• Used in demo
• Over-the-Air update for ESP8266
• Used in demo
Blink Project
[image]
Used in demo
1. Source code of Wiring Blink Example
2. cmd_run command
3. platformio run -t upload command.
Platform Manager
[image]
Used in demo
1. userguide_platform
2. cmd_platform_list command
3. platformio platform search avr command
4. platformio platform show teensy command
5. cmd_platform_update command.
Library Manager
[image]
Used in demo
1. cmd_lib
2. platformio lib search 1-wire command
3. platformio lib install 54 command
4. platformio lib search -f mbed command
5. platformio lib search -k rf command
6. platformio lib search radiohead command
7. platformio lib install 124 --version "1.40" command
8. platformio lib show 124 command
9. cmd_lib_update command.
Over-the-Air update for ESP8266
.SS Used in demo
1. cmd_run command
2. platformio run -t upload command.
Installation
NOTE:
Please note that you do not need to install piocore if you are going to use pioide.
piocore is built into PlatformIO IDE and you will be able to use it within PlatformIO
IDE Terminal.
If you need piocore outside PlatformIO IDE, please Install Shell Commands.
PlatformIO Core is written in Python and works on Windows, macOS, Linux, FreeBSD and
ARM-based credit-card sized computers (Raspberry Pi, BeagleBone, CubieBoard, Samsung
ARTIK, etc.).
• System requirements
• Installation Methods
• Installer Script
• Super-Quick (Mac / Linux)
• Local Download (Mac / Linux / Windows)
• Python Package Manager
• macOS Homebrew
• Virtual Environment
• Prerequisites
• Creating
• Development Version
• Install Shell Commands
• Unix and Unix-like
• Method 1
• Method 2
• Windows
• Uninstall PIO Core and dependent packages
• Integration with custom applications (extensions, plugins)
• Prerequisite
• Python Interpreter
• Installer Script
• Workflow
• Step 1. Where is PlatformIO Core installed?
• Step 2. Install PlatformIO Core
• Troubleshooting
System requirements
Operating System
Windows, macOS, Linux, FreeBSD, Linux ARMv6+
Python Interpreter
Python 3.5+ (Python 2.7 is not recommended, support for it will be removed in the
next releases). See detailed instruction on how to faq_install_python for Windows.
Terminal Application
All commands below should be executed in Command-line application (Terminal). For
macOS and Linux OS - Terminal application, for Windows OS – cmd.exe application.
Access to Serial Ports (USB/UART)
Windows Users: Please check that you have correctly installed USB driver from board
manufacturer
Linux Users:
• Please install faq_udev_rules
• Raspberry Pi users, please read this article Enable serial port on Raspberry Pi.
Installation Methods
Please choose ONE of the following methods:
• Installer Script
• Super-Quick (Mac / Linux)
• Local Download (Mac / Linux / Windows)
• Python Package Manager
• macOS Homebrew
• Virtual Environment
• Prerequisites
• Creating
Installer Script
WARNING:
PlatformIO DOES NOT require administrative/sudo permissions. Please install using
default user account WITHOUT EXTRA PERMISSIONS.
Super-Quick (Mac / Linux)
To install or upgrade PlatformIO Core paste that at a Terminal prompt:
python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)"
# or using `curl`
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
python3 get-platformio.py
# or using `wget`
wget https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -O get-platformio.py
python3 get-platformio.py
Local Download (Mac / Linux / Windows)
To install or upgrade PlatformIO Core, download (save as...) get-platformio.py script.
Then run the following:
# change directory to folder where is located downloaded "get-platformio.py"
cd /path/to/dir/where/is/located/get-platformio.py/script
# run it
python get-platformio.py
On Windows OS it may look like:
# change directory to folder where is located downloaded "get-platformio.py"
cd C:\path\to\dir\where\is\located\script\get-platformio.py
# run it
python.exe get-platformio.py
NOTE:
If you need to have access to platformio or platformio.exe commands from other
applications or terminal in your OS, please Install Shell Commands.
Python Package Manager
WARNING:
We recommend using this method ONLY FOR ci use cases or where your have full
permissions to install PlatformIO Core into the global scope of your OS.
For personal using, and avoiding maintenance and upgrade issues, we HIGHLY RECOMMEND
using Installer Script which installs PlatformIO Core into an isolated virtual
environment and does not affect your OS.
The latest stable version of PlatformIO Core may be installed or upgraded via Python
Package Manager (pip) as follows:
pip install -U platformio
macOS Homebrew
The latest stable version of PlatformIO may be installed or upgraded via macOS Homebrew
Packages Manager (brew) as follows:
brew install platformio
Virtual Environment
PlatformIO Core may be installed into isolated Python environment. This method is very
good if you don't want to install PlatformIO Core Python's dependencies (packages) into
your global system scope. pioide uses this method to install PlatformIO Core.
Default and recommended environment folder is "projectconf_pio_core_dir/penv". You can
print environment folder path using the next command in your system terminal:
python -c "import os; print(os.path.join(os.getenv('PLATFORMIO_CORE_DIR', os.path.join(os.path.expanduser('~'), '.platformio')), 'penv'))"
######################## Examples
# Windows
# C:\Users\UserName\.platformio\penv
# Linux
# ~/.platformio/penv
# /home/username/.platformio/penv
# macOS
# ~/.platformio/penv
# /Users/username/.platformio/penv
Prerequisites
1. Please remove existing PlatformIO Core environment folder if exists. See above command
how to get path to environment folder.
2. Please check that you have a valid Python interpreter running a next command in system
terminal. Python 2.7.9+ or Python 3.5+ is recommended.
python --version
# or, for Unix (Linux, Mac), you can use `python2` or `python3` aliases
python2 --version
python3 --version
WARNING:
Windows Users: If you already tried to install pioide and did not get success,
please open system's Control Panel > Installed Programs, and check if PlatformIO IDE
tried to install an own isolated Python 2.7 version. Please uninstall it. Also is
good to uninstall all Python interpreters from a system and install manually the
latest Python using faq_install_python guide.
3. Make sure virtualenv --help command exists in a system, otherwise, please install it
manually using pip install virtualenv or pip2 install virtualenv command.
If pip (Python Package Manager) does not exists, you have to install it manually. See
https://pip.pypa.io/en/stable/installing/
Creating
1. Create a folder which contains all the necessary executables to use the packages that
PIO Core would need using virtualenv command:
virtualenv /path/to/.platformio/penv
# If you want to use a custom Python interpreter
virtualenv --python=/path/to/custom/python /path/to/.platformio/penv
# EXAMPLES
# Windows
virtualenv C:\Users\UserName\.platformio\penv
virtualenv --python=C:\Python27\python.exe C:\Users\UserName\.platformio\penv
# Unix (Linux, Mac)
virtualenv ~/.platformio/penv
virtualenv -p python3 ~/.platformio/penv
2. Activate virtual environment
# Windows
C:\Users\UserName\.platformio\penv\Scripts\activate
# Unix (Linux, Mac)
source /path/to/.platformio/penv/bin/activate
# or
. /path/to/.platformio/penv/bin/activate
3. Install PIO Core into virtual environment
pip install -U platformio
If you plan to use PIO Core commands outside virtual environment, please Install Shell
Commands.
Development Version
WARNING:
If you use pioide, please enable development version:
• ide_atom: "Menu PlatformIO: Settings > PlatformIO IDE > Use development version of
PlatformIO Core"
• ide_vscode: Set platformio-ide.useDevelopmentPIOCore to true in ide_vscode_settings.
Install the latest PlatformIO from the develop branch:
# uninstall existing version
pip uninstall platformio
# install the latest development version of PlatformIO
pip install -U https://github.com/platformio/platformio-core/archive/develop.zip
If you want to be up-to-date with the latest develop version of PlatformIO, then you need
to re-install PlatformIO each time you see a new commits in PlatformIO GitHub repository
(branch: develop) like so:
pip install -U https://github.com/platformio/platformio-core/archive/develop.zip
Or:
pio upgrade --dev
To revert to the latest stable version:
pip uninstall platformio
pip install -U platformio
Install Shell Commands
piocore consists of 2 standalone tools in a system:
• platformio or pio (short alias) - piocore_userguide
• piodebuggdb - alias of cmd_debug
If you have pioide already installed, you do not need to install piocore separately. Just
link these tools with your shell:
• Unix and Unix-like
• Method 1
• Method 2
• Windows
Unix and Unix-like
In Unix and Unix-like systems, there are multiple ways to achieve this.
Method 1
You can export PlatformIO executables' directory to the PATH environmental variable. This
method will allow you to execute platformio commands from any terminal emulator as long as
you're logged in as the user PlatformIO is installed and configured for.
If you use Bash as your default shell, you can do it by editing either ~/.profile or
~/.bash_profile and adding the following line:
export PATH=$PATH:~/.platformio/penv/bin
If you use Zsh, you can either edit ~/.zprofile and add the code above, or for supporting
both, Bash and Zsh, you can first edit ~/.profile and add the code above, then edit
~/.zprofile and add the following line:
emulate sh -c '. ~/.profile'
After everything's done, just restart your session (log out and log back in) and you're
good to go.
If you don't know the difference between the two, check out this page.
Method 2
You can create system-wide symlinks. This method is not recommended if you have multiple
users on your computer because the symlinks will be broken for other users and they will
get errors while executing PlatformIO commands. If that's not a problem, open your system
terminal app and paste these commands (MAY require administrator access sudo):
ln -s ~/.platformio/penv/bin/platformio /usr/local/bin/platformio
ln -s ~/.platformio/penv/bin/pio /usr/local/bin/pio
ln -s ~/.platformio/penv/bin/piodebuggdb /usr/local/bin/piodebuggdb
After that, you should be able to run PlatformIO from terminal. No restart is required.
Windows
Please read one of these instructions How do I set or change the PATH system variable?
You need to edit system environment variable called Path and append
C:\Users\UserName\.platformio\penv\Scripts; path in the beginning of a list (please
replace UserName with your account name).
Uninstall PIO Core and dependent packages
• Uninstall PIO Core tool
# uninstall standalone PIO Core installed via `pip`
pip uninstall platformio
# uninstall Homebrew's PIO Core (only macOS users if you installed it via Homebrew before)
brew uninstall platformio
• Dependent packages, global libraries are installed to projectconf_pio_core_dir folder
(in user's HOME directory). Just remove it.
Integration with custom applications (extensions, plugins)
We recommend using PlatformIO Core Installer Script when you integrate PlatformIO Core
into an application, such as extension or plugin for IDE. Examples that use this installer
are:
• platformio-node-helpers, is used by PlatformIO IDE for VSCode and PlatformIO IDE for
Atom
Prerequisite
Python Interpreter
PlatformIO Core Installer Script is written in Python and is compatible with Python 2.7+
and Python 3.5+. We highly recommend using Python 3.
Python is installed by default on the most popular Unix OS (macOS, Linux, FreeBSD). If
there is no Python on a user machine (you can check running python --version), we have 2
options:
1. Ask the user to install Python 3 using our guide faq_install_python
2. You can automatically Download Portable Python 3 and unpack it in a cache folder of
your application. Later, you can use unpacked_protable_python_dir/python.exe for the
installer script.
Installer Script
There are 2 options on how to work with PlatformIO Core Installer Script:
1. Bundle get-platformio.py file into your application
2. Download get-platformio.py file on demand.
In both cases, you will need to have get-platformio.py script on the end-user machine.
You can copy or download it to a cache/temporary folder.
A list of arguments and options for the installer script is available via
python get-platformio.py --help
Workflow
We will describe a simple workflow on how to automatically install piocore for end-user of
your application/extension. We assume that get-platformio.py script is already
copied/downloaded and exists on the end-user machine. See above how to get it.
Step 1. Where is PlatformIO Core installed?
You should check the PlatformIO Core installation state each time when the user starts
your application. You need to call the Installer Script with check core arguments:
python get-platformio.py check core
This command returns 0 "exit code" when PlatformIO Core is already installed and is ready
for use, otherwise, the non-zero code of subprocess will be returned and you need to
install PlatformIO Core (see Step #2 below).
If you need to have full information about PlatformIO Core installation state, please run
with --dump-state option and specify a folder or a full path where to save data in JSON
format:
get-platformio.py check core --dump-state tmpdir/pioinstaller-state.json
Now, read JSON file and use platformio_exe binary to call PlatforIO Core using CLI (see
piocore_userguide). You can also export penv_bin_dir into system environment PATH variable
and platformio command will be available without a full path.
Example of pioinstaller-state.json run on macOS:
{
"cache_dir": "/Users/Freedom/.platformio/.cache",
"core_dir": "/Users/Freedom/.platformio",
"core_version": "4.3.1",
"installer_version": "0.2.0",
"is_develop_core": false,
"penv_bin_dir": "/Users/Freedom/.platformio/penv/bin",
"penv_dir": "/Users/Freedom/.platformio/penv",
"platformio_exe": "/Users/Freedom/.platformio/penv/bin/platformio",
"python_exe": "/Users/Freedom/.platformio/penv/bin/python",
"system": "darwin_x86_64"
}
Step 2. Install PlatformIO Core
To install PlatformIO Core into the virtual environment in an automatic mode, please call
installer script without any arguments:
python get-platformio.py
Available options:
• --verbose, verbose output
• --dev, install the latest development version of PlatformIO Core
• --ignore-python, a path to Python to be ignored (multiple options and unix wildcards are
allowed)
More options are available at python get-platformio.py --help.
Installer Script will return exit code 0 on success, otherwise non-zero code and error
explanation.
Next time just use again python get-platformio.py check core as described in Step #1 (see
above).
Troubleshooting
NOTE:
Linux OS: Don't forget to install "udev" rules file 99-platformio-udev.rules (an
instruction is located in the file).
Windows OS: Please check that you have correctly installed USB driver from board
manufacturer
For further details, frequently questions, known issues, please refer to faq.
If you find any issues with PlatformIO Core Installer Script, please report to
https://github.com/platformio/platformio-core-installer/issues
Quick Start
This tutorial introduces you to the basics of piocore Command Line Interface (CLI)
workflow and shows you a creation process of a simple cross-platform “Blink” Project.
After finishing you will have a general understanding of how to work with the multiple
development platforms and embedded boards.
Setting Up the Project
piocore provides special cmd_project_init command for configuring your projects. It
allows one to initialize new empty project or update existing with the new data.
What is more, cmd_project_init can be used for ide. It means that you will be able to
import pre-generated PlatformIO project using favorite IDE and extend it with the
professional instruments for IoT development.
This tutorial is based on the next popular embedded boards and development platforms using
framework_arduino:
┌───────────────────────┬───────────────────────────────┬───────────────────┐
│Platform │ Board │ Framework │
├───────────────────────┼───────────────────────────────┼───────────────────┤
│platform_atmelavr │ board_atmelavr_uno │ framework_arduino │
├───────────────────────┼───────────────────────────────┼───────────────────┤
│platform_espressif8266 │ board_espressif8266_nodemcuv2 │ framework_arduino │
├───────────────────────┼───────────────────────────────┼───────────────────┤
│platform_teensy │ board_teensy_teensy31 │ framework_arduino │
└───────────────────────┴───────────────────────────────┴───────────────────┘
Board Identifier
cmd_project_init command requires to specify board identifier ID. It can be found using
boards catalog, Boards Explorer or cmd_boards command. For example, using cmd_boards let's
try to find Teensy boards:
> platformio boards teensy
Platform: teensy
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
teensy20 atmega32u4 16MHz 31K 2.5K Teensy 2.0
teensy30 mk20dx128 48MHz 128K 16K Teensy 3.0
teensy31 mk20dx256 72MHz 256K 64K Teensy 3.1 / 3.2
teensylc mkl26z64 48MHz 62K 8K Teensy LC
teensy20pp at90usb1286 16MHz 127K 8K Teensy++ 2.0
According to the table above the ID for board_teensy_teensy31 is teensy31. Also, the ID
for board_atmelavr_uno is uno and for board_espressif8266_nodemcuv2 is nodemcuv2.
Initialize Project
PlatformIO ecosystem contains big database with pre-configured settings for the most
popular embedded boards. It helps you to forget about installing toolchains, writing build
scripts or configuring uploading process. Just tell PlatformIO the Board ID and you will
receive full working project with pre-installed instruments for the professional
development.
1. Create empty folder where you are going to initialize new PlatformIO project. Then open
system Terminal and change directory to it:
# create new directory
> mkdir path_to_the_new_directory
# go to it
> cd path_to_the_new_directory
2. Initialize project for the boards mentioned above (you can specify more than one board
at time):
> platformio project init --board uno --board nodemcuv2 --board teensy31
The current working directory *** will be used for the new project.
You can specify another project directory via
`platformio project init -d %PATH_TO_THE_PROJECT_DIR%` command.
The next files/directories will be created in ***
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
src - Put your source files here
lib - Put here project specific (private) libraries
Do you want to continue? [y/N]: y
Project has been successfully initialized!
Useful commands:
`platformio run` - process/build project from the current directory
`platformio run --target upload` or `platformio run -t upload` - upload firmware to embedded board
`platformio run --target clean` - clean project (remove compiled files)
Congrats! You have just created the first PlatformIO based Project with the next
structure:
• projectconf
• src directory where you should place source code (*.h, *.c, *.cpp, *.S, *.ino, etc.)
• lib directory can be used for the project specific (private) libraries. More details
are located in lib/README file.
• Miscellaneous files for VCS and ci support.
NOTE:
If you need to add new board to the existing project please use cmd_project_init again.
The result of just generated platformio.ini:
; PlatformIO Project Configuration File
;
; Build options: build flags, source filter, extra scripting
; Upload options: custom port, speed and extra flags
; Library options: dependencies, extra library storages
;
; Please visit documentation for the other options and examples
; https://docs.platformio.org/page/projectconf.html
[env:uno]
platform = atmelavr
framework = arduino
board = uno
[env:nodemcuv2]
platform = espressif8266
framework = arduino
board = nodemcuv2
[env:teensy31]
platform = teensy
framework = arduino
board = teensy31
Now, we need to create main.cpp file and place it to src folder of our newly created
project. The contents of src/main.cpp:
/**
* Blink
*
* Turns on an LED on for one second,
* then off for one second, repeatedly.
*/
#include "Arduino.h"
#ifndef LED_BUILTIN
#define LED_BUILTIN 13
#endif
void setup()
{
// initialize LED digital pin as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
void loop()
{
// turn the LED on (HIGH is the voltage level)
digitalWrite(LED_BUILTIN, HIGH);
// wait for a second
delay(1000);
// turn the LED off by making the voltage LOW
digitalWrite(LED_BUILTIN, LOW);
// wait for a second
delay(1000);
}
The final Project structure:
project_dir
├── lib
│ └── README
├── platformio.ini
└── src
└── main.cpp
Process Project
piocore provides special cmd_run command to process project. If you call it without any
arguments, PlatformIO Build System will process all project environments (which were
created per each board specified above). Here are a few useful commands:
• platformio run. Process (build) all environments specified in projectconf
• platformio run --target upload. Build project and upload firmware to the all devices
specified in projectconf
• platformio run --target clean. Clean project (delete compiled objects)
• platformio run -e uno. Process only uno environment
• platformio run -e uno -t upload. Build project only for uno and upload firmware.
Please follow to platformio run --target documentation for the other targets.
Finally, demo which demonstrates building project and uploading firmware to Arduino Uno:
[image]
Further Reading
• Project examples
• piocore_userguide for piocore commands
CLI Guide
Contents
• CLI Guide
• Usage
• Options
• Commands
Usage
pio [OPTIONS] COMMAND
platformio [OPTIONS] COMMAND
# "pio" is the alias of "platformio" command
Options
--no-ansi
Do not print ANSI control characters.
See also PLATFORMIO_NO_ANSI and PLATFORMIO_FORCE_ANSI environment variables.
--version
Show the version of PlatformIO
--help, -h
Show help for the available options and commands
$ platformio --help
$ platformio COMMAND --help
Commands
platformio account
CLI helper command for pioaccount.
To print all available commands and options use:
pio account --help
platformio account --help
platformio account COMMAND --help
platformio account forgot
Contents
• platformio account forgot
• Usage
• Description
• Options
Usage
platformio account forgot [OPTIONS]
pio account forgot [OPTIONS]
Description
Allows you to reset password for pioaccount using username or email which were specified
for registration.
Options
--username, -u
Username or email. You can omit this option and enter username or email in Forgot Wizard
later.
platformio account login
Contents
• platformio account login
• Usage
• Description
• Options
Usage
platformio account login [OPTIONS]
pio account login [OPTIONS]
Description
Log in to pioaccount. If you are not able to provide authentication credentials manually
you can use PLATFORMIO_AUTH_TOKEN. This is very useful for ci systems and pioremote
operations.
Options
--username, -u
Username or email. You can omit this option and enter username or email in Login Wizard
later.
--password, -p
You can omit this option and enter securely password in Login Wizard later.
platformio account logout
Contents
• platformio account logout
• Usage
• Description
Usage
platformio account logout
pio account logout
Description
Log out of pioaccount.
platformio account password
Contents
• platformio account password
• Usage
• Description
Usage
platformio account password
pio account password
Description
Change password for pioaccount.
platformio account register
Contents
• platformio account register
• Usage
• Description
• Options
Usage
platformio account register [OPTIONS]
pio account register [OPTIONS]
Description
Create a new pioaccount.
Options
You can omit these options and enter them later in Register Wizard.
--username, -u
A username. You can use it later for cmd_account_login, cmd_account_update, and
cmd_account_forgot commands.
The username must contain at least 4 characters including single hyphens, and cannot begin
or end with a hyphen.
--email, -e
An email. Please enter existing email, you will receive a confirmation letter.
--password, -p
A password. You will need it for cmd_account_login, cmd_account_password,
cmd_account_token, and cmd_account_update commands.
--firstname
A first name.
--lastname
A last name.
platformio account show
Contents
• platformio account show
• Usage
• Description
• Options
Usage
platformio account show
pio account show
Description
Show detailed information about pioaccount:
• Active subscriptions
• Available packages and services
Options
--json-output
Return the output in JSON format
platformio account token
Contents
• platformio account token
• Usage
• Description
• Options
Usage
platformio account token
pio account token
Description
Get or regenerate Personal Authentication Token. It is very useful for ci systems,
pioremote operations where you are not able to authorize manually.
PlatformIO handles Personal Authentication Token from environment variable
PLATFORMIO_AUTH_TOKEN.
Options
--regenerate
If this option is specified a new authentication token will be generated.
--json-output
Return the output in JSON format
platformio account update
Contents
• platformio account update
• Usage
• Description
• Options
Usage
platformio account update [OPTIONS]
pio account update [OPTIONS]
Description
Update pioaccount profile.
Options
You can omit these options and enter them later in update Wizard.
--username, -u
A username that must contain at least 4 characters including single hyphens, and cannot
begin or end with a hyphen.
--email, -e
An email. Please enter existing email, you will receive a confirmation letter.
--firstname
A first name.
--lastname
A last name.
--current-password
A current password to confirm this operation.
platformio boards
Contents
• platformio boards
• Usage
• Description
• Options
• Examples
Usage
platformio boards [OPTIONS] [FILTER]
pio boards [OPTIONS] [FILTER]
Description
List pre-configured Embedded Boards
Options
--installed
List boards only from the installed platforms
--json-output
Return the output in JSON format
Examples
1. Show all available pre-configured embedded boards
$ platformio boards
Platform: atmelavr
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
btatmega168 atmega168 16MHz 14K 1K Arduino BT ATmega168
btatmega328 atmega328p 16MHz 28K 2K Arduino BT ATmega328
diecimilaatmega168 atmega168 16MHz 14K 1K Arduino Duemilanove or Diecimila ATmega168
diecimilaatmega328 atmega328p 16MHz 30K 2K Arduino Duemilanove or Diecimila ATmega328
esplora atmega32u4 16MHz 28K 2K Arduino Esplora
ethernet atmega328p 16MHz 31K 2K Arduino Ethernet
...
2. Filter Arduino-based boards
$ platformio boards arduino
Platform: atmelavr
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
btatmega168 atmega168 16MHz 14K 1K Arduino BT ATmega168
btatmega328 atmega328p 16MHz 28K 2K Arduino BT ATmega328
diecimilaatmega168 atmega168 16MHz 14K 1K Arduino Duemilanove or Diecimila ATmega168
diecimilaatmega328 atmega328p 16MHz 30K 2K Arduino Duemilanove or Diecimila ATmega328
esplora atmega32u4 16MHz 28K 2K Arduino Esplora
ethernet atmega328p 16MHz 31K 2K Arduino Ethernet
...
3. Filter mbed-enabled boards
$ platformio boards mbed
Platform: freescalekinetis
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
frdm_k20d50m mk20dx128vlh5 48MHz 128K 16K Freescale Kinetis FRDM-K20D50M
frdm_k22f mk22fn512vlh12 120MHz 512K 128K Freescale Kinetis FRDM-K22F
...
Platform: nordicnrf51
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
wallBotBLE nrf51822 16MHz 128K 16K JKSoft Wallbot BLE
nrf51_dk nrf51822 32MHz 256K 32K Nordic nRF51-DK
...
Platform: nxplpc
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
blueboard_lpc11u24 lpc11u24 48MHz 32K 8K BlueBoard-LPC11U24
dipcortexm0 lpc11u24 50MHz 32K 8K DipCortex M0
lpc11u35 lpc11u35 48MHz 64K 10K EA LPC11U35 QuickStart Board
...
Platform: ststm32
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
disco_f401vc stm32f401vct6 84MHz 256K 64K 32F401CDISCOVERY
nucleo_f030r8 stm32f030r8t6 48MHz 64K 8K ST Nucleo F030R8
...
4. Filter boards which are based on ATmega168 MCU
$ platformio boards atmega168
Platform: atmelavr
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
btatmega168 atmega168 16MHz 14K 1K Arduino BT ATmega168
diecimilaatmega168 atmega168 16MHz 14K 1K Arduino Duemilanove or Diecimila ATmega168
miniatmega168 atmega168 16MHz 14K 1K Arduino Mini ATmega168
atmegangatmega168 atmega168 16MHz 14K 1K Arduino NG or older ATmega168
nanoatmega168 atmega168 16MHz 14K 1K Arduino Nano ATmega168
pro8MHzatmega168 atmega168 8MHz 14K 1K Arduino Pro or Pro Mini ATmega168 (3.3V, 8 MHz)
pro16MHzatmega168 atmega168 16MHz 14K 1K Arduino Pro or Pro Mini ATmega168 (5V, 16 MHz)
lilypadatmega168 atmega168 8MHz 14K 1K LilyPad Arduino ATmega168
168pa16m atmega168p 16MHz 15K 1K Microduino Core (Atmega168PA@16M,5V)
168pa8m atmega168p 8MHz 15K 1K Microduino Core (Atmega168PA@8M,3.3V)
5. Show boards by platform_timsp430
$ platformio boards timsp430
Platform: timsp430
---------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
---------------------------------------------------------------------------
lpmsp430fr5739 msp430fr5739 16MHz 15K 1K FraunchPad w/ msp430fr5739
lpmsp430f5529 msp430f5529 16MHz 128K 1K LaunchPad w/ msp430f5529 (16MHz)
lpmsp430f5529_25 msp430f5529 25MHz 128K 1K LaunchPad w/ msp430f5529 (25MHz)
lpmsp430fr5969 msp430fr5969 8MHz 64K 1K LaunchPad w/ msp430fr5969
lpmsp430g2231 msp430g2231 1MHz 2K 128B LaunchPad w/ msp430g2231 (1MHz)
lpmsp430g2452 msp430g2452 16MHz 8K 256B LaunchPad w/ msp430g2452 (16MHz)
lpmsp430g2553 msp430g2553 16MHz 16K 512B LaunchPad w/ msp430g2553 (16MHz)
platformio check
Helper command for piocheck.
Contents
• platformio check
• Usage
• Description
• Options
• Examples
Usage
platformio check [OPTIONS]
pio check [OPTIONS]
Description
Perform static analysis check on PlatformIO based project. By default check_tool_cppcheck
analysis tool is used.
More details about PlatformIO piocheck.
Options
-e, --environment
Process specified environments.
--pattern
You can specify which source files or folders should be included/excluded from check
process. By default only projectconf_pio_src_dir and projectconf_pio_include_dir are
checked. Multiple --pattern options and GLOB Patterns are allowed.
Example: platformio check --pattern="tests" --pattern="src/*.cpp"
--flags
Specify additional flags that need to be passed to the analysis tool. If multiple tools
set in projectconf_check_tool option, the flags are passed to all of them. Individual
flags for each tool can be added using a special suffix with the tool name.
┌────────────────┬─────────────────────────────┐
│Flag │ Meaning │
├────────────────┼─────────────────────────────┤
│--addon=<addon> │ Execute addon. i.e. cert. │
├────────────────┼─────────────────────────────┤
│-D<ID> │ Define preprocessor symbol. │
└────────────────┴─────────────────────────────┘
Multiple --flags options are allowed.
Example: platformio check --flags "-DDEBUG cppcheck: --std=c++11 --platform=avr8"
--severity
Specify the check_severity types which will be reported by the check_tools. Possible
values described in check_severity section. Multiple --severity options are allowed.
Example: platformio check --severity=high
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to the current
working directory (CWD).
-c, --project-conf
Process project with a custom projectconf.
--json-output
Return the output in JSON format.
--fail-on-defect
Fail (exit with non-zero code) if there is a defect found with specified severity. By
default exit code is the same as the exit code returned by a tool selected for performing
check. Possible values described in check_severity section. Multiple --fail-on-defect
options are allowed.
Example: platformio check --fail-on-defect=low --fail-on-defect=medium
-s, --silent
Suppress progress reporting and show only defects with high severity. See check_severity.
-v, --verbose
Show detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
Examples
For the examples please follow to piocheck page.
platformio ci
Contents
• platformio ci
• Usage
• Description
• Options
• Examples
Usage
platformio ci [OPTIONS] [SRC]
pio ci [OPTIONS] [SRC]
Description
platformio ci command is conceived of as "hot key" for building project with arbitrary
source code structure. In a nutshell, using SRC and platformio ci --lib contents
PlatformIO initializes via cmd_project_init new project in platformio ci --build-dir with
the build environments (using platformio ci --board or platformio ci --project-conf) and
processes them via cmd_run command.
platformio ci command accepts multiple SRC arguments, platformio ci --lib and platformio
ci --exclude options which can be a path to directory, file or Glob Pattern. Also, you
can omit SRC argument and set path (multiple paths are allowed denoting with :) to
PLATFORMIO_CI_SRC Environment variable
For more details as for integration with the popular Continuous Integration Systems please
follow to ci page.
NOTE:
platformio ci command is useful for library developers. It allows one to build
different examples without creating own project per them. Also, is possible to upload
firmware to the target device. In this case, you need to pass additional option
--project-option="targets=upload". What is more, you can specify custom upload port
using --project-option="upload_port=<port>" option. See platformio ci --project-option
for details.
Options
-l, --lib
Source code which will be copied to <BUILD_DIR>/lib directly.
If platformio ci --lib is a path to file (not to directory), then PlatformIO will create
temporary directory within <BUILD_DIR>/lib and copy the rest files into it.
--exclude
Exclude directories and/-or files from platformio ci --build-dir. The path must be
relative to PlatformIO project within platformio ci --build-dir.
For example, exclude from project src directory:
• examples folder
• *.h files from foo folder
platformio ci --exclude=src/examples --exclude=src/foo/*.h [SRC]
-b, --board
Build project with automatically pre-generated environments based on board settings.
For more details please look into platformio project init --board.
--build-dir
Path to directory where PlatformIO will initialise new project. By default it's temporary
directory within your operating system.
NOTE:
This directory will be removed at the end of build process. If you want to keep it,
please use platformio ci --keep-build-dir.
--keep-build-dir
Don't remove platformio ci --build-dir after build process.
-c, --project-conf
Build project using pre-configured projectconf.
-O, --project-option
Pass additional options from projectconf to cmd_project_init command. For example,
automatically install dependent libraries platformio ci
--project-option="lib_deps=ArduinoJSON" or ignore specific library platformio ci
--project-option="lib_ignore=SomeLib".
NOTE:
Use multiple --project-option to pass multiple options to projectconf. One option per
one argument. For example, platformio ci --project-option="build_unflags =
-std=gnu++11" --project-option="build_flags = -std=c++14"
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
Examples
For the others examples please follow to ci page.
platformio debug
Helper command for piodebug.
Contents
• platformio debug
• Usage
• Description
• Options
• Examples
Usage
platformio debug [OPTIONS]
pio debug [OPTIONS]
# A binary shortcut for "platformio debug --interface=gdb" command
piodebuggdb [GDB OPTIONS]
Description
Prepare PlatformIO project for debugging or launch debug server.
Options
-e, --environment
Debug specified environments.
You can also specify which environments should be used for debugging by default using
projectconf_pio_default_envs option from projectconf.
-d, --project-dir
Specify the path to a project directory. By default, --project-dir is equal to a current
working directory (CWD).
-c, --project-conf
New in version 4.0.
Process project with a custom projectconf.
--interface
PIO Debugging Interface. Valid values:
• gdb - GDB: The GNU Project Debugger
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
Examples
1. Prepare a project for debugging
> platformio debug
[Sun Apr 30 01:34:01 2017] Processing mzeropro (platform: atmelsam; debug_extra_cmds: b main.cpp:26; board: mzeropro; framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 26 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/mzeropro/src/main.o
Compiling .pio/build/mzeropro/FrameworkArduinoVariant/variant.o
Compiling .pio/build/mzeropro/FrameworkArduino/IPAddress.o
Compiling .pio/build/mzeropro/FrameworkArduino/Print.o
Archiving .pio/build/mzeropro/libFrameworkArduinoVariant.a
Indexing .pio/build/mzeropro/libFrameworkArduinoVariant.a
...
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_analog.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_digital.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_private.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_shift.o
Archiving .pio/build/mzeropro/libFrameworkArduino.a
Indexing .pio/build/mzeropro/libFrameworkArduino.a
Linking .pio/build/mzeropro/firmware.elf
Calculating size .pio/build/mzeropro/firmware.elf
Building .pio/build/mzeropro/firmware.bin
text data bss dec hex filename
11512 256 1788 13556 34f4 .pio/build/mzeropro/firmware.elf
=========================== [SUCCESS] Took 7.82 seconds ===========================
2. Launch GDB instance and load initial configuration per a project
> platformio debug --interface=gdb -x .pioinit
...
Loading section .text, size 0x2c98 lma 0x4000
Loading section .ramfunc, size 0x60 lma 0x6c98
Loading section .data, size 0x100 lma 0x6cf8
Start address 0x47b0, load size 11768
Transfer rate: 4 KB/sec, 3922 bytes/write.
target halted due to debug-request, current mode: Thread
xPSR: 0x81000000 pc: 0x000028f4 msp: 0x20002c00
target halted due to debug-request, current mode: Thread
xPSR: 0x81000000 pc: 0x000028f4 msp: 0x20002c00
Breakpoint 2 at 0x413a: file src/main.cpp, line 26.
Device Manager CLI
To print all available commands and options use:
pio device --help
platformio device --help
platformio device COMMAND --help
platformio device list
Contents
• platformio device list
• Usage
• Description
• Options
• Examples
Usage
platformio device list [OPTIONS]
pio device list [OPTIONS]
Description
List available devices. Default is set to --serial and all available Serial Ports will be
shown.
Options
--serial
List available Serial Ports, default.
--logical
List available logical devices.
--mdns
List multicast DNS services.
--json-output
Return the output in JSON format.
Examples
1. Unix OS
$ platformio device list
/dev/cu.SLAB_USBtoUART
----------
Hardware ID: USB VID:PID=10c4:ea60 SNR=0001
Description: CP2102 USB to UART Bridge Controller
/dev/cu.uart-1CFF4676258F4543
----------
Hardware ID: USB VID:PID=451:f432 SNR=1CFF4676258F4543
Description: Texas Instruments MSP-FET430UIF
2. Windows OS
$ platformio device list
COM4
----------
Hardware ID: USB VID:PID=0451:F432
Description: MSP430 Application UART (COM4)
COM3
----------
Hardware ID: USB VID:PID=10C4:EA60 SNR=0001
Description: Silicon Labs CP210x USB to UART Bridge (COM3)
3. List multicast DNS services and logical devices
$ platformio device list --mdns --logical
Multicast DNS Services
======================
PlatformIO._bttremote._tcp.local.
------------------------------
Type: _bttremote._tcp.local.
IP: ...
Port: 62941
Properties: ...
Time for PlatformIO._adisk._tcp.local.
---------------------------------
Type: _adisk._tcp.local.
IP: 192.168.0.1
Port: 9
Properties: ...
PlatformIO._ssh._tcp.local.
------------------------
Type: _ssh._tcp.local.
IP: ...
Port: 22
PlatformIO._sftp-ssh._tcp.local.
-----------------------------
Type: _sftp-ssh._tcp.local.
IP: ...
Port: 22
Logical Devices
===============
/
-
Name:
/Volumes/PIO
-------------
Name: PIO
/Volumes/PLUS
--------------
Name: PLUS
platformio device monitor
Contents
• platformio device monitor
• Usage
• Description
• Options
• Filters
• Capture output to a file
• Device Monitor Filter API
• Examples
Usage
platformio device monitor [OPTIONS]
Description
This is a console application that provides a small terminal application. It is based on
Miniterm and itself does not implement any terminal features such as VT102 compatibility.
However it inherits these features from the terminal it is run. For example on GNU/Linux
running from an xterm it will support the escape sequences of the xterm. On Windows the
typical console window is dumb and does not support any escapes. When ANSI.sys is loaded
it supports some escapes.
Miniterm supports RFC 2217 remote serial ports and raw sockets using URL Handlers such as
rfc2217://<host>:<port> respectively socket://<host>:<port> as port argument when
invoking.
To control monitor please use these "hot keys":
• Ctrl+C Quit
• Ctrl+T Menu
• Ctrl+T followed by Ctrl+H Help
Options
-p, --port
Port, a number or a device name, or valid URL Handlers.
Can be customized in projectconf using projectconf_monitor_port option.
URL Handlers
• rfc2217://<host>:<port>[?<option>[&<option>...]]
• socket://<host>:<port>[?logging={debug|info|warning|error}]
• loop://[?logging={debug|info|warning|error}]
• hwgrep://<regexp>[&skip_busy][&n=N]
• spy://port[?option[=value][&option[=value]]]
• alt://port?class=<classname>
-b, --baud
Set baud rate, default 9600.
Can be customized in projectconf using projectconf_monitor_speed option.
--parity
Set parity (None, Even, Odd, Space, Mark), one of [N, E, O, S, M], default N
--rtscts
Enable RTS/CTS flow control, default Off
--xonxoff
Enable software flow control, default Off
--rts
Set initial RTS line state (0 or 1).
Can be customized in projectconf using projectconf_monitor_rts option.
--dtr
Set initial DTR line state (0 or 1).
Can be customized in projectconf using projectconf_monitor_dtr option.
--echo
Enable local echo, default Off
--encoding
Set the encoding for the serial port (e.g. hexlify, Latin1, UTF-8), default UTF-8.
-f, --filter
Add text transformation. See available filters at Filters.
--eol
End of line mode (CR, LF or CRLF), default CRLF
NEW: Available in Miniterm/PySerial 3.0
--raw
Do not apply any encodings/transformations
--exit-char
ASCII code of special character that is used to exit the application, default 3 (DEC,
Ctrl+C).
For example, to use Ctrl+] run platformio device monitor --exit-char 29.
--menu-char
ASCII code of special character that is used to control miniterm (menu), default 20 (DEC)
---quiet
Diagnostics: suppress non-error messages, default Off
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-e, --environment
Process specified environments.
You can also specify which environments should be processed by default using
projectconf_pio_default_envs option from projectconf.
Filters
New in version 4.3.
A list of filters that can be applied for monitor output using platformio device monitor
--filter or projectconf and projectconf_monitor_filters options. option.
┌──────────────────────────┬────────────────────────────────────────┐
│Name │ Description │
├──────────────────────────┼────────────────────────────────────────┤
│default │ Remove typical terminal control │
│ │ codes from input │
├──────────────────────────┼────────────────────────────────────────┤
│colorize │ Apply different colors for │
│ │ received and echo │
├──────────────────────────┼────────────────────────────────────────┤
│debug │ Print what is sent and received │
├──────────────────────────┼────────────────────────────────────────┤
│direct │ Do-nothing: forward all data │
│ │ unchanged │
├──────────────────────────┼────────────────────────────────────────┤
│hexlify │ Show a hexadecimal │
│ │ representation of the data (code │
│ │ point of each character) │
├──────────────────────────┼────────────────────────────────────────┤
│log2file │ Log data to a file │
│ │ "platformio-device-monitor-%date%.log" │
│ │ located in the current working │
│ │ directory │
├──────────────────────────┼────────────────────────────────────────┤
│nocontrol │ Remove all control codes, incl. CR+LF │
├──────────────────────────┼────────────────────────────────────────┤
│printable │ Show decimal code for all non-ASCII │
│ │ characters and replace most control │
│ │ codes │
├──────────────────────────┼────────────────────────────────────────┤
│time │ Add timestamp with milliseconds for │
│ │ each new line │
├──────────────────────────┼────────────────────────────────────────┤
│send_on_enter │ Send a text to device on ENTER │
├──────────────────────────┼────────────────────────────────────────┤
│esp32_exception_decoder │ Custom filter for platform_espressif32 │
│ │ which decodes crash exception │
├──────────────────────────┼────────────────────────────────────────┤
│esp8266_exception_decoder │ Custom filter for │
│ │ platform_espressif8266 which decodes │
│ │ crash exception │
└──────────────────────────┴────────────────────────────────────────┘
Capture output to a file
New in version 4.3.
You need to use a log2file filter from Filters:
$ platformio device monitor -f log2file -f default
or using projectconf and projectconf_monitor_filters
[env:log_output_to_file]
...
platform = ...
monitor_filters = log2file, default
Device Monitor Filter API
piocore provides an API to extend device monitor with a custom filter declared in
"monitor" folder of platforms. See examples:
• https://github.com/platformio/platform-espressif32/tree/develop/monitor
• https://github.com/platformio/platform-espressif8266/tree/develop/monitor
Examples
1. Show available options for monitor
$ platformio device monitor --help
Usage: platformio device monitor [OPTIONS]
Options:
-p, --port TEXT Port, a number or a device name
-b, --baud INTEGER Set baud rate, default=9600
--parity [N|E|O|S|M] Set parity, default=N
--rtscts Enable RTS/CTS flow control, default=Off
--xonxoff Enable software flow control, default=Off
--rts [0|1] Set initial RTS line state, default=0
--dtr [0|1] Set initial DTR line state, default=0
--echo Enable local echo, default=Off
--encoding TEXT Set the encoding for the serial port (e.g. hexlify,
Latin1, UTF-8), default: UTF-8
-f, --filter TEXT Add filters / text transformation
--eol [CR|LF|CRLF] End of line mode, default=CRLF
--raw Do not apply any encodings/transformations
--exit-char INTEGER ASCII code of special character that is used to exit
the application, default=29 (DEC)
--menu-char INTEGER ASCII code of special character that is used to
control miniterm (menu), default=20 (DEC)
--quiet Diagnostics: suppress non-error messages, default=Off
-h, --help Show this message and exit.
2. Communicate with serial device and print help inside terminal
$ platformio device monitor
--- Available ports:
--- /dev/cu.Bluetooth-Incoming-Port n/a
--- /dev/cu.Bluetooth-Modem n/a
--- /dev/cu.SLAB_USBtoUART CP2102 USB to UART Bridge Controller
--- /dev/cu.obd2ecu-SPPDev n/a
Enter port name:/dev/cu.SLAB_USBtoUART
--- Miniterm on /dev/cu.SLAB_USBtoUART: 9600,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
Hello PlatformIO!
---
--- Ctrl+] Exit program
--- Ctrl+T Menu escape key, followed by:
--- Menu keys:
--- Ctrl+T Send the menu character itself to remote
--- Ctrl+] Send the exit character itself to remote
--- Ctrl+I Show info
--- Ctrl+U Upload file (prompt will be shown)
--- Toggles:
--- Ctrl+R RTS Ctrl+E local echo
--- Ctrl+D DTR Ctrl+B BREAK
--- Ctrl+L line feed Ctrl+A Cycle repr mode
---
--- Port settings (Ctrl+T followed by the following):
--- p change port
--- 7 8 set data bits
--- n e o s m change parity (None, Even, Odd, Space, Mark)
--- 1 2 3 set stop bits (1, 2, 1.5)
--- b change baud rate
--- x X disable/enable software flow control
--- r R disable/enable hardware flow control
--- exit ---
platformio home
Helper command for piohome.
Contents
• platformio home
• Usage
• Description
• Options
• Examples
Usage
platformio home
pio home
Description
Launch piohome Web-server.
Options
--port
Web-server HTTP port, default is 8008.
--host
Web-server HTTP host, default is 127.0.0.1. You can open PIO Home for inbound connections
using host 0.0.0.0.
--no-open
Do not automatically open PIO Home in a system Web-browser.
--shutdown-timeout
Automatically shutdown server on timeout (in seconds) when no clients are connected.
Default is 0 which means never auto shutdown.
Examples
> platformio home
___I_
/\-_--\ PlatformIO Home
/ \_-__\
|[]| [] | http://127.0.0.1:8008
|__|____|_______________________
Open PIO Home in your browser by this URL => http://127.0.0.1:8008
PIO Home has been started. Press Ctrl+C to shutdown.
Library Manager CLI
Usage
platformio lib [OPTIONS] COMMAND
# To print all available commands and options use
platformio lib --help
platformio lib COMMAND --help
Options
-d, --storage-dir
Manage custom library storage. It can be used later for the projectconf_lib_extra_dirs
option from projectconf. Multiple options are allowed.
-g, --global
Manage global PlatformIO's library storage ( "projectconf_pio_core_dir/lib") where ldf
will look for dependencies by default.
-e, --environment
Manage libraries for the specific project build environments declared in projectconf.
Works for --storage-dir which is valid PlatformIO project.
Demo
[image]
Commands
platformio lib builtin
Contents
• platformio lib builtin
• Usage
• Description
• Options
• Examples
Usage
platformio lib builtin [OPTIONS]
pio lib builtin [OPTIONS]
Description
List built-in libraries based on installed platforms and their frameworks, SDKs, etc.
Options
--storage
List libraries from specified storages. For example, framework-arduinoavr.
--json-output
Return the output in JSON format
Examples
> platformio lib builtin
framework-arduinoavr
********************
Bridge
======
Enables the communication between the Linux processor and the microcontroller. For Arduino/Genuino Yún, Yún Shield and TRE only.
Version: 1.6.1
Homepage: http://www.arduino.cc/en/Reference/YunBridgeLibrary
Keywords: communication
Compatible frameworks: arduino
Compatible platforms: *
Authors: Arduino
EEPROM
======
Enables reading and writing to the permanent board storage.
Version: 2.0
Homepage: http://www.arduino.cc/en/Reference/EEPROM
Keywords: data, storage
Compatible frameworks: arduino
Compatible platforms: atmelavr
Authors: Arduino, Christopher Andrews
...
framework-arduinosam
********************
Audio
=====
Allows playing audio files from an SD card. For Arduino DUE only.
Version: 1.0
Homepage: http://arduino.cc/en/Reference/Audio
Keywords: signal, input, output
Compatible frameworks: arduino
Compatible platforms: atmelsam
Authors: Arduino
...
framework-arduinoespressif32
****************************
SPI
===
Enables the communication with devices that use the Serial Peripheral Interface (SPI) Bus. For all Arduino boards, BUT Arduino DUE.
Version: 1.0
Homepage: http://arduino.cc/en/Reference/SPI
Keywords: signal, input, output
Compatible frameworks: arduino
Compatible platforms:
Authors: Hristo Gochkov
...
framework-arduinoespressif8266
******************************
ArduinoOTA
==========
Enables Over The Air upgrades, via wifi and espota.py UDP request/TCP download.
Version: 1.0
Keywords: communication
Compatible frameworks: arduino
Compatible platforms: espressif8266
Authors: Ivan Grokhotkov and Miguel Angel Ajo
DNSServer
=========
A simple DNS server for ESP8266.
Version: 1.1.0
Keywords: communication
Compatible frameworks: arduino
Compatible platforms: espressif8266
Authors: Kristijan Novoselić
...
framework-arduinointel
**********************
Adafruit NeoPixel
=================
Arduino library for controlling single-wire-based LED pixels and strip.
Version: 1.0.3
Homepage: https://github.com/adafruit/Adafruit_NeoPixel
Keywords: display
Compatible frameworks: arduino
Compatible platforms: *
Authors: Adafruit
CurieBLE
========
Library to manage the Bluetooth Low Energy module with Curie Core boards.
Version: 1.0
Keywords: communication
Compatible frameworks: arduino
Compatible platforms: intel_arc32
Authors: Emutex
CurieEEPROM
===========
Enables reading and writing to OTP flash area of Curie
Version: 1.0
Homepage: http://www.arduino.cc/en/Reference/EEPROM
Keywords: data, storage
Compatible frameworks: arduino
Compatible platforms: intel_arc32
Authors: Intel
...
framework-arduinomicrochippic32
*******************************
Firmata
=======
Enables the communication with computer apps using a standard serial protocol. For all Arduino boards.
Version: 2.4.4
Homepage: https://github.com/firmata/arduino
Keywords: device, control
Compatible frameworks: arduino
Compatible platforms: *
Authors: Firmata Developers
framework-arduinoteensy
***********************
Adafruit CC3000 Library
=======================
Library code for Adafruit's CC3000 WiFi breakouts.
Version: 1.0.1
Homepage: https://github.com/adafruit/Adafruit_CC3000_Library
Keywords: communication
Compatible frameworks: arduino
Compatible platforms: *
Authors: Adafruit
...
framework-energiamsp430
***********************
AIR430BoostEuropeETSI
=====================
Library for the CC110L Sub-1GHz radio BoosterPack for use in Europe
Version: 1.0.0
Homepage: http://energia.nu/reference/libraries/
Keywords: communication
Compatible frameworks: arduino
Compatible platforms:
Authors: Energia
...
framework-energiativa
*********************
aJson
=====
An Arduino library to enable JSON processing with Arduino
Keywords: json, rest, http, web
Compatible frameworks: arduino
Compatible platforms: atmelavr
platformio lib install
Contents
• platformio lib install
• Usage
• Description
• Storage Options
• Options
• Version control
• Git
• Mercurial
• Subversion
• Examples
Usage
platformio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]
pio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]
# install all project dependencies declared via "lib_deps"
# (run it from a project root where is located "platformio.ini")
platformio lib install [OPTIONS]
# install project dependent library
# (run it from a project root where is located "platformio.ini")
platformio lib install [OPTIONS] [LIBRARY...]
# install dependencies for the specific project build environment
# (run it from a project root where is located "platformio.ini")
platformio lib -e myenv install [OPTIONS] [LIBRARY...]
platformio lib -d /path/to/platformio/project -e myenv install [OPTIONS] [LIBRARY...]
# install to global storage
platformio lib --global install [OPTIONS] [LIBRARY...]
platformio lib -g install [OPTIONS] [LIBRARY...]
# install to custom storage
platformio lib --storage-dir /path/to/dir install [OPTIONS] [LIBRARY...]
platformio lib -d /path/to/dir1 -d /path/to/dir2 install [OPTIONS] [LIBRARY...]
# [LIBRARY...] forms
platformio lib [STORAGE_OPTIONS] install (with no args, project dependencies)
platformio lib [STORAGE_OPTIONS] install <id>
platformio lib [STORAGE_OPTIONS] install id=<id>
platformio lib [STORAGE_OPTIONS] install <id>@<version>
platformio lib [STORAGE_OPTIONS] install <id>@<version range>
platformio lib [STORAGE_OPTIONS] install <name>
platformio lib [STORAGE_OPTIONS] install <name>@<version>
platformio lib [STORAGE_OPTIONS] install <name>@<version range>
platformio lib [STORAGE_OPTIONS] install <zip or tarball url>
platformio lib [STORAGE_OPTIONS] install file://<zip or tarball file>
platformio lib [STORAGE_OPTIONS] install file://<folder>
platformio lib [STORAGE_OPTIONS] install <repository>
platformio lib [STORAGE_OPTIONS] install <name>=<repository> (name it should have locally)
platformio lib [STORAGE_OPTIONS] install <repository#tag> ("tag" can be commit, branch or tag)
WARNING:
If some libraries are not visible in pioide and Code Completion or Code Linting does
not work properly, please perform
• Atom: "Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter)"
• VSCode: "Menu: View > Command Palette... > PlatformIO: Rebuild C/C++ Project Index"
Description
Install a library, and any libraries that it depends on using:
1. Library id or name from PlatformIO Library Registry
2. Custom folder, repository or archive.
The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of
the following forms:
• 1.2.3 - an exact version number. Use only this exact version
• ^1.2.3 - any compatible version (exact version for 1.x.x versions)
• ~1.2.3 - any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
PlatformIO supports installing from local directory or archive. Need to use file:// prefix
before local path. Also, directory or archive should contain .library.json manifest (see
library_config).
• file:///local/path/to/the/platform/dir
• file:///local/path/to/the/platform.zip
• file:///local/path/to/the/platform.tar.gz
Storage Options
See base options for cmd_lib.
Options
--save
Save installed libraries into the projectconf dependency list (projectconf_lib_deps).
You can save libraries for the specific project environment using -e, --environment option
from platformio lib command. For example, platformio lib -e myenv install [LIBRARY...].
-s, --silent
Suppress progress reporting
--interactive
Allow one to make a choice for all prompts
-f, --force
Reinstall/redownload library if it exists
Version control
PlatformIO supports installing from Git, Mercurial and Subversion, and detects the type of
VCS using url prefixes: "git+", "hg+", or "svn+".
NOTE:
PlatformIO requires a working VCS command on your path: git, hg or svn.
Git
The supported schemes are: git, git+https and git+ssh. Here are the supported forms:
• user/library (short version for GitHub repository)
• https://github.com/user/library.git
• git+git://git.server.org/my-library
• git+https://git.server.org/my-library
• git+ssh://git.server.org/my-library
• git+ssh://user@git.server.org/my-library
• [user@]host.xz:path/to/repo.git
Passing branch names, a commit hash or a tag name is possible like so:
• https://github.com/user/library.git#master
• git+git://git.server.org/my-library#master
• git+https://git.server.org/my-library#v1.0
• git+ssh://git.server.org/my-library#7846d8ad52f983f2f2887bdc0f073fe9755a806d
Mercurial
The supported schemes are: hg+http, hg+https and hg+ssh. Here are the supported forms:
• https://developer.mbed.org/users/user/code/library/ (install ARM mbed library)
• hg+hg://hg.server.org/my-library
• hg+https://hg.server.org/my-library
• hg+ssh://hg.server.org/my-library
Passing branch names, a commit hash or a tag name is possible like so:
• hg+hg://hg.server.org/my-library#master
• hg+https://hg.server.org/my-library#v1.0
• hg+ssh://hg.server.org/my-library#4cfe2fa00668
Subversion
The supported schemes are: svn, svn+svn, svn+http, svn+https and svn+ssh. Here are the
supported forms:
• svn+svn://svn.server.org/my-library
• svn+https://svn.server.org/my-library
• svn+ssh://svn.server.org/my-library
You can also give specific revisions to an SVN URL, like so:
• svn+svn://svn.server.org/my-library#13
Examples
1. Install the latest version of library to a global storage using ID or NAME
> platformio lib -g install 4
Library Storage: /storage/dir/...
LibraryManager: Installing id=4
Downloading [####################################] 100%
Unpacking [####################################] 100%
IRremote @ 2.2.1 has been successfully installed!
# repeat command with name
> platformio lib -g install IRRemote
Library Storage: /storage/dir/...
Looking for IRRemote library in registry
Found: https://platformio.org/lib/show/4/IRremote
LibraryManager: Installing id=4
IRremote @ 2.2.1 is already installed
2. Install specified version of a library to a global storage
> platformio lib -g install ArduinoJson@5.6.7
Library Storage: /storage/dir/...
Looking for ArduinoJson library in registry
Found: https://platformio.org/lib/show/64/ArduinoJson
LibraryManager: Installing id=64 @ 5.6.7
Downloading [####################################] 100%
Unpacking [####################################] 100%
ArduinoJson @ 5.6.7 has been successfully installed!
3. Install library with dependencies to custom storage
> platformio lib --storage-dir /my/storage/dir install DallasTemperature
Library Storage: /my/storage/dir
Looking for DallasTemperature library in registry
Found: https://platformio.org/lib/show/54/DallasTemperature
LibraryManager: Installing id=54
Downloading [####################################] 100%
Unpacking [####################################] 100%
DallasTemperature @ 3.7.7 has been successfully installed!
Installing dependencies
Looking for OneWire library in registry
Found: https://platformio.org/lib/show/1/OneWire
LibraryManager: Installing id=1
Downloading [####################################] 100%
Unpacking [####################################] 100%
OneWire @ 8fd2ebfec7 has been successfully installed!
4. Install ARM mbed library to the global storage
> platformio lib -g install https://developer.mbed.org/users/simon/code/TextLCD/
Library Storage: /storage/dir/...
LibraryManager: Installing TextLCD
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
requesting all changes
adding changesets
adding manifests
adding file changes
added 9 changesets with 18 changes to 6 files
updating to branch default
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
TextLCD @ 308d188a2d3a has been successfully installed!
5. Install from archive using URL
> platformio lib -g install https://github.com/adafruit/DHT-sensor-library/archive/master.zip
Library Storage: /storage/dir/...
LibraryManager: Installing master
Downloading [####################################] 100%
Unpacking [####################################] 100%
DHT sensor library @ 1.2.3 has been successfully installed!
platformio lib list
Contents
• platformio lib list
• Usage
• Description
• Storage Options
• Options
• Examples
Usage
platformio lib [STORAGE_OPTIONS] list [OPTIONS]
pio lib [STORAGE_OPTIONS] list [OPTIONS]
# list project dependent libraries
# (run it from a project root where is located "platformio.ini")
platformio lib list [OPTIONS]
# list libraries from global storage
platformio lib --global list [OPTIONS]
platformio lib -g list [OPTIONS]
# list libraries from custom storage
platformio lib --storage-dir /path/to/dir list [OPTIONS]
platformio lib -d /path/to/dir list [OPTIONS]
Description
List installed libraries
Storage Options
See base options for cmd_lib.
Options
--json-output
Return the output in JSON format
Examples
> platformio lib -g list
Library Storage: /storage/dir/...
Adafruit Unified Sensor
=======================
#ID: 31
Required for all Adafruit Unified Sensor based libraries.
Version: 1.0.2
Keywords: sensors
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: Adafruit
ArduinoJson
===========
#ID: 64
An elegant and efficient JSON library for embedded systems
Version: 5.8.0
Keywords: web, json, http, rest
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: Benoit Blanchon
ArduinoJson
===========
#ID: 64
An elegant and efficient JSON library for embedded systems
Version: 5.6.7
Keywords: web, json, http, rest
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: Benoit Blanchon
ArduinoJson
===========
#ID: 64
An elegant and efficient JSON library for embedded systems
Version: 5.7.2
Keywords: web, json, http, rest
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: Benoit Blanchon
Blynk
=====
#ID: 415
Build a smartphone app for your project in minutes. Blynk allows creating IoT solutions easily. It supports WiFi, BLE, Bluetooth, Ethernet, GSM, USB, Serial. Works with many boards like ESP8266, ESP32, Arduino UNO, Nano, Due, Mega, Zero, MKR100, Yun, Raspberry Pi, Particle, Energia, ARM mbed, Intel Edison/Galileo/Joule, BBC micro:bit, DFRobot, RedBearLab, Microduino, LinkIt ONE ...
Version: 0.4.3
Homepage: http://blynk.cc
Keywords: control, gprs, protocol, communication, app, bluetooth, serial, cloud, web, usb, m2m, ble, 3g, smartphone, http, iot, device, sensors, data, esp8266, mobile, wifi, ethernet, gsm
Compatible frameworks: energia, wiringpi, arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, linux_arm, microchippic32, nordicnrf51, teensy, timsp430, titiva
Authors: Volodymyr Shymanskyy
Bounce2
=======
#ID: 1106
Debouncing library for Arduino or Wiring
Version: 2.1
Keywords: input, signal, output, bounce
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: Thomas O Fredericks
Homie
=====
#ID: 555
ESP8266 framework for Homie, a lightweight MQTT convention for the IoT
Version: 1.5.0
Keywords: home, mqtt, iot, esp8266, automation
Compatible frameworks: arduino
Compatible platforms: espressif8266
Authors: Marvin Roger
JustWifi
========
#ID: 1282
Wifi Manager for ESP8266 that supports multiple wifi networks and scan for strongest signal
Version: 1.1.1
License: GPL-3.0
Keywords: manager, wifi, scan
Compatible frameworks: arduino
Compatible platforms: espressif8266
Authors: Xose Perez
LiquidCrystal
=============
#ID: 136
LiquidCrystal Library is faster and extensable, compatible with the original LiquidCrystal library
Version: 1.3.4
Keywords: lcd, hd44780
Compatible frameworks: arduino
Compatible platforms: atmelavr
Authors: F Malpartida
TextLCD
=======
hg+https://developer.mbed.org/users/simon/code/TextLCD/
Version: 308d188a2d3a
Keywords: uncategorized
Time
====
#ID: 44
Time keeping library
Version: 1.5
Homepage: http://playground.arduino.cc/Code/Time
Keywords: week, rtc, hour, year, month, second, time, date, day, minute
Compatible frameworks: arduino
Compatible platforms:
Authors: Michael Margolis, Paul Stoffregen
Timezone
========
#ID: 76
Arduino library to facilitate time zone conversions and automatic daylight saving (summer) time adjustments
Version: 510ae2f6b6
Keywords: zone, time
Compatible frameworks: arduino
Compatible platforms: atmelavr
Authors: Jack Christensen
U8g2
====
#ID: 942
Monochrome LCD, OLED and eInk Library. Display controller: SSD1305, SSD1306, SSD1322, SSD1325, SSD1327, SSD1606, SH1106, T6963, RA8835, LC7981, PCD8544, PCF8812, UC1604, UC1608, UC1610, UC1611, UC1701, ST7565, ST7567, NT7534, ST7920, LD7032, KS0108. Interfaces: I2C, SPI, Parallel.
Version: 2.11.4
Homepage: https://github.com/olikraus/u8g2
Keywords: display
Compatible frameworks: arduino
Compatible platforms: atmelavr, atmelsam, espressif8266, intel_arc32, microchippic32, nordicnrf51, teensy, timsp430
Authors: oliver
USB-Host-Shield-20
==================
#ID: 59
Revision 2.0 of MAX3421E-based USB Host Shield Library
Version: 1.2.1
License: GPL-2.0
Keywords: usb, spp, mass storage, pl2303, acm, ftdi, xbox, host, hid, wii, buzz, ps3, bluetooth, adk, ps4
Compatible frameworks: spl, arduino
Compatible platforms: atmelavr, atmelsam, teensy, nordicnrf51, ststm32
Authors: Oleg Mazurov, Alexei Glushchenko, Kristian Lauszus, Andrew Kroll
platformio lib register
Contents
• platformio lib register
• Usage
• Description
• Examples
Usage
platformio lib register [MANIFEST_URL]
pio lib register [MANIFEST_URL]
Description
Register new library in PlatformIO Library Registry.
PlatformIO Library Registry supports the next library manifests:
• PlatformIO library_config
• Arduino library.properties
• ARM mbed yotta module.json.
Examples
platformio lib register https://raw.githubusercontent.com/bblanchon/ArduinoJson/master/library.json
platformio lib register https://raw.githubusercontent.com/adafruit/DHT-sensor-library/master/library.properties
platformio lib register https://raw.githubusercontent.com/ARMmbed/ble/master/module.json
platformio lib search
Contents
• platformio lib search
• Usage
• Description
• Options
• Examples
Usage
platformio lib search [OPTIONS] [QUERY]
pio lib search [OPTIONS] [QUERY]
Description
Search for library in PlatformIO Library Registry by library_config fields in the boolean
mode.
The boolean search capability supports the following operators:
┌──────────────┬──────────────────────────────────┐
│Operator │ Description │
├──────────────┼──────────────────────────────────┤
│+ │ A leading or trailing plus sign │
│ │ indicates that this word must be │
│ │ present in library fields (see │
│ │ above) that is returned. │
├──────────────┼──────────────────────────────────┤
│- │ A leading or trailing minus sign │
│ │ indicates that this word must │
│ │ not be present in any of the │
│ │ libraries that are returned. │
├──────────────┼──────────────────────────────────┤
│(no operator) │ By default (when neither + nor - │
│ │ is specified), the word is │
│ │ optional, but the libraries that │
│ │ contain it are rated higher. │
├──────────────┼──────────────────────────────────┤
│> < │ These two operators are used to │
│ │ change a word's contribution to │
│ │ the relevance value that is │
│ │ assigned to a library. The > │
│ │ operator increases the │
│ │ contribution and the < operator │
│ │ decreases it. │
├──────────────┼──────────────────────────────────┤
│( ) │ Parentheses group words into │
│ │ subexpressions. Parenthesized │
│ │ groups can be nested. │
├──────────────┼──────────────────────────────────┤
│~ │ A leading tilde acts as a │
│ │ negation operator, causing the │
│ │ word's contribution to the │
│ │ library's relevance to be │
│ │ negative. This is useful for │
│ │ marking "noise" words. A library │
│ │ containing such a word is rated │
│ │ lower than others, but is not │
│ │ excluded altogether, as it would │
│ │ be with the - operator. │
└──────────────┴──────────────────────────────────┘
│* │ The asterisk serves as the │
│ │ truncation (or wildcard) │
│ │ operator. Unlike the other │
│ │ operators, it is appended to the │
│ │ word to be affected. Words match │
│ │ if they begin with the word │
│ │ preceding the * operator. │
├──────────────┼──────────────────────────────────┤
│" │ A phrase that is enclosed within │
│ │ double quote (") characters │
│ │ matches only libraries that │
│ │ contain the phrase literally, as │
│ │ it was typed. │
└──────────────┴──────────────────────────────────┘
For more detail information please go to MySQL Boolean Full-Text Searches.
Options
--id
Filter libraries by registry ID
-n, --name
Filter libraries by specified name (strict search)
-a, --author
Filter libraries by specified author
-k, --keyword
Filter libraries by specified keyword
-f, --framework
Filter libraries by specified framework
-p, --platform
Filter libraries by specified keyword
-i, --header
Filter libraries by header file (include)
For example, platformio lib search --header "OneWire.h"
--json-output
Return the output in JSON format
--page
Manually paginate through search results. This option is useful in pair with
--json-output.
Examples
1. List all libraries
> platformio lib search
Found N libraries:
ArduinoJson
===========
#ID: 64
An elegant and efficient JSON library for embedded systems
Keywords: web, json, http, rest
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Teensy, TI MSP430
Authors: Benoit Blanchon
DHT sensor library
==================
#ID: 19
Arduino library for DHT11, DHT22, etc Temp & Humidity Sensors
Keywords: unified, dht, sensor, temperature, humidity
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Adafruit Industries
PubSubClient
============
#ID: 89
A client library for MQTT messaging. MQTT is a lightweight messaging protocol ideal for small devices. This library allows you to send and receive MQTT messages. It supports the latest MQTT 3.1.1 protocol and can be configured to use the older MQTT 3.1...
Keywords: ethernet, mqtt, iot, m2m
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Teensy, TI MSP430
Authors: Nick O'Leary
...
ESPAsyncWebServer
=================
#ID: 306
Asynchronous HTTP and WebSocket Server Library for ESP8266 and ESP32
Keywords: async, websocket, http, webserver
Compatible frameworks: Arduino
Compatible platforms: Espressif 8266
Authors: Hristo Gochkov
Show next libraries? [y/N]:
...
2. Search for 1-Wire libraries
> platformio lib search "1-wire"
Found N libraries:
DS1820
======
#ID: 196
Dallas / Maxim DS1820 1-Wire library. For communication with multiple DS1820 on a single 1-Wire bus. Also supports DS18S20 and DS18B20.
Keywords: ds18s20, 1-wire, ds1820, ds18b20
Compatible frameworks: mbed
Compatible platforms: Freescale Kinetis, Nordic nRF51, NXP LPC, ST STM32, Teensy
Authors: Michael Hagberg
OneWire
=======
#ID: 1
Control 1-Wire protocol (DS18S20, DS18B20, DS2408 and etc)
Keywords: onewire, temperature, bus, 1-wire, ibutton, sensor
Compatible frameworks: Arduino
Compatible platforms:
Authors: Paul Stoffregen, Jim Studt, Tom Pollard, Derek Yerger, Josh Larios, Robin James, Glenn Trewitt, Jason Dangel, Guillermo Lovato, Ken Butcher, Mark Tillotson, Bertrik Sikken, Scott Roberts
Show next libraries? [y/N]:
...
3. Search for Arduino-based "I2C" libraries
> platformio lib search "i2c" --framework="arduino"
Found N libraries:
I2Cdevlib-AK8975
================
#ID: 10
AK8975 is 3-axis electronic compass IC with high sensitive Hall sensor technology
Keywords: i2c, i2cdevlib, sensor, compass
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Jeff Rowberg
I2Cdevlib-Core
==============
#ID: 11
The I2C Device Library (I2Cdevlib) is a collection of uniform and well-documented classes to provide simple and intuitive interfaces to I2C devices.
Keywords: i2cdevlib, i2c
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Jeff Rowberg
Adafruit 9DOF Library
=====================
#ID: 14
Unified sensor driver for the Adafruit 9DOF Breakout (L3GD20 / LSM303)
Keywords: magnetometer, unified, accelerometer, spi, compass, i2c, sensor, gyroscope
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Adafruit Industries
Show next libraries? [y/N]:
...
4. Search for libraries by "web" and "http" keywords.
> platformio lib search --keyword="web" --keyword="http"
Found N libraries:
ArduinoJson
===========
#ID: 64
An elegant and efficient JSON library for embedded systems
Keywords: web, json, http, rest
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Teensy, TI MSP430
Authors: Benoit Blanchon
ESPAsyncWebServer
=================
#ID: 306
Asynchronous HTTP and WebSocket Server Library for ESP8266 and ESP32
Keywords: async, websocket, http, webserver
Compatible frameworks: Arduino
Compatible platforms: Espressif 8266
Authors: Hristo Gochkov
ESP8266wifi
===========
#ID: 1101
ESP8266 Arduino library with built in reconnect functionality
Keywords: web, http, wifi, server, client, wi-fi
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Jonas Ekstrand
Blynk
=====
#ID: 415
Build a smartphone app for your project in minutes. Blynk allows creating IoT solutions easily. It supports WiFi, BLE, Bluetooth, Ethernet, GSM, USB, Serial. Works with many boards like ESP8266, ESP32, Arduino UNO, Nano, Due, Mega, Zero, MKR100, Yun,...
Keywords: control, gprs, protocol, communication, app, bluetooth, serial, cloud, web, usb, m2m, ble, 3g, smartphone, http, iot, device, sensors, data, esp8266, mobile, wifi, ethernet, gsm
Compatible frameworks: Arduino, Energia, WiringPi
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 8266, Intel ARC32, Linux ARM, Microchip PIC32, Nordic nRF51, Teensy, TI MSP430, TI Tiva
Authors: Volodymyr Shymanskyy
Show next libraries? [y/N]:
...
5. Search for libraries by "Adafruit Industries" author
> platformio lib search --author="Adafruit Industries"
Found N libraries:
DHT sensor library
==================
#ID: 19
Arduino library for DHT11, DHT22, etc Temp & Humidity Sensors
Keywords: unified, dht, sensor, temperature, humidity
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Adafruit Industries
Adafruit DHT Unified
====================
#ID: 18
Unified sensor library for DHT (DHT11, DHT22 and etc) temperature and humidity sensors
Keywords: unified, dht, sensor, temperature, humidity
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Adafruit Industries
Show next libraries? [y/N]:
...
6. Search for libraries which are compatible with Dallas temperature sensors like DS18B20,
DS18S20 and etc.
> platformio lib search "DS*"
Found N libraries:
DS1820
======
#ID: 196
Dallas / Maxim DS1820 1-Wire library. For communication with multiple DS1820 on a single 1-Wire bus. Also supports DS18S20 and DS18B20.
Keywords: ds18s20, 1-wire, ds1820, ds18b20
Compatible frameworks: mbed
Compatible platforms: Freescale Kinetis, Nordic nRF51, NXP LPC, ST STM32, Teensy
Authors: Michael Hagberg
I2Cdevlib-DS1307
================
#ID: 99
The DS1307 serial real-time clock (RTC) is a low-power, full binary-coded decimal (BCD) clock/calendar plus 56 bytes of NV SRAM
Keywords: i2cdevlib, clock, i2c, rtc, time
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Jeff Rowberg
Show next libraries? [y/N]:
...
7. Search for Energia-based *nRF24* or *HttpClient* libraries. The search query that is
described below can be interpreted like energia nRF24 OR energia HttpClient
> platformio lib search "+(nRF24 HttpClient)" --framework="arduino"
Found N libraries:
RadioHead
=========
#ID: 124
The RadioHead Packet Radio library which provides a complete object-oriented library for sending and receiving packetized messages via RF22/24/26/27/69, Si4460/4461/4463/4464, nRF24/nRF905, SX1276/77/78, RFM95/96/97/98 and etc.
Keywords: rf, radio, wireless
Compatible frameworks: Arduino, Energia
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 32, Espressif 8266, Infineon XMC, Intel ARC32, Kendryte K210, Microchip PIC32, Nordic nRF51, Nordic nRF52, ST STM32, ST STM8, Teensy, TI MSP430, TI Tiva
Authors: Mike McCauley
ArduinoHttpClient
=================
#ID: 798
[EXPERIMENTAL] Easily interact with web servers from Arduino, using HTTP and WebSocket's.
Keywords: communication
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 32, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Nordic nRF52, ST STM32, ST STM8, Teensy, TI MSP430
Authors: Arduino
HttpClient
==========
#ID: 66
Library to easily make HTTP GET, POST and PUT requests to a web server.
Keywords: communication
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 32, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Nordic nRF52, ST STM32, Teensy, TI MSP430
Authors: Adrian McEwen
Show next libraries? [y/N]:
...
8. Search for the all sensor libraries excluding temperature.
> platformio lib search "sensor -temperature"
Found N libraries:
SparkFun VL6180 Sensor
======================
#ID: 407
The VL6180 combines an IR emitter, a range sensor, and an ambient light sensor together for you to easily use and communicate with via an I2C interface.
Keywords: sensors
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR, Atmel SAM, Espressif 8266, Intel ARC32, Microchip PIC32, Nordic nRF51, Teensy, TI MSP430
Authors: Casey Kuhns@SparkFun, SparkFun Electronics
I2Cdevlib-AK8975
================
#ID: 10
AK8975 is 3-axis electronic compass IC with high sensitive Hall sensor technology
Keywords: i2c, i2cdevlib, sensor, compass
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Jeff Rowberg
Adafruit 9DOF Library
=====================
#ID: 14
Unified sensor driver for the Adafruit 9DOF Breakout (L3GD20 / LSM303)
Keywords: magnetometer, unified, accelerometer, spi, compass, i2c, sensor, gyroscope
Compatible frameworks: Arduino
Compatible platforms: Atmel AVR
Authors: Adafruit Industries
Show next libraries? [y/N]:
...
platformio lib show
Contents
• platformio lib show
• Usage
• Description
• Options
• Examples
Usage
platformio lib show [LIBRARY]
pio lib show [LIBRARY]
Description
Show detailed info about a library using PlatformIO Library Registry.
The possible values for [LIBRARY]:
• Library ID from Registry (preferred)
• Library Name
Options
--json-output
Return the output in JSON format
Examples
> platformio lib show OneWire
PubSubClient
============
#ID: 89
A client library for MQTT messaging. MQTT is a lightweight messaging protocol ideal for small devices. This library allows you to send and receive MQTT messages. It supports the latest MQTT 3.1.1 protocol and can be configured to use the older MQTT 3.1...
Version: 2.6, released 10 months ago
Manifest: https://raw.githubusercontent.com/ivankravets/pubsubclient/patch-2/library.json
Homepage: http://pubsubclient.knolleary.net
Repository: https://github.com/knolleary/pubsubclient.git
Authors
-------
Nick O'Leary https://github.com/knolleary
Keywords
--------
ethernet
mqtt
iot
m2m
Compatible frameworks
---------------------
Arduino
Compatible platforms
--------------------
Atmel AVR
Atmel SAM
Espressif 8266
Intel ARC32
Microchip PIC32
Nordic nRF51
Teensy
TI MSP430
Headers
-------
PubSubClient.h
Examples
--------
http://dl.platformio.org/libraries/examples/0/89/mqtt_auth.ino
http://dl.platformio.org/libraries/examples/0/89/mqtt_basic.ino
http://dl.platformio.org/libraries/examples/0/89/mqtt_esp8266.ino
http://dl.platformio.org/libraries/examples/0/89/mqtt_publish_in_callback.ino
http://dl.platformio.org/libraries/examples/0/89/mqtt_reconnect_nonblocking.ino
http://dl.platformio.org/libraries/examples/0/89/mqtt_stream.ino
Versions
--------
2.6, released 10 months ago
Downloads
---------
Today: 25
Week: 120
Month: 462
platformio lib stats
Contents
• platformio lib stats
• Usage
• Description
• Options
• Examples
Usage
platformio lib stats
pio lib stats
Description
Show PlatformIO Library Registry statistics:
• Recently updated
• Recently added
• Recent keywords
• Popular keywords
• Featured: Today
• Featured: Week
• Featured: Month
This information is the same that is shown on this page:
• https://platformio.org/lib
Options
--json-output
Return the output in JSON format
Examples
RECENTLY UPDATED
****************
Name Date Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
GroveEncoder 12 hours ago https://platformio.org/lib/show/1382/GroveEncoder
RF24G 12 hours ago https://platformio.org/lib/show/1381/RF24G
Sim800L Library Revised 12 hours ago https://platformio.org/lib/show/1380/Sim800L%20Library%20Revised
ArduinoSTL 12 hours ago https://platformio.org/lib/show/750/ArduinoSTL
hd44780 13 hours ago https://platformio.org/lib/show/738/hd44780
RECENTLY ADDED
**************
Name Date Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
GroveEncoder 12 hours ago https://platformio.org/lib/show/1382/GroveEncoder
RF24G 12 hours ago https://platformio.org/lib/show/1381/RF24G
Sim800L Library Revised 12 hours ago https://platformio.org/lib/show/1380/Sim800L%20Library%20Revised
DS3231 a day ago https://platformio.org/lib/show/1379/DS3231
ArduboyPlaytune 4 days ago https://platformio.org/lib/show/1378/ArduboyPlaytune
RECENT KEYWORDS
***************
Name Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
cobs https://platformio.org/lib/search?query=keyword%3Acobs
packet https://platformio.org/lib/search?query=keyword%3Apacket
framing https://platformio.org/lib/search?query=keyword%3Aframing
3g https://platformio.org/lib/search?query=keyword%3A3g
tdd https://platformio.org/lib/search?query=keyword%3Atdd
POPULAR KEYWORDS
****************
Name Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
display https://platformio.org/lib/search?query=keyword%3Adisplay
lcd https://platformio.org/lib/search?query=keyword%3Alcd
sensors https://platformio.org/lib/search?query=keyword%3Asensors
graphics https://platformio.org/lib/search?query=keyword%3Agraphics
communication https://platformio.org/lib/search?query=keyword%3Acommunication
oled https://platformio.org/lib/search?query=keyword%3Aoled
tft https://platformio.org/lib/search?query=keyword%3Atft
control https://platformio.org/lib/search?query=keyword%3Acontrol
device https://platformio.org/lib/search?query=keyword%3Adevice
glcd https://platformio.org/lib/search?query=keyword%3Aglcd
displaycore https://platformio.org/lib/search?query=keyword%3Adisplaycore
font https://platformio.org/lib/search?query=keyword%3Afont
other https://platformio.org/lib/search?query=keyword%3Aother
i2c https://platformio.org/lib/search?query=keyword%3Ai2c
input https://platformio.org/lib/search?query=keyword%3Ainput
signal https://platformio.org/lib/search?query=keyword%3Asignal
sensor https://platformio.org/lib/search?query=keyword%3Asensor
output https://platformio.org/lib/search?query=keyword%3Aoutput
spi https://platformio.org/lib/search?query=keyword%3Aspi
data https://platformio.org/lib/search?query=keyword%3Adata
timing https://platformio.org/lib/search?query=keyword%3Atiming
serial https://platformio.org/lib/search?query=keyword%3Aserial
temperature https://platformio.org/lib/search?query=keyword%3Atemperature
http https://platformio.org/lib/search?query=keyword%3Ahttp
wifi https://platformio.org/lib/search?query=keyword%3Awifi
rf https://platformio.org/lib/search?query=keyword%3Arf
i2cdevlib https://platformio.org/lib/search?query=keyword%3Ai2cdevlib
processing https://platformio.org/lib/search?query=keyword%3Aprocessing
storage https://platformio.org/lib/search?query=keyword%3Astorage
radio https://platformio.org/lib/search?query=keyword%3Aradio
web https://platformio.org/lib/search?query=keyword%3Aweb
accelerometer https://platformio.org/lib/search?query=keyword%3Aaccelerometer
wireless https://platformio.org/lib/search?query=keyword%3Awireless
protocol https://platformio.org/lib/search?query=keyword%3Aprotocol
server https://platformio.org/lib/search?query=keyword%3Aserver
wi-fi https://platformio.org/lib/search?query=keyword%3Awi-fi
ethernet https://platformio.org/lib/search?query=keyword%3Aethernet
mbed https://platformio.org/lib/search?query=keyword%3Ambed
openag https://platformio.org/lib/search?query=keyword%3Aopenag
led https://platformio.org/lib/search?query=keyword%3Aled
esp8266 https://platformio.org/lib/search?query=keyword%3Aesp8266
humidity https://platformio.org/lib/search?query=keyword%3Ahumidity
time https://platformio.org/lib/search?query=keyword%3Atime
iot https://platformio.org/lib/search?query=keyword%3Aiot
json https://platformio.org/lib/search?query=keyword%3Ajson
timer https://platformio.org/lib/search?query=keyword%3Atimer
client https://platformio.org/lib/search?query=keyword%3Aclient
driver https://platformio.org/lib/search?query=keyword%3Adriver
button https://platformio.org/lib/search?query=keyword%3Abutton
mbed-official https://platformio.org/lib/search?query=keyword%3Ambed-official
FEATURED: TODAY
***************
Name Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PubSubClient https://platformio.org/lib/show/89/PubSubClient
Adafruit Unified Sensor https://platformio.org/lib/show/31/Adafruit%20Unified%20Sensor
DHT sensor library https://platformio.org/lib/show/19/DHT%20sensor%20library
ESPAsyncUDP https://platformio.org/lib/show/359/ESPAsyncUDP
NtpClientLib https://platformio.org/lib/show/727/NtpClientLib
Embedis https://platformio.org/lib/show/408/Embedis
Blynk https://platformio.org/lib/show/415/Blynk
SimpleTimer https://platformio.org/lib/show/419/SimpleTimer
Adafruit DHT Unified https://platformio.org/lib/show/18/Adafruit%20DHT%20Unified
RTClib https://platformio.org/lib/show/83/RTClib
FEATURED: WEEK
**************
Name Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
DHT sensor library https://platformio.org/lib/show/19/DHT%20sensor%20library
Adafruit Unified Sensor https://platformio.org/lib/show/31/Adafruit%20Unified%20Sensor
Blynk https://platformio.org/lib/show/415/Blynk
ESPAsyncWebServer https://platformio.org/lib/show/306/ESPAsyncWebServer
Adafruit GFX Library https://platformio.org/lib/show/13/Adafruit%20GFX%20Library
I2Cdevlib-Core https://platformio.org/lib/show/11/I2Cdevlib-Core
TimeAlarms https://platformio.org/lib/show/68/TimeAlarms
PubSubClient https://platformio.org/lib/show/89/PubSubClient
Timer https://platformio.org/lib/show/75/Timer
esp8266_mdns https://platformio.org/lib/show/1091/esp8266_mdns
FEATURED: MONTH
***************
Name Url
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ArduinoJson https://platformio.org/lib/show/64/ArduinoJson
DHT sensor library https://platformio.org/lib/show/19/DHT%20sensor%20library
Adafruit Unified Sensor https://platformio.org/lib/show/31/Adafruit%20Unified%20Sensor
PubSubClient https://platformio.org/lib/show/89/PubSubClient
OneWire https://platformio.org/lib/show/1/OneWire
ESPAsyncTCP https://platformio.org/lib/show/305/ESPAsyncTCP
Time https://platformio.org/lib/show/44/Time
DallasTemperature https://platformio.org/lib/show/54/DallasTemperature
ESPAsyncWebServer https://platformio.org/lib/show/306/ESPAsyncWebServer
WifiManager https://platformio.org/lib/show/567/WifiManager
platformio lib uninstall
Contents
• platformio lib uninstall
• Usage
• Description
• Storage Options
• Examples
Usage
platformio lib [STORAGE_OPTIONS] uninstall [LIBRARY...]
pio lib [STORAGE_OPTIONS] uninstall [LIBRARY...]
# uninstall project dependent library
# (run it from a project root where is located "platformio.ini")
platformio lib uninstall [LIBRARY...]
# uninstall library from global storage
platformio lib --global uninstall [LIBRARY...]
platformio lib -g uninstall [LIBRARY...]
# uninstall library from custom storage
platformio lib --storage-dir /path/to/dir uninstall [LIBRARY...]
platformio lib -d /path/to/dir uninstall [LIBRARY...]
# [LIBRARY...] forms
platformio lib [STORAGE_OPTIONS] uninstall <id>
platformio lib [STORAGE_OPTIONS] uninstall <id>@<version>
platformio lib [STORAGE_OPTIONS] uninstall <id>@<version range>
platformio lib [STORAGE_OPTIONS] uninstall <name>
platformio lib [STORAGE_OPTIONS] uninstall <name>@<version>
platformio lib [STORAGE_OPTIONS] uninstall <name>@<version range>
Description
Uninstall specified library
The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of
the following forms:
• 1.2.3 - an exact version number. Use only this exact version
• ^1.2.3 - any compatible version (exact version for 1.x.x versions)
• ~1.2.3 - any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
Storage Options
See base options for cmd_lib.
Examples
> platformio lib -g uninstall AsyncMqttClient
Library Storage: /storage/dir/...
Uninstalling AsyncMqttClient @ 0.2.0: [OK]
platformio lib update
Contents
• platformio lib update
• Usage
• Description
• Storage Options
• Options
• Examples
Usage
platformio lib [STORAGE_OPTIONS] update [OPTIONS]
pio lib [STORAGE_OPTIONS] update [OPTIONS]
# update all project libraries
# (run it from a project root where is located "platformio.ini")
platformio lib update [OPTIONS]
# update project dependent library
platformio lib [STORAGE_OPTIONS] update [OPTIONS] [LIBRARY...]
# update library in global storage
platformio lib --global update [OPTIONS] [LIBRARY...]
platformio lib -g update [OPTIONS] [LIBRARY...]
# update library in custom storage
platformio lib --storage-dir /path/to/dir update [OPTIONS] [LIBRARY...]
platformio lib -d /path/to/dir update [OPTIONS] [LIBRARY...]
# [LIBRARY...] forms
platformio lib [STORAGE_OPTIONS] update <id>
platformio lib [STORAGE_OPTIONS] update <id>@<version>
platformio lib [STORAGE_OPTIONS] update <id>@<version range>
platformio lib [STORAGE_OPTIONS] update <name>
platformio lib [STORAGE_OPTIONS] update <name>@<version>
platformio lib [STORAGE_OPTIONS] update <name>@<version range>
Description
Check or update installed libraries.
The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of
the following forms:
• 1.2.3 - an exact version number. Use only this exact version
• ^1.2.3 - any compatible version (exact version for 1.x.x versions)
• ~1.2.3 - any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
Storage Options
See base options for cmd_lib.
Options
-c, --only-check
DEPRECATED. Please use --dry-run instead.
--dry-run
Do not update, only check for the new versions
--json-output
Return the output in JSON format
Examples
1. Update all installed libraries in global storage
> platformio lib -g update
Library Storage: /storage/dir/...
Updating ESP8266_SSD1306 @ 3.2.3: [Up-to-date]
Updating EngduinoMagnetometer @ 3.1.0: [Up-to-date]
Updating IRremote @ 2.2.1: [Up-to-date]
Updating Json @ 5.4.0: [Out-of-date]
LibraryManager: Installing id=64 @ 5.6.4
Downloading [####################################] 100%
Unpacking [####################################] 100%
Json @ 5.6.4 has been successfully installed!
Updating PJON @ 1fb26fd: [Checking]
git version 2.7.4 (Apple Git-66)
Already up-to-date.
Updating TextLCD @ 308d188a2d3a: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/TextLCD/
searching for changes
no changes found
2. Update specified libraries in global storage
> platformio lib -g update Json 4
Library Storage: /storage/dir/...
Updating Json @ 5.6.4: [Up-to-date]
Updating IRremote @ 2.2.1: [Up-to-date]
Project Manager CLI
To print all available commands and options use:
platformio project --help
platformio project COMMAND --help
platformio project config
Contents
• platformio project config
• Usage
• Description
• Options
• Examples
Usage
platformio project config [OPTIONS]
pio project config [OPTIONS]
Description
Show project computed configuration based on projectconf. The extra configuration files
and dynamic variables will be expanded.
This command is useful for developers to check how PlatformIO computes configuration from
projectconf.
Options
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
--json-output
Return the output in JSON format.
Examples
> pio platformio config
Computed project configuration for Tasmota Project
platformio
----------
src_dir = tasmota
build_dir = .pioenvs
build_cache_dir = .cache
extra_configs = platformio_tasmota_env.ini
platformio_override.ini
default_envs = tasmota
common
------
framework = arduino
board = esp01_1m
board_build.flash_mode = dout
platform = espressif8266
build_flags = -D NDEBUG
-mtarget-align
-Wl,-Map,firmware.map
-Wl,-Teagle.flash.1m.ld
-DBEARSSL_SSL_BASIC
-DPIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_190703
-DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH
-DVTABLES_IN_FLASH
-fno-exceptions
-lstdc++
build_unflags = -Wall
board_build.f_cpu = 80000000L
monitor_speed = 115200
upload_speed = 115200
upload_resetmethod = nodemcu
upload_port = COM5
extra_scripts = pio/strip-floats.py
pio/name-firmware.py
scripts_defaults
----------------
extra_scripts = pio/strip-floats.py
pio/name-firmware.py
...
platformio project init
Contents
• platformio project init
• Usage
• Description
• Options
• Examples
Usage
platformio project init [OPTIONS]
pio project init [OPTIONS]
Description
Initialize a new PlatformIO based project or update existing with new data.
This command will create:
• projectconf
• projectconf_pio_include_dir, put project header files here
• projectconf_pio_src_dir, put project source files here (*.h, *.c, *.cpp, *.S, *.ino,
etc.)
• projectconf_pio_lib_dir, put project specific (private) libraries here. See also ldf
• projectconf_pio_test_dir, put project tests here. More details unit_testing
• Miscellaneous files for VCS and ci support.
Options
-d, --project-dir
A path to a directory where PlatformIO will initialize new project.
-b, --board
If you specify board ID (you can pass multiple --board options), then PlatformIO will
automatically generate environment for projectconf and pre-fill these data:
• projectconf_env_platform
• projectconf_env_framework
• projectconf_env_board
The full list with pre-configured boards is available here platforms.
--ide
Initialize PlatformIO project for the specified IDE which can be imported later via
"Import Project" functionality.
A list with supported IDE is available within platformio project init --help command.
Also, please take a look at ide page.
-O, --project-option
Initialize project with additional options from projectconf. For example, platformio
project init --project-option="lib_deps=ArduinoJSON". Multiple options are allowed.
--env-prefix
An environment prefix which will be used with pair in projectconf_env_board ID. For
example, the default environment name for board_teensy_teensy31 board will be
[env:teensy31].
-s, --silent
Suppress progress reporting
Examples
1. Initialize new project in a current working directory
> platformio project init
The current working directory *** will be used for the new project.
You can specify another project directory via
`platformio project init -d %PATH_TO_THE_PROJECT_DIR%` command.
The next files/directories will be created in ***
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
src - Put your source files here
lib - Put here project specific (private) libraries
Project has been successfully initialized!
Useful commands:
`platformio run` - process/build project from the current directory
`platformio run --target upload` or `platformio run -t upload` - upload firmware to embedded board
`platformio run --target clean` - clean project (remove compiled files)
2. Initialize new project in a specified directory
> platformio project init -d %PATH_TO_DIR%
The next files/directories will be created in ***
platformio.ini - Project Configuration File. |-> PLEASE EDIT ME <-|
...
3. Initialize project for Arduino Uno
> platformio project init --board uno
The current working directory *** will be used for the new project.
You can specify another project directory via
`platformio project init -d %PATH_TO_THE_PROJECT_DIR%` command.
...
4. Initialize project for Teensy 3.1 board with custom framework_mbed
> platformio project init --board teensy31 --project-option "framework=mbed"
The current working directory *** will be used for the new project.
You can specify another project directory via
`platformio project init -d %PATH_TO_THE_PROJECT_DIR%` command.
...
Platform Manager CLI
To print all available commands and options use:
platformio platform --help
platformio platform COMMAND --help
[image]
platformio platform frameworks
Contents
• platformio platform frameworks
• Usage
• Description
• Options
• Examples
Usage
platformio platform frameworks QUERY [OPTIONS]
pio platform frameworks QUERY [OPTIONS]
Description
List supported frameworks (SDKs, etc).
Options
--json-output
Return the output in JSON format
Examples
Print all supported frameworks, SDKs, etc.
> platformio platform frameworks
arduino ~ Arduino
=================
Arduino Wiring-based Framework allows writing cross-platform software to control devices attached to a wide range of Arduino boards to create all kinds of creative coding, interactive objects, spaces or physical experiences.
Home: https://platformio.org/frameworks/arduino
artik-sdk ~ ARTIK SDK
=====================
ARTIK SDK is a C/C++ SDK targeting Samsung ARTIK platforms. It exposes a set of APIs to ease up development of applications. These APIs cover hardware buses such as GPIO, SPI, I2C, UART, connectivity links like Wi-Fi, Bluetooth, Zigbee, and network protocols such as HTTP, Websockets, MQTT, and others.
Home: https://platformio.org/frameworks/artik-sdk
cmsis ~ CMSIS
=============
The ARM Cortex Microcontroller Software Interface Standard (CMSIS) is a vendor-independent hardware abstraction layer for the Cortex-M processor series and specifies debugger interfaces. The CMSIS enables consistent and simple software interfaces to the processor for interface peripherals, real-time operating systems, and middleware. It simplifies software re-use, reducing the learning curve for new microcontroller developers and cutting the time-to-market for devices.
Home: https://platformio.org/frameworks/cmsis
espidf ~ ESP-IDF
================
Espressif IoT Development Framework. Official development framework for ESP32.
Home: https://platformio.org/frameworks/espidf
libopencm3 ~ libOpenCM3
=======================
The libOpenCM3 framework aims to create a free/libre/open-source firmware library for various ARM Cortex-M0(+)/M3/M4 microcontrollers, including ST STM32, Ti Tiva and Stellaris, NXP LPC 11xx, 13xx, 15xx, 17xx parts, Atmel SAM3, Energy Micro EFM32 and others.
Home: https://platformio.org/frameworks/libopencm3
mbed ~ mbed
===========
The mbed framework The mbed SDK has been designed to provide enough hardware abstraction to be intuitive and concise, yet powerful enough to build complex projects. It is built on the low-level ARM CMSIS APIs, allowing you to code down to the metal if needed. In addition to RTOS, USB and Networking libraries, a cookbook of hundreds of reusable peripheral and module libraries have been built on top of the SDK by the mbed Developer Community.
Home: https://platformio.org/frameworks/mbed
pumbaa ~ Pumbaa
===============
Pumbaa is Python on top of Simba. The implementation is a port of MicroPython, designed for embedded devices with limited amount of RAM and code memory.
Home: https://platformio.org/frameworks/pumbaa
simba ~ Simba
=============
Simba is an RTOS and build framework. It aims to make embedded programming easy and portable.
Home: https://platformio.org/frameworks/simba
spl ~ SPL
=========
The ST Standard Peripheral Library provides a set of functions for handling the peripherals on the STM32 Cortex-M3 family. The idea is to save the user (the new user, in particular) having to deal directly with the registers.
Home: https://platformio.org/frameworks/spl
wiringpi ~ WiringPi
===================
WiringPi is a GPIO access library written in C for the BCM2835 used in the Raspberry Pi. It's designed to be familiar to people who have used the Arduino "wiring" system.
Home: https://platformio.org/frameworks/wiringpi
platformio platform install
Contents
• platformio platform install
• Usage
• Options
• Description
• Version control
• Git
• Mercurial
• Subversion
• Examples
Usage
platformio platform install [OPTIONS] [PLATFORM...]
pio platform install [OPTIONS] [PLATFORM...]
# [PLATFORM...] forms
platformio platform install <name>
platformio platform install <name>@<version>
platformio platform install <name>@<version range>
platformio platform install <zip or tarball url>
platformio platform install file://<zip or tarball file>
platformio platform install file://<folder>
platformio platform install <repository>
platformio platform install <name=repository> (name it should have locally)
platformio platform install <repository#tag> ("tag" can be commit, branch or tag)
Options
--with-package
Install specified package (or alias)
--without-package
Do not install specified package (or alias)
--skip-default
Skip default packages
--with-all-packages
Install all declared packages in platform.json
-f, --force
Reinstall/redownload development platform and its packages if they exist
Description
Install platforms and dependent packages.
The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of
the following forms:
• 1.2.3 - an exact version number. Use only this exact version
• ^1.2.3 - any compatible version (exact version for 1.x.x versions)
• ~1.2.3 - any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
Also, PlatformIO supports installing from local directory or archive. Need to use file://
prefix before local path. Also, directory or archive should contain platform.json
manifest.
• file:///local/path/to/the/platform/dir
• file:///local/path/to/the/platform.zip
• file:///local/path/to/the/platform.tar.gz
Version control
PlatformIO supports installing from Git, Mercurial and Subversion, and detects the type of
VCS using url prefixes: "git+", "hg+", or "svn+".
NOTE:
PlatformIO requires a working VCS command on your path: git, hg or svn.
Git
The supported schemes are: git, git+https and git+ssh. Here are the supported forms:
• platformio/platform-NAME (short version for GitHub repository)
• https://github.com/platformio/platform-NAME.git
• git+git://git.server.org/my-platform
• git+https://git.server.org/my-platform
• git+ssh://git.server.org/my-platform
• git+ssh://user@git.server.org/my-platform
• [user@]host.xz:path/to/repo.git
Passing branch names, a commit hash or a tag name is possible like so:
• https://github.com/platformio/platform-name.git#master
• git+git://git.server.org/my-platform#master
• git+https://git.server.org/my-platform#v1.0
• git+ssh://git.server.org/my-platform#7846d8ad52f983f2f2887bdc0f073fe9755a806d
Mercurial
The supported schemes are: hg+http, hg+https and hg+ssh. Here are the supported forms:
• hg+hg://hg.server.org/my-platform
• hg+https://hg.server.org/my-platform
• hg+ssh://hg.server.org/my-platform
Passing branch names, a commit hash or a tag name is possible like so:
• hg+hg://hg.server.org/my-platform#master
• hg+https://hg.server.org/my-platform#v1.0
• hg+ssh://hg.server.org/my-platform#4cfe2fa00668
Subversion
The supported schemes are: svn, svn+svn, svn+http, svn+https and svn+ssh. Here are the
supported forms:
• svn+svn://svn.server.org/my-platform
• svn+https://svn.server.org/my-platform
• svn+ssh://svn.server.org/my-platform
You can also give specific revisions to an SVN URL, like so:
• svn+svn://svn.server.org/my-platform#13
Examples
1. Install platform_atmelavr with default packages
> platformio platform install atmelavr
PlatformManager: Installing atmelavr
Downloading...
Unpacking [####################################] 100%
atmelavr @ 0.0.0 has been successfully installed!
PackageManager: Installing tool-scons @ >=2.3.0,<2.6.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
tool-scons @ 2.4.1 has been successfully installed!
PackageManager: Installing toolchain-atmelavr @ ~1.40801.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
toolchain-atmelavr @ 1.40801.0 has been successfully installed!
The platform 'atmelavr' has been successfully installed!
The rest of packages will be installed automatically depending on your build environment.
2. Install platform_atmelavr with uploader utility only and skip default packages
> platformio platform install atmelavr --skip-default-package --with-package=uploader
PlatformManager: Installing atmelavr
Downloading [####################################] 100%
Unpacking [####################################] 100%
atmelavr @ 0.0.0 has been successfully installed!
PackageManager: Installing tool-micronucleus @ ~1.200.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
tool-micronucleus @ 1.200.0 has been successfully installed!
PackageManager: Installing tool-avrdude @ ~1.60001.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
tool-avrdude @ 1.60001.1 has been successfully installed!
The platform 'atmelavr' has been successfully installed!
The rest of packages will be installed automatically depending on your build environment.
3. Install the latest development platform_atmelavr from Git repository
> platformio platform install https://github.com/platformio/platform-atmelavr.git
PlatformManager: Installing platform-atmelavr
git version 2.7.4 (Apple Git-66)
Cloning into '/Volumes/MEDIA/tmp/pio3_test_projects/arduino-digihead-master/home_dir/platforms/installing-U3ucN0-package'...
remote: Counting objects: 176, done.
remote: Compressing objects: 100% (55/55), done.
remote: Total 176 (delta 114), reused 164 (delta 109), pack-reused 0
Receiving objects: 100% (176/176), 38.86 KiB | 0 bytes/s, done.
Resolving deltas: 100% (114/114), done.
Checking connectivity... done.
Submodule 'examples/arduino-external-libs/lib/OneWire' (https://github.com/PaulStoffregen/OneWire.git) registered for path 'examples/arduino-external-libs/lib/OneWire'
Cloning into 'examples/arduino-external-libs/lib/OneWire'...
remote: Counting objects: 91, done.
remote: Total 91 (delta 0), reused 0 (delta 0), pack-reused 91
Unpacking objects: 100% (91/91), done.
Checking connectivity... done.
Submodule path 'examples/arduino-external-libs/lib/OneWire': checked out '57c18c6de80c13429275f70875c7c341f1719201'
atmelavr @ 0.0.0 has been successfully installed!
PackageManager: Installing tool-scons @ >=2.3.0,<2.6.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
tool-scons @ 2.4.1 has been successfully installed!
PackageManager: Installing toolchain-atmelavr @ ~1.40801.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
toolchain-atmelavr @ 1.40801.0 has been successfully installed!
The platform 'https://github.com/platformio/platform-atmelavr.git' has been successfully installed!
The rest of packages will be installed automatically depending on your build environment.
platformio platform list
Contents
• platformio platform list
• Usage
• Description
• Options
• Examples
Usage
platformio platform list [OPTIONS]
pio platform list [OPTIONS]
Description
List installed platforms
Options
--json-output
Return the output in JSON format.
Examples
> platformio platform list
atmelavr ~ Atmel AVR
====================
Atmel AVR 8- and 32-bit MCUs deliver a unique combination of performance, power efficiency and design flexibility. Optimized to speed time to market-and easily adapt to new ones-they are based on the industrys most code-efficient architecture for C and assembly programming.
Home: https://platformio.org/platforms/atmelavr
Packages: toolchain-atmelavr, framework-simba
Version: 0.0.0
atmelsam ~ Atmel SAM
====================
Atmel | SMART offers Flash- based ARM products based on the ARM Cortex-M0+, Cortex-M3 and Cortex-M4 architectures, ranging from 8KB to 2MB of Flash including a rich peripheral and feature mix.
Home: https://platformio.org/platforms/atmelsam
Packages: framework-arduinosam, framework-mbed, framework-simba, toolchain-gccarmnoneeabi, tool-bossac
Version: 0.0.0
espressif8266 ~ Espressif 8266
==============================
Espressif Systems is a privately held fabless semiconductor company. They provide wireless communications and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.
Home: https://platformio.org/platforms/espressif8266
Packages: framework-simba, tool-esptool, framework-arduinoespressif8266, sdk-esp8266, toolchain-xtensa
Version: 0.0.0
...
platformio platform search
Contents
• platformio platform search
• Usage
• Description
• Options
• Examples
Usage
platformio platform search QUERY [OPTIONS]
pio platform search QUERY [OPTIONS]
Description
Search for development platforms
Options
--json-output
Return the output in JSON format
Examples
1. Print all available development platforms
> platformio platform search
atmelavr ~ Atmel AVR
====================
Atmel AVR 8- and 32-bit MCUs deliver a unique combination of performance, power efficiency and design flexibility. Optimized to speed time to market-and easily adapt to new ones-they are based on the industrys most code-efficient architecture for C and assembly programming.
Home: https://platformio.org/platforms/atmelavr
Packages: toolchain-atmelavr, framework-arduinoavr, framework-simba, tool-avrdude, tool-micronucleus
atmelsam ~ Atmel SAM
====================
Atmel | SMART offers Flash- based ARM products based on the ARM Cortex-M0+, Cortex-M3 and Cortex-M4 architectures, ranging from 8KB to 2MB of Flash including a rich peripheral and feature mix.
Home: https://platformio.org/platforms/atmelsam
Packages: toolchain-gccarmnoneeabi, framework-arduinosam, framework-simba, tool-openocd, framework-mbed, tool-avrdude, tool-bossac
espressif32 ~ Espressif 32
==========================
Espressif Systems is a privately held fabless semiconductor company. They provide wireless communications and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.
Home: https://platformio.org/platforms/espressif32
Packages: toolchain-xtensa32, framework-simba, framework-arduinoespressif32, framework-pumbaa, framework-espidf, tool-esptoolpy
espressif8266 ~ Espressif 8266
==============================
Espressif Systems is a privately held fabless semiconductor company. They provide wireless communications and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.
Home: https://platformio.org/platforms/espressif8266
Packages: toolchain-xtensa, framework-simba, tool-esptool, tool-mkspiffs, tool-espotapy, framework-arduinoespressif8266, sdk-esp8266
freescalekinetis ~ Freescale Kinetis
====================================
Freescale Kinetis Microcontrollers is family of multiple hardware- and software-compatible ARM Cortex-M0+, Cortex-M4 and Cortex-M7-based MCU series. Kinetis MCUs offer exceptional low-power performance, scalability and feature integration.
...
2. Search for TI development platforms
> platformio platform search texas
timsp430 ~ TI MSP430
====================
MSP430 microcontrollers (MCUs) from Texas Instruments (TI) are 16-bit, RISC-based, mixed-signal processors designed for ultra-low power. These MCUs offer the lowest power consumption and the perfect mix of integrated peripherals for thousands of applications.
Home: https://platformio.org/platforms/timsp430
Packages: toolchain-timsp430, tool-mspdebug, framework-energiamsp430, framework-arduinomsp430
titiva ~ TI TIVA
================
Texas Instruments TM4C12x MCUs offer the industrys most popular ARM Cortex-M4 core with scalable memory and package options, unparalleled connectivity peripherals, advanced application functions, industry-leading analog integration, and extensive software solutions.
Home: https://platformio.org/platforms/titiva
Packages: ldscripts, framework-libopencm3, toolchain-gccarmnoneeabi, tool-lm4flash, framework-energiativa
> platformio platform search framework-mbed
atmelsam ~ Atmel SAM
====================
Atmel | SMART offers Flash- based ARM products based on the ARM Cortex-M0+, Cortex-M3 and Cortex-M4 architectures, ranging from 8KB to 2MB of Flash including a rich peripheral and feature mix.
Home: https://platformio.org/platforms/atmelsam
Packages: toolchain-gccarmnoneeabi, framework-arduinosam, framework-simba, tool-openocd, framework-mbed, ldscripts, tool-bossac
freescalekinetis ~ Freescale Kinetis
====================================
Freescale Kinetis Microcontrollers is family of multiple hardware- and software-compatible ARM Cortex-M0+, Cortex-M4 and Cortex-M7-based MCU series. Kinetis MCUs offer exceptional low-power performance, scalability and feature integration.
Home: https://platformio.org/platforms/freescalekinetis
Packages: framework-mbed, toolchain-gccarmnoneeabi
nordicnrf51 ~ Nordic nRF51
==========================
The Nordic nRF51 Series is a family of highly flexible, multi-protocol, system-on-chip (SoC) devices for ultra-low power wireless applications. nRF51 Series devices support a range of protocol stacks including Bluetooth Smart (previously called Bluetooth low energy), ANT and proprietary 2.4GHz protocols such as Gazell.
Home: https://platformio.org/platforms/nordicnrf51
Packages: framework-mbed, tool-rfdloader, toolchain-gccarmnoneeabi, framework-arduinonordicnrf51
nxplpc ~ NXP LPC
================
The NXP LPC is a family of 32-bit microcontroller integrated circuits by NXP Semiconductors. The LPC chips are grouped into related series that are based around the same 32-bit ARM processor core, such as the Cortex-M4F, Cortex-M3, Cortex-M0+, or Cortex-M0. Internally, each microcontroller consists of the processor core, static RAM memory, flash memory, debugging interface, and various peripherals.
Home: https://platformio.org/platforms/nxplpc
Packages: framework-mbed, toolchain-gccarmnoneeabi
siliconlabsefm32 ~ Silicon Labs EFM32
=====================================
Silicon Labs EFM32 Gecko 32-bit microcontroller (MCU) family includes devices that offer flash memory configurations up to 256 kB, 32 kB of RAM and CPU speeds up to 48 MHz. Based on the powerful ARM Cortex-M core, the Gecko family features innovative low energy techniques, short wake-up time from energy saving modes and a wide selection of peripherals, making it ideal for battery operated applications and other systems requiring high performance and low-energy consumption.
Home: https://platformio.org/platforms/siliconlabsefm32
Packages: framework-mbed, toolchain-gccarmnoneeabi
ststm32 ~ ST STM32
==================
The STM32 family of 32-bit Flash MCUs based on the ARM Cortex-M processor is designed to offer new degrees of freedom to MCU users. It offers a 32-bit product range that combines very high performance, real-time capabilities, digital signal processing, and low-power, low-voltage operation, while maintaining full integration and ease of development.
Home: https://platformio.org/platforms/ststm32
Packages: framework-libopencm3, toolchain-gccarmnoneeabi, tool-stlink, framework-spl, framework-cmsis, framework-mbed, ldscripts
teensy ~ Teensy
===============
Teensy is a complete USB-based microcontroller development system, in a very small footprint, capable of implementing many types of projects. All programming is done via the USB port. No special programmer is needed, only a standard USB cable and a PC or Macintosh with a USB port.
Home: https://platformio.org/platforms/teensy
Packages: framework-arduinoteensy, tool-teensy, toolchain-gccarmnoneeabi, framework-mbed, toolchain-atmelavr, ldscripts
...
platformio platform show
Contents
• platformio platform show
• Usage
• Description
• Examples
Usage
platformio platform show PLATFORM
pio platform show PLATFORM
Description
Show details about platforms
Examples
> platformio platform show atmelavr
atmelavr ~ Atmel AVR
====================
Atmel AVR 8- and 32-bit MCUs deliver a unique combination of performance, power efficiency and design flexibility. Optimized to speed time to market-and easily adapt to new ones-they are based on the industrys most code-efficient architecture for C and assembly programming.
Version: 1.2.1
Home: https://platformio.org/platforms/atmelavr
License: Apache-2.0
Frameworks: simba, arduino
Package toolchain-atmelavr
--------------------------
Type: toolchain
Requirements: ~1.40902.0
Installed: Yes
Description: avr-gcc
Url: http://www.atmel.com/products/microcontrollers/avr/32-bitavruc3.aspx?tab=tools
Version: 1.40902.0 (4.9.2)
Package framework-arduinoavr
----------------------------
Type: framework
Requirements: ~1.10612.1
Installed: Yes
Url: https://www.arduino.cc/en/Main/Software
Version: 1.10612.1 (1.6.12)
Description: Arduino Wiring-based Framework (AVR Core, 1.6)
Package framework-simba
-----------------------
Type: framework
Requirements: >=7.0.0
Installed: Yes
Url: https://github.com/eerimoq/simba
Version: 11.0.0
Description: Simba Embedded Programming Platform
Package tool-avrdude
--------------------
Type: uploader
Requirements: ~1.60300.0
Installed: Yes
Description: AVRDUDE
Url: http://www.nongnu.org/avrdude/
Version: 1.60300.0 (6.3.0)
Package tool-micronucleus
-------------------------
Type: uploader
Requirements: ~1.200.0
Installed: No (optional)
platformio platform uninstall
Contents
• platformio platform uninstall
• Usage
• Description
• Examples
Usage
platformio platform uninstall [PLATFORM...]
pio platform uninstall [PLATFORM...]
# uninstall specific platform version using Semantic Versioning
platformio platform uninstall PLATFORM@X.Y.Z
Description
Uninstall specified platforms
Examples
> platformio platform uninstall atmelavr
Uninstalling platform atmelavr @ 0.0.0: [OK]
Uninstalling package tool-scons @ 2.4.1: [OK]
Uninstalling package toolchain-atmelavr @ 1.40801.0: [OK]
The platform 'atmelavr' has been successfully uninstalled!
platformio platform update
Contents
• platformio platform update
• Usage
• Description
• Options
• Examples
Usage
platformio platform update [OPTIONS] [PLATFORM...]
pio platform update [OPTIONS] [PLATFORM...]
# update specific platform version using Semantic Versioning
platformio platform update PLATFORM@X.Y.Z
Description
Check or update installed platforms
Options
-p, --only-packages
Update only the platform related packages. Do not update development platform build
scripts, board configs and etc.
-c, --only-check
DEPRECATED. Please use --dry-run instead.
--dry-run
Do not update, only check for the new versions
--json-output
Return the output in JSON format
Examples
> platformio platform update
Platform atmelavr
--------
Updating atmelavr @ 0.0.0: [Up-to-date]
Updating framework-arduinoavr @ 1.10608.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform espressif8266
--------
Updating espressif @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-xtensa @ 1.40802.0: [Up-to-date]
Updating tool-esptool @ 1.409.0: [Up-to-date]
Updating tool-mkspiffs @ 1.102.0: [Up-to-date]
Updating framework-arduinoespressif8266 @ 1.20300.0: [Up-to-date]
Updating sdk-esp8266 @ 1.10502.0: [Up-to-date]
Platform teensy
--------
Updating teensy @ 0.0.0: [Up-to-date]
Updating framework-arduinoteensy @ 1.128.0: [Up-to-date]
Updating tool-teensy @ 1.1.0: [Up-to-date]
Updating framework-mbed @ 1.121.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
...
PlatformIO Remote CLI
Helper command for pioremote.
To print all available commands and options use:
pio remote --help
platformio remote --help
platformio remote COMMAND --help
# run command on the specified PIO Remote Agents
platformio remote --agent NAME_1 --agent NAME_N COMMAND
PIO Remote Agent
Start PIO Remote Agent on a host machine and work remotely with your devices WITHOUT extra
software, services, SSH, VPN, tunneling or opening incoming network ports.
pioremote supports wired and wireless devices. Wired devices should be connected
physically to host machine where PIO Remote Agent is started, where wireless devices
should be visible for PIO Remote Agent to provide network operations Over-The-Air (OTA).
Contents
• PIO Remote Agent
• platformio remote agent list
• Usage
• Description
• Example
• platformio remote agent start
• Usage
• Description
• Options
platformio remote agent list
Usage
platformio remote agent list
pio remote agent list
Description
List active PIO Remote Agent s started using own pioaccount or shared with you by other
PlatformIO developers.
Example
> platformio remote agent list
innomac.local
-------------
ID: 98853d930......788d77375e7
Started: 2016-10-26 16:32:56
----
platformio remote agent start
Usage
platformio remote agent start [OPTIONS]
pio remote agent start [OPTIONS]
Description
Start PIO Remote Agent and work remotely with your devices from anywhere in the world.
This command can be run as daemon or added to autostart list of your OS.
Options
-n, --name
Agent name/alias. By default, machine's hostname will be used. You can use this name
later for cmd_remote_device and cmd_remote_run commands. Good names are home, office, lab
or etc.
-s, --share
Share your agent/devices with other PlatformIO developers who have pioaccount: friends,
co-workers, team, etc.
The valid value for --share option is email address that was used for cmd_account_register
command.
-d, --working-dir
A working directory where PIO Remote Agent stores projects data for incremental
synchronization and embedded programs for PIO Process Supervisor.
platformio remote device
Remote Device: monitor remote device or list existing.
Contents
• platformio remote device
• platformio remote device list
• Usage
• Description
• Options
• Example
• platformio remote device monitor
• Usage
• Description
• Options
• Examples
platformio remote device list
Usage
platformio remote device list [OPTIONS]
pio remote device list [OPTIONS]
# List devices from the specified agents. Multiple agents are allowed.
platformio remote --agent NAME device list [OPTIONS]
Description
List Serial Ports on remote machines where cmd_remote_agent is started.
You can list devices from the specified remote machines using --agent NAME option between
"remote" & "device" sub-commands. For example, you have run platformio remote agent start
--name command with "home" and "office" options:
• platformio remote agent start --name home
• platformio remote agent start --name office
Now, to list devices from office machine please use platformio remote --agent office
device list.
Multiple agents are allowed ( platformio remote --agent lab1 --agent lab3 device ...).
Options
--json-output
Return the output in JSON format
Example
> platformio remote device list
Agent innomac.local
===================
/dev/cu.Bluetooth-Incoming-Port
-------------------------------
Hardware ID: n/a
Description: n/a
/dev/cu.obd2ecu-SPPDev
----------------------
Hardware ID: n/a
Description: n/a
/dev/cu.usbmodemFA1431
----------------------
Hardware ID: USB VID:PID=2A03:0043 SER=75435353038351015271 LOCATION=250-1.4.3
Description: Arduino Uno
/dev/cu.usbserial-A6004003
--------------------------
Hardware ID: USB VID:PID=0403:6001 SER=A6004003 LOCATION=253-1.3.1
Description: FT232R USB UART - FT232R USB UART
/dev/cu.SLAB_USBtoUART
----------------------
Hardware ID: USB VID:PID=10C4:EA60 SER=0001 LOCATION=253-1.3.2
Description: CP2102 USB to UART Bridge Controller - CP2102 USB to UART Bridge Controller
/dev/cu.usbmodem589561
----------------------
Hardware ID: USB VID:PID=16C0:0483 SER=589560 LOCATION=250-1.4.1
Description: USB Serial
platformio remote device monitor
Remote Serial Port Monitor
Usage
platformio remote device monitor [OPTIONS]
pio remote device monitor [OPTIONS]
# Connect to a specified agent
platformio remote --agent NAME device monitor [OPTIONS]
platformio remote -a NAME device monitor [OPTIONS]
Description
Connect to Serial Port of remote device and receive or send data in real time.
cmd_remote_agent should be started before on a remote machine.
To control monitor please use these "hot keys":
• Ctrl+C Quit
• Ctrl+T Menu
• Ctrl+T followed by Ctrl+H Help
Options
-p, --port
Port, a number or a device name
-b, --baud
Set baud rate, default 9600
--parity
Set parity (None, Even, Odd, Space, Mark), one of [N, E, O, S, M], default N
--rtscts
Enable RTS/CTS flow control, default Off
--xonxoff
Enable software flow control, default Off
--rts
Set initial RTS line state, default 0
--dtr
Set initial DTR line state, default 0
--echo
Enable local echo, default Off
--encoding
Set the encoding for the serial port (e.g. hexlify, Latin1, UTF-8), default UTF-8.
-f, --filter
Add text transformation. Available filters:
• colorize Apply different colors for received and echo
• debug Print what is sent and received
• default Remove typical terminal control codes from input
• direct Do-nothing: forward all data unchanged
• nocontrol Remove all control codes, incl. CR+LF
• printable Show decimal code for all non-ASCII characters and replace most control codes
--eol
End of line mode (CR, LF or CRLF), default CRLF
--raw
Do not apply any encodings/transformations
--exit-char
ASCII code of special character that is used to exit the application, default 3 (DEC,
Ctrl+C).
For example, to use Ctrl+] run platformio remote device monitor --exit-char 29.
--menu-char
ASCII code of special character that is used to control miniterm (menu), default 20 (DEC)
---quiet
Diagnostics: suppress non-error messages, default Off
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-e, --environment
Process specified environments.
You can also specify which environments should be processed by default using
projectconf_pio_default_envs option from projectconf.
Examples
1. Show available options for monitor
> platformio remote device monitor --help
Usage: platformio remote device monitor [OPTIONS]
Options:
-p, --port TEXT Port, a number or a device name
-b, --baud INTEGER Set baud rate, default=9600
--parity [N|E|O|S|M] Set parity, default=N
--rtscts Enable RTS/CTS flow control, default=Off
--xonxoff Enable software flow control, default=Off
--rts [0|1] Set initial RTS line state, default=0
--dtr [0|1] Set initial DTR line state, default=0
--echo Enable local echo, default=Off
--encoding TEXT Set the encoding for the serial port (e.g. hexlify,
Latin1, UTF-8), default: UTF-8
-f, --filter TEXT Add text transformation
--eol [CR|LF|CRLF] End of line mode, default=CRLF
--raw Do not apply any encodings/transformations
--exit-char INTEGER ASCII code of special character that is used to exit
the application, default=29 (DEC)
--menu-char INTEGER ASCII code of special character that is used to
control miniterm (menu), default=20 (DEC)
--quiet Diagnostics: suppress non-error messages, default=Off
-h, --help Show this message and exit.
2. Communicate with serial device and print help inside terminal
> platformio remote device monitor
--- Available ports:
--- /dev/cu.Bluetooth-Incoming-Port n/a
--- /dev/cu.Bluetooth-Modem n/a
--- /dev/cu.SLAB_USBtoUART CP2102 USB to UART Bridge Controller
--- /dev/cu.obd2ecu-SPPDev n/a
Enter port name:/dev/cu.SLAB_USBtoUART
--- Miniterm on /dev/cu.SLAB_USBtoUART: 9600,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
Hello PlatformIO!
---
--- Ctrl+] Exit program
--- Ctrl+T Menu escape key, followed by:
--- Menu keys:
--- Ctrl+T Send the menu character itself to remote
--- Ctrl+] Send the exit character itself to remote
--- Ctrl+I Show info
--- Ctrl+U Upload file (prompt will be shown)
--- Toggles:
--- Ctrl+R RTS Ctrl+E local echo
--- Ctrl+D DTR Ctrl+B BREAK
--- Ctrl+L line feed Ctrl+A Cycle repr mode
---
--- Port settings (Ctrl+T followed by the following):
--- p change port
--- 7 8 set data bits
--- n e o s m change parity (None, Even, Odd, Space, Mark)
--- 1 2 3 set stop bits (1, 2, 1.5)
--- b change baud rate
--- x X disable/enable software flow control
--- r R disable/enable hardware flow control
--- exit ---
platformio remote run
Remote Firmware Updates
Contents
• platformio remote run
• Usage
• Description
• Options
• Example
Usage
platformio remote run [OPTIONS]
pio remote run [OPTIONS]
# process environments using specified PIO Remote Agent
platformio remote --agent NAME run [OPTIONS]
Description
Process remotely environments which are defined in projectconf file. By default,
pioremote builds project on a host machine and deploy final firmware (program) to a remote
device (embedded board).
If you need to process project on a remote machine, please use platformio remote run
--force-remote option. In this case, pioremote will automatically synchronize your project
with remote machine, install required toolchains, frameworks, SDKs, etc., and process
project.
Options
-e, --environment
Process specified environments.
You can also specify which environments should be processed by default using
projectconf_pio_default_envs option from projectconf.
-t, --target
Process specified targets.
Built-in targets:
• clean delete compiled object files, libraries and firmware/program binaries
• upload firmware "auto-uploading" for embedded platforms
• program firmware "auto-uploading" for embedded platforms using external programmer
(available only for platform_atmelavr)
• buildfs platform_espressif_uploadfs
• uploadfs platform_espressif_uploadfs
• envdump dump current build environment
• size print the size of the sections in a firmware/program
--upload-port
Custom upload port of embedded board. To print all available ports use cmd_remote_device
command.
If upload port is not specified, PlatformIO will try to detect it automatically.
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
--disable-auto-clean
Disable auto-clean of projectconf_pio_build_dir when projectconf or
projectconf_pio_src_dir (project structure) have been modified.
-r, --force-remote
By default, pioremote builds project on a host machine and deploy final firmware (program)
to remote device (embedded board).
If you need to process project on remote machine, please use platformio remote run
--force-remote option. In this case, pioremote will automatically synchronize your project
with remote machine, install required toolchains, frameworks, SDKs, etc., and process
project.
Example
> platformio remote run --environment uno --target upload
Building project locally
[Wed Oct 26 16:35:09 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
--------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 25 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/uno/src/main.o
Archiving .pio/build/uno/libFrameworkArduinoVariant.a
Indexing .pio/build/uno/libFrameworkArduinoVariant.a
Compiling .pio/build/uno/FrameworkArduino/CDC.o
Compiling .pio/build/uno/FrameworkArduino/HardwareSerial.o
Compiling .pio/build/uno/FrameworkArduino/HardwareSerial0.o
Compiling .pio/build/uno/FrameworkArduino/HardwareSerial1.o
Compiling .pio/build/uno/FrameworkArduino/HardwareSerial2.o
Compiling .pio/build/uno/FrameworkArduino/HardwareSerial3.o
Compiling .pio/build/uno/FrameworkArduino/IPAddress.o
Compiling .pio/build/uno/FrameworkArduino/PluggableUSB.o
Compiling .pio/build/uno/FrameworkArduino/Print.o
Compiling .pio/build/uno/FrameworkArduino/Stream.o
Compiling .pio/build/uno/FrameworkArduino/Tone.o
Compiling .pio/build/uno/FrameworkArduino/USBCore.o
Compiling .pio/build/uno/FrameworkArduino/WInterrupts.o
Compiling .pio/build/uno/FrameworkArduino/WMath.o
Compiling .pio/build/uno/FrameworkArduino/WString.o
Compiling .pio/build/uno/FrameworkArduino/_wiring_pulse.o
Compiling .pio/build/uno/FrameworkArduino/abi.o
Compiling .pio/build/uno/FrameworkArduino/hooks.o
Compiling .pio/build/uno/FrameworkArduino/main.o
Compiling .pio/build/uno/FrameworkArduino/new.o
Compiling .pio/build/uno/FrameworkArduino/wiring.o
Compiling .pio/build/uno/FrameworkArduino/wiring_analog.o
Compiling .pio/build/uno/FrameworkArduino/wiring_digital.o
Compiling .pio/build/uno/FrameworkArduino/wiring_pulse.o
Compiling .pio/build/uno/FrameworkArduino/wiring_shift.o
Archiving .pio/build/uno/libFrameworkArduino.a
Indexing .pio/build/uno/libFrameworkArduino.a
Linking .pio/build/uno/firmware.elf
Checking program size
Building .pio/build/uno/firmware.hex
text data bss dec hex filename
2574 48 168 2790 ae6 .pio/build/uno/firmware.elf
========================= [SUCCESS] Took 10.01 seconds =======================
================================== [SUMMARY] =================================
Environment nodemcuv2 [SKIP]
Environment uno_pic32 [SKIP]
Environment teensy31 [SKIP]
Environment uno [SUCCESS]
========================= [SUCCESS] Took 10.01 seconds ========================
Uploading firmware remotely
[Wed Oct 26 19:35:20 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Looking for upload port...
Auto-detected: /dev/cu.usbmodemFA1431
Uploading .pio/build/uno/firmware.hex
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e950f
avrdude: reading input file ".pio/build/uno/firmware.hex"
avrdude: writing flash (2622 bytes):
Writing | ################################################## | 100% 0.43s
avrdude: 2622 bytes of flash written
avrdude: verifying flash memory against .pio/build/uno/firmware.hex:
avrdude: load data flash data from input file .pio/build/uno/firmware.hex:
avrdude: input file .pio/build/uno/firmware.hex contains 2622 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 0.34s
avrdude: verifying ...
avrdude: 2622 bytes of flash verified
avrdude done. Thank you.
========================= [SUCCESS] Took 3.04 seconds =======================
========================= [SUMMARY] =========================================
Environment nodemcuv2 [SKIP]
Environment uno_pic32 [SKIP]
Environment teensy31 [SKIP]
Environment uno [SUCCESS]
========================= [SUCCESS] Took 3.04 seconds ========================
platformio remote test
Helper command for remote unit_testing.
Contents
• platformio remote test
• Usage
• Description
• Options
• Examples
Usage
platformio remote test [OPTIONS]
pio remote test [OPTIONS]
# run tests on specified PIO Remote Agent
platformio remote --agent NAME test [OPTIONS]
Description
Run remotely tests from PlatformIO based project. More details about PlatformIO
unit_testing.
This command allows you to apply the tests for the environments specified in projectconf.
Options
-e, --environment
Process specified environments. More details platformio run --environment
-i, --ignore
Ignore tests where the name matches specified patterns. More than one pattern is allowed.
If you need to ignore some tests for the specific environment, please take a look at
projectconf_test_ignore option from projectconf.
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
└────────┴──────────────────────────────────┘
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
For example, platformio remote test --ignore "mytest*" -i "test[13]"
--upload-port
A port that is intended for firmware uploading. To list available ports please use
cmd_device_list command.
If upload port is not specified, PlatformIO will try to detect it automatically.
--test-port
A Serial/UART port that PlatformIO uses as communication interface between PlatformIO Unit
Test Engine and target device. To list available ports please use cmd_device_list command.
If test port is not specified, PlatformIO will try to detect it automatically.
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-r, --force-remote
By default, pioremote processes project on a host machine and deploy final testing
firmware (program) to remote device (embedded board).
If you need to process project on remote machine, please use platformio remote test
--force-remote option. In this case, pioremote will automatically synchronize your project
with remote machine, install required toolchains, frameworks, SDKs, etc., and process
project.
--without-building
Skip building stage.
--without-uploading
Skip uploading stage
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
Examples
For the examples please follow to unit_testing page.
platformio remote update
Contents
• platformio remote update
• Usage
• Description
• Options
• Examples
Usage
platformio remote update [OPTIONS]
pio remote update [OPTIONS]
# start update process on the specified agents/machines
platformio remote --agent NAME update [OPTIONS]
Description
Check or update installed platforms and global Libraries on the remote machine.
Options
-c, --only-check
DEPRECATED. Please use --dry-run instead.
--dry-run
Do not update, only check for the new versions
Examples
> platformio remote update
Platform Manager
================
Platform timsp430
--------
Updating timsp430 @ 0.0.0: [Up-to-date]
Updating toolchain-timsp430 @ 1.40603.0: [Up-to-date]
Updating framework-energiamsp430 @ 1.17.0: [Up-to-date]
Updating framework-arduinomsp430 @ 1.10601.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform freescalekinetis
--------
Updating freescalekinetis @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform ststm32
--------
Updating ststm32 @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-stlink @ 1.10200.0: [Up-to-date]
Updating framework-spl @ 1.10201.0: [Up-to-date]
Updating framework-cmsis @ 1.40300.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform lattice_ice40
--------
Updating lattice_ice40 @ 0.0.0: [Up-to-date]
Updating toolchain-icestorm @ 1.7.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelavr
--------
Updating atmelavr @ 0.0.0: [Up-to-date]
Updating framework-arduinoavr @ 1.10608.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform espressif8266
--------
Updating espressif8266 @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-xtensa @ 1.40802.0: [Up-to-date]
Updating tool-esptool @ 1.409.0: [Up-to-date]
Updating tool-mkspiffs @ 1.102.0: [Up-to-date]
Updating framework-arduinoespressif8266 @ 1.20300.0: [Up-to-date]
Updating sdk-esp8266 @ 1.10502.0: [Up-to-date]
Platform linux_x86_64
--------
Updating linux_x86_64 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux64 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform windows_x86
--------
Updating windows_x86 @ 0.0.0: [Up-to-date]
Updating toolchain-gccmingw32 @ 1.40800.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform teensy
--------
Updating teensy @ 0.0.0: [Up-to-date]
Updating framework-arduinoteensy @ 1.128.0: [Up-to-date]
Updating tool-teensy @ 1.1.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Platform nordicnrf51
--------
Updating nordicnrf51 @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-arduinonordicnrf51 @ 1.20302.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform titiva
--------
Updating titiva @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-energiativa @ 1.17.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelsam
--------
Updating atmelsam @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-openocd @ 1.900.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating tool-bossac @ 1.10601.0: [Up-to-date]
Platform siliconlabsefm32
--------
Updating siliconlabsefm32 @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform microchippic32
--------
Updating microchippic32 @ 0.0.0: [Up-to-date]
Updating framework-arduinomicrochippic32 @ 1.10201.0: [Up-to-date]
Updating toolchain-microchippic32 @ 1.40803.0: [Up-to-date]
Updating tool-pic32prog @ 1.200200.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_i686
--------
Updating linux_i686 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux32 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform intel_arc32
--------
Updating intel_arc32 @ 0.0.0: [Up-to-date]
Updating framework-arduinointel @ 1.10006.0: [Up-to-date]
Updating tool-arduino101load @ 1.124.0: [Up-to-date]
Updating toolchain-intelarc32 @ 1.40805.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform nxplpc
--------
Updating nxplpc @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_arm
--------
Updating linux_arm @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmlinuxgnueabi @ 1.40802.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform native
--------
Updating native @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Library Manager
===============
Updating Adafruit-GFX @ 334e815bc1: [Up-to-date]
Updating Adafruit-ST7735 @ d53d4bf03a: [Up-to-date]
Updating Adafruit-DHT @ 09344416d2: [Up-to-date]
Updating Adafruit-Unified-Sensor @ f2af6f4efc: [Up-to-date]
Updating ESP8266_SSD1306 @ 3.2.3: [Up-to-date]
Updating EngduinoMagnetometer @ 3.1.0: [Up-to-date]
Updating IRremote @ 2.2.1: [Up-to-date]
Updating Json @ 5.6.4: [Up-to-date]
Updating MODSERIAL @ d8422efe47: [Up-to-date]
Updating PJON @ 1fb26fd: [Checking]
git version 2.7.4 (Apple Git-66)
Already up-to-date.
Updating Servo @ 36b69a7ced07: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/Servo/
searching for changes
no changes found
Updating TextLCD @ 308d188a2d3a: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/TextLCD/
searching for changes
no changes found
platformio run
Contents
• platformio run
• Usage
• Description
• Options
• Examples
Usage
platformio run [OPTIONS]
pio run [OPTIONS]
Description
Process environments which are defined in projectconf file
Options
-e, --environment
Process specified environments.
You can also specify which environments should be processed by default using
projectconf_pio_default_envs option from projectconf.
-t, --target
Process specified targets.
NOTE:
You can configure default targets per project environment using projectconf_targets
option in projectconf.
Built-in targets:
• Processing
• clean delete compiled object files, libraries and firmware/program binaries
• upload firmware "auto-uploading" for embedded platforms
• debug build using Debug Configuration
• program firmware "auto-uploading" for embedded platforms using external programmer
(available only for platform_atmelavr)
• fuses set fuse bits (available only for platform_atmelavr)
• buildfs platform_espressif_uploadfs
• uploadfs platform_espressif_uploadfs
• size print the size of the sections in a firmware/program
• checkprogsize check maximum allowed firmware size for uploading
• erase erase device flash (not available on the all platforms)
• compiledb build compilation_db
• Device
• monitor automatically start cmd_device_monitor after success build operation. You
can configure monitor using projectconf_section_env_monitor.
• Service
• envdump dump current build environment
• idedata export build environment for IDE (defines, build flags, CPPPATH, etc.)
--upload-port
Custom upload port of embedded board. To print all available ports use cmd_device_list
command.
If upload port is not specified, PlatformIO will try to detect it automatically.
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-c, --project-conf
New in version 4.0.
Process project with a custom projectconf.
-j, --jobs
New in version 4.0.
Control a number of parallel build jobs. Default is a number of CPUs in a system.
-s, --silent
Suppress progress reporting
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
--disable-auto-clean
Disable auto-clean of projectconf_pio_build_dir when projectconf or
projectconf_pio_src_dir (project structure) have been modified.
Examples
1. Process Wiring Blink Example
> platformio run
[Wed Sep 7 15:48:58 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 36 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/uno/src/main.o
Archiving .pio/build/uno/libFrameworkArduinoVariant.a
Indexing .pio/build/uno/libFrameworkArduinoVariant.a
Compiling .pio/build/uno/FrameworkArduino/CDC.o
...
Compiling .pio/build/uno/FrameworkArduino/wiring_shift.o
Archiving .pio/build/uno/libFrameworkArduino.a
Indexing .pio/build/uno/libFrameworkArduino.a
Linking .pio/build/uno/firmware.elf
Building .pio/build/uno/firmware.hex
Calculating size .pio/build/uno/firmware.elf
AVR Memory Usage
----------------
Device: atmega328p
Program: 1034 bytes (3.2% Full)
(.text + .data + .bootloader)
Data: 9 bytes (0.4% Full)
(.data + .bss + .noinit)
=========================== [SUCCESS] Took 2.47 seconds ===========================
[Wed Sep 7 15:49:01 2016] Processing nodemcu (platform: espressif8266, board: nodemcu, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 34 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/nodemcu/src/main.o
Archiving .pio/build/nodemcu/libFrameworkArduinoVariant.a
Indexing .pio/build/nodemcu/libFrameworkArduinoVariant.a
Compiling .pio/build/nodemcu/FrameworkArduino/Esp.o
Compiling .pio/build/nodemcu/FrameworkArduino/FS.o
Compiling .pio/build/nodemcu/FrameworkArduino/HardwareSerial.o
...
Archiving .pio/build/nodemcu/libFrameworkArduino.a
Indexing .pio/build/nodemcu/libFrameworkArduino.a
Linking .pio/build/nodemcu/firmware.elf
Calculating size .pio/build/nodemcu/firmware.elf
text data bss dec hex filename
221240 888 29400 251528 3d688 .pio/build/nodemcu/firmware.elf
Building .pio/build/nodemcu/firmware.bin
=========================== [SUCCESS] Took 6.43 seconds ===========================
[Wed Sep 7 15:49:07 2016] Processing teensy31 (platform: teensy, board: teensy31, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 96 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/teensy31/src/main.o
Compiling .pio/build/teensy31/FrameworkArduino/AudioStream.o
Compiling .pio/build/teensy31/FrameworkArduino/DMAChannel.o
...
Compiling .pio/build/teensy31/FrameworkArduino/yield.o
Archiving .pio/build/teensy31/libFrameworkArduino.a
Indexing .pio/build/teensy31/libFrameworkArduino.a
Linking .pio/build/teensy31/firmware.elf
Calculating size .pio/build/teensy31/firmware.elf
text data bss dec hex filename
11288 168 2288 13744 35b0 .pio/build/teensy31/firmware.elf
Building .pio/build/teensy31/firmware.hex
=========================== [SUCCESS] Took 5.36 seconds ===========================
[Wed Sep 7 15:49:12 2016] Processing lpmsp430g2553 (platform: timsp430, build_flags: -D LED_BUILTIN=RED_LED, board: lpmsp430g2553, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 29 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/lpmsp430g2553/src/main.o
Compiling .pio/build/lpmsp430g2553/FrameworkAnergia/HardwareSerial.o
Compiling .pio/build/lpmsp430g2553/FrameworkAnergia/IPAddress.o
...
Compiling .pio/build/lpmsp430g2553/FrameworkAnergia/wiring_digital.o
Compiling .pio/build/lpmsp430g2553/FrameworkAnergia/wiring_pulse.o
Compiling .pio/build/lpmsp430g2553/FrameworkAnergia/wiring_shift.o
Archiving .pio/build/lpmsp430g2553/libFrameworkAnergia.a
Indexing .pio/build/lpmsp430g2553/libFrameworkAnergia.a
Linking .pio/build/lpmsp430g2553/firmware.elf
Calculating size .pio/build/lpmsp430g2553/firmware.elf
text data bss dec hex filename
820 0 20 840 348 .pio/build/lpmsp430g2553/firmware.elf
Building .pio/build/lpmsp430g2553/firmware.hex
=========================== [SUCCESS] Took 2.34 seconds ===========================
2. Process specific environment
> platformio run -e nodemcu -e teensy31
[Wed Sep 7 15:49:01 2016] Processing nodemcu (platform: espressif8266, board: nodemcu, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 34 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/nodemcu/src/main.o
Archiving .pio/build/nodemcu/libFrameworkArduinoVariant.a
Indexing .pio/build/nodemcu/libFrameworkArduinoVariant.a
Compiling .pio/build/nodemcu/FrameworkArduino/Esp.o
Compiling .pio/build/nodemcu/FrameworkArduino/FS.o
Compiling .pio/build/nodemcu/FrameworkArduino/HardwareSerial.o
...
Archiving .pio/build/nodemcu/libFrameworkArduino.a
Indexing .pio/build/nodemcu/libFrameworkArduino.a
Linking .pio/build/nodemcu/firmware.elf
Calculating size .pio/build/nodemcu/firmware.elf
text data bss dec hex filename
221240 888 29400 251528 3d688 .pio/build/nodemcu/firmware.elf
Building .pio/build/nodemcu/firmware.bin
=========================== [SUCCESS] Took 6.43 seconds ===========================
[Wed Sep 7 15:49:07 2016] Processing teensy31 (platform: teensy, board: teensy31, framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 96 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/teensy31/src/main.o
Compiling .pio/build/teensy31/FrameworkArduino/AudioStream.o
Compiling .pio/build/teensy31/FrameworkArduino/DMAChannel.o
...
Compiling .pio/build/teensy31/FrameworkArduino/yield.o
Archiving .pio/build/teensy31/libFrameworkArduino.a
Indexing .pio/build/teensy31/libFrameworkArduino.a
Linking .pio/build/teensy31/firmware.elf
Calculating size .pio/build/teensy31/firmware.elf
text data bss dec hex filename
11288 168 2288 13744 35b0 .pio/build/teensy31/firmware.elf
Building .pio/build/teensy31/firmware.hex
=========================== [SUCCESS] Took 5.36 seconds ===========================
3. Process specific target (clean project)
> platformio run -t clean
[Wed Sep 7 15:53:26 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
-----------------------------------------------------------------------------------------------------
Removed .pio/build/uno/firmware.elf
Removed .pio/build/uno/firmware.hex
Removed .pio/build/uno/libFrameworkArduino.a
Removed .pio/build/uno/libFrameworkArduinoVariant.a
Removed .pio/build/uno/FrameworkArduino/_wiring_pulse.o
Removed .pio/build/uno/FrameworkArduino/abi.o
Removed .pio/build/uno/FrameworkArduino/CDC.o
Removed .pio/build/uno/FrameworkArduino/HardwareSerial.o
Removed .pio/build/uno/FrameworkArduino/HardwareSerial0.o
Removed .pio/build/uno/FrameworkArduino/HardwareSerial1.o
Removed .pio/build/uno/FrameworkArduino/HardwareSerial2.o
Removed .pio/build/uno/FrameworkArduino/HardwareSerial3.o
Removed .pio/build/uno/FrameworkArduino/hooks.o
Removed .pio/build/uno/FrameworkArduino/IPAddress.o
Removed .pio/build/uno/FrameworkArduino/main.o
Removed .pio/build/uno/FrameworkArduino/new.o
Removed .pio/build/uno/FrameworkArduino/PluggableUSB.o
Removed .pio/build/uno/FrameworkArduino/Print.o
Removed .pio/build/uno/FrameworkArduino/Stream.o
Removed .pio/build/uno/FrameworkArduino/Tone.o
Removed .pio/build/uno/FrameworkArduino/USBCore.o
Removed .pio/build/uno/FrameworkArduino/WInterrupts.o
Removed .pio/build/uno/FrameworkArduino/wiring.o
Removed .pio/build/uno/FrameworkArduino/wiring_analog.o
Removed .pio/build/uno/FrameworkArduino/wiring_digital.o
Removed .pio/build/uno/FrameworkArduino/wiring_pulse.o
Removed .pio/build/uno/FrameworkArduino/wiring_shift.o
Removed .pio/build/uno/FrameworkArduino/WMath.o
Removed .pio/build/uno/FrameworkArduino/WString.o
Removed .pio/build/uno/src/main.o
Done cleaning
======================= [SUCCESS] Took 0.49 seconds =======================
[Wed Sep 7 15:53:27 2016] Processing nodemcu (platform: espressif8266, board: nodemcu, framework: arduino)
-----------------------------------------------------------------------------------------------------
Removed .pio/build/nodemcu/firmware.bin
Removed .pio/build/nodemcu/firmware.elf
Removed .pio/build/nodemcu/libFrameworkArduino.a
Removed .pio/build/nodemcu/libFrameworkArduinoVariant.a
...
Removed .pio/build/nodemcu/FrameworkArduino/spiffs/spiffs_nucleus.o
Removed .pio/build/nodemcu/FrameworkArduino/umm_malloc/umm_malloc.o
Removed .pio/build/nodemcu/src/main.o
Done cleaning
======================= [SUCCESS] Took 0.50 seconds =======================
[Wed Sep 7 15:53:27 2016] Processing teensy31 (platform: teensy, board: teensy31, framework: arduino)
-----------------------------------------------------------------------------------------------------
Removed .pio/build/teensy31/firmware.elf
Removed .pio/build/teensy31/firmware.hex
Removed .pio/build/teensy31/libFrameworkArduino.a
Removed .pio/build/teensy31/FrameworkArduino/analog.o
Removed .pio/build/teensy31/FrameworkArduino/AudioStream.o
...
Removed .pio/build/teensy31/FrameworkArduino/WString.o
Removed .pio/build/teensy31/FrameworkArduino/yield.o
Removed .pio/build/teensy31/src/main.o
Done cleaning
======================= [SUCCESS] Took 0.50 seconds =======================
[Wed Sep 7 15:53:28 2016] Processing lpmsp430g2553 (platform: timsp430, build_flags: -D LED_BUILTIN=RED_LED, board: lpmsp430g2553, framework: energia)
-----------------------------------------------------------------------------------------------------
Removed .pio/build/lpmsp430g2553/firmware.elf
Removed .pio/build/lpmsp430g2553/firmware.hex
Removed .pio/build/lpmsp430g2553/libFrameworkAnergia.a
Removed .pio/build/lpmsp430g2553/FrameworkAnergia/atof.o
...
Removed .pio/build/lpmsp430g2553/FrameworkAnergia/avr/dtostrf.o
Removed .pio/build/lpmsp430g2553/src/main.o
Done cleaning
======================= [SUCCESS] Took 0.49 seconds =======================
4. Mix environments and targets
> platformio run -e uno -t upload
[Wed Sep 7 15:55:11 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
--------------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 36 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/uno/src/main.o
Archiving .pio/build/uno/libFrameworkArduinoVariant.a
Indexing .pio/build/uno/libFrameworkArduinoVariant.a
Compiling .pio/build/uno/FrameworkArduino/CDC.o
...
Compiling .pio/build/uno/FrameworkArduino/wiring_shift.o
Archiving .pio/build/uno/libFrameworkArduino.a
Indexing .pio/build/uno/libFrameworkArduino.a
Linking .pio/build/uno/firmware.elf
Checking program size .pio/build/uno/firmware.elf
text data bss dec hex filename
1034 0 9 1043 413 .pio/build/uno/firmware.elf
Building .pio/build/uno/firmware.hex
Looking for upload port...
Auto-detected: /dev/cu.usbmodemFA141
Uploading .pio/build/uno/firmware.hex
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.01s
avrdude: Device signature = 0x1e950f
avrdude: reading input file ".pio/build/uno/firmware.hex"
avrdude: writing flash (1034 bytes):
Writing | ################################################## | 100% 0.18s
avrdude: 1034 bytes of flash written
avrdude: verifying flash memory against .pio/build/uno/firmware.hex:
avrdude: load data flash data from input file .pio/build/uno/firmware.hex:
avrdude: input file .pio/build/uno/firmware.hex contains 1034 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 0.15s
avrdude: verifying ...
avrdude: 1034 bytes of flash verified
avrdude: safemode: Fuses OK (H:00, E:00, L:00)
avrdude done. Thank you.
======================== [SUCCESS] Took 4.14 seconds ========================
platformio settings
Manage PlatformIO settings
Contents
• platformio settings
• platformio settings get
• Usage
• Description
• Settings
• auto_update_libraries
• auto_update_platforms
• check_libraries_interval
• check_platformio_interval
• check_platforms_interval
• enable_cache
• strict_ssl
• enable_telemetry
• force_verbose
• projects_dir
• Examples
• platformio settings set
• Usage
• Description
• Examples
• platformio settings reset
• Usage
• Description
• Examples
platformio settings get
Usage
platformio settings get [NAME]
pio settings get [NAME]
Description
NOTE:
• The Yes value is equal to: True, Y, 1 and is not case sensitive.
• You can override these settings using envvars.
Get/List existing settings
Settings
auto_update_libraries
Default
No
Values Yes/No
Automatically update libraries.
auto_update_platforms
Default
No
Values Yes/No
Automatically update platforms.
check_libraries_interval
Default
7
Values Days (Number)
Check for the library updates interval.
check_platformio_interval
Default
3
Values Days (Number)
Check for the new PlatformIO interval.
check_platforms_interval
Default
7
Values Days (Number)
Check for the platform updates interval.
enable_cache
Default
Yes
Values Yes/No
Enable caching for API requests and Library Manager
strict_ssl
Default
No
Values Yes/No
Strict SSL for PlatformIO Services
enable_telemetry
Default
Yes
Values Yes/No
Share minimal diagnostics and usage information to help us make PlatformIO better.
The source code of telemetry service is open source. You can make sure that we DO NOT
SHARE PRIVATE information or source code of your project. All information shares
ANONYMOUSLY.
Which data do we collect and why?
• A version of Python Interpreter. piocore is written in Python language, including
development platforms. We need to know which Python version produces such type of
exceptions (see below), which is more popular, which version we should drop and focus on
a new one
• piocore errors/exceptions. We report automatically fatal exceptions raised by PlatformIO
Core source code but NOT by your project
• The name of the used platform, board, framework. We collect this type of information to
have a clear picture which software products are the most widely used by our Community
and for the which we should provide frequent updates and add new features ( for example,
"atmelavr", "arduino", "uno", etc.)
• The name of CLI command. It helps us to improve our CLI. For example, "run", "lib list")
• The name of ide. This is very important information for us. We create native extensions
based on the popularity of IDEs (for example, ide_vscode, ide_clion)
Thanks a lot that you keep this setting enabled!
force_verbose
Default
No
Values Yes/No
Force verbose output when processing environments. This setting overrides
• platformio run --verbose
• platformio ci --verbose
• platformio test --verbose
projects_dir
Default
~/Documents/PlatformIO/Projects
Values Path to folder
Default location for PlatformIO projects (PIO Home)
Examples
1. List all settings and theirs current values
> platformio settings get
Name Value [Default] Description
------------------------------------------------------------------------------------------
auto_update_libraries No Automatically update libraries (Yes/No)
auto_update_platforms No Automatically update platforms (Yes/No)
check_libraries_interval 7 Check for the library updates interval (days)
check_platformio_interval 3 Check for the new PlatformIO interval (days)
check_platforms_interval 7 Check for the platform updates interval (days)
enable_cache Yes Enable caching for API requests and Library Manager
strict_ssl No Strict SSL for PlatformIO Services
enable_telemetry Yes Telemetry service?#enable-telemetry> (Yes/No)
force_verbose No Force verbose output when processing environments
projects_dir ~/Documents/PlatformIO/Projects Default location for PlatformIO projects (PIO Home)
2. Show specified setting
$ platformio settings get auto_update_platforms
Name Value [Default] Description
------------------------------------------------------------------------------------------
auto_update_platforms Yes Automatically update platforms (Yes/No)
platformio settings set
Usage
platformio settings set NAME VALUE
Description
Set new value for the setting
Examples
Change to check for the new PlatformIO each day
$ platformio settings set check_platformio_interval 1
The new value for the setting has been set!
Name Value [Default] Description
------------------------------------------------------------------------------------------
check_platformio_interval 1 [3] Check for the new PlatformIO interval (days)
platformio settings reset
Usage
platformio settings reset
Description
Reset settings to default
Examples
$ platformio settings reset
The settings have been reset!
Name Value [Default] Description
------------------------------------------------------------------------------------------
auto_update_libraries No Automatically update libraries (Yes/No)
auto_update_platforms No Automatically update platforms (Yes/No)
check_libraries_interval 7 Check for the library updates interval (days)
check_platformio_interval 3 Check for the new PlatformIO interval (days)
check_platforms_interval 7 Check for the platform updates interval (days)
enable_cache Yes Enable caching for API requests and Library Manager
strict_ssl No Enable SSL for PlatformIO Services
enable_telemetry Yes Telemetry service?#enable-telemetry> (Yes/No)
force_verbose No Force verbose output when processing environments
projects_dir ~/Documents/PlatformIO/Projects Default location for PlatformIO projects (PIO Home)
platformio system
Miscellaneous system commands.
To print all available commands and options use:
platformio system --help
platformio system COMMAND --help
pio system --help
PlatformIO Shell Completion
Shell completion support for
• Fish
• Zsh
• Bash
• PowerShell
To print all available commands and options use:
platformio misc completion --help
platformio misc completion COMMAND --help
pio misc completion --help
platformio misc completion install
Contents
• platformio misc completion install
• Usage
• Description
• Options
• Examples
Usage
platformio misc completion install [OPTIONS]
pio misc completion install [OPTIONS]
Description
Install shell completion files or code.
Options
--shell
The shell type, default is auto and will be detected from a current shell session.
Supported shells are:
• fish
• zsh
• bash
• powershell
--path
Custom installation path of the code to be evaluated by the shell. The standard
installation path is used by default.
Examples
> pio misc completion install
PlatformIO CLI completion has been installed for fish shell to ~/.config/fish/completions/pio.fish
Please restart a current shell session
platformio misc completion uninstall
Contents
• platformio misc completion uninstall
• Usage
• Description
• Options
• Examples
Usage
platformio misc completion uninstall [OPTIONS]
pio misc completion uninstall [OPTIONS]
Description
Uninstall shell completion files or code.
Options
--shell
The shell type, default is auto and will be detected from a current shell session.
Supported shells are:
• fish
• zsh
• bash
• powershell
--path
Custom installation path of the code to be evaluated by the shell. The standard
installation path is used by default.
Examples
> pio misc completion uninstall
PlatformIO CLI completion has been uninstalled for fish shell from ~/.config/fish/completions/pio.fish
Please restart a current shell session.
platformio test
Helper command for local unit_testing.
Contents
• platformio test
• Usage
• Description
• Options
• Examples
Usage
platformio test [OPTIONS]
pio test [OPTIONS]
Description
Run locally tests from PlatformIO based project. More details about PlatformIO
unit_testing.
This command allows you to apply the tests for the environments specified in projectconf.
Options
-e, --environment
Process specified environments. More details platformio run --environment
-f, --filter
Process only the tests where the name matches specified patterns. More than one pattern is
allowed. If you need to filter some tests for a specific environment, please take a look
at projectconf_test_filter option from projectconf.
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
For example, platformio test --filter "mytest*" -i "test[13]"
-i, --ignore
Ignore tests where the name matches specified patterns. More than one pattern is allowed.
If you need to ignore some tests for a specific environment, please take a look at
projectconf_test_ignore option from projectconf.
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
For example, platformio test --ignore "mytest*" -i "test[13]"
--upload-port
A port that is intended for firmware uploading. To list available ports please use
cmd_device_list command.
If upload port is not specified, PlatformIO will try to detect it automatically.
--test-port
A Serial/UART port that PlatformIO uses as communication interface between PlatformIO Unit
Test Engine and target device. To list available ports please use cmd_device_list command.
If test port is not specified, PlatformIO will try to detect it automatically.
-d, --project-dir
Specify the path to project directory. By default, --project-dir is equal to current
working directory (CWD).
-c, --project-conf
New in version 4.0.
Process project with a custom projectconf.
--without-building
Skip building stage.
--without-uploading
Skip uploading stage
--no-reset
Disable software reset via Serial.DTR/RST before test running. In this case, need to press
"reset" button manually after firmware uploading.
WARNING:
If board does not support software reset via Serial.DTR/RTS you should add >2 seconds
delay before UNITY_BEGIN()`. We need that time to establish a ``Serial communication
between host machine and target device. See unit_testing.
--monitor-rts
Set initial RTS line state for Serial Monitor (0 or 1), default 1. We use it to gather
test results via Serial connection.
--monitor-dtr
Set initial DTR line state for Serial Monitor (0 or 1), default 1. We use it to gather
test results via Serial connection.
-v, --verbose
Shows detailed information when processing environments.
This option can also be set globally using setting_force_verbose setting or by environment
variable PLATFORMIO_SETTING_FORCE_VERBOSE.
Examples
For the examples please follow to unit_testing page.
platformio update
Contents
• platformio update
• Usage
• Description
• Options
• Examples
Usage
platformio update [OPTIONS]
pio update [OPTIONS]
Description
Check or update installed PIO Core packages, platforms and global Libraries. This command
is combination of 2 sub-commands:
• cmd_platform_update
• cmd_lib_update
Options
--core-packages
Update only the core packages
-c, --only-check
DEPRECATED. Please use --dry-run instead.
--dry-run
Do not update, only check for the new versions
Examples
> platformio update
Platform Manager
================
Platform timsp430
--------
Updating timsp430 @ 0.0.0: [Up-to-date]
Updating toolchain-timsp430 @ 1.40603.0: [Up-to-date]
Updating framework-energiamsp430 @ 1.17.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform freescalekinetis
--------
Updating freescalekinetis @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform ststm32
--------
Updating ststm32 @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-stlink @ 1.10200.0: [Up-to-date]
Updating framework-spl @ 1.10201.0: [Up-to-date]
Updating framework-cmsis @ 1.40300.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform lattice_ice40
--------
Updating lattice_ice40 @ 0.0.0: [Up-to-date]
Updating toolchain-icestorm @ 1.7.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelavr
--------
Updating atmelavr @ 0.0.0: [Up-to-date]
Updating framework-arduinoavr @ 1.10608.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform espressif8266
--------
Updating espressif8266 @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-xtensa @ 1.40802.0: [Up-to-date]
Updating tool-esptool @ 1.409.0: [Up-to-date]
Updating tool-mkspiffs @ 1.102.0: [Up-to-date]
Updating framework-arduinoespressif8266 @ 1.20300.0: [Up-to-date]
Updating sdk-esp8266 @ 1.10502.0: [Up-to-date]
Platform linux_x86_64
--------
Updating linux_x86_64 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux64 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform windows_x86
--------
Updating windows_x86 @ 0.0.0: [Up-to-date]
Updating toolchain-gccmingw32 @ 1.40800.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform teensy
--------
Updating teensy @ 0.0.0: [Up-to-date]
Updating framework-arduinoteensy @ 1.128.0: [Up-to-date]
Updating tool-teensy @ 1.1.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Platform nordicnrf51
--------
Updating nordicnrf51 @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-arduinonordicnrf51 @ 1.20302.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform titiva
--------
Updating titiva @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-energiativa @ 1.17.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelsam
--------
Updating atmelsam @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-openocd @ 1.900.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating tool-bossac @ 1.10601.0: [Up-to-date]
Platform siliconlabsefm32
--------
Updating siliconlabsefm32 @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform microchippic32
--------
Updating microchippic32 @ 0.0.0: [Up-to-date]
Updating framework-arduinomicrochippic32 @ 1.10201.0: [Up-to-date]
Updating toolchain-microchippic32 @ 1.40803.0: [Up-to-date]
Updating tool-pic32prog @ 1.200200.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_i686
--------
Updating linux_i686 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux32 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform intel_arc32
--------
Updating intel_arc32 @ 0.0.0: [Up-to-date]
Updating framework-arduinointel @ 1.10006.0: [Up-to-date]
Updating tool-arduino101load @ 1.124.0: [Up-to-date]
Updating toolchain-intelarc32 @ 1.40805.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform nxplpc
--------
Updating nxplpc @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_arm
--------
Updating linux_arm @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmlinuxgnueabi @ 1.40802.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform native
--------
Updating native @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Library Manager
===============
Updating Adafruit-GFX @ 334e815bc1: [Up-to-date]
Updating Adafruit-ST7735 @ d53d4bf03a: [Up-to-date]
Updating Adafruit-DHT @ 09344416d2: [Up-to-date]
Updating Adafruit-Unified-Sensor @ f2af6f4efc: [Up-to-date]
Updating ESP8266_SSD1306 @ 3.2.3: [Up-to-date]
Updating EngduinoMagnetometer @ 3.1.0: [Up-to-date]
Updating IRremote @ 2.2.1: [Up-to-date]
Updating Json @ 5.6.4: [Up-to-date]
Updating MODSERIAL @ d8422efe47: [Up-to-date]
Updating PJON @ 1fb26fd: [Checking]
git version 2.7.4 (Apple Git-66)
Already up-to-date.
Updating Servo @ 36b69a7ced07: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/Servo/
searching for changes
no changes found
Updating TextLCD @ 308d188a2d3a: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/TextLCD/
searching for changes
no changes found
platformio upgrade
Contents
• platformio upgrade
• Usage
• Description
• Options
• Examples
Usage
platformio upgrade
pio upgrade
Description
Check or upgrade PlatformIO to the latest version
Options
--dev
Use development branch.
Examples
> platformio upgrade
You are up-to-date!
PlatformIO x.x.x is currently the newest version available.
# If you have problem with permissions try:
> sudo platformio upgrade
PlatformIO Home
PlatformIO Home allows you to interact with PlatformIO ecosystem using modern and
cross-platform GUI:
• Project Manager
• pioaccount
• librarymanager
• platforms
• Library and development platform updates
• frameworks
• boards
• Device Manager: serial, logical, and multicast DNS services
• Static Code Analysis
• Firmware File Explorer
• Firmware Memory Inspection
• Firmware Sections & Symbols Viewer.
Contents
• Installation
• Quick Start
• PlatformIO IDE
• PlatformIO Core
• Demo
• Welcome & Project Manager
• Project Inspect
• Statistics
• Firmware File Explorer
• Firmware Symbols
• Firmware Sections
• Static Code Analysis
• Library Manager
• Board Explorer
Installation
You do not need to install PlatformIO Home separately, it's already built-in in pioide and
piocore.
Quick Start
PlatformIO IDE
Please open PlatformIO Home using (HOME) button on PIO Toolbar:
• Atom: atom_ide_platformio_toolbar
• VSCode: ide_vscode_toolbar
PlatformIO Core
Please launch PlatformIO Home Web-server using cmd_home command and open in your browser
http://127.0.0.1:8008.
You can change host and port. Please check cmd_home command for details.
Demo
Welcome & Project Manager
[image]
Project Inspect
Statistics
[image]
Only code analysis (piocheck) [image]
Firmware File Explorer
[image]
File Symbols [image]
Firmware Symbols
[image]
Firmware Sections
[image]
Static Code Analysis
[image]
Library Manager
[image]
Board Explorer
[image]
Tutorials and Examples
Tutorials
Unit Testing of a Blink Project
The goal of this tutorial is to demonstrate how simple it is to use unit_testing.
• Level: Beginner
• Platforms: Windows, macOS, Linux
Contents
• Setting Up the Project
• Project structure
• Source files
• Test results
Setting Up the Project
1. Please navigate to the core_quickstart section and create the "Blink Project".
2. Create a test directory in the project (on the same level as src) and place a
test_main.cpp file in it (the source code is located below).
3. Run tests using the cmd_test command.
Project structure
project_dir
├── lib
│ └── README
├── platformio.ini
├── src
│ └── ...
└── test
└── test_main.cpp
Source files
• platformio.ini
; PlatformIO Project Configuration File
;
; Build options: build flags, source filter, extra scripting
; Upload options: custom port, speed and extra flags
; Library options: dependencies, extra library storages
;
; Please visit documentation for the other options and examples
; https://docs.platformio.org/page/projectconf.html
[env:uno]
platform = atmelavr
framework = arduino
board = uno
[env:teensy31]
platform = teensy
framework = arduino
board = teensy31
• test/test_main.cpp
#include <Arduino.h>
#include <unity.h>
// void setUp(void) {
// // set stuff up here
// }
// void tearDown(void) {
// // clean stuff up here
// }
void test_led_builtin_pin_number(void) {
TEST_ASSERT_EQUAL(13, LED_BUILTIN);
}
void test_led_state_high(void) {
digitalWrite(LED_BUILTIN, HIGH);
TEST_ASSERT_EQUAL(HIGH, digitalRead(LED_BUILTIN));
}
void test_led_state_low(void) {
digitalWrite(LED_BUILTIN, LOW);
TEST_ASSERT_EQUAL(LOW, digitalRead(LED_BUILTIN));
}
void setup() {
// NOTE!!! Wait for >2 secs
// if board doesn't support software reset via Serial.DTR/RTS
delay(2000);
UNITY_BEGIN(); // IMPORTANT LINE!
RUN_TEST(test_led_builtin_pin_number);
pinMode(LED_BUILTIN, OUTPUT);
}
uint8_t i = 0;
uint8_t max_blinks = 5;
void loop() {
if (i < max_blinks)
{
RUN_TEST(test_led_state_high);
delay(500);
RUN_TEST(test_led_state_low);
delay(500);
i++;
}
else if (i == max_blinks) {
UNITY_END(); // stop unit testing
}
}
Test results
> platformio test -e uno --verbose
Verbose mode can be enabled via `-v, --verbose` option
Collected 1 items
===================== [test/*] Building... (1/3) =======================
Processing uno (platform: atmelavr; board: uno; framework: arduino)
-------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Atmel AVR > Arduino Uno
SYSTEM: ATMEGA328P 16MHz 2KB RAM (31.50KB Flash)
Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF MODES: FINDER(chain) COMPATIBILITY(soft)
Collected 24 compatible libraries
Scanning dependencies...
No dependencies
Compiling .pio\build\uno\test\output_export.cpp.o
Compiling .pio\build\uno\test\test_main.cpp.o
Archiving .pio\build\uno\libFrameworkArduinoVariant.a
Compiling .pio\build\uno\FrameworkArduino\CDC.cpp.o
Indexing .pio\build\uno\libFrameworkArduinoVariant.a
Compiling .pio\build\uno\FrameworkArduino\HardwareSerial.cpp.o
Compiling .pio\build\uno\FrameworkArduino\HardwareSerial0.cpp.o
Compiling .pio\build\uno\FrameworkArduino\HardwareSerial1.cpp.o
Compiling .pio\build\uno\FrameworkArduino\HardwareSerial2.cpp.o
Compiling .pio\build\uno\FrameworkArduino\HardwareSerial3.cpp.o
Compiling .pio\build\uno\FrameworkArduino\IPAddress.cpp.o
Compiling .pio\build\uno\FrameworkArduino\PluggableUSB.cpp.o
Compiling .pio\build\uno\FrameworkArduino\Print.cpp.o
Compiling .pio\build\uno\FrameworkArduino\Stream.cpp.o
Compiling .pio\build\uno\FrameworkArduino\Tone.cpp.o
Compiling .pio\build\uno\FrameworkArduino\USBCore.cpp.o
Compiling .pio\build\uno\FrameworkArduino\WInterrupts.c.o
Compiling .pio\build\uno\FrameworkArduino\WMath.cpp.o
Compiling .pio\build\uno\FrameworkArduino\WString.cpp.o
Compiling .pio\build\uno\FrameworkArduino\abi.cpp.o
Compiling .pio\build\uno\FrameworkArduino\hooks.c.o
Compiling .pio\build\uno\FrameworkArduino\main.cpp.o
Compiling .pio\build\uno\FrameworkArduino\new.cpp.o
Compiling .pio\build\uno\FrameworkArduino\wiring.c.o
Compiling .pio\build\uno\FrameworkArduino\wiring_analog.c.o
Compiling .pio\build\uno\FrameworkArduino\wiring_digital.c.o
Compiling .pio\build\uno\FrameworkArduino\wiring_pulse.S.o
Compiling .pio\build\uno\FrameworkArduino\wiring_pulse.c.o
Compiling .pio\build\uno\FrameworkArduino\wiring_shift.c.o
Compiling .pio\build\uno\UnityTestLib\unity.o
Archiving .pio\build\uno\libFrameworkArduino.a
Indexing .pio\build\uno\libFrameworkArduino.a
Archiving .pio\build\uno\libUnityTestLib.a
Indexing .pio\build\uno\libUnityTestLib.a
Linking .pio\build\uno\firmware.elf
Checking size .pio\build\uno\firmware.elf
Building .pio\build\uno\firmware.hex
Memory Usage -> http://bit.ly/pio-memory-usage
DATA: [== ] 20.0% (used 410 bytes from 2048 bytes)
PROGRAM: [= ] 12.6% (used 4060 bytes from 32256 bytes)
========================================== [SUMMARY] ==========================================
Environment uno [SUCCESS]
Environment teensy31 [SKIP]
================================= [SUCCESS] Took 2.54 seconds =================================
================================= [test/*] Uploading... (2/3) =================================
Processing uno (platform: atmelavr; board: uno; framework: arduino)
-------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Atmel AVR > Arduino Uno
SYSTEM: ATMEGA328P 16MHz 2KB RAM (31.50KB Flash)
Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF MODES: FINDER(chain) COMPATIBILITY(soft)
Collected 24 compatible libraries
Scanning dependencies...
No dependencies
Checking size .pio\build\uno\firmware.elf
Memory Usage -> http://bit.ly/pio-memory-usage
DATA: [== ] 20.0% (used 410 bytes from 2048 bytes)
PROGRAM: [= ] 12.6% (used 4060 bytes from 32256 bytes)
Configuring upload protocol...
AVAILABLE: arduino
CURRENT: upload_protocol = arduino
Looking for upload port...
Auto-detected: COM18
Uploading .pio\build\uno\firmware.hex
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e950f (probably m328p)
avrdude: reading input file ".pio\build\uno\firmware.hex"
avrdude: writing flash (4060 bytes):
Writing | ################################################## | 100% 0.76s
avrdude: 4060 bytes of flash written
avrdude: verifying flash memory against .pio\build\uno\firmware.hex:
avrdude: load data flash data from input file .pio\build\uno\firmware.hex:
avrdude: input file .pio\build\uno\firmware.hex contains 4060 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 0.48s
avrdude: verifying ...
avrdude: 4060 bytes of flash verified
avrdude: safemode: Fuses OK (E:00, H:00, L:00)
avrdude done. Thank you.
=============================== [SUMMARY] ================================
Environment uno [SUCCESS]
Environment teensy31 [SKIP]
====================== [SUCCESS] Took 4.45 seconds ======================
================================== [test/*] Testing... (3/3) ==================================
If you don't see any output for the first 10 secs, please reset board (press reset button)
test\test_main.cpp:30:test_led_builtin_pin_number [PASSED]
test\test_main.cpp:41:test_led_state_high [PASSED]
test\test_main.cpp:43:test_led_state_low [PASSED]
test\test_main.cpp:41:test_led_state_high [PASSED]
test\test_main.cpp:43:test_led_state_low [PASSED]
test\test_main.cpp:41:test_led_state_high [PASSED]
test\test_main.cpp:43:test_led_state_low [PASSED]
test\test_main.cpp:41:test_led_state_high [PASSED]
test\test_main.cpp:43:test_led_state_low [PASSED]
test\test_main.cpp:41:test_led_state_high [PASSED]
test\test_main.cpp:43:test_led_state_low [PASSED]
-----------------------
11 Tests 0 Failures 0 Ignored
============================ [TEST SUMMARY] ==============================
test/*/env:uno [PASSED]
test/*/env:teensy31 [IGNORED]
==================== [PASSED] Took 12.99 seconds =========================
Get started with Arduino and ESP32-DevKitC: debugging and unit testing
The goal of this tutorial is to demonstrate how simple it is to use ide_vscode to develop,
run and debug a simple project with the framework_arduino framework for the ESP32-DevKitC
board.
• Level: Beginner
• Platforms: Windows, Mac OS X, Linux
Requirements:
• Downloaded and installed ide_vscode
• ESP32-DevKitC development board
• debugging_tool_olimex-arm-usb-ocd or debugging_tool_olimex-jtag-tiny adapter for
debugging
Contents
• Setting Up the Project
• Adding Code to the Generated Project
• Compiling and Uploading the Firmware
• Debugging the Firmware
• Setting Up the Hardware
• Writing Unit Tests
• Adding Bluetooth LE features
• Conclusion
Setting Up the Project
First, we need to create a new project using the PlatformIO Home Page (to open this page,
just press the Home icon on the toolbar): [image]
Next, we need to select ESP32-DevKitC as a development board, framework_arduino as a
framework and a path to the project location (or use the default one): [image]
Processing the selected project may take some time (PlatformIO will download and install
all required packages). After that, we have a fully configured project that is ready for
developing code with the framework_arduino framework.
Adding Code to the Generated Project
Let's add some actual code to the project. Firstly, we open a default main file named
main.cpp in the projectconf_pio_src_dir folder and replace its content with following:
#include <Arduino.h>
void setup()
{
Serial.begin(9600);
}
void loop()
{
Serial.println("Hello world!");
delay(1000);
}
[image]
We have now created a basic project ready for compiling and uploading.
Compiling and Uploading the Firmware
Now we can build the project. There are several ways to compile firmware:
• Build option in the Project Tasks menu,
• Build button in ide_vscode_toolbar,
• Task Menu: Tasks: Run Task... > PlatformIO: Build, or in the ide_vscode_toolbar,
• Command Palette: View: Command Palette > PlatformIO: Build, or
• via hotkeys cmd-alt-b / ctrl-alt-b
Marked in red: [image]
If everything went well, we should see a Success message in the terminal window: [image]
There are also several ways to upload the firmware to the board:
• Upload option in the Project Tasks menu,
• Upload button in ide_vscode_toolbar,
• Command Palette: View: Command Palette > PlatformIO: Upload,
• using the Task Menu: Tasks: Run Task... > PlatformIO: Upload, or
• via hotkeys: cmd-alt-u / ctrl-alt-u:
[image]
After uploading, we need to check if the firmware is uploaded correctly. To do this, open
the serial monitor and check that the message from the board is received. To open the
serial monitor, we can use the following options:
• Monitor option in the Project Tasks menu,
• Serial Monitor button in the ide_vscode_toolbar,
• Command Palette: View: Command Palette > PlatformIO: Monitor, or
• Task Menu: Tasks: Run Task... > PlatformIO: Monitor:
[image]
If the firmware works as expected, the message from the board can be observed in the
terminal window: [image]
Debugging the Firmware
Setting Up the Hardware
In order to use a JTAG probe with an ESP32, we need to connect the following pins:
┌──────────────┬────────────────┐
│ESP32 pin │ JTAG probe pin │
├──────────────┼────────────────┤
│3.3V │ Pin 1(VTref) │
├──────────────┼────────────────┤
│GPIO 9 (EN) │ Pin 3 (nTRST) │
├──────────────┼────────────────┤
│GND │ Pin 4 (GND) │
├──────────────┼────────────────┤
│GPIO 12 (TDI) │ Pin 5 (TDI) │
├──────────────┼────────────────┤
│GPIO 14 (TMS) │ Pin 7 (TMS) │
├──────────────┼────────────────┤
│GPIO 13 (TCK) │ Pin 9 (TCK) │
├──────────────┼────────────────┤
│GPIO 15 (TDO) │ Pin 13 (TDO) │
└──────────────┴────────────────┘
piodebug offers the easiest way to debug the board. Firstly, we need to specify
projectconf_debug_tool in projectconf. In this tutorial, an
debugging_tool_olimex-arm-usb-ocd-h debug probe is used:
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
debug_tool = olimex-arm-usb-ocd-h
To start the debug session we can use the following methods:
• Debug: Start debugging in the top menu,
• Start Debugging option in the Quick Access menu, or
• hotkey button F5:
[image]
We need to wait some time while PlatformIO initializes the debug session, and are ready to
debug when the first line after the main function is highlighted.
1. Please wait when debugging session is stopped at the first line of app_main() function
2. WARNING! Please set a breakpoint at void loopTask(void *pvParameters) (line 13 in the
screenshot below - this line can change between releases)
3. Now, please press CONTINUE/RUN button on debugging toolbar (right arrow icon)
4. The debugging session should stop at the first line of the void loopTask(void
*pvParameters) function
5. Now, navigate to your Arduino setup/loop code and do classic debugging.
[image]
We can walk through the code using control buttons, set breakpoints, and add variables to
the Watch window: [image]
Writing Unit Tests
Test cases can be added to a single file that may include multiple tests. First of all, in
this file, we need to add four default functions: setUp, tearDown, setup and loop.
Functions setUp and tearDown are used to initialize and finalize test conditions.
Implementations of these functions are not required for running tests, but if you need to
initialize some variables before you run a test, use the setUp function. Likewise, if you
need to clean up variables, use tearDown function. In our example we will use these
functions to respectively initialize and deinitialize LED states. The setup and loop
functions act as a simple Arduino program where we describe our test plan.
Let's create a test folder in the root of the project and add a new file, test_main.cpp,
to this folder. Next, basic tests for String class will be implemented in this file:
• test_string_concat tests the concatenation of two strings
• test_string_substring tests the correctness of the substring extraction
• test_string_index_of ensures that the string returns the correct index of the specified
symbol
• test_string_equal_ignore_case tests case-insensitive comparison of two strings
• test_string_to_upper_case tests conversion of the string to upper-case
• test_string_replace tests the correctness of the replacing operation
#include <Arduino.h>
#include <unity.h>
String STR_TO_TEST;
void setUp(void) {
// set stuff up here
STR_TO_TEST = "Hello, world!";
}
void tearDown(void) {
// clean stuff up here
STR_TO_TEST = "";
}
void test_string_concat(void) {
String hello = "Hello, ";
String world = "world!";
TEST_ASSERT_EQUAL_STRING(STR_TO_TEST.c_str(), (hello + world).c_str());
}
void test_string_substring(void) {
TEST_ASSERT_EQUAL_STRING("Hello", STR_TO_TEST.substring(0, 5).c_str());
}
void test_string_index_of(void) {
TEST_ASSERT_EQUAL(7, STR_TO_TEST.indexOf('w'));
}
void test_string_equal_ignore_case(void) {
TEST_ASSERT_TRUE(STR_TO_TEST.equalsIgnoreCase("HELLO, WORLD!"));
}
void test_string_to_upper_case(void) {
STR_TO_TEST.toUpperCase();
TEST_ASSERT_EQUAL_STRING("HELLO, WORLD!", STR_TO_TEST.c_str());
}
void test_string_replace(void) {
STR_TO_TEST.replace('!', '?');
TEST_ASSERT_EQUAL_STRING("Hello, world?", STR_TO_TEST.c_str());
}
void setup()
{
delay(2000); // service delay
UNITY_BEGIN();
RUN_TEST(test_string_concat);
RUN_TEST(test_string_substring);
RUN_TEST(test_string_index_of);
RUN_TEST(test_string_equal_ignore_case);
RUN_TEST(test_string_to_upper_case);
RUN_TEST(test_string_replace);
UNITY_END(); // stop unit testing
}
void loop()
{
}
Now we are ready to upload tests to the board. To do this we can use the following:
• Test button on ide_vscode_toolbar,
• Test option in the Project Tasks menu, or
• Tasks: Run Task... > PlatformIO Test in the top menu:
[image]
After processing, we should see a detailed report about the testing results: [image]
As we can see from the report, all our tests were successful!
Adding Bluetooth LE features
Now let's create a basic application that can interact with other BLE devices (e.g
phones). For example, the following code declares a BLE characteristic whose value can be
printed to the serial port:
#include <Arduino.h>
#include <BLEDevice.h>
#include <BLEUtils.h>
#include <BLEServer.h>
#define SERVICE_UUID "4fafc201-1fb5-459e-8fcc-c5c9c331914b"
#define CHARACTERISTIC_UUID "beb5483e-36e1-4688-b7f5-ea07361b26a8"
class MyCallbacks: public BLECharacteristicCallbacks {
void onWrite(BLECharacteristic *pCharacteristic) {
std::string value = pCharacteristic->getValue();
if (value.length() > 0) {
Serial.print("\r\nNew value: ");
for (int i = 0; i < value.length(); i++)
Serial.print(value[i]);
Serial.println();
}
}
};
void setup() {
Serial.begin(9600);
BLEDevice::init("ESP32 BLE example");
BLEServer *pServer = BLEDevice::createServer();
BLEService *pService = pServer->createService(SERVICE_UUID);
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
CHARACTERISTIC_UUID,
BLECharacteristic::PROPERTY_READ |
BLECharacteristic::PROPERTY_WRITE
);
pCharacteristic->setCallbacks(new MyCallbacks());
pCharacteristic->setValue("Hello World");
pService->start();
BLEAdvertising *pAdvertising = pServer->getAdvertising();
pAdvertising->start();
}
void loop() {
delay(2000);
}
Now we can compile and upload this program to the board as described in the previous
sections. To verify that our application works as expected, we can use any Android
smartphone with the BLE feature and Nordic nRF Connect tool.
At first, we need to scan all advertising BLE devices and connect to the device called
ESP32 BLE example. After successful connection to the board, we should see one "Unknown
Service" with one "Unknown Characteristic" field: [image]
To set the value, we need to send new text to the BLE characteristic: [image]
The change of the value is printed to the serial monitor: [image]
Conclusion
Now we have a project template for the ESP32-DevKitC board that we can use as boilerplate
for later projects.
Get started with ESP-IDF and ESP32-DevKitC: debugging, unit testing, project analysis
The goal of this tutorial is to demonstrate how simple it is to use ide_vscode to develop,
run and debug a simple Wi-Fi project with the framework_espidf framework for the
ESP32-DevKitC board.
• Level: Intermediate
• Platforms: Windows, Mac OS X, Linux
Requirements:
• Downloaded and installed ide_vscode
• ESP32-DevKitC development board
• An external debug adapter (e.g. debugging_tool_olimex-arm-usb-ocd)
Contents
• Setting Up the Project
• Adding Code to the Generated Project
• Debugging the Firmware
• Setting Up the Hardware
• Writing Unit Tests
• Project Inspection
• Conclusion
Setting Up the Project
1. Click on "PlatformIO Home" button on the bottom PlatformIO Toolbar:
[image]
2. Click on "New Project", select ESP32-DevKitC as the development board, framework_espidf
as the framework and a path to the project location (or use the default one):
[image]
Adding Code to the Generated Project
1. Create a new file main.c in projectconf_pio_src_dir folder and add the following code:
/* WiFi softAP Example
This example code is in the Public Domain (or CC0 licensed, at your option.)
Unless required by applicable law or agreed to in writing, this
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied.
*/
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_log.h"
#include "nvs_flash.h"
#include "lwip/err.h"
#include "lwip/sys.h"
#define EXAMPLE_ESP_WIFI_SSID "mywifissid"
#define EXAMPLE_ESP_WIFI_PASS "mywifipass"
#define EXAMPLE_MAX_STA_CONN (3)
static const char *TAG = "wifi softAP";
static void wifi_event_handler(void* arg, esp_event_base_t event_base,
int32_t event_id, void* event_data)
{
if (event_id == WIFI_EVENT_AP_STACONNECTED) {
wifi_event_ap_staconnected_t* event = (wifi_event_ap_staconnected_t*) event_data;
ESP_LOGI(TAG, "station "MACSTR" join, AID=%d",
MAC2STR(event->mac), event->aid);
} else if (event_id == WIFI_EVENT_AP_STADISCONNECTED) {
wifi_event_ap_stadisconnected_t* event = (wifi_event_ap_stadisconnected_t*) event_data;
ESP_LOGI(TAG, "station "MACSTR" leave, AID=%d",
MAC2STR(event->mac), event->aid);
}
}
void wifi_init_softap()
{
tcpip_adapter_init();
ESP_ERROR_CHECK(esp_event_loop_create_default());
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
ESP_ERROR_CHECK(esp_wifi_init(&cfg));
ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL));
wifi_config_t wifi_config = {
.ap = {
.ssid = EXAMPLE_ESP_WIFI_SSID,
.ssid_len = strlen(EXAMPLE_ESP_WIFI_SSID),
.password = EXAMPLE_ESP_WIFI_PASS,
.max_connection = EXAMPLE_MAX_STA_CONN,
.authmode = WIFI_AUTH_WPA_WPA2_PSK
},
};
if (strlen(EXAMPLE_ESP_WIFI_PASS) == 0) {
wifi_config.ap.authmode = WIFI_AUTH_OPEN;
}
ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_AP));
ESP_ERROR_CHECK(esp_wifi_set_config(ESP_IF_WIFI_AP, &wifi_config));
ESP_ERROR_CHECK(esp_wifi_start());
ESP_LOGI(TAG, "wifi_init_softap finished. SSID:%s password:%s",
EXAMPLE_ESP_WIFI_SSID, EXAMPLE_ESP_WIFI_PASS);
}
void app_main()
{
//Initialize NVS
esp_err_t ret = nvs_flash_init();
if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
ESP_ERROR_CHECK(nvs_flash_erase());
ret = nvs_flash_init();
}
ESP_ERROR_CHECK(ret);
ESP_LOGI(TAG, "ESP_WIFI_MODE_AP");
wifi_init_softap();
}
WARNING:
Make sure this new file main.c is registered as source file using
idf_component_register function in src/CMakeLists.txt file:
idf_component_register(SRCS "main.c")
2. To compile the project use one of the following options:
• Build option from the Project Tasks menu
• Build button in ide_vscode_toolbar
• Task Menu Tasks: Run Task... > PlatformIO: Build or in ide_vscode_toolbar
• Command Palette View: Command Palette > PlatformIO: Build
• Hotkeys cmd-alt-b / ctrl-alt-b:
[image]
3. If everything went well, we should see a successful result message in the terminal
window:
[image]
4. To upload the firmware to the board we can use the following options:
• Upload option from the Project Tasks menu
• Upload button in ide_vscode_toolbar
• Command Palette View: Command Palette > PlatformIO: Upload
• Task Menu Tasks: Run Task... > PlatformIO: Upload
• Hotkeys cmd-alt-u / ctrl-alt-u:
[image]
5. Connect the board to your computer and update the default monitor speed to 115200 in
platformio.ini file:
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = espidf
monitor_speed = 115200
6. Open Serial Monitor to observe the output from the board:
[image]
7. If everything went well, the board should be visible as a WiFi access point:
[image]
Debugging the Firmware
Setting Up the Hardware
In order to use piodebug, we need to connect an external JTAG probe and the board using
the following pins:
┌──────────────┬────────────────┐
│ESP32 pin │ JTAG probe pin │
├──────────────┼────────────────┤
│3.3V │ Pin 1(VTref) │
├──────────────┼────────────────┤
│GPIO 9 (EN) │ Pin 3 (nTRST) │
├──────────────┼────────────────┤
│GND │ Pin 4 (GND) │
├──────────────┼────────────────┤
│GPIO 12 (TDI) │ Pin 5 (TDI) │
├──────────────┼────────────────┤
│GPIO 14 (TMS) │ Pin 7 (TMS) │
├──────────────┼────────────────┤
│GPIO 13 (TCK) │ Pin 9 (TCK) │
├──────────────┼────────────────┤
│GPIO 15 (TDO) │ Pin 13 (TDO) │
└──────────────┴────────────────┘
1. Specify projectconf_debug_tool in projectconf. In this tutorial,
debugging_tool_olimex-arm-usb-ocd-h debug probe is used:
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = espidf
monitor_speed = 115200
debug_tool = olimex-arm-usb-ocd-h
2. To start the debug session we can use the following methods:
• Debug: Start debugging in the top menu
• Start Debugging option in the Quick Access menu
• Hotkey button F5:
[image]
3. Walk through the code using control buttons, set breakpoints, and add variables to the
Watch window:
[image]
Writing Unit Tests
NOTE:
Functions setUp and tearDown are used to initialize and finalize test conditions.
Implementations of these functions are not required for running tests but if you need
to initialize some variables before you run a test, you use the setUp function and if
you need to clean up variables you use tearDown function.
For the sake of simplicity, let's create a small library called calculator, implement
several basic functions addition, subtraction, multiplication, division and test them
using unit_testing engine.
1. Create a new folder calculator in the projectconf_pio_lib_dir folder and add two new
files calculator.h and calculator.c with the following contents:
calculator.h:
#ifndef _CALCULATOR_H_
#define _CALCULATOR_H_
#ifdef __cplusplus
extern "C" {
#endif
int addition (int a, int b);
int subtraction (int a, int b);
int multiplication (int a, int b);
int division (int a, int b);
#ifdef __cplusplus
}
#endif
#endif // _CALCULATOR_H_
calculator.c:
#include "calculator.h"
int addition(int a, int b)
{
return a + b;
}
int subtraction(int a, int b)
{
return a - b;
}
int multiplication(int a, int b)
{
return a * b;
}
int division(int a, int b)
{
return a / b;
}
2. Create a new file test_calc.c to the folder projectconf_pio_test_dir and add basic
tests for the calculator library:
#include <calculator.h>
#include <unity.h>
void test_function_calculator_addition(void) {
TEST_ASSERT_EQUAL(32, addition(25, 7));
}
void test_function_calculator_subtraction(void) {
TEST_ASSERT_EQUAL(20, subtraction(23, 3));
}
void test_function_calculator_multiplication(void) {
TEST_ASSERT_EQUAL(50, multiplication(25, 2));
}
void test_function_calculator_division(void) {
TEST_ASSERT_EQUAL(32, division(100, 3));
}
void main() {
UNITY_BEGIN();
RUN_TEST(test_function_calculator_addition);
RUN_TEST(test_function_calculator_subtraction);
RUN_TEST(test_function_calculator_multiplication);
RUN_TEST(test_function_calculator_division);
UNITY_END();
}
3. Let's run tests on the board and check the results. There should be a problem with
test_function_calculator_division test:
[image]
4. Let's fix the incorrect expected value and run tests again. After processing the
results should be correct:
[image]
Project Inspection
For illustrative purposes, let's imagine we need to find a function with the biggest
memory footprint. Also, let's introduce a bug to our project so piocheck can report it.
1. Open PlatformIO Home and navigate to Inspect section, select the current project and
press Inspect button:
[image]
2. Project statistics:
[image]
3. The biggest function:
[image]
4. Possible bugs:
[image]
Conclusion
Now we have a project template for the ESP32-DevKitC board that we can use as boilerplate
for later projects.
STM32Cube HAL and Nucleo-F401RE: debugging and unit testing
The goal of this tutorial is to demonstrate how simple it is to use ide_atom to develop,
run and debug a basic blink project with framework_stm32cube framework for STM32
Nucleo-F401RE board.
• Level: Intermediate
• Platforms: Windows, Mac OS X, Linux
Requirements:
• Downloaded and installed ide_atom
• Install drivers for debugging_tool_stlink debug tool
• Nucleo-F401RE development board
Contents
• Setting Up the Project
• Adding Code to the Generated Project
• Compiling and Uploading the Firmware
• Debugging the Firmware
• Writing Unit Tests
• Conclusion
• Project Source Code
Setting Up the Project
At first step, we need to create a new project using PlatformIO Home Page (to open this
page just press Home icon on the toolbar): [image]
On the next step, we need to select ST Nucleo-F401RE as a development board,
framework_stm32cube as a framework and a path to the project location (or use the default
one): [image]
Processing the selected project may take some amount of time (PlatformIO will download and
install all required packages) and after these steps, we have a fully configured project
that is ready for developing code with framework_stm32cube framework.
Adding Code to the Generated Project
Let's add some actual code to the project. Firstly, we create two main files main.c and
main.h in the projectconf_pio_src_dir folder. Right click on the src in the project
window: [image]
Add next content to main.h:
#ifndef MAIN_H
#define MAIN_H
#include "stm32f4xx_hal.h"
#define LED_PIN GPIO_PIN_5
#define LED_GPIO_PORT GPIOA
#define LED_GPIO_CLK_ENABLE() __HAL_RCC_GPIOA_CLK_ENABLE()
#endif // MAIN_H
Add this code to main.c:
#include "main.h"
void LED_Init();
int main(void) {
HAL_Init();
LED_Init();
while (1)
{
HAL_GPIO_TogglePin(LED_GPIO_PORT, LED_PIN);
HAL_Delay(1000);
}
}
void LED_Init() {
LED_GPIO_CLK_ENABLE();
GPIO_InitTypeDef GPIO_InitStruct;
GPIO_InitStruct.Pin = LED_PIN;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_PULLUP;
GPIO_InitStruct.Speed = GPIO_SPEED_HIGH;
HAL_GPIO_Init(LED_GPIO_PORT, &GPIO_InitStruct);
}
void SysTick_Handler(void) {
HAL_IncTick();
}
After this step, we created a basic blink project that is ready for compiling and
uploading.
Compiling and Uploading the Firmware
Now we can build the project. To compile firmware we can use next options: Build option on
the Project Tasks menu, Build button on ide_vscode_toolbar, using Command Palette View:
Command Palette > PlatformIO: Build, using Task Menu Tasks: Run Task... > PlatformIO:
Build or via hotkeys cmd-alt-b / ctrl-alt-b: [image]
If everything went well, we should see the successful result in the terminal window:
[image]
To upload the firmware to the board we can use next options: Upload option on the Project
Tasks menu, Upload button on ide_vscode_toolbar, using Command Palette View: Command
Palette > PlatformIO: Upload, using Task Menu Tasks: Run Task... > PlatformIO: Upload or
via hotkeys cmd-alt-u / ctrl-alt-u: [image]
After successful uploading, the green LED2 should start blinking.
Debugging the Firmware
piodebug offers the easiest way to debug your board. To start debugging session you can
use Start debugging option in PlatformIO Quick Access menu, Debug: Start debugging from
the top menu or hotkey button F5: [image]
We need to wait some time while PlatformIO is initializing debug session and when the
first line after the main function is highlighted we are ready to debug: [image]
We can walk through the code using control buttons, set breakpoints, see peripheral
registers, add variables to Watch window: [image]
Writing Unit Tests
Now let’s write some tests using unit_testing feature that can help us test code directly
on the target board. unit_testing engine by default supports only three frameworks:
framework_arduino, framework_espidf, framework_mbed, and framework_mbed. Since we decided
to use framework_stm32cube we need to implement a custom projectconf_test_transport to
print testing results and specify that condition in projectconf:
[env:nucleo_f401re]
platform = ststm32
board = nucleo_f401re
framework = stm32cube
test_transport = custom
Also, we need to create a new folder test where the tests and custom
projectconf_test_transport implementation (described next) will be located: [image]
We will use USART2 on ST Nucleo-F401RE board because it's directly connected to the STLink
debug interface and in OS it can be visible as a Virtual Com Port, so we don't need any
additional USB-UART converter. To implement the custom projectconf_test_transport we need
to create two files unittest_transport.h and unittest_transport.c and put them in the
projectconf_pio_test_dir in the root folder of our project. In these files we need to
implement the next four functions:
void unittest_uart_begin();
void unittest_uart_putchar(char c);
void unittest_uart_flush();
void unittest_uart_end();
Implementation of unittest_transport.h:
#ifndef UNITEST_TRANSPORT_H
#define UNITEST_TRANSPORT_H
#ifdef __cplusplus
extern "C" {
#endif
void unittest_uart_begin();
void unittest_uart_putchar(char c);
void unittest_uart_flush();
void unittest_uart_end();
#ifdef __cplusplus
}
#endif
#endif // UNITEST_TRANSPORT_H
Implementation of unittest_transport.c:
#include "unittest_transport.h"
#include "stm32f4xx_hal.h"
#define USARTx USART2
#define USARTx_CLK_ENABLE() __HAL_RCC_USART2_CLK_ENABLE()
#define USARTx_CLK_DISABLE() __HAL_RCC_USART2_CLK_DISABLE()
#define USARTx_RX_GPIO_CLK_ENABLE() __HAL_RCC_GPIOA_CLK_ENABLE()
#define USARTx_TX_GPIO_CLK_ENABLE() __HAL_RCC_GPIOA_CLK_ENABLE()
#define USARTx_RX_GPIO_CLK_DISABLE() __HAL_RCC_GPIOA_CLK_DISABLE()
#define USARTx_TX_GPIO_CLK_DISABLE() __HAL_RCC_GPIOA_CLK_DISABLE()
#define USARTx_FORCE_RESET() __HAL_RCC_USART2_FORCE_RESET()
#define USARTx_RELEASE_RESET() __HAL_RCC_USART2_RELEASE_RESET()
#define USARTx_TX_PIN GPIO_PIN_2
#define USARTx_TX_GPIO_PORT GPIOA
#define USARTx_TX_AF GPIO_AF7_USART2
#define USARTx_RX_PIN GPIO_PIN_3
#define USARTx_RX_GPIO_PORT GPIOA
#define USARTx_RX_AF GPIO_AF7_USART2
static UART_HandleTypeDef UartHandle;
void unittest_uart_begin()
{
GPIO_InitTypeDef GPIO_InitStruct;
USARTx_TX_GPIO_CLK_ENABLE();
USARTx_RX_GPIO_CLK_ENABLE();
USARTx_CLK_ENABLE();
GPIO_InitStruct.Pin = USARTx_TX_PIN;
GPIO_InitStruct.Mode = GPIO_MODE_AF_PP;
GPIO_InitStruct.Pull = GPIO_PULLUP;
GPIO_InitStruct.Speed = GPIO_SPEED_FAST;
GPIO_InitStruct.Alternate = USARTx_TX_AF;
HAL_GPIO_Init(USARTx_TX_GPIO_PORT, &GPIO_InitStruct);
GPIO_InitStruct.Pin = USARTx_RX_PIN;
GPIO_InitStruct.Alternate = USARTx_RX_AF;
HAL_GPIO_Init(USARTx_RX_GPIO_PORT, &GPIO_InitStruct);
UartHandle.Instance = USARTx;
UartHandle.Init.BaudRate = 115200;
UartHandle.Init.WordLength = UART_WORDLENGTH_8B;
UartHandle.Init.StopBits = UART_STOPBITS_1;
UartHandle.Init.Parity = UART_PARITY_NONE;
UartHandle.Init.HwFlowCtl = UART_HWCONTROL_NONE;
UartHandle.Init.Mode = UART_MODE_TX_RX;
UartHandle.Init.OverSampling = UART_OVERSAMPLING_16;
if(HAL_UART_Init(&UartHandle) != HAL_OK) {
while(1){}
}
}
void unittest_uart_putchar(char c)
{
HAL_UART_Transmit(&UartHandle, (uint8_t*)(&c), 1, 1000);
}
void unittest_uart_flush(){}
void unittest_uart_end() {
USARTx_CLK_DISABLE();
USARTx_RX_GPIO_CLK_DISABLE();
USARTx_TX_GPIO_CLK_DISABLE();
}
Now we need to add some test cases. Tests can be added to a single C file that may include
multiple tests. First of all, we need to add three default functions: setUp, tearDown and
main. setUp and tearDown are used to initialize and finalize test conditions.
Implementations of these functions are not required for running tests but if you need to
initialize some variables before you run a test, you use the setUp function and if you
need to clean up variables you use tearDown function. In our example, we will use these
functions to accordingly initialize and deinitialize LED. main function acts as a simple
program where we describe our test plan.
Let's add a new file test_main.c to the folder test. Next basic tests for blinking routine
will be implemented in this file:
• test_led_builtin_pin_number ensures that LED_PIN has the correct value
• test_led_state_high tests functions HAL_GPIO_WritePin and HAL_GPIO_ReadPin with
GPIO_PIN_SET value
• test_led_state_low tests functions HAL_GPIO_WritePin and HAL_GPIO_ReadPin with
GPIO_PIN_RESET value
NOTE:
• 2 sec delay is required since the board doesn't support software resetting via
Serial.DTR/RTS
#include "../src/main.h"
#include <unity.h>
void setUp(void) {
LED_GPIO_CLK_ENABLE();
GPIO_InitTypeDef GPIO_InitStruct;
GPIO_InitStruct.Pin = LED_PIN;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_PULLUP;
GPIO_InitStruct.Speed = GPIO_SPEED_HIGH;
HAL_GPIO_Init(LED_GPIO_PORT, &GPIO_InitStruct);
}
void tearDown(void) {
HAL_GPIO_DeInit(LED_GPIO_PORT, LED_PIN);
}
void test_led_builtin_pin_number(void) {
TEST_ASSERT_EQUAL(GPIO_PIN_5, LED_PIN);
}
void test_led_state_high(void) {
HAL_GPIO_WritePin(LED_GPIO_PORT, LED_PIN, GPIO_PIN_SET);
TEST_ASSERT_EQUAL(GPIO_PIN_SET, HAL_GPIO_ReadPin(LED_GPIO_PORT, LED_PIN));
}
void test_led_state_low(void) {
HAL_GPIO_WritePin(LED_GPIO_PORT, LED_PIN, GPIO_PIN_RESET);
TEST_ASSERT_EQUAL(GPIO_PIN_RESET, HAL_GPIO_ReadPin(LED_GPIO_PORT, LED_PIN));
}
int main() {
HAL_Init(); // initialize the HAL library
HAL_Delay(2000); // service delay
UNITY_BEGIN();
RUN_TEST(test_led_builtin_pin_number);
for (unsigned int i = 0; i < 5; i++)
{
RUN_TEST(test_led_state_high);
HAL_Delay(500);
RUN_TEST(test_led_state_low);
HAL_Delay(500);
}
UNITY_END(); // stop unit testing
while(1){}
}
void SysTick_Handler(void) {
HAL_IncTick();
}
Now we are ready to upload tests to the board. To do this we can use Test option from the
Project Tasks menu, Tasks: Run Task... > PlatformIO Test option from the top menu or Test
button on ide_vscode_toolbar: [image]
After processing we should see a detailed report about the testing results: [image]
Congratulations! As we can see from the report, all our tests went successfully!
Conclusion
Now we have a decent template that we can improve for our next more complex projects.
Project Source Code
The source code of this tutorial is available at
https://github.com/platformio/platformio-examples/tree/develop/unit-testing/stm32cube
Arduino and Nordic nRF52-DK: debugging and unit testing
The goal of this tutorial is to demonstrate how simple it is to use ide_vscode to develop,
run and debug a simple project with framework_arduino framework for Nordic nRF52-DK board.
• Level: Beginner
• Platforms: Windows, Mac OS X, Linux
Requirements:
• Downloaded and installed ide_vscode
• Install drivers for debugging_tool_jlink debug tool
• Nordic nRF52-DK development board
Contents
• Setting Up the Project
• Adding Code to the Generated Project
• Compiling and Uploading the Firmware
• Debugging the Firmware
• Writing Unit Tests
• Adding Bluetooth LE features
• Conclusion
Setting Up the Project
At first step, we need to create a new project using PlatformIO Home Page (to open this
page just press Home icon on the toolbar): [image]
On the next step we need to select Nordic nRF52-DK as a development board,
framework_arduino as a framework and a path to the project location (or use the default
one): [image]
Processing the selected project may take some amount of time (PlatformIO will download and
install all required packages) and after these steps, we have a fully configured project
that is ready for developing code with framework_arduino framework.
Adding Code to the Generated Project
Let's add some actual code to the project. Firstly, we open a default main file main.cpp
in the projectconf_pio_src_dir folder and replace its contents with the following:
#include <Arduino.h>
void setup()
{
pinMode(LED_BUILTIN, OUTPUT);
}
void loop()
{
digitalWrite(LED_BUILTIN, HIGH);
delay(100);
digitalWrite(LED_BUILTIN, LOW);
delay(100);
}
[image]
After this step, we created a basic blink project ready for compiling and uploading.
Compiling and Uploading the Firmware
Now we can build the project. To compile firmware we can use next options: Build option
from the Project Tasks menu, Build button in ide_vscode_toolbar, Task Menu Tasks: Run
Task... > PlatformIO: Build or in ide_vscode_toolbar, Command Palette View: Command
Palette > PlatformIO: Build or via hotkeys cmd-alt-b / ctrl-alt-b: [image]
If everything went well, we should see a successful result message in the terminal window:
[image]
To upload the firmware to the board we can use next options: Upload option from the
Project Tasks menu, Upload button in ide_vscode_toolbar, Command Palette View: Command
Palette > PlatformIO: Upload, using Task Menu Tasks: Run Task... > PlatformIO: Upload or
via hotkeys cmd-alt-u / ctrl-alt-u: [image]
After successful uploading, the green LED1 should start blinking.
Debugging the Firmware
piodebug offers the easiest way to debug the board. Firstly, we need to specify
projectconf_debug_tool in projectconf. Since the board has an on-board JLink debug probe
we can directly declare it in projectconf:
[env:nrf52_dk]
platform = nordicnrf52
board = nrf52_dk
framework = arduino
debug_tool = jlink
To start the debug session we can use next options: Debug: Start debugging from the top
menu, Start Debugging option from Quick Access menu or hotkey button F5: [image]
We need to wait some time while PlatformIO is initializing the debug session and when the
first line after the main function is highlighted we are ready to debug: [image]
We can walk through the code using control buttons, set breakpoints, add variables to
Watch window: [image]
Writing Unit Tests
Test cases can be added to a single file that may include multiple tests. First of all, in
this file, we need to add four default functions: setUp, tearDown, setup and loop.
Functions setUp and tearDown are used to initialize and finalize test conditions.
Implementations of these functions are not required for running tests but if you need to
initialize some variables before you run a test, you use the setUp function and if you
need to clean up variables you use tearDown function. In our example we will use these
functions to accordingly initialize and deinitialize LED. setup and loop functions act as
a simple Arduino program where we describe our test plan.
Let's create test folder in the root of the project and add a new file test_main.cpp to
this folder. Next basic tests for String class will be implemented in this file:
• test_string_concat tests the concatenation of two strings
• test_string_substring tests the correctness of the substring extraction
• test_string_index_of ensures that the string returns the correct index of the specified
symbol
• test_string_equal_ignore_case tests case-insensitive comparison of two strings
• test_string_to_upper_case tests upper-case conversion of the string
• test_string_replace tests the correctness of the replacing operation
NOTE:
• 2 sec delay is required since the board doesn't support software resetting via
Serial.DTR/RTS
#include <Arduino.h>
#include <unity.h>
String STR_TO_TEST;
void setUp(void) {
// set stuff up here
STR_TO_TEST = "Hello, world!";
}
void tearDown(void) {
// clean stuff up here
STR_TO_TEST = "";
}
void test_string_concat(void) {
String hello = "Hello, ";
String world = "world!";
TEST_ASSERT_EQUAL_STRING(STR_TO_TEST.c_str(), (hello + world).c_str());
}
void test_string_substring(void) {
TEST_ASSERT_EQUAL_STRING("Hello", STR_TO_TEST.substring(0, 5).c_str());
}
void test_string_index_of(void) {
TEST_ASSERT_EQUAL(7, STR_TO_TEST.indexOf('w'));
}
void test_string_equal_ignore_case(void) {
TEST_ASSERT_TRUE(STR_TO_TEST.equalsIgnoreCase("HELLO, WORLD!"));
}
void test_string_to_upper_case(void) {
STR_TO_TEST.toUpperCase();
TEST_ASSERT_EQUAL_STRING("HELLO, WORLD!", STR_TO_TEST.c_str());
}
void test_string_replace(void) {
STR_TO_TEST.replace('!', '?');
TEST_ASSERT_EQUAL_STRING("Hello, world?", STR_TO_TEST.c_str());
}
void setup()
{
delay(2000); // service delay
UNITY_BEGIN();
RUN_TEST(test_string_concat);
RUN_TEST(test_string_substring);
RUN_TEST(test_string_index_of);
RUN_TEST(test_string_equal_ignore_case);
RUN_TEST(test_string_to_upper_case);
RUN_TEST(test_string_replace);
UNITY_END(); // stop unit testing
}
void loop()
{
}
Now we are ready to upload tests to the board. To do this we can use next options: Test
button on ide_vscode_toolbar, Test option from the Project Tasks menu or Tasks: Run
Task... > PlatformIO Test from the top menu: [image]
After processing we should see a detailed report about the testing results: [image]
As we can see from the report, all our tests were successful!
Adding Bluetooth LE features
To add the basic BLE functionality to our project we need to define the SoftDevice version
and install a library called BLEPeripheral. Both these modifications can be specified in
projectconf:
[env:nrf52_dk]
platform = nordicnrf52
board = nrf52_dk
framework = arduino
debug_tool = jlink
; SoftDevice version
build_flags = -DNRF52_S132
lib_deps =
BLEPeripheral
Now let's create a basic application that can interact with other BLE devices (e.g phone)
For example, next code declares a BLE characteristic that controls the state of the LED1.
#include <Arduino.h>
#include <SPI.h>
#include <BLEPeripheral.h>
BLEPeripheral ledPeripheral = BLEPeripheral();
BLEService ledService = BLEService("19b10000e8f2537e4f6cd104768a1214");
BLECharCharacteristic ledCharacteristic = BLECharCharacteristic("19b10001e8f2537e4f6cd104768a1214", BLERead | BLEWrite);
void setup()
{
pinMode(LED_BUILTIN, OUTPUT);
ledPeripheral.setAdvertisedServiceUuid(ledService.uuid());
ledPeripheral.addAttribute(ledService);
ledPeripheral.addAttribute(ledCharacteristic);
ledPeripheral.setLocalName("Nordic NRF52 DK");
ledPeripheral.begin();
}
void loop()
{
BLECentral central = ledPeripheral.central();
if (central) {
while (central.connected()) {
if (ledCharacteristic.written()) {
if (ledCharacteristic.value()) {
digitalWrite(LED_BUILTIN, HIGH);
}
else{
digitalWrite(LED_BUILTIN, LOW);
}
}
}
}
}
Now we can compile and upload this program to the board as described in previous sections.
To verify that our application works as expected, we can use any Android smartphone with
BLE feature and Nordic nRF Connect tool.
At first, we need to scan all advertising BLE devices and connect to the device called
Nordic NRF52 DK. After a successful connection to the board, we should see one "Unknown
Service" with one "Unknown Characteristic" fields: [image]
To switch the LED on or off we just need write 0 or 1 as UINT8 to the BLE characteristic:
[image]
Conclusion
Now we have a project template for Nordic nRF52-DK board that we can use as a boilerplate
for the next projects.
Zephyr and Nordic nRF52-DK: debugging, unit testing, project analysis
The goal of this tutorial is to demonstrate how simple it is to use ide_vscode to develop,
run and debug a simple Bluetooth project using framework_zephyr framework for the Nordic
nRF52-DK board.
• Level: Intermediate
• Platforms: Windows, Mac OS X, Linux
Requirements:
• Downloaded and installed ide_vscode
• Install drivers for debugging_tool_jlink debug tool
• Nordic nRF52-DK development board
Contents
• Setting Up the Project
• Adding Code to the Generated Project
• Compiling and Uploading the Firmware
• Debugging the Firmware
• Writing Unit Tests
• Project Inspection
• Conclusion
Setting Up the Project
1. Click on "PlatformIO Home" button on the bottom PlatformIO Toolbar:
[image]
2. Click on "New Project", select Nordic nRF52-DK as the development board,
framework_zephyr as the framework and a path to the project location (or use the
default one):
[image]
Adding Code to the Generated Project
1. Create a new file main.c in projectconf_pio_src_dir folder and add the following code:
//
// Copyright (c) 2015-2016 Intel Corporation
//
// SPDX-License-Identifier: Apache-2.0
//
#include <zephyr/types.h>
#include <stddef.h>
#include <sys/printk.h>
#include <sys/util.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/hci.h>
#define DEVICE_NAME CONFIG_BT_DEVICE_NAME
#define DEVICE_NAME_LEN (sizeof(DEVICE_NAME) - 1)
// Set Advertisement data. Based on the Eddystone specification:
// https://github.com/google/eddystone/blob/master/protocol-specification.md
// https://github.com/google/eddystone/tree/master/eddystone-url
static const struct bt_data ad[] = {
BT_DATA_BYTES(BT_DATA_FLAGS, BT_LE_AD_NO_BREDR),
BT_DATA_BYTES(BT_DATA_UUID16_ALL, 0xaa, 0xfe),
BT_DATA_BYTES(BT_DATA_SVC_DATA16,
0xaa, 0xfe,
0x10, // Eddystone-URL frame type
0x00, // Calibrated Tx power at 0m
0x00, // URL Scheme Prefix http://www.
'z', 'e', 'p', 'h', 'y', 'r',
'p', 'r', 'o', 'j', 'e', 'c', 't',
0x08) // .org
};
// Set Scan Response data
static const struct bt_data sd[] = {
BT_DATA(BT_DATA_NAME_COMPLETE, DEVICE_NAME, DEVICE_NAME_LEN),
};
static void bt_ready(int err)
{
if (err) {
printk("Bluetooth init failed (err %d)\n", err);
return;
}
printk("Bluetooth initialized\n");
// Start advertising
err = bt_le_adv_start(BT_LE_ADV_NCONN, ad, ARRAY_SIZE(ad),
sd, ARRAY_SIZE(sd));
if (err) {
printk("Advertising failed to start (err %d)\n", err);
return;
}
printk("Beacon started\n");
}
void main(void)
{
int err;
printk("Starting Beacon Demo\n");
// Initialize the Bluetooth Subsystem
err = bt_enable(bt_ready);
if (err) {
printk("Bluetooth init failed (err %d)\n", err);
}
}
2. By default Bluetooth feature is disabled, we can enable it by creating a new file
prj.conf in zephyr folder and adding the following lines:
CONFIG_BT=y
CONFIG_BT_DEBUG_LOG=y
CONFIG_BT_DEVICE_NAME="Test beacon"
Compiling and Uploading the Firmware
1. To compile the project use one of the following options:
• Build option from the Project Tasks menu
• Build button in ide_vscode_toolbar
• Task Menu Tasks: Run Task... > PlatformIO: Build or in ide_vscode_toolbar
• Command Palette View: Command Palette > PlatformIO: Build
• Hotkeys cmd-alt-b / ctrl-alt-b:
[image]
2. If everything went well, we should see a successful result message in the terminal
window:
[image]
3. To upload the firmware to the board we can use the following options:
• Upload option from the Project Tasks menu
• Upload button in ide_vscode_toolbar
• Command Palette View: Command Palette > PlatformIO: Upload
• Task Menu Tasks: Run Task... > PlatformIO: Upload
• Hotkeys cmd-alt-u / ctrl-alt-u:
[image]
4. Connect the board to your computer and update the default monitor speed to 115200 in
platformio.ini file:
[env:hifive1-revb]
platform = sifive
board = hifive1-revb
framework = zephyr
monitor_speed = 115200
5. Open Serial Monitor to observe the output from the board:
[image]
6. If everything went well, the board should be visible as a beacon:
[image]
Debugging the Firmware
Since Nordic nRF52-DK includes an onboard debug probe we can use piodebug without any
configuration.
1. To start a debug session we can use the following options:
• Debug: Start debugging from the top menu
• Start Debugging option from Quick Access menu
• Hotkey button F5:
[image]
2. We can walk through the code using control buttons, set breakpoints, add variables to
Watch window:
[image]
Writing Unit Tests
NOTE:
Functions setUp and tearDown are used to initialize and finalize test conditions.
Implementations of these functions are not required for running tests but if you need
to initialize some variables before you run a test, you use the setUp function and if
you need to clean up variables you use tearDown function.
For the sake of simplicity, let's create a small library called calculator, implement
several basic functions add, sub, mul, div and test them using unit_testing engine.
1. PlatformIO uses a unit testing framework called Unity. Unity is not compatible with C
library implemented in the framework. Let's enable standard version of newlib C library
in prj.conf file using the following config:
CONFIG_NEWLIB_LIBC=y
2. Create a new folder calculator in the lib folder and add two new files calculator.h and
calculator.c with the following contents:
calculator.h:
#ifndef _CALCULATOR_H_
#define _CALCULATOR_H_
#ifdef __cplusplus
extern "C" {
#endif
int add (int a, int b);
int sub (int a, int b);
int mul (int a, int b);
int div (int a, int b);
#ifdef __cplusplus
}
#endif
#endif // _CALCULATOR_H_
calculator.c:
#include "calculator.h"
int add(int a, int b)
{
return a + b;
}
int sub(int a, int b)
{
return a - b;
}
int mul(int a, int b)
{
return a * b;
}
3. Create a new file `test_calc.c to the folder test and add basic tests for calculator
library:
#include <calculator.h>
#include <unity.h>
void test_function_calculator_addition(void) {
TEST_ASSERT_EQUAL(32, add(25, 7));
}
void test_function_calculator_subtraction(void) {
TEST_ASSERT_EQUAL(20, sub(23, 3));
}
void test_function_calculator_multiplication(void) {
TEST_ASSERT_EQUAL(50, mul(25, 2));
}
void test_function_calculator_division(void) {
TEST_ASSERT_EQUAL(32, div(100, 3));
}
void main() {
UNITY_BEGIN();
RUN_TEST(test_function_calculator_addition);
RUN_TEST(test_function_calculator_subtraction);
RUN_TEST(test_function_calculator_multiplication);
RUN_TEST(test_function_calculator_division);
UNITY_END();
}
4. Let's run tests on the board and check the results. There should be a problem with
test_function_calculator_division test:
[image]
5. Let's fix the incorrect expected value, run tests again. After processing the results
should be correct:
[image]
Project Inspection
For illustrative purposes, let's imagine we need to find a function with the biggest
memory footprint. Also, let's introduce a bug to our project so piocheck can report it.
1. Open PlatformIO Home and navigate to Inspect section, select the current project and
press Inspect button:
[image]
2. Project statistics:
[image]
3. The biggest function:
[image]
4. Possible bugs:
[image]
Conclusion
Now we have a project template for Nordic Nordic nRF52-DK board that we can use as a
boilerplate for the next projects.
RISC-V ASM Video Tutorial
An introduction to using platform_sifive and Assembly language on the SiFive
board_sifive_hifive1 by Martin Fink, Chief Technology Officer at Western Digital.
Source Files
A demo source code is published on Github:
https://github.com/martin-robert-fink/superBlink.git
It is already pre-configured PlatformIO project:
• Clone it or download
• Open in ide_vscode
• Happy coding and debugging!
Video Collection
.INDENT 0.0
• Part 1 of 12 | Introduction
• Part 2 of 12 | Setting Up
• Part 3 of 12 | Tour PlatformIO
• Part 4 of 12 | C Code Wrapper
• Part 5 of 12 | HiFive Docs
• Part 6 of 12 | Understanding GPIO
• Part 7 of 12 | setupGPIO
• Part 8 of 12 | Debug setupGPIO
• Part 9 of 12 | setLED
• Part 10 of 12 | Debug setLED
• Part 11 of 12 | Delay
• Part 12 of 12 | Final and Conclusion
Project Examples
Pre-configured projects with source code are located in PlatformIO Examples repository.
Community Projects
• PlatformIO DIY Projects & Tutorials at Hackster.io
Community Video Tutorials
• PlatformIO Video Collection on YouTube
• Next-generation IDE for your RISC-V Product in 20 Minutes by CEO of PlatformIO
• Use the PlatformIO Debugger on the ESP32 Using an ESP-prog
• RISC-V ASM Tutorial
• PlatformIO for Arduino, ESP8266, and ESP32 Tutorial
• Free Inline Debugging for ESP32 and Arduino Sketches
• PlatformIO или прощай, Arduino IDE
• Отладка ESP32 в PlatformIO
• A Better Arduino IDE - Getting Started with PlatformIO
• PlatformIO - Using External Libraries
platformio.ini (Project Configuration File)
Each PlatformIO project has a configuration file named platformio.ini in the root
directory for the project. This is a INI-style file.
platformio.ini has sections (each denoted by a [header]) and key / value pairs within the
sections. Lines beginning with ; are ignored and may be used to provide comments.
Multiple value options can be specified in two ways:
1. Split values with ", " (comma + space)
2. Multi-line format, where each new line starts with at least two spaces
There are two required sections:
• piocore settings: projectconf_section_platformio
• Environment settings: projectconf_section_env
The other sections are optional to include. Here are the allowed sections and their
allowed contents:
Section [platformio]
• Generic options
• description
• default_envs
• extra_configs
• Directory options
• core_dir
• globallib_dir
• platforms_dir
• packages_dir
• cache_dir
• build_cache_dir
• workspace_dir
• build_dir
• libdeps_dir
• include_dir
• src_dir
• lib_dir
• data_dir
• test_dir
• boards_dir
• shared_dir
The platform.ini platformio section is used for overriding the default configuration
options for piocore.
NOTE:
Relative path is allowed for directory option:
• ~ will be expanded to user's home directory
• ../ or ..\ go up to one folder
There is a $PROJECT_HASH template variable. You can use it in a directory path. It will
by replaced by a SHA1[0:10] hash of the full project path. This is very useful to
declare a global storage for project workspaces. For example,
/tmp/pio-workspaces/$PROJECT_HASH (Unix) or $[sysenv.TEMP}/pio-workspaces/$PROJECT_HASH
(Windows). You can set a global workspace directory using the system environment
variable PLATFORMIO_WORKSPACE_DIR.
See the available directory ***_dir options below.
Generic options
description
Type: String | Multiple: No
Short description of the project. PlatformIO uses it for piohome in the multiple places.
default_envs
Type: String | Multiple: Yes
The cmd_run command processes all environments [env:***] by default if the platformio run
--environment option is not specified. default_envs allows one to define which
environments that should be processed by default.
Also, piodebug checks this option when looking for debug environment.
This option can also be configured by the global environment variable
PLATFORMIO_DEFAULT_ENVS.
Example:
[platformio]
default_envs = uno, nodemcu
[env:uno]
platform = atmelavr
framework = arduino
board = uno
[env:nodemcu]
platform = espressif8266
framework = arduino
board = nodemcu
[env:teensy31]
platform = teensy
framework = arduino
board = teensy31
[env:lpmsp430g2553]
platform = timsp430
framework = arduino
board = lpmsp430g2553
build_flags = -D LED_BUILTIN=RED_LED
extra_configs
New in version 4.0.
Type: String (Pattern) | Multiple: Yes
This option allows extending a base projectconf with extra configuration files. The format
and rules are the same as for the projectconf. A name of the configuration file can be
any.
extra_configs can be a single path to an extra configuration file or a list of them.
Please note that you can use Unix shell-style wildcards:
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
NOTE:
If you declare the same pair of "group" + "option" in an extra configuration file which
was previously declared in a base projectconf, it will be overwritten with a value from
extra configuration.
Example
Base "platformio.ini"
[platformio]
extra_configs =
extra_envs.ini
extra_debug.ini
; Global data for all [env:***]
[env]
platform = espressif32
framework = espidf
; Custom data group
; can be use in [env:***] via ${common.***}
[common]
debug_flags = -D RELEASE
lib_flags = -lc -lm
[env:esp-wrover-kit]
board = esp-wrover-kit
build_flags = ${common.debug_flags}
"extra_envs.ini"
[env:esp32dev]
board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}
[env:lolin32]
platform = espressif32
framework = espidf
board = lolin32
build_flags = ${common.debug_flags}
"extra_debug.ini"
# Override base "common.debug_flags"
[common]
debug_flags = -D DEBUG=1
[env:lolin32]
build_flags = -Og
After a parsing process, configuration state will be the next:
[common]
debug_flags = -D DEBUG=1
lib_flags = -lc -lm
[env:esp-wrover-kit]
platform = espressif32
framework = espidf
board = esp-wrover-kit
build_flags = ${common.debug_flags}
[env:esp32dev]
platform = espressif32
framework = espidf
board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}
[env:lolin32]
platform = espressif32
framework = espidf
board = lolin32
build_flags = -Og
Directory options
core_dir
New in version 4.0.
Type: DirPath | Multiple: No
The core_dir variable points out the directory used for all development platform packages
(toolchains, frameworks, SDKs, upload and debug tools), global libraries for ldf, and
other PlatformIO Core service data. The size of this folder will depend on the number of
installed development platforms.
The default value is the user's home directory:
• Unix ~/.platformio
• Windows %HOMEPATH%\.platformio
This option can also be configured by the global environment variable PLATFORMIO_CORE_DIR.
Example:
[platformio]
core_dir = /path/to/custom/pio-core/storage
globallib_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "core_dir/lib"
Global library storage for PlatfrmIO projects and librarymanager where ldf looks for
dependencies.
This option can also be configured by the global environment variable
PLATFORMIO_GLOBALLIB_DIR.
platforms_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "core_dir/platforms"
Global storage where PlatformIO Package Manager installs platforms.
This option can also be configured by the global environment variable
PLATFORMIO_PLATFORMS_DIR.
packages_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "core_dir/packages"
Global storage where PlatformIO Package Manager installs platforms dependencies
(toolchains, frameworks, SDKs, upload and debug tools).
This option can also be configured by the global environment variable
PLATFORMIO_PACKAGES_DIR.
cache_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "core_dir/cache"
piocore uses this folder to store caching information (requests to PlatformIO Registry,
downloaded packages and other service information).
To reset a cache, please run cmd_update command.
This option can also be configured by the global environment variable
PLATFORMIO_CACHE_DIR.
build_cache_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: None (Disabled)
piocore uses this folder to store derived files from a build system (objects, firmwares,
ELFs). These files are shared between all build environments. To speed up a build process,
you can use the same cache folder between different projects if they depend on the same
development platform and framework.
This option can also be configured by the global environment variable
PLATFORMIO_BUILD_CACHE_DIR.
The example of projectconf below instructs PlatformIO Build System to check
build_cache_dir for already compiled objects for framework_stm32cube and project source
files. The cached object will not be used if the original source file was modified or
build environment has a different configuration (new build flags, etc):
[platformio]
; Set a path to a cache folder
build_cache_dir =
; Examples:
; (Unix) build_cache_dir = /path/to/cache/folder
; (Windows) build_cache_dir = C:/path/to/cache/folder
[env:bluepill_f103c6]
platform = ststm32
framework = stm32cube
board = bluepill_f103c6
[env:nucleo_f411re]
platform = ststm32
framework = stm32cube
board = nucleo_f411re
workspace_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "Project/.pio"
The path to a project workspace directory where PlatformIO keeps by default compiled
objects, static libraries, firmwares, and external library dependencies. It is used by
these options:
• build_dir
• libdeps_dir.
The default value is .pio and means that folder is located in the root of project.
This option can also be configured by the global environment variable
PLATFORMIO_WORKSPACE_DIR.
build_dir
WARNING:
PLEASE DO NOT EDIT FILES IN THIS FOLDER. PlatformIO will overwrite your changes on the
next build. THIS IS A CACHE DIRECTORY.
Type: DirPath | Multiple: No | Default: "workspace_dir/build"
PlatformIO Build System uses this folder for project environments to store compiled object
files, static libraries, firmwares and other cached information. It allows PlatformIO to
build source code extremely fast!
You can delete this folder without any risk! If you modify projectconf, then PlatformIO
will remove this folder automatically. It will be created on the next build operation.
This option can also be configured by the global environment variable
PLATFORMIO_BUILD_DIR.
NOTE:
If you have any problems with building your project environments which are defined in
projectconf, then TRY TO DELETE this folder. In this situation you will remove all
cached files without any risk. Also, you can use "clean" target for platformio run
--target command.
libdeps_dir
Type: DirPath | Multiple: No | Default: "workspace_dir/libdeps"
Internal storage where librarymanager will install project dependencies
(projectconf_lib_deps).
This option can also be configured by the global environment variable
PLATFORMIO_LIBDEPS_DIR.
include_dir
Type: DirPath | Multiple: No | Default: "Project/include"
The path to project's default header files. PlatformIO uses it for the cmd_run command.
The default value is include meaning an include directory located under the root directory
of the project. This path will be added to CPPPATH of the build environment.
If you need to add extra include directories to CPPPATH scope, please use
projectconf_build_flags with -I /path/to/extra/dir option.
This option can also be configured by the global environment variable
PLATFORMIO_INCLUDE_DIR.
src_dir
Type: DirPath | Multiple: No | Default: "Project/src"
The path to the project's directory with source code. PlatformIO uses it for the cmd_run
command. The default value is src meaning a src directory located in the root directory of
the project.
This option can also be configured by the global environment variable PLATFORMIO_SRC_DIR.
NOTE:
This option is useful for people who migrate from Arduino IDE where the source
directory should have the same name as the main source file. See example project with
own source directory.
lib_dir
Type: DirPath | Multiple: No | Default: "Project/lib"
You can put your own/private libraries here. The source code of each library should be
placed in separate directory, like lib/private_lib/[here are source files]. This directory
has the highest priority for ldf.
The default value is lib, meaning a lib directory located in the root of the project.
This option can also be configured by the global environment variable PLATFORMIO_LIB_DIR.
For example, see how the Foo and Bar libraries are organized:
|--lib
| |--Bar
| | |--docs
| | |--examples
| | |--src
| | |- Bar.c
| | |- Bar.h
| |--Foo
| | |- Foo.c
| | |- Foo.h
|- platformio.ini
|--src
|- main.c
Then in src/main.c you should use:
#include <Foo.h>
#include <Bar.h>
// rest of H/C/CPP code
PlatformIO will find your libraries automatically, configure the preprocessor's include
paths and build them.
data_dir
Type: DirPath | Multiple: No | Default: "Project/data"
Data directory to store contents and platform_espressif_uploadfs. The default value is
data that means that folder is located in the root of the project.
This option can also be configured by the global environment variable PLATFORMIO_DATA_DIR.
test_dir
Type: DirPath | Multiple: No | Default: "Project/test"
The directory where unit_testing engine will look for the tests. The default value is
test, meaning a test directory located in the root of the project.
This option can also be configured by the global environment variable PLATFORMIO_TEST_DIR.
boards_dir
Type: DirPath | Multiple: No | Default: "Project/boards"
The location of project-specific board definitions. Each project may choose a suitable
directory name. The default value is boards, meaning a "boards" directory located in the
root of the project.
By default, PlatformIO looks for boards in this order:
1. Project boards_dir (as defined by this setting)
2. Global core_dir/boards
3. Development platform core_dir/platforms/*/boards.
This option can also be configured by the global environment variable
PLATFORMIO_BOARDS_DIR.
shared_dir
New in version 4.0.
Type: DirPath | Multiple: No | Default: "Project/shared"
pioremote uses this folder to synchronize extra files between remote machine. For example,
you can share projectconf_extra_scripts.
Please note that these folders are automatically shared between remote machine with
platformio remote run --force-remote or platformio remote test --force-remote commands:
• lib_dir
• include_dir
• src_dir
• boards_dir
• data_dir
• test_dir
The default value is shared, meaning a directory named "shared" located in the root of the
project.
This option can also be configured by the global environment variable
PLATFORMIO_SHARED_DIR.
Section [env]
• Common [env]
• Environment [env:NAME]
• Options
Each project may have multiple configuration environments defining the available project
tasks for building, programming, debugging, unit testing, device monitoring, library
dependencies, etc. The configuration environments are declared using [env] sections in
projectconf.
The allowed options are listed under Options.
Common [env]
New in version 4.0.
An optional configuration environment with common options that will be shared between all
[env:NAME] environments in the platform.ini file. It is very useful if the configuration
file has a lot of environments [env:NAME] and they share common settings.
For example:
[env]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
lib_deps = Dep1, Dep2
[env:release]
build_flags = -D RELEASE
lib_deps =
${env.lib_deps}
Dep3
[env:debug]
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom
In this example we have two configuration environments release and debug. This is
equivalent to duplicating all options as shown below:
[env:release]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
build_flags = -D RELEASE
lib_deps = Dep1, Dep2, Dep3
[env:debug]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom
Environment [env:NAME]
A section with an env: prefix defines a working environment for cmd_run, cmd_test,
cmd_check, cmd_debug and other commands. Multiple [env:NAME] environments with different
NAME are allowed. Every project must define at least one working environment.
Each environment must have a unique NAME. The valid chars for NAME are letters a-z,
numbers 0-9, special char _ (underscore). For example, [env:hello_world].
If you have multiple working environments and you need to process only a few of them, the
commands mentioned above accept the -e, --environment option to select a subset of the
working environments to process. The [platformio] projectconf_pio_default_envs option can
be used to define a default set of working environments for the commands to process.
Options
Platform options
• platform
• platform_packages
• framework
• board
• board_build.mcu
• board_build.f_cpu
• board_build.ldscript
• More options
platform
Type: String | Multiple: No
platforms name.
PlatformIO allows one to use specific version of platform using Semantic Versioning
(X.Y.Z=MAJOR.MINOR.PATCH) or VCS (Git, Mercurial and Subversion).
Version specifications can take any of the following forms:
• 1.2.3: an exact version number. Use only this exact version
• ^1.2.3: any compatible version (exact version for 1.x.x versions)
• ~1.2.3: any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3: any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0: any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
Other forms are the same as for the cmd_platform_install command.
Examples:
[env:the_latest_version]
platform = atmelavr
[env:exact_version]
platform = atmelavr@1.2.3
[env:specific_major_version]
platform = atmelavr@^1.2.3
[env:specific_major_and_minor_version]
platform = atmelavr@~1.2.3
[env:development_verion_by_git]
platform = https://github.com/platformio/platform-ststm32.git
[env:custom_git_branch]
platform = https://github.com/platformio/platform-espressif8266.git#feature/stage
[env:specific_git_commit]
platform = https://github.com/platformio/platform-espressif8266.git#921855a9c530082efddb5d48b44c3f4be0e2dfa2
platform_packages
New in version 4.0.
Type: String | Multiple: Yes
Configure custom packages per a build environment. You can also override default packages
by platforms using the same name. Packages will be installed in
projectconf_pio_packages_dir.
Examples:
[env:override_default_toolchain]
platform = atmelavr
platform_packages =
; use GCC AVR 5.0+
toolchain-gccarmnoneeabi@>1.50000.0
[env:override_framework]
platform = espressif8266
platform_packages =
; use upstream Git version
framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git
[env:external_package]
platform = ststm32
platform_packages =
; latest openOCD from PlatformIO Package Registry
tool-openocd
; source code of ST-Link
tool-stlink-source @ https://github.com/texane/stlink.git
framework
Type: String | Multiple: Yes
frameworks name.
board
Type: String (ID) | Multiple: No
PlatformIO has pre-configured settings for the most popular boards:
• build configuration
• upload configuration
• debugging configuration
• connectivity information, etc.
You can find a valid board ID in boards catalog, Boards Explorer or cmd_boards command.
board_build.mcu
Type: String | Multiple: No
board_build.mcu is a microcontroller(MCU) type that is used by compiler to recognize MCU
architecture. The correct type of board_build.mcu depends on platform library. For
example, the list of board_build.mcu for "megaAVR Devices" is described here.
The full list of board_build.mcu for the popular embedded platforms you can find in Boards
section of platforms. See "Microcontroller" column.
board_build.f_cpu
Type: Integer | Multiple: No
The option board_build.f_cpu is used to define MCU frequency (Hertz, Clock). A format of
this option is C-like long integer value with L suffix. The 1 Hertz is equal to 1L, then
16 MHz (Mega Hertz) is equal to 16000000L.
The full list of board_build.f_cpu for the popular embedded platforms you can find in
Boards section of platforms. See "Frequency" column. You can overclock a board by
specifying a board_build.f_cpu value other than the default.
board_build.ldscript
Type: String | Multiple: No
Path to the linker script to be used instead of the one defined by a framework. This is
useful for specifying a modified linker script, for example, when an application requires
a special memory section for a bootloader.
More options
You can override any board option declared in manifest file using the next format
board_{OBJECT.PATH}, where {OBJECT.PATH} is an object path in JSON manifest. Please
navigate to "boards" folder of PlatfomIO development platforms and open JSON file to list
all available options.
For example, Manifest: Espressif ESP32 Dev Module:
[env:custom_board_options]
; Custom CPU Frequency
board_build.f_cpu = 160000000L
; Custom FLASH Frequency
board_build.f_flash = 80000000L
; Custom FLASH Mode
board_build.flash_mode = qio
; Custom linker script
board_build.ldscript = /path/to/ldscript.ld
; Custom maximum program size
board_upload.maximum_size = 1310720
Build options
• build_type
• build_flags
• Built-in Variables
• Dynamic build flags
• src_build_flags
• build_unflags
• src_filter
• targets
build_type
New in version 4.0.
Type: String | Multiple: No | Default: release
See extended documentation for build_configurations.
build_flags
Type: String | Multiple: Yes
These flags/options affect the preprocessing, compilation, assembly and linking processes
for C and C++ code. All compiler and linker flags can be used. Here is a list of some
common options.
In spite of the name, CPPDEFINES rows also applies to the C compiler.
┌───────────────────┬────────────────────────┬──────────────────────────┐
│Format │ Affects build variable │ Description │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-D name │ CPPDEFINES │ Predefine name as a │
│ │ │ macro, with definition │
│ │ │ 1. │
└───────────────────┴────────────────────────┴──────────────────────────┘
│-D name=definition │ CPPDEFINES │ The contents of │
│ │ │ definition are tokenized │
│ │ │ and processed as if they │
│ │ │ appeared during │
│ │ │ translation phase three │
│ │ │ in a #define directive. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-U name │ CPPDEFINES │ Cancel any previous │
│ │ │ definition of name, │
│ │ │ either built in or │
│ │ │ provided with a -D │
│ │ │ option. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Wp,option │ CPPFLAGS │ Bypass the compiler │
│ │ │ driver and pass option │
│ │ │ directly through to the │
│ │ │ preprocessor │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Wall │ CCFLAGS │ Turn on all optional │
│ │ │ warnings which are │
│ │ │ desirable for normal │
│ │ │ code. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Werror │ CCFLAGS │ Make all warnings into │
│ │ │ hard errors. With this │
│ │ │ option, if any source │
│ │ │ code triggers warnings, │
│ │ │ the compilation will be │
│ │ │ aborted. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-w │ CCFLAGS │ Suppress all warnings, │
│ │ │ including those which │
│ │ │ GNU CPP issues by │
│ │ │ default. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-include file │ CCFLAGS │ Process file as if │
│ │ │ #include "file" appeared │
│ │ │ as the first line of the │
│ │ │ primary source file. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Idir │ CPPPATH │ Add the directory dir to │
│ │ │ the list of directories │
│ │ │ to be searched for │
│ │ │ header files. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Wa,option │ ASFLAGS, CCFLAGS │ Pass option as an option │
│ │ │ to the assembler. If │
│ │ │ option contains commas, │
│ │ │ it is split into │
│ │ │ multiple options at the │
│ │ │ commas. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Wl,option │ LINKFLAGS │ Pass option as an option │
│ │ │ to the linker. If option │
│ │ │ contains commas, it is │
│ │ │ split into multiple │
│ │ │ options at the commas. │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-llibrary │ LIBS │ Search the library named │
│ │ │ library when linking │
├───────────────────┼────────────────────────┼──────────────────────────┤
│-Ldir │ LIBPATH │ Add directory dir to the │
│ │ │ list of directories to │
│ │ │ be searched for -l. │
└───────────────────┴────────────────────────┴──────────────────────────┘
This option can also be set by global environment variable PLATFORMIO_BUILD_FLAGS.
For more detailed information about available flags/options go to:
• Options to Request or Suppress Warnings
• Options for Debugging Your Program
• Options That Control Optimization
• Options Controlling the Preprocessor
• Passing Options to the Assembler
• Options for Linking
• Options for Directory Search
Examples:
[env:specific_defines]
build_flags =
-DFOO -DBAR=1
-D BUILD_ENV_NAME=$PIOENV
-D CURRENT_TIME=$UNIX_TIME
-DFLOAT_VALUE=1.23457e+07
[env:string_defines]
build_flags =
-DHELLO="World!"
'-DWIFI_PASS="My password"'
; Password with special chars: My pass'word
-DWIFI_PASS=\"My\ pass\'word\"
[env:specific_inclibs]
build_flags =
-I/opt/include
-L/opt/lib
-lfoo
[env:ignore_incremental_builds]
; We dynamically change the value of "LAST_BUILD_TIME" macro,
; PlatformIO will not cache objects
build_flags = -DLAST_BUILD_TIME=$UNIX_TIME
NOTE:
If you need to control build flags that are specific for debug configuration please
refer to projectconf_debug_build_flags.
Built-in Variables
You can inject the built-in variables into your build flags, such as:
• $PYTHONEXE, full path to current Python interpreter
• $UNIX_TIME, current time in Unix format
• $PIOENV, name of build environment from projectconf
• $PIOPLATFORM, name of development platform
• $PIOFRAMEWORK, a list of frameworks
• $PROJECT_DIR, project directory
• $PROJECT_CORE_DIR, PlatformIO Core directory, see projectconf_pio_core_dir
• $PROJECT_BUILD_DIR, project build directory per all environments
• $BUILD_DIR, build directory per current environment
See the full list of PlatformIO variables.
Please use target envdump for the platformio run --target command to see ALL variable
values for a build environment.
Dynamic build flags
PlatformIO allows users to run an external command/script which outputs build flags into
STDOUT by prepending the shell command with a ! character. PlatformIO will automatically
replace commands with their output when appending flags to build environments.
You can use any shell or programming language.
This external command will be called on each cmd_run command before building/uploading
process.
Use cases:
• Macro with the latest VCS revision/tag "on-the-fly"
• Generate dynamic headers (*.h)
• Process media content before generating SPIFFS image
• Make some changes to source code or related libraries
NOTE:
If you need more advanced control and would like to apply changes to a PlatformIO Build
System environment, please refer to projectconf_advanced_scripting.
Example:
[env:generate_flags_with_external_command]
build_flags = !cmd_or_path_to_script
; Unix only, get output from internal command
build_flags = !echo "-DSOME_MACRO="$(some_cmd arg1 --option1)
Use Case: Create a "PIO_SRC_REV" macro with the latest Git revision
This example includes a separate file named git_rev_macro.py, to be placed in the same
directory as platformio.ini.
platformio.ini:
[env:git_revision_macro]
build_flags = !python git_rev_macro.py
git_rev_macro.py:
import subprocess
revision = subprocess.check_output(["git", "rev-parse", "HEAD"]).strip()
print("-DPIO_SRC_REV=%s" % revision)
src_build_flags
Type: String | Multiple: Yes
An option src_build_flags has the same behavior as build_flags but will be applied only
for project source files in the projectconf_pio_src_dir directory.
This option can also be set by the global environment variable PLATFORMIO_SRC_BUILD_FLAGS.
build_unflags
Type: String | Multiple: Yes
Selectively remove base/initial flags that were set by the development platform.
[env:unflags]
build_unflags = -Os -std=gnu++11
build_flags = -O2
src_filter
Type: String (Templates) | Multiple: Yes
This option allows one to specify which source files should be included or excluded from
projectconf_pio_src_dir for a build process. Filter supports two templates:
• +<PATH> include template
• -<PATH> exclude template
PATH is relative to projectconf_pio_src_dir. All patterns will be applied in their order
of definition. GLOB Patterns are allowed.
By default, src_filter is predefined to +<*> -<.git/> -<.svn/> -<example/> -<examples/>
-<test/> -<tests/>, meaning "include ALL files, then exclude the .git and svn repository
folders and the example ... folder.
This option can also be set by the global environment variable PLATFORMIO_SRC_FILTER.
targets
Type: String | Multiple: Yes
A list of targets which will be processed by the cmd_run command by default. You can enter
more than one target, if separated by comma+space ", ".
The list with available targets is located in platformio run --target.
Examples
1. Build a project using Release Configuration, upload the firmware, and start Serial
Monitor automatically:
[env:upload_and_monitor]
targets = upload, monitor
2. Build a project using Debug Configuration.
Tip! You can use these targets like an option to platformio run --target command. For
example:
# clean project
platformio run -t clean
# dump current build environment
platformio run --target envdump
When no targets are defined, PlatformIO will build only sources by default.
Library options
SEE ALSO:
Please make sure to read ldf guide first.
• lib_deps
• lib_ignore
• lib_extra_dirs
• lib_ldf_mode
• lib_compat_mode
• lib_archive
lib_deps
SEE ALSO:
Please make sure to read ldf guide first.
Type: String | Multiple: Yes
Specify project dependencies that should be installed automatically to
projectconf_pio_libdeps_dir before environment processing.
If you have multiple build environments that depend on the same libraries, you can use
projectconf_dynamic_vars to use common configuration.
Valid forms
; one line definition (comma + space)
[env:myenv]
lib_deps = LIBRARY_1, LIBRARY_2, LIBRARY_N
; multi-line definition
[env:myenv2]
lib_deps =
LIBRARY_1
LIBRARY_2
LIBRARY_N
The each line with LIBRARY_1... LIBRARY_N will be passed automatically to cmd_lib_install
command. Please follow to cmd_lib_install for detailed documentation about possible
values.
Example:
[env:myenv]
lib_deps =
13
PubSubClient
ArduinoJson@~5.6,!=5.4
https://github.com/gioblu/PJON.git#v2.0
me-no-dev/ESPAsyncTCP
IRremoteESP8266=https://github.com/markszabo/IRremoteESP8266/archive/master.zip
lib_ignore
SEE ALSO:
Please make sure to read ldf guide first.
Type: String | Multiple: Yes
Specify libraries which should be ignored by Library Dependency Finder.
The correct value for this option is a library name (not folder name). You will see these
names in "Library Dependency Graph" when building a project between < and > symbols.
Example:
Build output
...
Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF MODES: FINDER(chain+) COMPATIBILITY(soft)
Collected 54 compatible libraries
Scanning dependencies...
Dependency Graph
|-- <Hash> v1.0
|-- <AsyncMqttClient> v0.8.2
| |-- <ESPAsyncTCP> v1.1.3
|-- <ESP8266WiFi> v1.0
|-- <ESP Async WebServer> v1.1.1
| |-- <ESPAsyncTCP> v1.1.3
| |-- <ESP8266WiFi> v1.0
| |-- <Hash> v1.0
| |-- <ArduinoJson> v5.13.1
|-- <ArduinoJson> v5.13.1
|-- <DNSServer> v1.1.0
| |-- <ESP8266WiFi> v1.0
|-- <Ticker> v1.0
....
platformio.ini
[env:myenv]
; Single line
lib_ignore = AsyncMqttClient, DNSServer
; Multi-line
lib_ignore =
AsyncMqttClient
ESP Async WebServer
lib_extra_dirs
SEE ALSO:
Please make sure to read ldf guide first.
Type: DirPath | Multiple: Yes
A list with extra directories/storages where ldf will look for dependencies.
This option can also be set by global environment variable PLATFORMIO_LIB_EXTRA_DIRS.
WARNING:
This is a not direct path to a library with source code. It should be a path to storage
that contains libraries grouped by folders. For example, D:\PlatformIO\extra\libraries
but not D:\PlatformIO\extra\libraries\FooLibrary.
Example:
[env:myenv]
lib_extra_dirs =
/common/libraries
/iot/libraries
lib_ldf_mode
SEE ALSO:
Please make sure to read ldf guide first.
Type: String | Multiple: No | Default: chain
This option specifies how does Library Dependency Finder should analyze dependencies
(#include directives). See ldf_mode for details and available options.
Example:
[env:myenv]
; evaluate C/C++ Preprocessor conditional syntax
lib_ldf_mode = chain+
lib_compat_mode
SEE ALSO:
Please make sure to read ldf guide first.
Type: String | Multiple: No | Default: soft
Library compatibility mode allows one to control strictness of Library Dependency Finder.
See ldf_compat_mode for details and available options..
By default, this value is set to lib_compat_mode = soft and means that LDF will check only
for framework compatibility.
Example:
[env:myenv]
; Checks for the compatibility with frameworks and dev/platforms
lib_compat_mode = strict
lib_archive
Type: Bool (yes or no) | Multiple: No | Default: yes
Create an archive (*.a, static library) from the object files and link it into a firmware
(program). This is default behavior of PlatformIO Build System (lib_archive = yes).
Setting lib_archive = no will instruct PIO Build System to link object files directly
(in-line). This could be useful if you need to override weak symbols defined in framework
or other libraries.
You can disable library archiving per a custom library using libjson_archive field in
library_config manifest.
Example:
[env:myenv]
lib_archive = no
Upload options
• upload_port
• upload_protocol
• upload_speed
• upload_flags
• upload_resetmethod
• upload_command
upload_port
Type: String (Pattern) | Multiple: No
This option is used by "uploader" tool when sending firmware to board via upload_port. For
example,
• /dev/ttyUSB0 - Serial port (Unix-based OS)
• COM3 - Serial port (Windows OS)
• 192.168.0.13 - IP address when using OTA
• /media/disk - physical path to media disk/flash drive (framework_mbed enabled boards)
• D: - physical path to media disk/flash drive (Windows OS).
If upload_port isn't specified, then PlatformIO will try to detect it automatically.
To print all available serial ports please use cmd_device_list command.
This option can also be set by global environment variable PLATFORMIO_UPLOAD_PORT.
Please note that you can use Unix shell-style wildcards:
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
Example
[env:uno]
platform = atmelavr
framework = arduino
; any port that starts with /dev/ttyUSB
upload_port = /dev/ttyUSB*
; COM1 or COM3
upload_port = COM[13]
upload_protocol
Type: String | Multiple: No
A protocol that "uploader" tool uses to talk to a board. Please check boards for supported
uploading protocols by your board.
upload_speed
Type: Integer | Multiple: No
A connection speed (baud rate) which "uploader" tool uses when sending firmware to board.
upload_flags
Type: String | Multiple: Yes
Extra flags for uploader. Will be added to the end of uploader command. If you need to
override uploader command or base flags please use projectconf_extra_scripts.
This option can also be set by global environment variable PLATFORMIO_UPLOAD_FLAGS.
Example
Please specify each flag/option in a new line starting with minimum 2 spaces.
[env:atmega328pb]
platform = atmelavr
board = atmega328pb
framework = arduino
upload_flags =
-P$UPLOAD_PORT
-b$UPLOAD_SPEED
-u
-Ulock:w:0xCF:m
-Uhfuse:w:0xD7:m
-Uefuse:w:0xF6:m
-Ulfuse:w:0xE2:m
upload_resetmethod
Type: String | Multiple: No
Specify reset method for "uploader" tool. This option isn't available for all development
platforms. The only platform_espressif8266 supports it.
upload_command
New in version 4.0.
Type: String | Multiple: No
Override default platforms upload command with a custom. You can pass a full upload
command with arguments and options or mix with upload_flags.
Default upload commands are declared in build/main.py script file of platforms. See a list
with open source platforms => https://github.com/topics/platformio-platform
NOTE:
Please note that you can use build variables in upload_command, such as PlatformIO
project folders and other runtime configuration. A list with build variables are
available by running platformio run --target envdump command.
Examples
1. Override default upload command but handle pre-uploading actions (looking for serial
port, extra image preparation, etc.). Normally, the pre-configured upload options will
be stored in $UPLOADERFLAGS build variable. A classic default upload command for
platforms may look as some-flash-bin-tool $UPLOADERFLAGS $SOURCE, where $SOURCE will be
replaced by a real program/firmware binary.
$PROJECT_PACKAGES_DIR build variable points to projectconf_pio_packages_dir.
[env:program_via_AVR_ISP]
platform = atmelavr
framework = arduino
board = uno
upload_flags =
-C
$PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
-p
atmega328p
-P
$UPLOAD_PORT
-b
115200
-c
stk500v1
upload_command = avrdude $UPLOAD_FLAGS -U flash:w:$SOURCE:i
2. Override default upload command and skip pre-uploading actions.
[env:program_via_usbasp]
platform = atmelavr
framework = arduino
board = uno
upload_flags =
-C
$PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf
-p
atmega328p
-Pusb
-c
stk500v1
upload_command = avrdude $UPLOAD_FLAGS -U flash:w:$SOURCE:i
; Use ST-util for flashing
; https://github.com/texane/stlink
[env:custom_st_flash]
platform = ststm32
framework = stm32cube
board = bluepill_f103c6
upload_command = $PROJECT_PACKAGES_DIR/tool-stlink/st-flash write $SOURCE 0x8000000
Monitor options
• monitor_port
• monitor_speed
• monitor_filters
• monitor_rts
• monitor_dtr
• monitor_flags
Custom options for cmd_device_monitor command.
monitor_port
Type: String | Multiple: No
Port, a number or a device name, or valid URL Handlers. See platformio device monitor
--port. To print all available serial ports please use cmd_device_list command.
Please note that you can use Unix shell-style wildcards:
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
Example:
[env:custom_monitor_port]
...
; Unix
monitor_port = /dev/ttyUSB1
; Windows, COM1 or COM3
monitor_port = COM[13]
; Socket
monitor_port = socket://localhost:4444
monitor_speed
Type: Integer | Multiple: No | Default: 9600
A monitor speed (baud rate). See platformio device monitor --baud.
Example:
[env:custom_monitor_speedrate]
...
monitor_speed = 115200
monitor_filters
New in version 4.3.
Type: String | Multiple: Yes
Apply filters and text transformation for device output. See available filters at
cmd_device_monitor_filters.
Example:
[env:log_output_to_file_with_timestamp]
...
platform = ...
monitor_filters = log2file, time, default
monitor_rts
Type: Integer (0 or 1) | Multiple: No
A monitor initial RTS line state. See platformio device monitor --rts.
monitor_dtr
Type: Integer (0 or 1) | Multiple: No
A monitor initial DTR line state. See platformio device monitor --dtr.
monitor_flags
New in version 4.0.
Type: String | Multiple: Yes
Pass extra flags and options to cmd_device_monitor command. Please note that each flag,
option or its value should be passed in a new line. See example below.
Available flags and options are the same which are documented for cmd_device_monitor
command.
Example:
[env:extra_monitor_flags]
platform = ...
board = ...
monitor_flags=
--parity
N
--encoding
hexlify
Check options
SEE ALSO:
Please make sure to read piocheck guide first.
• check_tool
• check_patterns
• check_flags
• check_severity
check_tool
Type: String | Multiple: Yes | Default: cppcheck
A name of the check tool used for analysis. This option is useful when you want to check
source code with two or more tools.
See available tools in check_tools.
Example
[env:myenv]
platform = ...
board = ...
check_tool = cppcheck, clangtidy
check_patterns
Type: String (Pattern) | Multiple: Yes
This option allows specifying which source files or folders should be included/excluded
from the check process. GLOB Patterns are allowed. projectconf_pio_src_dir and
projectconf_pio_include_dir folders are checked by default.
Another option for filtering source files is platformio check --pattern command.
Example
[env:custom_check_patterns]
platform = ...
board = ...
check_tool = clangtidy
check_patterns =
app/sources
tests/hardware/*.c
check_flags
Type: String | Multiple: Yes
Additional flags to be passed to the tool command line. This option is useful when you
want to adjust the check process to fit your project requirements. By default, the flags
are passed to all tools specified in check_tool section. To set individual flags, define
tool name at the beginning of the line.
Another option for adding flags is platformio check --flags command.
Example
[env:extra_check_flags]
platform = ...
board = ...
check_tool = cppcheck, clangtidy
check_flags =
--common-flag
cppcheck: --enable=performance --inline-suppr
clangtidy: -fix-errors -format-style=mozilla
check_severity
Type: String | Multiple: Yes | Default: low, medium, high
This option allows specifying the check_severity types which will be reported by the
check_tools.
Another option for filtering source files is platformio check --severity command.
Example
[env:detect_only_medium_or_high_defects]
platform = ...
board = ...
check_severity = medium, high
Test options
SEE ALSO:
Please make sure to read unit_testing guide first.
• test_filter
• test_ignore
• test_port
• test_speed
• test_transport
• test_build_project_src
test_filter
Type: String (Pattern) | Multiple: Yes
Process only the unit_testing tests where the name matches specified patterns.
Also, you can filter some tests using platformio test --filter command.
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
Example
[env:myenv]
test_filter = footest, bartest_*, test[13]
test_ignore
Type: String (Pattern) | Multiple: Yes
Ignore unit_testing tests where the name matches specified patterns.
Also, you can ignore some tests using platformio test --ignore command.
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
Example
[env:myenv]
test_ignore =
footest
bartest_*
test[13]
test_port
Type: String (Pattern) | Multiple: No
This option specifies communication interface (Serial/UART) between PlatformIO
unit_testing Engine and target device. For example,
• /dev/ttyUSB0 - Unix-based OS
• COM3 - Windows OS
If test_port isn't specified, then PlatformIO will try to detect it automatically.
To print all available serial ports use cmd_device_list command.
test_speed
Type: Integer | Multiple: No | Default: 115200
A connection speed (baud rate) to communicate with a target device.
test_transport
Type: String | Multiple: No
A transport type which will be used to read test results from a target device. See more
details at unit_testing_transport.
test_build_project_src
Type: Bool (yes or no) | Multiple: No | Default: no
Force unit_testing engine to build project source code from projectconf_pio_src_dir
setting test_build_project_src to yes. More detail about unit_testing_shared_code.
Example
[env:myenv]
platform = ...
test_build_project_src = yes
Debugging options
SEE ALSO:
Please make sure to read piodebug guide first.
• debug_tool
• debug_build_flags
• debug_init_break
• debug_init_cmds
• debug_extra_cmds
• debug_load_cmds
• debug_load_mode
• debug_server
• debug_port
• debug_svd_path
debug_tool
Type: String | Multiple: No
A name of debugging tool. This option is useful when board supports more than one
debugging tool (adapter, probe) or you want to create debugging_tool_custom debugging
configuration.
See available tools in debugging_tools.
Example
[env:debug]
platform = ...
board = ...
debug_tool = custom
debug_build_flags
New in version 4.2.0.
Type: String | Multiple: Yes | Default: -Og -g2 -ggdb2
These flags/options affect the preprocessing, compilation, assembly and linking processes
for C and C++ code.
NOTE:
This option might be helpful to adjust the optimization level if firmware with debug
information is too big to be uploaded to a target
Example
[env:debug]
platform = ...
board = ...
; Set optimization level and amount of debug information generated by the compiler
debug_build_flags = -O0 -ggdb3 -g3
Other possible flags that might be useful for debugging your application.
debug_init_break
Type: String | Multiple: No | Default: tbreak main
An initial breakpoint that makes your program stop whenever a certain point in the program
is reached. Default value is set to tbreak main and means creating a temporary breakpoint
at int main(...) function and automatically delete it after the first time a program stops
there.
• GDB Setting Breakpoints
• GDB Breakpoint Locations
NOTE:
Please note that each debugging tool (adapter, probe) has limited number of hardware
breakpoints.
If you need more Project Initial Breakpoints, please place them in debug_extra_cmds.
Examples
[env:debug]
platform = ...
board = ...
; Examples 1: disable initial breakpoint
debug_init_break =
; Examples 2: temporary stop at ``void loop()`` function
debug_init_break = tbreak loop
; Examples 3: stop in main.cpp at line 13
debug_init_break = break main.cpp:13
; Examples 4: temporary stop at ``void Reset_Handler(void)``
debug_init_break = tbreak Reset_Handler
debug_init_cmds
Type: String | Multiple: Yes | Default: See details...
Initial commands that will be passed to back-end debugger.
PlatformIO dynamically configures back-end debugger depending on a debug environment. Here
is a list with default initial commands for the popular debugging_tools.
For example, the custom initial commands for GDB:
[env:debug]
platform = ...
board = ...
debug_init_cmds =
target extended-remote $DEBUG_PORT
$INIT_BREAK
monitor reset halt
$LOAD_CMDS
monitor init
monitor reset halt
debug_extra_cmds
Type: String | Multiple: Yes
Extra commands that will be passed to back-end debugger after debug_init_cmds. For
example, add custom breakpoint and load .gdbinit from a project directory for GDB:
[env:debug]
platform = ...
board = ...
debug_extra_cmds =
break main.cpp:13
break foo.cpp:100
source .gdbinit
NOTE:
Initial Project Breakpoints: Use break path/to/file:LINE_NUMBER to define initial
breakpoints for debug environment. Multiple breakpoints are allowed.
To save session breakpoints, please use save breakpoints [filename] command in Debug
Console. For example, save breakpoints .gdbinit. Later, this file could be loaded via
source [filename] command. See above.
debug_load_cmds
New in version 4.0.
Type: String | Multiple: Yes | Default: load
Specify a command which will be used to load program/firmware to a target device. Possible
options:
• load - default option
• load [address] - load program at specified address, where "[address]" should be a valid
number
• preload - some embedded devices have locked Flash Memory (a few Freescale Kinetis and
NXP LPC boards). In this case, firmware loading using debugging client is disabled.
preload command instructs piocore to load program/firmware using development platform
"upload" method (via bootloader, media disk, etc)
• (empty value, debug_load_cmds =), disables program loading at all.
• custom commands - pass any debugging client command (GDB, etc.)
Sometimes you need to run extra monitor commands (on debug server side) before
program/firmware loading, such as flash unlocking or erasing. In this case we can combine
service commands with loading and run them before. See example:
[env:debug]
platform = ...
board = ...
debug_load_cmds =
monitor flash erase_sector 0 0 11
load
debug_load_mode
Type: String | Multiple: No | Default: always
Allows one to control when PlatformIO should load debugging firmware to the end target.
Possible options:
• always - load for the each debugging session, default
• modified - load only when firmware was modified
• manual - do not load firmware automatically. You are responsible to pre-flash target
with debugging firmware in this case.
debug_server
Type: String | Multiple: Yes
Allows one to setup a custom debugging server. By default, boards are pre-configured with
a debugging server that is compatible with "on-board" debugging tool (adapter, probe).
Also, this option is useful for a debugging_tool_custom debugging tool.
Option format (multi-line):
• First line is an executable path of debugging server
• 2-nd and the next lines are arguments for executable file
Example:
[env:debug]
platform = ...
board = ...
debug_server =
/path/to/debugging/server
arg1
arg2
...
argN
debug_port
Type: String | Multiple: No
A debugging port of a remote target. Could be a serial device or network address.
PlatformIO detects it automatically if is not specified.
For example:
• /dev/ttyUSB0 - Unix-based OS
• COM3 - Windows OS
• localhost:3333
debug_svd_path
Type: FilePath | Multiple: No
A custom path to SVD file which contains information about device peripherals.
Advanced options
extends
New in version 4.1.
Type: String | Multiple: Yes
This option allows one to inherit configuration from other sections or build environments
in projectconf. Multiple items are allowed, split them with , or with a new line.
If you need to extend only a few options from some section, please take a look at
projectconf_dynamic_vars.
Example:
[strict_ldf]
lib_ldf_mode = chain+
lib_compat_mode = strict
[espressi32_base]
platform = espressif32
framework = arduino
[env:release]
extends = espressi32_base, strict_ldf
board = esp32dev
build_flags = -D RELEASE
[env:debug]
extends = env:release
build_type = debug
build_flags = -D DEBUG
extra_scripts
Type: FilePath | Multiple: Yes
A list of PRE and POST extra scripts.
See details and examples in projectconf_advanced_scripting section.
If you plan to share these scripts with pioremote machine, please put them to
projectconf_pio_shared_dir.
Build Configurations
New in version 4.0.0.
There are 2 types (projectconf_build_type) of build configuration in PlatformIO:
release
Default configuration. A "release" configuration of your firmware/program does not
contain symbolic debug information and is optimized for the firmware size or speed
(depending on platforms)
debug A "debug" configuration of your firmware/program is compiled with full symbolic
debug information and no optimization. Optimization complicates debugging, because
the relationship between source code and generated instructions is more complex.
NOTE:
If you need to control build flags that are specific for debug configuration please
refer to projectconf_debug_build_flags.
If you need to build a project in debug configuration, please use one of these options:
• Add projectconf_build_type with debug value to projectconf
• Use target debug for the platformio run --target command.
NOTE:
piodebug automatically switches to debug configuration when you do project debugging
from pioide or use the cmd_debug command.
To avoid having piodebug rebuild the project, please create a separate build
environment that defines build_type = debug. See the example below where the mydebug
build environment will be used automatically by piodebug:
[env]
platform = ...
board = ...
framework = ...
... other common configuration
[env:myrelease]
some_extra_options = ...
[env:mydebug]
build_type = debug
some_extra_options = ...
Please note that you can set a default build environment per a project using the
projectconf_pio_default_envs option in projectconf_section_platformio.
Dynamic variables
Dynamic variables (interpolations) are useful when you have a custom configuration data
between build environments. For examples, extra projectconf_build_flags or project
dependencies projectconf_lib_deps.
Each variable should have a next format: ${<section>.<option>}, where <section> is a value
from [<section>] group, and <option> is a first item from pair <option> = value.
You can inject system environment variable using sysenv as a section. For example,
${sysenv.HOME}.
• Variable can be applied only for the option's value
• Multiple variables are allowed
• The projectconf_section_platformio and projectconf_section_env sections are reserved and
could not be used as a custom section. Some good section names might be extra or custom.
NOTE:
If you need to share common configuration options between build environments, please
take a look at "Global scope" in projectconf_section_env or projectconf_env_extends
option which allows extending of other sections.
Example:
[env]
; Unix
lib_extra_dirs = ${sysenv.HOME}/Documents/Arduino/libraries
; Windows
lib_extra_dirs = ${sysenv.HOMEDRIVE}${sysenv.HOMEPATH}\Documents\Arduino\libraries
; You MUST inject these options into [env:] section
; using ${extra.***} (see below)
[extra]
build_flags = -D VERSION=1.2.3 -D DEBUG=1
lib_deps_builtin =
SPI
Wire
lib_deps_external = ArduinoJson@>5.6.0
[env:uno]
platform = atmelavr
framework = arduino
board = uno
build_flags = ${extra.build_flags}
lib_deps =
${extra.lib_deps_builtin}
${extra.lib_deps_external}
[env:nodemcuv2]
platform = espressif8266
framework = arduino
board = nodemcuv2
build_flags = ${extra.build_flags} -Wall
lib_deps =
${extra.lib_deps_builtin}
${extra.lib_deps_external}
PubSubClient@2.6
OneWire
; Keep sensitive data in environment variables
;
; Unix
; export WIFI_SSID='\"my\ ssid\ name\"'
; export WIFI_PASS='\"my\ password\"'
;
; Windows
; set WIFI_SSID='"my ssid name"'
; set WIFI_PASS='"my password"'
[env:esp32dev]
extends = env:nodemcuv2
platform = espressif32
board = esp32dev
build_flags =
-DWIFI_SSID=${sysenv.WIFI_SSID}
-DWIFI_PASS=${sysenv.WIFI_PASS}
WARNING:
Be careful with special characters in system environment variables on Unix systems,
especially when they are used as the value for preprocessor directives. Symbols like
$, &, ~, etc must be explicitly escaped, for example:
export WIFI_PASS='\"my\~p\&a\\\$\$\$\$word\"'
Examples
NOTE:
A full list with project examples can be found in PlatformIO Repository.
Community project examples with platformio.ini:
• MarlinFirmware/Marlin
• xoseperez/espurna
• esphome/esphome
• cyberman54/ESP32-Paxcounter
Example
For more examples, see projectconf_examples.
[platformio]
default_envs = nodemcuv2
; You MUST inject these options into [env:] section
; using ${common_env_data.***} (see below)
[common_env_data]
build_flags =
-D VERSION=1.2.3
-D DEBUG=1
lib_deps_builtin =
SPI
Wire
lib_deps_external =
ArduinoJson@~5.6,!=5.4
https://github.com/gioblu/PJON.git#v2.0
IRremoteESP8266=https://github.com/markszabo/IRremoteESP8266/archive/master.zip
[env:nodemcuv2]
platform = espressif8266
framework = arduino
board = nodemcuv2
; Build options
build_flags =
${common_env_data.build_flags}
-DSSID_NAME=HELLO
-DSSID_PASWORD=WORLD
; Library options
lib_deps =
${common_env_data.lib_deps_builtin}
${common_env_data.lib_deps_external}
https://github.com/me-no-dev/ESPAsyncTCP.git
PubSubClient@2.6
OneWire
; Serial Monitor options
monitor_speed = 115200
monitor_flags =
--encoding
hexlify
; Unit Testing options
test_ignore = test_desktop
[env:bluepill_f103c8]
platform = ststm32
framework = arduino
board = bluepill_f103c8
; Build options
build_flags = ${common_env_data.build_flags}
; Library options
lib_deps =
${common_env_data.lib_deps_external}
; Debug options
debug_tool = custom
debug_server =
JLinkGDBServer
-singlerun
-if
SWD
-select
USB
-port
2331
-device
STM32F103C8
; Unit Testing options
test_ignore = test_desktop
Environment variables
Environment variables are a set of dynamic named values that can affect the way running
processes will behave on a computer. PlatformIO handles variables which start with
PLATFORMIO_ prefix.
How to set environment variable?
# Windows
set VARIABLE_NAME=VALUE
# Windows GUI -> https://www.youtube.com/watch?v=bEroNNzqlF4
# Unix (bash, zsh)
export VARIABLE_NAME=VALUE
# Unix (fish)
set -x VARIABLE_NAME VALUE
Contents
• General
• Directories
• Building
• Uploading
• Settings
General
PlatformIO uses General environment variables for the common operations/commands.
CI
PlatformIO handles CI variable which is setup by Continuous Integration (Travis, Circle
and etc.) systems. PlatformIO uses it to disable prompts and progress bars. In other
words, CI=true automatically setup PLATFORMIO_DISABLE_PROGRESSBAR to true.
PLATFORMIO_AUTH_TOKEN
Allows one to specify Personal Authentication Token that could be used for automatic login
in to pioaccount. It is very useful for ci systems and pioremote operations where you are
not able manually authorize.
You can get own Personal Authentication Token using cmd_account_token command.
PLATFORMIO_FORCE_ANSI
Force to output ANSI control character even if the output is a pipe (not a tty). The
possible values are true and false. Default is PLATFORMIO_FORCE_ANSI=false.
PLATFORMIO_NO_ANSI
Do not print ANSI control characters. The possible values are true and false. Default is
PLATFORMIO_NO_ANSI=false.
You can also use platformio --no-ansi flag for piocore.
PLATFORMIO_DISABLE_PROGRESSBAR
Disable progress bar for package/library downloader and uploader. This is useful when
calling PlatformIO from subprocess and output is a pipe (not a tty). The possible values
are true and false. Default is PLATFORMIO_DISABLE_PROGRESSBAR=false.
Directories
PLATFORMIO_CORE_DIR
Allows one to override projectconf option projectconf_pio_core_dir.
PLATFORMIO_GLOBALLIB_DIR
Allows one to override projectconf option projectconf_pio_globallib_dir.
PLATFORMIO_PLATFORMS_DIR
Allows one to override projectconf option projectconf_pio_platforms_dir.
PLATFORMIO_PACKAGES_DIR
Allows one to override projectconf option projectconf_pio_packages_dir.
PLATFORMIO_CACHE_DIR
Allows one to override projectconf option projectconf_pio_cache_dir.
PLATFORMIO_BUILD_CACHE_DIR
Allows one to override projectconf option projectconf_pio_build_cache_dir.
PLATFORMIO_WORKSPACE_DIR
Allows one to override projectconf option projectconf_pio_workspace_dir.
PLATFORMIO_INCLUDE_DIR
Allows one to override projectconf option projectconf_pio_include_dir.
PLATFORMIO_SRC_DIR
Allows one to override projectconf option projectconf_pio_src_dir.
PLATFORMIO_LIB_DIR
Allows one to override projectconf option projectconf_pio_lib_dir.
PLATFORMIO_LIBDEPS_DIR
Allows one to override projectconf option projectconf_pio_libdeps_dir.
PLATFORMIO_BUILD_DIR
Allows one to override projectconf option projectconf_pio_build_dir.
PLATFORMIO_DATA_DIR
Allows one to override projectconf option projectconf_pio_data_dir.
PLATFORMIO_TEST_DIR
Allows one to override projectconf option projectconf_pio_test_dir.
PLATFORMIO_BOARDS_DIR
Allows one to override projectconf option projectconf_pio_boards_dir.
PLATFORMIO_SHARED_DIR
Allows one to override projectconf option projectconf_pio_shared_dir.
PLATFORMIO_REMOTE_AGENT_DIR
Allows one to override platformio remote agent start --working-dir.
PLATFORMIO_LIB_EXTRA_DIRS
Allows one to set projectconf option projectconf_lib_extra_dirs.
Building
PLATFORMIO_BUILD_FLAGS
Allows one to set projectconf option projectconf_build_flags.
Examples:
# Unix:
export PLATFORMIO_BUILD_FLAGS=-DFOO
export PLATFORMIO_BUILD_FLAGS=-DFOO -DBAR=1 -Wall
# Windows:
SET PLATFORMIO_BUILD_FLAGS=-DFOO
SET PLATFORMIO_BUILD_FLAGS=-DFOO -DBAR=1 -Wall
WARNING:
Consider using projectconf_dynamic_vars instead of PLATFORMIO_BUILD_FLAGS environment
variable if additional build flags contain preprocessor directive with special
characters ($, &, ~, etc) in its value.
PLATFORMIO_SRC_BUILD_FLAGS
Allows one to set projectconf option projectconf_src_build_flags.
PLATFORMIO_SRC_FILTER
Allows one to set projectconf option projectconf_src_filter.
PLATFORMIO_EXTRA_SCRIPTS
Allows one to set projectconf option projectconf_extra_scripts.
PLATFORMIO_DEFAULT_ENVS
Allows one to set projectconf option projectconf_pio_default_envs.
Uploading
PLATFORMIO_UPLOAD_PORT
Allows one to set projectconf option projectconf_upload_port.
PLATFORMIO_UPLOAD_FLAGS
Allows one to set projectconf option projectconf_upload_flags.
Settings
Allows one to override PlatformIO settings. You can manage them via cmd_settings command.
PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES
Allows one to override setting setting_auto_update_libraries.
PLATFORMIO_SETTING_AUTO_UPDATE_PLATFORMS
Allows one to override setting setting_auto_update_platforms.
PLATFORMIO_SETTING_CHECK_LIBRARIES_INTERVAL
Allows one to override setting setting_check_libraries_interval.
PLATFORMIO_SETTING_CHECK_PLATFORMIO_INTERVAL
Allows one to override setting setting_check_platformio_interval.
PLATFORMIO_SETTING_CHECK_PLATFORMS_INTERVAL
Allows one to override setting setting_check_platforms_interval.
PLATFORMIO_SETTING_ENABLE_CACHE
Allows one to override setting setting_enable_cache.
PLATFORMIO_SETTING_STRICT_SSL
Allows one to override setting setting_strict_ssl.
PLATFORMIO_SETTING_ENABLE_TELEMETRY
Allows one to override setting setting_enable_telemetry.
PLATFORMIO_SETTING_FORCE_VERBOSE
Allows one to override setting setting_force_verbose.
PLATFORMIO_SETTING_PROJECTS_DIR
Allows one to override setting setting_projects_dir.
Advanced Scripting
WARNING:
Advanced Scripting is recommended for Advanced Users and requires knowledge of the
Python language.
WARNING:
projectconf_dynamic_build_flags is a highly recommended alternative to advanced
scripting, where you can use any programming language. Also, that option is useful if
you need to apply changes to the project before the building/uploading process, such
as:
• Macro with the latest VCS revision/tag "on-the-fly"
• Generate dynamic headers (*.h)
• Process media content before generating SPIFFS image
• Make some changes to source code or related libraries
Contents
• Advanced Scripting
• Launch types
• Construction Environments
• Before/Pre and After/Post actions
• Build Middlewares
• Custom target
• Command shortcut
• Dependent target
• Target with options
• Examples
• Custom options in platformio.ini
• Split C/C++ build flags
• Extra Linker Flags without -Wl, prefix
• Custom upload tool
• Upload to Cloud (OTA)
• Custom firmware/program name
• Override package files
• Override Board Configuration
• Custom debug flags
The PlatformIO Build System allows the user to extend the build process with custom
scripts using the Python interpreter and the SCons construction tool. Build flags, upload
flags, targets, toolchains data and other information are available for modification as
SCons Construction Environments. Custom scripts are included with
projectconf_extra_scripts
WARNING:
You can not run or debug these scripts manually with a Python interpreter. They will be
loaded automatically when the cmd_run command processes the project environment.
Launch types
There are two execution orders for extra scripts:
1. PRE - executes before the main script of platforms
2. POST - executes after the main script of platforms
Multiple extra scripts are allowed. Please split them via ", " (comma + space) in the
same line or use multi-line values.
For example, in projectconf:
[env:my_env_1]
platform = ...
; Defaults to POST script since no prefix is used
extra_scripts = post_extra_script.py
[env:my_env_2]
platform = ...
extra_scripts =
pre:pre_extra_script.py
post:post_extra_script1.py
post_extra_script2.py
This option can also be set by the global environment variable PLATFORMIO_EXTRA_SCRIPTS.
Construction Environments
The PlatformIO Build System uses two built-in construction environments to process each
project:
• env, Import("env") - the global construction environment used for the platforms and
frameworks build scripts, upload tools, ldf, and other internal operations
• projenv, Import("projenv") - the isolated construction environment used for processing
the project source code in projectconf_pio_src_dir. Please note that any
projectconf_src_build_flags specified in projectconf will be passed to projenv and not
to env.
WARNING:
1. projenv is available only for POST-type scripts
2. Flags passed to env using PRE-type script will affect projenv too.
my_pre_extra_script.py:
Import("env")
# access to global construction environment
print(env)
# Dump construction environment (for debug purpose)
print(env.Dump())
# append extra flags to global build environment
# which later will be used to build:
# - project source code
# - frameworks
# - dependent libraries
env.Append(CPPDEFINES=[
"MACRO_1_NAME",
("MACRO_2_NAME", "MACRO_2_VALUE")
])
my_post_extra_script.py:
Import("env", "projenv")
# access to global construction environment
print(env)
# access to project construction environment
print(projenv)
# Dump construction environments (for debug purpose)
print(env.Dump())
print(projenv.Dump())
# append extra flags to global build environment
# which later will be used to build:
# - frameworks
# - dependent libraries
env.Append(CPPDEFINES=[
"MACRO_1_NAME",
("MACRO_2_NAME", "MACRO_2_VALUE")
])
# append extra flags to only project build environment
projenv.Append(CPPDEFINES=[
"PROJECT_EXTRA_MACRO_1_NAME",
("ROJECT_EXTRA_MACRO_2_NAME", "ROJECT_EXTRA_MACRO_2_VALUE")
])
See examples below how to import construction environments and modify existing data or add
new.
Before/Pre and After/Post actions
The PlatformIO Build System has a rich API that allows one to attach different pre-/post
actions (hooks) using env.AddPreAction(target, callback) or env.AddPreAction(target,
[callback1, callback2, ...]) function. The first argument target can be the name of a
target that is passed using the platformio run --target command, the name of a built-in
target (buildprog, size, upload, program, buildfs, uploadfs, uploadfsota) or the path to a
file which PlatformIO processes (ELF, HEX, BIN, OBJ, etc.).
Examples
The extra_script.py file is located in the same directory as platformio.ini.
platformio.ini:
[env:pre_and_post_hooks]
extra_scripts = post:extra_script.py
extra_script.py:
Import("env", "projenv")
# access to global build environment
print(env)
# access to project build environment (is used source files in "src" folder)
print(projenv)
#
# Dump build environment (for debug purpose)
# print(env.Dump())
#
#
# Change build flags in runtime
#
env.ProcessUnFlags("-DVECT_TAB_ADDR")
env.Append(CPPDEFINES=("VECT_TAB_ADDR", 0x123456789))
#
# Upload actions
#
def before_upload(source, target, env):
print("before_upload")
# do some actions
# call Node.JS or other script
env.Execute("node --version")
def after_upload(source, target, env):
print("after_upload")
# do some actions
print("Current build targets", map(str, BUILD_TARGETS))
env.AddPreAction("upload", before_upload)
env.AddPostAction("upload", after_upload)
#
# Custom actions when building program/firmware
#
env.AddPreAction("buildprog", callback...)
env.AddPostAction("buildprog", callback...)
#
# Custom actions for specific files/objects
#
env.AddPreAction("$BUILD_DIR/${PROGNAME}.elf", [callback1, callback2,...])
env.AddPostAction("$BUILD_DIR/${PROGNAME}.hex", callback...)
# custom action before building SPIFFS image. For example, compress HTML, etc.
env.AddPreAction("$BUILD_DIR/spiffs.bin", callback...)
# custom action for project's main.cpp
env.AddPostAction("$BUILD_DIR/src/main.cpp.o", callback...)
# Custom HEX from ELF
env.AddPostAction(
"$BUILD_DIR/${PROGNAME}.elf",
env.VerboseAction(" ".join([
"$OBJCOPY", "-O", "ihex", "-R", ".eeprom",
"$BUILD_DIR/${PROGNAME}.elf", "$BUILD_DIR/${PROGNAME}.hex"
]), "Building $BUILD_DIR/${PROGNAME}.hex")
)
Build Middlewares
New in version 4.1.
PlatformIO Build System allows you to add middleware functions that can be used for Build
Node(Object) construction. This is very useful if you need to add custom flags for the
specific file nodes or exclude them from a build process.
There is env.AddBuildMiddleware(callback, pattern) helper which instructs PlatformIO Build
System to call callback for each SCons File System Node whose path matches with Unix
shell-style "pattern" (wildcards).
If a pattern is omitted, the callback will be called for each File System Node which is
added for the build process.
You can add an unlimited number of build middlewares. They will be called in order of
registration. Please note, if the first middleware ignores some File Nodes, they will not
be passed to the next middleware in chain.
Examples
platformio.ini:
[env:build_middleware]
extra_scripts = pre:extra_script.py
extra_script.py:
Import("env")
# --- Add custom macros for the ALL files which name contains "http"
def extra_http_configuration(node):
"""
`node.name` - a name of File System Node
`node.get_path()` - a relative path
`node.get_abspath()` - an absolute path
"""
# do not modify node if file name does not contain "http"
if "http" not in node.name:
return node
# now, we can override ANY SCons variables (CPPDEFINES, CCFLAGS, etc.,) for the specific file
# pass SCons variables as extra keyword arguments to `env.Object()` function
# p.s: run `pio run -t envdump` to see a list with SCons variables
return env.Object(
node,
CPPDEFINES=env["CPPDEFINES"]
+ [("HTTP_HOST", "device.local"), ("HTTP_PORT", 8080)],
CCFLAGS=env["CCFLAGS"] + ["-fno-builtin-printf"]
)
env.AddBuildMiddleware(extra_http_configuration)
# --- Replace some file from a build process with another
def replace_node_with_another(node):
return env.File("path/to/patched/RtosTimer.cpp")
env.AddBuildMiddleware(
replace_node_with_another,
"framework-mbed/rtos/RtosTimer.cpp"
)
# --- Skip assembly *.S files from build process
def skip_asm_from_build(node):
# to ignore file from a build process, just return None
return None
env.AddBuildMiddleware(skip_asm_from_build, "*.S")
Custom target
There is a list with built-in targets which could be processed using platformio run
--target option. You can create unlimited number of the own targets and declare custom
handlers for them.
We will use SCons's Alias(alias, [targets, [action]]) , env.Alias(alias, [targets,
[action]]) function to declare a custom target/alias.
Command shortcut
Create a custom node target (alias) which will print a NodeJS version
platformio.ini:
[env:myenv]
platform = ...
...
extra_scripts = extra_script.py
extra_script.py:
Import("env")
env.AlwaysBuild(env.Alias("node", None, ["node --version"]))
Now, run pio run -t node.
Dependent target
Sometimes you need to run a command which depends on another target (file, firmware, etc).
Let's create an ota target and declare command which will depend on a project firmware. If
a build process successes, declared command will be run.
platformio.ini:
[env:myenv]
platform = ...
...
extra_scripts = extra_script.py
extra_script.py:
Import("env")
env.AlwaysBuild(env.Alias("ota",
"$BUILD_DIR/${PROGNAME}.elf",
["ota_script --firmware-path $SOURCE"]))
Now, run pio run -t ota.
Target with options
Let's create a simple ping target and process it with platformio run --target ping
command:
platformio.ini:
[env:env_custom_target]
platform = ...
...
extra_scripts = extra_script.py
custom_ping_host = google.com
extra_script.py:
try:
import configparser
except ImportError:
import ConfigParser as configparser
Import("env")
config = configparser.ConfigParser()
config.read("platformio.ini")
host = config.get("env_custom_target", "custom_ping_host")
def mytarget_callback(*args, **kwargs):
print("Hello PlatformIO!")
env.Execute("ping " + host)
env.AlwaysBuild(env.Alias("ping", None, mytarget_callback))
Examples
The best examples are PlatformIO development platforms. Please check builder folder for
the main and framework scripts.
Custom options in platformio.ini
platformio.ini:
[env:my_env]
platform = ...
extra_scripts = extra_script.py
custom_option1 = value1
custom_option2 = value2
extra_script.py:
try:
import configparser
except ImportError:
import ConfigParser as configparser
config = configparser.ConfigParser()
config.read("platformio.ini")
value1 = config.get("my_env", "custom_option1")
value2 = config.get("my_env", "custom_option2")
Split C/C++ build flags
platformio.ini:
[env:my_env]
platform = ...
extra_scripts = extra_script.py
extra_script.py (place it near platformio.ini):
Import("env")
# General options that are passed to the C and C++ compilers
env.Append(CCFLAGS=["flag1", "flag2"])
# General options that are passed to the C compiler (C only; not C++).
env.Append(CFLAGS=["flag1", "flag2"])
# General options that are passed to the C++ compiler
env.Append(CXXFLAGS=["flag1", "flag2"])
Extra Linker Flags without -Wl, prefix
Sometimes you need to pass extra flags to GCC linker without Wl,. You could use
projectconf_build_flags option but it will not work. PlatformIO will not parse these flags
to LINKFLAGS scope. In this case, simple extra script will help:
platformio.ini:
[env:env_extra_link_flags]
platform = windows_x86
extra_scripts = extra_script.py
extra_script.py (place it near platformio.ini):
Import("env")
#
# Dump build environment (for debug)
# print(env.Dump())
#
env.Append(
LINKFLAGS=[
"-static",
"-static-libgcc",
"-static-libstdc++"
]
)
Custom upload tool
You can override default upload command of development platform using extra script. There
is the common environment variable UPLOADCMD which PlatformIO Build System will handle
when you platformio run -t upload.
Please note that some development platforms can have more than 1 upload command. For
example, platform_atmelavr has UPLOADHEXCMD (firmware) and UPLOADEEPCMD (EEPROM data).
See examples below:
Template
platformio.ini:
[env:my_custom_upload_tool]
platform = ...
; place it into the root of project or use full path
extra_scripts = extra_script.py
upload_protocol = custom
; each flag in a new line
upload_flags =
-arg1
-arg2
-argN
extra_script.py (place it near platformio.ini):
Import("env")
# please keep $SOURCE variable, it will be replaced with a path to firmware
# Generic
env.Replace(
UPLOADER="executable or path to executable",
UPLOADCMD="$UPLOADER $UPLOADERFLAGS $SOURCE"
)
# In-line command with arguments
env.Replace(
UPLOADCMD="executable -arg1 -arg2 $SOURCE"
)
# Python callback
def on_upload(source, target, env):
print(source, target)
firmware_path = str(source[0])
# do something
env.Execute("executable arg1 arg2")
env.Replace(UPLOADCMD=on_upload)
Custom openOCD command
platformio.ini:
[env:disco_f407vg]
platform = ststm32
board = disco_f407vg
framework = mbed
extra_scripts = extra_script.py
upload_protocol = custom
; each flag in a new line
upload_flags =
-f
scripts/interface/stlink.cfg
-f
scripts/target/stm32f4x.cfg
extra_script.py (place it near platformio.ini):
Import("env")
platform = env.PioPlatform()
env.Prepend(
UPLOADERFLAGS=["-s", platform.get_package_dir("tool-openocd") or ""]
)
env.Append(
UPLOADERFLAGS=["-c", "program {{$SOURCE}} verify reset; shutdown"]
)
env.Replace(
UPLOADER="openocd",
UPLOADCMD="$UPLOADER $UPLOADERFLAGS"
)
Upload to Cloud (OTA)
See project example https://github.com/platformio/bintray-secure-ota
Custom firmware/program name
Sometimes is useful to have a different firmware/program name in
projectconf_pio_build_dir.
platformio.ini:
[env:env_custom_prog_name]
platform = espressif8266
board = nodemcuv2
framework = arduino
build_flags = -D VERSION=13
extra_scripts = pre:extra_script.py
extra_script.py:
Import("env")
my_flags = env.ParseFlags(env['BUILD_FLAGS'])
defines = {k: v for (k, v) in my_flags.get("CPPDEFINES")}
# print(defines)
env.Replace(PROGNAME="firmware_%s" % defines.get("VERSION"))
Override package files
PlatformIO Package Manager automatically installs pre-built packages (frameworks,
toolchains, libraries) required by development platforms and build process. Sometimes you
need to override original files with own versions: configure custom GPIO, do changes to
built-in LD scripts, or some patching to installed library dependency.
The simplest way is using Diff and Patch technique. How does it work?
1. Modify original source files
2. Generate patches
3. Apply patches via PlatformIO extra script before build process.
Example
We need to patch the original standard/pins_arduino.h variant from framework_arduino
framework and add extra macro #define PIN_A8 (99). Let's duplicate
standard/pins_arduino.h and apply changes. Generate a patch file and place it into patches
folder located in the root of a project:
diff ~/.platformio/packages/framework-arduinoavr/variants/standard/pins_arduino.h /tmp/pins_arduino_modified.h > /path/to/platformio/project/patches/1-framework-arduinoavr-add-pin-a8.patch
The result of 1-framework-arduinoavr-add-pin-a8.patch:
63a64
> #define PIN_A8 (99)
112c113
< // 14-21 PA0-PA7 works
---
> // 14-21 PA0-PA7 works
Using extra scripting we can apply patching before a build process. The final result of
projectconf and "PRE" extra script named apply_patches.py:
platformio.ini:
[env:uno]
platform = atmelavr
board = uno
framework = arduino
extra_scripts = pre:apply_patches.py
apply_patches.py:
from os.path import join, isfile
Import("env")
FRAMEWORK_DIR = env.PioPlatform().get_package_dir("framework-arduinoavr")
patchflag_path = join(FRAMEWORK_DIR, ".patching-done")
# patch file only if we didn't do it before
if not isfile(join(FRAMEWORK_DIR, ".patching-done")):
original_file = join(FRAMEWORK_DIR, "variants", "standard", "pins_arduino.h")
patched_file = join("patches", "1-framework-arduinoavr-add-pin-a8.patch")
assert isfile(original_file) and isfile(patched_file)
env.Execute("patch %s %s" % (original_file, patched_file))
# env.Execute("touch " + patchflag_path)
def _touch(path):
with open(path, "w") as fp:
fp.write("")
env.Execute(lambda *args, **kwargs: _touch(patchflag_path))
Please note that this example will work on a system where a patch tool is available. For
Windows OS, you can use patch and diff tools provided by Git client utility (located
inside installation directory).
If you need to make it more independent to the operating system, please replace the patch
with a multi-platform python-patch script.
Override Board Configuration
PlatformIO allows one to override some basic options (integer or string values) using
projectconf_board_more_options in projectconf. Sometimes you need to do complex changes
to default board manifest and extra PRE scripting work well here. See example below how to
override default hardware VID/PIDs.
WARNING:
Due to a technical limitation these board changes will not work for cmd_device_monitor
command.
platformio.ini:
[env:uno]
platform = atmelavr
board = uno
framework = arduino
extra_scripts = pre:custon_hwids.py
custon_hwids.py:
Import("env")
board_config = env.BoardConfig()
# should be array of VID:PID pairs
board_config.update("build.hwids", [
["0x2341", "0x0243"], # 1st pair
["0x2A03", "0x0043"]. # 2nd pair, etc.
])
Custom debug flags
PlatformIO removes all debug/optimization flags before a debug session or when
build_configurations is set to debug and overrides them with -0g -g2 -ggdb2 for ASFLAGS,
CCFLAGS, and LINKFLAGS build scopes.
An extra script allows us to override PlatformIO's default behavior and declare custom
flags. See example below where we override -Og with -O0:
platformio.ini:
[env:teensy31]
platform = teensy
board = teensy31
framework = arduino
extra_scripts = custom_debug_flags.py
custom_debug_flags.py:
Import("env")
if env.GetBuildType() == "debug":
for scope in ("ASFLAGS", "CCFLAGS", "LINKFLAGS"):
for i, flag in enumerate(env[scope]):
if flag == "-Og":
env[scope][i] = "-O0"
Library Manager
PlatformIO Library Manager is a tool for managing libraries of PlatformIO Registry and VCS
repositories (Git, Hg, SVN). It makes it exceedingly simple to find, install and keep
libraries up-to-date. PlatformIO Library Manager supports Semantic Versioning and its
rules.
----
pioide has built-in piohome with a modern GUI which allows:
• Search for new libraries in PlatformIO Registry
• "1-click" library installation, per-project libraries, extra storages
• List installed libraries in multiple storages
• List built-in libraries (by frameworks)
• Updates for installed libraries
• Multiple examples, trending libraries, and more.
[image]
Quick Start
PlatformIO Library Manager is a tool for managing libraries of PlatformIO Registry and VCS
repositories (Git, Hg, SVN). It makes it exceedingly simple to find, install and keep
libraries up-to-date. PlatformIO Library Manager supports Semantic Versioning and its
rules.
There are 3 options how to find/manage libraries:
• piohome
• Web Library Search
• PIO Core Command Line Interface
You can manage different library storages using platformio lib --global or platformio lib
--storage-dir options. If you change current working directory in terminal to project
folder, then platformio lib command will manage automatically dependency storage in
projectconf_pio_libdeps_dir.
Project dependencies
PlatformIO Library Manager allows one to specify project dependencies
(projectconf_lib_deps) that will be installed automatically per project before environment
processing. You do not need to install libraries manually. The only one simple step is to
define dependencies in projectconf. You can use library ID, Name or even repository URL.
For example,
[env:myenv]
platform = ...
framework = ...
board = ...
lib_deps =
13
PubSubClient
ArduinoJson@~5.6,!=5.4
https://github.com/gioblu/PJON.git#v2.0
https://github.com/me-no-dev/ESPAsyncTCP.git
https://github.com/adafruit/DHT-sensor-library/archive/master.zip
Please follow to cmd_lib_install for detailed documentation about possible values.
WARNING:
If some libraries are not visible in pioide and Code Completion or Code Linting does
not work properly, please perform
• Atom: "Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter)"
• VSCode: "Menu: View > Command Palette... > PlatformIO: Rebuild C/C++ Project Index"
PlatformIO IDE
pioide has built-in piohome with a modern GUI which allows:
• Search for new libraries in PlatformIO Registry
• "1-click" library installation, per-project libraries, extra storages
• List installed libraries in multiple storages
• List built-in libraries (by frameworks)
• Updates for installed libraries
• Multiple examples, trending libraries, and more.
[image]
PlatformIO Core
[image]
CLI Guide
Library Dependency Finder (LDF)
Library Dependency Finder is a core part of PlatformIO Build System that operates with the
C/C++ source files and looks for #include ... directives to know what header directories
to include for the compiler.
In spite of the fact that Library Dependency Finder is written in pure Python, it
evaluates C/C++ Preprocessor conditional syntax (#ifdef, if, defined, else, and elif)
without calling gcc -E. This approach allows to significantly reduce the total compilation
time. See Dependency Finder Mode for more details.
Contents
• Library Dependency Finder (LDF)
• Configuration
• Storage
• Dependency Finder Mode
• Compatibility Mode
• C/C++ Preprocessor conditional syntax
Configuration
Library Dependency Finder can be configured from projectconf:
Storage
There are different storages where Library Dependency Finder looks for libraries. These
storages (folders) have priority and LDF operates in the next order:
1. projectconf_lib_extra_dirs - extra storages per build environment
2. projectconf_pio_lib_dir - own/private library storage per project
3. projectconf_pio_libdeps_dir - project dependency storage used by librarymanager
4. "projectconf_pio_core_dir/lib" - global storage per all projects.
5. Library storages built into frameworks, SDKs.
Dependency Finder Mode
Library Dependency Finder starts work from analyzing source files of the project
(projectconf_pio_src_dir) and can work in the next modes:
off "Manual mode", does not process source files of a project and dependencies. Builds
only the libraries that are specified in manifests (library_config, module.json) or
using projectconf_lib_deps option.
chain [DEFAULT] Parses ALL C/C++ source files of the project and follows only by nested
includes (#include ..., chain...) from the libraries. It also parses C, CC, CPP
files from libraries which have the same name as included header file. Does not
evaluate C/C++ Preprocessor conditional syntax.
deep Parses ALL C/C++ source files of the project and parses ALL C/C++ source files of
the each found dependency (recursively). Does not evaluate C/C++ Preprocessor
conditional syntax.
chain+ The same behavior as for the chain but evaluates C/C++ Preprocessor conditional
syntax.
deep+ The same behavior as for the deep but evaluates C/C++ Preprocessor conditional
syntax.
The mode can be changed using projectconf_lib_ldf_mode option in projectconf. Default
value is set to chain.
NOTE:
Usually, when the LDF appears to fail to identify a dependency of a library, it is
because the dependency is only referenced from a library source file, and not a library
header file (see example below). In this case, it is necessary to either explicitly
reference the dependency from the project source or projectconf (projectconf_lib_deps
option), or change the LDF mode to "deep" (not generally recommended).
A difference between chain/chain+ and deep/deep+ modes. For example, there are 2
libraries:
• Library Foo with files:
• Foo/foo.h
• Foo/foo.cpp
• Foo/extra.cpp
• Library Bar with files:
• Bar/bar.h
• Bar/bar.cpp
Case 1
• lib_ldf_mode = chain
• Foo/foo.h depends on the Bar library (contains #include <bar.h>)
• #include <foo.h> is located in one of the project source files
Here the nested includes (project file > foo.h > bar.h) and LDF will find both
libraries "Foo`` and Bar.
Case 2
• lib_ldf_mode = chain
• Foo/extra.cpp depends on the Bar library (contains #include <bar.h>)
• #include <foo.h> is located in one of the project source files
In this case, LDF will not find the Bar library because it doesn't know about the
CPP file (Foo/extra.cpp).
Case 3
• lib_ldf_mode = deep
• Foo/extra.cpp depends on Bar library (contains #include <bar.h>)
• #include <foo.h> is located in one of the project source files
Firstly, LDF finds the Foo library, then it parses all sources from the Foo library
and finds Foo/extra.cpp that depends on #include <bar.h>. Secondly, it will parse
all sources from the Bar library. This operation continues until all dependencies
will not be parsed.
Compatibility Mode
Compatibility mode allows one to control strictness of Library Dependency Finder. If
library contains one of manifest file (library_config, library.properties, module.json),
then LDF check compatibility of this library with real build environment. Available
compatibility modes:
off Does not check for compatibility (is not recommended)
soft [DEFAULT] Checks for the compatibility with projectconf_env_framework from build
environment
strict Checks for the compatibility with projectconf_env_framework and
projectconf_env_platform from build environment.
This mode can be changed using projectconf_lib_compat_mode option in projectconf. Default
value is set to soft.
C/C++ Preprocessor conditional syntax
In spite of the fact that Library Dependency Finder is written in pure Python, it
evaluates C/C++ Preprocessor conditional syntax (#ifdef, if, defined, else, and elif)
without calling gcc -E. For example,
platformio.ini
[env:myenv]
lib_ldf_mode = chain+
build_flags = -D MY_PROJECT_VERSION=13
mylib.h
#ifdef MY_PROJECT_VERSION
// include common file for the project
#include "my_common.h"
#endif
#if MY_PROJECT_VERSION < 10
// this include will be ignored because does not satisfy condition above
#include "my_old.h"
#endif
library.json
library.json is a manifest file of development library. It allows developers to keep
project in own structure and define:
• location of source code
• examples list
• compatible frameworks and platforms
• library dependencies
• advanced build settings
PlatformIO Library Crawler uses library.json manifest to extract source code from
developer's location and keeps a cleaned library in own Library Registry.
A data in library.json should be represented in JSON-style via associative array
(name/value pairs). An order doesn't matter. The allowable fields (names from pairs) are
described below.
Fields
• name
• version
• description
• keywords
• authors
• repository
• license
• downloadUrl
• homepage
• export
• include
• exclude
• frameworks
• platforms
• dependencies
• examples
• build
• flags
• unflags
• includeDir
• srcDir
• srcFilter
• extraScript
• libArchive
• libLDFMode
• libCompatMode
• Examples
name
Required | Type: String | Max. Length: 50
A name of the library.
• Must be unique.
• Should be slug style for simplicity, consistency and compatibility. Example:
Arduino-SPI
• Title Case, Aa-z, can contain digits and dashes (but not start/end with them).
• Consecutive dashes are not allowed.
version
Required | Type: String | Max. Length: 20
A version of the current library source code. Can contain a-z, digits, dots or dash and
should be Semantic Versioning <http://semver.org> compatible.
Example:
"name": "Bar",
"version": "1.0.0",
"repository":
{
"type": "git",
"url": "https://github.com/foo/bar.git"
}
description
Required | Type: String | Max. Length: 255
The field helps users to identify and search for your library with a brief description.
Describe the hardware devices (sensors, boards and etc.) which are suitable with it.
keywords
Required | Type: String | Max. Length: 255
Used for search by keyword. Helps to make your library easier to discover without people
needing to know its name.
The keyword should be lowercased, can contain a-z, digits and dash (but not start/end with
them). A list from the keywords can be specified with separator ,
authors
Required if repository field is not defined | Type: Object or Array
An author contact information
• name Full name (Required)
• email
• url An author's contact page
• maintainer Specify "maintainer" status
Examples:
"authors":
{
"name": "John Smith",
"email": "me@john-smith.com",
"url": "http://www.john-smith/contact"
}
...
"authors":
[
{
"name": "John Smith",
"email": "me@john-smith.com",
"url": "http://www.john-smith/contact"
},
{
"name": "Andrew Smith",
"email": "me@andrew-smith.com",
"url": "http://www.andrew-smith/contact",
"maintainer": true
}
]
NOTE:
You can omit authors field and define repository field. Only GitHub-based repository is
supported now. In this case PlatformIO Library Registry Crawler will use information
from GitHub API Users.
repository
Required if downloadUrl field is not defined | Type: Object
The repository in which the source code can be found. The field consists of the next
items:
• type the only "git", "hg" or "svn" are supported
• url
• branch if is not specified, default branch will be used. This field will be ignored if
tag/release exists with the value of version.
Example:
"repository":
{
"type": "git",
"url": "https://github.com/foo/bar.git"
}
license
Optional | Type: String
A license of the library. You can check the full list of SPDX license IDs. Ideally you
should pick one that is OSI approved.
"license": "Apache-2.0"
downloadUrl
Required if repository field is not defined | Type: String
It is the HTTP URL to the archived source code of library. It should end with the type of
archive (.zip or .tar.gz).
NOTE:
downloadUrl has higher priority than repository.
Example with detached release/tag on GitHub:
"version": "1.0.0",
"downloadUrl": "https://github.com/foo/bar/archive/v1.0.0.tar.gz",
"include": "bar-1.0.0"
See more library.json library_creating_examples.
homepage
Optional | Type: String | Max. Length: 255
Home page of library (if is different from repository url).
export
Optional | Type: Object
Explain PlatformIO Library Crawler which content from the repository/archive should be
exported as "source code" of the library. This option is useful if need to exclude extra
data (test code, docs, images, PDFs, etc). It allows one to reduce size of the final
archive.
Possible options:
• include
• exclude
include
Optional | Type: String or Array | Glob Pattern
If include field is a type of String, then PlatformIO Library Registry Crawler will
recognize it like a "relative path inside repository/archive to library source code". See
example below where the only source code from the relative directory LibrarySourceCodeHere
will be included.
"include": "some/child/dir/LibrarySourceCodeHere"
If include field is a type of Array, then PlatformIO Library Registry Crawler will
include only directories/files which match with include patterns.
Example:
"export": {
"include":
[
"dir/*.[ch]pp",
"dir/examples/*",
"*/*/*.h"
]
}
Pattern Meaning
┌────────┬──────────────────────────────────┐
│Pattern │ Meaning │
├────────┼──────────────────────────────────┤
│* │ matches everything │
├────────┼──────────────────────────────────┤
│? │ matches any single character │
├────────┼──────────────────────────────────┤
│[seq] │ matches any character in seq │
├────────┼──────────────────────────────────┤
│[!seq] │ matches any character not in seq │
└────────┴──────────────────────────────────┘
See more library.json library_creating_examples.
exclude
Optional | Type: String or Array | Glob Pattern
Exclude the directories and files which match with exclude patterns.
frameworks
Optional | Type: String or Array
A list with compatible frameworks. The available framework types are defined in the
frameworks section.
If the library is compatible with the all frameworks, then you can use * symbol:
"frameworks": "*"
platforms
Optional | Type: String or Array
A list with compatible platforms. The available platform types are defined in platforms
section.
If the library is compatible with the all platforms, then you can use * symbol:
"platforms": "*"
dependencies
Optional | Type: Array or Object
A list of dependent libraries. They will be installed automatically with cmd_lib_install
command.
Allowed requirements for dependent library:
• name | Type: String
• version | Type: String
• authors | Type: String or Array
• frameworks | Type: String or Array
• platforms | Type: String or Array
The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of
the following forms:
• 1.2.3 - an exact version number. Use only this exact version
• ^1.2.3 - any compatible version (exact version for 1.x.x versions
• ~1.2.3 - any version with the same major and minor versions, and an equal or greater
patch version
• >1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
• >0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than
0.3.0
The rest possible values including VCS repository URLs are documented in cmd_lib_install
command.
Example:
"dependencies":
[
{
"name": "Library-Foo",
"authors":
[
"Jhon Smith",
"Andrew Smith"
]
},
{
"name": "Library-Bar",
"version": "~1.2.3"
},
{
"name": "lib-from-repo",
"version": "https://github.com/user/package.git#1.2.3"
}
]
A short definition of dependencies is allowed:
"dependencies": {
"mylib": "1.2.3",
"lib-from-repo": "githubuser/package"
}
See more library.json library_creating_examples.
examples
Optional | Type: String or Array | Glob Pattern
A list of example patterns. This field is predefined with default value:
"examples": [
"[Ee]xamples/*.c",
"[Ee]xamples/*.cpp",
"[Ee]xamples/*.ino",
"[Ee]xamples/*.pde",
"[Ee]xamples/*/*.c",
"[Ee]xamples/*/*.cpp",
"[Ee]xamples/*/*.ino",
"[Ee]xamples/*/*.pde",
"[Ee]xamples/*/*/*.c",
"[Ee]xamples/*/*/*.cpp",
"[Ee]xamples/*/*/*.ino",
"[Ee]xamples/*/*/*.pde"
]
build
Optional | Type: Object
Specify advanced settings, options and flags for the build system. Possible options:
• flags
• unflags
• includeDir
• srcDir
• srcFilter
• extraScript
• libArchive
• libLDFMode
• libCompatMode
flags
Optional | Type: String or Array
Extra flags to control preprocessing, compilation, assembly and linking processes. More
details projectconf_build_flags.
unflags
Optional | Type: String or Array
Remove base/initial flags which were set by development platform. More details
projectconf_build_unflags.
includeDir
Optional | Type: String
New in version 4.0.
Custom location of library header files. A default value is include and means that folder
is located in the root of a library.
srcDir
Optional | Type: String
New in version 4.0.
Custom location of library source code. A default value is src and means that folder is
located in the root of a library.
srcFilter
Optional | Type: String or Array
Specify which source files should be included/excluded from build process. The path in
filter should be relative from a root of library.
See syntax in projectconf_src_filter.
Please note that you can generate source filter "on-the-fly" using extraScript (see below)
extraScript
Optional | Type: String
Launch extra script before build process. More details projectconf_extra_scripts.
Example (HAL-based library)
This example demonstrates how to build HAL-dependent source files and exclude other source
files from a build process.
Project structure
├── lib
│ ├── README
│ └── SomeLib
│ ├── extra_script.py
│ ├── hal
│ │ ├── bar
│ │ │ ├── hal.c
│ │ │ └── hal.h
│ │ ├── foo
│ │ ├── hal.c
│ │ └── hal.h
│ ├── library.json
│ ├── SomeLib.c
│ └── SomeLib.h
├── platformio.ini
└── src
└── test.c
platformio.ini
[env:foo]
platform = native
build_flags = -DHAL=foo
[env:bar]
platform = native
build_flags = -DHAL=bar
library.json
{
"name": "SomeLib",
"version": "0.0.0",
"build": {
"extraScript": "extra_script.py"
}
}
extra_script.py
Import('env')
from os.path import join, realpath
# private library flags
for item in env.get("CPPDEFINES", []):
if isinstance(item, tuple) and item[0] == "HAL":
env.Append(CPPPATH=[realpath(join("hal", item[1]))])
env.Replace(SRC_FILTER=["+<*>", "-<hal>", "+<%s>" % join("hal", item[1])])
break
# pass flags to a global build environment (for all libraries, etc)
global_env = DefaultEnvironment()
global_env.Append(
CPPDEFINES=[
("MQTT_MAX_PACKET_SIZE", 512),
"ARDUINOJSON_ENABLE_STD_STRING",
("BUFFER_LENGTH", 32)
]
)
libArchive
Optional | Type: Boolean
Create an archive (*.a, static library) from the object files and link it into a firmware
(program). This is default behavior of PlatformIO Build System ("libArchive": true).
Setting "libArchive": false will instruct PIO Build System to link object files directly
(in-line). This could be useful if you need to override weak symbols defined in framework
or other libraries.
You can disable library archiving globally using projectconf_lib_archive option in
projectconf.
libLDFMode
Optional | Type: String
Specify Library Dependency Finder Mode. See ldf_mode for details.
libCompatMode
Optional | Type: String
Specify Library Compatibility Mode. See ldf_compat_mode for details.
Examples
1. Custom macros/defines
"build": {
"flags": "-D MYLIB_REV=1.2.3 -DRELEASE"
}
2. Extra includes for C preprocessor
"build": {
"flags": [
"-I inc",
"-I inc/target_x13"
]
}
3. Force to use C99 standard instead of C11
"build": {
"unflags": "-std=gnu++11",
"flags": "-std=c99"
}
4. Build source files (c, cpp, h) at the top level of the library
"build": {
"srcFilter": [
"+<*.c>",
"+<*.cpp>",
"+<*.h>"
]
}
5. Extend PlatformIO Build System with own extra script
"build": {
"extraScript": "generate_headers.py"
}
generate_headers.py
Import('env')
# print(env.Dump())
env.Append(
CPPDEFINES=["HELLO=WORLD", "TAG=1.2.3", "DEBUG"],
CPPPATH=["inc", "inc/devices"]
)
# some python code that generates header files "on-the-fly"
Creating Library
PlatformIO librarymanager doesn't have any requirements to a library source code
structure. The only one requirement is library's manifest file - library_config,
library.properties or module.json. It can be located inside your library or in the another
location where PlatformIO Library Registry Crawler will have HTTP access.
Updates to existing libraries are done every 24 hours. In case a more urgent update is
required, you can post a request on PlatformIO community.
Contents
• Source Code Location
• At GitHub
• Under VCS (SVN/GIT)
• Self-hosted
• Register
• Examples
Source Code Location
There are a several ways how to share your library with the whole world (see examples).
You can hold a lot of libraries (split into separated folders) inside one of the
repository/archive. In this case, you need to specify include option of libjson_export
field to relative path to your library's source code.
At GitHub
Recommended
If a library source code is located at GitHub, then you need to specify only these fields
in the library_config:
• libjson_name
• libjson_version (is not required, but highly recommended for new librarymanager)
• libjson_keywords
• libjson_description
• libjson_repository
PlatformIO Library Registry Crawler will populate the rest fields, like libjson_authors
with an actual information from GitHub.
Example, DallasTemperature:
{
"name": "DallasTemperature",
"keywords": "onewire, 1-wire, bus, sensor, temperature",
"description": "Arduino Library for Dallas Temperature ICs (DS18B20, DS18S20, DS1822, DS1820)",
"repository":
{
"type": "git",
"url": "https://github.com/milesburton/Arduino-Temperature-Control-Library.git"
},
"authors":
[
{
"name": "Miles Burton",
"email": "miles@mnetcs.com",
"url": "http://www.milesburton.com",
"maintainer": true
},
{
"name": "Tim Newsome",
"email": "nuisance@casualhacker.net"
},
{
"name": "Guil Barros",
"email": "gfbarros@bappos.com"
},
{
"name": "Rob Tillaart",
"email": "rob.tillaart@gmail.com"
}
],
"dependencies": [
{
"name": "OneWire",
"authors": "Paul Stoffregen",
"frameworks": "arduino"
}
],
"version": "3.7.7",
"frameworks": "arduino",
"platforms": "*"
}
Under VCS (SVN/GIT)
PlatformIO Library Registry Crawler can operate with a library source code that is under
VCS control. The list of required fields in the library_config will look like:
• libjson_name
• libjson_keywords
• libjson_description
• libjson_authors
• libjson_repository
Example:
{
"name": "XBee",
"keywords": "xbee, protocol, radio",
"description": "Arduino library for communicating with XBees in API mode",
"authors":
{
"name": "Andrew Rapp",
"email": "andrew.rapp@gmail.com",
"url": "https://code.google.com/u/andrew.rapp@gmail.com/"
},
"repository":
{
"type": "git",
"url": "https://code.google.com/p/xbee-arduino/"
},
"frameworks": "arduino",
"platforms": "atmelavr"
}
Self-hosted
You can manually archive (Zip, Tar.Gz) your library source code and host it in the
Internet. Then you should specify the additional fields, like libjson_version and
libjson_downloadurl. The final list of required fields in the library_config will look
like:
• libjson_name
• libjson_keywords
• libjson_description
• libjson_authors
• libjson_version
• libjson_downloadurl
{
"name": "OneWire",
"keywords": "onewire, 1-wire, bus, sensor, temperature, ibutton",
"description": "Control devices (from Dallas Semiconductor) that use the One Wire protocol (DS18S20, DS18B20, DS2408 and etc)",
"authors":
{
"name": "Paul Stoffregen",
"url": "http://www.pjrc.com/teensy/td_libs_OneWire.html"
},
"version": "2.2",
"downloadUrl": "http://www.pjrc.com/teensy/arduino_libraries/OneWire.zip",
"export": {
"include": "OneWire"
},
"frameworks": "arduino",
"platforms": "atmelavr"
}
Register
The registration requirements:
• A library must adhere to the library manifest specification - library_config,
library.properties or module.json.
• There must be public HTTP access to the library manifest file.
Now, you can register your library and allow others to install it.
Examples
Command:
$ platformio lib register http://my.example.com/library.json
$ platformio lib register http://my.example.com/library.properties
$ platformio lib register http://my.example.com/module.json
• GitHub + detached release
• Dependencies by author and framework
• Multiple libraries in the one repository
Development Platforms
The PlatformIO ecosystem has a decentralized architecture, allowing development for a
range of development platforms. A development platform (or just "platform" for short) is
usually a particular microcontroller or processor architecture that PlatformIO projects
can be compiled to run on. (A few platforms, for example Teensy, use different target
architectures for different boards.)
Each of the three supported host systems Mac OS X, Linux and Windows support compiling for
all platforms listed below. Some platforms are also supported under ARM Linux hosts such
as Raspberry Pi. For each development platform, PlatformIO defines:
• The PlatformIO Build System build scripts for the supported frameworks and SDKs
• Pre-configured presets for embedded circuit boards
• Pre-compiled toolchains and related tools for the architechture(s)
Each project must specify the platform name using the projectconf_env_platform option in
projectconf. A specific platform version can optionally be specified as well. As embedded
boards are equipped with a particular microcontroller, each embedded board specifies what
development platform it uses and this can not be changed.
If a new board uses an architecture not in this list, a custom development platform can be
created; see platform_creating.
Embedded
Aceinna IMU
Configuration
projectconf_env_platform = aceinna_imu
Open-source, embedded development platform for Aceinna IMU hardware. Run custom algorithms
and navigation code on Aceinna IMU/INS hardware.
For more detailed information please visit vendor site.
Contents
• Examples
• Debugging
• Stable and upstream versions
• Packages
• Boards
Examples
Examples are listed from Aceinna IMU development platform repository:
• OpenIMU300RI
• OpenIMU330BI
• OpenRTK330LI
• OpenIMU300ZI
Debugging
piodebug - "1-click" solution for debugging with a zero configuration.
• Tools & Debug Probes
• On-Board Debug Tools
• External Debug Tools
Tools & Debug Probes
Supported debugging tools are listed in "Debug" column. For more detailed information,
please scroll table by horizontal. You can switch between debugging debugging_tools using
projectconf_debug_tool option in projectconf.
WARNING:
You will need to install debug tool drivers depending on your system. Please click on
compatible debug tool below for the further instructions.
On-Board Debug Tools
Boards listed below have on-board debug probe and ARE READY for debugging! You do not
need to use/buy external debug probe.
┌─────────────────────────────┬───────────────┬───────────┬───────┬───────┐
│Name │ MCU │ Frequency │ Flash │ RAM │
├─────────────────────────────┼───────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_LowCostRTK │ STM32F469NIH6 │ 180MHz │ 1MB │ 384KB │
└─────────────────────────────┴───────────────┴───────────┴───────┴───────┘
External Debug Tools
Boards listed below are compatible with piodebug but DEPEND ON external debug probe. They
ARE NOT READY for debugging. Please click on board name for the further details.
┌───────────────────────────────┬─────────────┬───────────┬───────┬───────┐
│Name │ MCU │ Frequency │ Flash │ RAM │
├───────────────────────────────┼─────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_OpenIMU300 │ STM32F405RG │ 120MHz │ 1MB │ 128KB │
├───────────────────────────────┼─────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_OpenIMU300ZA │ STM32F405RG │ 120MHz │ 1MB │ 128KB │
├───────────────────────────────┼─────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_OpenIMU330 │ STM32L431CB │ 80MHz │ 128KB │ 64KB │
├───────────────────────────────┼─────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_OpenRTK │ STM32F469IG │ 180MHz │ 1MB │ 384KB │
├───────────────────────────────┼─────────────┼───────────┼───────┼───────┤
│board_aceinna_imu_OpenRTK330L │ STM32F469IG │ 180MHz │ 1MB │ 384KB │
└───────────────────────────────┴─────────────┴───────────┴───────┴───────┘
Stable and upstream versions
You can switch between stable releases of Aceinna IMU development platform and the latest
upstream version using projectconf_env_platform option in projectconf as described below.
Stable
; Latest stable version
[env:latest_stable]
platform = aceinna_imu
board = ...
; Custom stable version
[env:custom_stable]
platform = aceinna_imu@x.y.z
board = ...
Upstream
[env:upstream_develop]
platform = https://github.com/aceinna/platform-aceinna_imu.git
board = ...
Packages
┌─────────────────────────┬──────────────────────────────────┐
│Name │ Description │
├─────────────────────────┼──────────────────────────────────┤
│tool-jlink │ SEGGER J-Link Software and │
│ │ Documentation Pack │
├─────────────────────────┼──────────────────────────────────┤
│tool-openocd │ OpenOCD │
├─────────────────────────┼──────────────────────────────────┤
│toolchain-gccarmnoneeabi │ gcc-arm-embedded │
└─────────────────────────┴──────────────────────────────────┘
WARNING:
Linux Users:
• Install "udev" rules faq_udev_rules
• Raspberry Pi users, please read this article Enable serial port on Raspberry Pi.
Windows Users:
Please check that you have a correctly installed USB driver from board manufacturer
Boards
NOTE:
• You can list pre-configured boards by cmd_boards command or PlatformIO Boards
Explorer
• For more detailed board information please scroll the tables below by horizontally.
Aceinna
────────────────────────────────────────────────────────────────────────────────────────
Name Debug MCU Frequency Flash RAM
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_LowCostRTK On-board STM32F469NIH6 180MHz 1MB 384KB
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_OpenIMU300 External STM32F405RG 120MHz 1MB 128KB
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_OpenIMU300ZA External STM32F405RG 120MHz 1MB 128KB
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_OpenIMU330 External STM32L431CB 80MHz 128KB 64KB
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_OpenRTK External STM32F469IG 180MHz 1MB 384KB
────────────────────────────────────────────────────────────────────────────────────────
board_aceinna_imu_OpenRTK330L External STM32F469IG 180MHz 1MB 384KB
┌───────────────────────────────┬──────────┬───────────────┬───────────┬───────┬───────┐
│ │ │ │ │ │ │
Atmel│AVR │ │ │ │ │ │
--
AUTHOR
PlatformIO
COPYRIGHT
2014-present, PlatformIO