WiFiSense

🌐 简体中文 | 繁體中文 | English

WiFi空间智能感知引擎
Cross-platform WiFi Spatial Intelligence Engine

---

🎉 项目介绍

WiFiSense 是一款轻量级的跨平台WiFi空间智能感知工具，灵感来源于 GitHub Trending 项目 RuView。

🔥 核心价值

• 📡 实时信号监测 - 跨平台WiFi信号强度实时监控
• 📍 空间定位 - 基于信号强度的室内三角定位
• 👤 存在感测 - 通过信号变化检测人员存在
• 📊 覆盖分析 - WiFi信号覆盖热力图可视化
• ⚡ 零依赖 - 核心模块零外部依赖，即装即用

✨ 自研差异化亮点

1. 跨平台原生支持 - Windows/macOS/Linux 全平台兼容
2. 零依赖核心 - 核心功能无需安装任何第三方库
3. TUI/GUI双界面 - 支持终端界面和图形界面
4. 存在感知识别 - 独特的WiFi信号变化检测算法
5. 轻量级设计 - 单文件即可运行，占用资源极低

---

🚀 快速开始

📦 安装

# 方式一：pip安装
pip install wifisense

# 方式二：从源码安装
git clone https://github.com/gitstq/WiFiSense.git
cd WiFiSense
pip install -e .

# 方式三：直接运行（无需安装）
python3 main.py --help

📋 环境要求

• Python 3.8+
• 操作系统：Windows / macOS / Linux
• WiFi适配器（支持混杂模式）

🖥️ 基本使用

# 扫描WiFi网络
wifisense scan

# 获取当前连接
wifisense connected

# 实时监控模式（TUI界面）
wifisense monitor

# 存在感知识别
wifisense presence --duration 120

# 覆盖分析
wifisense analyze --width 20 --height 15

# JSON格式输出
wifisense scan --json

# 导出数据
wifisense export -o data.json

🎨 增强功能（可选）

安装增强依赖以获得更好的体验：

pip install -r requirements.txt

这将安装：

• rich - 彩色TUI界面
• numpy - 数值计算
• scipy - 科学计算
• matplotlib - 数据可视化

---

📖 详细使用指南

📡 扫描WiFi网络

# 基本扫描
wifisense scan

# JSON格式（便于程序处理）
wifisense scan --json

输出示例：

SSID                 MAC                信号      距离   质量         频道
--------------------------------------------------------------------------------
MyHome_WiFi          AA:BB:CC:DD:EE:FF   -45dBm   0.3m   🟢excellent     6
Office_Network       11:22:33:44:55:66   -58dBm   0.8m   🔵good          11
Guest_WiFi           77:88:99:AA:BB:CC   -72dBm   2.5m   🟡fair           1

👁️ 实时监控

# 启动TUI监控界面
wifisense monitor

# 调整更新间隔
wifisense monitor -i 1  # 每秒更新

界面预览：

┌─────────────────────────────────────────────────────────┐
│ WiFiSense - WiFi空间智能感知引擎 | 2024-01-15 14:30:25  │
├─────────────────────────────────────────────────────────┤
│  SSID                 MAC               信号    距离    │
│  MyHome_WiFi          AA:BB:CC:...       -45dBm  0.3m   │
│  Office_Network       11:22:33:...       -58dBm  0.8m   │
├─────────────────────────────────────────────────────────┤
│ 🟢 存在感测: 检测到存在 (置信度: 78%)                   │
│ ⚡ 按 Ctrl+C 退出                                       │
└─────────────────────────────────────────────────────────┘

👤 存在感知识别

# 校准后进行120秒监控
wifisense presence --samples 5 --duration 120

工作原理：

1. 首先在校准模式下采样（无人环境）
2. 然后检测信号强度变化
3. 当多个AP信号发生显著变化时，判断为有人员存在

📊 覆盖分析

# 分析10m x 10m区域的WiFi覆盖
wifisense analyze --width 10 --height 10

输出：

覆盖评分: 85.2%
良好覆盖率: 85.2%
检测到AP数: 8
分析区域: 10.0m x 10.0m

📈 信号质量分布:
   excellent : ████████ (5)
   good      : ███ (2)
   fair      : █ (1)

📍 位置估算（三角定位）

# 编辑代码配置AP位置
known_positions = {
    'AA:BB:CC:DD:EE:FF': (0, 0),      # AP1位置
    '11:22:33:44:55:66': (5, 0),       # AP2位置
    '77:88:99:AA:BB:CC': (2.5, 4),     # AP3位置
}

# 运行位置估算
wifisense position
# 输出: 📍 估算位置: (2.32, 1.85)

---

💡 设计思路

🏗️ 架构设计

WiFiSense
├── wifi_scanner.py      # 信号采集层
├── signal_processor.py  # 信号处理层
├── config.py            # 配置管理层
├── cli.py               # 命令行接口
├── tui.py               # TUI界面
└── main.py              # 主入口

🔬 技术选型

组件	选型	原因
核心语言	Python 3.8+	跨平台、生态丰富
信号采集	系统API	零依赖、直接调用系统命令
UI框架	Rich/TUI	现代化终端体验
可视化	Matplotlib	灵活的数据绑定

📐 核心算法

1. 距离估算：使用对数路径损耗模型

   RSSI = TX_POWER - 10 * n * log10(d)
   

2. 三角定位：加权质心算法

   • 多AP信号强度加权
   • 实时位置估算

3. 存在感测：信号变化检测

   • 基线建立
   • 滑动窗口分析
   • 异常检测

---

🔮 迭代规划

v1.1.0 (规划中)

• 支持更多平台特性
• 增强存在感测精度
• 添加信号历史记录

v1.2.0 (规划中)

• GUI图形界面
• Web控制台
• 多设备协同

v2.0.0 (长期)

• 机器学习增强定位
• 实时热力图生成
• 开放API

---

📦 打包与部署

🐧 Linux

chmod +x build.sh
./build.sh

🍎 macOS

chmod +x build.sh
./build.sh

🪟 Windows

build.bat

☁️ Docker (可选)

FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["wifisense", "monitor"]

---

🤝 贡献指南

我们欢迎各种形式的贡献！

• 🐛 报告问题
• 💡 提出建议
• 🔧 提交代码

请查看 CONTRIBUTING.md 了解更多。

---

📄 开源协议

本项目基于 MIT 协议开源。

---

Made with ❤️ by gitstq