NOTE: If you plan on using the TWI keyboard with the Arduino IDE or with avr-gcc, there is a ready-made library available. See here for details.

The TWI Keyboard and LED controller defines a simple TWI protocol for easy interfacing. Connect SDA and SCL to the corresponding SDA and SCL pins on your microcontroller. The TWI protocol requires pull-up resistors, 4.7k or 10k are usually good values, but for short cable runs it is usually sufficient to use the microcontroller's built-in pull-up resistors if available.

The keyboard works as a TWI slave. The default slave address is 16. Writing bytes to the slave address activates the keyboard.

Bytes with values between 0x80 and 0xff (that is, all 8-bit values with MSB 1) are reserved for commands. Any undefined command (inclding everything between 0x00 and 0x79) is defined as a nop and has no effect.

Command set

All bytes from 0x80 to 0xff are reserved for commands. Some commands are followed by additional data in the form of one of more bytes. For such commands, be sure to send all expected bytes, otherwise the keyboard will be stuck in an invalid state.

0x81 (slave addr): Change slave address. Send this command followed by a new TWI slave address. The valid address range is 0-127 (7-bits). If an invalid address is sent, it will be ignored.

After changing the address, it is neccesary to toggle power to the device: Once the address has been successfully changed, the keyboard will only respond by its new address.

To reset the device to its default address of 16, hold button 1, 2 and 5.

0x82: Clear all LEDs (turning them OFF)

0x83 (led id, brightness): Set LED brigthness. This command is followed by the id of the LED (numbered from 0 to 5) and then the desired brightness between 0 (off) and 100 (full brightness). The brightness change is instantaneous.

Led id must be between 0 and 5, otherwise the command is treated as a nop (no effect). Any brightness value greater than 100 is treated as 100 (full brightness).

0x84 (led id, pulse on/off): Set LED to pulse. This command is followed by the id of the LED (numbered from 0 to 5) and then 1 to set pulsing on or 0 to set pulsing off.

Led id must be between 0 and 5, otherwise the command is treated as a nop (no effect)

0x85 (led id, brigthness): Fade the value of the LED from the current value to a new value. This command is followed by the id of the LED (numbered from 0 to 5) and then the desired brightness between 0 (off) and 255 (full brightness). The brightness change will be gradual.

Led id must be between 0 and 5, otherwise the command is treated as a nop (no effect) Any brightness value greater than 100 is treated as 100 (full brightness).

--add example--

0x90: Get key up event
0x91: Get key down event

Returns a byte with the key up and key down state of each button respectively, each packed into one bit, with button 1 as MSB and button 7 as LSB.

When the key state is read, the internal state of the key is reset. This means that the user pressing and releasing a single key will result in one key down and one key up event only. If key repeat is set (see command 0x92), the key down event is re-triggered while the key is held down.

0x92 (key id, key repeat): Set key repeat. Send the command followed by key id (numbered from 0 to 7) and then the key repeat mode.

The following key repeat modes are available:

• 0: none
• 1: slow
• 2: medium slow
• 3: medium
• 4: medium fast
• 5: fast

For key repeat modes between 1 (slow) and 5 (fast) the key down event is re-triggered at a time interval. For key repeat set to 0, only one key down and one key up event is sent.

Key id must be between 0 and 7, key repeat must be between 0 and 5. If any other value is sent, the entire command is treated as a nop and will have no effect.

Default is 0 (none) for all keys.

0xFE: Reset0xFF: Flush the bus

When initializing the keyboard, send four 0xFF followed by 0xFE to reset the keyboard to a known state. Failure to to this may result in key up and key down events getting mixed up.