# macless-haystack
**Repository Path**: ynzheng/macless-haystack
## Basic Information
- **Project Name**: macless-haystack
- **Description**: 制作自己的AirTag
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 59
- **Created**: 2025-04-24
- **Last Updated**: 2025-04-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Macless-Haystack 中文版
该项目的目标是
- 1、DIY 兼容 FindMy 网络的定位标签/设备
- 2、运行 FindMy 网络，而无需拥有 Mac 电脑或虚拟机，也不需要拥有 iPhone 与其上面的查找 app 即可查看您 DIY 的定位标签/设备的位置（注册 Apple-ID 时需要借用一下别人的 iPhone）。
## 目录
- [Macless-Haystack 中文版](#macless-haystack-中文版)
- [目录](#目录)
- [安装](#安装)
- [先决条件](#先决条件)
- [硬件设置](#硬件设置)
- [服务器设置](#服务器设置)
- [前端应用程序](#前端应用程序)
- [Home Assistant 集成](#home-assistant-集成)
- [问题 / 争议 / 疑问](#问题--争议--疑问)
- [包含的项目和变更](#包含的项目和变更)
- [截图](#截图)
- [Android](#android)
- [网页](#网页)
- [贡献](#贡献)
- [免责声明](#免责声明)
## 安装
在本节中，您将找到有关如何设置自己的 Macless-Haystack 网络的分步指南。
硬件DIY有点门槛，如果你不想自己动手，可以咸鱼搜索 “自制定位标签”（用户名 lovelyelfpop），我会不定时上架一些成品，但仍然需要你自己搭建服务。
如果你已经有了成品定位标签，可以参考此简要使用说明 [成品使用教程](./read/ProductUsage.md)。
否则，请往下一步步跟着我从零开始吧。
1. 先决条件
### 先决条件
- 会**魔法上网**。本教程很多东西需要去 github 等地方下载文件。
- 有 **Linux 服务器**（任意Linux均可）。
用来运行 Docker 服务和 Python 脚本。
- 已启用 2FA (双重认证)的 **Apple-ID**。
强烈建议不要使用个人常用的 Apple ID，而是注册一个新的 Apple ID 用于实验目的。
没有 Apple ID 的 可以找朋友借用一下苹果设备（iPad、Macbook、iPhone），注册一个。
- 仅支持短信方式作为双重认证！
- 如果有苹果设备登录着该 Apple ID，最好退出，否则有可能收不到短信验证码。
- 您需要在苹果设备上登录过该帐户才可以（获得了 iCloud 的 5G 免费空间或登录过 Apple Music 才是有效的 Apple ID）。仅在 iCloud 网页上注册的 Apple ID 权限不足。
- ST17H66 系列芯片的廉价蓝牙防丢 iTag 或 nRF51/nRF52系列芯片的 iBeacon
- 蓝牙防丢 iTag
拼夕夕9块钱左右，但是现在很少有 ST17H66 的芯片了。不建议大家购买。
- nRF5x 蓝牙信标
价格比较贵，推荐阿里巴巴采购，最便宜的也要20左右(加邮费)。需要从商品页面详情获取或向商家询问蓝牙信标电路板上 SWCLK/SWDIO 引脚的位置
- nRF5x 蓝牙模块
这个比蓝牙信标便宜，特别是闲鱼上两三块钱一个。模块体积小可以做出的定位标签也小。但是模块引脚太小要考验焊工，另外还需要网上找相应模块资料或询问卖家，找出 VCC/GND/SWCLK/SWDIO 四个引脚。最后成品如何接电池需要自己处理。
- nRF52810 PCB打样
有同学在嘉立创分享了 [nRF52810 信标 PCB 设计图](https://oshwhub.com/bitshen/lan-ya-xin-biao-findmy_copy_copy)，可以自己打样、焊接元件，成本非常低，但是自己焊元件难度很大。
- 电烙铁、焊锡丝；ST-LINK V2编程器(用来给 nRF5x 刷固件) 或 USB转TTL刷机线/转接器(比如CH340，用来给 ST17H66 刷固件)；杜邦线若干
- 给 ST17H66 刷机需要另外准备一个 3.3V 电源（各种3.3V电源方案均可，比如 AMS1117 稳压板，要能支持超过500mA电流），因为USB转TTL提供的电流不够，不接外部电源大概率刷不成功
- Windows 电脑，用来刷机等操作
- Linux 已安装 [Docker](https://www.docker.com/)。
- 如果你有 Home Assistant 集成的需求(不知道是啥的就不用看这段了)，还要满足以下条件
- Home Assistant 安装有 mqtt 和 mqtt broker(比如 Mosquitto broker)。
- Linux 已安装 [Python3](https://www.python.org/) 和 [pip3](https://pypi.org/project/pip/)
- 下载或克隆本仓库到 Linux 的 `~/macless-haystack/` (`~` 代表 home 目录)，并执行 `pip3 install -r requirements.txt` 命令用于安装依赖包。
- 创建 `keys/` 目录
```bash
mkdir ~/macless-haystack/keys/
```
然后把 `XXXXXX.keys` 文件放到此目录下
---
2. 硬件设置
### 硬件设置
1. 下载刷机固件和刷机脚本
- ST17H66 芯片前往 [Lenze_ST17H66](https://github.com/biemster/FindMy/tree/main/Lenze_ST17H66) 下载所需固件(FindMy.hex)和刷机脚本(flash_st17h66.py)
- nRF5x 前往 [openhaystack-firmware](https://github.com/acalatrava/openhaystack-firmware/releases) 下载所需固件(nrf51_firmware.bin或nrf52_firmware.bin)
- [TLSR825X 芯片](https://github.com/biemster/FindMy/blob/main/Telink_TLSR825X/README.md)，比如米家温湿度计2(型号 LYWSD03MMC)也可以刷机成定位标签，但我没有尝试
2. 执行本仓库的 `python3 generate_keys.py` 来生成密钥对(在 `keys/` 目录下)。(注意: 必须安装依赖 `cryptography`. 用 `pip3 install cryptography` 命令安装)
Windows 或 Linux 下都可以执行。
3. 将固件刷入设备
这里说一下，`generate_keys.py` 可以指定参数 `python3 generate_keys.py -n 50` 来生成包含多个密钥的 keyfile，其中 50 就是个数，可以自己改。不指定则默认单个密钥，也就是定位标签运行过程中只有一个蓝牙 Mac 地址（密钥其实就是加密了的 Mac 地址），而多密钥就是定位标签可以定时更换 Mac 地址(称为滚动密钥，苹果 AirTag 就是这样)。
经过我的测试，如果单密钥的定位标签和某台 iPhone 每天都会在同一个地方相遇，第一天 iPhone 会报告标签的位置，后面一两天可能这台 iPhone 就不会报告标签的位置了，即使 iPhone 和定位标签这一两天内并不在一个地方。我猜这与密钥轮换有关，带密钥轮换机制的标签，其位置会被更频繁的上报，即位置更新更频繁，更能被精确定位。推荐使用多密钥的 keyfile。但是，密钥轮换会增加一定功耗。
刷机方法：
- [ST17H66](read/ST17H66.md)
ST17H66 目前为止能找到的固件都只支持单密钥。
- [nRF5x](read/nRF5x.md)
支持多密钥轮换。
---
3. 服务器设置
### 服务器设置
1. 在终端中执行以下命令，创建一个新的docker网络
```bash
docker network create mh-network
```
2. 安装 [Anisette Server](https://github.com/Dadoum/anisette-v3-server):
```bash
docker run -d --restart always --name anisette -p 6969:6969 --volume anisette-v3_data:/home/Alcoholic/.config/anisette-v3/ --network mh-network dadoum/anisette-v3-server
```
注意：首次执行该命令会自动从 docker 官方仓库拉取镜像，因国内网络环境的原因，需要设置镜像仓库。如下修改 docker 的配置文件`/etc/docker/daemon.json`（不存在就新建），增加 `registry-mirrors`：
```json
{
"registry-mirrors": [
"https://docker.hpcloud.cloud",
"https://docker.m.daocloud.io",
"https://docker.unsee.tech",
"https://docker.1panel.live",
"http://mirrors.ustc.edu.cn",
"https://docker.chenby.cn",
"http://mirror.azure.cn",
"https://dockerpull.org",
"https://dockerhub.icu",
"https://hub.rat.dev"
]
}
```
之后运行如下命令重启 docker 服务：
```bash
systemctl restart docker
# 或者
service docker restart
```
此时，镜像源应该生效了。可以用 `docker info` 命令验证，如果输出末尾有如下`Registry Mirrors`，说明镜像源配置成功了：
```
Registry Mirrors:
https://docker.hpcloud.cloud/
https://docker.m.daocloud.io/
https://docker.unsee.tech/
......
```
*如果配置未生效，拉取docker镜像还是出错，可能的原因：
1、Ubuntu 可能是因为你的docker是snap安装的，解决方法请移步 https://blog.csdn.net/lovelyelfpop/article/details/146802408
2、群晖 配置方法请移步 https://post.smzdm.com/p/ag82opxd/ 或 https://blog.csdn.net/Falleaves_Yu/article/details/120316411 或 https://wiki.slarker.me/basic/docker_mirrors.html*
镜像源配置生效后，继续执行上面安装 Anisette Server 的命令。
*要检测 Anisette 是否正常运行，可以浏览器打开 `http://服务器ip:6969`，如果能访问就说明正常；或者执行命令 `curl http://服务器ip:6969`，如果有输出`{"X-Apple-I-Client-Time":"202......`则正常。*
**如果你没有在安卓手机或网页端查看 Tag 标签定位的需求，就不用看下面的3、4步骤了。**
3. 启动 Macless Haystack 服务
运行下面命令启动 macless-haystack 服务：
```bash
docker run -it --restart unless-stopped --name macless-haystack-gitee -p 6176:6176 --volume mh_data:/app/endpoint/data --network mh-network lovelyelfpop/macless-haystack-gitee
```
启动服务时，系统会要求您输入 Apple ID、密码和两步验证短信验证码（注意如果 AppleID 是大陆手机号，前面要加上 +86）。
如果您看到命令行显示 `serving at port 6176 over HTTP` 则所有设置均正确。
*要检测 Macless Haystack 服务是否正常运行，可以浏览器打开 `http://服务器ip:6176`，如果页面显示`Nothing to see here`就说明正常；或者执行命令 `curl http://服务器ip:6176`，如果有输出`Nothing to see here`则正常。*
4. 立即开启另一个终端，执行下面命令重新启动服务器
```bash
docker restart macless-haystack-gitee
```
---
4. 前端应用程序
### 前端应用程序
**如果你没有在安卓手机或网页上查看 Tag 标签定位的需求，就不用看本节内容了。**
您可以使用 Atomgit 提供的前端 web 网站，也可以自己托管网站服务器；也可以使用 Android app。
另外，请自己去[高德开放平台](https://console.amap.com/dev/key/app)申请 web 服务 key(key 类型一定要是 ***Web服务***，申请是免费的)，在 app/web 网站的设置中需要填入。不填也可以用，但是只会显示位置坐标，不会显示中文地址描述。
- 安装/打开前端应用
- 安卓设备请安装 [apk](https://gitee.com/lovelyelfpop/macless-haystack/releases)
- 非安卓的设备(iOS/鸿蒙/PC)可使用浏览器打开网站(任选其一)
- [Atomgit Page(http)](http://lovelyelfpop.atomgit.net/macless_haystack_pages/)
- [Atomgit Page(https)](https://lovelyelfpop.atomgit.net/macless_haystack_pages/)
注意：
1、因浏览器限制，https 的网站只能访问 https 的后台服务。所以如果你选择使用 [Atomgit Page(https)](https://lovelyelfpop.atomgit.net/macless_haystack_pages/)，那么必须将 macless_haystack 服务部署为 https（需要 SSL 证书）。可以使用 nginx 等工具进行反代，也可以使用服务内置支持的 [SSL 使用方法](read/FAQ.md#%E5%A6%82%E6%9E%9C%E6%9C%8D%E5%8A%A1%E5%92%8C-ui-%E4%B8%8D%E5%9C%A8%E4%B8%80%E5%8F%B0%E6%9C%BA%E5%99%A8%E4%B8%8A%E8%BF%90%E8%A1%8C%E6%88%91%E8%AF%A5%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8-ssl)
2、访问 http 的地址，浏览器可能会自作主张转向 https 的地址，可以地址栏改成 http 再回车
- *可选: 如果需要iOS、Linux 或 Windows 客户端，可以自己打包（本项目前端基于 Flutter）*
- 点击前端应用程序(app 或 网站)右上角齿轮图标进入设置，填写 **高德web 服务 key** 和 **macless haystack 服务 url 地址**。其它设置项默认或按需设置。
- 回主界面，点"+"图标，选择"导入 json 文件"，将 `XXXXXX_devices.json` 文件导入前端应用程序内。
- 注意：
- 1、"高德web 服务 key" 如果不填，位置只会显示成经纬度，而不显示中文地址描述。
- 2、"macless haystack 服务 url 地址" 形如 `http://服务器ip:6176`。若要在公网使用，需将 macless haystack 服务公开到公网，可以用 路由器端口映射 或 内网穿透 的方式实现。具体操作不属于本文范畴，请自行搜索。
- 3、如果 app 获取位置报告时报错`未获取到位置。AppleID登录失效，请移除 auth.json 并重启 macless-haystack 服务`，请移步 [FAQ#重新注册/更改账户](read/FAQ.md#%E9%87%8D%E6%96%B0%E6%B3%A8%E5%86%8C%E6%9B%B4%E6%94%B9%E8%B4%A6%E6%88%B7)
- 4、部分国产安卓机因系统魔改，点"导入 json 文件"可能弹不出文件选择。可以安装 "File Manager Plus" 这个文件管理器([[GooglePlay]](https://play.google.com/store/apps/details?id=com.alphainventor.filemanager) [[Apkpure]](https://apkpure.com/file-manager/com.alphainventor.filemanager) [[百度]](https://www.baidu.com/s?wd=com.alphainventor.filemanager))，即可支持文件选择。
---
5. Home Assistant集成
### Home Assistant 集成
**如果你没有 Home Assistant 集成的需求(或者不知道是啥的)，就不用看本节内容了。**
此处利用了 OwnTracks 这个官方集成。
本服务的 `request_reports.py` 脚本运行之后，会通过 HA 的 mqtt 向 OwnTracks 发布消息。OwnTracks 收到消息之后会自动生成 device_tracker。
- Home Assistant 中添加集成 [OwnTracks](https://www.home-assistant.io/integrations/owntracks)
集成安装后，要在 `/homeassistant/configuration.yaml` 增加如下配置：
```yaml
# Example configuration.yaml entry
owntracks:
max_gps_accuracy: 200
waypoints: true
mqtt_topic: "owntracks/#"
events_only: false
```
- 把 `XXXXXX.keys` 文件放到 `~/macless-haystack/keys/` 目录下
- 编辑本仓库的 `settings.toml` 文件，填入你自己的 mqtt地址、用户名、密码 和 Tag 标签等信息（文件内有说明）
- 执行 `request_reports.py` 脚本。会要求你输入 Apple-ID、密码和两步验证短信验证码。
```bash
python3 ./request_reports.py
# 或者 仅获取过去12小时位置报告
python3 ./request_reports.py --hours 12
```
去 Home Assistant "设备与服务-实体"(或 OwnTracks 集成)中，应该可以看到 `tag` 开头的 device_tracker 了。
可以在墨澜地图中查看
- 最后，需要设置定时任务(比如Linux的cron)，比如每隔15分钟（建议不要太频繁）执行一次上面的 `python3 ./request_reports.py --hours 2`，这样位置才会定时更新。
- 注意
- 1：如果获取不到位置报告，建议拿着定位标签去人多的地方逛逛。
- 2：执行 `request_reports.py` 时如果报错 `401`，说明 `keys/auth.json` 登录失效，请删除该文件后重新执行，重新输入 AppleID 和密码即可
- 3: 以定时任务执行时，如果 `auth.json` 失效，希望能第一时间知晓，可以配置 `settings.toml` 文件内的"通知功能"部分，支持钉钉、企业微信等通知方式
---
Android 应用程序
### Android
网站
### 网页
