用户指南

---

1. Entrixy 是什么

Entrixy 是一套远程控制出入口的系统：道闸、门、大门、锁。控制方式有两种：

• BLE 控制器 ——通过蓝牙直接接收手机的指令并闭合继电器。既不需要服务器，也不需要互联网，因此在没有信号的地方照样能用；应用还能在您靠近时自动开启。
• 联网控制器 ——与服务器保持长连接，可从任何地方打开对象，而不限于近旁（ESP32、ESP8266 或树莓派）。驱动装置旁需要 Wi-Fi 和长供电。
• 电话号码 ——拨打控制器号码，或凭来电号码识别，打开大门或道闸。
• Webhook ——向第三方服务发送 HTTP 请求：智能家居、您 Wi-Fi 网络里的继电器、大门控制器的接口。

任何对象都可以分享给访客——家人、同事、快递员——并按期限、时段或位置条件加以限制。

更多功能：

• 靠近即自动触发——依据定位、BLE、连上家里的 Wi-Fi，或按时间表。
• 每次开启前用 PIN 码或生物识别确认。
• 每次开启都有记录，含发起人。
• 可与智能家居系统协同：Home Assistant、Shelly、Tasmota、ESPHome、OpenHAB。

---

2. 安装应用

应用以独立 APK 文件形式在站点分发 entrixy.com。目前尚未上架应用商店。

在 Android 手机上

1. 在手机上打开 entrixy.com/download/android 并点击“下载 APK”。
2. 等待下载完成，然后打开下载好的 entrixy.apk.
3. 若系统提示，请允许您的浏览器或文件管理器安装未知来源的应用。
4. 确认安装。
5. 首次启动时，应用会申请权限。各项权限的用途：

   权限	用途
   蓝牙（扫描与连接）	查找附近的控制器并发送开启指令
   地理位置	地理围栏自动化场景。在旧版 Android 上进行 BLE 扫描。
   后台定位	应用在后台时，靠近对象即触发
   相机	扫描访客钥匙的二维码
   通知	关于来电或待确认操作的提醒
   不受电池优化限制	避免省电策略杀死后台服务

安装完成后，应用会询问您以哪种身份使用：

• “我是机主” ——您拥有控制器，完成配对后可以把权限分享给其他人。
• “我收到了邀请” ——有人给您发来二维码或链接。扫一下，就获得了对方对象的权限。

---

3. 准备控制器

如果您已经有出厂预装 Entrixy 固件的成品控制器，可跳过本节，直接前往 绑定.

控制器默认工作在点动模式：把驱动装置或门锁上的一对触点短暂闭合（0.5–2 秒），效果与有人按下「开」按钮完全一样。

对于需要独立开／关输入或需要保持状态的驱动装置和门锁，还有 双稳态模式：控制器切换状态并记录下来——应用显示的是「已开／已关」，而不只是「已触发」。该模式在配置器里生成固件时选择。

以下都可用作控制器：

• 自行组装的开发板 ——一块 ESP32 开发板（S3 DevKit、经典 WROOM、C3 SuperMini 之类）外接继电器模块。最灵活的方案，但需要基本的焊接能力。
• 成品 Wi-Fi 继电器 带无源 NO/COM 干接点，刷入 Entrixy 固件。Shelly Plus 1 和 Shelly Plus 1PM 都合适——这类继电器带有额外的 Open 端子，正是为大门和车库自动化设计的。需要打开外壳，把 USB 转串口适配器接到板上的 UART 引脚。
• 无需刷写的成品 Wi-Fi 设备 配合原厂云、Tasmota 或 ESPHome，通过 Entrixy 的 Webhook 驱动。不需要 BLE，上手更简单，但耗电更高、响应更慢。详见 “集成”.

如果您自己搭建控制器，或者需要非标准引脚布局的固件，只需三步：

3.1 固件配置器

打开 entrixy.com/esp/ble/ — 这是固件参数表单。（在 entrixy.com/controller/ 会先让您在 BLE 与联网两种方案之间选择——这里我们走 BLE 路线。）

需要填写的内容 （表单分为若干部分）：

1. 1. 选择开发板。点选与您的板子对应的卡片（ESP32 DevKit、ESP32-S3 DevKit、ESP32-C3 SuperMini、成品 Shelly Plus 1 继电器、裸模块等）——型号、引脚和电平极性会自动填好。之后仍可手动修改。
2. 2. 开发板。ESP32 芯片型号——它决定了有哪些引脚可用。在 Chrome 或 Edge 中，「检测已连接的芯片」按钮可通过 USB 识别板子。
3. 3. 锁的类型. 弹簧锁 — 单次开启脉冲。 双稳态 ——两种位置（开与关分处不同引脚）；状态会被记录，并在应用中显示。
4. 4. 引脚与极性. 开启继电器引脚 ——继电器模块控制输入所接的 GPIO；其 NO/COM 触点接到驱动装置的 Open 端子。 脉冲期间电平 与 静默电平 （HIGH/LOW）：多数成品模块和 Shelly 的脉冲为 LOW、静默为 HIGH；直接用三极管开关时则相反。 脉冲时长 ——通常为 500–2000 毫秒。下方还有：配对按钮引脚（一般是板载 BOOT 键，GPIO0；长按可清除配对）和可选的 LED（没有就填 −1）。
5. 5. 供电与省电。BLE 周期参数： 广播周期 （控制器多久唤醒一次——数值越小响应越快，越大越省电）， 广播窗口时长, 连接保持时间, 绑定窗口 与 周期间的休眠 （10–20 秒——两节 AA 电池可用数月；填 0 表示不休眠，适用于 USB 供电）。
6. 6. 外部时钟（可选）。RTC 模块（DS3231、DS1307、PCF8563）及其 I2C 引脚——只有在给访客发放限时密钥时才需要。没有它可以跳过本节。

填好表单后，点击 “生成程序”.

• 首次生成约需 25–60 秒，视芯片而定。
• 如果已经有人用同样的参数编译过程序，它会直接从缓存中秒回。
• 生成完成后会出现按钮 “上传到控制器” （直接在浏览器里烧录）、「下载文件」和「在编辑器中打开」。

3.2 通过浏览器烧录

最简单的方式，无需安装额外软件。

1. 用 USB 将控制器连接到电脑。
2. 在配置器页面点击“上传到控制器”。
3. 浏览器会弹出 USB 设备选择框。从列表中选择您的控制器。
4. 页面上会出现过程日志：
   • 读取芯片信息（型号、MAC 地址）。
   • 从服务器下载固件。
   • 开始写入，进度条从 0 走到 100%。
   • 重启控制器。
5. 完成后控制器会自行重启，并开始运行新固件。

如果出现问题：

现象	解决办法
“不支持 WebSerial”	请在桌面版 Chrome 或 Edge 中打开页面
端口选择框中没有控制器	安装 USB-COM 驱动（CH340、CP210x）
长时间等待后出现 Failed to connect	按住板上的 BOOT（或 IO0）键，按一下 RESET，先松开 RESET，再松开 BOOT——这样就手动把控制器切到了引导加载模式
"Port is already open"	关闭 Arduino IDE、PuTTY、MicroPython 以及其他占用该端口的程序

3.3 刷写成品 Wi-Fi 继电器

带干接点的成品 Wi-Fi 继电器（Shelly Plus 1、Shelly Plus 1PM）出厂时装的是厂商固件。要实现不依赖云、也不依赖 Wi-Fi 的直连 BLE 控制，必须把它刷成 Entrixy 固件。

这类设备本就是为大门和道闸自动化设计的：带有一对无源 NO/COM 端子，可直接接到驱动装置的 Open 端子。外壳紧凑，继电器有认证，而且不像自制模块那样还要另配接线盒。

需要准备：

• 一个 USB 转串口适配器（CP2102、CH340、FTDI）。只需几美元。
• 四五根鳄鱼夹线或杜邦线。
• 一把打开外壳的螺丝刀。
• 如果您手上的是较新版本、引脚与公开资料不符，用万用表逐针量一下会很有帮助。

步骤：

1. 打开配置器 entrixy.com/esp/ble/。在「可改刷的成品 Wi-Fi 继电器」一节中，选择以您的继电器命名的预设。
2. 引脚设置会自动填好。它们取自公开的引脚数据库（templates.blakadder.com、devices.esphome.io），并已在常见版本上验证过。
3. 在配置器页面的「成品 Wi-Fi 继电器的 UART 接入」一节里找到您的型号，按接线说明操作。
4. 连接 USB 转串口适配器：TX 接设备的 RX，RX 接设备的 TX，GND 接 GND。设备可由适配器的 3.3 V 供电，或在断开市电的情况下用它自己的电源。
5. 让 ESP 进入引导加载模式（多数设备的做法是：上电瞬间把 GPIO0 接到 GND）。
6. 点击“生成程序”并等待完成。
7. 用「上传到控制器」，或在电脑上用 esptool 烧录。
8. 拆掉所有连线，合上外壳。给设备恢复正常的市电供电。
9. 该继电器会通过 BLE 显示为等待配对的设备。请按以下章节所述完成配对： 4. 绑定控制器.
10. 把设备市电侧的 NO/COM 端子与驱动装置的「开」按钮并联（典型端子对照表见配置器的「继电器与驱动装置的接线」一节）。

如果预设中没有您的型号：

1. 可在 templates.blakadder.com — Tasmota 模板的开放数据库。
2. 模板会列出主要元件的 GPIO： Relay1 = 继电器引脚， Button1 = 按键引脚， Led1 = 状态指示灯。
3. 请确认设备带有 NO/COM 输出端子（干接点）——没有它就无法驱动大门电机，只能给负载通断电。
4. 把查到的 GPIO 数值手动填进配置器表单。

3.4 用 esptool 手动烧录

如果 WebSerial 用不了（比如电脑较旧，或用的是手机），可以下载固件文件，改用 esptool 工具。

1. 在配置器页面点击「下载文件」，保存 .bin 文件。
2. 用 Python 安装 esptool：

   pip install esptool

3. 将控制器连接到电脑。
4. 执行烧录命令：

   esptool.py --chip auto --port /dev/ttyUSB0 \
     write_flash 0x0 entrixy-ble-XXXX.bin

   在 Windows 上，请把 /dev/ttyUSB0 改为 COM 端口（例如 COM3）。文件名请换成您自己的。地址 0x0 是正确的——我们的文件已经把引导程序、分区表和应用合并成了一个镜像。
5. 完成后拔下控制器再插上，新固件即可启动。

---

4. 将控制器与应用绑定

刷完固件后，控制器进入等待配对状态。此模式下它会广播 90 秒的「等待主人」信号。若这段时间内无人配对，它就转入无主人的普通模式。

1. 以机主身份打开应用。
2. 进入 设置 → “添加对象” → 类型“BLE”。
3. 应用开始搜索处于绑定模式的控制器。
4. 如果控制器已处于配对模式（刚刷完固件，或不久前按过配对键），它会出现在列表里。选中它即可。
5. 若没有出现，请按一下控制器上的配对键。指示灯会开始快速闪烁，应用中的列表随之刷新。
6. 应用会执行一次 ECDH 密钥交换，耗时几秒。此后这个控制器就归您了——在您复位它之前，别人无法与它配对。
7. 给对象起个名字（「院子道闸」「侧门」「储藏室门锁」）。可以选一个图标，也可以上传照片。

---

5. 对象

对象就是您想控制的东西。同一个用户可以有多个不同类型的对象：院子里的道闸（BLE 控制器）、运营方的号码（电话号码）、智能家居里的继电器（Webhook）。

5.1 BLE 控制器

通过上文「控制器配对」一节添加。在主界面上它显示为一张带状态指示的卡片：

• 灰色 ——空中信号里看不到控制器（超出 BLE 范围，或已关闭）。
• 橙色 ——能看到控制器，但您还没进入触发区（在已设置自动化的情况下）。
• 绿色 — 您已进入触发区域，正在开启。
• 灰色带绿色描边，标注“点击呼叫” — 刚刚触发过，点击可再次开启。

点击卡片即可直接开启对象，前提是您的安全设置允许。

5.2 电话号码

适用于拨号即可开启的大门和道闸。

1. 设置 → “添加对象” → 类型“呼叫”。
2. 输入运营方号码，或道闸控制器的号码。
3. 如果希望开门的通话短促（5–10 秒）且不通话，请设置「N 秒后挂断」。
4. 选择处理方式：
   • 直接拨号 — 由应用自动拨号。
   • 通知 ——访客会收到「是否开启？」的询问，由您本人确认，通话从您的手机拨出。

5.3 Webhook

用于对接任何接受 HTTP 指令的系统：智能家居、您 Wi-Fi 网络里的继电器、大门接口、IFTTT。

1. 设置 → “添加对象” → 类型“URL”。
2. 输入目标服务的 URL。
3. 选择 HTTP 方法：GET、POST、PUT。
4. 如有需要，添加请求头（Authorization、X-API-Key）。
5. 为 POST 或 PUT 提供请求体。
6. 选择模式：应用或服务器（详见第 8. Webhook).

---

6. 访客钥匙

访客密钥是发给他人的邀请，让对方能访问您的对象。访客用的是同一个 Entrixy 应用，只是身份为访客。

创建钥匙

1. 在主屏幕：访客 → 创建钥匙。
2. 填写接收者的名字（「快递员」「安娜」）。这个名字只有您在日志里看得到，访客看到的是另一个。
3. 勾选要授予权限的对象。可以是您名下对象的任意组合。
4. 为每个分享出去的对象设置自动化（地理围栏、时间表、BLE 区域）。您可以把设置锁死，让访客改不了；也可以给出默认值，允许访客放宽或收紧。
5. 保存后，钥匙会出现在访客列表中。

交付钥匙

密钥卡片提供了多种交给对方的方式：

• 二维码 ——对方用手机摄像头扫一下。当面交接时最快。
• 链接 ——已复制到剪贴板。可通过即时通讯、邮件或短信发送。对方点开链接，即会打开 Entrixy 应用（若已安装）并添加密钥。
• 文本 — 可以口述的简短激活码。

管理访客

「访客」一栏列出您发放过的密钥。对每一个您都可以：

• 更改访客可见的对象。
• 更改自动化规则。
• 更改显示名称。
• 彻底吊销密钥——访客立即失去权限。
• 查看状态：在线还是离线，以及上次使用的时间。

访客的事件记录

访客的每一次开启都会记入所有者的日志，并标注「访客：姓名」。即便访客当时无网、直接走 BLE 也一样——事件先存在访客手机上，一连上服务器就发送。

---

7. 自动化

任何对象都可以设置按条件自动触发。从对象菜单 → 自动化 进入。

7.1 地理位置

当您靠近地图上的某点时开启。

1. 在地图上放置该点（若您就站在对象旁，点「使用当前位置」）。
2. 设定半径——即触发的距离（院子一般 20–50 米，大型停车场 100–200 米）。
3. 保存。

触发逻辑：

• 在外圈——半径再加 250 米，但离该点绝不小于 300 米——卡片会变成橙色：您正在靠近，触发已就绪。
• 进入半径内即自动开启一次。卡片先闪绿，随后变为带绿色描边的灰色。
• 在您离开外圈之前不会再次触发。这样在该点附近走动时就不会反复开启。

7.2 Wi-Fi

当手机连上指定的 Wi-Fi 网络时开启。适合「我在家时，车一到就开门」这类场景。

1. 开启 Wi-Fi 规则。
2. 添加网络，应用会列出附近可用的网络。
3. 可以添加多个网络（比如家里和公司）。默认只要命中任意一个就触发。

7.3 时间

按一天中的时段和星期几作限制。可用来约束访客（「仅工作时间可用」），也可作为您自己自动化中的条件。

• 添加一个时间段：从某点到某点。一天可以有多个时间段。
• 勾选星期几。
• 可以创建多个不同的时间段，各自适用不同的日子。

7.4 BLE

依据控制器 BLE 信号的强弱触发。适合 GPS 不准的门锁和道闸——室内或地下车库。

• 设置触发半径（1 至 30 米）。
• 进入半径内，卡片变绿并自动开启。
• 在范围内但半径之外时，卡片为橙色。
• 只有离开范围后才会再次触发。

7.5 组合规则

可以同时启用多条规则，并选择它们如何组合：

• 或 （默认）——只要满足其中任意一条就触发。例如：「在家（Wi-Fi）或正在到达（地理围栏）」。
• 且 ——只有所有规则同时满足时才触发。例如：「工作时间（时间表）且在办公室（Wi-Fi）」。「且」模式下不会自动开启：卡片只是提示条件已满足，您可以点一下。

7.6 操作确认

可以要求每次开启前额外确认：

• PIN 码 — 在应用中输入的短数字码。
• 生物识别 ——指纹或人脸识别，走 Android 的系统对话框。
• 确认 ——一个简单的「是否开启？ 是／否」对话框。防止误触。

这些设置可以写进访客密钥里——比如要求访客输 PIN，而您自己不用。

---

8. Webhook 详解

Webhook 对象有两种工作模式。选哪一种，取决于由谁来发出 HTTP 请求：您的手机，还是我们的服务器。

8.1 应用模式

HTTP 请求由您手机上的应用发出。触发时——您点一下，或访客通过服务器请求——服务器给您的手机发信号，再由手机向目标地址发起请求。

何时选择：

• 目标服务位于您的局域网内（Shelly、Tasmota、智能家居继电器），从互联网访问不到。请求由您的手机在网内发出。
• 您不希望我们的服务器知道目标 URL。

限制： 此时您的手机必须在线。若手机关机或没有网络，Webhook 就发不出去。

8.2 服务器模式

由我们的服务器用自己的 IP 地址直接发出 HTTP 请求。此刻不需要您的手机。

请求体为带 HMAC 签名的 JSON：

{
  "action": "open",
  "object_id": 42,
  "timestamp": 1717075200,
  "nonce": "8f2a1c4b5e6d7f80",
  "signature": "a3b4c5d6e7f8..."
}

签名的计算方式：先构造字符串 timestamp.nonce.action.object_id 再计算 HMAC-SHA256(该字符串, webhook_secret)，然后与收到的 signature进行比对。若 |now − timestamp| 已超过 300 秒。完整格式和测试向量见 entrixy.com/webhook.

何时选择：

• 目标服务可从互联网访问（挂在公网地址上的 Home Assistant、云端接口、IFTTT）。
• 您希望手机关机时也能开启——比如按时间表，或应访客的请求。
• 目标服务要求请求带签名，以防外部伪造调用。

安全： 创建 Webhook 时您需要设置一个 webhook_secret。访客永远拿不到这个密钥，即使他们有该对象的权限。服务器会用它代您为请求签名。

超时： 若目标服务 15 秒内没有响应，服务器会关闭连接并返回错误状态。

---

9. 智能家居集成

网站上的 /integrations/ 目录里放着常见平台的现成配置。每份都带有自己的 README 和接线图。

平台	怎么做
Home Assistant	复制 configuration.yaml （取自该目录）。在 Entrixy 中新建一个服务器模式的 Webhook，地址填 https://your-ha/api/webhook/entrixy.
Shelly	在 Entrixy 中新建一个应用模式的 Webhook，地址填 http://shelly-ip/relay/0?turn=on。一个普通的 GET 调用：手机在您的家庭网络内发起请求。
Tasmota	与 Shelly 相同。地址： http://tasmota-ip/cm?cmnd=Power%20Toggle.
ESPHome	如果比起我们的 BLE 协议，您更喜欢 ESPHome 生态，可以用这套 ESP32 的替代固件。目录里有 YAML 配置示例。
OpenHAB	与 Home Assistant 类似。它通过规则接口接收 HTTP 请求。
curl	一个测试脚本。它接收我们的 JSON，校验 HMAC 签名并打印结果。可用于调试。
Flask	一个 Python 骨架，供您搭建自己的服务。它接收我们的 JSON 并校验签名。

---

10. 访客网页版

如果访客不想装 Android 应用，或者用的是 iPhone，可以使用网页版： entrixy.com/app/.

网页版支持：

• 通过电话号码和 Webhook 开启。
• 事件日志。
• 以 PWA 形式安装到主屏幕（通过浏览器的「安装应用」菜单）。

网页版 不支持:

• 直接操作 BLE 控制器（浏览器无法在所需层级访问蓝牙协议栈）。
• 后台定位自动化。
• 通过 FCM 发送的通知。

想要功能不受限制，访客最好还是装上 Android 应用。

---

11. 安全

与控制器之间的连接

首次配对采用 ECDH X25519。双方各自同时算出共享密钥——密钥本身从不经过空中传输。

每一条开启指令（FIRE）都用共享密钥和控制器预先下发的一次性随机数做 HMAC-SHA256 签名。监听空中信号也无法重放该指令——那个随机数已经作废。

访客权限

访客拿到的不是共享密钥，而是一枚由所有者签名、有效期有限（默认 24 小时）的令牌。控制器会校验所有者的签名和有效期——即便访客令牌外泄，过期后也就失效了。

只要所有者的配对关系还在，令牌就会通过服务器自动续期。所有者一旦吊销密钥，下一次续期便失败，访客随即失去权限。

应用与服务器之间的连接

所有连接都走 TLS（HTTPS 与 WSS）。用户数据——电话号码、对象名称和访客名称——在服务器上以端到端加密方式存放，没有您的密钥，连服务器的主人也读不了。

密码学细节详见文档 端到端加密架构.

服务器模式下的 Webhook

请求以 HMAC-SHA256 签名。您在服务器上设置的密钥绝不会交给客户端或访客。即使有人截获请求也无法重放，因为时间戳 300 秒后即失效——这条规则由目标服务来执行。

---

12. 常见问题与排查

看不到 BLE 控制器

1. 确认控制器已通电。指示灯应当在闪烁。
2. 确认手机的蓝牙已打开。
3. 如果开了省电模式，请对 Entrixy 关闭它。
4. 走近控制器，到一两米内——在信号边缘处容易掉线。
5. 如果控制器设了深度休眠（deep_sleep_wake_s > 0），它并非一直在广播——只在唤醒窗口里。请等 10–30 秒。

连续触发了好几次

多半是您正好站在触发区边缘，信号受干扰而忽强忽弱。可以这样做：

• 在自动化设置里把 BLE 区域的半径调小。
• 把控制器挪开，远离会屏蔽信号的金属物体。

访客说卡片是灰的，打不开

在您的「访客」一栏里查看该密钥的状态。可能的原因：

• 访客的令牌过期了——比如他的手机已超过 24 小时没联网。让访客打开应用并连上网络，令牌会自动续期。
• 您误吊销了密钥。重新建一个即可。
• 访客不在范围内——BLE 对象要求人就在控制器旁边。

应用自己退出了

为了省电，Android 会强行杀掉后台服务。要避免这一点：

• 打开「应用设置 → Entrixy → 电池」，选择「无限制」。
• 三星机型：在「设备维护」里把 Entrixy 加入「永不休眠的应用」。
• 小米和红米机型：允许 Entrixy 自启动。
• 华为机型：把它加入「受保护的应用」，并允许后台活动。

Webhook 到不了 Home Assistant

1. 检查 Webhook 设置里的地址。它必须完整——带 https:// 协议头，端口若非标准也要写上。
2. 确认 Home Assistant 可从外网访问（服务器模式），或可从家庭网络访问（应用模式）。
3. 触发时盯一下 Home Assistant 的日志——里面应当有这条入站请求的记录。
4. 检查路由器上的防火墙，看它是不是挡住了入站连接。

华为手机上收不到来电通知

推送依赖 Google FCM，而华为在没有 Google 服务的情况下用不了它。变通办法：让应用保持打开而不是最小化，或者用 BLE 配对和地理围栏来代替通知。

如何更新应用

在手机上打开 entrixy.com/download/android，把最新版直接覆盖安装。数据会保留。

当某次更新是强制的——比如关键安全修复——应用会在启动时弹出阻断式对话框。

如何删除账户和全部数据

打开应用 → 设置 → 删除账户。服务器上的一切会在 30 天内清除，这是隐私政策中写明的标准期限。

如需立即删除，请向隐私政策中给出的支持邮箱发送申请。

---

文档更新于 2026-05-30。若有不清楚之处，或您的场景没被覆盖，请写信至 hello@entrixy.com.