Esp32-HID外设 iOS
请前往 HID 外设 页面查看完整的芯片选购、固件下载、烧录教程和视频教程。
iOS 暂时仅支持蓝牙固件，所有支持的芯片型号均可用于 iOS。
本模块为 HID 模式专用，需要 ESP32 硬件。WDA 模式下请使用 action 模块。
使用前准备
手机设置
使用HID之前,需要在iPhone上做一项设置:
开启辅助触控: 设置 → 辅助功能 → 触控 → 辅助触控 → 打开开关
不开启辅助触控,鼠标指针能移动但点击无效. 这是 iOS 系统的要求,开启后即可,无需调整追踪速度或灵敏度.
第一次使用(配对)
第一次运行脚本时,手机上会弹出一个**"蓝牙配对请求"**的弹窗,点 "配对" 就行.
配好之后,以后再运行脚本就不用配对了,会自动连上.
- 配对弹窗只有在App前台时才会显示,如果看不到弹窗请切回App
- 配对成功后,千万别去蓝牙设置里点"忽略此设备",不然要重新配对
- 配对后屏幕上会出现一个小圆点(鼠标指针),这是正常的
- 也可以在系统蓝牙设置里直接配对,然后程序里直接连接
导入模块
from ascript.ios.esp32hid import BleDevice
快速上手
开启辅助触控后,连接即用,无需校准,无需调整追踪速度或灵敏度:
from ascript.ios.esp32hid import BleDevice
# 创建设备(会自动获取屏幕信息)
device = BleDevice()
# 连接芯片(自动扫描、连接、登录,一步到位)
device.connect()
# 点击屏幕上某个位置(物理像素坐标)
device.click(642, 1389)
# 双击
device.double_click(642, 1389)
# 按Home键回到桌面
device.home()
connect()不传参数时,会自动扫描并连接第一个 AS_ 开头的设备- 也可以指定设备名:
device.connect("AS_iOS_XXXX") - 连接成功后会自动登录,不需要手动调
login() - 脚本多次运行时,如果上次的连接还在,会自动复用,速度很快
连接相关
创建设备
创建一个HID设备对象,会自动读取手机屏幕大小.
device = BleDevice()
扫描设备
搜索附近的ESP32芯片,返回找到的设备名称列表.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| timeout | float | 5.0 | 搜索时间,单位秒 |
devices = device.scan(timeout=5)
print(devices) # ['AS_iOS_8CD0CA63B0E4']
连接设备
连接并自动登录. 不传参数会自动扫描连接 第一个 AS_ 开头的设备.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| device_name | str | None | 芯片的蓝牙名称,不传则自动发现 |
| timeout | float | 15.0 | 连接超时时间,单位秒 |
# 自动发现并连接
device.connect()
# 或指定设备名
device.connect("AS_iOS_8CD0CA63B0E4")
断开连接
手动断开蓝牙连接. 一般不需要调用,连接会自动保持.
device.disconnect()
检查连接状态
判断当前是否已连上芯片.
if device.is_connected():
print("已连接")
点击和滑动
所有坐标都是屏幕物理像素坐标,左上角是原点(0, 0).
5.0 版本采用绝对定位方案,无需调整iOS追踪速度或灵敏度,连接即用.
点击
点击屏幕上的某个位置. 这个方法会等点击完成才返回,所以可以放心连续调用.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x | int | - | 横坐标(物理像素) |
| y | int | - | 纵坐标(物理像素) |
| duration | int | 100 | 按住多长时间,单位毫秒 |
device.click(642, 1389) # 点击一下
device.click(200, 300) # 点另一个位置
device.click(500, 800, 200) # 按住200毫秒再松开
双击
在同一位置快速点击两次. 两次点击的间隔在芯片内部完成,不受蓝牙通信延迟影响.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x | int | - | 横坐标(物理像素) |
| y | int | - | 纵坐标(物理像素) |
| interval | int | 80 | 两次点击间隔(毫秒),默认80ms |
device.double_click(642, 1389) # 双击,默认80ms间隔
device.double_click(642, 1389, 50) # 更快的双击
触摸
低层触摸方法,点击指定像素坐标. 与 click 不同的是,touch 不会阻塞等 待完成.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x | int | - | 横坐标(物理像素) |
| y | int | - | 纵坐标(物理像素) |
| duration | int | 100 | 按住多长时间,单位毫秒 |
device.touch(642, 1389)
长按
长按屏幕上的某个位 置,默认按住1秒.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x | int | - | 横坐标(物理像素) |
| y | int | - | 纵坐标(物理像素) |
| duration | int | 1000 | 按住多长时间,单位毫秒,默认1秒 |
device.long_click(500, 800) # 长按1秒
device.long_click(500, 800, 2000) # 长按2秒
滑动
从一个位置滑动到另一个位置. 可以设置滑动速度和缓动效果.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x1 | int | - | 起点横坐标(物理像素) |
| y1 | int | - | 起点纵坐标(物理像素) |
| x2 | int | - | 终点横坐标(物理像素) |
| y2 | int | - | 终点纵坐标(物理像素) |
| duration | int | 300 | 滑动时间(毫秒) |
| easing_mode | int | 0 | 缓动模式,见下表 |
| easing_power | int | 0 | 缓动力度(2=二次方, 3=三次方) |
缓动模式(让滑动更自然):
| 值 | 效果 | 说明 |
|---|---|---|
| 0 | 匀速 | 从头到尾速度一样 |
| 1 | 先慢后快 | 起步慢,越来越快 |
| 2 | 先快后慢 | 起步快,慢慢停下来 |
| 3 | 两头慢中间快 | 起步慢,中间加速,结尾减速 |
# 从上往下滑
device.swipe(642, 800, 642, 1800, 500)
# 带缓动效果的滑动(先快后慢,更自然)
device.swipe(642, 800, 642, 1800, 500, easing_mode=2, easing_power=3)
向上滑
快捷方法,从屏幕中下方往上滑.
device.swipe_up()
device.swipe_up(500) # 慢一点,滑500毫秒
向下滑
快捷方法,从屏幕中上方往下滑.
device.swipe_down()
向左滑
快捷方法,从右往左滑.
device.swipe_left()
向右滑(返回上一页)
快捷方法,从左往右滑. 在iOS上相当于返回上一页.
device.swipe_right()
检查是否正在拖拽
判断当前是否有滑动/拖拽操作正在进行.
if device.is_dragging():
print("正在滑动中...")
按键操作
按Home键
回到手机桌面.
device.home()
按返回键
模拟返回操作. iOS上部分App可能不响应这个键,可以用 swipe_right() 代替.
device.back()
按回车键
相当于键盘上的回车.
device.enter()
打开最近应用
相当于双击Home键,打开多任务界面.
device.recent()
全选复制
先全选(Cmd+A),再复制(Cmd+C). 适用于输入框里有文字的场景.
device.copy()
粘贴
把剪贴板里的内容粘贴出来(Cmd+V).
device.paste()
清空输入框
先全选,再删除. 可以快速清空输入框.
device.clear()
输入文字
通过模拟键盘一个字一个字地打出来. 只支持英文和数字等ASCII字符.
| 参数 | 类型 | 说明 |
|---|---|---|
| text | str | 要输入的文字(仅支持英文/数字/符号) |
device.print_text("hello world")
键盘输入
另一种输入文字的方式.
| 参数 | 类型 | 说明 |
|---|---|---|
| text | str | 要输入的文字 |
device.keyboard_write("hello")
按下按键(不释放)
按住一个键不松开,需要配合 keyboard_release_all() 使用.
| 参数 | 类型 | 说明 |
|---|---|---|
| text | str | 要按下的按键字符 |
device.keyboard_press("a") # 按住 a 键
import time; time.sleep(1)
device.keyboard_release_all() # 松开
释放所有按键
如果之前有按键没松开,可以用 这个方法全部释放.
device.keyboard_release_all()
发送组合键
同时按下修饰键和普通键,比如Cmd+A.
| 参数 | 类型 | 说明 |
|---|---|---|
| modifier_hex | str | 修饰键的HID编码(16进制),填"0"表示没有修饰键 |
| key_hex | str | 按键的HID编码(16进制) |
# Cmd+A (全选)
device.key("E3", "04")
设备管理
获取芯片ID
获取ESP32芯片的唯一识别码.
chip_id = device.get_id()
print(chip_id)
查看设备状态
看看芯片是否已经登录并正常运行.
if device.state():
print("设备正常")
改蓝牙名称
给芯片改个名字. 改完后芯片会自动重启.
| 参数 | 类型 | 说明 |
|---|---|---|
| new_name | str | 新名字,最长30个字符 |
device.set_name("我的芯片")
恢复默认名称
把蓝牙名称改回出厂默认. 改完后芯片会自动重启.
device.reset_name()
重启芯片
重启ESP32芯片.
device.restart()
高级设置
偏移微调
微调点击偏移,单位为物理像素. 大多数情况下不需要设置.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| offset_x | int | 0 | 横向偏移(物理像素,正=右移,负=左移) |
| offset_y | int | 0 | 纵向偏移(物理像素,正=下移,负=上移) |
# 如果点击总是偏右10像素、偏下20像素:
device.set_offset(-10, -20)
同步光标坐标系
横竖屏切换后,iOS 系统的鼠标坐标系可能不会立即同步,导致点击位置不准. 调用此方法可修复,耗时约 3-5 秒.
如果App的录屏扩展正在运行,横竖屏切换时会自动检测并同步,一般不需要手动调用.
device.sync_cursor()
手动设置屏幕大小
一般会自动获取,不需要手动设置. 如果自动获取有问题,可以手动指定.
| 参数 | 类型 | 说明 |
|---|---|---|
| width | int | 竖屏时的屏幕宽度(物理像素) |
| height | int | 竖屏时的屏幕高度(物理像素) |
device.set_screen_size(1284, 2778)
横屏使用说明
横屏下坐标使用方式和竖屏完全一样,直接传当前屏幕方向的物理像素坐标即可.
由于 iOS 系统的限制,横竖屏切换后鼠标的坐标系可能不会立即同步,导致点击位置不准.
解决方法:
- 自动同步: 确保App的录屏扩展正在运行,切换时会自动同步
- 手动同步: 调用
device.sync_cursor()(需等待 3-5 秒重连) - 避免平放: 手机不要完全平放在桌面上,稍微倾斜让重力感应能识别当前方向
from ascript.ios.esp32hid import BleDevice
device = BleDevice()
device.connect()
# 横屏下直接使用截图坐标点击
device.click(1500, 400)
# 如果切换方向后点击不准,同步坐标系
device.sync_cursor()
device.click(1500, 400)
完整例子
基本操作
from ascript.ios.esp32hid import BleDevice
import time
# 第一步: 创建设备并连接
device = BleDevice()
device.connect() # 自动扫描、连接、登录
# 第二步: 回到桌面
device.home()
time.sleep(1)
# 第三步: 点击打开一个App
device.click(500, 800)
time.sleep(2)
# 第四步: 双击某个元素
device.double_click(500, 600)
time.sleep(1)
# 第五步: 在输入框里打字
device.click(642, 400) # 先点一下输入框
time.sleep(0.5)
device.print_text("hello") # 打字
device.enter() # 按回车
# 第六步: 往下滑一滑看看
device.swipe_down(500)
time.sleep(1)
device.swipe_down(500)
# 第七步: 返回上一页
device.swipe_right()