Skip to content

Latest commit

 

History

History
138 lines (98 loc) · 5.04 KB

contrib.rst

File metadata and controls

138 lines (98 loc) · 5.04 KB

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 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.

#if defined(ARDUINO_ARCH_RP2040) && !defined(__MBED__)
~~~ your changes ~~~
#endif

Identifying RP2040, RP2530A, or RP2350B

To check if a board is an original RP2040

#if defined(PICO_RP2040)
...OG Pico code...
#endif

For RP2350(A or B):

#if defined(PICO_RP2350)
...Pico 2 code...
#endif

For only RP2350A variants (using the compile options, not the onboard ID register):

#if defined(PICO_RP2350) && !defined(PICO_RP2350B)
...RP2350A only code...
#endif

For only RP2350B variants (again, at compile time as identified by the selected board and not the chip ID register):

#if defined(PICO_RP2350B)
...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.