Skip to content

Latest commit

 

History

History
executable file
·
184 lines (125 loc) · 11.7 KB

platformio_doc.md

File metadata and controls

executable file
·
184 lines (125 loc) · 11.7 KB
Raw

PlatformIO Rules.

These are Bazel Starlark rules for building and uploading Arduino programs using the PlatformIO build system.

platformio_fs

platformio_fs(name, board, data, framework, platform, port, programmer)

Defines data that will be uploaded to the microcontroller's filesystem using PlatformIO.

Creates, configures and runs a PlatformIO project. This is equivalent to running:

platformio run

This rule is executable and when executed, it will upload the provided data to the connected Arduino device. This is equivalent to running:

platformio run -t uploadfs

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
board A string, name of the Arduino board to build this project for. You can find the supported boards in the PlatformIO Embedded Boards Explorer. This is mandatory. String required
data Filegroup containing files to upload to the device's FS memory. Label required
framework A string, the name of the framework for this project. String optional "arduino"
platform A string, the name of the development platform for this project. String optional "atmelavr"
port Port where your microcontroller is connected. This field is mandatory if you are using arduino_as_isp as your programmer. String optional ""
programmer Type of programmer to use: - direct: Use the USB connection in the microcontroller deveopment board to program it - arduino_as_isp: Use an arduino programmed with the Arduino as ISP code to in-circuit program another microcontroller (see https://docs.arduino.cc/built-in-examples/arduino-isp/ArduinoISP for details). - usbtinyisp: Use an USBTinyISP programmer, like https://www.amazon.com/gp/product/B09DG384MK String optional "direct"

platformio_library

platformio_library(name, add_hdrs, add_srcs, deps, hdr, lib_deps, src)

Defines a C++ library that can be imported in an PlatformIO project.

The PlatformIO build system requires a set project directory structure. All libraries must be under the lib directory. Furthermore all libraries can only consist of a single header and a single source file. The name of the library must match the names of the header file, the source file and the subdirectory under the lib directory.

If you have a C++ library with files my_lib.h and my_lib.cc, using this rule:

platformio_library(
    # Start with an uppercase letter to keep the Arduino naming style.
    name = "My_lib",
    hdr = "my_lib.h",
    src = "my_lib.cc",
)

Will generate a zip file containing the following structure:

lib/
  My_lib/
    My_lib.h
    My_lib.cpp

In the Arduino code, you should include this as follows. The PLATFORMIO_BUILD will be set when the library is built by the PlatformIO build system.

#ifdef PLATFORMIO_BUILD
#include <My_lib.h>  // This is how PlatformIO sees and includes the library.
#else
#include "actual/path/to/my_lib.h" // This is for native C++.
#endif

Outputs a single zip file containing the C++ library in the directory structure expected by PlatformIO.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
add_hdrs A list of labels, additional header files to include in the resulting zip file. List of labels optional []
add_srcs A list of labels, additional source files to include in the resulting zip file. List of labels optional []
deps A list of Bazel targets, other platformio_library targets that this one depends on. List of labels optional []
hdr A string, the name of the C++ header file. This is mandatory. Label required
lib_deps A list of external (PlatformIO) libraries that this library depends on. These libraries will be added to any platformio_project() rules that directly or indirectly link this library. List of strings optional []
src A string, the name of the C++ source file. This is optional. Label optional None

platformio_project

platformio_project(name, board, build_flags, deps, environment_kwargs, framework, lib_deps,
                   lib_ldf_mode, platform, port, programmer, src)

Defines a project that will be built and uploaded using PlatformIO.

Creates, configures and runs a PlatformIO project. This is equivalent to running:

platformio run

This rule is executable and when executed, it will upload the compiled firmware to the connected Arduino device. This is equivalent to running: platformio run -t upload

Outputs the C++ source file containing the Arduino setup() and loop() functions renamed according to PlatformIO needs, a platformio_ini with the project configuration file for PlatformIO and the firmware. The firmware_elf is the compiled version of the Arduino firmware for the specified board and the firmware_hex is the firmware in the hexadecimal format ready for uploading.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
board A string, name of the Arduino board to build this project for. You can find the supported boards in the PlatformIO Embedded Boards Explorer. This is mandatory. String required
build_flags A list of strings, any provided strings will directly appear in the generated platformio.ini file in the build_flags option for the selected env:board section. Refer to the Project Configuration File manual for the available options. List of strings optional []
deps A list of Bazel targets, the platformio_library targets that this one depends on. List of labels optional []
environment_kwargs A dictionary of strings to strings, any provided keys and values will directly appear in the generated platformio.ini file under the env:board section. Refer to the Project Configuration File manual for the available options. Dictionary: String -> String optional {}
framework A string, the name of the framework for this project. String optional "arduino"
lib_deps A list of external (PlatformIO) libraries that this project depends on. List of strings optional []
lib_ldf_mode Library dependency finder for PlatformIO (https://docs.platformio.org/en/stable/librarymanager/ldf.html). String optional "deep+"
platform A string, the name of the development platform for this project. String optional "atmelavr"
port Port where your microcontroller is connected. This field is mandatory if you are using arduino_as_isp as your programmer. String optional ""
programmer Type of programmer to use: - direct: Use the USB connection in the microcontroller deveopment board to program it - arduino_as_isp: Use an arduino programmed with the Arduino as ISP code to in-circuit program another microcontroller (see https://docs.arduino.cc/built-in-examples/arduino-isp/ArduinoISP for details). - usbtinyisp: Use an USBTinyISP programmer, like https://www.amazon.com/gp/product/B09DG384MK String optional "direct"
src A string, the name of the C++ source file, the main file for the project that contains the Arduino setup() and loop() functions. This is mandatory. Label required

PlatformIOLibraryInfo

PlatformIOLibraryInfo(default_runfiles, transitive_libdeps)

Information needed to define a PlatformIO library.

FIELDS

Name Description
default_runfiles Files needed to execute anything depending on this library.
transitive_libdeps External platformIO libraries needed by this library.