If you have a Bluefruit v1.1 or later, you can wirelessly re-map the keys, no need to use a console cable (altho the console cable technique will still work). Original v1.0 Bluefruits can only be remapped over serial console

The default buttons->keypresses will be satisfactory for most projects. However, you may want to customize those keys so when a GPIO pin is pulled to ground, a different keystroke is sent. It isn't that difficult to do! However, you will need an FTDI Friend or USB console cable to connect the EZ-Key to your computer.

If using an FTDI friend, connect the TX pin of the EZ-Key to the RX pin on your FTDI friend and the RX pin to the TX pin (receiver goes to transmit). Also be sure to power the EZ-Key. You do not have to pair it for this remapping

You will have to put the EZ-Key into re-mapping mode. To do this, the pair-button must be pressed while the module is powered up. The easiest way to do this is to disconnect the red Vin wire from the console cable, press down on the button, then plug in the red wire, that's it!
As a 'safety' procedure, every time you power the module with the re-pair button pressed (to enter remapping mode) it will reload the default keymap. This is so if you somehow really mess things up, you can always get back to the default keymap without a console cable

Load Processing Sketch

We wrote the re-mapping software in Processing. Processing is cross-platform and easy to install. Please download Processing v1.5.1 since that's known to work

You'll also need to download and install the ControlP5 library

Then click below to download the remap software

Uncompress and open the remapper.pde in Processing. Plug in the USB console cable or FTDI adapter. Select Sketch->Run menu item and look in the debug window below, you should see Found Serial Ports: and then a list of ports. On Windows, it will be something like COM1, COM2, COM3 etc. On Mac/Linux it will be something like /dev/USBtty or /dev/cu.usbserial

Copy and paste the list into a notepad, now File->Run it again, this time with the USB console cable unplugged. The list should be one line shorter. In this case COM3 is missing. That means that the cable name is COM3
in the line
myPort = new Serial(this, "COM3", 9600);
Change "COM3" to whatever the cable name is. Again, for Mac or Linux it will probably be /dev/cu.something

Replug in the FTDI/Console cable.

Select File->Run again to start the script with the correct /dev or COM port

Now disconnect the red wire that is powering the EZ-Key, press and hold the Pair button on the module and reconnect the red wire. You should see:

Adafruit Bluefruit HID 9/18/2013

Remap ready!

Appear in the bottom half of the screen. Now click that large gray square window to remap
You should see


Set Mapping:128

Indicating that the mapping was sent.

Customizing Keys

OK now you want to actually change the key report. Each of the 12 keys has a report. This is an example for #0:


There are 8 'arguments' to each report:

The first one is the GPIO#, in this case its #0.

Second is the modifier keys, such as Shift, Control, Alt, etc. See hid_keys.pde for a list of the modifier available. You can 'or' the modifiers. For example, if you want to press shift and control modifiers at the same time, use MODIFIER_SHIFT_LEFT | MODIFIER_CONTROL_LEFT

The last 6 are the 6 slots available for concurrent keys. You can have up to 6 key-codes sent at once (handy for when you want to send complex key reports. Check hid_keys.pde for the list of all the keycodes!

This guide was first published on Sep 27, 2013. It was last updated on Sep 22, 2016.

This page (Remapping the Buttons (Serial)) was last updated on Sep 27, 2013.

Text editor powered by tinymce.