Skip to content

Commit 3df3f07

Browse files
maxgerhardtmaxgerhardt
authored
Add PlatformIO support (earlephilhower#250)
* Add package.json To make package easily integratable with PlatformIO * Correct name back to original one * Format package.json * Add first shot at builder script * Add USB stack flags, fix compile flags * Formatting * Add more link & USB flags * Build Boot2 bootloader * Formatting * Generate linkerscript, linker fixes * Fix linkflags, make firmware runnable * Update USB flags and RAM size * Correct USB flags, add dynamic sketch partitioning * Restructure filesystem size and flash size logic into platform code * Move C++ only flags to CXXFLAGS * Add PlatformIO documentation * Link to new platform.io document in the docs TOC * Fix typos in platformio docs * Fix one additional typo in platformio.rst * Update docs * Remove wrongly commited build folder
1 parent 3585c58 commit 3df3f07

File tree

6 files changed

+464
-4
lines changed

6 files changed

+464
-4
lines changed

‎docs/images/the_arduinoide_experience.png

28.5 KB
Loading

‎docs/images/the_platformio_experience.png

93 KB
Loading

‎docs/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
2020
Installation <install>
2121
IDE Menus <ide>
2222

23+
Platform.IO Integration <platformio>
24+
2325
Pin (Re)Assignment <pins>
2426

2527
Analog I/O <analog>

‎docs/platformio.rst

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
Using this core with PlatformIO
2+
===============================
3+
4+
What is PlatformIO?
5+
-------------------
6+
7+
`PlatformIO <https://platformio.org/>`__ is a free, open-source build-tool written in Python, which also integrates into VSCode code as an extension.
8+
9+
PlatformIO significantly simplifies writing embedded software by offering a unified build system, yet being able to create project files for many different IDEs, including VSCode, Eclipse, CLion, etc.
10+
Through this, PlatformIO can offer extensive features such as IntelliSense (autocomplete), debugging, unit testing etc., which not available in the standard Arduino IDE.
11+
12+
The Arduino IDE experience:
13+
14+
.. image:: images/the_arduinoide_experience.png
15+
16+
The PlatformIO experience:
17+
18+
.. image:: images/the_platformio_experience.png
19+
20+
Refer to the general documentation at https://docs.platformio.org/.
21+
22+
Especially useful is the `Getting started with VSCode + PlatformIO <https://docs.platformio.org/en/latest/integration/ide/vscode.html#installation), [CLI reference](https://docs.platformio.org/en/latest/core/index.html) and [platformio.ini options](https://docs.platformio.org/en/latest/projectconf/index.html)>`__ page.
23+
24+
Hereafter it is assumed that you have a basic understanding of PlatformIO in regards to project creation, project file structure and building and uploading PlatformIO projects, through reading the above pages.
25+
26+
Current state of development
27+
----------------------------
28+
29+
At the time of writing, PlatformIO integration for this core is a work-in-progress and not yet merged into mainline PlatformIO. This is subject to change soon.
30+
31+
If you want to use the PlatformIO integration right now, make sure you first create a standard Raspberry Pi Pico + Arduino project within PlatformIO.
32+
This will give you a project with the ``platformio.ini``
33+
34+
.. code:: ini
35+
36+
[env:pico]
37+
platform = raspberrypi
38+
board = pico
39+
framework = arduino
40+
41+
Here, you need to change the `platform` to take advantage of the features described hereunder.
42+
You *also* need to inject two PlatformIO packages, one for the compiler toolchain and one for the Arduino core package.
43+
44+
.. code:: ini
45+
46+
[env:pico]
47+
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
48+
board = pico
49+
framework = arduino
50+
; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
51+
platform_packages =
52+
maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
53+
maxgerhardt/toolchain-pico@https://github.com/earlephilhower/pico-quick-toolchain/releases/download/1.3.1-a/x86_64-w64-mingw32.arm-none-eabi-7855b0c.210706.zip
54+
55+
When the support for this core has been merged into mainline PlatformIO, this notice will be removed and a standard `platformio.ini` as shown above will work as a base.
56+
57+
Selecting the new core
58+
----------------------
59+
60+
Prerequisite for using this core is to tell PlatformIO to switch to it.
61+
There will be board definition files where the Earle-Philhower core will
62+
be the default since it's a board that only exists in this core (and not
63+
the other https://github.com/arduino/ArduinoCore-mbed). To switch boards
64+
for which this is not the default core (e.g. the standard
65+
``board = pico``), the directive
66+
67+
.. code:: ini
68+
69+
board_build.core = earlephilhower
70+
71+
must be added to the ``platformio.ini``. This controls the `core
72+
switching
73+
logic <https://github.com/maxgerhardt/platform-raspberrypi/blob/77e0d3a29d1dbf00fd3ec3271104e3bf4820869c/builder/frameworks/arduino/arduino.py#L27-L32>`__.
74+
75+
Flash size
76+
----------
77+
78+
Controlled via specifying the size allocated for the filesystem.
79+
Available sketch size is calculated accordingly by using (as in
80+
``makeboards.py``) that number and the (constant) EEPROM size (4096
81+
bytes) and the total flash size as known to PlatformIO via the board
82+
definition file. The expression on the right can involve "b","k","m"
83+
(bytes/kilobytes/megabytes) and floating point numbers. This makes it
84+
actually more flexible than in the Arduino IDE where there is a finite
85+
list of choices. Calculations happen in `the
86+
platform <https://github.com/maxgerhardt/platform-raspberrypi/blob/77e0d3a29d1dbf00fd3ec3271104e3bf4820869c/builder/main.py#L118-L184>`__.
87+
88+
.. code:: ini
89+
90+
; in reference to a board = pico config (2MB flash)
91+
; Flash Size: 2MB (Sketch: 1MB, FS:1MB)
92+
board_build.filesystem_size = 1m
93+
; Flash Size: 2MB (No FS)
94+
board_build.filesystem_size = 0m
95+
; Flash Size: 2MB (Sketch: 0.5MB, FS:1.5MB)
96+
board_build.filesystem_size = 1.5m
97+
98+
CPU Speed
99+
---------
100+
101+
As for all other PlatformIO platforms, the ``f_cpu`` macro value (which
102+
is passed to the core) can be changed as
103+
`documented <https://docs.platformio.org/en/latest/boards/raspberrypi/pico.html#configuration>`__
104+
105+
.. code:: ini
106+
107+
; 133MHz
108+
board_build.f_cpu = 133000000L
109+
110+
Debug Port
111+
----------
112+
113+
Via
114+
`build_flags <https://docs.platformio.org/en/latest/projectconf/section_env_build.html#build-flags>`__
115+
as done for many other cores
116+
(`example <https://docs.platformio.org/en/latest/platforms/ststm32.html#configuration>`__).
117+
118+
.. code:: ini
119+
120+
; Debug Port: Serial
121+
build_flags = -DDEBUG_RP2040_PORT=Serial
122+
; Debug Port: Serial 1
123+
build_flags = -DDEBUG_RP2040_PORT=Serial1
124+
; Debug Port: Serial 2
125+
build_flags = -DDEBUG_RP2040_PORT=Serial2
126+
127+
Debug Level
128+
-----------
129+
130+
Done again by directly adding the needed `build
131+
flags <https://github.com/earlephilhower/arduino-pico/blob/05356da2c5552413a442f742e209c6fa92823666/boards.txt#L104-L114>`__.
132+
When wanting to define multiple build flags, they must be accumulated in
133+
either a sing line or a newline-separated expression.
134+
135+
.. code:: ini
136+
137+
; Debug level: Core
138+
build_flags = -DDEBUG_RP2040_CORE
139+
; Debug level: SPI
140+
build_flags = -DDEBUG_RP2040_SPI
141+
; Debug level: Wire
142+
build_flags = -DDEBUG_RP2040_WIRE
143+
; Debug level: All
144+
build_flags = -DDEBUG_RP2040_WIRE -DDEBUG_RP2040_SPI -DDEBUG_RP2040_CORE
145+
; Debug level: NDEBUG
146+
build_flags = -DNDEBUG
147+
148+
; example: Debug port on serial 2 and all debug output
149+
build_flags = -DDEBUG_RP2040_WIRE -DDEBUG_RP2040_SPI -DDEBUG_RP2040_CORE -DDEBUG_RP2040_PORT=Serial2
150+
; equivalent to above
151+
build_flags =
152+
-DDEBUG_RP2040_WIRE
153+
-DDEBUG_RP2040_SPI
154+
-DDEBUG_RP2040_CORE
155+
-DDEBUG_RP2040_PORT=Serial2
156+
157+
USB Stack
158+
---------
159+
160+
Not specifying any special build flags regarding this gives one the
161+
default Pico SDK USB stack. To change it, add
162+
163+
.. code:: ini
164+
165+
; Adafruit TinyUSB
166+
build_flags = -DUSE_TINYUSB
167+
; No USB stack
168+
build_flags = -DPIO_FRAMEWORK_ARDUINO_NO_USB
169+
170+
Note that the special "No USB" setting is also supported, through the
171+
shortcut-define ``PIO_FRAMEWORK_ARDUINO_NO_USB``.
172+
173+
174+
Selecting a different core version
175+
----------------------------------
176+
177+
If you wish to use a different version of the core, e.g., the latest git
178+
``master`` version, you can use a
179+
`platform_packages <https://docs.platformio.org/en/latest/projectconf/section_env_platform.html#platform-packages>`__
180+
directive to do so. Simply specify that the framework package
181+
(``framework-arduinopico``) comes from a different source.
182+
183+
.. code:: ini
184+
185+
platform_packages =
186+
framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git#master
187+
188+
Whereas the ``#master`` can also be replaced by a ``#branchname`` or a
189+
``#commithash``. If left out, it will pull the default branch, which is ``master``.
190+
191+
The ``file://`` pseudo-protocol can also be used instead of ``https://`` to point to a
192+
local copy of the core (with e.g. some modifications) on disk.
193+
194+
Note that this can only be done for versions that have the PlatformIO
195+
builder script it in, so versions before 1.9.2 are not supported.
196+
197+
Examples
198+
--------
199+
200+
The following example ``platformio.ini`` can be used for a Raspberry Pi Pico
201+
and 0.5MByte filesystem.
202+
203+
.. code:: ini
204+
205+
[env:pico]
206+
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
207+
board = pico
208+
framework = arduino
209+
build_board.core = earlephilhower
210+
board_build.filesystem_size = 0.5m
211+
; note that download link for toolchain is specific for OS. see https://github.com/earlephilhower/pico-quick-toolchain/releases.
212+
platform_packages =
213+
maxgerhardt/framework-arduinopico@https://github.com/earlephilhower/arduino-pico.git
214+
maxgerhardt/toolchain-pico@https://github.com/earlephilhower/pico-quick-toolchain/releases/download/1.3.1-a/x86_64-w64-mingw32.arm-none-eabi-7855b0c.210706.zip
215+
216+
217+
The initial project structure should be generated just creating a new
218+
project for the Pico and the Arduino framework, after which the
219+
auto-generated ``platformio.ini`` can be adapted per above.

‎package.json

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
{
2-
"name": "framework-arduinopico",
3-
"description": "Arduino Wiring-based Framework (RPi Pico RP2040)",
4-
"url": "https://github.com/earlephilhower/arduino-pico",
5-
"version": "0.9.2"
2+
"name": "framework-arduinopico",
3+
"version": "1.10903.0",
4+
"description": "Arduino Wiring-based Framework (RPi Pico RP2040)",
5+
"keywords": [
6+
"framework",
7+
"arduino",
8+
"Cortex-M",
9+
"Raspberry Pi",
10+
"RP2040"
11+
],
12+
"homepage": "https://arduino-pico.readthedocs.io/en/latest/",
13+
"repository": {
14+
"type": "git",
15+
"url": "https://github.com/earlephilhower/arduino-pico"
16+
}
617
}

0 commit comments

Comments
 (0)