The TextBlade uses BLE (Bluetooth Low Energy) to communicate with host systems. BLE was introduced as part of the Bluetooth 4.0 specification so systems running earlier versions of Bluetooth are not capable of running in BLE mode and thus cannot be used with the TextBlade. Most modern phones, tablets and laptop PC/Mac systems will have the appropriate hardware built-in and for such systems the TextBlade can be used without the need for additional hardware.

Hardware with built-in Bluetooth support that operates in BLE mode started becoming the norm during 2011, but you need to check the specification of your hardware to check. At the OS level this is only the case for the most recent versions of most common OS. For PCs the OS support for BLE is built-in on systems running Windows 8 or later (although there are drivers for Windows 7). On Macs OS support for BLE is built-in if using OSX Mavericks or later.

For systems that do not have Bluetooth 4.0 support built-in at the hardware level then a Bluetooth dongle plugged in via USB is the way to add such support. If purchasing a dongle for use with the TextBlade ensure that it supports Bluetooth BLE mode. This means that the dongle must support at least Bluetooth 4.0 or later.

A Bluetooth dongle can operate in two modes:

WayTools make a Bluetooth dongle suitable for use with the TextBlade available as an optional accessory.

The dongle supplied to early TREG testers (image above) was actually a Laird 820 dongle (as discussed later in this section) pre-paired to a slot on the TextBlade. Later TREG testers got a version of the dongle with Waytools branding applied as the Way-In dongle rather than it having the Laird branding (although under the covers it is identical to the Laird 820). When supplied by WayTools in conjunction with a TextBlade then the dongle arrives with the following customisations already done for you:

• It is already paired with the TextBlade on Jump Slot 6. You therefore should not attempt to pair anything else to Jump Slot 6 unless you are prepared to lose the pre-supplied pairing between the dongle and your new TextBlade.
• It is already set into HID mode. This means the dongle can be plugged into any system that can accept a USB keyboard and the TextBlade will immediately start working with that system at long as the TextBlade is using Jump Slot 6. There is no need do any Bluetooth setup on the system the dongle has been plugged into. You will find that the dongle will start flashing its blue LED to show it is active the moment you plug it in (even if the TextBlade does not have the dongle Jump Slot set as the active one).

The only further customisation you might normally need to do is to set the correct Key Map, Target OS and Target Keyboard for your intended use of Jump Slot 6. This is done with the TextBlade connected to the device running the TextBlade app (on the Jump slot appropriate to that device which will not be Jump Slot 6) from the Jumps section of the app.

In normal use when using a WayTools supplied dongle the remainder of this section can be ignored. It does, however, become relevant if:

• You need to reset the pairing between the dongle and the TextBlade. This could be because the original pairing was lost for some reason, or because you want to move the pairing to use a different Jump Slot. If you need to do this then you start by Resetting the dongle to HCI mode and then follow the procedure for setting a dongle up from scratch.
• You want to do something advanced with the dongle as discussed at the end of this section.

In the ideal world such a Bluetooth dongle could be combined with the NanoCharger so that it can be held inside the TextBlade when not in use. However such a product would definitely not be something that is likely to be available for initial release of the TextBlade to the general public (assuming it ever appears at all). It is also not clear if such a product (if it existed) would be able to receive Bluetooth signals reliably enough in such a small form factor.

The setup when a dongle is being used but the host is going to run the Bluetooth stack is exactly the same as when using built-in Bluetooth hardware. It is expected that this is the method that many users will use rather than the more complicated one of getting the Dongle to run the Bluetooth stack (which is the focus of the sections after this one).

Points to note are:

• You need to be running a version of the host OS that has built-in support for Bluetooth LE.
• Any dongle that claims to support the Bluetooth Low energy protocol should be usable in this mode.
• If you have built-in Bluetooth hardware that supports an older version of the Bluetooth protocol then you will probably need to disable the built-in hardware so that the dongle can be used successfully. The method of doing this should be detailed in the documentation for your host.

The detailed steps of the process of connecting a Bluetooth keyboard to such a system is going to be specific to the Operating System that is being used, so you should refer to the OS documentation for more information.

For an old Mac, the procedure that appears to work is:

• Turn off Bluetooth
• Install the dongle
• Download and I install Hardware_IO_Tools_for_Xcode from Apple (you need a free Developer account to be able to do this).
• Run the Bluetooth File Explorer and select the Tools→HCI Controller Selector and switch to the dongle (as opposed to the built-in hardware).
• Turn on Bluetooth again.

That should it and you will now be able to pair the TextBlade to the Mac.

Some users have also reported success by omitting the steps that use the Bluetooth File Explorer, but exactly under what conditions this is possible is not clear. Any feedback from users who can clarify this would be appreciated as obviously removing the need for getting the additional software from Apple is highly desirable.

GMYLE BT V4.0 Dual Mode Procedure on Older Mac Running 10.11.6:

• Open Bluetooth Control Panel.
• Make sure Bluetooth is ON.
• Turn off all other Bluetooth devices, since the Mac can not connect via the GMYLE if the builtin bluetooth is in use. You will need to pair all devices thru the GMYLE to use the dongle.
• Plug in Dongle.
• Select an empty jump slot on the TextBlade as indicated by landing lights animation.
• The TextBlade should appear in the Devices pane.
• Select this device to pair. A window will appear with a pairing code.
• Type the code on the TextBlade.

This is the only way to get a TextBlade to work with a system that is not capable of supporting Bluetooth natively. It allows the TextBlade to be used with any system that is capable of supporting a USB keyboard. This would cover:

• Older versions of standard operating systems that do not have Bluetooth support built-in.
• Systems where you need to be able to use a keyboard before Bluetooth is available (e.g. during the Boot process).
• Systems where for some reason you are not able to configure the Bluetooth even when the system is technically capable of supporting it.

From trial-and-error experiments by early TextBlade users it appears that the hardware requirements for dongles to be capable of operating in HID proxy mode are:

• It must use the Cambridge Silicon Radio (CSR) 8510 chipset
• It must have at least 64K of flash memory internally. Many of the cheaper dongles based on the CSR8510 chipset and advertising themselves as BLE compatible do not appear to meet this requirement.

It is quite possible that dongles based on other chipsets may be capable of this mode as well, but so far none have been found.

Dongles that have been found to meet the above requirements and have been successfully used in HID mode with TextBlades are:

• Laird 820 (European and US versions). It is suspected that Laird dongles in the 900 series may also work, but so far no user has reported back on this.

The steps to getting a compatible dongle working in HID Proxy mode with a TextBlade have proved to be a little convoluted and thus prone to error. A Texblade-dongler project has been started on GitHub to try and automate this as far as possible and to act as a repository for information needed to get this working. This work has resulted in a process that seems to work reasonably reliably for most early users (although still not for the faint-of-heart).

The following approaches to doing these steps have so far been validated:

• Windows only approach. This only works for certain versions of Windows as documented on the Laird Site
• Virtual Machine based approach for those running Windows, MacOS, or Linux (on PC type hardware).
• Raspberry Pi based approach (or possibly other Single Board Computer) systems that are becoming commonly available as they are so cheap and are being widely promoted for use by children to learn about computers. The Raspberry Pi Zero which has a list price of only £4 for the base system might be attractive for this for those who do not already have a Raspberry Pi and want a cheap starting point.

Virtual Machine Approach

• Install VirtualBox
  If you do not already have it installed then download and install the VirtualBox software which is available (free) for Windows, OSX or Linux. You also need to install the Extension pack to give you required support for USB devices.
• Get the NixOS VM.
  A NixOS VM (a light-weight version of Linux) as been prepared that has the relevant Bluetooth support built in. The VM runs under VirtualBox.
• Import the VM into VirtualBox.
  To do this one starts VirtualBox and then uses the File→Import Appliance option
• Adjust the VM settings.
  The settings you will probably want to change are:
  • Network settings so that the first network slot is selected to act a 'bridged' network
  • USB settings. You want to add a filter that automatically connects the dongle to the VM when it is started. If the dongle is already plugged into the host system running VirtualBox then it will be shown in the list of available devices when you press the '+' button to create a new filter'. It is also possible to connect the dongle to the VM after it has been started by right-clicking on the USB icon (the third from the left) at the bottom of the VM window.
  • Shared Folders. This provides an easy way to get files in/out of the VM. The shared folder will appear in the VM under the /media location. This is not critical to using the VM but is very convenient.
• Start the VM. This starts up the VM and then automatically logs you in as the 'root' user. At this point very basic instructions on how to proceed are displayed.

  * Plug in the CSR dongle
  * Switch your TB on a free jump slot
  * Disconnect the KeyBlades, connect only one KeyBlade to the SpaceBlade
  * Run pair.sh
  * Run the make-hid.sh command it outputs.  Make sure that is your TextBlade.

  In the ideal world that is all that is required although experience has shown that it is not always as smooth as that so more detail is given below.

Raspberry Pi Approach

It has been found that the Raspberry Pi Single Board Computer (SBC) can also be used to configure the dongle. It is possible that other SBC systems that are Linux based may work but the Raspberry Pi is the only one tested so far. The steps to get a Raspberry Pi ready to run the dongle setup process are:

• Boot Raspberry Pi into Raspbian
  Set up the Raspberry Pi (RPi) to run the Raspbian operating system (a Debian release optimized for the Raspberry Pi) and boot the system into Raspbian.
• Make sure you have a working internet connection
  It does not matter whether this is a wired or WiFi connection. * If you are running the GUI, then open up a terminal window so you can enter CLI (Command Level Interface) commands.
• Make sure required software installed
  Run the following commands to install the supporting software
  

  sudo apt-get update
  sudo apt-get upgrade
  sudo apt-get install libusb-1.0-0-dev
  sudo apt-get install bc

• Update the bluez version
  The default Bluez version needs to be updated. These instructions are sourced from https://scribles.net/updating-bluez-on-raspberry-pi-5-43-to-5-48/
  

  sudo apt-get install libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev -y
  wget www.kernel.org/pub/linux/bluetooth/bluez-5.48.tar.xz
  tar xvf bluez-5.48.tar.xz && cd bluez-5.48
  ./configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc --localstatedir=/var --enable-experimental
  make -j4
  sudo make install

• Reboot and verify the version of bluez
  

  sudo reboot
  bluetoothctl -v

  The results should look like this:
  

  $ bluetoothctl -v
  bluetoothctl: 5.48

• Get the dongler project software
  Create a directory to hold the dongle related files and then change to it

  mkdir dongler
  cd dongler

  Get the required files from the GitHub dongler project
  

  wget https://raw.githubusercontent.com/wmertens/textblade-dongler/master/src/hid2hci.c
  wget https://raw.githubusercontent.com/wmertens/textblade-dongler/master/src/pair.sh
  wget https://raw.githubusercontent.com/wmertens/textblade-dongler/master/src/make-hid.sh

• Install dongler software
  Build the hid2hci binary
  

  gcc -o hid2hci -lusb-1.0 hid2hci.c

  Copy the dongler software to somewhere on the search path for the root user

  chmod +x pair.sh make-hid.sh
  sudo cp pair.sh make-hid.sh hid2hci /usr/local/sbin

• Get into root mode
  The commands required at the CLI level to configure the dongle require you to have root privileges. If you run

  sudo bash

  you are now in a shell with root privileges and are in a position to run the same commands that can be used from the VM.

• Check that your dongle is visible
  

  lsusb

  The results should look something like this

  lsusb
  Bus 001 Device 004: ID 0a12:100b Cambridge Silicon Radio, Ltd 
  Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter
  Bus 001 Device 002: ID 0424:9514 Standard Microsystems Corp. SMC9514 Hub
  Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

COMMON STEPS

You are now in a position to start configuring the dongle

• Check dongle can be seen.
  With the dongle plugged in you use the lsusb command to show what USB devices are connected to the VM. If using a VM then normally this would just be the USB bluetooth dongle that you are intending to work with so the output would look something like

    lsusb
    Bus 001 Device 002: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)
    Bus 001 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
    

  If using a Raspberry Pi then any other connected USB devices will also be listed. The important points about the above output are first that you can see the dongle in the VM in the first place, and secondly the field ID: 0a12:0001 that is the ID for the dongle. If your dongle has a different ID then it will be necessary to amend the pair.sh script (held at /run/current-system/sw/bin/pair.sh) to have the ID of your dongle in the part near the top where it is waiting for the dongle to be seen.

• Select a Jump slot on the TextBlade.
  Select on the TextBlade the jump slot that you intend to use in conjunction with this dongle. Be sure to only select one jump slot prior to the next step, and do not select a different jump slot while pairing as doing so may create complications. If you have previously had the Jump slot you want to use paired with a different device then it is a good idea to have that device either switched off or out-of-range to avoid it pre-emptively grabbing the TextBlade Jump slot.

• Erase any existing pairing.
  Remove any existing pairing for the slot. To do this you hold down the jump chord for 10 seconds. You will see the LED's show the jump display, and then flash the slot location progressively faster, until the whole display flashes on and the off after 10 seconds and finally all the LEDs switch off. At this point any existing pairing for that slot has been erased and the TextBlade is ready to accept a new pairing. The existing name that shows up at the Bluetooth level for that device will have been incremented to a new unique name of the form TextBlade n-mm where n is the Jump Slot number and last two mm characters have changed from their previous value (typically increments by one).

• Prepare the TextBlade for pairing without a PIN
  If running firmware 8098 or later then you are normally required to enter a PIN on the TextBlade as part of the pairing process. The VM approach requires the dongle to accept pairing without a PIN being entered. To put the dongle into a mode where a PIN is not required for pairing you need to do the following steps.
  • Detach the KeyBlades from the SpaceBlade. Allow the LED shutdown sequence to complete.
  • Attach only one KeyBlade. Normally this is the blade that contains the chord for the required Jump Slot but this is not mandatory.
  • The TextBlade will now boot up ready to accept a PINless pairing.

• Run the pairing script
  Run the pair.sh script.

  pair.sh

  If you are using the latest scripts and there are multiple HCI devices (such as on a Raspberry Pi 3) you will see output something like this:

  Devices:
          hci[1]:  00:16:A4:0F:4B:10
          hci[0]:  B8:27:EB:F8:50:8E
  There are multiple HCI devices.
  Which HCI device do you want to use?

  You enter the number of the hci device that corresponds to your dongle. On the Raspberry Pi this would typically be 1. If using PIN based pairing you will see something like:

  btctl> [TextBlade 2-28
  [agent] Passkey: 346820
  -- waiting for Paired:

  At this point you would enter this PIN on the TextBlade to pair the device.
  If using PINless pairing this should automatically find and pair itself to the TextBlade. If this step completes successfully then typing characters on the TextBlade will result in them appearing in the VM. At the end of the pair.sh script you are given the chance to automatically run the next step, but you may want to pause and check things out before doing so. If you choose to pause and check things out, be sure to note the address for your TextBlade (e.g., B8:F5:E7:50:43:2E) since you'll need it for the next step.

• Verify keys are present
  Before running the make-hid.sh script in the next step, you should verify that your dongle has all of the needed keys present. If not, you will need to add these prior to the next step. This seems to be necessary for some Laird 820 dongles purchased in the United States.
  First read the keys by running

  bccmd psread > pair.txt

  Compare the contents of the file to this file: European Laird 820 psread output. If all of the keys are there (they may have different values), then you should be ready to move on to the next step. Some users with U.S. sourced Laird 820 dongles have needed to write the keys contained in the to-apply file. Move the file somewhere where you will have access to it on the VM and then type:

  bccmd psload -s 0 to-apply.txt

  You can do the psread command again to ensure that the additional keys are now stored on your dongle. If so, you're ready to move to the next step.

• Run the script to put dongle into HID mode.
  Run

  make-hid.sh <TextBlade address> {<HCI device>}

  where <TextBlade address> is the address of the TextBlade jump slot that you paired with (and is typically of the form B8:F5:E7:50:43:2E) and the optional {<HCI device>} is the HCI device if other than hci0. This is the step that puts the dongle into the all-important HID mode. It also stores the pairing keys within the flash of the Dongle so that the dongle remains paired with the selected Jump slot on the TextBlade going forward.

• Start the dongle in HID mode.
  It should now be possible to power-cycle the dongle (i.e. unplug it and then plug it back in) and it should be in HID mode.
  
  Note that if you unplug it and then plug it right back in, it will act as a USB keyboard for your computer (not the VM that you've just been working in) as the 'product id' field will have changed at the USB level so it will not automatically be picked up by the VM.

Assuming the above has all worked successfully then you should be able to plug the dongle into any system capable of supporting USB keyboards and find that it will work with the TextBlade if you select the Jump Slot that you paired with the dongle. If the dongle selected has a LED that indicates it is active in Bluetooth mode you will find that the mere act of plugging it into a system (and thus powering it) will start that LED flashing.

The following video is a walkthrough of the above steps, pairing a WayTools supplied (Laird 820) dongle with slot 6 on a TextBlade using VirtualBox.

Once you are have paired the dongle and are ready to configure the dongle there are some useful commands that can be used at the CLI level to check out the dongle.

This command provides basic Bluetooth control. Once started you will stay in the bluetoothctl program until you enter the quit option. A list of sub-commands available is available by typing

help

once bluetoothctl has been started. This will give output of the form

Available commands:
  list                       List available controllers
  show [ctrl]                Controller information
  select <ctrl>              Select default controller
  devices                    List available devices
  paired-devices             List paired devices
  power <on/off>             Set controller power
  pairable <on/off>          Set controller pairable mode
  discoverable <on/off>      Set controller discoverable mode
  agent <on/off/capability>  Enable/disable agent with given capability
  default-agent              Set agent as the default one
  set-scan-filter-uuids [uuid1 uuid2 ...] Set scan filter uuids
  set-scan-filter-rssi [rssi] Set scan filter rssi, and clears pathloss
  set-scan-filter-pathloss [pathloss] Set scan filter pathloss, and clears rssi
  set-scan-filter-transport [transport] Set scan filter transport
  set-scan-filter-clear      Clears discovery filter.
  scan <on/off>              Scan for devices
  info [dev]                 Device information
  pair [dev]                 Pair with device
  trust [dev]                Trust device
  untrust [dev]              Untrust device
  block [dev]                Block device
  unblock [dev]              Unblock device
  remove <dev>               Remove device
  connect <dev>              Connect device
  disconnect [dev]           Disconnect device
  list-attributes [dev]      List attributes
  select-attribute <attribute> Select attribute
  attribute-info [attribute] Select attribute
  read                       Read attribute value
  write <data=[xx xx ...]>   Write attribute value
  notify <on/off>            Notify attribute value
  register-profile <UUID ...> Register profile to connect
  unregister-profile         Unregister profile
  version                    Display version
  quit                       Quit program

The command sequence that is most likely to be required is

poweron
quit

to get the dongle ready to respond to bccmd commands.

If you are using the bluetoothctl command to pair the TextBlade (rather than using the pair.sh script mentioned above) then the sequence of commands will be something along the lines of:

poweron

to make sure the dongle is activated. Then with the dongle waiting to be paired run

scan on

to find the 'id' of the TextBlade. A list of devices seen by the dongle will be listed.

pair XXXXX

To pair the TextBlade with the dongle (where XXXXX is the id obtained from the scan command).

paired-devices

to check that the pairing has been successful.

quit

to exit from the bluetoothctl command and get back to the command line. At this point you can manually run

make-hid.sh XXXXX

to get the dongle into HID mode.

This is used to provide finer grain control of the dongle. It takes additional parameters to specify the action to be performed.

bccmd help

can be used to get a list of the options with available for use with the bccmd command

bccmd - Utility for the CSR BCCMD interface

Usage:
	bccmd [options] <command>

  Options:
	-t <transport>     Select the transport
	-d <device>        Select the device
	-b <bcsp rate>     Select the bcsp transfer rate
	-h, --help         Display help

  Transports:
	HCI USB BCSP H4 3WIRE

  Commands:
	builddef                       	Get build definitions
	keylen     <handle>            	Get current crypt key length
	clock                          	Get local Bluetooth clock
	rand                           	Get random number
	chiprev                        	Get chip revision
	buildname                      	Get the full build name
	panicarg                       	Get panic code argument
	faultarg                       	Get fault code argument
	coldreset                      	Perform cold reset
	warmreset                      	Perform warm reset
	disabletx                      	Disable TX on the device
	enabletx                       	Enable TX on the device
	singlechan <channel>           	Lock radio on specific channel
	hoppingon                      	Revert to channel hopping
	rttxdata1  <freq> <level>      	TXData1 radio test
	radiotest  <freq> <level> <id> 	Run radio tests
	memtypes                       	Get memory types
	psget      <key>               	Get value for PS key
	psset      <key> <value>       	Set value for PS key
	psclr      <key>               	Clear value for PS key
	pslist                         	List all PS keys
	psread                         	Read all PS keys
	psload     <file>              	Load all PS keys from PSR file
	pscheck    <file>              	Check PSR file
	adc        <mux>               	Read ADC value of <mux> input

  Keys:
	bdaddr country devclass keymin keymax features commands version 
	remver hciextn mapsco baudrate hostintf anafreq anaftrim usbvid 
	usbpid dfupid bootmode 

The one that is most likely to be used is

bccmd psread

can be used to get a list of the current keys that are stored in the flash. Getting the initial list of keys that this returns can be useful in determining if a particular dongle is likely to successfully work in HID Proxy mode.

An example of what this returns is European Laird 820 psread output in its out-of-the-box state.

If you need to change the device that is paired to the dongle, then you are first going to have to reset it into HCI mode before this can be done. The would also be required if you accidentally erased the Jump slot that is paired to the dongle so that you can restart the process described above for getting the TextBlade to work with the dongle.

To do this you start by using the

hid2hci     (or csr-hid2hci if used from within VM)

program.

hid2hci puts the dongle into HCI mode until the dongle is reset (power-cycled). This allows you to use it as a normal bluetooth radio temporarily, or to change configuration such as the paired keyboard. If you need the dongle to stay in HCI mode after resetting it (essentially, restoring it to factory configuration), run

bccmd psset -s 0 0x3cd 0

which will disable HID mode until make-hid.sh is run again.

There a number of more complicated scenarios that have been identified for using the dongle:

• Pairing a Mouse to the dongle in addition to the TextBlade. The dongle supports two devices being simultaneously paired but the details of how the process needs amending to do this are still to be laid out. Mice that support Bluetooth BLE mode are not yet commonly available so this has not yet been tried.
• Pairing two TextBlades to the same dongle. This is just a variant of the previous point where the second device is another TextBlade rather than a mouse.
• Pairing two Jump Slots on the same TextBlade to the dongle. Since each Jump Slot on a TextBlade looks like a separate keyboard as far as the hosts are concerned this is merely a variant on the previous point. The reason for doing this would be because you want different settings on the Jump Slots (e.g. One with a QWERTY layout and one with a Colemak layout).
• Pairing the two different dongles to the same TextBlade Jump Slot. An example of when this might be useful is a care where you want to leave dongles plugged in at home at work and only move the TextBlade itself between the sites. This is the most esoteric of the options listed and may well prove not to be feasible. The same results could be obtained by using the previous point at the expense of using an additional Jump Slot.

Although it is believed that all the scenarios are possible they have not yet been validated and a robust procedure identified for implementing any of them.