WHAD

https://github.com/whad-team/whad-client
Admin
WHAD is a framework providing command-line tools and a library for wireless protocol hacking,...
Tokens:82,592
Snippets:835
Trust Score:8.2
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start wserver to Expose a WHAD Device

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wserver.md

Example of starting wserver to expose a WHAD device connected via uart0, listening on a specific IP address and port.

```text
$ wserver -i uart0 -a 192.168.1.2 -p 4444
```

--------------------------------

### Install WHAD from GitHub

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Installs WHAD by cloning the GitHub repository and using pip. Ensure you are in a virtual environment.

```bash
$ git clone --recurse-submodules --remote-submodules https://github.com/whad-team/whad-client.git
$ cd whad-client
$ python3 -m venv venv
$ . ./venv/bin/activate
(venv)$ pip install --upgrade pip setuptools
(venv)$ pip install .

```

--------------------------------

### Start Advertising

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Starts advertising the peripheral and allows connections.

```APIDOC
## Start Advertising

### Description
Starts the advertising process for the peripheral, making it discoverable and allowing connections. Once connected, configured services and characteristics are exposed.

### Command
```bash
start
```
```

--------------------------------

### Install WHAD with pip

Source: https://github.com/whad-team/whad-client/blob/main/README.md

Use this command to install the WHAD framework using pip.

```bash
pip install whad
```

--------------------------------

### Install Rules for All Devices

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Installs the necessary rules and configures permissions for all supported WHAD-compatible devices. Requires root privileges.

```bash
$ winstall --rules all

```

--------------------------------

### Install WHAD and Device Permissions

Source: https://context7.com/whad-team/whad-client/llms.txt

Install the WHAD framework from PyPI or source. Ensure device permissions are set up using `winstall` for all supported devices. List detected devices with `whadup` and flash firmware with `winstall --flash`.

```bash
pip install whad
```

```bash
git clone --recurse-submodules --remote-submodules https://github.com/whad-team/whad-client.git
cd whad-client
python3 -m venv venv && source venv/bin/activate
pip install --upgrade pip setuptools && pip install .
```

```bash
winstall --rules all
```

```bash
whadup
```

```bash
# [i] Available devices
# - ubertooth0  (UbertoothDevice, index 0)
# - hci0        (HCIDevice, index 0)
# - uart0       (UartDevice, /dev/ttyUSB0)
```

```bash
winstall --list           # discover attached devices and their ports
winstall --flash ubertooth --port 0
```

```bash
# winstall --flash butterfly --port /dev/ttyUSB0
```

--------------------------------

### Install Rules for Specific Devices

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Installs rules and configures permissions for specific WHAD-compatible devices. Replace 'all' with the desired device name.

```bash
# Install rules for HCI devices
$ winstall --rules hci

# Install rules for ButteRFly device (nRF52840 dongle - pca10059 or Makerdiary MDK nrf52 dongle)
$ winstall --rules butterfly

# Install rules for nodeMCU ESP-32
$ winstall --rules esp

# Install rules for nucleo STM32-WL55
$ winstall --rules nucleowl55

# Install rules for LoRa e5 mini dongle
$ winstall --rules lorae5mini

# Install rules for Ubertooth One
$ winstall --rules ubertooth

# Install rules for Yard Stick One
$ winstall --rules yardstickone

# Install rules for RFStorm device (CrazyRadio PA / Logitech Unifying dongle)
$ winstall --rules rfstorm

# Install rules for APIMote device
$ winstall --rules apimote

# Install rules for RZUSBStick
$ winstall --rules rzusbstickrfstorm

```

--------------------------------

### Example: Create, Connect, Monitor, and Spawn BLE Device

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-spawn.md

This example demonstrates a complete workflow: creating a JSON profile, connecting to a device, monitoring BLE packets with wshark, and spawning a new BLE device using the profile. The spawned device will mirror the original device's advertising data.

```text
# wble-central -i hci0 -b 11:22:33:44:55:66 profile mydevice.json
# wble-connect -i hci0 11:22:33:44:55:66 | wshark | wble-spawn -i hci1 -p mydevice.json
```

--------------------------------

### Getting Help for Commands

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Use the 'help' command followed by an optional command name to get detailed information about available commands and their usage.

```text
$ wble-periph help [command]
```

--------------------------------

### Install System Dependencies (Debian/Ubuntu x86/x64)

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Installs essential system dependencies for WHAD on Debian/Ubuntu x86/x64 systems.

```bash
$ sudo apt install gcc python3-dev binutils -y

```

--------------------------------

### Install System Dependencies (Debian/Ubuntu aarch64)

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Installs essential system dependencies for WHAD on Debian/Ubuntu aarch64 systems.

```bash
$ sudo apt install aarch64-linux-gnu-gcc binutils python3-dev -y

```

--------------------------------

### Start the BLE Peripheral Device

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/peripheral.md

Initiate the BLE peripheral device by calling the `start()` method. This will begin advertising and listening for connections.

```python
peripheral.start()
```

--------------------------------

### Starting the Peripheral

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Initiates the Bluetooth peripheral to become discoverable and connectable. The prompt changes to indicate the running state.

```text
wble-periph> start
wble-periph[running]>
```

--------------------------------

### Wireshark Monitoring Example

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

Example showing the output in the interactive shell when Wireshark is monitoring and a characteristic is read. This demonstrates the correlation between shell commands and Wireshark captures.

```text
wble-central|d0:d0:03:77:53:28> wireshark on
wble-central|d0:d0:03:77:53:28> read 22
00000000: 5B 54 56 5D 20 53 61 6D  73 75 6E 67 20 37 20 53  [TV] Samsung 7 S
00000010: 65 72 69 65 73 20                                 eries
```

--------------------------------

### wdump Usage Example

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wdump.md

This example demonstrates how to use wdump in conjunction with wplay and wfilter to process a PCAP file, filter for BLE advertisements, and save the results to a new PCAP file.

```bash
$ wplay --flush ressources/pcaps/ble_discovery.pcap ble | wfilter "BTLE_ADV_IND in p" | wdump ble_advertisements.pcap
```

--------------------------------

### Start Advertising

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Starts the advertising process for the configured BLE peripheral, allowing devices to connect and access its services and characteristics.

```text
start
```

--------------------------------

### Start Interactive BLE Peripheral Shell

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Launches an interactive shell for managing BLE peripherals. Requires specifying the WHAD interface name.

```text
$ wble-periph -i <interface> interactive
```

```text
$ wble-periph -i hci0 interactive
wble-periph>
```

--------------------------------

### Execute DuckyScript with wuni-keyboard

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/unifying/wuni-keyboard.md

Example of providing a DuckyScript file to wuni-keyboard for executing a series of keypresses.

```bash
$ wuni-keyboard -i uart0 -a 99:f9:51:2e:a4 -d myscript.ducky
```

--------------------------------

### Install Build Dependencies for Python 2 on ARM Linux

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/device/compat.md

Installs necessary packages for building Python 2 on ARM Linux systems. This is a prerequisite for building older versions of 'nrfutil'.

```shell
sudo apt install -y build-essential checkinstall libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev libffi-dev
```

--------------------------------

### Start wble-periph Interactive Shell

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-periph.md

Initiates the wble-periph interactive shell on a specified interface (e.g., hci0).

```text
$ wble-periph -i hci0
wble-periph>
```

--------------------------------

### View Available WHAD Devices

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/install.md

Displays a list of available WHAD devices after flashing firmware or installation.

```bash
$ whadup
[i] Available devices
- ubertooth0
  Type: UbertoothDevice
  Index: 0
  Identifier: 16b00016c61435aeaec24253811e00f5

- hci0
  Type: HCIDevice
  Index: 0
  Identifier: hci0

- uart0
  Type: UartDevice
  Index: 0
  Identifier: /dev/ttyUSB0

```

--------------------------------

### Peripheral Profile with Custom Service

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/profile.md

Create a peripheral profile that includes the custom standard service defined previously. This example also shows how to instantiate a peripheral with this profile.

```python
from whad.ble import Profile, Peripheral
from .service import CustomService

class CutomProfile(Profile):
    """My custom profile"""
    custom_service = CustomService()

# Create an instance of our profile and set its version
profile = CustomProfile()
profile.custom_service.version = (1,2,3)

# Create a peripheral using this profile
periph = Peripheral(Device.create('hci0'), profile=profile)
```

--------------------------------

### wble-central help command

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

Use the help command to get information about other commands supported by wble-central.

```bash
$ wble-central help [command]
```

--------------------------------

### Get Service using New Syntax (Python)

Source: https://github.com/whad-team/whad-client/blob/main/RELEASE_NOTES.md

Introduces the `service()` method for accessing services, which accepts the UUID as a string or a `UUID` object.

```python
my_service = remote_device.service('1800')
```

--------------------------------

### Send Payload via Standard Input

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/unifying/wuni-keyboard.md

Example of piping text from standard input to wuni-keyboard to send it as a payload to the target dongle.

```bash
$ echo "Hello world !" | wuni-keyboard -i uart0 -a 99:f9:51:2e:a4
```

--------------------------------

### Download Sample PCAP File

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wanalyze.md

Use wget to download a sample PCAP file containing a Bluetooth Low Energy pairing discovery procedure. This file is used in subsequent examples.

```bash
$ wget https://github.com/whad-team/whad-client/raw/main/whad/resources/pcaps/ble_pairing.pcap
```

--------------------------------

### Replaying Advertisements from PCAP

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/winject.md

This example shows how to replay BLE advertisements captured in a PCAP file. It uses a custom BTLE syntax to define the packet structure.

```text
BTLE  access_addr=0x8e89bed6 crc=0x45c882 |<BTLE_ADV  RxAdd=public TxAdd=public ChSel=0 RFU=0 PDU_type=ADV_IND Length=0x1c |<BTLE_ADV_IND  AdvA=11:22:33:44:55:66 data=[<EIR_Hdr  len=2 type=flags |<EIR_Flags  flags=general_disc_mode |>>, <EIR_Hdr  len=18 type=complete_local_name |<EIR_CompleteLocalName  local_name='TimeBox-Evo-audio' |>>] |>>>
```

--------------------------------

### wextract Usage Example

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wextract.md

Demonstrates how to pipe output from wsniff to wextract for extracting Bluetooth Low Energy advertisement data and RSSI, using a comma as a delimiter.

```text
$ wsniff -i uart0 ble -a | wextract -d ',' "p.AdvA" "p.metadata.rssi"
a4:c1:38:60:fc:5c,-69
6b:37:c6:f1:89:ae,-74
d0:d0:03:77:53:28,-70
a4:c1:38:60:fc:5c,-69
d0:d0:03:77:53:28,-70
```

--------------------------------

### wsniff with Wireshark Integration

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of using wsniff with the --wireshark option to monitor packets in real-time within a Wireshark instance.

```text
wsniff -i <interface> -w <domain> [DOMAIN OPTIONS]
```

--------------------------------

### wsniff with Scapy Show Format

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of configuring wsniff to display captured data using Scapy's show() method format.

```text
wsniff --format show ...
```

--------------------------------

### Scan for ESB Devices

Source: https://context7.com/whad-team/whad-client/llms.txt

Initializes an ESB scanner and starts discovering nearby ESB devices. The discovered devices are then printed to the console.

```python
from whad.device import WhadDevice
from whad.esb import Scanner, Sniffer, PRX, PTX

device = WhadDevice.create("uart:/dev/ttyUSB0")

# --- Scan for ESB devices ---
scanner = Scanner(device)
scanner.start()
for esb_device in scanner.discover_devices():
    print(esb_device)
```

--------------------------------

### Analyze Specific Analyzer Field

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wanalyze.md

This example shows how to select and display only a specific field, 'stk', from the 'legacy_pairing_cracking' analyzer's output.

```bash
$ wplay --flush ble_pairing.pcap | wanalyze legacy_pairing_cracking.stk
```

--------------------------------

### LoRaWAN Connector Setup

Source: https://context7.com/whad-team/whad-client/llms.txt

Imports necessary components for the LoRaWAN connector, including device creation and channel plan definitions. This snippet sets the stage for LoRaWAN communication.

```python
from whad.device import WhadDevice
from whad.lorawan.connector import LoRaWAN
from whad.lorawan.channel import ChannelPlan, Uplink, Downlink, DataRate, EU868
```

--------------------------------

### Create BLE Peripheral with WHAD Profile

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/profile.md

Define a BLE peripheral using WHAD's Profile class. This example shows how to declare services and characteristics as class properties.

```python
from whad.ble import UUID, Profile, PrimaryService, Characteristic

class MyPeripheral(Profile):

    generic_access = PrimaryService(
        UUID(0x1800),

        device_name = Characteristic(
            UUID(0x2A00),
            permissions=['read', 'notify'],
            value=b'My device name'
        )
    )
```

--------------------------------

### Logitech Unifying Sniffer Example

Source: https://context7.com/whad-team/whad-client/llms.txt

Use the Sniffer class to passively capture all Logitech Unifying frames. Set `scanning` to True to loop over all channels. The sniffer requires a device instance.

```python
from whad.device import WhadDevice
from whad.unifying import Sniffer

device = WhadDevice.create("uart:/dev/ttyUSB0")

# --- Passive sniffer (all Unifying frames) ---
sniffer = Sniffer(device)
sniffer.scanning = True   # loop over all channels
for packet in sniffer.sniff(timeout=30.0):
    packet.show()
```

--------------------------------

### Assemble and Instantiate Protocol Stack

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/protocol/index.md

Demonstrates how to assemble a protocol stack by adding layers and then instantiating it to process packets. Use this to set up and run basic packet processing.

```python
Ethernet.add(IPLayer)
Phy.add(Ethernet)

if __name__ == '__main__':

    # Instantiate our protocol stack
    my_stack = Phy()

    # Pass some packets to our stack
    packets = [
        Ether()/IP(src="192.168.1.1", dst="192.168.2.2")/TCP(),
        Ether()/IP(src="192.168.1.1", dst="192.168.2.2")/TCP(),
        Ether()/IP(src="192.168.1.2", dst="192.168.2.2")/TCP()
    ]

    for packet in packets:
        my_stack.on_packet_received(packet)

    # Display the current state of the stack
    print(my_stack.save())
```

--------------------------------

### Install nrfutil with pip

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/device/compat.md

Installs the nrfutil package using pip, which is required for firmware upgrades. Ensure you are using the correct Python version (python2.7 in this case).

```shell
sudo make install
curl https://bootstrap.pypa.io/pip/2.7/get-pip.py -o get-pip.py
sudo python2.7 get-pip.py
pip2.7 install nrfutil
```

--------------------------------

### Basic wfilter Usage

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wfilter.md

Demonstrates the basic command-line structure for using wfilter in a processing chain.

```text
... | wfilter [OPTIONS] FILTER | ...
```

--------------------------------

### Get Characteristic using New Concise Syntax (Python)

Source: https://github.com/whad-team/whad-client/blob/main/RELEASE_NOTES.md

Utilizes the new `char()` method for a simpler and more concise way to get a characteristic. The service UUID is required.

```python
my_char = remote_device.char('2A00', '1800')
if my_char is not None:
    print("Characteristic 2A00 has been found !")
else:
    print("No characteristic 2A00 found.")
```

--------------------------------

### Initialize WHAD Device and Sniffer Configuration

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/phy/started.md

Create a WHAD device instance and initialize the `SnifferConfiguration` object to hold demodulation parameters.

```python
from whad.device import WhadDevice
from whad.phy import SnifferConfiguration, Sniffer

# Create our WHAD device
device = WhadDevice.create('uart:/dev/ttyUSB0')

# Create our sniffing configuration
config = SnifferConfiguration()
```

--------------------------------

### wserver Command-Line Usage

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wserver.md

Basic syntax for running the wserver command with required interface and port, and optional IP address.

```text
wserver -i <INTERFACE> -p PORT [-a IP_ADDRESS]
```

--------------------------------

### Enumerate Available WHAD Devices

Source: https://context7.com/whad-team/whad-client/llms.txt

Use 'whadup' to list all discoverable WHAD devices on the system.

```bash
whadup
```

--------------------------------

### Start Sniffer and Demodulate Packets

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/phy/started.md

Start the sniffer and iterate through captured packets, calling the `show()` method on each to display packet information. This is the final step to capture and process raw demodulated data.

```python
# Start sniffer
sniffer.start()

# Demodulate raw packets
for packet in sniffer.sniff():
    packet.show()
```

--------------------------------

### Analyze All BLE Analyzers

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wanalyze.md

This example shows how to use wanalyze to process all available BLE analyzers by piping the output of `wplay --flush ble_pairing.pcap` to `wanalyze` without specifying any particular analyzer.

```bash
$ wplay --flush ble_pairing.pcap | wanalyze
```

--------------------------------

### Getting a Characteristic Object by UUID

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/central.md

Retrieves a `PeripheralCharacteristic` object from a service using its UUID.

```APIDOC
## characteristic(uuid)

### Description
Retrieves a `PeripheralCharacteristic` object corresponding to the given UUID from a service.

### Parameters
- **uuid** (str) - Required - The UUID of the characteristic to retrieve.

### Method
`characteristic(uuid)`

### Response
- Returns a `PeripheralCharacteristic` instance if found.

### Request Example
```python
# Assuming 'service' is a PeripheralService object
char = service.characteristic('2A00')
```
```

--------------------------------

### Enumerate Plugged WHAD Devices

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/whadup.md

Run `whadup` without arguments to list all connected WHAD devices and their basic information. This is useful for a quick overview of available hardware.

```text
# whadup
[i] Available devices
- hci0
  Type: HCIDevice
  Index: 0
  Identifier: hci0

- hci1
  Type: HCIDevice
  Index: 1
  Identifier: hci1

- uart0
  Type: UartDevice
  Index: 0
  Identifier: /dev/ttyUSB0
```

--------------------------------

### scan

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

Starts a BLE scan to discover nearby devices. The scan can be interrupted by pressing Ctrl+C.

```APIDOC
## scan

### Description
Starts a scan for Bluetooth Low Energy devices. Discovered devices are displayed in the console as they are found. The scan can be terminated by pressing Ctrl+C.

### Command
```text
scan
```

### Example Output
```text
 RSSI Lvl  Type  BD Address        Extra info
[ -62 dBm] [PUB] d0:d0:03:77:53:28
[ -62 dBm] [PUB] d0:d0:03:77:53:28 name:"[TV] Samsung 7 Series (55)"
Scan terminated by user
```
```

--------------------------------

### wzb-enddevice Usage

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/zigbee/zb-enddevice.md

The basic syntax for running the wzb-enddevice tool. It accepts options and requires a command as its first argument.

```text
wzb-enddevice [OPTIONS] ([COMMAND] ([COMMAND ARGS]))
```

--------------------------------

### Instantiate and Test Protocol Stack

Source: https://context7.com/whad-team/whad-client/llms.txt

Instantiate a protocol stack, send packets through it, save/load state snapshots, and export the stack as a DOT graph. Includes unit testing with Sandbox.

```python
# --- Instantiate and use the stack ---
stack = PhyLayer(options={"ether": {}})
stack.on_packet_received(Ether(src="aa:bb:cc:dd:ee:ff") / IP() / TCP())

# Save / restore state snapshot
snapshot = stack.save()
stack.load(snapshot)

# Export DOT graph for visualization
PhyLayer.export("mystack.dot")

# --- Unit testing with Sandbox ---
@alias("phy_mock")
class PhyMock(Sandbox):
    pass
PhyMock.add(EthernetLayer)

class TestEther:
    @pytest.fixture
    def phy(self):
        return PhyMock()

    def test_echo(self, phy):
        pkt = Ether(src="aa:bb:cc:dd:ee:ff") / IP() / TCP()
        phy.send("ether", pkt)
        assert phy.expect(LayerMessage("ether", "phy_mock", pkt))
```

--------------------------------

### Getting a Service Object by UUID

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/central.md

Retrieves a `PeripheralService` object from the discovered services using its UUID.

```APIDOC
## service(uuid)

### Description
Retrieves a `PeripheralService` object corresponding to the given UUID.

### Parameters
- **uuid** (str) - Required - The UUID of the service to retrieve.

### Method
`service(uuid)`

### Response
- Returns a `PeripheralService` instance if found.

### Request Example
```python
service = target.service('1800')
```
```

--------------------------------

### wsniff LoRa Capture with Bandwidth

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data, specifying the bandwidth in Hz.

```text
wsniff -i <interface> phy -lora -bw <bandwidth> ...
```

--------------------------------

### Start BLE Scan

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

Initiates a scan for nearby Bluetooth devices. The scan can be terminated manually with Ctrl+C.

```text
scan
```

```text
wble-central> scan
 RSSI Lvl  Type  BD Address        Extra info
[ -62 dBm] [PUB] d0:d0:03:77:53:28
[ -62 dBm] [PUB] d0:d0:03:77:53:28 name:"[TV] Samsung 7 Series (55)"
Scan terminated by user
```

--------------------------------

### BLE Scanner - Discover Devices (One-Shot)

Source: https://context7.com/whad-team/whad-client/llms.txt

Use the `whad.ble.Scanner` to discover BLE advertising devices. This example performs a one-shot scan for 30 seconds. The context manager ensures clean teardown of the scanner.

```python
from whad.device import Device
from whad.ble import Scanner

# One-shot scan for 30 seconds (context manager ensures clean teardown)
with Scanner(Device.create("hci0")) as scanner:
    for adv_device in scanner.discover_devices(timeout=30.0):
        print(f"[{adv_device.rssi:+4d} dBm] {adv_device.address}  {adv_device.name or ''}")
```

--------------------------------

### Get Device Information

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

Displays detailed information about a discovered device using its name or Bluetooth address.

```text
info [NAME | BDADDR]
```

```text
wble-central> info d0:d0:03:77:53:28
Device d0:d0:03:77:53:28
RSSI:               -62 dBm
Address type:       public

Raw advertising records

  AD Record #0:
   02 01 0a

  AD Record #1:
   1b ff 75 00 42 04 01 20 76 19 0f 00 00 01 37 00
   00 00 00 00 00 00 00 00 00 00 00 00
```

--------------------------------

### Interact with Standard BLE Battery Service (Python)

Source: https://github.com/whad-team/whad-client/blob/main/RELEASE_NOTES.md

Example of connecting to a BLE device, discovering services, and interacting with the standard Battery Service using the `BatteryService` class. Ensure the device supports this service before querying.

```python
from whad.device import Device
from whad.ble import Central, UUID, BatteryService
from whad.ble.exceptions import PeripheralNotFound

# We assign a BLE central role to our HCI adapter
central = Central(Device.create("hci0"))

# Target not connected
target = None

try:
    # Connect to remote device and discover services and characteristics
    target = central.connect("00:11:22:33:44:55", random=True)
    target.discover()

    # Check the device exposes a Battery service, queries it and read
    # the battery's level as a percentage
    if target.has(BatteryService):
        battery = target.query(BatteryService)
        print(f"Battery level: {battery.percentage}%")
    else:
        print("Battery service is not supported by this device.")

    # Closing connection
    target.disconnect()
```

--------------------------------

### wsniff LoRa Capture with Coding Rate

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data, specifying the coding rate.

```text
wsniff -i <interface> phy -lora -cr <coding_rate> ...
```

--------------------------------

### Create Peripheral Instance with Custom Profile

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/ble/peripheral.md

Instantiate the `Peripheral` connector using a specific HCI device, a custom GATT profile, and advertising data.

```python
from whad.device import Device
from whad.ble import (
    Peripheral, AdvCompleteLocalName, AdvDataFieldList, AdvFlagsField, UUID,
    PrimaryService, Characteristic, GenericProfile,
)

class CustomProfile(Profile):
    """Custom GATT profile"""

    # Define a generic access service (GAS) with UUID 0x1800
    gas = PrimaryService(
        UUID(0x1800),

        # Define a DeviceName characteristic with read/write permissions
        device_name = Characteristic(
            UUID(0x2A00),

            # Read/write permissions
            permissions=['read', 'write'],

            # Characteristic supports notifications with a
            # ClientCharacteristicConfiguration descriptor (CCCD)
            notify=True,

            # Default value for this characteristic
            value=b"TestDevice"
        )
    )

# Create an instance of Peripheral class using HCI device hci0 and a custom
# profile defined in CustomProfile
profile = CustomProfile()
peripheral = Peripheral(
    Device.create("hci0"),
    profile=profile,
    adv_data=AdvDataFieldList(
        AdvFlagsField(), # Defines a default Flags record
        AdvCompleteLocalName(b"TestDevice") # Adds a CompleteLocalName record
    )
)
```

--------------------------------

### wplay Usage Syntax

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wplay.md

Basic syntax for using the wplay tool. It requires a PCAP file and a domain, and can be piped to other WHAD tools.

```text
wplay PCAP DOMAIN [DOMAIN OPTIONS] | ...
```

--------------------------------

### wsniff LoRa Capture with Spreading Factor

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data, specifying the spreading factor.

```text
wsniff -i <interface> phy -lora -sf <spreading_factor> ...
```

--------------------------------

### Complete Protocol Stack Initialization

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/protocol/index.md

This snippet shows the complete definition of the Ethernet and Phy layers, including their handlers and the final step of adding the Ethernet layer as a sub-layer to the Phy layer, initializing the protocol stack.

```python
from whad.common.stack import Layer, alias, source
from scapy.all import *

@alias('ether')
class Ethernet(Layer):

    def configure(self, options={}):
        if 'something' in options:
            self.state.something = options['something']

    @source('phy')
    def on_packet_received(self, packet):
        """Process incoming packets from the PHY layer.
        """
        # Send back the packet
        self.send('phy', packet)

@alias('phy')
class Phy(Layer):

    def configure(self, options={}):
        pass

    def on_packet_received(self, packet: Packet):
        if packet.haslayer(Ether):
            self.send('ether', packet.getlayer(Ether))

    @source('ether')
    def on_ether_packet(self, packet):
        print('Received a packet from Ether layer:')
        packet.show()

Phy.add(Ethernet)
```

--------------------------------

### Create WHAD Hardware Interface with WhadDevice Class (Legacy)

Source: https://github.com/whad-team/whad-client/blob/main/RELEASE_NOTES.md

This code demonstrates the previous method of accessing WHAD hardware interfaces using the `WhadDevice` class. This class is maintained for backward compatibility but is planned for deprecation.

```python
from whad.device import WhadDevice

dev = WhadDevice.create("uart0")

```

--------------------------------

### wsniff LoRa Capture with Explicit Mode Enabled

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data with explicit mode enabled.

```text
wsniff -i <interface> phy -lora -em ...
```

--------------------------------

### wsniff PHY Capture with Little-Endian Interpretation

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing PHY data and interpreting bytes in little-endian format.

```text
wsniff -i <interface> phy -le ...
```

--------------------------------

### Connect to a Device and Profile Services

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/ble/ble-central.md

In interactive mode, use the 'connect' command to establish a connection with a target device. Subsequently, use the 'profile' command to list available services and their characteristics, including handles and access rights.

```text
wble-central> connect
Successfully connected to target 40:b3:14:04:b7:07
wble-central|40:b3:14:04:b7:07> profile
Service 1801

2A05 handle: 2, value handle: 3
| access rights: indicate

Service 1800

2A00 handle: 21, value handle: 22
| access rights: read
2A01 handle: 23, value handle: 24
| access rights: read
2AA6 handle: 25, value handle: 26
| access rights: read
```

--------------------------------

### Chaining WHAD Tools with Pipes

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/index.md

Demonstrates how to chain WHAD tools using the shell pipe operator (|) to create a packet processing chain. This example connects to a BLE device, monitors traffic with wshark, and then uses wble-central to interact with the device's services.

```text
$ wble-connect -i hci1 11:22:33:44:55:66 | wshark | wble-central profile
```

--------------------------------

### Basic ZigBee Sniffer

Source: https://context7.com/whad-team/whad-client/llms.txt

Initializes a ZigBee sniffer on a specified channel and starts capturing packets. The captured packets are then displayed.

```python
from whad.device import WhadDevice
from whad.zigbee import Sniffer

device = WhadDevice.create("uart0")

# Basic sniffer
sniffer = Sniffer(device)
sniffer.channel = 11
sniffer.start()
for packet in sniffer.sniff(timeout=30.0):
    packet.show()
```

--------------------------------

### Set Target Frequency for Sniffing

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/phy/started.md

Configure the target frequency in Hertz for demodulation. This example sets the frequency to 2.402 GHz.

```python
# Configure demodulation
config.frequency = 2402000000
```

--------------------------------

### Instantiate and Configure Protocol Stack

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/protocol/index.md

Instantiate a protocol stack starting from the PHY layer, automatically instantiating registered sub-layers. Options can be passed to configure sub-layers, such as enabling MAC address logging for the Ethernet layer.

```python
from whad.common.stack import Layer, LayerState, alias, source, state
from scapy.all import *

class EthernetState(LayerState):

    def __init__(self):
        super().__init__()
        self.macs = []

    def clear(self):
        self.macs = []

    def add_mac_address(self, mac):
        if mac not in self.macs:
            self.macs.append(mac)

    def has_mac_address(self, mac):
        return mac in self.macs

    def remove_mac_address(self, mac):
        if mac in self.macs:
            self.macs.remove(mac)

@state(EthernetState)
@alias('ether')
class Ethernet(Layer):

    def configure(self, options={}):
        # Clear state
        self.state.clear()
        self.log_macs = False

        # Check if we are asked to log mac addresses
        if 'log_macs' in options:
            if options['log_macs'] == True:
                self.log_macs = True


    @source('phy')
    def on_packet_received(self, packet):
        """Process incoming packets from the PHY layer.
        """
        if self.log_macs:
            # Add source mac to our mac address book
            self.state.add_mac_address(packet.getlayer(Ether).src)

        # Send back the packet
        self.send('phy', packet)


@alias('phy')
class Phy(Layer):

    def configure(self, options={}):
        pass

    def on_packet_received(self, packet: Packet):
        if packet.haslayer(Ether):
            self.send('ether', packet.getlayer(Ether))

    @source('ether')
    def on_ether_packet(self, packet):
        print('Received a packet from Ether layer:')
        packet.show()

Phy.add(Ethernet)

my_stack = Phy(options={
    'ether': {
        'log_macs': True
    }
})
```

--------------------------------

### wsniff LoRa Capture with Preamble Length

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data, specifying the preamble length in number of symbols.

```text
wsniff -i <interface> phy -lora -pl <preamble_length> ...
```

--------------------------------

### Set Analyzer Configuration Parameter

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wanalyze.md

Demonstrates how to set a configuration parameter for an analyzer using the --set OPTION=VALUE or -s OPTION=VALUE flag. This example shows setting the 'locale' parameter for the Unifying keystroke analyzer.

```bash
$ wanalyze -s locale=en
```

--------------------------------

### wsniff LoRa Capture with CRC Enabled

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing LoRa data with Cyclic Redundancy Check (CRC) enabled.

```text
wsniff -i <interface> phy -lora -crc ...
```

--------------------------------

### wsniff PHY Capture with FSK Deviation

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing PHY data with FSK modulation, specifying the frequency deviation.

```text
wsniff -i <interface> phy -dev <deviation> ...
```

--------------------------------

### wsniff PHY Capture with Sync Word

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of capturing PHY data, specifying a synchronization word in hexadecimal format.

```text
wsniff -i <interface> phy -w 8e89bed6 ...
```

--------------------------------

### wsniff with Raw Hexdump Output

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wsniff.md

Example of configuring wsniff to display captured data in a raw hex dump format.

```text
wsniff --format raw ...
```

--------------------------------

### Filtering Packets with Scapy Expression

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/generic/wfilter.md

Example of using a Python expression with Scapy to filter packets. The packet is available as 'p'.

```python
BTLE_ADV_IND in p
```

--------------------------------

### Instantiate a LoRaWAN Application

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/lorawan/gateway.md

Create an instance of your custom LoRaWAN application, providing a list of allowed LWNode devices. Devices without session keys are configured for OTAA.

```python
# Create our app instance
my_app = EchoApp(
    devices=[
        LWNode('74:a1:e4:c9:60:72:06:3a')
    ]
)
```

--------------------------------

### Send Encrypted Keypresses with wuni-keyboard

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/unifying/wuni-keyboard.md

Example of sending encrypted keypresses using a DuckyScript file and a provided encryption key.

```bash
$ wuni-keyboard -i uart0 -a 99:f9:51:2e:a4 -d myscript.ducky --key 086712d2f4f567662cb5ebafca20bb96
```

--------------------------------

### Send Text Payload with wuni-keyboard

Source: https://github.com/whad-team/whad-client/blob/main/doc/source/cli/unifying/wuni-keyboard.md

Example of sending a text payload to a target dongle. The payload is followed by an ENTER keypress.

```bash
$ wuni-keyboard -i uart0 -a 99:f9:51:2e:a4 -p "Hello world !"
```
Tokens:
Raw