Snapdragon Spaces 开发指南(1)
1 入门
1.1 Snapdragon Spaces 概述
Snapdragon Spaces SDK开发者包可以从Snapdragon Spaces 开发者门户下载 (打开新窗口)。下载 Unity 或 Unreal Engine 的最新版本。
开发人员包以 zip 存档形式提供,其中包括:
- 申请Snapdragon Spaces Services。
- 使用所选引擎制作的示例应用程序。
- Unity 软件包包含 Snapdragon Spaces Unity 软件包的 tarball。
- 虚幻引擎包包含示例存档和虚幻引擎插件。
- SDK 下载中包含其他手势跟踪包。
请继续阅读以下页面来设置设备并了解如何在支持的硬件上运行 Spaces 应用程序。
1.2 硬件设置
1.2.1 联想 ThinkReality A3 开发套件
本指南适用于连接到 Lenovo ThinkReality A3 设备的 motorola Edge 30 pro 和 motorola Edge+ 手机。
首次使用 A3 套件之前,motorola Edge 30 pro (motorola edge+) 需要保持最新状态,并且必须从 Lenovo ThinkReality Cloud 安装多个必需的应用程序。手机在 ThinkReality Cloud 上注册后,这些应用程序将自动安装。最后还需要更新玻璃固件;一旦完成以下步骤,此时它也会自动安装。
第 1 步:拆箱并设置手机
按照标准 Android 步骤设置手机并将其连接到可访问互联网的 Wi-Fi 网络。
第 2 步:下载所有系统更新
设置手机后,请访问Settings -> System updates -> Check for updates以确保已下载并安装强制更新。运行 Snapdragon Spaces 应用程序的最低要求是 Android 版本 12,软件版本为S3SH32.12-41-
警告:
目前,Lenovo UDC 应用程序不会将 ThinkReality 应用程序部署到运行 Android 版本 13 系统软件的设备。对于需要访问 ThinkReality 应用程序的用户,建议在部署之前保留 Android 版本 12。
步骤 3:连接 A3 Glass 和摩托罗拉手机
将 USB Type-C 电缆的一端连接到摩托罗拉手机上的插槽中。接下来,将电缆的另一端连接到耳机上的电缆连接器插槽。
步骤 4:启动 Lenovo Universal Device Client (UDC) 应用程序
Lenovo UDC 应用程序随步骤 2 中的最新软件版本一起安装,并且在 A3 眼镜首次插入后将可见。首次将 A3 眼镜连接到摩托罗拉手机将自动启用并启动 UDC 应用程序。
警告
请勿从Google Play Store下载 Lenovo UDC App ,因为该版本不包含 Snapdragon Spaces 开发。
提示
启用 UDC 应用程序后,断开 A3 眼镜。稍后在设置过程中重新连接 A3 眼镜以接收任何眼镜固件更新。
步骤 5:接受 UDC 条款和权限(应用程序内的步骤 1、2 和 3)
警告
请勿通过 UDS 门户手动注册设备,如应用程序的步骤 4 所示。设备一次只能在一个门户中注册。如果设备已在另一个 UDS Portal 中注册,则可以通过安装作为 Unity 或 Unreal SDK 包下载的一部分下载的 apk 来继续 Snapdragon Spaces 开发。要注册 Snapdragon Spaces 门户并接收通过无线方式推送到设备的 Snapdragon Spaces 软件,设备需要从任何其他 UDS 门户取消注册,然后才能继续下一步。
第6步:扫描二维码注册摩托罗拉手机
扫描此二维码注册摩托罗拉手机:
警告
如果注册时出现错误,则该设备可能之前已经注册过,并且可能需要从后端门户清除该设备的序列号。如果设备重置回出厂设置,也会发生这种情况。
无论哪种情况,请访问https://spaces.qualcomm.com/settings/ (打开新窗口),如有需要请登录。按照部分中的说明进行操作Serial Number of Phone,然后选择“清除我的注册”以提交序列号以进行清除。在后端处理后,将发送一封电子邮件,确认设备清理,允许重新提交序列号,此时重复此步骤。
第 7 步:接受应用程序安装提示
注册后,以下应用程序将自动安装在摩托罗拉手机上。在某些地区,名称可能相似且不准确。
- A3首页
- 伴侣
- 应用空间服务
- 移动应用程序启动器
- 增强现实演员表
提示
确保接受摩托罗拉手机上的所有应用程序安装请求。此外,某些应用程序会请求Display over other apps权限。请注意,这些应用程序是 Lenovo ThinkReality 套件的一部分,并未在实际的 Snapdragon Spaces 开发中使用,但建议用于一般设备。其他 ThinkReality 步骤包括在连接眼镜时提示自动打开 Companion 应用程序,以及完成眼镜的入门教程。同样,(目前)这些与 ThinkReality 平台相关,该平台与 Snapdragon Spaces 平台分离,并并行运行在设备上(今天)。
有关 ThinkReality 应用程序的视频教程可在此处找到:https://support.lenovo.com/us/en/videos/nvid500337
第 8 步:完成所有 A3 眼镜固件更新
如果 A3 眼镜有可用的固件更新,它将自动部署到摩托罗拉手机并安装在 A3 眼镜上。请参阅摩托罗拉手机上的 Android 通知栏以查看 A3 安装进度。在固件安装期间,眼镜需要保持与手机的连接,更新后它们将自动重新启动。
要获取最新的眼镜固件,可能需要按顺序安装多个更新。每当更新完成时,眼镜将断开连接,Lenovo UDC 屏幕将报告“眼镜未连接”,并且需要手动拔下并重新插入才能进入下一个迭代固件更新。重新插入眼镜后,点击“检查更新”重复此过程直至完成。
原始格式的眼镜固件显示在 Lenovo 通用设备客户端 (UDC) 应用程序的底部。请注意,眼镜必须插入并完全连接才能显示眼镜版本。
提示
随着固件更新的不断推出,正确的 A3 眼镜固件可能会略有不同。此框代表要继续操作的最低可用 A3 固件。请注意,此处要查找的关键版本是 S1040,而不是 D983、D914 等较低版本。
最低固件版本:A3_user_S1040001_2208180059_sdm710_postcs8
可选:启用开发者模式
警告
对于装有 Android 13 和 Think Reality (TR) 应用程序的 motorola Edge 手机,请跳过此步骤。由于配套应用程序不包含在更新的 TR 应用程序套件中,因此开发人员模式既不可用也不必需。
这是强烈推荐的可选步骤。当 ThinkReality A3 连接到摩托罗拉手机时,它将自动启动 Lenovo Companion 应用程序。要禁用此功能:
- 打开配套应用程序
- 选择“以访客身份继续”
- 触摸左上角的三行图标,调出侧边栏菜单
- 选择“设置”
- 向下滑动并在“开发人员设置”标题下,切换滑块“启用开发人员模式”
- 连接 ThinkReality A3 时,Companion 应用程序将不再启动
第 9 步:Spaces 软件设置
开发人员应按照启动应用程序中的说明,通过从各自的 SDK 下载文件并使用 Android 开发人员工具进行侧面加载来安装 Spaces Services apk 以及 Unity 或 Unreal 示例。
非开发者:提供手机序列号
建议下载 Android 开发人员工具来旁加载 Spaces 服务和示例 apk。对于那些无法访问开发团队或开发人员工具的人来说,这些可以通过无线方式推送到设备,尽管这是一个纯手动过程并且不是立即进行的。
要进行此设置,请按照以下步骤提交设备序列号:
- 前往https://spaces.qualcomm.com/settings/(打开新窗口)
- 按照部分下的说明进行操作Serial Number of Phone,然后选择“管理我的设备”。
- 经过审核和处理后,一切完成后,您将收到电子邮件通知。
设置完成
Lenovo ThinkReality A3 现在应该可以使用了。
1.3 启动应用程序
1.3.1 推出 Snapdragon Spaces 应用程序 - ThinkReality A3
Snapdragon Spaces SDK开发包包括一个在设备上运行的Android服务应用程序,负责运行感知算法、与眼镜通信以及处理OpenXR运行时。
安装 Snapdragon Spaces 服务
Snapdragon Spaces Services apk 目前包含在 SDK 下载中。一旦进入应用商店,这将是一个补充下载,可以在运行专为 Snapdragon Spaces 设计的应用程序时提取。
目前,需要手动安装和设置。按着这些次序:
先决条件
这一步需要安装android debugbridge (打开新窗口)继续之前在计算机上。
- 设置移动设备以启用开发者选项 (打开新窗口)并启用USB调试。
- 将移动设备连接至电脑并授权USB调试。
- 从开发门户下载可用的 SDK 之一 (打开新窗口)并将它们解压到本地文件夹。
- 在解压文件夹的顶层找到Snapdragon Spaces Servicesadb install .apk 并通过安装它们。
- 检查示例 apk 的子文件夹并使用adb install.
设置 Snapdragon Spaces 服务
需要配置 Snapdragon 服务才能获得成功的开发人员体验:
- 从应用程序启动器中找到Snapdragon Spaces Services应用程序
- 按住(长按)此按钮并选择“应用程序信息”。
- 按进入“权限”并验证是否允许相机权限。如果没有,请点击并将其设置为“仅在使用应用程序时允许”。
- 从应用程序启动器或应用程序信息设置页面中的“打开”打开Snapdragon Spaces Services应用程序。
- 选择“显示在其他应用程序之上”并使用此权限启用Snapdragon Spaces 服务。
安装、重新安装或更新 Snapdragon Spaces 服务后
目前建议重复关闭“在其他应用程序上显示”并再次打开,即使该设置已显示为活动状态,以确保设备上完全识别该值。
验证应用程序启动
通过上述步骤配置Snapdragon Spaces 服务后,此步骤将验证设备是否已使用提供的 Snapdragon Spaces 应用程序完全设置。
- 对于 A3 眼镜:确保眼镜与手机完全连接并启动。该应用程序可能会出现在眼镜上,或者 ThinkReality 徽标可能出现在眼镜上。其中任何一个都可以。
- 在移动设备上,点击“所有应用程序”抽屉或主屏幕上的Snapdragon Spaces Samples应用程序图标。
- 如果Snapdragon Spaces 服务未正确安装或完全设置,请务必检查上述安装 Snapdragon Spaces 服务的步骤。
- 首次运行应用程序时可能会出现任何必要的权限弹出窗口。某些感知跟踪功能(例如平面检测、图像跟踪和手部跟踪)需要相机权限,因此应该允许这些功能。“在其他应用程序上显示”是正确渲染的另一个必要设置,应该启用。
- Spaces 服务和权限检查完成后,Controller Companion 应用程序应立即出现在手机上,而主应用程序应在短暂延迟后出现在 AR 眼镜上。(这是由于运行时需要启动而导致的,这可能需要几秒钟的时间。)
- 在继续之前验证示例应用程序是否运行。
安装并运行 Spaces 应用程序
设备验证后,Spaces Apps 现在可以在设备上安装和测试。
- 使用以下命令从计算机安装应用程序adb install
- 从 Google Play 商店安装应用程序
- 使用 Unity 或 Unreal Engine 开发应用程序
- 从 Lenovo UDC 客户端接收应用程序(需要从 Qualcomm 进行推送,如硬件设置中所述)
笔记
以下是有关这些平台的附加说明。
升级 Snapdragon Spaces 服务
在设备上安装新版本的 Snapdragon Spaces Services 时,请重新启动手机以确保清除所有痕迹。如果任何行为无法正常工作,请尝试在 Spaces Services 应用程序中禁用并重新启用权限(相机、在其他应用程序上显示)。
关于 ThinkReality A3 应用程序
ThinkReality A3 应用程序不是 Spaces 应用程序
在 A3 眼镜上,请注意,以下应用程序不属于 Snapdragon Spaces,而是另一个平台(称为 ThinkReality A3 平台)的一部分。
- 联想UDC
- 伴侣
- A3首页
- 增强现实演员表
- 模型查看器
有关 ThinkReality 的更多信息,请查看Lenovo 的支持网站 (打开新窗口)。请注意,您不需要Lenovo ID 或组织 ID 来设置设备,而是参考Spaces 门户上的ThinkReality A3 设置。
此外,伴侣应用程序默认会自动启动。可以通过打开开发人员模式来更改此行为。
关于拔掉 A3 眼镜
拔下 A3 眼镜之前关闭跑步空间应用程序
建议在拔下 A3 眼镜之前关闭或强制停止所有 Spaces 应用程序。如果在 Spaces 应用程序运行时眼镜断开连接,则需要重新启动手机才能再次正确运行 OpenXR 应用程序。为了获得最佳的开发人员体验,请按照“应用程序关闭”中的步骤操作。
申请关闭
由于应用程序的主要活动是在查看器上启动的,因此它不会显示在 Android 中的多任务视图/最近的应用程序列表中。
要关闭 Snapdragon Spaces Unity 或 Unreal Engine 示例应用程序,请执行以下任一操作:
- 按住手机控制器的MENU按钮2秒(在SampleController.csUnity中的脚本中实现),或者
- 瞄准眼镜主菜单场景中的“退出”按钮并激活它。
对于不提供退出功能的应用程序,可以使用Android 上的强制停止来关闭应用程序,如下一节所述。
应用强制停止
由于大多数 Spaces 应用程序都是通过在查看器上启动 Activity 来运行的(请参阅架构),因此通过系统优雅地关闭正在运行的应用程序的传统 Android 系统不可用。因此,Spaces 应用程序应处理应用程序内 UI 以关闭应用程序。如果此 UI 未实现或不可用,则可能需要手动关闭应用程序。
这可以通过长按应用程序启动器中的应用程序图标直到出现上下文菜单来完成App Info。打开应用程序信息视图后,可以通过单击 来停止应用程序Force Stop。
强制停止可能需要重新启动手机
请注意,强制停止应用程序不会向应用程序发送关闭信号,而是立即终止它,因此套接字可能会保持打开状态以超时,并且由于应用程序突然退出,某些感知功能可能不再正常工作。因此,后续启动时的任何意外行为都可以通过重新启动手机来纠正。
故障排除
如果您在运行硬件或应用程序时遇到问题,本部分包含您可能会遇到的一些常见问题。
检查您的设置
确保您遵循最新版本的硬件设置和相应的引擎设置指南:
- 设置手机和眼镜的程序
- 适用于 Unity 的 Snapdragon Spaces SDK 入门
- 适用于 Unreal 的 Snapdragon Spaces SDK 入门
症状: | 重新启动后我无法让应用程序运行多次 |
---|---|
行为: | 有时,Snapdragon Spaces Services 应用程序无法正确关闭,从而阻止下一个应用程序初始化该服务。 |
解决: | 强制停止任何使用 Snapdragon Spaces 服务的应用程序,然后重试。您可能还必须强制停止 Snapdragon Spaces Services 应用程序。如果失败,请尝试重新启动手机。 |
症状: | 我根本无法让我的应用程序运行。 |
---|---|
行为: | 您已插入眼镜并设置诱饵,但当您选择应用程序并运行它时,您会看到以下情况之一:1) 应用程序无法运行 2) 在手机上显示 3) 向我显示一条警告消息 4) 向我显示黑屏 |
解决: | 这表明 Spaces 服务未运行或与您的设备不兼容。检查您正在运行的版本(手机和眼镜)并确保您的版本是最新的。尝试运行 SDK 示例应用程序来验证您在设备上的设置。 |
症状: | 运行 Spaces 应用程序后,头部锁定的 ThinkReality 菜单显示为“卡住” |
---|---|
行为: | 头部锁定的 ThinkReality 菜单显得“卡住”。 |
解决: | 运行 Spaces 应用程序后有时会发生这种情况,但 Spaces 应用程序仍应正常运行。要恢复 ThinkReality 功能,请重新启动手机。 |
症状: | 当我插入眼镜时,我看不到任何东西。 |
---|---|
行为: | 你似乎无法让眼镜正常工作 |
解决: | 尝试拔掉并重新插入眼镜。如果这不起作用,请摘下眼镜并运行 Companion 应用程序。它会提示您插入眼镜。插上眼镜。大约 15-30 秒后,应表明眼镜已连接。如果失败,请尝试将 USB 电缆翻转到另一个方向。如果仍然失败,请尝试重新启动手机。如果仍然失败,请访问支持论坛 (打开新窗口)。 |
如果您遇到上述任一技术无法解决的问题,请尝试以下操作;
- 从手机上拔下眼镜。
- 确保手机电量充足。
- 重新启动手机,等待其完成启动。
- 插入眼镜,等待它们完成启动 - 大约 15 秒,直到您看到 ThinkReality 徽标。
- 尝试提供的 Spaces 应用程序,例如 SDK 下载中的示例之一。
- 如果有效,请退出示例应用程序并启动您自己的应用程序。
如果您仍然遇到问题,请联系支持论坛 (打开新窗口)以获得更多帮助。