Photonicat 2 开发者 API

来自Photonicat Wiki
C2h2​（留言 | 贡献）2026年7月13日 (一) 00:47的版本 （New topic: developer overview of the REST + WebSocket API — auth, endpoint groups, error shape, quick examples）
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)
跳转到导航 跳转到搜索
适用 / Applies to Photonicat 1/2, pcat-manager-web（2026-07 起所有接口强制鉴权） / Photonicat 1/2, pcat-manager-web (auth enforced on all endpoints since 2026-07)

pcat-manager-web 管理界面的所有功能都基于一套 REST + WebSocket API，可用于脚本自动化和第三方集成（Home Assistant、监控面板、短信转发等）。本页是面向开发者的概览。注意：这是设备内部 API，版本间可能变动，升级固件后请回归测试你的集成。

Everything in the pcat-manager-web UI is driven by a REST + WebSocket API you can use for scripting and integrations (Home Assistant, monitoring dashboards, SMS forwarding…). This page is a developer-oriented overview. Note: this is the device's internal API and may change between releases — retest integrations after firmware updates.

基础 Basics

  • Base URL：设备地址，如 http://172.16.0.1/ / your device address, e.g. http://172.16.0.1/
  • 认证 Authentication：先 POST /login 建立会话（Cookie）；2026-07 起所有 API 强制登录校验。 / Establish a session via /login first; since 2026-07 every endpoint requires it.
  • 格式 Content type：POST 一律 application/json，并携带有效 CSRF token（登录页面/会话中获取）。所有改变状态的操作只接受 POST。 / POSTs use application/json with a valid CSRF token; all state-changing operations are POST-only.
  • 错误格式 Error shape（统一 / uniform）：
{ "status": "error", "message": "Descriptive error message", "error_code": "SPECIFIC_ERROR_CODE" }
HTTP 状态码：200 成功，400 参数错误，401 未登录，403 无权限/CSRF 失败，404 不存在。 / 200 OK, 400 bad request, 401 login required, 403 forbidden/CSRF, 404 not found.

接口分组 Endpoint groups

以下为主要分组及代表接口（完整字段见设备仓库 docs/api.md）。 / Major groups with representative endpoints (full schemas in the repo's docs/api.md).

分组 Group 代表接口 Representative endpoints 说明 Notes
系统 System GET /api/v1/system/board.json（设备信息 device info）、系统信息 system info、重启/关机 reboot & poweroff 型号、序列号、固件版本、运行时间 / model, serial, firmware, uptime
网络 Network 无线配置 wireless config、接口状态 interfaces、GET 已连接设备 connected devices WiFi SSID/密码、DHCP 客户端列表 / WiFi credentials, DHCP client list
蜂窝 Mobile APN 设置、调制解调器信息/配置 modem info & config 运营商、信号、IMEI、网络模式 / carrier, signal, IMEI, network mode
短信 SMS 列表 list、发送 send（v1/v2）、标记已读 mark-read、删除 delete、清空 clear 收发短信自动化的主要入口 / the main hook for SMS automation
语音通话 Voice call 拨打 make、接听 answer、挂断 hangup、状态 status、通话记录 history、音频通道 audio path 蜂窝版专属 / cellular models only
设备控制 Device control 电源 LED、蜂鸣器 beeper、设备设置 device settings 灯光/提示音策略 / LED & beeper policies
定时 Timer 时间信息、定时任务管理、车载模式 car boot mode 对应 /timer 页面的三种电源模式 / powers the /timer page modes
统计 Statistics 仪表盘数据 dashboard、状态 status、流量统计 data statistics 监控集成最常用 / most used for monitoring integrations
屏幕 Screen GET/POST /api/v1/screen/user_config.json、GET /api/v1/screen/data.json、GET /api/v1/screen/frame.png、custom_metrics 状态/执行 布局、数据、实时截屏 / layout, data, live frame capture
系统配置 System config CPU 调度 CPU scheduling、风扇转速 fan speed、屏幕短信条数限制 SMS screen limit 性能与散热调优 / performance & thermals
维护 Maintenance 固件管理 firmware management、软件包管理 package management、SMS Hook 管理 升级与短信钩子（转发脚本）/ upgrades & SMS hooks (forwarding scripts)

WebSocket（SocketIO）

实时事件走 SocketIO（连接根路径）。 / Real-time events use SocketIO at the root URL.

  • 客户端 → 服务器 Client → server：request_install（本地 IPK 安装 / local IPK install）、request_install_package（仓库安装 / repo install）、request_firmware_upgrade、get_firmware_upgrade_status_socket、cancel_firmware_upgrade（仅下载阶段可取消 / cancellable during download only）
  • 服务器 → 客户端 Server → client：log_response（实时日志 / live logs）、firmware_upgrade_status（含进度百分比 / with progress percentage）：
{ "status": "downloading", "progress": 45, "message": "Downloading firmware (45%)" }
  • 2026-07 起 WebSocket 连接同样需要已登录会话。 / Since 2026-07 the socket also requires an authenticated session.

快速上手示例 Quick example

# 登录拿会话 / log in for a session cookie
curl -c jar.txt -X POST http://172.16.0.1/login -d 'password=YOUR_PASSWORD'

# 读取设备信息 / read device info
curl -b jar.txt http://172.16.0.1/api/v1/system/board.json

# 抓一帧屏幕画面 / grab a live screen frame
curl -b jar.txt -o frame.png http://172.16.0.1/api/v1/screen/frame.png
提示 Tips
  • 写操作需附带 CSRF token；具体字段名以当前固件版本为准。 / State-changing calls need the CSRF token; field names follow your firmware version.
  • 不要在公网直接暴露管理端口；如需远程访问请走 VPN。 / Never expose the manager port to the internet; use a VPN for remote access.

Photonicat 2 管理界面新功能 (2026) ｜ Photonicat 2 小屏幕自定义

检索自“https://photonicat.com/index.php?title=Photonicat_2_开发者_API&oldid=918”