Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

BTIL

The BREW Tools Interface Layer (BTIL, pronounced "beetle") is a packet-based layered transport used by BREW 3.x and newer versions to communicate with tools.

Unlike its predecessor, Diag , BTIL is not tied to Qualcomm (AMSS) devices, and is extensible at runtime. BTIL can run over a variety of reliable and unreliable transports.

BTILExtension communicates with BTILServer (both on the PC side) by sending UDP packets to the address localhost for IPC.

Some security applications may block all incoming UDP incoming packets, even those sent to Localhost. To work around this issue, add BTIL applications to the exclusion list: BTILServer.exe, BTILLogServer.exe and Loader.exe. If your firewall is blocking UDP incoming packets, do the following to enable Loader or Logger to connect to a device over COM/BTIL.

  1. Within your firewall application (Example: Sophos Endpoint), add the following applications to the exclusion list for network access/permissions. Certain IT security configurations are too strict and affect UDP based IPC communication for Brew MP tools.
    1. BTILServer.exe LOCATION: %BREWMP_TOOLSET%\bin\deprecated\BTIL\Host\bin
    2. BTILLogServer.exe LOCATION: %BREWMP_TOOLSET%\bin\deprecated\BTIL\Host\bin
    3. Loader.exe LOCATION: %BREWMP_TOOLSET%\bin
    4. Logger.exe LOCATION: %BREWMP_TOOLSET%\bin

Device support

BTIL works on compliant BREW 3.x devices, however for most 3.x and 4.x devices it is not loaded on by default. On some devices, the AMSS does not support FEATURE_BTIL, requiring that a special module, called cnxnfix, be loaded on. Some 3.x and 4.x devices have broken BREW implementations preventing BTIL running. As no major carrier requires BTIL to be working, it is often untested on these platforms.

On Brew MP devices, BTIL is preinstalled and tested. Note that BTIL is typically installed in the const filesystem and will not show up in diag-based tools (i.e. Loader using "QCOMOEM.dll" or EFS Explorer).

Connection types supported

BTIL 1.x versions can be connected to legacy BREW Simulators, devices on their modem port, Bluetooth devices, and OTA connections using UDP.

BTIL 2.x (Brew MP) can be connected to all of the above connection types as well as Brew MP Simulators, diag ports (both with and without QPST installed). BTIL 2.x devices can also "piggyback" on the OS Services Gateway to establish connections over any mechanism that the Gateway supports.

Developer enablement

All versions of BTIL require that the user authorize themselves to the system. This is done by providing BTIL with a test signature before connecting with BTIL's BTIL_InitDevice() API. BTIL requires that a signature, named after the hardware ID (ESN, IMEI, or MEID) of the device be named appropriately and placed in one of two Test Signature Repositories.

  1. The legacy location at is used by all versions of BTIL
  2. The BMP (BTIL 2.0.x+) version at <%ALLUSERSPROFILE%\BTIL\sigs>

Brew MP versions of Connect have automated this process in Loader, Logger, and Test Studio. You should establish your first connection to a device using one of those tools to enable the device.

BTIL shipped with Brew MP Platforms version 1.0.2 and newer uses the provided signature to authorize the connection and install it as the Developer Enable Signature. After establishing a BTIL connection, a user on Brew MP platform version 1.0.2 or newer should be able to copy modules onto the phone without a signature.

Clients and hosts

The BTIL Host is the software that runs on a PC. This software is split into two parts. The first part is a set of DLLs that are loaded into the address space of a given tool, and handle the majority of the BTIL protocol. These DLLs include BTILExtension.dll, SYSTEMExtension.dll, and FILEExtension.dll. Loading these DLLs is dependent on either the BTIL directory being in the tool's path at runtime, or having that tool include and use the Locator Header, BTILFinder.h

The BTIL Client is the software that runs on the device. With the exception of a small (~1K) piece of code that OEMs must pre-integrate into their devices, the BTIL Client is comprised of entirely dynamic modules. Those modules are btilmain, btilsec, and btilcs. Btilmain and btilsec must be present for all versions of BTIL on all devices. Btilcs is required only for Brew MP devices with Brew MP versions of BTIL (2.x.x).

The BTIL Client is usually not present on BREW 3.x and 4.x devices. To aid in its installation, the BTIL Client Installer is provided. The installer uses the diag protocol to load BTIL. The Client Installer should only be used on BREW 3.x and 4.x devices, as Brew MP devices already have BTIL installed. The BTIL Client Installer (BCI) is located at <%Brew MP Toolset%\bin\deprecated\BTIL\Host\bin>. BCI can be used to load the BTIL agent manually on a legacy BREW device. Do not use the BCI unless instructed by a dialog to do so. Avoid using the BCI with Brew MP devices.