From Zero to Custom - A Guide of how to use this software for noobies

ffabreti commented 1 year ago

So, you have gotten a MIDI Commander...

...and you have hit lots of limitations, so frustrating to get a good piece of hardware with a crappy software. But wait, that's not all, MeloAudio site seens to be heading the same crappy way. Enters midi-commander-custom. Harvie256 was kind enough to share his knowledge of reverse engineering poor firmwares and improving over it. But where do you begin ? You know nothing about C++ or Python and you just want to make music! Keep reading...

Firmwhat ?

First of, you need to understand a firmware is a bridge between a hardware and another software. In this case, when you press a button with you feet, the firmware will send a MIDI command thru a physical interface (5 pin MIDI or USB) to a computer, an Ipad, an amplifier or any other piece of software inside a hardware you want to control.

The problem with MIDI Commander is that it's firmware has very little functionality and installing midi-commander-custom will allow you to overcome those limitations.

According to Harvie256, this software is written in an area not used by the original firmware, what makes very easy to revert the changes if you need to get back to the original initial state.

How it works...

Great, let's understand how this software works. Midi-commander-custom is made of 2 parts:

a software that controls the hardware, written in C++ and responsible for interacting with the electronics inside like buttons, output ports, microcontrollers, etc. This will replace the MidiCommander firmware so that you can use the configuration software below (Python part). I will call this the Midi-commander-custom-firmware.
another software that configures the button actions, written in Python and responsible by customizing the ways the hardware will behave when a user interacts with the hardware. I will call this the Python-script.

The Midi-commander-custom-firmware

You can find this piece of software in DFU/DFU_OUT probably in a file named like generated-20220424-163714.dfu This is the piece of firmware that needs to be loaded to your MidiCommander device flash memory so that it will accept the configuration loaded by the Python-script later. To achieve this, you need to use a software like DfuSe (I used it on Windows 10) to upload this project DFU file into your MidiCommander device. This issue #16 has references to download, install and fix the DfuSe install on Windows, the procedure to upload the image is inside de DfuSe software. Be very carefull to exactly follow the steps.
Because MeloAudio site seems to be down, you may be need instructions on how to put you device in DFU mode:

With MidiCommander off, press buttons D and Down and turn the device on
You should hold D and Down until button 3 lights up
You can confirm your device is in DFU mode opening the Windows Device Manager and looking for "USB device in DFU Mode" under "USB Controllers" section.

The CSV config file used by the Python-script

The "Comma-Separated Values" file is where the user interacts with midi-commander-custom defining a configuration that will change the default behavior of Midi-Commander device. This CSV file is easily edited on Google-Sheets (or Excel) and the user may alter some arguments that will end-up at the physical memory of Midi-Commander and that will be read by the firmware device when it turns on. Remember to save the file as CSV (that is a text format) and NOT as XLS or similar binary format. It is important to say that the CSV file must not be edited at will, because it is a formatted file where the Phyton script will be expecting some sections and some fixed keywords so that it can read the user inputed config

Sections on the file start with a * Let's walk through each section of the CSV file

Global_Settings

Here you can define MIDI_Channel, RealTime_Passthroughand ConfigName. Not sure what the first two are supposed to mean, but the ConfigNameis the name that will show-up in the LCD display of Midi-Commander. Be careful with the length of ConfigNamebecause the display supports few characters.

Bank_Naming

Banks are like pages where you can write a config that will be acting over the 8 buttons Midi-Commander have. The 2 buttons at the right (UP and DOWN) are used to change between banks. As each bank have a specific config you can have and you may have 10 banks with midi-commander-custom, you can have 10 differents pages (banks) to produce 10 differents scenarios controlled by the same set of 8 buttons. So banks can have names that are shown at the LCD display when selected, so that you can realize which scenario you are current working on. Those names are defined in the parameters Bank_Name_Largeand Bank_Info_Small

Button_Settings

When you press a physical button, a MIDI message will be carried from `Midi-Commander` output to the other physical connected device input. A MIDI message is composed of a Command and a Channel. Of course MIDI messages carry aditional info to configure the command to be executed on the channel. All of it can be customised by `midi-commander-custom`:	Keyword	Applies to
CommandType	-	can be one of : PC (program change) CC (control change) Note (note to play) PB (pitch bend to execute) Start Stop
Channel	PC/CC/Note/PB	The channel your controlled midi device will be expecting commands to come from
Number	PC/CC/Note	The number of program or control or note to execute
OnValue	CC/PB	a value from 0 to 127 that sets the control or pitch at start
OffValue	CC	a value from 0 to 127 that sets the control or pitch at end
BankSelect	PC	?
BankSelectHighByte	PC	?
Toggle	CC/PB/Note	if the buttom press is hold or toggle the control or pitch or note
Velocity	Note	the strength (volume) of the note
Duration	Note/PB	number of millisecs? of the note or pitch

The Python Script

The Python Script CSV_to_Flash.py is used to convert and load the SpreadSheet that holds user configs into the physical flash memory of MidiCommander device. I supose there is a specific part of the flash memory that (besides holding the firmware) holds the configuration that will be active when the user press a button. That is exactly where the python script will write the config provided by the spreadsheet.

The script is then run from a terminal (I recommend a Linux virtual machine, not Windows WLS) taking as the only argument the spreadsheet path: python /some/path/CSV_to_Flash.py my_spreadsheet_config.csv

Note: after you edit your spreadsheet, save it as a CSV file. That is the format of the file expected by the script. Do not save it as XLS or XLSX because it will not work as an input the the python script.

continues...

andrema2 commented 1 year ago

This is going to be great.... Looking forward for the rest

Iztoksson commented 1 year ago

(hijacking this great guide, thanks @ffabreti) Does this also work with Harley Benton MP-100?

I will answer this myself - YES, it does work with Harley Benton MP-100 too.

angeloregis49 commented 11 months ago

Good job guys! I am also looking forward for the rest of the explanation.

eliericha commented 11 months ago

Hello folks,

In my fork of the project I expanded the documentation a bit on the topics of setting up Python and loading the CSV config and the firmware. It's over here. Hope this helps!

I also created a pull request to get it into the main project but I suspect that harvie256 might be busy these days as he hasn't been very active here recently :)

harvie256 commented 11 months ago

Thanks @eliericha I've merged the pull request.

Yes sorry, I've been in a field camp for the last couple of months so haven't been active of any projects!

eliericha commented 11 months ago

No worries, thanks @harvie256 !

harvie256 / midi-commander-custom