Created By: Jacob Christ from pontech.com and Quick240.com, (hopefully) community maintained.
This guide is a starting point for anyone that is wishing to help improve the chipKIT-core API’s. That is to say, fix bugs, add features or help make the core more compatible with the Arduino/Wiring API.
Although one of the primary goals of both Arduino and chipKIT is to make getting started with embedded development as easy as possible. If you are new to core hacking then you are in for a bit of a learning curve. If you want to know more about the history of chipKIT and chipKIT-core skip to the end of this document. If you are ready to for core hacking then let’s get started.
Knowing where various files are intended to be stored within the Arduino IDE is crucial for successful core hacking.
· If you have made it this far you probably already know the following: within the Ardunio IDE when a user writes a program targeted for an embedded development platform these programs are called sketches.
· Sketches are stored in a folder called the “sketchbook”. The default sketchbook folder name is “Arduino”. In windows this folder is created in the users “Documents” folder the first time the Arduino IDE is run.
· Although not needed for core hacking it’s good to know that the default “sketchbook” folder can be changed from the Arduino IDE preferences dialog box. The preferences dialog box is accessible from the File menu in the Arduino IDE.
· Sketches can use “libraries” that provide additional canned functionality for your programs. Libraries can come from at least three different locations.
o Built in libraries that are part of the Arduino IDE.
o Libraries that are part of a specific core.
o User (aka contributed) libraries that are stored in the “libraries” folder within the “sketchbook” folder.
· Additional cores can be added to the IDE by adding a links to the “Additional Boards Manager URL’s” in the preference dialog box as described here. The additional cores are added into the “hardware” folder of for the IDE which is NOT to be confused with the following:
o The “Sketchbook” folder can have a sub folder called “hardware” that is used give the IDE access to compiler and APIs not accessible in the default download of the IDE.
o Whenever you make a change to any of these folders are where the IDE is looking for them you need to restart the IDE, it’s just not that smart.
The chipKIT wiki describes two ways to install a chipKIT-core.
1. Auto install via URL from within Arduino IDE
2. Manual install by copying ZIP file
The auto install will put the chipKIT-core into a place that is hidden from you but accessible by the Arduino IDE. On my computer, it puts it here:
C:\Users\Jacob Christ\AppData\Local\Arduino15\packages
The manual installation is better for hacking since it gets put into the “sketchbook” folder …/Arduino/hardware/ but for best results I recommend linking the git chipKIT-core repo to this directory as explained below.
The chipKIT-core repository is maintained in a git repository on github located here: https://github.com/chipKIT32/chipKIT-core
WHEN YOU FETCH DON’T FOR GET TO UPDATE YOUR SUBMODULES!
You can download, hack and contribute to the repository without using git, but if you plan on doing a lot of work on the repo or any other programming for that matter then it’s time to learn git. Learning and using git is outside the scope of this document but there is plenty of information on how to use it out there.
Once you have cloned the repo you will have a “chipKIT-core” folder (unless you renamed it). Inside this folder you have the following folders:
Source code for tool used by ANT for extracting git tags out of the repo when building the core.
Java jar files used by ANT when building the core.
Created by ANT when the project is built.
github.io chipKIT-core documentation web site.
Location of the pic32prog programming tool
This is where the chipKIT-core Wiring API’s live.
A smattering test files.
Used by ANT to create the chipKIT-core distributions. Try “ant build help” for a list of possible targets.
Reminders to the developers on how to build the distribution.
The chipKIT-core license file.
A publicly visible json file that tells the Arduino IDE how to install specific versions of chipKIT-core.
The chipKIT-core license file
Not sure what this file is for, I think it’s used by ANT
When I’m hacking the core, I’m doing it with the sole intention of making it better for myself and the community. Because of this I want to make it very easy for me to get my changes pushed back up to github so that I can make a pull request. Some might suggest modifying the files in your installed version of the core then copying them back to your cloned repo when you are ready to commit. I’m a bit lazier and prefer to operate directly on the core itself. Basically, it works like this. Clone chipKIT core into its own directory. Then create a symbolic directory link from your hardware folder in your sketchbook directory to the chipKIT-core repository. The hardware folder (in the sketch folder) is there to house custom cores for non-Arduino boards that provide the compilers and libraries necessary to compile your sketch (such at chipKITE-core). Build a distribution of the core in the chipKIT-core repository then copy compiler and tools directory from the build distribution back down to the pic32 directory in the chipKIT-core repo.
Here is how I accomplished this in windows:
· Open cmd prompt as administrator
· cd c:\sketchbook_folder\
· mkdir hardware
· cd hardware
· mkdir chipkit-core
· cd chipkit-core
· mklink /D pic32 c:\path_to_repos\chipKIT-core\pic32
· cd c:\path_to_repos\chipKIT-core
· ant build (see installing ant below if not installed)
· wait 10+ minutes for build to complete
· The next steps I do with the Windows file explorer
o copy the compiler and tools folder from c:\path_to_repos\chipKIT-core\dist\windows\chipkit-core\pic32 to c:\path_to_repos\chipKIT-core\pic32
· Edit c:\path_to_repos\chipKIT-core\pic32\platform.txt file and change the name from “chipKIT” to “chipKIT (git)” to make it easy to distinguish which core you are using in the Arduino IDE. NOTE: do not commit this change!
· At this point you open the Arduino IDE, select a chipKIT board form the “chipKIT (git)” menu and then edit core files in the path_to_repos\chipKIT-core\pic32.
If you have auto installed chipKIT-core, when you restart the IDE you will now have two copies of the chipKIT in your boards menu. The version which is hackable will show up in the Boards menu with the name “chipKIT (git)” after you restart the Arduino IDE. Happy hacking…
The previous section mentioned using ANT to build the distribution. Instructions for installing ANT can be found here:
In an effort to make this documentation better, I’ve decided to move some of the previous introduction (which is mostly history) to the end of the document. The thought being is that if you are looking to hack the core the history may only slow your efforts.
The chipKIT project started as fork of the Arduino IDE, plus its Wiring API as implemented for the Atmel AVR, with the express goal of making the tools work with the Microchip PIC32 microcontroller. Although the project started with the Microchip PIC32, the ultimate goal was to allow the growing number of people familiar with the Wiring API to use any microcontroller they wanted with a “Multi-Platform” IDE. The forked Arduino IDE was renamed to MPIDE for Multi-Platform IDE and initially supported both Atmel AVR and Microchip PIC32 devices.
Within the Ardunio IDE, when a user writes a program targeted for an embedded development platform these programs are called sketches.
The concept of a program as a sketch is trying to make the analogy of sketches in an artist’s sketch book.
As the Arduino community to expand their offerings to include the Arduino Due which was implemented with an Atmel SAM ARM processors they needed to change the Arduino IDE to support this new architecture. This was accomplished by pulling changes from MPIDE back into the Arudino IDE. Around version 1.6.5 of the Arduino IDE became the multi-platform IDE that MPIDE had always yearned to be. With this the chipKIT team dropped further MPIDE development in favor turning the ported PIC32 libraries into what is known at the chipKIT-core. The chipKIT-core can now be installed within the Arduino IDE Boards manager like many other cores for other boards and processor types.
Starting around version 1.6 of the Arduino IDE features were added to that allowed swapping out different compliers and libraries so that the IDE can support the variety of different microcontrollers that have sprung up around the Arduino community. The files that are brought in to support these boards are called “cores”.
The chipKIT-core project as it exists on github consists of the implementation of the Arduino/Wiring API as implemented for the Microchip PIC32 Microcontrollers. The core consists of the PIC32 gcc cross complier, PIC32 programming tools (picprog32), USB Drivers and Java/ANT build scripts. The Java/ANT build scripts allow for distributions to be built for multiple platforms including Windows, Mac OSX, Linux and Arm processors (Such as the RaspPI). The chipKIT-core at best is very useful in getting a PIC32 processor to do you bidding, at its worse its incomplete and needs help to improve it.