Files

# Sniffer Firmware
[Applications]

This application provides funtions for scanning and sniffing different radio channels.
More...

## Files
file | sniffer.c

| Implementation of the Sniffer Firmware.
file | sniffer.h

| Interface of the Sniffer Firmware.
file | sniffer_ctrl.c

| Implementation of the control commands for Sniffer Firmware.
file | sniffer_scan.c

| Implementation of the scanning functions for Sniffer Firmware.

## Detailed Description

This application provides funtions for scanning and sniffing different radio channels.

This section describes the UART interface of the sniffer firmware. The interfacing with wireshark is described in section 802.15.4 Packet Sniffing.

The application provides two modes:

- The Scan Mode scans over the selected channels and displays statistics of the received frames. The channel is switched after the time SCAN_PERIOD_MS.
- The Sniff Mode receives on one selected channel and dumps the frames on the host interface. This mode can used for live capturing WPAN data with wireshark (see contibution guide for more details).

## Usage

The following commands are available in the terminal:

Mode Commands:

- idle, Keys: `I`, `<SPACE>`
  Set application to idle mode and transceiver to state TRX_OFF.
- scan
  Scan for frames on the enabled channels (see also commands `cmask`, `cmset` and `cmclr`)
- sniff
  Start sniffing frames on the current channel and dump the received packets of the hostinterface (see command `parms`).

Parameter Commands:

- parms
  Display current parameter settings.
- chan <CHAN>, Keys: `+` , `-`
  Set current channel (for sniffing). "+" increments the current channel by one, "-" decrements by one.
- cmclr <chan>
  Erase the channel bit in `cmask`.
- cmset <chan>
  Set the channel bit in `cmask`.
- cmask <mask>
  Set the 32 bit channel mask. `mask` can be a hexadecimal value, e.g. 0x07fff800
- cpage <page>
  Set current channel page ({not yet supported})
- drate <ratestr>
  Set current data rate of transceiver. ratestr = {BPSK{20,40}, OQPSK{100,200,250,400,500,1000,2000}}
- chkcrc <[0|1]>
  if 0, discard frames with invalid CRC, if 1, report also frames with invalid CRC.

### Scan Mode

The Scan Mode is started with the command `scan`. The scanned channels can be configured with the channel mask and the commands `cmset`, `cmclr` and `cmask`.

IEEE Channels, Channel Mask and Channel Page in Scan Mode

IEEE 802.15.4 uses a 32 bit channel mask. Since the standard uses just 26 channels (0 for 868 MHz, 1-10 for 915 MHz and 11-26 for 2.4 GHz) the upper 5 bits of the channel mask are currently used by the value channel page. The channel page identifies the modulation method used.

In order to enable channel 15 in the channel mask for scanning, you can use the command `cmask 0x00008000` or `cmset 15`.

    > parms
    SUPP_CMSK: 0x07fff800 ....... shows the supported channels of the radio
    CURR_CMSK: 0x04008800 ....... channel mask used for scanning (11,15,26)
    CURR_CHAN: 11 ............... channel used for sniffing
    CURR_PAGE: 0  ............... unsupported yet

Display of the Scan Results

In scan mode the application switches from channel to channel and collects the statistics of the received frames. The information can be displayed in a terminal as table (see example below, which scans only channels 11 and 15, cmask = 0x00008800).

    > scan
    Scanning channels, scan period 2000ms
                 bad    Avg.         802.15.4 frames
    chan   frm   crc   ed lqi      B     D     A     C  PER
    11      0     0    0   0      0     0     0     0    0
     12  n/a
     13  n/a
     14  n/a
     15     62     0   71 255      0    62     0     0    0
     16  n/a
     17  n/a
     18  n/a
     19  n/a
     20  n/a
     21  n/a
     22  n/a
     23  n/a
     24  n/a
     25  n/a
     26      1     1    0   0      0     0     0     0  100
    === ur 0 err 0 frames: 63 ===

The columns of the table have the following meaning:

                 bad    Avg.         802.15.4 frames
    chan   frm   crc   ed lqi      B     D     A     C  PER
     |      |     |    |   |       |     |     |     |   +... Estimated packet error rate
     |      |     |    |   |       |     |     |     +....... number of rx'd command frames
     |      |     |    |   |       |     |     +............. number of rx'd ACK frames
     |      |     |    |   |       |     +................... number of rx'd data frames
     |      |     |    |   |       +......................... number of rx'd beacon frames
     |      |     |    |   +................................. average LQI of frames on this channel
     |      |     |    +..................................... average energy value frames on this channel
     |      |     +.......................................... number of frames with bad CRC
     |      +................................................ number of received frames
     +....................................................... channel number

### Sniffer Mode

The Sniff Mode is started with the command `sniff`. The channel which should be monitored is set with the command `chan`. In the sniff mode, each received frame is transfered over the host interface to the PC application.

Data Transfer in Sniffer Mode

The binary protocoll used for transfer the received frames over the host interface in sniff-mode has the following format:

     +-------+--------+--------+------------+--------+
     | SOF   |  LEN   | TSTAMP | FRAMEDATA  | EOF    |
     +-------+--------+--------+------------+--------+
     | 1Byte | 1 Byte | 8 Byte | 1-127 Byte | 1 Byte |
     +-------+--------+--------+------------+--------+

Parameters:

  | SOF | Start of frame field (0x01)
  | LEN | Length of packet (size of time stamp and frame size) (8 ... 133)
  | TSTAMP | Time structure (4 Byte seconds, 4 byte micro seconds)
  | FRAMEDATA | Octets of the frame (the data does not contain the IEEE 802.15.4 PHR with the reserved bit value).
  | EOF | End of frame field.