This repository holds tools to encode and decode Texas Instrument BTS files (.bts) to/from an intermediate JSON format.

BTS files are (proprietary) script files used to initialize Texas Instrument (TI) Bluetooth modules. Each script contains a sequence of commands to setup the Bluetooth module. It is loaded by the host system on every boot. They may also contain binary patches to the firmware running on the radio module.

Some commands are executed on the host (e.g setup baudrate), some are sent as HCI commands to the Bluetooth module.

NOTE: Altering the BTS may invalidate hardware certification. You must NEVER use inofficial BTS files in production hardware.

Official BTS files are provided by radio module manufacturers, or by TI:

https://github.com/TI-ECS/bt-firmware

This tool was primarily develop to be able to tweak minor settings inside a BTS without having to reach out to a 3rd party (TI or other radio module vendor) to have them send a new BTS file.

BTS files contain a small header and one or more action blocks. This script is capable of encoding/decoding the following action blocks:

• Remarks
• Serial settings (baudrate & flowcontrol)
• Delays
• Run script
• Wait event
• Send command

For the "Send command" action, the script will also try to determine the command using an internal database. The internal database is by no means complete and covers mostly WiLink >= 8 commands.

NOTE: btstool requires Python 3.x and will not work with Python 2.7.x.

Install using PIP:

1. Obtain PIP (may vary on your Linux distribution):

   apt-get install python-pip

2. Install btstools and all dependencies:

   pip install .

If you wish to remove btstools, issue the following PIP command:

pip uninstall bts

Decode a BTS into a readable JSON file:

$ btsdump.py my.bts > my.json

Encode a JSON (same format as output by btsdump.py) into a BTS file:

$ btsgen.py my.json > my.bts

With these tools, you can tweak existing BTS files by decoding into JSON, modifying the contents and re-encode to BTS.

If you wish to inspect the HCI commands sent by the BTS, you can dump the commands from the BTS into a format (btsnoop) readable by Wireshark.

$ hcidump.py my.bts > my.dat

.. and open it using Wireshark. Any "Send command" will be displayed as a HCI message sent from the Host to the Controller. Any "Wait data"-event (HCI data expected to be received) will be displayed as a HCI message sent from the Controller to the Host.

To view a diff between two JSON files:

$ btsdump.py orig.bts > orig.json
$ btsdump.py modified.bts > modified.json
$ btsdiff.py orig.json modified.json

It has the option to ignore remarks, which can be convenient when trying to figure out what a new version of a BTS entails.

Self-test btstools:

$ btstest my.bts

The self-test will translate the given bts into JSON and then back to BTS and compare it to the original input. If they differ, there's probably a bug in the btstools.