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:
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:
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:
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:
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:
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:
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 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:
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:
Virtual Machine Approach
/media
location. This is not critical to using the VM but is very convenient.* 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:
sudo apt-get update sudo apt-get upgrade sudo apt-get install libusb-1.0-0-dev sudo apt-get install bc
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
sudo reboot bluetoothctl -v
The results should look like this:
$ bluetoothctl -v bluetoothctl: 5.48
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
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
root
moderoot
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.
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
bluez
software installed as standard with Raspbian can have problems handling the TextBlade and is typically not the latest version available. You can upgrade to a later release by following the bluez update instructions provided by Adafruit. The :rpi-bluez-install.zip attached script provides an automated way of carrying out all those steps (it defaults to 5.50 but a different release can be provided as a parameter). Releases between the bluez 5.37
and bluez 5.50
releases are ones that have been tested successfully against the TextBlade.COMMON STEPS
You are now in a position to start configuring the dongle
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 likelsusb 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.
ID: 0a12:100b
and the Description field no longer mentions HCI mode.
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.
pair.sh
script then it is also possible to do the pairing manually while running the bluetoothctl
command (see later for details on this command). Many TREG users seem to have preferred using bluetoothctl
as it gives them a finer-grained control of the process.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.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.
bccmd -d <HCI device>
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.
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:
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.