How To Define Custom Board within Project

mitchdetailed · March 31, 2024, 11:01pm

I had some trouble understanding what to do exactly, so I figured I’d try to help by answering the question of how to define a board from within the project files and not from within the .pio General file locations.

find a reference board project .json file using a similar package framework .json file for a board found in the C:\Users\{$USER}\.platformio\platforms\{$PLATFORM}\boards files.
once you have a project setup. create a folder called “boards” in the root project directory chosen.
copy the reference board .json file into the “boards” folder,
rename the file to whatever you want to call the board,
edit the .json to meet your needs.

And that’s it. Your custom board will be referenced when the project is built.
reference link : Custom Embedded Boards — PlatformIO v6.1 documentation

my example :

sivar2311 · April 1, 2024, 6:19am

This makes the board only available in the current project.

If you want to make it globally available for all projects, use the path
C:\Users\<USERNAME>\.platformio\boards

This folder will remain even if you delete or reinstall the platform.

mitchdetailed · April 21, 2024, 1:39am

That’s correct. For my instance, the goal was to have all documents provided inside a github folder to be cloned so the work flow was :
Clone repo, edit code as needed, upload, and you’re done.

freddymcloughlan · June 24, 2024, 7:36am

Just for future reference if anyone else is having the same issue I did:

If you get an error saying the board doesn’t exist, make sure you’re using the .json filename and your file is in the correct directory (see: boards_dir if using local dir)

If that is okay, make sure your platformio.ini file doesn’t contradict your board. For example, if your environment looks like:

[env:custom-esp32]
platform = espressif32
board = ESP32-S2-SOLO-2-N4
framework = arduino

Make sure your board definition supports the arduino framework and it’s respective platform or it may say it doesn’t exist. For me, I had a typo in the platform definition of the board and It said it didn’t exist. I deleted the platforms from the board .json config and it fixed it

bishoy_daniel · January 29, 2025, 5:32pm

Hi , i saw your reply to the topic “How To Define Custom Board within Project” , so you said that to make a board available globally we need to put the jason file in C:\Users<USERNAME>.platformio\boards , i tried that but when i comes to to create a project i get the following error:

PIO Core Call Error: ""The following files/directories have been created in C:\Users\Bisho\Documents\PlatformIO\Projects	esting indusrial sheilds Ardbox PLC
include - Put project header files here
lib - Put project specific (private) libraries here
src - Put project source files here
platformio.ini - Project Configuration File
Resolving ardbox_relay dependencies...


KeyError: Traceback (most recent call last):
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\__main__.py", line 103, in main
 cli() # pylint: disable=no-value-for-parameter
 ^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\click\core.py", line 1157, in __call__
 return self.main(*args, **kwargs)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\click\core.py", line 1078, in main
 rv = self.invoke(ctx)
 ^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\cli.py", line 85, in invoke
 return super().invoke(ctx)
 ^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\click\core.py", line 1688, in invoke
 return _process_result(sub_ctx.command.invoke(sub_ctx))
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\click\core.py", line 1434, in invoke
 return ctx.invoke(self.callback, **ctx.params)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\click\core.py", line 783, in invoke
 return __callback(*args, **kwargs)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\project\commands\init.py", line 106, in project_init_cmd
 install_project_dependencies(
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\package\commands\install.py", line 107, in install_project_dependencies
 already_up_to_date = not install_project_env_dependencies(env, options)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\package\commands\install.py", line 132, in install_project_env_dependencies
 _install_project_env_platform(project_env, options),
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\package\commands\install.py", line 149, in _install_project_env_platform
 PlatformPackageManager().install(
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\package\manager\platform.py", line 60, in install
 p.configure_project_packages(project_env, project_targets)
 File "C:\Users\Bisho\.platformio\penv\Lib\site-packages\platformio\platformase.py", line 185, in configure_project_packages
 self.configure_default_packages(options, targets or [])
 File "C:\Users\Bisho\.platformio\platforms\atmelavr\platform.py", line 47, in configure_default_packages
 self.packages[framework_package]["optional"] = False
 ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
KeyError: 'framework-arduino-avr-industrialshields'

============================================================

An unexpected error occurred. Further steps:

* Verify that you have the latest version of PlatformIO using
 `python -m pip install -U platformio` command

* Try to find answer in FAQ Troubleshooting section
 https://docs.platformio.org/page/faq/index.html

* Report this problem to the developers
 https://github.com/platformio/platformio-core/issues

============================================================"

maxgerhardt · January 29, 2025, 7:37pm

It looks like your board JSON file has a core definition of

{
  "build": {
    "core": "industrialshields",

Which will in turn instruct this code to activate the “framework-arduino-avr-industrialshields” package

github.com

platformio/platform-atmelavr/blob/26b79f8b52c0a046e79586b839fbe20547484561/platform.py#L28-L31


      
          if "arduino" in variables.get(
                  "pioframework", []) and build_core != "arduino":
          
              framework_package = "framework-arduino-avr-%s" % build_core.lower()

However, there is no such package defined in the platform.json. See

github.com

platformio/platform-atmelavr/blob/26b79f8b52c0a046e79586b839fbe20547484561/platform.json#L34-L51


      
          "framework-arduino-avr": {
            "type": "framework",
            "optional": true,
            "owner": "platformio",
            "version": "~5.2.0"
          },
          "framework-arduino-avr-attiny": {
            "type": "framework",
            "optional": true,
            "owner": "platformio",
            "version": "~1.5.2"
          },
          "framework-arduino-avr-bean": {
            "type": "framework",
            "optional": true,
            "owner": "platformio",
            "version": "~2.0.3"
          },

etc. So, as a next step, you would have to add your new package to that list, e.g.

    "framework-arduino-avr-industrialshields": {
      "type": "framework",
      "optional": true,
      "owner": "platformio",
      "version": "XXXXX"
    },

But as explained in Support for Industrial Sheilds Arduino based PLC e.g ARDBOX Relay PLC - #2 by maxgerhardt, you don’t need to do this.