Midifighter Code
Brought to you by:
fatlimey,
midifidler
Menu
▾
▴
Tree [r13] / History
Read Me
Contents:
1. Features of the Midifighter v1
2. How to use the Menu System
3. How To Flash the Midifighter with new Firmware
4. How To set up the Development Environment
-------------------------------------------------------------------------------
Features of the Midifighter Firmware v1.2
=========================================
The Midifighter is a Class Compliant USB device, plug and play MIDI over USB
on Mac, PC and Linux.
It provides high performance key scanning, with keys read at 1000hz giving 1
millisecond response to keydowns and 10ms response to keyups (use to the
10-entry debounce buffer). We send the MIDI events to the host as fast as we
capture them.
The midifighter provides a Menu system as a boot-time option that allows you
to alter system settings which are written to persistent storage and reused
at every subsequent reboot. Hold down the top-left key (nearest the USB
socket) while powering up to enter Menu Mode.
MIDI Implementation
-------------------
The MIDI implementation has two modes of operation , "Normal" and
"Fourbanks" modes. In Normal operation, each of the 16 keys generates a
different MIDI NoteON/NoteOff pair when pressed and released. Additionally,
the LED for each key can be activated by sending a NoteOn to the device on
the same MIDI channel it uses for outputting notes. The default MIDI channel
is channel 3, and each NoteOn produces the same velocity (default 127), a
setting which can also be altered in the Menu system.
Under default settings, the keyboard generates notes from C2 to D#3
(assuming the standard MIDI interpretation that "Middle C" = C4, note 60),
and this is designed to line up the keypad with the default window of an
Ableton Live 8 drum map:
C3 C#3 D3 D#3
G#2 A2 A#2 B2
E2 F2 F#2 G2
C2 C#2 D2 D#2
or as MIDI note numbers:
48 49 50 51
44 45 46 47
40 41 42 43
36 37 38 39
The base note of this group (which default to note 36, C2) is selectable
through the menu system. The digital and analog expansion ports generate
note numbers above this range, creating a moveable "Note Window" in Normal
mode of 28 notes.
. . . . <- analog expansion = 24 .. 27
. . . . <- analog expansion = 20 .. 23
expansion -> . . . . <- digital expansion = 16 .. 19
o o o o <- bank 0 = 12 .. 15
o o o o <- bank 0 = 8 .. 11
o o o o <- bank 0 = 4 .. 7
basenote -> * o o o <- bank 0 = 0 .. 3
This means that the Normal Mode basenote can only have a value in the range
0 to 100.
In Fourbanks mode the top four keys select between four adjacent "banks" of
12 notes and the currently selected bank is highlighted with an LED on the
top row. When a bank is selected the bottom three rows of buttons switch their
note values accordingly:
. . . . <- analog expansion = 56 .. 59
. . . . <- analog expansion = 52 .. 55
expansion -> . . . . <- digital expansion = 48 .. 51
o o o o <- bank 3 = 44 .. 47
o o o o <- bank 3 = 40 .. 43
o o o o <- bank 3 = 36 .. 39
. . . . <- bank 2 = 32 .. 35
. . . . <- bank 2 = 28 .. 31
. . . . <- bank 2 = 24 .. 27
o o o o <- bank 1 = 20 .. 23
o o o o <- bank 1 = 16 .. 19
o o o o <- bank 1 = 12 .. 15
. . . . <- bank 0 = 8 .. 11
. . . . <- bank 0 = 4 .. 7
basenote -> * . . . <- bank 0 = 0 .. 3
The Fourbanks mode basenote can take a value in the range 0 to 68.
Expansion Ports
---------------
The Expansion Port has 4 debounced digital inputs that transmit on the four
notes above the keybaoard range (from basenote + 16 to basenote + 19 in
Normal mode, basenote + 48 to basenote + 51 in Fourbanks mode).
These are inputs are disabled by default to prevent random values from
unconnected hardware generating MIDI events but can be turned on using the
Menu system. When connecting switches to the digital inputs no pull-up
resistor is required as this is now handled by the CPU itself. Simply
connect the switch between the Digital Input Ppin and Ground. Activating the
switch will pull the pin low which the CPU will intepret as a keypress.
The Expansion Port also has 4 Analog Input Pins which can be enabled
independently from the Menu system. These analog inputs generate "smart
fader" output, a combination of interleaved CC and NoteOn/NoteOff messages
spread out along the fader's length. Four signals are sent in this precise
order:
a) A Control Change (CC) that varies from 0 to 127 along the entire
range of the fader.
b) A CC that transmots nothing for the first half of the range, then
transmits 0 to 127 along the second half of the range.
c) A Note that transmits a NoteOff when the fader enters the range 0 to 1,
and a NoteOn when it enters the range 1..127.
d) A Note that transmits a NoteOff when the fader enters the 126-127 range
and a NoteOff when it leaves that range.
This diagram shows the messages transmitted for Analog Input "A1":
|0------------------------------127| CC16
|0------------127| CC20
|off|on----------------------------| Note 52
|off----------------------------|on| Note 53
This order is chosen so that it is possible to use "MIDI Learn" to assign
the four messages in your favourite DAW.
-------------------------------------------------------------------------------
Menu Mode
=========
To enter Menu Mode, hold down the top-left key while resetting the
Midifighter. You can reset the Midifigher by either by plugging in the USB
cable, or by pressing an optional "reset" button that can be soldered to the
top left of the motherboard.
Once in Menu Mode, the LED will display 7 option keys and a flashing "exit"
key:
* * * * <- Menu items
* * * .
. . . .
. . . # <- Flashing exit key
Any changes made to the options are only written to the Midifighter if
you exit the Menu Mode through this top level "exit" button - this allows you
to playwith the options without having to remember the previous values.
Only when you are sure the Midifighter is set up to your specifications should
you use the top level "exit" button to commit your changes.
The seven menu items are:
MIDI channel
MIDI velocity
MIDI base note
Enable keypress LED
Enable Four Banks mode
Enable Expansion port Digital inputs
Enable Expansion Port Analog inputs
1. MIDI Channel
---------------
# . . . <- Flashing exit key
. . . .
* * * * <- MIDI Channel in binary
o . . o <- increment/decrement keys
Each note generated by the Midifighter is generated on a single MIDI
channel. By default this is Channel 3, but the first menu item allows you to
change this to any of the 16 MIDI channels. The 4-bit binary value can be
altered by incrementing and decrementing or you can directly toggle bits in
the value itself.
NOTE: MIDI channels are written down as "1..16" but their binary number is
written "0..15", therefore all leds off will represent the binary value
b0000, which is interpreted as "MIDI Channel 1", b0001 is "MIDI Channel 2",
b0100 is "MIDI Channel 5", etc.
2. MIDI Velocity
----------------
. # . . <- Flashing exit key
. * * * <- MIDI Channel in binary (high bits)
* * * * <- MIDI Channel in binary (low bits)
o . . o <- increment/decrement keys
Each NoteOn event has an accompanying velocity. As the Midifighter keys are
not velocity sensitive we use a single fixed value for all events. This menu
item allows you to alter that velocity value. The 7-bit binary value can be
altered by incrementing and decrementing or you can directly toggle bits in
the value itself.
3. MIDI Base Note
-----------------
. . # . <- Flashing exit key
. * * * <- MIDI note in binary (high bits)
* * * * <- MIDI note in binary (low bits)
o . . o <- increment/decrement
The lowest note generated by the keypad defaults to C2 (note 36), but the
16-key window can be positioned anywhere in the possible 127 MIDI notes. The
7-bit binary value can be altered by incrementing and decrementing or you
can directly toggle bits in the value itself.
NOTE: if the Expansion port Digital Inputs are enabled, the lowest value
that can be set in this menu is 4 = b0100 to allow the digital inputs to
generate the 4 MIDI notes immediately below the keypad.
4. Enable Keypress LED
----------------------
. . . # <- Flashing exit key
. . . .
* * * * <- All on or all off, click to toggle
o . . o <- Toggle
The LEDs react to MIDI inputs on the same channel and note numbers that they
generate when pressed. This allows advanced users to directly control the
display of information on the 4x4 grid using their software mappings. The
keypad also automatically lights the LED associated with a keypress. This
feature can be disabled if the user requires complete external control over
the 16 LEDs using this menu option.
The four LEDs of the "boolean bar" are either all on or all off. They can be
toggled using the increment/decrement buttons or by directly toggling the
LEDs.
5. Enable Fourbanks Mode
------------------------
. . . .
# . . . <- Flashing exit key
* * * * <- All on or all off, click to toggle
o . . o <- Toggle
"Fourbanks mode" is a mode of operation where the top four keys toggle
between four banks of 3x4 keys. The MIDI states on each bank are tracked
so switching to a different bank will correctly display the LED state.
NOTE: If the MIDI Base Note is set to a value higher than 68, it will be
truncated to 68 when Fourbanks mode is activated.
6. Enable Expansion Port Digital Inputs
---------------------------------------
. . . .
. # . . <- Flashing exit key
* * * * <- All on or all off, click to toggle
o . . o <- Toggle
Enabling this option causes the Midifighter to read the values of the
four external digital input pins and track their state using a debounce
buffer. Pins should be wired using a 10K ohm pull-up resistor with a
switch connecting the pin to ground to avoid unconnected pins for
generating spurious MIDI events.
The four LEDs of the "boolean bar" are either all on or all off. They
can be toggled using the increment/decrement buttons or by directly
toggling the LEDs.
7. Enable Expansion Port Analog Inputs
--------------------------------------
. . . .
. . # . <- Flashing exit key
* * * * <- All on or all off, click to toggle
o . . o <- Toggle
Enabling this option causes the Midifighter to read the analog values of
the four external Analog Inputs and generate MIDI Control Change (CC)
events on channels 16, 17, 18 and 19 (the "General Purpose 1-4" CC
channels) if the voltages change. The ADC samples the channels to 10-bit
accuracy but only the top 7 bits of this are used as the CC value.
The four LEDs of the "boolean bar" are either all on or all off. They
can be toggled using the increment/decrement buttons or by directly
toggling the LEDs.
-------------------------------------------------------------------------------
How To Flash the Midifighter with new Firmware
==============================================
The Midifighter uses a "DFU" style bootloader that allows the chip, once put
into "bootloader mode", to receive new programs and settings over the USB
connection. Any tool that supports the DFU command set can be used to flash
a new program to the Midifighter over USB.
To drop your Midifighter into Bootloader Mode, plug in the USB cable while
holding down the four corner keys:
# . . #
. . . .
. . . .
# . . #
The Midifighter show a checkerboard pattern to indicate that it is ready to
accept DFU commands:
* . * .
. * . *
* . * .
. * . *
Putting the Midifighter into bootloader mode causes it to disconnect from
USB and reconnect as a different kind of USB device (i.e. not a MIDI class
device), and on some systems this device type requires the installation of a
driver before the reflashing software will recognize the bootloader
device. Setting up this driver is a one-time installation that is only
required of you wish to reflash your Midifighter.
The EEPROMs inside the chip are designed to be programmable for several
thousand cycles, a number of flahes that will take serious amounts of
development time. It's just worth knowing that there is a limit and it may
be a, very improbable, cause of strange behaviors.
1. PC using Atmel Flip
----------------------
Using the program "Flip" from Atmel.
http://atmel.com/dyn/products/tools_card_mcu.asp?tool_id=3886
At the end of installation, you *must* select the option to read the README file:
file:///C:/Program%20Files/Atmel/Flip%203.4.1/info/Readme.html
as it contains instructions for installing the USB driver for the DFU
device. This driver allows connection to the DFU bootloader so that a
program can be uploaded. It's a normal driver install involving:
- Go to the device manager.
- Find the AT90USB162 device in the "Jungo" section.
- Right-click and select "Update Driver...".
- Select "Install from a specific location".
- Select "Include this location in the search" and specify the driver
location, which by default would be "C:/Program Files/Atmel/Flip 3.4.1/usb"
- Select "Finish" to finally install the driver.
- The device should appear in the "LibUSB-Win32 Devices" section.
Once installed, Flip is simple to use.
1. Select the chip that is to be programmed. Use the "chip" icon,the menu
item "Device/Select..." or press Ctrl-S. Select the option:
AT90USB162
This will tell the program what start address and size to use for
program uploads.
2. With the Midifighter connected and in Bootloader Mode, connect to the
device by pressing the "usb cable" icon and selecting "USB", or by
pressing Ctrl-U. Then select "Open" to connect to the Midifighter.
(TIP: If you are going to be doing software development on the
Midifighter, and uploading fresh firmware often, it's useful to
select the option:
"Settings/Preferences/Connecting-Closing/Auto-Connect"
This will save you from having to hit Ctrl-U to connect over USB
before each firmware upload.)
3. Load a ".hex" firmware file using the "File/Load Hex File..." option,
or by hitting Ctrl-L, and navigating to the hex file and hitting "OK".
4. Select the programming steps "Erase", "Program" and "Verify". This
will cause the old program data to be removed, the new data to be
written and then read back to verify that it was successfully uploaded
to the device. ("Blank Check" is used to verify that the erase
operation completed successfully and is mainly used to verify that a
chip is bad.)
5. Hit the "Run" button to execute the reprogramming.
6. Restart the Midifighter using the "Start Application" button, making
sure the "reset" option is selected, or just unplug and replug the USB
cable. The Midifighter should reset and act as if it has just been
plugged in. Depending on the purpose of the new firmware you may
notice no immediate difference, and if the EEPROM version has been
incremented you may have lost your persistent settings or you may in
rare situations encounter the "first boot hardware test". Read the
firmware release notes for more information on the exact behavior to
expect.
2. PC using the command line.
-----------------------------
If you are developing software for the Midifighter, it's sometimes useful to
be able to automate the reflashing process. Atmel Flip comes with a
command-line application for this called "batchisp.exe", and it can be found in
the same directory as the "flip.exe" binary.
The simplest way to access this program is to add the directory containing
the Flip binaries to the $PATH environment variable. For example, if you
have installed Flip version 3.4.1, the path can be appended using:
> set PATH = %PATH%;"C:\Program Files\Atmel\Flip 3.4.1\bin"
Reprogramming and rebooting a chip takes three calls of the program. To
reflash the Midifighter with a firmware file called "myhexfile.hex" you
would issue these three commands:
> batchisp -hardware usb -device at90usb162 -operation memory EEPROM erase
> batchisp -hardware usb -device at90usb162 \
-operation memory EEPROM loadbuffer myhexfile.hex program
> batchisp -hardware usb -device at90usb162 -operation start reset 0
3. Mac
------
(Thanks to SarahEmm)
You will need to download the latest ".hex" firmware from the Midifighter
sourceforge site:
http://sourceforge.net/projects/midifighter/files/
Then your steps are:
a) Ensure you have the Apple Developer Tools installed (they come on a
CD/DVD with new macs/new OSes)
b) Install "MacPorts". An installer can be found at
http://www.macports.org/install.php
c) Open a Terminal window, found under /Applications/Utilities/Terminal, to
get a command line.
d) At the command line, type
sudo /opt/local/bin/port install dfu-programmer
to build and install dfu-programmer and dependencies.
e) Hold down the four corner buttons on your Midifighter and plug in the USB
cable.
f) At the command line, type these three lines:
dfu-programmer at90usb162 erase
dfu-programmer at90usb162 flash --debug 1 midifighter.hex
dfu-programmer at90usb162 reset
where "midifighter.hex" is the name of the new firmware file to be
programmed.
g) Unplug and re-plug your Midifighter to start running the new firmware.
-------------------------------------------------------------------------------
How To set up the Development Environment
=========================================
Developing under Windows
------------------------
Create a project directory that will hold the libraries and tools, say,
"Midifighter" in an easy to find location. As many of the tools we will be
using are command-line based, keeping the path to this directory short will
help keep typing to a minimum. I keep my workspace at "C:\midifighter"
The source code for the Midifighter firmware can be downloaded from
Sourceforge at:
http://sourceforge.net/projects/midifighter/
Unzip the source tree into your project directory and you should find the
source code (.c and .h files) as well as the project Makefile. The source
code is heavily documented and is broken into logical systems with the main
program loop residing in "midifighter.c".
The Midifighter zip archive contains the source code only, and so you will
need to download two additional sets of libraries that are required to
produce working binaries. WinAVR is a set of libraries, compilers, debuggers
and command line tools for the AVR series of processors that can be found
at:
http://sourceforge.net/projects/winavr/
This version of the firmware was built against the "WinAVR 20100110"
version. WinAVR comes with an installer that installs all the tools and adds
the install path to the PATH environment variable. This means that all the
command line tools are instantly available at the command prompt. Part of
the WinAVR package is a set of Gnu Tools compiled for Win32 that provide the
Unix command line tools "make", "grep", "find" etc.
Next you will need to download the LUFA libraries for USB on AVR chips. This
library, written by Dean Camera can be found at:
http://www.fourwalledcubicle.com/LUFA.php
The current codebase is built against the "LUFA 101122" version. Create a
"LUFA101122" subdirectory (without the space)) inside the project directory
and Unzip the LUFA source code into that location. The resulting layout
after installing these tools should be:
drive (c:)
|_ Program Files
| |_ Atmel
| |_ Flip 3.4.1
| |_ bin
|_ ...
|_ WinAVR
| |_ bin
| |_ utils
|_ ...
|_ midifighter
|_ LUFA101122
| |_ Bootloaders
| |_ Demos
| |_ Documentation
| |_ LUFA
| |_ ...
|_ COPYING.txt
|_ Makefile
|_ README.txt
|_ adc.c
|_ adc.h
|_ constants.h
|_ eeprom.c
|_ eeprom.h
|_ expansion.c
|_ expansion.h
|_ fourbanks.c
|_ fourbanks.h
|_ key.c
|_ key.h
|_ led.c
|_ led.h
|_ menu.c
|_ menu.h
|_ midi.c
|_ midi.h
|_ midifighter.c
|_ selftest.c
|_ selftest.h
|_ spi.c
|_ spi.h
|_ usb_descriptors.c
|_ usb_descriptors.h
To build the firmware, open a command line (from the Start button you can use "All
Programs/Accessories/Command Prompt", or use the "Run..." option and execute
"cmd"). Change the directory to your project dir and build the project using
the make command:
> cd C:\midifighter
> make -s
The "-s" on the make command silences printout of the actual commands
executed (which is optional), but the output should resemble:
-------- begin --------
avr-gcc (WinAVR 20100110) 4.3.3
Copyright (C) 2008 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Compiling C: midifighter.c
Compiling C: eeprom.c
Compiling C: spi.c
Compiling C: adc.c
Compiling C: led.c
Compiling C: key.c
Compiling C: midi.c
Compiling C: menu.c
Compiling C: selftest.c
Compiling C: expansion.c
Compiling C: usb_descriptors.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/Device.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/Endpoint.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/Host.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/Pipe.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/USBController.c
Compiling C: LUFA101122/LUFA/Drivers/USB/LowLevel/USBInterrupt.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/DeviceStandardReq.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/Events.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/EndpointStream.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/HostStandardReq.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/PipeStream.c
Compiling C: LUFA101122/LUFA/Drivers/USB/HighLevel/USBTask.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/HIDParser.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/Audio.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/CDC.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/HID.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/MassStorage.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/MIDI.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Device/RNDIS.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/CDC.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/HID.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/MassStorage.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/MIDI.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/Printer.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/RNDIS.c
Compiling C: LUFA101122/LUFA/Drivers/USB/Class/Host/StillImage.c
Linking: midifighter.elf
Creating load file for Flash: midifighter.hex
Creating load file for EEPROM: midifighter.eep
Creating Extended Listing: midifighter.lss
Creating Symbol Table: midifighter.sym
Size after:
AVR Memory Usage
----------------
Device: at90usb162
Program: 7194 bytes (43.9% Full)
(.text + .data + .bootloader)
Data: 175 bytes (34.2% Full)
(.data + .bss + .noinit)
-------- end --------
At the end of this you will find a firmware image called "midifighter.hex"
in the project directory. This is the image that you "flash" to the
hardware.
Flashing from the Makefile
--------------------------
The Makefile that comes with the project contains a build target that will
reflash the Midifighter from the command line.
If you have already installed the Atmel Flip tool and added the "bin"
directory from that tool to your PATH environment variable:
> set PATH= %PATH%;C:\Program Files\Atmel\Flip 3.4.1\bin
we can use the "batchisp" command to do the work. Make sure the Midifighter
is in Bootloader Mode and execute "make flip". This will execute a script
that will upload the firmware and reset the Midifighter to start the program
executing:
> make flip
batchisp -hardware usb -device at90usb162 -operation erase f
Running batchisp 1.2.4 on Fri Oct 29 15:53:12 2010
AT90USB162 - USB - USB/DFU
Device selection....................... PASS
Hardware selection..................... PASS
Opening port........................... PASS
Reading Bootloader version............. PASS 1.0.5
Erasing................................ PASS
Summary: Total 5 Passed 5 Failed 0
batchisp -hardware usb -device at90usb162 -operation loadbuffer midifighter.hex program
Running batchisp 1.2.4 on Fri Oct 29 15:53:13 2010
AT90USB162 - USB - USB/DFU
Device selection....................... PASS
Hardware selection..................... PASS
Opening port........................... PASS
Reading Bootloader version............. PASS 1.0.5
Parsing HEX file....................... PASS midifighter.hex
Programming memory..................... PASS 0x00000 0x01c19
Summary: Total 6 Passed 6 Failed 0
batchisp -hardware usb -device at90usb162 -operation start reset 0
Running batchisp 1.2.4 on Fri Oct 29 15:53:14 2010
AT90USB162 - USB - USB/DFU
Device selection....................... PASS
Hardware selection..................... PASS
Opening port........................... PASS
Reading Bootloader version............. PASS 1.0.5
Starting Application................... PASS RESET 0
Summary: Total 5 Passed 5 Failed 0
There are similar targets for programming using the "dfu=programmer" tool or
hardware programming debugging using Avrdude and a JTAG programmer. Read the
Makefile for more information.
-------------------------------------------------------------------------------
Robin Green
(C) Copyright DJ Tech Tools 2010
October 29 2010
