13 Termux:API 硬件调用：用命令行操控手机硬件

📚 Termux 无 Root 学习开发系列

阶段一：环境搭建与终端基础 ✅ 已完成

01-05 Termux 安装 → 包管理 → 文件管理 → Vim/tmux

阶段二：编程开发环境 ✅ 已完成

06-09 Python → C/C++ → Node.js → Git

阶段三：网络与远程操作 ✅ 已完成

10-12 SSH → 网络工具 → 网络代理

阶段四：Termux:API 与自动化

13 Termux:API 硬件调用（当前篇）

14 定时任务与自动化

阶段五至九共 14 篇，后续持续更新

读完本篇你将能：通过命令行调用手机摄像头拍照、获取 GPS 定位、读取传感器数据、发送短信、播放音频、弹出对话框——把手机变成一个可编程的硬件遥控器。

📑 本文目录

01Termux:API 概述与安装配置

02电池、传感器与设备信息

03定位与拍照

04通信功能

05网络与连接

06媒体与文件操作

07界面交互与进阶组合

前几篇你掌握了网络通信与代理配置。从本篇开始，我们换一个方向——不再向外连接远程服务器，而是向内操控手机本身的硬件。Termux:API 就是终端命令与 Android 硬件之间的"翻译官"：你说命令行语言，它翻译成摄像头、GPS、传感器、短信等硬件动作。

01 Termux:API 概述与安装配置

Termux:API 不是一个单独的工具，而是两个组件的组合：Termux:API App（Android 应用）负责调用硬件接口，termux-api 包（命令行脚本）负责在 Termux 中发送指令。两者通过 Unix socket 通信（v0.57+ 起取代了旧的 am broadcast 机制，速度更快、更可靠）。

当前版本：Termux:API App v0.53.0，termux-api 包 v0.59.0。安装分两步——先从 F-Droid 安装 App（不要用 Play Store 版，已停止更新），再在 Termux 中安装命令行包。

Bash

# Install CLI package (App from F-Droid first)
pkg install termux-api
# Verify: query battery status
termux-battery-status
# {"percentage":85,"temperature":32.5,"status":"charging","plugged":"ac"}

如果命令执行后无响应或超时，运行 termux-api-start 启动后台服务。首次调用涉及摄像头、定位、短信等功能时，Android 会弹出权限授权对话框，需手动点击"允许"。

不同 API 类别需要不同的 Android 权限，下表列出了各类功能及其所需权限：

功能类别	代表命令	所需权限
电池/传感器	termux-battery-status	无特殊权限
摄像头	termux-camera-photo	CAMERA
GPS 定位	termux-location	ACCESS_FINE_LOCATION
短信/电话	termux-sms-send	SEND_SMS / READ_SMS
通知	termux-notification	POST_NOTIFICATIONS (Android 13+)
麦克风	termux-microphone-record	RECORD_AUDIO

Android 14+ 对权限管控更严格，部分权限需在系统设置中手动授予（设置 → 应用 → Termux:API → 权限）。v0.55 修复了 termux-notification 和 termux-toast 在后台执行时挂起的问题，如果你遇到通知命令无响应，确认 App 版本不低于 v0.53.0。

02 电池、传感器与设备信息

安装完成后，我们先从最简单的硬件查询开始。电池状态是 Termux:API 的"Hello World"——不需要任何特殊权限，执行即可返回 JSON。

Bash

# Get battery percentage only

termux-battery-status | jq '.percentage'

# 85

# List available sensors

termux-sensor -l | jq '.sensors | length'

# 12

# Sample accelerometer data

termux-sensor -s "BMI160 Accelerometer" -n 3

termux-sensor 的 -n 参数指定采样次数，不指定则持续采样直到手动停止。加速度计返回的三轴数据（X/Y/Z）单位是 m/s²，静止时 Z 轴约等于 9.81（重力加速度）。

除了传感器查询，Termux:API 还能直接操控设备：设置剪贴板内容、朗读文字、发送通知、控制震动和手电筒。这些功能不需要复杂权限，是日常自动化的利器。

Bash

# Clipboard + TTS + notification
termux-clipboard-set "Hello from Termux"
termux-tts-speak "Hello from Termux"
termux-notification --title "Backup" --content "Done"
# Vibrate + flashlight
termux-vibrate -d 500
termux-torch on & sleep 3 & termux-torch off

termux-tts-speak 调用 Android 系统的 TTS 引擎，手机会发出语音朗读传入的文字。termux-notification 会在状态栏推送一条系统通知，v0.51 起支持 --icon 参数设置通知图标（内置 950+ 图标可选）。

💡 小贴士

所有返回 JSON 的 API 命令都可以通过管道传给 jq 提取字段。例如 termux-battery-status | jq '{battery: .percentage, temp: .temperature}' 只输出电量和温度。这种"API + jq"管道组合是后续所有进阶用法的基础。

03 定位与拍照

GPS 定位和摄像头拍照是 Termux:API 中最直观的硬件调用。前者获取地理位置，后者拍摄照片，两者组合可以记录"在哪里拍了什么"。

termux-location 支持三种定位提供器：-p gps（GPS 卫星定位，精度最高但耗电）、-p network（网络定位，速度快精度低）、-p passive（被动定位，其他 App 触发定位时才返回数据，最省电）。

Bash

# Get GPS location
termux-location -p gps | jq '{lat: .latitude, lon: .longitude}'
# {"lat": 31.2304, "lon": 121.4737}
# Take photo with rear camera
termux-camera-photo -c 0 ~/storage/shared/photo.jpg
# Take photo with front camera
termux-camera-photo -c 1 ~/storage/shared/selfie.jpg

-c 0 表示后置摄像头，-c 1 表示前置摄像头。照片默认保存为 JPEG 格式，文件路径必须是绝对路径，推荐保存到 ~/storage/shared/（共享存储）便于在相册中查看。

💡 小贴士

GPS 定位的 accuracy 字段表示精度（单位米），数值越小越精确。室内 GPS 信号弱时精度可能降到 50 米以上，此时切换 -p network 可能更快获得结果。持续 GPS 采样耗电量大，脚本中建议获取一次后立即退出。

04 通信功能

Termux:API 可以直接调用手机的通信硬件——发送短信、拨打电话、读取通话记录。这些功能涉及敏感权限（SEND_SMS、CALL_PHONE、READ_SMS），Android 14+ 首次调用时会弹出授权对话框。

Bash

# Send SMS
termux-sms-send -n 10086 "Query balance"
# Read latest 5 SMS
termux-sms-list -l 5 | jq '.[] | {number: .number, body: .body[:20]}'
# Make a phone call
termux-telephony-call 10086

termux-sms-list 的 -l 参数限制返回条数，-o 指定偏移量（分页读取）。v0.56 修复了 termux-sms-list 参数处理的 bug，确保使用最新版本。

⚠️ 常见错误

termux-sms-send -n 10086 "Hello" — 报错：Permission denied

✓ 修复：进入系统设置 → 应用 → Termux:API → 权限 → 短信 → 允许。Android 14+ 需在运行时动态授权，首次调用会弹窗，点击"允许"即可。如果权限窗口不弹出，执行 termux-sms-send 触发权限请求。

05 网络与连接

第 11 篇你学会了用 curl 和 ss 查看网络信息，但那是在 Termux 内部。Termux:API 提供了直接查询 Android 系统网络状态的能力——WiFi 连接信息、扫描附近 WiFi、查看基站信息和 USB 设备列表。

Bash

# WiFi connection info
termux-wifi-connectioninfo | jq '{ssid: .ssid, ip: .ip}'
# {"ssid": "MyHomeWiFi", "ip": "192.168.1.105"}
# List USB devices
termux-usb -l
# [{"vendor_id":"1234","product_id":"5678","device_name":"USB Storage"}]

termux-wifi-scaninfo 返回附近所有 WiFi 热点的 SSID、BSSID、信号强度（rssi）和频率。termux-usb 配合 -r 参数可以请求 USB 设备访问权限，v0.57 起支持通过 vendorId 和 productId 指定设备。

termux-telephony-deviceinfo 返回设备 IMEI、SIM 卡状态、运营商等信息。注意：Android 10+ 限制了非系统应用读取 IMEI，termux-telephony-deviceinfo 可能返回空值。

06 媒体与文件操作

Termux:API 的媒体能力覆盖音频播放、麦克风录音、文件下载和系统分享——让你的脚本不仅能读数据，还能产生多媒体内容和与系统交互。

Bash

# Play audio file

termux-media-player play ~/storage/shared/music.mp3

termux-media-player stop

# Record 5 seconds of audio

termux-microphone-record -d 5000 -f ~/storage/shared/record.mp3

# Download + share files

termux-download https://example.com/file.pdf

termux-share -a send ~/storage/shared/photo.jpg

termux-media-player 支持 play（播放）、pause（暂停）、stop（停止）三个子命令，底层调用 Android MediaPlayer。termux-microphone-record 的 -d 参数单位是毫秒，-f 指定输出文件路径，默认录制为 MP3 格式。

termux-download 调用 Android 系统下载管理器，文件下载完成后出现在通知栏和 Downloads 目录。termux-share 通过系统分享菜单将文件或文本分享到其他 App（微信、QQ、邮件等），-a send 表示发送操作，-a view 则是用系统默认应用打开文件。

07 界面交互与进阶组合

前面六章按功能分类逐个演示了 API 命令。本章把多个命令组合成实用脚本——这才是 Termux:API 的真正威力所在。先看几个界面交互命令，它们能在脚本运行时与用户对话。

Bash

# Dialog: get user input
NAME=$(termux-dialog -t text --title "Enter name" | jq -r '.text')
# Fingerprint authentication
termux-fingerprint | jq '.status'
# Set screen brightness (0-255)
termux-brightness 128

termux-dialog 弹出一个 Android 原生输入对话框，返回 JSON 格式 {"text":"用户输入","code":0}。用 jq -r '.text' 提取纯文本。支持多种对话框类型：-t text（文本输入）、-t number（数字输入）、-t password（密码输入）。

下面是一个综合脚本——获取 GPS 定位、拍摄照片、推送带位置信息的通知，并将日志保存到共享存储：

Bash

#!/data/data/com.termux/files/usr/bin/bash

# Capture location + photo + save metadata

TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Get GPS coordinates

LAT=$(termux-location -p gps | jq '.latitude')

LON=$(termux-location -p gps | jq '.longitude')

# Take photo with rear camera

termux-camera-photo -c 0 ~/storage/shared/photo_${TIMESTAMP}.jpg

# Send notification with location info

termux-notification --title "Photo Captured" --content "Lat: $LAT, Lon: $LON"

# Log to file

echo "${TIMESTAMP},${LAT},${LON}" >> ~/storage/shared/photo_log.csv

这个脚本演示了"API + jq + 变量 + 管道"的经典组合模式：termux-location 输出 JSON → jq 提取经纬度 → 存入变量 → termux-camera-photo 拍照 → termux-notification 推送结果。shebang 必须使用 Termux 完整路径 #!/data/data/com.termux/files/usr/bin/bash，不能简写为 #!/bin/bash。

再看一个电池监控脚本——每 60 秒轮询电池状态，电量低于 20% 时自动推送通知告警：

Bash

#!/data/data/com.termux/files/usr/bin/bash

# Poll battery level, alert when low

LOGFILE="$HOME/storage/shared/battery_monitor.csv"

echo "timestamp,pct,temp,status" > "$LOGFILE"

while true; do

DATA=$(termux-battery-status)

PCT=$(echo "$DATA" | jq '.percentage')

STATUS=$(echo "$DATA" | jq -r '.status')

echo "$(date +%H:%M:%S),$PCT,$STATUS" >> "$LOGFILE"

if [ "$PCT" -lt 20 ]; then

termux-notification --title "Low Battery" --content "${PCT}%"

fi

sleep 60

done

这个脚本每次循环执行一次 termux-battery-status，用 jq 提取电量和状态，写入 CSV 日志文件。电量低于 20% 时推送通知。注意：长时间运行的后台脚本需要配合 termux-wake-lock 防止屏幕关闭后 CPU 休眠导致脚本暂停。

💡 小贴士

长时间运行 Termux:API 轮询脚本时，在脚本开头加 termux-wake-lock 保持 CPU 唤醒，结尾加 termux-wake-unlock 释放。在电池设置中将 Termux 设为"不受限制"可避免后台被杀。下一篇将介绍 cron 定时任务和 Termux:Widget，实现更优雅的定时调度。

✏️ 动手练习

🟢 基础验证

执行 termux-battery-status，用 jq 提取电量和温度，将结果输出到终端。预期：5 分钟内完成。

🟡 组合应用

编写脚本：用 termux-dialog 获取用户输入的通知内容，用 termux-tts-speak 朗读一遍，再用 termux-notification 推送系统通知。需要组合 3 个 API 命令和 jq 解析。预期：10 分钟。

🔴 开放挑战

编写一个"防盗拍照"脚本：用 termux-sensor 检测加速度计数据变化（如手机被移动），触发时立即调用 termux-camera-photo 拍照，并通过 termux-notification 推送告警。提示：需要设定加速度阈值，持续轮询传感器数据，检测到异常时触发拍照。可能需要 30 分钟以上。

📖 知识回顾

Termux:API 安装电池与传感器 GPS 定位摄像头拍照短信与电话 WiFi 与 USB 媒体播放与录音剪贴板与通知对话框与指纹 jq 管道组合权限管理

下篇预告

14 定时任务与自动化：cron 定时、Widget 快捷方式与开机自启

将学习如何在 Termux 中配置 cron 定时任务、使用 Termux:Widget 在桌面创建一键执行脚本、配合 Termux:Boot 实现开机自动启动服务