pio-project

Initialize a new PlatformIO project

$ pio project init

$ pio project init [[-d|--project-dir]] [path/to/project_directory]

$ pio project init [[-b|--board]] [ATmega328P|uno|...]

$ pio project init [[-O|--project-option]] "[option]=[value]" [[-O|--project-option]] "[option]=[value]"

$ pio project config

pio project <command> [options]

init [options]
    Initializes a new PlatformIO project in the current or specified directory. Allows selection of board, framework, and IDE for the project setup.

build [options]
    Compiles the project source code for the specified environment(s) and target(s). This command generates firmware binaries and other build artifacts.

upload [options]
    Uploads the compiled firmware binary to the target development board connected to the system. This often uses parameters to specify port or protocol.

clean [options]
    Removes compiled object files, firmware binaries, and other temporary build artifacts from the project, ensuring a fresh build on subsequent compilations.

run [options]
    A versatile command that can perform various actions on the project, such as building, uploading, monitoring serial output, or debugging. It serves as a unified entry point for project workflow.

config [options]
    Manages project configuration, allowing users to inspect or modify settings defined within the platformio.ini file programmatically.

data [options]
    Manages the project's data folder, typically used for storing assets like SPIFFS images or web interfaces for embedded devices.

deps [options]
    Manages project dependencies (libraries). This command can install, update, or uninstall libraries specified in the platformio.ini file.

The pio project command group is a fundamental component of the PlatformIO Core Command Line Interface (CLI). It provides comprehensive tools for managing the entire lifecycle of Internet of Things (IoT) and embedded development projects.

This command abstracts away the complexities of cross-platform development, allowing users to initialize new projects, configure build environments, manage dependencies (libraries), compile source code, upload firmware to target boards, and clean project artifacts. It supports a vast ecosystem of development boards, frameworks (like Arduino, ESP-IDF, Mbed), and debugging tools, making it an indispensable utility for developers working with embedded systems.

The commands within pio project interact heavily with the platformio.ini configuration file, which defines project-specific settings, environments, and build instructions. While primarily a CLI tool, its functionality is deeply integrated into popular IDEs, most notably the PlatformIO IDE extension for VSCode, providing a seamless graphical interface for these powerful project management capabilities.

The pio project commands require PlatformIO Core to be properly installed and configured on the system. Initial project setup and dependency resolution can involve significant downloads of toolchains, platforms, and libraries, which require an active internet connection. Project configuration heavily relies on the platformio.ini file, which must be correctly structured for the commands to function as expected and to define the project's specific requirements.

PlatformIO projects are primarily configured using the platformio.ini file, located in the project's root directory. This INI-style file defines build environments, target boards, frameworks, library dependencies, custom build flags, and upload/monitor settings. It is the central hub for customizing a project's behavior for different environments and hardware, offering granular control over the build process.

While pio project commands are executed from the command line, PlatformIO offers deep integration with various Integrated Development Environments (IDEs). The most popular integration is the PlatformIO IDE extension for Visual Studio Code, which provides a rich graphical interface for initializing, building, uploading, and debugging projects, all powered by the underlying pio project CLI commands. This integration streamlines the development process for users preferring a visual workflow.

PlatformIO was founded by Ivan Kravets with the vision of simplifying cross-platform embedded development. The pio project command group has been central to PlatformIO Core since its inception, evolving significantly to support a rapidly expanding ecosystem of microcontrollers, development boards, and frameworks. Its design emphasizes ease of use, automation, and cross-platform compatibility, making it a popular choice for both hobbyists and professional IoT developers. The continuous development focuses on integrating new hardware and software standards, further streamlining the embedded development workflow and enhancing developer productivity.

pio(1), make(1), gcc(1), cmake(1)