I'm interested in writing an "Arduino core" (i. e. porting Arduino to a new MCU and new board(s)). I'm having trouble finding much documentation on how to do so. Am I missing something?

This page says "anyone may develop a core for their own boards following the rules and requirements we have issued." So, where are those "rules and requirements?"

I found something called the "Platform Specification", which sounded promising, but it only documents the config files; it does not say anything about the code that needs to be written to support a new platform.

I found ArduinoCore-API, which says it is the "hardware independent layer of Arduino core." But it doesn't mention anything about how to write the hardware-dependent part of the core.

I'd be grateful if anyone could point me to the Arduino core documentation. It's not turning up in my web searches. Thanks!


  • Yes, I can look at existing cores as examples, but I'd rather have the documentation, as well. Especially since existing cores may be of varying quality, or may not be up to the latest standard. Documentation is always a good thing.
  • The reason I want to write a core is because... I want to use an MCU which is not currently supported! (Specifically, I want to add support for the GD32F350, but really that shouldn't be relevant to answering "Where is the documentation?")
  • the specification you linked is all what you need. see existing cores as examples. why do you want to create a core?
    – Juraj
    Commented Apr 21, 2021 at 6:58
  • The specification doesn't say anything about the code I need to write. Where does it specify that?
    – user31708
    Commented Apr 21, 2021 at 8:02
  • I understand. The Arduino API is described here arduino.cc/reference/en. some parts are implemented in Arduino API repository. some depend on the hardware and must be implemented.
    – Juraj
    Commented Apr 21, 2021 at 8:30
  • 99% of writing a core is understanding, and coding for, the chip that you are working with. The specification cannot tell you that, since it completely depends on the chip architecture. You basically have two options: 1. use the pre-defined API layer and fill it out with your code behind it to make the functions work, or 2. write your own code that implements the API functions. The documentation is the list of API functions. It cannot tell you how to write those functions.
    – Majenko
    Commented Apr 21, 2021 at 10:07
  • some new Arduino cores for ARM MCUs are made on top of ARM mbed OS and use the mbed support for the MCU
    – Juraj
    Commented Apr 21, 2021 at 12:28

1 Answer 1


There are two major parts to writing an Arduino core: the hardware independent portions and the hardware dependent.

The hardware independent portions are pretty much done for you in the ArduinoCore-API. However I wouldn't just use that verbatim but use it as a starting point and adapt it to your needs. This is because it actually has a couple of unresolved issues and not everything may 100% fit your needs. We don't use it for the chipKIT core because:

  • It has an unresolved issue around the naming of the String.h file which conflicts with the libc's string.h on case insensitive filesystems
  • Our USB stack is vastly different to how the Arduino "Pluggable USB" works
  • We have extra facilities in a number of standard objects to make use of more efficient use of more advanced hardware

Once you have the hardware independent portion sorted you need to write, from scratch, the hardware dependent portion. The basic list of functions you need to implement are listed in the Arduino reference. How you write them cannot be documented, since that depends on the hardware. And you may well need to (or want to) write considerably more functions that just those. For example on chipKIT as well as the standard analogWrite() function we also have functions to change the PWM frequency and resolution - things that aren't part of the "standard", but are incredibly useful.

A good starting point is to examine the Arduino.h file of an existing core (the AVR core is a good baseline) which will list most of the functions and their parameter/return types. That gives you what the functions expect to receive and what they should emit, but how those functions are written is completely down to you.

And then of course you have to implement the boards variants etc to make the whole things work...

Also, be warned that writing (and maintaining) a core is a long and involved process and will consume the rest of your life.

  • Thanks! I guess it's a lot more obvious than I thought, in that you're directly implementing the API, rather than implementing some sort of "backend" functions that are called by the API. Still, some sort of "10,000 foot overview" doc would have been helpful. I'm not as worried about the "how", because I plan to just call into the chip vendor's firmware library.
    – user31708
    Commented Apr 21, 2021 at 16:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.