智能家居摄像头开发本地 HTTP API安卓离线构建

国内 TP-Link IPC 本地 API(tplink-ipc-local-api)

国内版 TP-Link 摄像头(TL-IPC 系列)的本地 API 协议与离线安卓构建,面向要开发/修复连接 App 的开发者

一、这个 skill 是做什么的

这个 skill 是为开发者准备的:当你要自己写程序或安卓 App 去连接"国内版 TP-Link 摄像头"(型号以 TL-IPC 开头,走的是本地局域网管理员账号直连、HTTP 端口 80,不是 Tapo/Kasa 云方案)时,它给出一套真实、可照抄的本地 API 协议。

它覆盖三件事:① 登录认证流程(3 步 HTTP POST,含 RSA 加密与最容易踩坑的 URL 编码);② 常用功能模块名(隐私遮蔽、移动侦测、声光报警的 get/set 接口);③ 离线安卓构建链路(不依赖 Android Studio GUI,用脚本一条龙编译出 APK)。

所有协议事实都锚定在真实的逆向源码上(toast-riot/TP-Link-Camera-API 与 xiaodong-lx/tplink-ipc-control),禁止臆造参数,所以本说明书里出现的每个字段、盐值、模块名都可与源码对齐。

二、什么时候用它

三、前置条件 / 准备

两种 TP-Link 摄像头认证完全不同,别套错:本项目是本地 TL-IPC(salt=TPCQ75NF2Y:,RSA 加密类型 "2");而 bingooo/hass-tplink-ipc 用的 security_encode(password,"RDpbLfCPsJZ7fiv",...) 那是 TP-Link 云/Kasa 方案,不能用于本地 TL-IPC 的登录。不过它的 get/set 模块名与本项目一致,可采信。
离线安卓构建依赖(仅当你要编译 APK):Git Bash 环境,依赖 C:/Program Files/Android/Android Studio/plugins/Kotlin/kotlinc 与 /AppData/Local/Android/Sdk,无需联网。

四、具体用法(步骤)

第 1 步:get_encrypt_info(拿 RSA 公钥和 nonce)

向 http://<ip>:80/ POST:

{"method":"do","user_management":{"get_encrypt_info":null}}

从响应里取 data.key(RSA 公钥 base64,注意是 URL-encoded 需先 unquote)、data.nonce、data.encrypt_type(列表,如 ["1","2"])。即使返回 HTTP 401 或非零 error_code,只要带有效 key+nonce 就要照常提取。

第 2 步:构造密码(关键,极易出错)

  1. pwd_md5 = MD5("TPCQ75NF2Y:" + password).upper() —— 盐值在前,结果取大写 hex。
  2. plainText = f"{pwd_md5}:{nonce}"。
  3. 用公钥做 RSA_encrypt(plainText)(PKCS1v15 padding),输出 base64。
  4. 🔴 关键一步:把 base64 结果做 url_quote 再放入 JSON!base64 里的 + 和 = 必须 URL 编码,否则摄像头会把 + 当空格、= 截断,导致 RSA 解密失败、持续报 -40401。

第 3 步:do/login 登录

{"method":"do","login":{ "username":"admin", "password":"<url_quote 后的 base64>", "passwdType":"md5", "encrypt_type":"2" }}

encrypt_type 必须是字符串 "2"(RSA),放在 login 对象内(不是顶层、不是数组 ["2"])。优先选列表里的 "2";不含 "2" 才退回 [0];列表为空兜底 "2"。登录成功后从顶层取 stok。

第 4 步:用 stok 调用功能模块(get/set)

所有设置请求 POST 到 http://<ip>/stok=<stok>/ds,body 形如 {"method":"get"|"set","<module>":{...}}:

功能模块名GET 示例SET 示例
隐私遮蔽lens_mask{"method":"get","lens_mask":{"name":["lens_mask_info"]}}{"method":"set","lens_mask":{"lens_mask_info":{"enabled":"on"}}}
移动侦测motion_detection{"method":"get","motion_detection":{"name":["motion_det"]}}{"method":"set","motion_detection":{"motion_det":{"enabled":"on","digital_sensitivity":"50"}}}
声光报警msg_alarm{"method":"get","msg_alarm":{"name":["chn1_msg_alarm_info"]}}{"method":"set","msg_alarm":{"chn1_msg_alarm_info":{"enabled":"on"}}}
命名雷区:隐私遮蔽是 lens_mask,不是 privacy_mask!这是最常见的错误。GET 响应里 enabled 是字符串 "on"/"off"(非布尔)。GET 的 name 数组元素就等于 SET 的子键名。

五、可直接照用的示例

你直接对 AI大模型或AI智能体 说:「我要写个程序连家里的 TL-IPC 摄像头 ,登录后把镜头遮蔽打开、移动侦测关掉。」

AI大模型或AI智能体 会:先给你完整的三步登录流程(get_encrypt_info → 用 salt TPCQ75NF2Y: 算 MD5+RSA+url_quote → do/login 拿 stok),再用 stok 拼出两条 set 请求:lens_mask 设 enabled:"on"、motion_detection 设 enabled:"off",并提醒你 encrypt_type 用字符串 "2" 且放在 login 内。

你直接对 AI大模型或AI智能体 说:「我的 App 登录一直报 -40401,密码应该没输错,怎么排查?」

AI大模型或AI智能体 会:按"真机测试前提"给你一张诊断清单——逐值打印 pwdHash、plainText 长度、enc(raw base64)、enc(url-quoted);若 raw 与 quoted 不同,说明 URL-quote 已生效;多半是 base64 里 +/= 没做 url_quote,或 encrypt_type 误用了数组 ["2"]。

进阶 / 可选:离线构建安卓 APK(项目 D:\android\tplink,纯命令行,不用开 Android Studio 界面):
# 在 Git Bash 中运行(依赖 Android 构建工具链) bash build_apk.sh clean && bash build_apk.sh # 输出:app/build/outputs/apk/release/app-release.apk

改版本号要同步三处:app/build.gradle.kts(versionCode/versionName)、app/src/main/res/values/strings.xml(app_version)、build_apk.sh(--version-code/--version-name)。

六、常见注意 / 避坑

七、相关 skill / 延伸

← 返回 SKILL 库