MCU Integration Guide

[edbaafi]

Integration Guide

Background: Modkit is pushing Wiring as the preferred way for chip/board manufacturers to add hardware to Modkit Micro and other upcoming Modkit tools. This is pretty straightforward for AVR based boards but there is not a clear guide to adding new MCU's. Let's use this github issue thread to facilitate the creation of such a document. Let's keep this issue open until the documentation is complete and available in the source tree.

Files and directories

A given board entry in the Wiring drop-down-list is dependent on a number of files and directories. The following list attempts to explain how these different files and directories relate to the Wiring IDE and the microcontroller code build process.

Board Categories - Each folder in "wiring/framework/hardware" represents a different sub-menu in the Wiring IDE under tools->board. Logically, these folders are separated by manufacturer or other high level category.

Board Configurations - The actual boards in a given category are defined in a boards.txt file within that category's folder (eg: Wiring/framework/hardware/Wiring/boards.txt). Each board in the category has an entry in the boards.txt file of the follwing form:

WiringS.name=Wiring S @ 16 MHz
WiringS.upload.protocol=wiring
WiringS.build.mcu=atmega644p
WiringS.build.core=AVR8Bit
WiringS.build.hardware=WiringS

The name parameter determines the name that will show up in the drop down board list. The build.core parameter determines which core libraries will be used when compiling and corresponds to the name of a directory in the "wiring/framework/cores" folder. The build.hardware parameter determines which pin definitions (BoardDefs.h and BoardDefs.cpp) will be used and corresponds to the name of a directory within the "wiring/framework/hardware/CATEGORY" directory. The upload.protocol parameter determines which upload protocol will be used. It seems this is passed directly to avrdude.

Core Libraries This is the folder (eg wiring/framework/cores/AVR8Bit) referenced by the build.core parameter in the boards.txt file. This folder contains the core Wiring framework implementation for a given architecture as well as a "libraries" directory with any peripheral libraries (eg. Ethernet, Servo, etc).

Board/Hardware Definitions - This is the folder (eg wiring/framework/hardware/Wiring/WiringS) referenced by the build.hardware parameter in the boards.txt file. It contains the BoardDefs.h and BoardDefs.cpp files which are to be linked/compiled during compilation. Multiple products can share the same board definition (eg Arduino/Mega12802560).

[edbaafi]

So what does this mean we would need to do to add a new MCU? Adding a new MCU also requires adding a new board so here are the rough steps:

1. Decide which category the new board will go in or create a new one by creating a new directory as in wiring/framework/hardware/NEW_CATEGORY

2. Using the new board named NEW_BOARD, create a boards.txt file and place it in wiring/framework/hardware/NEW_CATEGORY:

##############################################################

NEW_BOARD.name=New Board Name
NEW_BOARD.upload.protocol=_NEW_UPLOAD_PROTOCOL
NEW_BOARD.build.mcu=NEW_MCU
NEW_BOARD.build.core=NEW_CORE
NEW_BOARD.build.hardware=NEW_BOARD_DEF
##############################################################

3. Create the "core" directory as in wiring/framework/cores/NEW_CORE and place all the platform specific library files there. Be sure to implement Wiring.h to include any of the other necessary files in this directory

4. Create a board definition folder as in wiring/framework/hardware/NEW_CATEGORY/NEW_BOARD_DEF and place BoardDefs.h and BoardDefs.cpp files there with pin mappings for the specific board.

[edbaafi]

And more specifically, what about the specific case of porting the Energia boards (based on Arduino) to the Wiring framework?

1. Create the wiring/framework/hardware/TI directory
2. Take the TI specific boards.txt file from Energia/hardware/msp430/boards.txt and place it in the wiring/framework/hardware/TI directory, changing xx.build.variant=xx to xx.build.hardware=xx:

###############################################################
lpmsp430g2231.name=LaunchPad w/ msp430g2231 (1MHz)
lpmsp430g2231.upload.protocol=rf2500
lpmsp430g2231.upload.maximum_size=2048
lpmsp430g2231.build.mcu=msp430g2231
lpmsp430g2231.build.f_cpu=1000000L
lpmsp430g2231.build.core=msp430
lpmsp430g2231.build.hardware=launchpad
##############################################################

3. Create wiring/framework/cores/msp430 and place all the platform specific library files from Energia/hardware/msp430 /cores/msp430 there. Rework Wiring.h to include everything included in Energia.h or you might be able to get away from just renaming Energia's Arduino.h to Wiring.h when copying. Then copy Energia/hardware/msp430/libraries/ to wiring/framework/cores/msp430/libraries/.

4. Create wiring/framework/hardware/TI/launchpad and place BoardDefs.h and BoardDefs.cpp files there. This should be a straightforward reorganization of Energia/hardware/msp430/variants/launchpad/pins_energia.h

[edbaafi]

But that's too easy right? Yes, but it shouldn't be.. Currently there are two things that are not as easy as just setting a configuration file and putting some directories and files in the right place (both in Arduino and Wiring). These two things are:

1. Adding a new compiler executable
2. Adding a new upload executable / protocol

Energia seems to have addressed #1 by modfying https://github.com/energia/Energia/blob/master/app/src/processing/app/debug/Compiler.java to check Base.getArch() against "msp430".

Energia seems to have addressed #2 by creating a new uploader java file: https://github.com/energia/Energia/blob/master/app/src/processing/app/debug/MSP430Uploader.java and referencing this from https://github.com/energia/Energia/blob/master/app/src/processing/app/Sketch.java. This also seems to use this Base.getArch call to choose the correct uploader.

I propose the TI team just gets things working in this way by adding the above additions along with the getArch additions from https://github.com/energia/Energia/blob/master/app/src/processing/app/Base.java. The Wiring team can then make the final tweaks to the integration plan and update your fork with the new way of defining compilers and uploaders. My thought is this should be done in a generic way as in ajd4096/Arduino@3c43d99

[edbaafi]

Wiring's creator Hernando (Damian) got in touch by email and sent me the following solutions to:

1. Adding a new compiler executable
2. Adding a new upload executable / protocol

Hernando explains the "toolchain" and "makefile" parameters in boards.txt.. Here's what he sent:

---

toolchains are supported in the application installation folder tools:
Wiring.app/tools/avr
Wiring.app/tools/arm etc

the can also be located in the Sketchbook folder:
Documents/Wiring/tools/avr
Documents/Wiring/tools/arm etc

in the boards.txt file two extra variables are defined:

WiringS.build.makefiles=Makefile,Variables.mk,Step1.mk,Step2.mk,Wiring.mk,Avrdude.mk
WiringS.build.toolchain=avr

the makefiles variable could be just one Makefile, in the example above there are defined several makefiles, this possibility to define multiple makefiles is for flexibility for the developers:

Makefile,Variables.mk,Step1.mk,Step2.mk,Wiring.mk,Avrdude.mk

or we could have just one:

WiringS.build.makefiles=Makefile

These makefiles are defined in a board basis so they should be located in the board folder, from the example above the Makefile,Variables.mk,Step1.mk,Step2.mk,Wiring.mk,Avrdude.mk should be located in the framework/hardware/Wiring/WiringS folder.

when a sketch is compiled these files or whatever files the developer defined in "board.build.makefiles=" are copied into the current sketch build folder, the IDE then generates a few environment variables in a file Variables.mk which is included in the main Makefile of the current sketch build folder, then the IDE invokes make and voila, this is it.
To upload etc, it invokes "make upload" etc. so the board handles the upload or whatever processes the developer wants inside the makefile file giving all possible flexibility to him.

This requires "make" to be available on osx, windows and linux. I see no problem with linux and perhaps forcing to install a minimum xcode package with command line tools for osx, windows seems to be the pain, but Marti found this:

"I've got Make working without Cygwin or MinGW on Windows 7 64-bit. You can try it for yourself by downloading the version of Make we ship with our ARM toolchain here:

http://static.leaflabs.com/pub/codesourcery/arm-2010q1-188-arm-none-eabi-toolchain-win32.zip

Extract the .zip, then the folder arm\bin\ that gets extracted to your PATH. You now have cs-make, a version of Make built by CodeSourcery to run natively on Windows. I've used it to build all of libmaple using our Makefile; it works fine from PowerShell, even in a directory with spaces in the path."

---

I think this approach to packaging a simple Make implementation make sense. Modkit will likely explore pymake (http://benjamin.smedbergs.us/pymake/) since Modkit's compiler/upload codebase is all python based.