Esp32-HID外设 iOS
请前往 HID 外设 页面查看完整的芯片选购、固件下载、烧录教程和视频教程。
iOS 暂时仅支持蓝牙固件，所有支持的芯片型号均可用于 iOS。
使用前准备
手机设置
使用HID之前,需要在iPhone上做一个设置:
- 开启辅助触控: 打开 设置 → 辅助功能 → 触控 → 辅助触控 → 打开开关
连接蓝牙鼠标后, 设置 → 辅助功能 → 指针控制 中会出现追踪速度滑块.
请保持默认值(中间位置),不要调整! 系统的校准参数是基于默认追踪速度计算的, 调整后点击位置会不准确.
第一次使用(配对)
第一次运行脚本时,手机上会弹出一个**"蓝牙配对请求"**的弹窗,点 "配对" 就行.
配好之后,以后再运行脚本就不用配对了,会自动连上.
- 配对弹窗只有在App前台时才会显示,如果看不到弹窗请切回App
- 配对成功后,千万别去蓝牙设置里点"忽略此设备",不然要重新配对
- 配对后屏幕上会出现一个小圆点(鼠标指针),这是正常的
- 也可以在系统蓝牙设置里直接配对,然后程序里直接连接
导入模块
from ascript.ios.esp32hid import BleDevice
校准调整(重要,请先阅读)
由于iOS使用相对鼠标,不同手机型号和iPad需要调整校准系数和偏移量才能精确点击.
iOS鼠标指针的移动存在加速曲线,1个HID单位并不等于1个屏幕像素. 不同设备(iPhone/iPad)、不同屏幕缩放比(@2x/@3x)的换算系数不同. 另外由于iPhone圆角屏的限制,鼠标归零后无法到达屏幕最左上角,存在一个偏移.
设置校准系数
调整鼠标移动的灵敏度. 数字越大,同样的指令鼠标移动越远. 不同设备的系数不同,需要分别调整.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| scale_x | float | - | 横向缩放比例 |
| scale_y | float | None | 纵向缩放比例,不填就和横向一样 |
参考值(默认追踪速度):
| 设备 | 校准系数 |
|---|---|
| iPhone (3x屏,如iPhone 14) | 约 2.05 |
| iPad (2x屏) | 约 1.60 |
# iPhone
device.set_calibration(2.05)
# iPad
device.set_calibration(1.60)
# X和Y分别设置
device.set_calibration(2.05, 2.00)
设置偏移量
调整鼠标归零后的起始位置. 因为圆角屏的原因,鼠标没法到达屏幕最左上角,会有一个偏移.
| 参数 | 类型 | 默认值 | 说 明 |
|---|---|---|---|
| offset_x | int | - | 横向偏移(像素) |
| offset_y | int | 0 | 纵向偏移(像素) |
参考值:
| 设备 | 偏移量 |
|---|---|
| iPhone 14 | (160, 0) |
| iPad | (35, 0) |
device.set_offset(160, 0) # iPhone
device.set_offset(35, 0) # iPad
如何找到自己设备的校准值
如果参考值不准确,可以按以下步骤手动校准:
- 先设一个大概的系数,运行
device.click(500, 500) - 观察鼠标实际点击位置和目标的差距
- 如果点太远了(超过目标),就把系数调小; 没到目标就调大
- 反复微调直到点击位置准确
- 偏移量的调整方法类似: 点击靠近左上角的位置(如
click(200, 200)),看是否偏移
快速上手
下面是一个最简单的例子:
from ascript.ios.esp32hid import BleDevice
# 创建设备(会自动获取屏幕信息)
device = BleDevice()
# 连接芯片(自动扫描、连接、登录,一步到位)
device.connect()
# 校准(根据你的设备型号设置,只需设置一次)
device.set_calibration(2.05) # iPhone
device.set_offset(160, 0)
# 点击屏幕上某个位置
device.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).
使用前请确保已设置正确的校准系数和偏移量,否则点击位置会不准确.
点击
点击屏幕上的某个位置. 这个方法会等点击完成才返回,所以可以放心连续调用.
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| 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()
高级设置
手动设置屏幕大小
一般会自动获取,不需要手动设置. 如果自动获取有问题,可以手动指定.
| 参数 | 类型 | 说明 |
|---|---|---|
| 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)
完整例子
iPhone 基本操作
from ascript.ios.esp32hid import BleDevice
import time
# 第一步: 创建设备并连接
device = BleDevice()
device.connect() # 自动扫描、连接、登录
# 第二步: 校准(根据你的设备调整,只需在脚本开头设置一次)
device.set_calibration(2.05)
device.set_offset(160, 0)
# 第三步: 回到桌面
device.home()
time.sleep(1)
# 第四步: 点击打开一个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()
iPad 基本操作
from ascript.ios.esp32hid import BleDevice
import time
device = BleDevice()
device.connect()
# iPad 的校准参数与 iPhone 不同
device.set_calibration(1.60)
device.set_offset(35, 0)
# 后续操作和 iPhone 一样
device.home()
time.sleep(1)
device.click(500, 500)
横屏模式
from ascript.ios.esp32hid import BleDevice
device = BleDevice()
device.connect()
device.set_calibration(2.05)
device.set_offset(160, 0)
# 切换到横屏模式
device.set_orientation(BleDevice.LANDSCAPE_LEFT)
# 横屏下的坐标(宽高互换)
device.click(1000, 300)
# 切回竖屏
device.set_orientation(BleDevice.PORTRAIT)