How koff75/wifi-position-tracker works
Project Type and Purpose
• This is a Node.js–based command-line toolkit (CLI) for geolocating WiFi BSSIDs via Apple’s undocumented location API.
• It provides two entry points:
• bssid-geolocator.js – core geolocation and comparison tool
• scan_and_map.js – Windows-only WiFi scanner + mapper
File Structure
• Top‐level files only (no nested directories):
• bssid-geolocator.js – main CLI for geolocating and comparing BSSIDs
• scan_and_map.js – wraps Windows netsh scan, invokes bssid-geolocator logic, and outputs KML
• bssid.proto – Protocol Buffer schema for Apple’s API
• README.md, LICENSE, .gitignore
• Patterns and architecture hints:
• CLI argument parsing & interactive UI (yargs, inquirer)
• Protocol-buffer encoding/decoding (protobufjs)
• HTTP transport (axios) to external Apple service
• Concurrency control (p-limit), retry/backoff, error handling
• Output modules: console, TSV, JSON, KML (xmlbuilder2)
Extract Architectural Insights from README
• Core workflow:
User input → CLI parser → Request builder → Apple API → Response processor → Output generator
• scan_and_map.js augments this by first retrieving SSIDs/BSSIDs via netsh (Windows), then pipelines them through the same core.
• Movement comparison: accepts a previous JSON, computes distances, filters, then includes movement metadata in JSON/KML.
a. Main Components
• CLI Frontend
– bssid-geolocator.js (flags, interactive mode)
– scan_and_map.js (Windows netsh wrapper)
• Input Sources
– User (stdin prompts via inquirer)
– BSSID list file (fs.readFile)
– Windows netsh scan output
– Previous JSON (for movement compare)
• Core Processing
– Argument Parser (yargs)
– Interactive UI (inquirer)
– BSSID Normalizer
– Protobuf Encoder/Decoder (protobufjs with bssid.proto)
– HTTP Client (axios) + concurrency manager (p-limit) + retry/backoff
– Response Sanitizer & Error Handler
– Movement Detection Engine (optional compare module)
• Output Generators
– Console Formatter (TSV table)
– JSON Writer
– KML Builder (xmlbuilder2)
• External Services
– Apple Location Services API
– Windows netsh command
b. Relationships & Data Flow
1. User or script invokes bssid-geolocator.js / scan_and_map.js
2. CLI Parser reads flags or launches interactive prompts
3. Input module loads BSSIDs (stdin, file, or netsh scan)
4. Core Processing loops over BSSIDs:
– Normalize MAC
– Encode request (protobuf)
– Send HTTP POST to Apple service (axios) under concurrency limits
– Handle errors and retries
– Decode response, extract lat/lon, hacc, timestamp, channel
5. Optional: If --compare is set, load previous JSON → Movement Detection → annotate moved BSSIDs
6. Output module formats and writes results → console, JSON, TSV, KML
7. scan_and_map.js: embeds step 3 by invoking netsh, parses results, then follows the same pipeline
c. Architectural Patterns & Principles
• Modular separation of concerns: parsing, processing, output
• Pipeline pattern for streaming BSSID data
• Concurrency control with p-limit to avoid rate-limit errors
• Retry with exponential backoff for resilience
• Stateless core processing functions for testability
d. Key Technologies & Libraries
• Node.js & npm (runtime)
• yargs (CLI arguments)
• inquirer (interactive)
• protobufjs + bssid.proto (message encoding)
• axios (HTTP)
• p-limit (concurrency)
• xmlbuilder2 (KML)
• iconv-lite (Windows charset conversion in scan script)