DOCSEARCHbyAlgolia
Submit Docs

PlatformIO Documentation

repository·develop·Indexed 42 days ago

https://github.com/platformio/platformio-docs

Official documentation for PlatformIO, an embedded development ecosystem featuring a CLI, IDE extension, and package manager. Includes guides on static code analysis using pio check and Cppcheck, as well as unit testing with pio test, pio remote test, and frameworks such as Unity and Doctest.

Tokens
262.8K
Snippets
1.3K
Records
2K
Agent score
54%

What's inside PlatformIO

  1. Overview of PlatformIO Debugging

    develop

    PlatformIO provides a unified debugging experience designed for embedded development across multiple architectures and boards. It aims for a 'zero configuration' experience by using a rich configuration database that automatically handles the complexities of debugging servers based on your selected board and probe.

    Key features include:

    • Support for 300+ embedded boards.
    • Compatibility with Windows, MacOS, and Linux.
    • Integration with VS Code (recommended), Eclipse, and Sublime Text.
    • Support for various debugging probes and architectures.

  2. Overview of Static Code Analysis in PlatformIO

    develop

    PlatformIO provides integrated Static Code Analysis to identify potential bugs, vulnerabilities, and security threats in C/C++ code without requiring hardware execution. It helps detect defects such as:

    • Potential NULL pointer dereferences
    • Possible indexing beyond array bounds
    • Suspicious assignments
    • Reads of potentially uninitialized objects
    • Unused variables or functions
    • Out of scope memory usage

    Key benefits include integration with CI services, flexible rule configuration, and cross-platform support (Windows, MacOS, Linux).

  3. Configure debugging tools for Nordic nRF52

    develop

    PlatformIO supports debugging for Nordic nRF52 boards. Boards are categorized into two types:

    1. On-Board Debug Tools: These boards have an integrated debug probe and are ready for debugging immediately without external hardware.
    2. External Debug Tools: These boards are compatible with PlatformIO's debugging features but require an external debug probe to function.

    You can switch between different debugging tools using the debug_tool option in your platformio.ini file.

  4. Prerequisite for Static Code Analysis: Successful Build

    develop

    Before performing a static analysis check, you must ensure that your project builds successfully without errors. If the project fails to compile, the static analysis tools may not be able to process the source code correctly.

    To build your project, use the pio run command or your IDE's build functionality (e.g., VS Code with the PlatformIO extension).

  5. Debug SiFive boards with on-board tools

    develop

    Several SiFive boards include an on-board debug probe, meaning they are READY for debugging without requiring an external probe.

    Supported boards with on-board debugging:

    • sifive_e310-arty (MCU: FE310)
    • sifive_hifive-unleashed (MCU: FU540)
    • sifive_hifive1 (MCU: FE310)
    • sifive_hifive1-revb (MCU: FE310)
    • sifive_sparkfun_redboard_v (MCU: FE310)
    • sifive_sparkfun_thing_plus_v (MCU: FE310)

    You can switch between different debugging tools using the debug_tool option in your platformio.ini file.

  7. Debugging on Generic ATtiny84

    develop

    The Generic ATtiny84 does not have an on-board debug probe and is not ready for debugging out of the box. To enable debugging, you must use an external probe.

    • Default Debug Tool: simavr (Simulator) is supported by default.
    • Switching Tools: Use the debug_tool option in platformio.ini to switch between compatible debugging tools.
    • Requirement: You must install the appropriate drivers for your specific external debug tool on your system.

  8. Understand PlatformIO package types

    develop

    PlatformIO categorizes packages into three main types:

    • library: Assembly/C/C++ files used to extend project functionality.
    • platform: Development platforms that provide the necessary environment for specific hardware.
    • tool: Specialized programs, toolchains, or auxiliary files (such as frameworks or SDKs) used to build, debug, or upload firmware to a target device.

  9. Identify board debugging capabilities

    develop

    When selecting a board for development in PlatformIO, check its debugging support. Boards are categorized by their debug method:

    • On-board: The board includes an integrated debugger, allowing for direct debugging without additional hardware.
    • External: The board requires an external debug probe (e.g., ST-Link, J-Link) to perform debugging operations.

    Refer to the specific board tables in the documentation to confirm the required Platform, MCU, and Debug type for your hardware.

  10. Debug features in VS Code

    develop

    While PlatformIO supports multiple IDEs, the VS Code integration is recommended for the best system performance and modern interface. Key debugging features available in the VS Code extension include:

    • Local, Global, and Static Variable Explorer
    • Conditional Breakpoints
    • Expressions and Watchpoints
    • Generic Registers and Peripheral Registers
    • Memory Viewer
    • Disassembly
    • Multi-thread support
    • Hot restart of an active debugging session

  11. Configure Doctest using identifiers or Context

    develop

    Doctest can be configured in two ways:

    1. Using Identifiers (Macros)

    Use C++ preprocessor macros via build_flags in platformio.ini to control how Doctest is built. This is useful for performance optimizations or suppressing warnings.

    2. Using doctest::Context

    For runtime control, use the doctest::Context object within your custom main() function. This allows you to set options programmatically before running the tests.

    Example of programmatic configuration:

    int main(int argc, char **argv)
{
  doctest::Context context;

  // BEGIN:: PLATFORMIO REQUIRED OPTIONS
  context.setOption("success", true);
  context.setOption("no-exitcode", true);
  // END:: PLATFORMIO REQUIRED OPTIONS

  // YOUR CUSTOM DOCTEST OPTIONS
  context.setOption("abort-after", 5);    // stop test execution after 5 failed assertions
  context.setOption("order-by", "name");  // sort the test cases by their name

  context.applyCommandLine(argc, argv);
  return context.run();
}

  12. Available frameworks for ST STM8

    develop

    The ST STM8 platform supports the following frameworks:

    • Arduino: An Arduino-like programming API (framework-arduinoststm8) for writing cross-platform software.
    • SPL (Standard Peripheral Library): The standard peripheral library for ST STM8S/A microcontrollers (framework-ststm8spl).