MIDIbox KB

Keyboard Controller with MIDI, USB-MIDI and Ethernet interface

This page collects some preliminary informations about the MIDIbox KB project.

MIDIbox KB utilizes the new MBHP_CORE_LPC17 and MBHP_DIO_MATRIX modules.

Currently following features are already implemented:

  • up to 2 keyboard matrices can be scanned separately at a very high scan rate (around 200 uS)
  • optional support for velocity!
  • 8 analog inputs of the core module can be used to connect pitchwheels, modulation wheel, sustain and expression pedal (or aftertouch).
    Alternatively a MBHP_AINSER8 module can be connected for higherer quality signal conversion without jitter.
  • analog inputs can be calibrated
  • two MIDI IN and two MIDI OUT ports
  • USB MIDI port with much higher transfer rate (ca. 100x faster!) than common MIDI
  • Ethernet port to send/receive events via OSC
  • support for DHCP - connect the module to a wireless router without additional configuration
  • different OSC modes are prepared for popular PC/Mac/iPhone/iPad apps, extensions can be added on request
  • integrated MIDI router with 16 configurable nodes
  • can also be used as USB/MIDI interface, or even as OSC/MIDI interface
  • configuration done via the MIOS Terminal of MIOS Studio
  • configuration is stored in on-board EEPROM of LPCXPRESSO module

Please note: the same keyboard driver is also available in MIDIbox NG. If you are searching for more capabilities (e.g. integrated controller with many pots, encoders, buttons, leds), consider to use the MBNG firmware instead of MBKB.

The main difference between the two applications is, that MIDIbox KB is optimized for high scan speeds! MIDIbox NG scans the keyboard 10 times slower to give the core more processing time for other tasks. However, with MBNG the latency to scan the whole keyboard is still lower than 3 mS (MBKB: 260 uS)!

Schematics

All schematics are subject to change without notice!

Supported Keyboard Types
Schematic Description
midibox_kb_scanmatrix_type1.pdf Type #1 Keyboard without velocity
midibox_kb_scanmatrix_type2.pdf Type #2 Keyboard with Velocity (e.g. Fatar DR type)
midibox_kb_scanmatrix_type3.pdf Type #3 Keyboard with Velocity (alternating switch)
Fatar DR Adapters to MBHP_DIO_MATRIX module
midibox_kb_fatar_df_61_interconnections.pdf Fatar DF Type with 61 keys
midibox_kb_fatar_df_76_interconnections.pdf Fatar DF Type with 76 keys
midibox_kb_fatar_df_88_interconnections.pdf Fatar DF Type with 88 keys

Terminal Commands

MIDIbox KB can be completely configured from the MIOS Terminal of MIOS Studio.

Enter 'help' to get a list of available commands.
Here a more detailed description of most commands:

help Lists all available commands (some of them are maybe not listed here)
store Stores the complete configuration (not only keyboard parameters, but also router, etc...) into the EEPROM of the LPCXPRESSO module, so that they will be restored during startup.
Usually a firmware update doesn't overwrite the stored parameters if not noticed in the ChangeLog.
Please enter the store command once you've adapted the parameters for your keyboard setup.
restore Restores the complete configuration from EEPROM. This command could become useful if you messed up the configuration, just type restore to undo the changes.
system Prints some system informations, such as the name and version number of the application.
reset Restarts the application remotely. Mainly intended for development.
set srio_num <1..16> Selects the number of DIN/DOUT shift registers (resp. 74HC165 and 74HC595) which should be scanned.
Examples:
set srio_num 2: two DIN and two DOUTs should be scanned
set srio_num 4: four DIN and four DOUTs should be scanned
set srio_num 6: e.g. if six DIN and four DOUTs should be scanned - more DINs than DOUTs, therefore the number of DINs is relevant here!
 Than more shift registers are scanned, than higher the latency of your keyboards. Therefore the minimum value is desired.
2 is typically a good choice if only one keyboard should be scanned, and 4 if two keyboard should be scanned.
kb <1|2>
keyboard <1|2>		 Prints a list of all keyboard parameters. MIDIbox KB can handle up to 2 keyboards in parallel, please specify the keyboard number with:
kb 1 or kb 2
set kb <1|2> debug <on|off> Enables some useful debugging messages for troubleshooting the hardware. This switch is not stored in EEPROM. Means: on each reset/power-on MIDIbox KB starts with debug mode disabled, and you have to enable it again.
Examples:
set kb 1 debug on: print some useful debugging messages for keyboard 1
set kb <1|2> midi_ports <ports> Each keyboard can send to one or multiple MIDI ports. They are currently (unfortunately) entered via a hexadecimal number, which is a nice short cut for techies, but probably difficult to understand for normal users. A more comfortable solution will be available once I found the time to improve the parser.
Coding:
  • Bit 0: USB1
  • Bit 1: USB2
  • Bit 2: USB3
  • Bit 3: USB4
  • Bit 4: MIDI OUT1
  • Bit 5: MIDI OUT2
  • Bit 12: OSC1
  • Bit 13: OSC2
  • Bit 14: OSC3
  • Bit 15: OSC4
Examples:
set kb 1 midi_ports 0x1011: keyboard 1 will send to USB1, OUT1 and OSC1
set kb 1 midi_ports 0x0020: keyboard 1 will only send to OUT2
set kb 2 midi_ports 0x0030: keyboard 2 will send to OUT1 and OUT2
set kb <1|2> midi_chn <channel> Each keyboard can send to a dedicated MIDI channel.
Select 1..16 for MIDI Channel 1..16. 0 will disable MIDI (no events will be sent to any channel)
 Examples:
set kb 1 midi_chn 1: keyboard 1 will send MIDI Channel 1
set kb 2 midi_chn 5: keyboard 2 will send MIDI Channel 5
set kb <1|2> note_offset <0-127> Sets the starting note of the leftmost key of your keyboard. The value is entered in decimal format.
Most important values:
  • 21: a-1 for Fatar DF Type with 88 keys
  • 28: E-0 for Fatar DF Type with 76 keys
  • 36: C-1 for Fatar DF Type with 61 and 49 keys
  • 48: C-2 for Fatar DF Type with 25 keys
Example:
set kb 1 note_offset 36: a Fatar 61 keys will start with C-1
set kb <1|2> rows <0-16> Specifies how many rows of the keyboard matrix have to be scanned.
If rows < 9, and a second DOUT is specified, the selection signal will be available on both DOUTs (perfect for 1:1 connection to a Fatar Keyboard with 61 keys)
Examples:
set kb 1 rows 8: keyboard 1 will scan 8 rows of the matrix -> up to 128 inputs = 64 break/make contacts (keys)
set kb 1 rows 16: for a different hardware: keyboard 1 will scan 16 rows of the matrix -> up to 256 inputs = 128 break/make contacts (keys)
set kb 2 rows 12: keyboard 2 will scan 12 rows of the matrix -> up to 192 inputs = 96 break/make contacts (keys)
set kb <1|2> velocity <on|off> off: each row will send a MIDI event with maximum velocity. Has to be used for keyboard with only one contact per key
on: one row is connect to "make" contacts, the next row to "break" contacts; period. This allows to measure the delay between contact activation in order to generate a velocity between 1 and 127 (see Fatar keyboard configuration examples below)
Examples:
set kb 1 velocity on: keyboard 1 provides two contacts to measure velocity
set kb 1 velocity off: keyboard 1 provides only one contact, resp. a common button matrix is used
set kb <1|2> release_velocity <on|off> off: when a key is released, a "Note On" event with velocity 0 will be sent.
on: when a key is released, a "Note Off" event with a velocity value which has been determined with the delay_fastest_release, delay_fastest_release_black_keys and delay_slowest_release parameters will be sent.
Example configuration:
  • set kb 1 release_velocity on
  • set kb 1 delay_fastest_release 100
  • set kb 1 delay_fastest_release_black_keys 80
  • set kb 1 delay_slowest_release 1000
set kb <1|2> optimized <on|off> Only valid in velocity mode.
off: break and make contacts are always scanned. This is the default configuration and should be used for debugging!
-> The resulting scan latency of a complete Fatar 63 keys keyboard is ca. 260 uS
on: make contacts will only be scanned if break contacts are active. This reduces the scan latency in most cases (no or only some keys are played). Won't work with Keyboard Type #3!
-> The resulting scan latency of a complete Fatar 63 keys keyboard is ca. 130 uS
Examples:
set kb 1 optimized off: keyboard 1 should be debugged because it doesn't send notes (e.g. type set kb 1 debug on thereafter).
set kb 1 optimized on: keyboard 1 should run in low-latency mode. Type store thereafter if the keyboard works as expected!
set kb <1|2> dout_sr1 <0-16> Selects the first DOUT shift register which is used to select the keyboard matrix rows.
Examples:
set kb 1 dout_sr1 1: row selection lines 1..8 of keyboard 1 are connected to first DOUT shift register.
set kb 2 dout_sr1 3: row selection lines 1..8 of keyboard 2 are connected to third DOUT shift register.
set kb 1 dout_sr1 0: disable this function for keyboard 1 (use DOUT for other purposes)
set kb <1|2> dout_sr2 <0-16> Selects the second DOUT shift register which is used to select the keyboard matrix rows.
Examples:
set kb 1 dout_sr2 2: row selection lines 9..16 of keyboard 1 are connected to the second DOUT shift register (if rows < 9, this DOUT will output the same pattern as dout_sr1)
set kb 2 dout_sr2 4: row selection lines 9..16 of keyboard 2 are connected to the fourth DOUT shift register (if rows < 9, this DOUT will output the same pattern as dout_sr1)
set kb 1 dout_sr2 0: disable this function for keyboard 1 (use DOUT for other purposes)
set kb <1|2> din_sr1 <0-16> Selects the first DIN shift register which is used to scan a keyboard matrix row.
Examples:
set kb 1 din_sr1 1: left side of keyboard 1 is connected to first DIN shift register.
set kb 2 din_sr1 3: left side of keyboard 2 is connected to third DIN shift register.
set kb 1 din_sr1 0: disable this function for keyboard 1 (use DIN for other purposes)
set kb <1|2> din_sr2 <0-16> Selects the second DIN shift register which is used to scan a keyboard matrix row.
Examples:
set kb 1 din_sr2 2: right side of keyboard 1 is connected to second DIN shift register.
set kb 2 din_sr2 4: right side of keyboard 2 is connected to fourthDIN shift register.
set kb 1 din_sr1 0: disable this function for keyboard 1 (use DIN for other purposes)
set kb <1|2> din_key_offset <0-127> Selects the offset which is added to the keys of the right half. Typically 32 for velocity keyboards (64 contacts), and 64 for non-velocity keyboards.
Examples:
set kb 1 din_key_offset 32: key number starts at 32 for the right side of keyboard 1 (velocity sensitive), e.g. suitable for Fatar 61 and 76 keys
set kb 1 din_key_offset 40: key number starts at 40 for the right side of keyboard 1 (velocity sensitive), e.g. suitable for Fatar 88 keys
set kb 1 din_key_offset 64: key number starts at 64 for the right side of keyboard 1 (no velocity)
set kb <1|2> din_inverted <on|off> This option should be enabled if diodes are used with the opposite polarity, and pull-downs are connected to DINs.
Examples:
set kb 1 din_inverted off: diodes with "normal" direction and pull-up resistors at 74HC165
set kb 1 din_inverted on: diodes with opposite direction and pull-down resistors at 74HC165
set kb <1|2> break_inverted <on|off> This option should be enabled for velocity keyboards with single switches (instead of break/make swicthes).
Examples:
set kb 1 break_inverted off: we have a break and make switch per key -> Type #2
set kb 1 break_inverted on: we have only a single switch per key -> Type #3
set kb <1|2> break_is_make <on|off> This option allows to trigger a note when the break contact is activated (nice for playing organ style) Examples:
set kb 1 break_is_make off: normal behaviour: MIDI note will be played when make contact is activated.
set kb 1 break_is_make on: MIDI note already send when the break contact is activated.
set kb <1|2> make_debounced <on|off> This option has to be enabled for certain keyboard architectures, such as Fatar TP400. Note Off will be played when the Break contact has been released, and not when the Make contact has been released.
Examples:
set kb 1 make_debounced off: for usual keyboard architectures
set kb 1 make_debounced on: for unusual keyboard architectures such as Fatar TP400
set kb <1|2> delay_fastest <0-65535> Only relevant for velocity sensitive keyboards: selects the minimum delay value at which the maximum velocity (=127) should be sent. Use debug mode to display the minimum delay when keys are hit strongly!
Examples:
set kb 1 delay_fastest 100: send maximum velocity when delay is <= 100
set kb 1 delay_fastest 200: send maximum velocity when delay is <= 200
set kb <1|2> delay_fastest_release <0-65535> The same for the release_velocity option.
set kb <1|2> delay_fastest_black_keys <0-65535> Optionally it's possible to specify a different delay value for the black keys (if 0: the value of delay_fastest will also be used for black keys - default!).
Background: it turned out, that black keys reach the make contact faster than white keys. By specifying a different delay value it's possible to compensate this.
set kb <1|2> delay_fastest_release_black_keys <0-65535> The same for the release_velocity option.
set kb <1|2> delay_slowest <0-65535> Only relevant for velocity sensitive keyboards: selects the maximum delay value at which the minimum velocity (=1) should be sent. Use debug mode to display the maximum delay when keys are hit softly!
Examples:
set kb 1 delay_slowest 1000: send maximum velocity when delay is >= 1000
set kb 1 delay_slowest 2000: send maximum velocity when delay is >= 2000
set kb <1|2> delay_slowest_release <0-65535> The same for the release_velocity option.
set kb <1|2> ain_pitchwheel <0-7, 128-135 or off> A number from 0..7 selects the J5.Ax input to which the PitchWheel pot is connected. A number of 128..135 selects the AINSER8 located Ax input. Use off if no PitchWheel is used to avoid that the unconnected analog input will send random MIDI events!
Examples:
set kb 1 ain_pitchwheel 0: PitchWheel of keyboard 1 connected to J5.A0 of the core module
set kb 2 ain_pitchwheel 3: PitchWheel of keyboard 2 connected to J5.A3 of the core module
set kb 1 ain_pitchwheel 128: PitchWheel of keyboard 1 connected to A0 of an AINSER8 module
set kb 2 ain_pitchwheel 131: PitchWheel of keyboard 2 connected to A3 of an AINSER8 module
set kb 1 ain_pitchwheel off: no PitchWheel connected
set kb <1|2>
ain_pitchwheel_inverted
<on|off>		 Inverts the output of the PitchWheel.
Examples:
set kb 1 ain_pitchwheel_inverted off: (default) PitchWheel outputs -8192..8191
set kb 1 ain_pitchwheel_inverted on: PitchWheel outputs 8191..-8192
set kb <1|2> ctrl_pitchwheel <0-129> What kind of MIDI events should be sent by the PitchWheel?
  • 0..127: CC#0 .. CC#127
  • 128: PitchBend (default)
  • 129: Aftertouch
Examples:
set kb 1 ctrl_pitchwheel 128: the PitchWheel of keyboard 1 sends PitchBend MIDI events
set kb 1 ctrl_pitchwheel 129: the PitchWheel of keyboard 2 sends Aftertouch MIDI events
set kb <1|2> ain_modwheel <0-7, 128-135 or off> A number from 0..7 selects the J5.Ax input to which the ModWheel pot is connected. A number of 128..135 selects the AINSER8 located Ax input. Use off if no ModWheel is used to avoid that the unconnected analog input will send random MIDI events!
Examples:
set kb 1 ain_modwheel 1: ModWheel of keyboard 1 connected to J5.A1 of the core module
set kb 2 ain_modwheel 4: ModWheel of keyboard 2 connected to J5.A4 of the core module
set kb 1 ain_modwheel 129: ModWheel of keyboard 1 connected to A1 of an AINSER8 module
set kb 2 ain_modwheel 132: ModWheel of keyboard 2 connected to A4 of an AINSER8 module
set kb 1 ain_modwheel off: no ModWheel connected
set kb <1|2>
ain_modwheel_inverted
<on|off>		 Inverts the output of the ModWheel.
Examples:
set kb 1 ain_modwheel_inverted off: (default) ModWheel outputs 0..127
set kb 1 ain_modwheel_inverted on: ModWheel outputs 127..0
set kb <1|2> ctrl_modwheel <0-129> What kind of MIDI events should be sent by the ModWheel?
  • 0..127: CC#0 .. CC#127 (default: CC#1)
  • 128: PitchBend
  • 129: Aftertouch
Examples:
set kb 1 ctrl_modwheel 1: the ModWheel of keyboard 1 sends CC#1 (CC Modulation)
set kb 2 ctrl_modwheel 7: the ModWheel of keyboard 2 sends CC#7 (CC Volume)
set kb <1|2> ain_sustain <0-7, 128-135 or off> A number from 0..7 selects the J5.Ax input to which a Sustain Pedal is connected. A number of 128..135 selects the AINSER8 located Ax input. Use off if no Pedal is used to avoid that the unconnected analog input will send random MIDI events!
Examples:
set kb 1 ain_sustain 2: Sustain Pedal of keyboard 1 connected to J5.A2 of the core module
set kb 2 ain_sustain 5: Sustain Pedal of keyboard 2 connected to J5.A5 of the core module
set kb 1 ain_sustain 130: Sustain Pedal of keyboard 1 connected to A2 of an AINSER8 module
set kb 2 ain_sustain 133: Sustain Pedal of keyboard 2 connected to A5 of an AINSER8 module
set kb 1 ain_sustain off: no Sustain Pedal connected
set kb <1|2>
ain_sustain_inverted
<on|off>		 Inverts the output of the Sustain Pedal.
Examples:
set kb 1 ain_sustain_inverted off: (default) Pedal outputs 0..127
set kb 1 ain_sustain_inverted on: Pedal outputs 127..0
set kb <1|2>
ain_sustain_switch
<on|off>		 Changes the Sustain Pedal behaviour:
Examples:
set kb 1 ain_sustain_switch off: (default) the pedal will output continuous controllers like a pot. set kb 1 ain_sustain_switch on: the pedal will only send 0 or 127 like a switch.
set kb <1|2> ctrl_sustain <0-129> What kind of MIDI events should be sent by the Sustain Pedal?
  • 0..127: CC#0 .. CC#127 (default: CC#64)
  • 128: PitchBend
  • 129: Aftertouch
Examples:
set kb 1 ctrl_sustain 64: the Sustain Pedal of keyboard 1 sends CC#64 (CC Sustain)
set kb 2 ctrl_sustain 65: the Sustain Pedal of keyboard 2 sends CC#65 (CC Portamento On)
set kb <1|2> ain_expression <0-7, 128-135 or off> A number from 0..7 selects the J5.Ax input to which the Expression pedal is connected. A number of 128..135 selects the AINSER8 located Ax input. Use off if no Expression pedal is used to avoid that the unconnected analog input will send random MIDI events!
Examples:
set kb 1 ain_expression 6: Expression pedal of keyboard 1 connected to J5.A6 of the core module
set kb 2 ain_expression 7: Expression pedal of keyboard 2 connected to J5.A7 of the core module
set kb 1 ain_expression 134: Expression pedal of keyboard 1 connected to A6 of an AINSER8 module
set kb 2 ain_expression 135: Expression pedal of keyboard 2 connected to A7 of an AINSER8 module
set kb 1 ain_expression off: no Expression connected
set kb <1|2>
ain_expression_inverted
<on|off>		 Inverts the output of the Expression pedal.
Examples:
set kb 1 ain_expression_inverted off: (default) Expression outputs 0..127
set kb 1 ain_expression_inverted on: Expression outputs 127..0
set kb <1|2> ctrl_expression <0-129> What kind of MIDI events should be sent by the Expression pedal?
  • 0..127: CC#0 .. CC#127 (default: CC#1)
  • 128: PitchBend
  • 129: Aftertouch
Examples:
set kb 1 ctrl_expression 1: the Expression pedal of keyboard 1 sends CC#1 (CC Modulation)
set kb 2 ctrl_expression 7: the Expression pedal of keyboard 2 sends CC#7 (CC Volume)
set kb <1|2>
ain_bandwidth_ms <delay>		 Allows to reduce the bandwidth for analog events. With 0 the default (very high) bandwidth will be used, which can send multiple MIDI events per milliseconds over USB. If this stresses your DAW too much, use higher values. E.g. with set kb 1 ain_bandwidth_ms 5 MIDI events will only be sent each 5 mS (on value changes).
set kb <1|2> calibration <off|pitchwheel|modwheel|expression|sustain> Starts the calibration of PitchWheel/ModWheel/Expression/Sustain potentiometers (or switches) to determine the minimum/maximum value.
After the calibration, just enter 'set kb 1 calibration off' to stop the calibration (and to test the behaviour), thereafter type 'store' to save the new values.

Recommended Configurations

Configuration examples for various keyboards - this list will be enhanced whenever new configurations have been tested:

Fatar DF Type with 61 keys (schematic)
  • set kb 1 note_offset 36
  • set kb 1 rows 8
  • set kb 1 velocity on
  • set kb 1 optimized on
  • set kb 1 dout_sr1 1
  • set kb 1 dout_sr2 2
  • set kb 1 din_sr1 1
  • set kb 1 din_sr2 2
  • set kb 1 din_key_offset 32
  • set kb 1 din_inverted off
  • set kb 1 break_inverted off
  • set kb 1 delay_fastest 50
  • set kb 1 delay_slowest 1000
  • store
Fatar DF Type with 76 keys (schematic)
  • set kb 1 note_offset 28
  • set kb 1 rows 12
  • set kb 1 velocity on
  • set kb 1 optimized on
  • set kb 1 dout_sr1 1
  • set kb 1 dout_sr2 2
  • set kb 1 din_sr1 1
  • set kb 1 din_sr2 2
  • set kb 1 din_key_offset 32
  • set kb 1 din_inverted off
  • set kb 1 break_inverted off
  • set kb 1 delay_fastest 50
  • set kb 1 delay_slowest 1000
  • store
Fatar DF Type with 88 keys (schematic)
  • set kb 1 note_offset 21
  • set kb 1 rows 12
  • set kb 1 velocity on
  • set kb 1 optimized on
  • set kb 1 dout_sr1 1
  • set kb 1 dout_sr2 2
  • set kb 1 din_sr1 1
  • set kb 1 din_sr2 2
  • set kb 1 din_key_offset 40
  • set kb 1 din_inverted off
  • set kb 1 break_inverted off
  • set kb 1 delay_fastest 50
  • set kb 1 delay_slowest 1000
  • store
Two "Refurbished Organ" keyboards with 63 keys (schematic)
  • set srio_num 4
  • set kb 1 note_offset 36
  • set kb 1 rows 8
  • set kb 1 velocity on
  • set kb 1 optimized off
  • set kb 1 dout_sr1 1
  • set kb 1 dout_sr2 2
  • set kb 1 din_sr1 1
  • set kb 1 din_sr2 2
  • set kb 1 din_key_offset 32
  • set kb 1 din_inverted off
  • set kb 1 break_inverted on
  • set kb 1 delay_fastest 50
  • set kb 1 delay_slowest 1000
  • set kb 2 note_offset 36
  • set kb 2 rows 8
  • set kb 2 velocity on
  • set kb 2 optimized off
  • set kb 2 dout_sr1 3
  • set kb 2 dout_sr2 4
  • set kb 2 din_sr1 3
  • set kb 2 din_sr2 4
  • set kb 2 din_key_offset 32
  • set kb 2 din_inverted off
  • set kb 2 break_inverted on
  • set kb 2 delay_fastest 50
  • set kb 2 delay_slowest 1000
  • store
Adding a Pitch Wheel to J5.A0
and a Modulation Wheel to J5.A1
and a Sustain Pedal to J5.A2
(no schematic yet)
  • set kb 1 ain_pitchwheel 0
  • set kb 1 ctrl_pitchwheel 128
  • set kb 1 ain_modwheel 1
  • set kb 1 ctrl_modwheel 1
  • set kb 1 ain_sustain 2
  • set kb 1 ctrl_sustain 64
  • set kb 1 ain_expression 6
  • set kb 1 ctrl_expression 11
  • store
Use following commands to calibrate the potentiometers (resp. switches):
  • set kb 1 calibration pitchwheel
    -> move the PitchWheel to min/max position
  • set kb 1 calibration modwheel
    -> move the PitchWheel to min/max position
  • set kb 1 calibration expression
    -> move the Expression Pedal to min/max position
  • set kb 1 calibration sustain
    -> turn on/off the Sustain Pedal
  • set kb 1 calibration off
  • store

Wishlist

  • support for triple sensor keyboards (allow to measure the key release velocity) - needs somebody who owns such a keyboard and can help testing

Firmware Download

The precompiled application can be downloaded from the MIOS32 Download page.


Last update: 2023-11-04

Copyright © 1998-2023, Thorsten Klose. All rights reserved.