├── Sniffer └── Sniffer.ino └── README.md /Sniffer/Sniffer.ino: -------------------------------------------------------------------------------- 1 | /* 2 | * Sniffing for WiFi packages in the air. 3 | * This code is in the public domain. 4 | */ 5 | 6 | // Include ticker for frequently executing functions 7 | #include 8 | 9 | // External library files of Espressif SDK 10 | extern "C" { 11 | #include "user_interface.h" 12 | #include "ets_sys.h" 13 | #include "osapi.h" 14 | #include "gpio.h" 15 | #include "os_type.h" 16 | #include "mem.h" 17 | #include "user_config.h" 18 | } 19 | 20 | // Delay times 21 | // Delay of loop function in milli seconds 22 | # define __delay__ 10 23 | // Delay of channel changing in seconds 24 | # define __dlay_ChannelChange__ 0.5 25 | 26 | //Ticker for channel hopping 27 | Ticker ts; 28 | 29 | //Promiscuous callback structures for storing package data, see Espressif SDK handbook 30 | struct RxControl { 31 | signed rssi:8; 32 | unsigned rate:4; 33 | unsigned is_group:1; 34 | unsigned:1; 35 | unsigned sig_mode:2; 36 | unsigned legacy_length:12; 37 | unsigned damatch0:1; 38 | unsigned damatch1:1; 39 | unsigned bssidmatch0:1; 40 | unsigned bssidmatch1:1; 41 | unsigned MCS:7; 42 | unsigned CWB:1; 43 | unsigned HT_length:16; 44 | unsigned Smoothing:1; 45 | unsigned Not_Sounding:1; 46 | unsigned:1; 47 | unsigned Aggregation:1; 48 | unsigned STBC:2; 49 | unsigned FEC_CODING:1; 50 | unsigned SGI:1; 51 | unsigned rxend_state:8; 52 | unsigned ampdu_cnt:8; 53 | unsigned channel:4; 54 | unsigned:12; 55 | }; 56 | struct LenSeq { 57 | uint16_t length; 58 | uint16_t seq; 59 | uint8_t address3[6]; 60 | }; 61 | struct sniffer_buf { 62 | struct RxControl rx_ctrl; 63 | uint8_t buf[36]; 64 | uint16_t cnt; 65 | struct LenSeq lenseq[1]; 66 | }; 67 | struct sniffer_buf2{ 68 | struct RxControl rx_ctrl; 69 | uint8_t buf[112]; 70 | uint16_t cnt; 71 | uint16_t len; 72 | }; 73 | 74 | // Function for printing the MAC address i of the MAC header 75 | void printMAC(uint8_t *buf, uint8 i) 76 | { 77 | Serial.printf("\t%02X:%02X:%02X:%02X:%02X:%02X", buf[i+0], buf[i+1], buf[i+2], buf[i+3], buf[i+4], buf[i+5]); 78 | } 79 | 80 | // Promiscuous callback function: is executed whenever package is received by ESP 8266 81 | void promisc_cb(uint8_t *buf, uint16_t len) 82 | { 83 | uint8_t* buffi; 84 | if ((len == 12)){ 85 | return; // Nothing to do for this package, see Espressif SDK documentation. 86 | } 87 | if (len == 12){ 88 | return; 89 | } 90 | else if (len == 128) { 91 | struct sniffer_buf2 *sniffer = (struct sniffer_buf2*) buf; 92 | buffi=sniffer->buf; 93 | } 94 | else { 95 | struct sniffer_buf *sniffer = (struct sniffer_buf*) buf; 96 | buffi=sniffer->buf; 97 | } 98 | Serial.printf("Channel %3d: Package Length %d", wifi_get_channel(), len); 99 | printMAC(buffi, 4); // Print address 1 100 | printMAC(buffi, 10); // Print address 2 101 | printMAC(buffi, 16); // Print address 3 102 | if((bitRead(buffi[1],7)==1)&&(bitRead(buffi[1],6)==1)) printMAC(buffi, 24); // Print address 4 103 | Serial.print(" "); 104 | Serial.print(bitRead(buffi[1],7)); 105 | Serial.print(bitRead(buffi[1],6)); 106 | Serial.printf("\n"); 107 | } 108 | 109 | // Change the WiFi channel 110 | void channelCh(void) 111 | { 112 | // Change the channels by modulo operation 113 | uint8 new_channel = wifi_get_channel()%12 + 1; 114 | Serial.printf("** Hop to %d **\n", new_channel); 115 | wifi_set_channel(new_channel); 116 | } 117 | 118 | // Setup procedure 119 | void setup() 120 | { 121 | // Set baudrate UART 122 | Serial.begin(115200); 123 | // Sniffer works only in station mode 124 | wifi_set_opmode(STATION_MODE); 125 | // Set the promiscuous related options 126 | wifi_promiscuous_enable(0); 127 | wifi_set_promiscuous_rx_cb(promisc_cb); 128 | wifi_promiscuous_enable(1); 129 | Serial.printf("Setup done!"); 130 | // Change the channel every 0.5 seconds, change for different frequency 131 | ts.attach(__dlay_ChannelChange__, channelCh); 132 | } 133 | 134 | // Loop 135 | void loop() 136 | { 137 | // Duration of loop defined by delay function: note that during delay the WiFi stack can process the data in the background and is waiting for WiFi packages 138 | delay(__delay__); 139 | } 140 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ESP-8266 sniffer on WeMos D1 mini board 2 | 3 | ## Content 4 | 5 | This software sketch is a port of the Espressif SDK sniffing functionality to the famous Arduino platform for the WeMos D1 mini (http://www.wemos.cc). 6 | With this code sketch, one is able to catch and analyse WiFi packages in the air and transmit them via USB-to-Serial to a PC in order to get information like the MAC addresses of participating receivers/senders. 7 | 8 | For more information of the main sniffer functionality, see the Espressif SDK documentation: 9 | 10 | http://espressif.com/file/384/download?token=6Xs47A-_ 11 | 12 | This instruction summarises the main points of the WeMos Tutorial (http://www.wemos.cc/Tutorial/get_started_in_arduino.html) and other tutorials about this topic on the Internet. 13 | 14 | Note that the Git software is used to clone this repository, see https://git-scm.com for more information or download the whole package from the repository page. For executing the commands, the Git Bash console is recommended. 15 | 16 | ## How to get started? 17 | 18 | ### First step 19 | 20 | First of all, one needs to install the driver of the USB-to-Serial chip for recognising the WeMos D1 mini board which is called ch301g. Download it from the following webpage: 21 | 22 | http://www.wemos.cc/downloads/ 23 | 24 | Install the driver and plug the WeMos D1 mini board to your computer per USB. 25 | 26 | In addition, a key point is to install the Arduino IDE software on the local machine as the WeMos D1 mini board is supported by it directly. Download the official Arduino software from the Arduino webpage: 27 | 28 | http://www.arduino.cc 29 | 30 | ### Second step 31 | 32 | Clone the Arduino support of the WeMos D1 mini board into the Arduino Sketchbook (see Arduino IDE: ``Files – Preferences`` for Sketchbook path): 33 | 34 | ``` 35 | cd hardware 36 | mkdir esp8266com 37 | cd esp8266com 38 | git clone https://github.com/esp8266/Arduino.git 39 | ``` 40 | 41 | If the hardware directory does not exist, create it. 42 | 43 | As a next step, the ESP 8266 binary tools must be downloaded by executing: 44 | 45 | ``` 46 | cd esp8266/tools 47 | python get.py 48 | ``` 49 | 50 | If the command ``python`` is unknown to your OS, please install the Python 2 package from the respective website (https://www.python.org/download/releases/2.7.2/) and configure it to work with your system. Especially, add the python executable file path to your Windows PATH variable or use the explicit ```python``` executable in its respective directory. 51 | 52 | ### Third step 53 | 54 | Start the Arduino IDE and configure the software for programming the WeMos D1 mini board under ``Tools – Board - WeMos D1 R2 & mini``. 55 | There are two ways to upload the code to the ESP 8266 to the board: either by USB-to-Serial using the USB plug on the board or per OTA to upload directly per WiFi. 56 | For first tries, one should rely on the USB variant as it is less complicated. To do so, set under ``Tools`` the following settings: 57 | 58 | ``` 59 | Upload Using “Serial” 60 | CPU Frequency “80 MHz” 61 | Flash Size “4M (3M SPIFFS) 62 | Upload Speed “921600” 63 | ``` 64 | 65 | ### Fourth (optional) step 66 | 67 | There are several examples for this board from WeMos directly available. Just clone the examples directory to the Sketchbook directory by executing: 68 | 69 | ``` 70 | cd Sketchbook 71 | git clone https://github.com/wemos/D1_mini_Examples.git 72 | ``` 73 | 74 | As examples are always a good way of introducing programming to oneself, it is strongly recommended for beginners to download them. 75 | 76 | ### Fifth step 77 | 78 | Clone this repository to the Sketchbook directory as it contains the main code and the sniffer program itself 79 | 80 | ``` 81 | git clone https://github.com/IoTpower/esp8266-ard-sniff.git 82 | ``` 83 | 84 | ### Fifth step 85 | 86 | Restart the Arduino IDE if still executed in the background. 87 | 88 | ## Loading the actual sniffer program 89 | 90 | ### Compiling and flashing 91 | 92 | Start the Arduino IDE and load the Sniffer file ```/Sniffer/Sniffer.ino``` via ``File – Open`` from the Sniffer directory. Compile it and upload it to the board. 93 | 94 | ### Start serial monitoring 95 | 96 | Go to ``Tools – Serial Monitor`` and set Baudrate to 115200, enjoy! 97 | 98 | ### What do I see? 99 | 100 | The first number is the channel of the monitored WiFi transmissions where the package has been captured. The second number is the length of the package and the following columns are the Addr1, Addr2, Addr3, and Addr4 of the MAC header of the captured WiFi package. The delay times and times of scanning a specific channel can be adjusted. 101 | --------------------------------------------------------------------------------