| Label | Description |
|---|---|
| A | Keyboard connection, USB Type-A port. |
| B | PC connection, micro-USB port. |
| C | BOOTSEL/RESET button. |
| D | Operation LED |
This is the simplest mode of connection and your keyboard should just work by plugging it into the USB-A female port (the bigger USB port) of the device labelled A in the diagram. You will need a USB-A to Lightning cable.
The micro-USB connection labelled B must be connected to one of your PC's USB ports.
Connecting any of these keyboards is pretty straightforward.
-
Remove any keyboard currently plugged-in to magicstick.io.
-
Turn the keyboard off and then on again.
-
Plug the magicstick.io device to a USB port and keep it close to the keyboard. magicstick.io should discover the keyboard and pair with it. There is no PIN code entry required.
Connecting the Older A1314 Keyboard
The older A1314 keyboard has a little bit more complicated pairing process.
Important: Make sure that the magicstick.io device is first reset to factory settings, so that it holds no previous paired keyboard data in its internal memory, by following these steps.
- Remove any keyboard currently plugged-in to magicstick.io.
- Turn the A1314 keyboard off by constantly pressing the right side button for a few seconds. You will see the green keyboard led powering off in a fading out fashion.
- Turn the A1314 keyboard on by constantly pressing the right side button for a few seconds. Keep pressing it until the green led starts flashing. The keyboard is now in discovery mode.
- (Unplug if plugged-in and) plug-in again your magicstick.io device to a PC USB port. magicstick.io will try to discover the keyboard. When the magicstick.io LED starts flashing non-stop, the keyboard is discovered and pairing has started. Immediately type 0000 (that is, four zeros) on the keyboard and press Enter.
- The keyboard should be now paired and connected. If this process fails repeat from step 1.
The magicstick-ui utility allows you to monitor the keyboard's connection status, monitor the battery level (both when wired or in Bluetooth), as well as to change the keyboard's special keys configuration and default keymap. You can also use it for permanently turning the magicstick.io Bluetooth chip on or off, for instance if you are in a very high IT security work environment.
To download the magicstick-ui utility, check the release notes page.
The LED is located at the diagram position marked D. The following table summarizes the various LED flashing states of the device:
| LED Status | Meaning |
|---|---|
| LED is on. | A keyboard is connected via wired or Bluetooth connection. |
| LED is off. | Device malfunction. |
| LED is flashing non-stop. | Bluetooth has initiated pairing mode. Depending on the keyboard model you may need to enter 0000 and press Enter on the keyboard to complete pairing or just wait, see Connecting a Keyboard for details. |
| 1 flash and a pause. | IDLE. magicstick.io is operational but no keyboard is connected via wire connection or Bluetooth. |
| 2 flashes and a pause. | Bluetooth CONNECTING. magicstick.io Bluetooth is trying to connect to an already paired keyboard via Bluetooth. |
| 3 flashes and a pause. | Bluetooth INQUIRING. magicstick.io Bluetooth is in inquiry (aka discovery) mode trying to discover and pair with a suitable keyboard nearby. |
When you connect your keyboard for the first time, this is the default keymap:
| Input Key(s) | Output Key |
|---|---|
| Left Ctrl | Fn |
| Fn | Left Ctrl |
| ⏏︎ Eject or 🔒 Lock | Del |
| ⌘ Cmd | Alt |
| ⌥ Alt/Option | Cmd |
| Fn + [F1] | Brightness Down |
| Fn + [F2] | Brightness Up |
| Fn + [F6] | Sleep (Windows OS) |
| Fn + [F7] ... [F12] | Multimedia Keys |
| Fn + Return | Insert |
| Fn + ⌫ | Del |
| Fn + P | Print Screen |
| Fn + S | Scroll Lock |
| Fn + B | Pause/Break |
| Fn + ↑ | Page Up |
| Fn + ↓ | Page Down |
| Fn + ← | Home |
| Fn + → | End |
This can be easily done in Settings by selecting:
This is swapped by default but can be reverted in Settings as seen above.
Note: This is an advanced feature and is mostly suited to people with a bit of programming background. If you do not feel that you have programming skills you may have difficulty in getting things right or you may even render the device slow and unresponsive if done something terribly wrong. If that happens there is always the reset option.
Expand.
The magicstick.io keymap is programmable via custom rules. This allows you to:
- Remap physical keys.
- Remap keys to target most of the HID Keyboard scan codes as per USB HID Usage Tables specification 1.12, under the Keyboard/Keypad and Consumer Pages, totalling 200+ keys and functions.
- Program keys for typing extended ASCII characters, Unicode characters and emojis.
To access the default keymap, right-click the utility icon and select Keymap to open the editor.
You will then see the keymap rules editor showing the current default rules:
A keymap rule can be one of the following 3:
-
label [label name]
-
goto [label name]
-
[expression] : [goto label if expression evaluates to true] : [goto label if expression evaluates to false]
or
[expression] : [goto label if expression evaluates to true]
or
[expression]
(1) A label rule defines a place/anchor in the program. The label name can be a word consisting of alphanumeric characters and underscores but starting with an underscore or a letter. E.g. lbl_1, _lbl1, lastlbl, etc.
(2) A goto rule tells the rules engine to jump to a particular label location in the list, by label name.
(3) An expression rule, executes and evaluates the result of an expression. If the expression result is true (i.e. any number except 0) it jumps to the rules list location specified by [goto label if expression evaluates to true]. If the result is false (equals 0), it jumps to the rules list location specified by [goto label if expression evaluates to false]. The goto sections are optional and if they are missing, execution will just continue with the next rule in the list until the end of the list.
Below is a further explanation of the default rules:
magicstick.io supports the remapping of a physical key via keymap rules. For instance, for swapping the blue and red circled keys,
the default keymap already includes the following 2 rules using the ch_key function:
ch_key(HID_KEY_EUROPE_2, HID_KEY_GRAVE):end
ch_key(HID_KEY_GRAVE, HID_KEY_EUROPE_2):end
You can remove these two rules if you would prefer to not swap these keys.
To delete all the remapped keys one-off, you can:
- Click the Load Default button in the keymap editor to load the default keymap. Or
- Reset the device to factory settings by following these steps.
We saw in a previous section that you can use the magicstick-ui utility for that. As an alternative, you can also code the relevant rules in the keymap editor. This will give you more fine-grained control, such as the ability to swap only the Left or only the Right Alt-Cmd keys, etc.
Rule to swap left ⌥ Alt/Option with left ⌘ Cmd:
(mod & KEYBOARD_MODIFIER_LEFTALT != 0) ^ (mod & KEYBOARD_MODIFIER_LEFTGUI != 0) && set_mod(mod ^ (KEYBOARD_MODIFIER_LEFTALT | KEYBOARD_MODIFIER_LEFTGUI))
You can add a similar rule to swap the KEYBOARD_MODIFIER_RIGHTALT and KEYBOARD_MODIFIER_RIGHTGUI keys if required.
Emulating these keys can be useful for entering Alt-codes under Windows, that require the use of a numeric keypad, which the Apple Magic keyboard does not have.
The following set of rules shows how to map the Fn + 0 - 9 key combinations to: Numeric Keypad keys 0 - 9:
Click to expand/collapse.
ch_key(HID_KEY_1, HID_KEY_KEYPAD_1):end
ch_key(HID_KEY_2, HID_KEY_KEYPAD_2):end
ch_key(HID_KEY_3, HID_KEY_KEYPAD_3):end
ch_key(HID_KEY_4, HID_KEY_KEYPAD_4):end
ch_key(HID_KEY_5, HID_KEY_KEYPAD_5):end
ch_key(HID_KEY_6, HID_KEY_KEYPAD_6):end
ch_key(HID_KEY_7, HID_KEY_KEYPAD_7):end
ch_key(HID_KEY_8, HID_KEY_KEYPAD_8):end
ch_key(HID_KEY_9, HID_KEY_KEYPAD_9):end
ch_key(HID_KEY_0, HID_KEY_KEYPAD_0):end
These rules must be entered after the "label lbl_fn_on" line and before the "goto end" line, so that they are taken into consideration when Fn is pressed.
Note: This functionality only works on Windows OS and requires the magicstick-ui utility to be running in the tray. Also please note that the program that you are typing in to must have Unicode support (e.g. Windows WordPad or Microsoft Word).
For entering Unicode characters, you need to know the hexadecimal Unicode point value of the character. You can use these tables for this.
The following example shows how to program the key shortcut Fn + 2 to type the € character:
find_key(HID_KEY_2) && send_unicode(0x20AC):end
The following example shows how to program the key shortcut Fn + 3 to type the £ character:
find_key(HID_KEY_3) && send_unicode(0x20A4):end
You will need to add both of the above rules after the "label lbl_fn_on" line and before the "goto end" line so that they are activated when Fn is pressed, as seen in lines 23-24:
You can also type Emojis, for example say that you would like to map Fn + Y to 👍 and Fn + N to 👎. This can be done like so:
find_key(HID_KEY_Y) && send_unicode(0x1F44D):end
find_key(HID_KEY_N) && send_unicode(0x1F44E):end
For a more complex example, assuming that would allow you to map:
Fn + 
to the Unicode character ≠
and
Fn + Shift + to the Unicode character ±
You'll need these rules:
!mod && find_key(HID_KEY_EQUAL) && send_unicode(0x2260):end
(mod & KEYBOARD_MODIFIER_LEFTSHIFT) && find_key(HID_KEY_EQUAL) && send_unicode(0xB1):end
Note how we also need to consult the mod keystroke modifiers (flags) variable value to check whether the Shift key is pressed or not.
This example shows how to map a single keystroke to multiple sequential keystrokes. We will map Fn + H to send 2 sequential keystrokes for typing the word "hi". This can be coded like so:
find_key(HID_KEY_H) && (send_key(0, HID_KEY_H), send_key(0, HID_KEY_I)):end
Or as another example, we will map Fn + X to send the 2 emojis: 👍👎. This can be coded like so:
find_key(HID_KEY_Y) && (send_unicode(0x1F44D), send_unicode(0x1F44E)):end
-
Download the latest (or the desired) uf2 firmware file and associated magicstick-ui utility exe file from the release notes page. The firmware file should be something like that: magicstick.x.x.x+release.xxxxxxx.uf2.
-
Enter magicstick.io to BOOTSEL mode.
-
Once magicstick.io is in BOOTSEL mode, a new File Explorer window will open in your desktop, titled: RPI-RP2. If this window does n't open automatically, you can still open it manually in File Explorer:
-
Copy the downloaded uf2 firmware file there. Once the copy completes, your magicstick.io device will automatically restart, running the new firmware.
-
If desired, you can now also run the downloaded magicstick-ui.exe UI utility (from step 1) to control the device.
BOOTSEL is a special device mode that allows you to write new firmware to it. You should only need to do this to run a manual firmware update or downgrade.
To enter into BOOTSEL mode, unplug magicstick.io and then plug it in while the bootsel button is constantly pressed. This will enter the magicstick.io into bootsel mode.
You can reset your device's internal memory (programmed keys, Bluetooth pairing etc.) by following these steps:
Unplug the device. Plug it in and as soon as the green LED turns on (it is important to wait until it turns on before you press), press the BOOTSEL button and keep pressing it until the LED starts flashing. Now release the BOOTSEL button. The device's memory will be wiped out and the device will reboot.
It is important to press the BOOTSEL button after the LED turns on. If you press it before, the device will enter into BOOTSEL mode instead of resetting, which is not what you want in this case.
As soon as the device resets back to factory settings, it will lose all key remapping information, special keys configuration, as well as any Bluetooth pairing information if it was previously paired with a Bluetooth keyboard. Therefore it will immediately enter into Bluetooth discovery mode again, trying to find a suitable keyboard to pair with.