MIDIpal firmware development under Mac OSX

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:

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

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

Thanks for the write-up!

> How to recover from a bricked device?

If only the application section of the flash is corrupted, the bootloader is still there so you can do a firmware update.

If the bootloader and/or fuses are corrupted, you’ll need an AVR programmer. But I don’t see how you could get reach this state from a factory-programmed device without using an AVR programmer in the first place.

> Is it possible to overwrite the bootloader with a bad .syx file?

No because the MIDIpal is programmed with a combination of fuses that write-protects the bootloader section.

> What is the “midipal_eeprom_golden.hex”?

This file gets written to the MIDIpal eeprom during factory programming and contains an initial value for all settings.

> Are fuses and locks corruptible with SysEx firmware updates?

No, there’s not even a piece of code in the application or bootloader section that touches them. They can only be modified with an AVR programmer.

nice write up! thanks.

i’m guessing there are some steps missing in the above. for example, i had to manually copy the contents of avril to avrlib, and i get the following when trying to build the syx file:

make: ***** No rule to make target `midipal.syx’. Stop.

" i had to manually copy the contents of avril to avrlib"

“git submodule init && git submodule update” after you clone the main repo.

“No rule to make target `midipal.syx”

From which directory do you run that?

midipal. ‘make’ run from the midipal folder works just fine.

I think the correct command is just “make syx” ?

cool, will try that tonight. next stop, crash course in C++, software development in general, and then implementing a custom Doepfer dark energy app.

lol. should be easy enough right?

Yes, it should be “make syx”

It was late when I originally posted!
(just edited the first post.)

For those interested I just posted my customized MIDIpal firmware here:

…add many new features to syncltch including footswitch arm/disarm.

For those interested seeing these code alterations my github link is here:

cool! will have a butchers. add pichnette’s line to the instructions above too:

git submodule init && git submodule update ::: after you clone the main repo

on an related note - anyone using the avrisp mkII on OSX?

not sure if it’s supported or not…

Yes, it works just fine.

good to know.

This seems like a good set up guide - http://mightyohm.com/blog/tutorials/avr-toolchain-installation/mac-os-x/

I was getting an error along the lines of “avrdude: ser_open(): can’t open device XYZ” last night when testing the programmer.

I couldn’t figure out whether this was because the programmer wasn’t recognized, or because i didn’t have xyz avr chip connected (I just wanted to verify the programmer on my macbook).

I was expecting something like “initilization failed, rc-1” if the programmer was recognized correctly and no chip was connected.

XYZ was? Name of a programmer family or chip?

Using AVR ISP mkII on two OS X machines, one with 10.5 and one with 10.8, no problem. Don’t remember if I had to install anything…

think it was the chip - can’t remember though, was late last night. will have a look again later. thanks.

What exact avrdude command did you use?
The commandline needs to include “-c avrispmkII -P usb” to point out this programmer type and the port (USB) it’s on…

ah - i was not setting “-p usb”. thanks both!

No problem! :slight_smile:

(note, it’s -P, not -p ! )

roger. and thanks again!