If in doubt, ask.
Back to the main user manual
This page describes the current firmware version, which is 1.7

Configuration

Introduction

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.

Tutorial

For a very readable overview of configuring the FH-1, please see this tutorial by Learning Modular.

Configuration tools

Some web-based tools are available to assist in creating scripts, and in transferring them to/from the FH-1. At present these are:

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.

Whitespace

(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

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.

CC2-4:1:5

means remap CCs 2 to 4 (inclusive) to CCs 5 to 7.

A more extensive example is here. This results in the CC assignments shown here.

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>

or

MCV<converter number>:

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 converters

Converter 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

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.

Polyphonic converters

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

MCV16:16:0-127:PS1:C0G1:C2G3:C4G5:C6G7

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.

Raw MIDI

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:

HEXb00040
which 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 40
You can use as many HEX commands as you like.

Reset

The 'RST' command anywhere in a script resets the FH-1's state (exactly equivalent to resetting via menu H/1).

Note-to-CC remaps

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:127
maps 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.

Device-specific scripts

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

Installing scripts

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.

Alternatively, a Python script for converting the FH-1 script to a Hex file is here. Note that this depends on the intelhex package, which you will need to install first. The usage is

python script2hex.py <your script file.txt>

Installation via SysEx

Scripts may also be installed via MIDI System Exclusive. See the SysEx page, and also the tools above.

Debugging

If there is a problem parsing the script, the FH-1 will flash LEDs C & D alternately for a short while at startup.