The FH-1's response to MIDI can be customised via scripts, which are installed from a USB flash drive in the same manner as updating the firmware. They can also be installed via MIDI System Exlusive.
Note that this is not intended as the primary means of integrating the FH-1 with your setup. It is generally much easier to configure your MIDI controller to send the MIDI that the FH-1 expects, rather than reconfiguring the FH-1 to respond to the controller's default MIDI output.
The scripts serve two purposes:
- To remap MIDI CCs.
- To configure the MIDI/CV converters.
CC remap is conceptually simple - for a given incoming MIDI channel and CC number, map that onto the FH-1's preprogrammed CC assignment. Configuration of the MIDI/CV converters is much more flexible, allowing creation of MIDI/CV modes not supported in the standard FH-1 configuration.
The script stored in the FH-1 is invoked whenever a USB device is attached. If the script contains a RST (reset) command, this allows for resetting the FH-1 by detaching and reattaching the USB device. In combination with the DEV command, this allows for having the FH-1 change behaviour when one USB device is detached and a different one attached.
For a very readable overview of configuring the FH-1, please see this tutorial by Learning Modular.
Some web-based tools are available to assist in creating scripts, and in transferring them to/from the FH-1. At present these are:
- GUI-based script generation tool - allows you to create and edit scripts entirely in a GUI, without actually typing anything.
- SysEx-based script installation tool - allows you to transfer scripts to/from the FH-1 over SysEx from the browser, and also to create a SysEx file from a script which can later be installed via another SysEx tool.
- Script-to-Hex converter - creates Hex files which can be used to install scripts via a USB flash drive.
Note that if you need/want to download local copies of these tools, you also need to download this script file on which they depend (just put it in the same local folder on your drive).
The script file
An FH-1 script is a simple text file. For example
FH-1 script v1 RC3 CC2:1:5
All scripts start with the line 'FH-1 script v1'. Subsequent lines are commands which are executed in order, and which are described below.
The script should end in a blank line - the last command should always have a carriage return after it.
(From firmware v1.4) All whitespace (i.e. spaces & tabs) in scripts is ignored. You can freely insert whitespace to aid readability. Note though that the total size of a script is limited, so for very long scripts you may need to watch how compact your script is.
Remapping CCs is done via two commands, 'RC' and 'CC'.
'RC' simply sets the incoming MIDI channel for subsequent 'CC' commands. RC is followed by the MIDI channel number 1-16. In the example above, 'RC3' indicates MIDI channel 3.
'CC' sets up the remap. The syntax is
CC<CC number or range>:<destination MIDI channel>:<destination CC range start>so in the example above 'CC2:1:5' means remap CC 2 (on MIDI channel 3, as set up by the RC command) to CC 5 on MIDI channel 1.
The CC number can be a single number or a range. Ranges are specified with a dash e.g.
means remap CCs 2 to 4 (inclusive) to CCs 5 to 7.
Note that to remap the 14 bit CCs (0-31), two CC commands are required, to map the high and low CCs in pairs.
Configuring MIDI/CV converters
By way of an example, here is the default script which is run at startup to configure the base functionality described in the user manual. Any user script is run after this one, and can redefine or disable the default converters.
FH-1 script v1 MCV1:1:0-127:C0G1 MCV2:2:0-127:C2G3 MCV3:3:0-127:C4G5 MCV4:4:0-127:C6G7 MCV5:5:0-127:C0G1V2 MCV6:6:0-127:C4G5V3 MCV7:7:0-127:C6G7V8 MCV8:8:0-127:C10G11V9 MCV9:9:0-127:C0G1V2A3 MCV10:10:0-127:C4G5V6A7 MCV11:11:0-127:C8G9V10A11 MCV12:12:64-95:-TA MCV13:13:0-127:-GN MCV14:14:0-127:-GV MCV15:15:0-127:PA6G7:C0G1V4:C2G3V5 MCV16:16:0-127:P:C0G1:C2G3:C4G5:C6G7
As you can see, there is one command, 'MCV'. The syntax is
MCV<converter number>:<MIDI channel>:<note range>:<converter details>
The 'converter number' identifies the converter. There are 16 converters available, so this number can be in the range 1-16.
If the second form of the command is used (nothing following the converter number), the converter is disabled. E.g. 'MCV1:' by itself disables MIDI/CV converter number 1.
'MIDI channel' is in the range 1-16.
The 'note range' is the range of MIDI note numbers to which this converter will respond. '0-127' responds to all notes on the channel.
The 'converter details' section of the command takes a number of forms, as follows.
Special case convertersConverter details starting with '-' are special cases, and are not configurable except to select them on a particular channel.
- -TA : triggers with accents
- -GN : gates/triggers without velocity
- -GV : gates/triggers with velocity
Monophonic converters have up to 4 outputs, which can be any combination of CV (C), gate (G), velocity (V), release velocity (R), trigger (T) and aftertouch (A). The details string is a list of the required outputs, each followed by the FH-1 output number. So e.g. 'C0G1' means CV on output 0 and gate on output 1.
The output numbers range from 0 to 63. 0 to 7 are the FH-1's own outputs; 8-15 are the outputs on expander 1, and so on.
In addition an 'I' (capital letter I) can be included in the details string, which causes the gate to be inverted.
If aftertouch is specified with a lower case 'a' (rather than the usual 'A'), this enables the Gated Aftertouch feature.
If the converter details start with a 'P', this indicates a polyphonic converter.
The 'P' can optionally be followed by an 'A/output' (for aftertouch) and/or a 'G/output' (for paraphonic gate i.e. a gate that is high when at least one of the voice gates is high). An example is in the script above for MCV15.
'P' can additionally be followed by 'S/option' to set the voice allocation scheme. For example
is the same as default MIDI/CV converter 16 but with voice allocation scheme 1. The available schemes are:
- 0 : round robin (default)
- 1 : lowest voice
- 2 : unison
Next comes a section for each voice, in the same format as the monophonic converters. Each voice can have CV (C), gate (G), velocity (V), release velocity (R) and trigger (T). Note that each voice does not need to have the same selection of outputs.
The polyphony of the converter is defined implicitly by the number of voices specified. The maximum polyphony is 16.
A script may contain raw MIDI messages, which are processed by the FH-1 exactly as if they'd arrived on its USB port. This provides an alternative setup method to storing presets.
MIDI is specified with the 'HEX' command, which is simply followed by a list of bytes in hexadecimal format. Whitespace between bytes is not required, but aids readability. You may also freely use commas to separate bytes. Upper or lower case letters may be used.
For example, to set the level of the FH-1's first output to halfway the command would be:
HEXb00040which breaks down as CC change on channel 1, CC number 0, value 64. As another example, to set up a sine LFO on output 1 you could use
HEX b4 40 7f, b2 00 40, b0 00 40You can use as many HEX commands as you like.
The 'RST' command anywhere in a script resets the FH-1's state (exactly equivalent to resetting via menu H/1).
The FH-1 has the ability to map incoming note on/offs to CC messages. This is useful for example if your MIDI controller has pads which can only transmit notes, but you want them to control something for which the FH-1 uses CCs.
The syntax is
NC<type>:<note MIDI channel>:<note number>:<CC MIDI channel>:<CC number>:<off value>:<on value>For example
NCC1:48:2:6:0:127maps note 48 on MIDI channel 1 to control CC 6 on MIDI channel 2, with values of 0 (note off) and 127 (note on).
The available types are
- C (i.e. NCC) - the note on/off state controls the CC directly. Note on will set the CC to the on value; note off will set the CC to the off value.
- T (i.e. NCT) - note on toggles the CC value between the off and on values. Note offs are ignored.
The 'DEV' command allows for scripts whose behaviour depends on the attached USB device. When the script encounters a DEV command, the device name in the command is compared with that of the currently connected device. If the two don't match, the following script commands are ignored, until the next DEV command.
Consider this example:
FH-1 script v1 RC9 CC74:1:4 DEV:nanoKEY2 RST DEV:Launch Control XL HEX b4 64 40 b2 44 3d b0 04 60 HEX b4 65 40 b2 45 3f b0 05 60
The remapping of channel 9 CC 74 always applies. If a nanoKEY2 is connected, then the RST command runs. If a Launch Control XL is connected, then the two HEX commands run.
Note that the device name in the DEV command is the one place where whitespace matters. E.g. a Launch Control XL will not match "DEV:LaunchControlXL" (no spaces) or "DEV:Launch Control XL" (double space).
The 'FORCE' command allows you to instruct the FH-1 to always assume a certain device is connected. This is useful for example if you want to use device specific behaviours but your FH-1 is connected indirectly to the device (e.g. through an iConnectivity interface). The usage is e.g.
FORCE:Launch Control XL
There are two methods for installing scripts:
Installation from USB flash drive
The process for installing scripts is exactly the same as that for updating the firmware, that is, the script is converted to a file called 'image.hex', which is put on a USB flash drive and written to the FH-1's flash by the bootloader.
A web-based tool for converting scripts to Hex is here.
python script2hex.py <your script file.txt>
Installation via SysEx
If there is a problem parsing the script, the FH-1 will flash LEDs C & D alternately for a short while at startup.