138 lines
5 KiB
ReStructuredText
138 lines
5 KiB
ReStructuredText
Contributing and Porting to the Core
|
|
====================================
|
|
|
|
First of all, thank you for contributing to the project. It's a lot of work
|
|
keeping up with all the different uses of the RP2040, so the more people
|
|
working on the code, the better. Your assistance can help the project
|
|
succeed.
|
|
|
|
Contributing to the Core (Pull Requests)
|
|
----------------------------------------
|
|
|
|
We use the standard GitHub Pull Request model. If you're unfamiliar with it,
|
|
this `guide <https://www.freecodecamp.org/news/how-to-make-your-first-pull-request-on-github-3/>`__
|
|
gives a simple overview of the process.
|
|
|
|
All pull requests have to pass a set of Continuous Integration (CI) checks
|
|
which help make sure the code compiles under different configurations and has
|
|
no spelling or style errors.
|
|
|
|
Tips for a Good Pull Request (PR)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
All code in the core and libraries, except for INO sketches, uses a 4-space
|
|
indent with cuddled brackets. When in doubt, copy your formatting from the
|
|
surrounding code. You should install ``astyle`` and run ``tests/restyle.sh``
|
|
on your machine before committing and pushing any pull requests to ensure
|
|
the formatting is correct.
|
|
|
|
Describe the change you're proposing and why it's important in your
|
|
``git commit`` message. If it fixes an open issue, place ``Fixes #xxxx``
|
|
(where xxxx is the issue number) in the message to link the two.
|
|
|
|
Try and only change one thing per pull request. That makes it easier to
|
|
review and prioritize. Opening up a separate PR per change also helps keep
|
|
track of them when release messages are generated.
|
|
|
|
Adding a New Board
|
|
------------------
|
|
|
|
Adding a new board requires:
|
|
|
|
* Updated ``tools/makeboards.py`` script
|
|
* Updated ``boards.txt`` file, generated by ``makeboard.py``
|
|
* Updated ``package_pico_index.template.json`` file, generated by ``makeboard.py``
|
|
* New ``tools/json/BOARD_NAME.json`` board file for Platform.IO
|
|
* New ``variants/BOARD_NAME/pins_arduino.h`` header defining the I/O pins
|
|
|
|
To add a new RP2040 board you will need to update the ``tools/makeboards.py``
|
|
script. Do *NOT* manually edit ``boards.txt``, that file is machine generated.
|
|
You will need to add a ``MakeBoard`` call at the end of the file. Please be sure
|
|
to add your board so that it sorts alphabetically, starting with the company name
|
|
and then the board name. Otherwise it is hard to find a specific board in the menu.
|
|
|
|
Run ``python3 tools/makeboards.py`` to update the ``boards.txt`` file and generate
|
|
a Platform.IO JSON file in the ``tools/json`` directory.
|
|
|
|
Create a folder called ``variants/BOARD_NAME`` and place in a ``pins_arduino.h``
|
|
file in it that contains your default pin name mapping (i.e. SPI0/1 pins, UART
|
|
pins, LED_DEFAULT, etc.). Copying one of the existing ones as a template can
|
|
make this task much simpler.
|
|
|
|
In your ``git commit`` be sure to add the newly generated ``tools/json/XXX.json``
|
|
file as well as the modified ``makeboards`` script and ``boards.txt``, the new
|
|
``pins_arduino.h`` header you generated, and the Arduino packaging JSON
|
|
``package/package_pico_index.template.json``. You should also add a note in
|
|
the ``README.md`` file listing your new board.
|
|
|
|
Submit the updated commit as a PR and, if all goes well, your board will be in
|
|
on the next core release.
|
|
|
|
|
|
Porting Libraries and Applications to the Core
|
|
----------------------------------------------
|
|
|
|
We try and follow Arduino standards so, with luck, porting to this core should
|
|
be relatively straightforward. The ``WiFi`` library and associates support
|
|
libraries like ``WebServer`` are modeled after the ESP32 and ESP8266 versions
|
|
of those libraries, combined with the "standard" Arduino ``WiFi`` one.
|
|
|
|
Compiler Defines for Porting
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you are adding RP2040 support to an existing library and need to isolate
|
|
code that only runs on this core, use the following define.
|
|
|
|
.. code:: cpp
|
|
|
|
#if defined(ARDUINO_ARCH_RP2040) && !defined(__MBED__)
|
|
~~~ your changes ~~~
|
|
#endif
|
|
|
|
Identifying RP2040, RP2530A, or RP2350B
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To check if a board is an original RP2040
|
|
|
|
.. code:: cpp
|
|
|
|
#if defined(PICO_RP2040)
|
|
...OG Pico code...
|
|
#endif
|
|
|
|
For RP2350(A or B):
|
|
|
|
.. code:: cpp
|
|
|
|
#if defined(PICO_RP2350)
|
|
...Pico 2 code...
|
|
#endif
|
|
|
|
For only RP2350A variants (using the compile options, not the onboard ID register):
|
|
|
|
.. code:: cpp
|
|
|
|
#if defined(PICO_RP2350A) && PICO_RP2350A
|
|
...RP2350A only code...
|
|
#endif
|
|
|
|
For only RP2350B variants (again, at compile time as identified by the selected board
|
|
and not the chip ID register):
|
|
|
|
.. code:: cpp
|
|
|
|
#if defined(PICO_RP2350A) && !PICO_RP2350A
|
|
...48-GPIO version code here
|
|
#endif
|
|
|
|
|
|
Library Architectures
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
After adding support in the code, libraries need their ``library.properties``
|
|
and ``library.json`` files updated to indicate support, or the IDE will
|
|
not know your new code is compatible here.
|
|
|
|
Add ``rp2040`` to ``architectures`` (in ``library.properties``) and
|
|
``"rp2040"`` to ``platforms[]`` (in ``library.json``) to let the tools know.
|
|
Note that even the RP2350 is identified as ``rp2040`` for this purpose.
|