diff --git a/README.md b/README.md index 2d1a5b3..26c0763 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,115 @@ -# Lora Scanner Application +# Skinny R&D Lora Scanner + +![lora-main](./doc/img/lora-main.png) ## Introduction -The Lora Scanner is a Flask web application integrated with SocketIO, designed for real-time communication and management of serial data across various frequency bands. This application is ideal for monitoring and analyzing LoRa (Long Range) wireless communication, offering features like device tracking, data analysis, and survey mode. +The Lora Scanner is a Flask web application integrated with SocketIO, designed for monitoring and analyzing LoRa (Long Range) wireless communication. ## Features -- **Real-Time Data Processing**: Read and process data from serial ports in real-time. -- **Frequency Band Management**: Manage connections across 433 MHz, 868 MHz, and 915 MHz bands. -- **Interactive Web Pages**: Dedicated pages for dashboard, analysis, survey, and tracking. -- **WebSocket Integration**: Real-time data streaming with SocketIO. -- **Serial Data Transmission**: Transmit data over serial connections. + +* **Packet Streaming**: View a live stream of each raw LoRa packet captured and received by the LoRa Scanner with `Analysis Mode`. +* **Supported Frequencies**: Capture packets at 915, 868, or 433 MHz +* **Device Tracking**: Track down LoRa Devices in the area using `Tracking Mode`. +* **Packet Analysis**: View every packet captured by the LoRa scanner with `Survey Mode`. +* **Exporting Data**: Perform AI powered data analysis on LoRa packets by downloading them from the `Survey Mode` page. +* **LoRaWAN Support**: Integrated LoRaWAN support with the Dragino LPS8N Indoor LoRaWAN Gateway. +* **Hardware Support**: The LoRa Scanner is currently designed to work with an `Adafruit Feather M0` or `32u4`. ## Installation +### Hardware Requirements + +Flash your Adafruit Feather M0 (or 32u4) with the Skinny LoRa firmware. You can attach up to three different receivers at a time. For instructions, please follow the steps 1-2 [here](https://github.com/skinnyrad/Skinny-LoRa). + +*Note: For 433 MHz analysis you need the `Adafruit Feather M0 LoRa 433 MHz`* + ### Prerequisites - Python 3.x - pip (Python package manager) - Virtual environment (recommended) -### Setup +### Setup For Linux, MacOS, and Windows 1. Navigate to the application directory: - ```bash + ``` cd lora-scanner ``` 2. Create a virtual environment (optional): - ```bash + ``` python -m venv venv ``` -3. Activate the virtual environment: - - Windows: `venv\Scripts\activate` - - macOS/Linux: `source venv/bin/activate` +3. Activate the virtual environment (optional): + +- Windows: `venv\Scripts\activate` +- macOS/Linux: `source venv/bin/activate` + 4. Install the required packages: - ```bash + ``` pip install -r requirements.txt ``` ## Usage 1. Run the application: - ```bash - python app.py - ``` +```bash +python app.py +``` 2. Access the web interface at `http://localhost:5000`. -## API Endpoints -- `/` - Homepage -- `/analysis` - Analysis Page -- `/survey` - Survey Page -- `/tracking` - Tracking Page -- Additional endpoints for managing serial connections and data transmission. +![scanner-main](./doc/img/lora-main.png) + +## Analysis Mode + +Analyze LoRa traffic received at 433, 868, or 915 MHz with ‘Analysis Mode’. Click the desired frequency to get started. Once you are on the appropriate page, click the 'Connect Serial Port' button to connect to a serial port on your computer (the one your Feather is attached to). Once connected to your LoRa receiver, traffic will automatically be streamed to the web page for analysis. To disconnect a receiver, click the 'Disconnect Serial Port' button. + +![analysis-mode](./doc/img/analysis-mode.png) + +![connect-main](./doc/img/connect-main.png) + +![connect-port](./doc/img/specify-port.png) + +You can view and inspect any received packets from the analysis window in the appropriate section: + +![analysis-mode-2](./doc/img/analysis-mode-2.png) + +From analysis mode you can also transmit a message at the desired frequency using the ‘Transmit Data’ button. + +![transmit](./doc/img/transmit.png) + +## Tracking Mode + +Tracking mode allows you to track down rogue LoRa transmitters by locking in on a particular LoRa device and receiving live updates of their RSSI values. From the main tracking mode screen, click the row containing the LoRa transmitter you are searching for and it will lock in on that particular device for seamless tracking. + +![tracking-mode](./doc/img/tracking-mode.png) + +If you toggle the beacon buttons at the bottom of the screen, you will find a similar interface to the ‘Analysis Mode’ page. From this window you will be able to see live traffic received from the LoRa transceivers you have attached to the scanner. If you would like to beacon a message at a desired frequency, you can use the ‘Start Beacon’ and ‘Stop Beacon’ buttons. This will allow you to transmit a custom LoRa message at any desired interval , in an attempt to probe any LoRa devices that might be listening for messages: + +![transmit-interval](./doc/img/transmit-interval.png) + +## Survey Mode + +Survey mode allows you to view all of the devices and corresponding packets discovered by the LoRa scanner. + +![survey](./doc/img/survey-mode.png) + +From the main ‘Survey Mode’ screen, you can view plaintext messages that were successfully decoded by the LoRa scanner using the ‘Show Values’ button next to a desired LoRa device. After clicking the button, all of the messages captured from that particular device will be displayed. Each row represents a single message captured from that device. + +![survey-packets](./doc/img/survey-packets.png) + +To collapse the packet list, click the ‘Hide Values’ button. + +![survey-collapse](./doc/img/survey-collapse.png) + +## Exporting LoRa Traffic + +To download all packets captured by the LoRa Scanner, click the ‘Download Packets’ button. This will export all packets into a CSV file. + +![export-packets](./doc/img/download-packets.png) + +## LoRaWAN + +To capture LoRaWAN traffic, you have to connect to an active Dragino LPS8N Indoor LoRaWAN gateway (915 or 868 MHz). You can connect to your gateway from the main screen by entering in the IP address of the gateway. Currently the application allows you to simultaneously connect to three gateways at once. + +![gateway](./doc/img/lorawan-gateway.png) + +![gateway-config](./doc/img/lorawan-gateway-configure.png) diff --git a/doc/api.md b/doc/api.md deleted file mode 100644 index df7a5c9..0000000 --- a/doc/api.md +++ /dev/null @@ -1,123 +0,0 @@ -# Lora Scanner API Documentation - -The Lora Scanner is a Flask web application integrated with SocketIO for real-time communication, primarily focused on managing and processing serial data from various frequencies. The application's core functionality revolves around connecting to, managing, and disconnecting from serial ports, corresponding to three distinct frequency bands: 433 MHz, 868 MHz, and 915 MHz. This is achieved through routes that allow users to attach or delete serial connections for each frequency, with the backend handling the setup and teardown of these connections. Additionally, the application includes functionality to transmit data over these serial connections, facilitated by POST routes for each frequency. - -The app features a real-time data processing aspect, where it reads from serial ports in separate threads, extracts and processes the data using regular expressions, and stores this data in a structured format. The processed data includes signal strength and decoded values from raw serial data, which are then appended to a survey data structure for further use. SocketIO is employed to emit this serial data to the frontend, enabling real-time data streaming and display. The application also includes routes for transmitting data via the serial ports, and a route to check the status of each serial port. - -The Flask application provides several web pages for user interaction, rendered through specific routes. These include the main dashboard, analysis, survey, and tracking pages, each serving different aspects of the application, like displaying initial data from serial buffers and the global dataframe. The app also features a WebSocket event for handling connections, ensuring initial serial data is emitted to connected clients. Overall, the `app.py` file presents a comprehensive web application designed for real-time serial data communication and processing, with a user-friendly interface for monitoring and interacting with connected devices across different frequencies. - -Each route description includes the HTTP method used (GET or POST), a brief description of what the route does, the expected parameters (if any), and the format of the response. This documentation is intended to help users understand how to interact with the application's API. - ---- - -#### 1. **Homepage** -- **Route:** `/` -- **Method:** `GET` -- **Description:** Renders the homepage. -- **Parameters:** None -- **Returns:** HTML content of the `index.html` page. - -#### 2. **Analysis Page** -- **Route:** `/analysis` -- **Method:** `GET` -- **Description:** Renders the analysis page with initial data from serial buffers. -- **Parameters:** None -- **Returns:** HTML content of the `analysis.html` page with initial serial buffer data. - -#### 3. **Survey Page** -- **Route:** `/survey` -- **Method:** `GET` -- **Description:** Renders the survey page. -- **Parameters:** None -- **Returns:** HTML content of the `survey.html` page with data from `global_dataframe`. - -#### 4. **Tracking Page** -- **Route:** `/tracking` -- **Method:** `GET` -- **Description:** Renders the tracking page with initial data. -- **Parameters:** None -- **Returns:** HTML content of the `tracking.html` page with initial serial buffer data. - -#### 5. **Attach Serial Port for 433 MHz** -- **Route:** `/attach_serial_433` -- **Method:** `GET` -- **Description:** Attaches a serial port for 433 MHz frequency based on user input. -- **Parameters:** `user_input` (string): Serial port to connect. -- **Returns:** JSON object with the result of the operation. - -#### 6. **Delete Serial Port for 433 MHz** -- **Route:** `/delete_serial_433` -- **Method:** `GET` -- **Description:** Disconnects the serial port for 433 MHz. -- **Parameters:** None -- **Returns:** JSON object indicating port disconnection. - -#### 7. **Attach Serial Port for 868 MHz** -- **Route:** `/attach_serial_868` -- **Method:** `GET` -- **Description:** Attaches a serial port for 868 MHz frequency based on user input. -- **Parameters:** `user_input` (string): Serial port to connect. -- **Returns:** JSON object with the result of the operation. - -#### 8. **Delete Serial Port for 868 MHz** -- **Route:** `/delete_serial_868` -- **Method:** `GET` -- **Description:** Disconnects the serial port for 868 MHz. -- **Parameters:** None -- **Returns:** JSON object indicating port disconnection. - -#### 9. **Attach Serial Port for 915 MHz** -- **Route:** `/attach_serial_915` -- **Method:** `GET` -- **Description:** Attaches a serial port for 915 MHz frequency based on user input. -- **Parameters:** `user_input` (string): Serial port to connect. -- **Returns:** JSON object with the result of the operation. - -#### 10. **Delete Serial Port for 915 MHz** -- **Route:** `/delete_serial_915` -- **Method:** `GET` -- **Description:** Disconnects the serial port for 915 MHz. -- **Parameters:** None -- **Returns:** JSON object indicating port disconnection. - -#### 11. **Transmit Data at 433 MHz** -- **Route:** `/transmit433` -- **Method:** `POST` -- **Description:** Transmits data via the 433 MHz serial port. -- **Parameters:** JSON payload with `user_input` (string). -- **Returns:** JSON object with the status of the transmission. - -#### 12. **Transmit Data at 868 MHz** -- **Route:** `/transmit868` -- **Method:** `POST` -- **Description:** Transmits data via the 868 MHz serial port. -- **Parameters:** JSON payload with `user_input` (string). -- **Returns:** JSON object with the status of the transmission. - -#### 13. **Transmit Data at 915 MHz** -- **Route:** `/transmit915` -- **Method:** `POST` -- **Description:** Transmits data via the 915 MHz serial port. -- **Parameters:** JSON payload with `user_input` (string). -- **Returns:** JSON object with the status of the transmission. - -#### 14. **Check Serial Port Status** -- **Route:** `/checkSer` -- **Method:** `GET` -- **Description:** Checks the status of a specified serial port. -- **Parameters:** `port` (string): Serial port to check. -- **Returns:** JSON object with the port status. - -#### 15. **Get Table Data** -- **Route:** `/get_table_data` -- **Method:** `GET` -- **Description:** Retrieves data for display in a table format. -- **Parameters:** None -- **Returns:** JSON object with survey data. - -#### 16. **WebSocket Connect** -- **Socket Event:** `connect` -- **Description:** Handles WebSocket connection and emits initial serial data. -- **Parameters:** None -- **Returns:** Emits initial serial data for each port. - diff --git a/doc/api.pdf b/doc/api.pdf deleted file mode 100644 index b15ee97..0000000 Binary files a/doc/api.pdf and /dev/null differ diff --git a/doc/img/analysis-mode-2.png b/doc/img/analysis-mode-2.png new file mode 100644 index 0000000..09b2386 Binary files /dev/null and b/doc/img/analysis-mode-2.png differ diff --git a/doc/img/analysis-mode.png b/doc/img/analysis-mode.png new file mode 100644 index 0000000..746ff0b Binary files /dev/null and b/doc/img/analysis-mode.png differ diff --git a/doc/img/connect-main.png b/doc/img/connect-main.png new file mode 100644 index 0000000..57d1519 Binary files /dev/null and b/doc/img/connect-main.png differ diff --git a/doc/img/download-packets.png b/doc/img/download-packets.png new file mode 100644 index 0000000..2946d2f Binary files /dev/null and b/doc/img/download-packets.png differ diff --git a/doc/img/lora-main.png b/doc/img/lora-main.png new file mode 100644 index 0000000..47557c3 Binary files /dev/null and b/doc/img/lora-main.png differ diff --git a/doc/img/lorawan-gateway-configure.png b/doc/img/lorawan-gateway-configure.png new file mode 100644 index 0000000..8a4c0ea Binary files /dev/null and b/doc/img/lorawan-gateway-configure.png differ diff --git a/doc/img/lorawan-gateway.png b/doc/img/lorawan-gateway.png new file mode 100644 index 0000000..95e91f5 Binary files /dev/null and b/doc/img/lorawan-gateway.png differ diff --git a/doc/img/specify-port.png b/doc/img/specify-port.png new file mode 100644 index 0000000..1281b41 Binary files /dev/null and b/doc/img/specify-port.png differ diff --git a/doc/img/survey-collapse.png b/doc/img/survey-collapse.png new file mode 100644 index 0000000..2419be8 Binary files /dev/null and b/doc/img/survey-collapse.png differ diff --git a/doc/img/survey-mode.png b/doc/img/survey-mode.png new file mode 100644 index 0000000..625a373 Binary files /dev/null and b/doc/img/survey-mode.png differ diff --git a/doc/img/survey-packets.png b/doc/img/survey-packets.png new file mode 100644 index 0000000..4411139 Binary files /dev/null and b/doc/img/survey-packets.png differ diff --git a/doc/img/tracking-mode.png b/doc/img/tracking-mode.png new file mode 100644 index 0000000..e22c7b5 Binary files /dev/null and b/doc/img/tracking-mode.png differ diff --git a/doc/img/transmit-interval.png b/doc/img/transmit-interval.png new file mode 100644 index 0000000..7b52950 Binary files /dev/null and b/doc/img/transmit-interval.png differ diff --git a/doc/img/transmit.png b/doc/img/transmit.png new file mode 100644 index 0000000..29e6f17 Binary files /dev/null and b/doc/img/transmit.png differ