Esp32-HID外设 ios版
什么是HID动作,啥时候使用HID?
我们可以把HID简单理解为给iOS 手机配一个 "可控鼠标"+"可控键盘"
- 换句话说:我们用esp32芯片虚拟了一个,ios鼠标键盘外设,并且可通过指令控制该外设.
在部分自动化中,WDA点击不可用时.
Esp芯片支持与固件刷入
本部分主要讲,如何准备芯片,如 何给芯片刷入固件
-
芯片:需自行购买
-
固件:免费提供
芯片获取
- 您需要根据已支持的型号,自行购买芯片
- 如果没有您的芯片型号,请加入官方Q群,联系管理员免费编译.
| 已支持芯片型号 | 芯片图样 | 蓝牙固件 | usb固件 | 购买途径 | 均价 |
|---|---|---|---|---|---|
| esp32-c3 |  | ✅ | ❌ | 某宝/某鱼 | 9元/个 |
| esp32-pico |  | ✅ | ❌ | 某宝/某鱼 | 17元/个 |
| esp32-s3 |  | ✅ | ✅ | 某宝/某鱼 | 20元/个 |
| 其他型号可联系官方编译 |
固件下载
使用前准备
手机设置
使用HID之前,需要在iPhone上做两个设置:
- 开启辅助触控: 打开 设置 → 辅助功能 → 触控 → 辅助触控 → 打开开关
- 把追踪速度调到最慢: 打开 设置 → 辅助功能 → 指针控制 → 追踪速度 → 把滑块拖到最左边
第一次使用(配对)
第一次运行脚本时,手机上会弹出一个**"蓝牙配对请求"**的弹窗,点 "配对" 就行.
配好之后,以后再运行脚本就不用配对了,会自动连上.
- 配对成功后,千万别去蓝牙设置里点"忽略此设备",不然要重新配对
- 配对后屏幕上会出现一个小圆点(鼠标指针),这是正常的
导入模块
from ascript.ios.esp32hid import BleDevice
快速上手
下面是一个最简单的例子,扫描设备、连接、登录、点击:
from ascript.ios.esp32hid import BleDevice
# 创建设备(会自动获取屏幕信息)
device = BleDevice()
# 扫描附近的芯片
devices = device.scan(timeout=5)
print("找到设备:", devices)
# 连接到你的芯片(把名字换成你自己的)
device.connect("AS_iOS_XXXX")
# 登录
device.login()
# 点击屏幕上某个位置
device.click(642, 1389)
# 按Home键回到桌面
device.home()
脚本多次运行时,如果上次的连接还在,会自动复用,不会重新扫描和配对,速度很快.
连接相关
创建设备
创建一个HID设备对象,会自动读取手机屏幕大小和校准参数.
device = BleDevice()
扫描设备
搜索附近的ESP32芯片,返回找到的设备名称列表.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| timeout | float | 5.0 | 搜索时间,单位秒 |
devices = device.scan(timeout=5)
print(devices) # ['AS_iOS_8CD0CA63B0E4']
连接设备
连接到指定名称的芯片. 如果之前已经连着了,会自动复用,不会重复连.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| device_name | str | - | 芯片的蓝牙名称 |
| timeout | float | 15.0 | 连接超时时间,单位秒 |
device.connect("AS_iOS_8CD0CA63B0E4")
登录
连接成功后必须先登录,才能发送其他指令. 如果之前已经登录过且连接还在,会自动跳过.
device.login()
断开连接
手动断开蓝牙连接. 一般不需要调用,连接会自动保持.
device.disconnect()
检查连接状态
判断当前是否已连上芯片.
if device.is_connected():
print("已连接")
点击和滑动
所有坐标都是屏幕像素坐标,左上角是原点(0, 0).
系统会自动处理不同手机的屏幕差异. 由于iPhone圆角屏的限制,屏幕最左上角一小块区域(约160像素)鼠标到不了,系统会自动移到最近的位置.
点击
点击屏幕上的某个位置. 这个方法会等点击完成才返回,所以可以放心连续调用.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| x | int | - | 横坐标(像素) |
| y | int | - | 纵坐标(像素) |
| duration | int | 100 | 按住多长时间,单位毫秒 |
device.click(642, 1389) # 点击一下
device.click(200, 300) # 点另一个位置
device.click(500, 800, 200) # 按住200毫秒再松开
长按
长按屏幕上的某个位置,默认按住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()
按键操作
按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")
释放所有按键
如果之前有按键没松开,可以用这个方法全部释放.
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()
校准微调
系统会根据你的手机型号自动计算校准参数,一般不需要手动调. 如果发现点击位置有偏差,可以用下面的方法微调.
微调缩放比例
调整鼠标移动的灵敏度. 数字越大,同样的指令鼠标移动越远.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| scale_x | float | - | 横向缩放比例 |
| scale_y | float | None | 纵向缩放比例,不填就和横向一样 |
怎么校准:
- 确保iOS追踪速度已调到最慢
- 运行
device.slide(100, 0, 100, 0, 100) - 看鼠标从左上角水平移动到了哪里,记下横坐标 ax
- 用
device.set_calibration(ax / 100)设置比例
device.set_calibration(2.36)
微调偏移量
调整鼠标归零后的起始位置. 因为圆角屏的原因,鼠标没法到达屏幕最左上角,会有一个偏移.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| offset_x | int | - | 横向偏移(像素) |
| offset_y | int | 0 | 纵向偏移(像素) |
device.set_offset(160, 0)
手动设置屏幕大小
一般会自动获取,不需要手动设置. 如果自动获取有问题,可以手动指定.
| 参数 | 类型 | 说明 |
|---|---|---|
| width | int | 竖屏时的屏幕宽度(像素) |
| height | int | 竖屏时的屏幕高度(像素) |
device.set_screen_size(1284, 2778)
设置屏幕方向
如果你的App是横屏运行的,需要告诉系统当前的屏幕方向.
| 值 | 说明 |
|---|---|
| BleDevice.PORTRAIT | 竖屏(默认) |
| BleDevice.LANDSCAPE_LEFT | 横屏,Home键在右边 |
| BleDevice.LANDSCAPE_RIGHT | 横屏,Home键在左边 |
| BleDevice.PORTRAIT_UPSIDE | 竖屏倒过来 |
# 切换到横屏模式
device.set_orientation(BleDevice.LANDSCAPE_LEFT)
# 切回竖屏
device.set_orientation(BleDevice.PORTRAIT)
完整例子
下面是一个完整的自动化脚本示例:
from ascript.ios.esp32hid import BleDevice
import time
# 第一步: 连接芯片
device = BleDevice()
device.scan(timeout=5)
device.connect("AS_iOS_8CD0CA63B0E4")
device.login()
# 第二步: 回到桌面
device.home()
time.sleep(1)
# 第三步: 点击打开一个App(坐标根据你手机上App的位置来)
device.click(500, 800)
time.sleep(2)
# 第四步: 在输入框里打字
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()