Setting up MIDIpal firmware development environment under Mac OSX
(A little guide to get you started.)
BASICS:
(More advanced coders can skip this and go to TOOLS section.)
First I’d advise you to become familiar with the ‘Terminal’ under Mac OSX. You can find it under Applications/Utilities.
Go ahead and drag it to your dock if you haven’t already. If this is your first time using the Terminal, try typing the following commands:
pwd [return]
whoami [return]
cd ~ [return]
pwd [return]
ls [return]
cd Desktop [return]
ls -ltr [return]
cd … [return]
history [return]
clear [return]
TOOLS:
- CrossPack for AVR from OBDEV:
http://www.obdev.at/products/crosspack/download.html
IMPORTANT: get the older version
CrossPack-AVR-20100115.dmg
which is required for correctly compiling the Mutable Instruments’ code base.
- Git: sign up with and install Github:
https://github.com/
- Text/code editor of your choice. If you have Xcode installed, you can use that, but turn off any of auto code-completion.
- Python 2.5 or newer:
http://www.python.org/getit/
PLEASE NOTE: This scripting language is likely already installed in OSX. You can check by typing "python’ in the Terminal. If it is installed it will report the version number. To exit type ^d [control-d]. If you need to update, then go install. Otherwise, skip this step.
- Snoize SysEx Librarian:
http://www.snoize.com/SysExLibrarian/
Great free tool for inspecting and transferring MIDI SysEx (System Exclusive) files.
- Snoize MIDImonitor:
http://www.snoize.com/MIDIMonitor/
Another great free tool for displaying MIDI signals, with spying and filtering.
SETTING UP PATHS:
Open a new Terminal window and it type:
echo $SHELL [and press return]
If the output is /bin/bash
then type the following command:
echo ‘PATH=$PATH:/usr/local/bin’ >> ~/.bash_profile
all on one line. Press return.
If the output is /bin/csh or /bin/tcsh
then type the following command:
echo ‘set path = ($path /usr/local/bin)’ >> ~/.cshrc all on one line. Press return.
Close any Terminal windows and open up a new one.
This makes sure the .bash_profile or .cshrc is reloaded. Now type in
echo $PATH (for bash) or echo $path (for t/csh)
you should get something like the following:
/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin
The important thing is that the end of the line is /usr/local/bin
INSTALLING AVR:
Again, get the installer from here:
Be sure to grab the older version with avr-gcc 4.3.3 -
CrossPack-AVR-20100115.dmg
There was a major change in the AVR standard library for handling
constants residing in flash storage and the MIDIpal code was not
updated for it.
As a bonus, avr-gcc’s “-Os” in 4.3.2 / 4.3.3 produces smaller (but
less efficient) code than in later versions.
For more AVR Setup option in OSX, please read:
http://www.ladyada.net/learn/avr/setup-mac.html
BRANCHING / RETRIEVING SOURCE CODE and UTILS:
Setup up your working directory for your code brand.
it might be something like
~/my_code/mutable
cd to such working directory
Before getting ambitious with code hacks, you may want to first verify that you can build Pichenette’s code.
Clone the repository and activate it by typing in the following commands:
git clone https://github.com/pichenettes/midipal
cd midipal
git clone https://github.com/pichenettes/avril
git clone https://github.com/pichenettes/avril-firmware_tools
If you already make branches in Github, then you’d replace ‘pichenettes’ with your username.
Compile:
From the /midipal directory type:
make syx
If everything goes well this should create all the objects as including the .hex and .syx files in the /build/midipal directory.
Now type
ls -ltr build/midipal
Using Snoize’s SysEx Librarian, open the newly created SysEx file, midipal.syx and verify that it look like a plausible firmware update; there should be approx 245 blocks, each 267 bytes.
UNDERSTANDING FIRMWARE VARIANTS
Take a look at app.cc source file. In particular note the array
const AppInfo* registry[] = {}
See those preprocessor directives? #ifdef - #else - #endif
Next, take a look at midipal/makefile and see
EXTRA_DEFINES = -DDISABLE_DEFAULT_UART_RX_ISR -DUSE_SH_SEQUENCER -DUSE_TANPURA
Finally, take a look at avril/makefile.mk where these EXTRA_DEFINES get added to CPPFLAGS
Studying this will help you understand how to remove some apps if you need make room for your own.
HOW TO RECOVER FROM A “BRICKED” DEVICE.
??? Good question for Pichenettes…
Is it possible to overwrite the boot loader with a bad .Syx file?
What is the “midipal_eeprom_golden.hex”?
Are uses and locks corruptible with SysEx firmware updates?
???
