Vijtus/empatica-e4-local
GitHub: Vijtus/empatica-e4-local
一个用于从 Empatica E4 手环离线读取原始传感器数据的工具，解决数据隐私和云依赖问题。
Stars: 1 | Forks: 0
# Empatica E4 智能手环 — 读取您自己的数据
从您拥有的 Empatica E4 手环读取原始传感器数据——
加速度计、皮肤温度、皮肤电活动（EDA/GSR）
以及原始光电容积脉搏波。**无需云端、无需账户、无需固件写入。** 支持在 Linux、macOS 和 Windows 上离线运行。
## 30秒开始使用
1. 将手环戴在手腕上。
2. 短按手环按钮，直到 LED 灯变为**蓝色**。
3. 在此文件夹中打开终端，输入：
* **Linux / macOS：** `./START`
* **Windows：** 双击 `START.bat`，或在 cmd 中输入 `START.bat` / 在 PowerShell 中输入 `.\START.bat`
就这样。程序会录制 5 分钟，然后将您的数据保存为 CSV 文件，您可以在 Excel / LibreOffice / pandas / R 中打开。
## 系统要求
* **Python 3.11 或更新版本**（否则启动程序将拒绝运行）。
* 蓝牙已开启：
* Linux：BlueZ（在 Debian/Ubuntu 上运行 `sudo apt install bluez`）。
* macOS：系统设置中的蓝牙。
* Windows 10+：设置 → 设备 → 蓝牙。
首次运行会在 `_engine/.venv/` 下创建一个 Python 虚拟环境，并安装 `bleak` + `pyusb`（约 40 MB，约 30 秒）。之后每次运行都直接启动程序。
## 此文件夹内容
```
START → Linux / macOS launcher (./START)
START.bat → Windows launcher (START.bat or double-click)
START.py → the cross-platform launcher both of the above call
README.md → this file
recordings/ → all your wristband data, one folder per session:
recordings/2026-05-15_14-09-15/
├── raw.sqlite the truth source (BLE packets)
├── raw.jsonl same data, JSON-lines
├── session.log what happened during recording
└── csv/ Excel-friendly files (open these)
help/ → guides if you get stuck
_engine/ → program code (ignore unless you're coding)
_trash/ → debloated stuff. delete any time: rm -rf _trash/
LICENSE → MIT
```
## 更多按钮
```
./START → record 5 minutes (the normal thing)
./START find → just find your wristband, don't record
./START check → check Bluetooth and setup
./START report → re-print the summary of your latest recording
./START make-csv → re-make the CSV files for your latest recording
./START --help → all options
```
（在 Windows 上，请将 `./START` 替换为 `START.bat`。）
您可以指定特定的录制：
```
./START report --db recordings/SOME_FOLDER/raw.sqlite
./START make-csv --db recordings/SOME_FOLDER/raw.sqlite
```
技术别名仍然有效：`scan` = 查找，`doctor` = 检查，`stream` = 录制，`decode` = 生成 CSV，`summary` = 报告。
## 录制文件夹 `csv/` 中的内容
| 文件 | 说明 |
|---|---|
| `acc.csv` | 3轴加速度计。32 Hz。`x_g, y_g, z_g` 单位为 g。 |
| `temp.csv` | 皮肤温度，单位为 °C。4 Hz。 |
| `gsr.csv` | 皮肤电活动（皮肤电导，原始计数）。4 Hz。 |
| `ppg.csv` | 光学脉搏传感器，原始 12 位计数。64 Hz。数据打包方式暂定——保留 `packet_hex` 用于重新解码。 |
| `bat.csv` | 电池读数（每会话数据极少）。 |
| `unknown.csv` | 任何我们尚未标记的数据。 |
完整列参考：**`help/02_what_is_in_your_data.md`**。
## 隐私
您的录制包含生物识别数据。`recordings/` 文件夹仅保存在您的笔记本电脑上——此程序不会上传任何内容。
`.gitignore` 会排除 `recordings/`，使其不被任何 git 提交包含。
## 如果出现问题
```
./START check (or START.bat check on Windows)
```
此操作会测试蓝牙和程序设置，并告知您问题所在。如果无法找到手环，请再次按下按钮使 LED 灯变为蓝色。
## 底层工作原理
`help/03_how_we_decoded_the_wristband.md` 记录了对 E4 的 GATT 服务的逆向工程，流式启动序列（从官方 Empatica Android SDK 恢复），以及我们目前已知的通道数据包布局。所有内容均已通过手腕佩戴的抓包数据验证，并附有引用。
## 许可证
MIT — 详见 `LICENSE`。此仓库中的代码为原创作品。
## 免责声明
此项目**与 Empatica Srl 无关、未经其认可或赞助**。"Empatica" 和 "E4" 是其各自所有者的商标，在此处仅用于指称此工具读取的手环硬件。此项目不与任何 Empatica 服务器通信、依赖或交互。
对设备公共 BLE GATT 接口的逆向工程受美国版权法（DMCA §1201(f)）和欧盟法律（《软件指令》2009/24/EC 第6条）的互操作性条款保护。
有关我们用作参考的公共材料的引用，请参见 `_engine/e4local/references/README.md`；我们**不**重新分发任何 Empatica 二进制文件。
标签：CSV数据, Empatica E4, JSONL数据, Python, Python虚拟环境, SQLite数据库, 个人健康数据, 二进制发布, 传感器数据读取, 健康监测, 光电容积描记图, 内核监控, 加速度计, 命令控制, 开源工具, 数据记录, 数据采集, 无云, 无后门, 智能手环, 生物传感器, 生理信号处理, 电活动, 皮肤温度, 离线数据, 蓝牙低功耗, 蓝牙连接, 跨操作系统支持, 逆向工具