BTSnoop File Format
Overview
The BTSnoop file format is suitable for storing Bluetooth® HCI traffic. It closely resembles the snoop format, as documented in RFC 1761.
File Format
The snoop packet capture file is an array of octets structured as follows:
The File Header is a fixed-length field containing general information about the packet file and the format of the packet records it contains. One or more variable-length Packet Record fields follow the File Header field. Each Packet Record field holds the data of one captured packet.
File Header
The structure of the File Header is as follows:
Identification Pattern:
A 64-bit (8 octet) pattern used to identify the file as a snoop packet capture file. The Identification Pattern consists of the 8 hexadecimal octets:
62 74 73 6E 6F 6F 70 00
This is the ASCII string "btsnoop" followed by one null octets.
Version Number:
A 32-bit (4 octet) unsigned integer value representing the version of the packet capture file being used. This document describes version number 1.
Datalink Type:
A 32-bit (4 octet) field identifying the type of datalink header used in the packet records that follow. The datalink type codes are listed in the table below. Values 0 - 1000 are reserved, to maximize compatibility with the RFC1761 snoop version 2 format.
| Datalink Type | Code |
|---|---|
| Reserved | 0 - 1000 |
| Un-encapsulated HCI (H1) | 1001 |
| HCI UART (H4) | 1002 |
| HCI BSCP | 1003 |
| HCI Serial (H5) | 1004 |
| Unassigned | 1005 - 4294967295 |
Packet Record Format
Each packet record holds a partial or complete copy of one packet as well as some descriptive information about that packet. The packet may be truncated in order to limit the amount of data to be stored in the packet file.
Each packet record holds 24 octets of descriptive information about the packet, followed by the packet data, which is variable-length, and an optional pad field. The descriptive information is structured as six 32-bit (4-octet) integer values.
The structure of the packet record is as follows:
Original Length
A 32-bit unsigned integer representing the length in octets of the captured packet as received via a network.
Included Length
A 32-bit unsigned integer representing the length of the Packet Data field. This is the number of octets of the captured packet that are included in this packet record. If the received packet was truncated, the Included Length field is less than the Original Length field.
Packet Flags
Flags specific to this packet. Currently the following flags are defined:
| Bit No. | Definition |
|---|---|
| 0 | Direction flag 0 = Sent, 1 = Received |
| 1 | Command flag 0 = Data, 1 = Command/Event |
| 2 - 31 | Reserved |
Bit 0 is the least significant bit of the 32-bit word.
Direction is relative to host / DTE. i.e. for Bluetooth controllers, Send is Host->Controller, Receive is Controller->Host.
Note: Some Datalink Types already encode some or all of this information within the Packet Data. With these Datalink Types, these flags should be treated as informational only, and the value in the Packet Data should take precedence.
Cumulative Drops
A 32-bit unsigned integer representing the number of packets that were lost by the system that created the packet file between the first packet record in the file and this one. Packets may be lost because of insufficient resources in the capturing system, or for other reasons.
Note: some implementations lack the ability to count dropped packets. Those implementations may set the cumulative drops value to zero.
Timestamp Microseconds
A 64-bit signed integer representing the time of packet arrival, in microseconds since midnight, January 1st, 0 AD nominal Gregorian.
In order to avoid leap-day ambiguity in calculations, note that an equivalent epoch may be used of midnight, January 1st 2000 AD, which is represented in this field as 0x00E03AB44A676000.
Packet Data
Variable-length field holding the packet that was captured, beginning with its datalink header. The Datalink Type field of the file header can be used to determine how to decode the datalink header. The length of the Packet Data field is given in the Included Length field.
Note that the length of this field in not necessarily rounded to any particular multi-octet boundary, as might otherwise be suggested by the diagram.
Data Format
All integer values are stored in "big-endian" order, with the high-order bits first.