Bluetooth Keyboard

About

MagiScript can turn a compatible device like the Atom into a Bluetooth keyboard. This enables the device to send keystrokes to a phone or computer that has been paired with it.

To use the keyboard and media support in MagiScript, you need to pair your device with the target phone or computer. Once the pairing process is complete, you can use the available functions to send keystrokes or media commands to the target device.

When Atom is paired with a phone, it automatically connects to Atom when turned on. You can still connect to Atom via Bluetooth from the same host device to develop mini-apps or use Atom. You can even pair another device, but this can start being unreliable. If you experience that you cannot connect to Atom again, or your device cannot pair with it, go to your Bluetooth settings to unpair Atom, and connect to it again.

Keyboard Type

The keyboard.type() function allows you to type a string of characters on the target device. The function takes a string as its argument, and it types each character of the string sequentially. For example, if you want to type the string “Hello, world!”, you can use the following code:

				
					keyboard.type('Hello, world!'); // prints "Hello, world!"

You can use multiple values, and even numbers. Atom will add a space between them:

				
					keyboard.type('Hello', 'World'); // prints "Hello World"
keyboard.type('Temperature:', 42); // prints "Temperature: 42"

Keyboard Tap

The keyboard.tap() function allows you to tap a specific key on the target device.

From firmware v2.3.1, we introduced a new, easy way to press keys or key combinations. This function takes a string or more as its arguments, representing the key or key combination you would like to press. Keys can be combined with Control, Shift, Alt, AltGr, Cmd and Win keys.

For example:

				
					keyboard.tap('return');
keyboard.tap('cmd-space');
keyboard.tap('Cmd+Space');
keyboard.tap('Ctrl-Alt-Del');
keyboard.tap('Ctrl-C', 'Ctrl-V');

You can use these modifiers, even combined:

ctrl control alt altgr option shift cmd command win windows

And these keys:

enter return esc backspace bs tab space sp minus - equal = leftbrace ( rightbrace ) backslash \ hashtilde tilde ~ semicolon ; apostrophe ' grave comma , dot . slash / capslock
f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 f13 f14 f15 f16 f17 f18 f19 f20 f21 f22 f23 f24
sysrq scrolllock pause insert home pageup delete del end pagedown right left down up numlock kpslash kpasterisk kpminus kpplus kpenter
kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 kp0 102nd compose power kpequal kpcomma kpleftparen kprightparen
open help props front stop again undo cut copy paste find mute volumeup volumedown
ro katakanahiragana yen henkan muhenkan kpjpcomma hangeul hanja katakana hiragana zenkakuhankaku
playpause play pause stop previous next eject volumeup volumedown mute www back forward stop2 find scrollup scrolldown edit sleep coffee refresh calc

DEPRECATED

There’s also a deprecated way to send simple key presses, by passing a keyCode as its argument, which represents the key that you want to tap. The available keyCodes are listed below:

- KBD_UP

- KBD_DOWN

- KBD_LEFT

- KBD_RIGHT

- KBD_PAGE_UP

- KBD_PAGE_DOWN

- KBD_HOME

- KBD_END

- KBD_BACKSPACE

- KBD_TAB

- KBD_RETURN

- KBD_ESC

- KBD_INSERT

- KBD_PRTSC

- KBD_DELETE

- KBD_CAPS_LOCK

- KBD_F1

- KBD_F2

- KBD_F3

- KBD_F4

- KBD_F5

- KBD_F6

- KBD_F7

- KBD_F8

- KBD_F9

- KBD_F10

- KBD_F11

- KBD_F12

For example, if you want to tap the “Enter” key, you can use the following code:

				
					keyboard.tap(KBD_RETURN);

Also, multiple keys can be listed:

				
					keyboard.tap(KBD_UP, KBD_END);

Media Key Tap

The media.tap() function allows you to send media commands to the target device. The function takes a mediaKeyCode as its argument, which represents the media command that you want to send. The available mediaKeyCodes are listed below:

- MEDIA_PLAY_PAUSE

- MEDIA_NEXT_TRACK

- MEDIA_PREVIOUS_TRACK

- MEDIA_STOP

- MEDIA_VOLUME_UP

- MEDIA_VOLUME_DOWN

- MEDIA_MUTE

For example, if you want to play or pause media playback on the target device, you can use the following code:

				
					media.tap(MEDIA_PLAY_PAUSE);

Keyboard Send

The keyboard.send() command serves as the foundation for all other keyboard-related functions. For instance, the Custom Keyboard built-in application utilizes this command to transmit key presses. This allows users to configure the function and media keys in the settings (as strings).

When you pass a simple string, it will act as keyboard.type(). You can use keywords, it will act as a keyboard tap or media key tap.

There are two special keywords, their behaviour can be configure in the settings:

- #SEPARATOR

- #SUBMIT (usually an ENTER)

And the available keywords are:

- #UP

- #DOWN

- #LEFT

- #RIGHT

- #PAGE_UP

- #PAGE_DOWN

- #HOME

- #END

- #BACKSPACE /
  #DEL /
  #DELETE

- #TAB

- #ENTER /
  #RETURN

- #INS /
  #INSERT

- #PRTSC

- #CAPS_LOCK

- #F1

- #F2

- #F3

- #F4

- #F5

- #F6

- #F7

- #F8

- #F9

- #F10

- #F11

- #F12

- #PLAY /
  #PAUSE /
  #PLAY_PAUSE

- #NEXT

- #PREV /
  #PREVIOUS

- #STOP

- #MUTE

- #VOL_UP /
  #VOLUME_UP

- #VOL_DOWN /
  #VOLUME_DOWN

For example:

				
					keyboard.send('Hello', '#SEPARATOR', 'World', '#ENTER', '#PLAY');

Note

It’s important to note that not all devices support all keyCodes and mediaKeyCodes. Also, some devices may have additional keyCodes or mediaKeyCodes not listed here.

Conclusion

MagiScript provides a simple and convenient way to turn a compatible device into a Bluetooth keyboard and send keystrokes or media commands to a target device. With the available functions, developers can create various applications that require keyboard or media input.