This brief page describes the new commands added to support Controller functionality.
All of the remapping, layer, select and macro commands of the Converter config are also supported.
A matrix is a grid of switches arranged in rows and columns.
To make clear which is driven by the controller and which is read, I mainly use the terms strobe and sense instead.
Depending on the matrix (and the orientation of the diodes, if it has them) you might strobe the rows and sense the columns, or you might strobe the columns and sense the rows.
Lock LEDs can be connected to any pin, and the polarity of each pin can be individually configured.
led <lock> [-]<pin>
Example:
led caps PD3 # for when the other end of the LED/resistor combination is 0V
led num -PD4 # for when the other end of the LED/resistor combination is +5V
led scroll -PD5
Syntax:
matrix
[scanrate <milliseconds>]
[debounce <scans>]
[debounce_method <method_num>]
[blocking <flag>]
[strobe_mode <mode>]
[sense_delay <microseconds>]
[sense_polarity <polarity>]
[muxstrobe_port <port_pin_range>]
[muxstrobe_enable [-]<pin>]
[muxstrobe_gate [-]<pin>]
[sense <pin> ...]
[muxstrobe <number> <hid> ...]
...
[strobe <pin> <hid> ...]
...
[unstrobed [-]<pin> <hid>]
...
end
All options have default values, so often hardly any need to be used.
The sense, muxstrobe, strobe
and unstrobed options, when used, must be given in that order!
Full example for my mini keyboard, which has 8 rows and 8 columns, and diodes fitted to each switch:
matrix
blocking 0
sense PB0 PB1 PB2 PB3 PD0 PD1 PD2 PD3
strobe PF0 ESC 2 4 5 7 9 MINUS LCTRL
strobe PF1 1 3 UNASSIGNED 6 8 0 BACKSPACE LGUI
strobe PF4 TAB W R T U O LEFT_BRACE LALT
strobe PF5 Q E BACKSPACE Y I P RIGHT_BRACE UNASSIGNED
strobe PF6 CAPS_LOCK S F G J L ENTER RALT
strobe PF7 A D SPACE H K SEMICOLON UNASSIGNED MENU
strobe PB6 LSHIFT Z C V N COMMA FN2 RCTRL
strobe PB7 FN1 X UNASSIGNED B M PERIOD RSHIFT UNASSIGNED
end
Scan rate is set in milliseconds, in other words it's actually the interval between scans.
The default is 1ms, giving a scan rate of 1000Hz.
Valid values are from 1 to 8, allowing scan rates between 1000Hz and 125Hz.
There's little reason to change this unless scanning is unreliable, or you need to extend the debounce time.
Debounce time is set as a number of scans. Multiply by the scan interval to get a debounce time in milliseconds.
The default is 5, which, along with the default scan rate, would give a debounce time of 5ms.
Valid values are from 1 to 7.
To get a higher debounce time than 7ms, the scan interval should be increased.
Two debounce methods are supported, both of which debounce each key individually.
Method 0 is a standard debounce, to handle both noisy switch contacts and electro-magnetic interference (EMI).
Method 1 is a turbo debounce, which adds no lag to your inputs unlike the standard debounce. It does not handle EMI.
Specify whether to activate the ghost key blocking function, which is required when the matrix does not have diodes
(or equivalent such as capacitive sensing).
Valid values are 0 (off) and 1 (on).
The default is on.
Various strobe modes can be selected, although it will be quite unusual to need anything other than the default, which is 0.
WARNING: exercise caution when using modes 1 or 5, since errors in the connections or lack of diodes can easily damage the Teensy!
| Mode | Active | Inactive |
|---|---|---|
| 0 | low | pullup |
| 1 | low | high |
| 2 | low | float |
| 3 | float | high |
| 4 | pullup | low |
| 5 | high | low |
| 6 | float | low |
| 7 | high | float |
A delay of at least 1 microsecond (µs) is inserted between setting a strobe and reading the senses,
to allow the signals across the matrix to settle.
Valid values are from 1 to 64 µs.
The default is 1 µs.
This setting should normally match the strobe mode, with 0 being used for strobe_modes 0 to 3, and 1 being used for strobe_modes 4 to 7.
Valid values are 0 (active low) or 1 (active high).
The default is 0.
For multiplexed strobes, muxstrobe_port defines the port and range of pins used to select the strobe.
Currently this is restricted to a contiguous set of pins on a single port.
Example:
muxstrobe_port PF7:4
External decoding logic may require an enable signal. This option assign a pin to that function.
The pin will be made active before scanning muxstrobes and inactive after - i.e. it remains active for the entire scan of all muxstrobes.
If the pin name is preceded with '-', the signal will be active low.
Example:
muxstrobe_enable -PD4
External decoding logic may require a gate signal. This option assign a pin to that function.
The pin will be made active and then inactive for each muxstrobe.
If the pin name is preceded with '-', the signal will be active low.
Example:
muxstrobe_gate -PD3
Specifies a list of pins to read every time the matrix is strobed by either strobe or muxstrobe.
Example:
sense PB3 PB7 PD0 PD1 PD2 PD3 PC6 PC7
Specifies a pin to strobe, and the HID codes corresponding to each sense pin.
If fewer HID codes are given than there are sense lines, the remainder are assumed to be UNASSIGNED.
Example:
strobe PF0 ESC 2 4 5 7 9 MINUS LCTRL
As strobe, except that instead of a pin to strobe, this specifies a code to send to the external decoding logic.
Example:
muxstrobe 7 ESC 2 4 5 7 9 MINUS LCTRL
Specifies a single pin to read and the corresponding HID code.
This is intended for a single switch which can be wired with the other side of the switch permanently connected to either ground or +5V.
If the other side of the switch is at +5V, a pull-down resistor must be added between the pin and ground.
Example:
unstrobed -PF1 LSHIFT