Sniffer

The entry point for the API.

Field	Type	Description
missedPackets	int	The number of missed packets over the UART, as determined by the packet counter in the header. Derived using the packetCounter field.
packetsInLastConnection	int	The number of packets which were sniffed in the last BLE connection. From CONNECT_REQ until link loss/termination.
connectEventPacketCounterValue	int	The packet counter value of the last received connect request.
inConnection	bool	A boolean indicating whether the sniffed device is in a connection.
currentConnectRequest	Packet	A Packet object containing the last received connect request.
state	int	The internal state of the sniffer. States are defined in SnifferCollector module. Valid values are 0-2.
portnum	int or string	The COM port of the sniffer hardware. During initialization, this value is a preset.
swversion	int	The version number of the API software.
fwversion	int	The version number of the sniffer firmware.
Function	Type	Description
__init__(portnum)	Sniffer	Constructor for the Sniffer class. The optional argument "portnum" is a string with the name of the port the sniffer board is at, e.g. "COM17". If not provided, the API will locate it automatically, but this takes more time.
start()	void	Starts the Sniffer thread. This call must be made (once and only once) before using the sniffer object.
getPackets(number)	List<Packet>	Get [number] number of packets since last fetch (-1 means all). Note that the packet buffer is limited to about 80000 packets.
getDevices()	DeviceList	Get a list of devices which are advertising in range of the Sniffer.
follow(device, followOnlyAdvertisements)	void	Signal the Sniffer firmware to sniff a specific device. If followOnlyAdvertisements is True, the sniffer will not sniff a connection, only advertisements from the followed device.
scan()	void	Signal the Sniffer to scan for advertising devices by sending the REQ_SCAN_CONT UART packet. This will cause it to stop sniffing any device it is sniffing at the moment.
sendTK(TK)	void	Send a temporary key to the sniffer for use when decrypting encrypted connections. TK is a list of 16 ints, each representing a byte in the temporary key. TK is on big-endian form.
setPortnum(portnum)	void	Set the preset COM port number. Only use this during startup. Set to None to search all ports.
doExit()	void	Gracefully shut down the sniffer threads and connections.

Device

Class representing a BLE device from which the sniffer has picked up data.

Field	Type	Description
address	List< int >	A list representing the device address of this device: [int, int, int, int, int, int]
txAdd	bool	A boolean representing whether the device address is public (False) or random (True).
name	string	A string containing the name (short or complete) of the device.
RSSI	int	An int representing the approximate RSSI value of packets received from this device.

DeviceList

A class representing a list of devices. Used to simplify extraction of devices using BLE metadata.

Function	Type	Description
find(id)	Device	Find a device in this DeviceList using either name or address. Returns None if no device is found.
remove(id)	Device	Remove a device from this DeviceList. Argument "id" has same format as in find.
append(Device)	void	Append a Device to the device list.
index(Device)	int	Returns the index of the provided Device.
getList()	List<Device>	Returns a list of the Devices in this DeviceList.

Packet

Represents the UART packet sent by the sniffer to the host.

Field	Type	Description
headerLength	int	The length of the UART header.	UART header
payloadLength	int	The length of the UART payload.
protover	int	The UART protocol version used.
packetCounter	int	Unique (16 bit) packet identifier which increments for each packet sent by the sniffer.
id	int	Identifier telling what type of packet this is. See UART protocol document.
bleHeaderLength	int	Length of the NRF_BLE_PACKET header.	NRF_BLE_PACKET header
crcOK	bool	Was the CRC received by the sniffer OK.
micOK	bool	Is the message integriy check OK. Only relevant in encrypted state.
direction	bool	Only relevant during connection. True -> Master to Slave, False -> Slave to Master
encrypted	bool	has the packet been encrypted.
channel	int	Which channel was the packet picked up from [0 - 39]
RSSI	int	The RSSI value reported by the sniffer. NOT PRECISE. Real value is the negative of this value.
eventCounter	int	The eventcounter of the packet in the connection. Only relevant for packets in a connection.
timestamp	int	Microseconds from the end of the last packet to the start of this one.
blePacket	BlePacket	The blePacket contained within this packet.	Other
packetList	List< int >	The entire UART packet as sent by the sniffer (with the exception of a padding byte which is removed).
OK	bool	Is the error detection of the attached BLE packet OK?
payload	List< int >	List containing the UART payload as bytes.
txADD	bool	Is the address public or random? True -> Random, False -> Public. Only relevant for advertisement packets.
version	int	The firmware version of the sniffer. Only sent in PING_RESP packets.

BlePacket

Represents the BLE packet received over the air by the sniffer.

Field	Type	Description
accessAddress	List< int >	A list of bytes representing the access for this packet.
advType	int	The advertisement type field.
advAddress	List< int >	The advertising address.
name	string	The value of the localname property of the ble packet.
payload	List< int >	The entire BLE payload (not including access address and header fields).
length	int	The value of the length field of the BLE PDU

Exceptions

The exceptions raised by the API.

Exception	Description
SnifferTimeout	UART read time out.
UARTPacketError	UART SLIP parsing error.
InvalidPacketException	Other UART parsing error.