SuperAPI AI Directory

hmos-multidevice-hardware-access

General & other

View repository

Updated 10-15 16:44

About this skill

Hardware invocation adaptation

Skill definition

Field Content
skill_id hardware-access
skill_name 硬件调用适配
one_line_purpose Provide unified access and fallback strategies for hardware capability detection, camera adaptation, sensors, and external devices.
device_scope phone / tablet / pc / foldable / wearables / 2in1
problem_scope SysCap、canIUse、相机枚举、折叠态相机重建、预览旋转、拍照旋转、stride花屏、传感器、GPS、NFC、蓝牙、外接设备、热插拔
not_in_scope 与硬件无关的纯 UI 布局问题、无能力差异的普通业务逻辑、视频编解码与流媒体、第三方相机库
primary_outputs primary_scene、device_constraints、code_touchpoints、fix_plan、verification_matrix

Core constraints

General hardware constraints

  1. Perform capability detection first, then call the relevant API.
  2. When system capabilities are involved, you must check both canIUse() and module.json5 declarations.
  3. When cameras are involved, enumerate devices first; do not hard-code camera IDs.
  4. When sensors are involved, you must describe the registration, unregistration, and lifecycle unbinding logic.
  5. When external devices are involved, you must describe the state refresh strategy after connection, disconnection, and hot plug/unplug.
  6. The output solution must include "how to degrade, hide, replace, or prompt when unsupported".

Camera-specific constraints

  1. Folding state changes must rebuild the camera: When the folding state switches, the camera selected before folding may no longer be available; you must listen for foldStatusChange and reselect the camera device, rebuild the XComponent, and rebuild the preview stream. The half-folded state (hover state) is a transitional state between folded/unfolded; under normal circumstances, half-folded state changes should be ignored and rebuilding skipped; handle it only when the user explicitly needs hover-state adaptation (HW-02-hover)
  2. stride must be compared with width: When obtaining preview frame data through ImageReceiver for secondary processing,image.Component.rowStride and width inconsistency must remove invalid pixels, otherwise screen corruption (stacked offset) occurs; stride varies by platform and must not be hard-coded
  3. Surface aspect ratio must match the preview stream ratio after rotation:display.rotation When it is 0°/180°, the Surface aspect ratio is the reciprocal of the preview aspect ratio; at 90°/270°, it is the same as the preview aspect ratio. Note: image stretching/compression (ratio mismatch) falls under this constraint; screen corruption stacking (pixel offset) falls under constraint 8
  4. Preview rotation angle = lens installation angle + screen rotation angle: The rear lens installation angle is 90°, and the front lens installation angle is 270°; the screen rotation angle is obtained through Display.rotation × 90° acquisition. It is recommended to use the getPreviewRotation() API to obtain it, without manual calculation
  5. Photo rotation angle depends on the gravity sensor: Rear camera 拍照旋转角度 = 镜头安装角度(90°) + 重力方向, front camera 拍照旋转角度 = 镜头安装角度(270°) - 重力方向; must be set at capture() when setting the rotation parameter
  6. Wide-fold external screen (such as PuraX) has only a front camera: A wide-fold device's external screen may have only a front camera; when switching to the external screen, you must handle the case where the rear camera is unavailable
  7. Rotation strategy distinction: sm breakpoint devices do not support rotation; md/lg breakpoint devices support rotation (window minimum dimension ≥ 600vp)
  8. Camera characteristics of 2in1 devices: Most 2in1 devices have only a front built-in camera, and a few also have a rear built-in camera; external cameras are not within the scope of HW-02 and belong to HW-04

Phase labels

Label Phase Current module focus
REQ Requirements analysis and design Capability boundaries, device differences, fallback strategies, camera capabilities, and folding-state adaptation scope
DEV Development Detection entry, enumeration logic, lifecycle binding, folding-state camera rebuild, stride handling, rotation angle calculation
FIX Issue fixing Incapability crash, wrong camera selection, garbled preview, abnormal rotation, sensor leakage, hot-plug failure
VAL Function verification canIUse results, device enumeration results, degradation behavior, connection switching evidence, camera function verification across all devices

Unified output fields

  • Routing field:active_phases、primary_phase、primary_scene、secondary_scenes、resources_used
  • REQ:device_constraints、capability_boundary、acceptance_focus
  • DEV:code_touchpoints、reuse_resources、implementation_notes、integration_risks
  • FIX:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
  • VAL:verification_matrix、evidence_requirements、pass_criteria、residual_risks

Field definition

  • device_constraints: refers to the hard adaptation constraints brought by differences in device hardware capabilities. This includes which devices have the target hardware, which checks must be performed before invocation, whether degradation, hiding, or substitution is mandatory when capabilities are missing; for camera scenarios, it also includes stride values, fold-state restrictions, etc.
  • capability_boundary: refers to which hardware capability combinations the current solution supports, which devices it does not support, and which capabilities can only be used after enumeration or declaration verification.
  • acceptance_focus: refers to the capability detection results, degradation paths, and device switching behavior that must be confirmed during acceptance in the requirements phase.
  • in scene deliverables.REQ appears device_constraints, indicating that "after this hardware scenario is hit, the requirements phase must first clarify the capability difference constraints," not a repeated explanation of the field.

AI retrieval requirements

  • When it involves whether a certain hardware capability is supported or whether a page should display a feature entry, prioritize matching HW-01。
  • When it involves taking photos, previewing, switching between front and rear cameras, camera switching in folded state, camera garbled display, or abnormal rotation, prioritize matching HW-02。
  • When it involves sensors such as accelerometer, gyroscope, light, proximity, GPS, etc., prioritize matching HW-03。
  • When it involves PC external cameras, keyboards, mice, or USB hot-plugging, prioritize matching HW-04。

Scenario index

HW-01 capability detection and function degradation

scene_id: HW-01
scene_name: 能力检测与功能降级
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - canIUse
  - SystemCapability
  - SysCap
  - module.json5
  - 不支持
applies_when:
  - 需要判断设备是否支持某硬件能力
  - 当前问题表现为不支持设备上仍显示功能入口或直接调用崩溃
not_applies_when:
  - 当前功能不依赖任何设备硬件差异
decisions:
  - 定义能力检测入口和展示策略
  - 决定不支持时是隐藏、置灰、替代还是提示
deliverables:
  REQ:
    - device_constraints
    - capability_boundary
    - acceptance_focus
  DEV:
    - code_touchpoints
    - reuse_resources
    - implementation_notes
    - integration_risks
  FIX:
    - problem_profile
    - root_cause_hypothesis
    - fix_plan
    - regression_watchlist
  VAL:
    - verification_matrix
    - evidence_requirements
    - pass_criteria
    - residual_risks
resource_refs:
  - RSC_HW_01
  - RSC_HW_02

HW-02 camera selection, preview, and form-factor switching

scene_id: HW-02
scene_name: 相机选择、预览与形态切换
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - 相机枚举
  - 前置相机
  - 后置相机
  - 预览旋转
  - 折叠屏相机
  - 花屏
  - stride
  - 拍照旋转
  - 录像角度
applies_when:
  - 需要拍照、预览、切前后摄或适配不同设备形态下的相机行为
  - 当前问题表现为默认相机错误、预览角度不对或设备切换后相机失效
  - 折叠状态变化导致相机设备不可用、黑屏
  - 预览流花屏、堆叠状偏移
  - 预览/拍照/录像旋转角度异常
not_applies_when:
  - 当前功能不使用相机
  - 外接摄像头(归 HW-04)
decisions:
  - 确定相机枚举逻辑和默认设备选择策略
  - 决定方向、预览、设备形态切换后的同步行为
  - 处理 stride 内存对齐问题
  - 计算预览/拍照/录像旋转角度
sub_scenes:
  - HW-02-fold: 折叠屏相机设备选择与重建
  - HW-02-layout: 基于断点的相机控制按钮布局
  - HW-02-stride: 预览流 stride 处理防花屏
  - HW-02-preview-rotation: 预览旋转角度与 Surface 宽高比
  - HW-02-capture-rotation: 拍照/录像旋转角度
  - HW-02-hover: 悬停态相机页面(可选,explicit_only)
deliverables:
  REQ:
    - device_constraints
    - capability_boundary
    - acceptance_focus
  DEV:
    - code_touchpoints
    - reuse_resources
    - implementation_notes
    - integration_risks
  FIX:
    - problem_profile
    - root_cause_hypothesis
    - fix_plan
    - regression_watchlist
  VAL:
    - verification_matrix
    - evidence_requirements
    - pass_criteria
    - residual_risks
resource_refs:
  - RSC_HW_03
  - RSC_HW_04
  - RSC_HW_08
  - RSC_HW_09
  - RSC_HW_10
  - RSC_HW_11
  - RSC_HW_12
HW-02 sub-scenario description
Sub-scenario Description Key acceptance points
HW-02-fold Camera device selection and re-creation when the fold state changes. Covers special scenarios such as the wide-fold outer screen having only the front camera and the 2in1 built-in camera No black screen when switching fold states, camera device correctly re-created
HW-02-layout Design adapted camera interface control button layouts for different device types and screen sizes Button layout is correct at each breakpoint
HW-02-stride Correctly handle stride memory alignment when using ImageReceiver to obtain each frame of preview stream data for secondary processing Pixel processing is correct when stride ≠ width, with no garbled stacking
HW-02-preview-rotation Preview rotation angle acquisition and setting, Surface aspect ratio calculation Preview orientation is correct, with no stretching
HW-02-capture-rotation Photo/video rotation angle depends on gravity sensor calculation Photo/video angle is consistent with the device holding orientation
HW-02-hover Camera page adaptation when a foldable screen is half-folded (hover state) and in landscape orientation. Enabled only when the application explicitly requires hover-state adaptation; do not add proactively Hover-state layout and rotation are correct
HW-02 routing rules
routing_rules:
  - keywords: [折叠, 折叠屏, foldStatus, 相机切换, PuraX, 外屏, 折叠后相机不可用]
    sub_scene: HW-02-fold
  - keywords: [断点, 相机按钮布局, 屏幕尺寸, 相机界面布局, 大屏按钮, 按钮显示异常, 按钮截断]
    sub_scene: HW-02-layout
  - keywords: [花屏, stride, 堆叠状, 内存对齐, rowStride, PixelMap, 预览花屏]
    sub_scene: HW-02-stride
  - keywords: [预览旋转, 预览方向, getPreviewRotation, setPreviewRotation, 预览拉伸, Surface宽高比, 预览画面压缩, 相机旋转]
    sub_scene: HW-02-preview-rotation
    auto_load_concepts: [RSC_HW_12]
  - keywords: [拍照方向, 照片旋转, 重力传感器, GRAVITY, capture(rotation), 录像角度, 录像方向]
    sub_scene: HW-02-capture-rotation
    auto_load_concepts: [RSC_HW_12]
  - keywords: [悬停态相机, 半折叠相机, FOLD_STATUS_HALF_FOLDED相机, 悬停态相机布局]
    sub_scene: HW-02-hover
    trigger_policy: explicit_only
    trigger_note: >
      半折叠态是折叠/展开的过渡状态,默认不路由。
      仅当用户提示词中显式包含"悬停态"+"相机"相关表述时才路由到 HW-02-hover。
      普通折叠切换导致的相机问题归 HW-02-fold。

HW-03 sensor subscription, reading, and unbinding

scene_id: HW-03
scene_name: 传感器订阅、读取与解绑
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
intent_signals:
  - 加速度
  - 陀螺仪
  - 光线
  - 距离
  - GPS
  - 生命周期解绑
applies_when:
  - 需要读取或订阅传感器数据
  - 当前问题表现为传感器不可用、数据不刷新或页面退出后未解绑
not_applies_when:
  - 功能不依赖传感器数据
decisions:
  - 选择订阅方式、刷新频率和生命周期绑定点
  - 决定传感器不可用时的回退逻辑
deliverables:
  REQ:
    - device_constraints
    - capability_boundary
    - acceptance_focus
  DEV:
    - code_touchpoints
    - reuse_resources
    - implementation_notes
    - integration_risks
  FIX:
    - problem_profile
    - root_cause_hypothesis
    - fix_plan
    - regression_watchlist
  VAL:
    - verification_matrix
    - evidence_requirements
    - pass_criteria
    - residual_risks
resource_refs:
  - RSC_HW_05
  - RSC_HW_06

HW-04 external devices and hot-plugging

scene_id: HW-04
scene_name: 外接设备与热插拔
phase_tags: [REQ, DEV, FIX, VAL]
priority: P1
intent_signals:
  - 外接设备
  - USB
  - 热插拔
  - 外接摄像头
  - 设备断连
applies_when:
  - 页面要适配外接摄像头、键盘、鼠标或 USB 设备
  - 当前问题表现为外接后状态不刷新或断开后仍保留旧状态
not_applies_when:
  - 当前功能只运行在单一内置硬件环境
decisions:
  - 定义连接、断开、热插拔后的状态刷新策略
  - 决定断连后的恢复、重试和回退行为
deliverables:
  REQ:
    - device_constraints
    - capability_boundary
    - acceptance_focus
  DEV:
    - code_touchpoints
    - reuse_resources
    - implementation_notes
    - integration_risks
  FIX:
    - problem_profile
    - root_cause_hypothesis
    - fix_plan
    - regression_watchlist
  VAL:
    - verification_matrix
    - evidence_requirements
    - pass_criteria
    - residual_risks
resource_refs:
  - RSC_HW_07
  - RSC_HW_01

Resource index

General hardware resources

RSC_HW_01 capability detection reference

resource_id: RSC_HW_01
resource_type: reference
path: ./references/syscap_mechanism.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
used_for:
  - 定义 SysCap 和 canIUse 的检测边界
  - 设计功能展示、降级和异常提示策略
load_when:
  - 命中 HW-01 或 HW-04
avoid_when:
  - 当前功能不依赖硬件差异
supports_scenes:
  - HW-01
  - HW-04
output_fields:
  - device_constraints
  - capability_boundary
  - implementation_notes
  - fix_plan
  - verification_matrix

RSC_HW_02 capability detection implementation assets

resource_id: RSC_HW_02
resource_type: asset
path: ./assets/SysCapChecker.ets
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 能力检测主实现示例
  - 复用 CanIUseExample 的接线方式
load_when:
  - 需要落能力检测和功能开关代码
avoid_when:
  - 当前只做需求分析
supports_scenes:
  - HW-01
output_fields:
  - code_touchpoints
  - reuse_resources
  - implementation_notes
  - pass_criteria

Camera resources

RSC_HW_03 camera adaptation reference

resource_id: RSC_HW_03
resource_type: reference
path: ./references/camera-device-selection.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
used_for:
  - 设计相机枚举、默认选择和预览行为
  - 多设备环境下的相机设备选择逻辑
  - 阔折叠外屏/2in1 设备相机回退策略
  - 热启动相机恢复
load_when:
  - 命中 HW-02
avoid_when:
  - 当前不涉及相机
supports_scenes:
  - HW-02
output_fields:
  - device_constraints
  - capability_boundary
  - implementation_notes
  - root_cause_hypothesis
  - verification_matrix

RSC_HW_04 camera implementation assets

resource_id: RSC_HW_04
resource_type: asset
path: ./assets/CameraAdapter.ets
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 相机选择和预览主示例
  - 复用 CameraExample、CameraPreviewExample、GetAvailableCameras 的枚举与预览方式
load_when:
  - 需要实现或修复相机逻辑
avoid_when:
  - 当前只做需求分析
supports_scenes:
  - HW-02
output_fields:
  - code_touchpoints
  - reuse_resources
  - implementation_notes
  - regression_watchlist
  - pass_criteria

RSC_HW_08 foldable-screen camera adaptation reference

resource_id: RSC_HW_08
resource_type: reference
path: ./references/camera-foldable-display.md
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 折叠状态变化时的相机设备选择与重建
  - XComponent 重建实现
  - 折叠状态监听方式选择
  - 半折叠态过滤策略
load_when:
  - 命中 HW-02-fold 或 HW-02-hover
avoid_when:
  - 当前不涉及折叠态相机切换
supports_scenes:
  - HW-02
output_fields:
  - code_touchpoints
  - fix_plan
  - verification_matrix

RSC_HW_09 preview stream stride handling reference

resource_id: RSC_HW_09
resource_type: reference
path: ./references/camera-stride-handling.md
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 处理预览流 stride 内存对齐导致的相机花屏
  - ImageReceiver 二次处理场景
load_when:
  - 命中 HW-02-stride
  - 出现相机预览花屏、堆叠状
avoid_when:
  - 不涉及 ImageReceiver 帧数据处理
supports_scenes:
  - HW-02
output_fields:
  - code_touchpoints
  - fix_plan
  - verification_matrix

RSC_HW_10 camera rotation angle adaptation reference

resource_id: RSC_HW_10
resource_type: reference
path: ./references/camera-rotation-adaptation.md
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 预览旋转角度获取与设置
  - Surface 宽高比计算
  - 拍照旋转角度计算
  - 录像旋转角度设置
load_when:
  - 命中 HW-02-preview-rotation 或 HW-02-capture-rotation
  - 出现预览拉伸、拍照方向异常
avoid_when:
  - 不涉及旋转角度问题
supports_scenes:
  - HW-02
output_fields:
  - code_touchpoints
  - fix_plan
  - verification_matrix

RSC_HW_11 camera issue fix scenario library

resource_id: RSC_HW_11
resource_type: reference
path: ./references/camera-bug-fix-cases.md
phase_tags: [FIX, VAL]
priority: P0
used_for:
  - 相机问题定位与修复
  - 正反例代码片段参考
  - 区分根因、问题场景和解决方案
load_when:
  - 命中 HW-02 且处于 FIX 阶段
  - 需要参考正反例代码
avoid_when:
  - 仅在需求分析阶段
supports_scenes:
  - HW-02
output_fields:
  - fix_plan
  - code_touchpoints
  - verification_matrix

RSC_HW_12 Camera rotation angle terminology reference

resource_id: RSC_HW_12
resource_type: reference
path: ./references/camera-rotation-terms.md
phase_tags: [REQ, DEV, FIX]
priority: P0
used_for:
  - 理解相机旋转相关角度概念和术语
  - 作为角度适配的概念基线
  - 角度概念混淆排查
load_when:
  - 命中 HW-02-preview-rotation 或 HW-02-capture-rotation
  - 需求分析阶段涉及相机旋转
avoid_when:
  - 仅需实现代码,不涉及角度问题
supports_scenes:
  - HW-02
output_fields:
  - device_constraints
  - capability_boundary

Sensor resources

RSC_HW_05 Sensor reference

resource_id: RSC_HW_05
resource_type: reference
path: ./references/sensor_adaptation.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P0
used_for:
  - 设计传感器可用性判断和订阅策略
  - 定义传感器不可用时的回退行为
load_when:
  - 命中 HW-03
avoid_when:
  - 当前不涉及传感器
supports_scenes:
  - HW-03
output_fields:
  - device_constraints
  - capability_boundary
  - implementation_notes
  - fix_plan
  - verification_matrix

RSC_HW_06 Sensor implementation assets

resource_id: RSC_HW_06
resource_type: asset
path: ./assets/SensorAdapter.ets
phase_tags: [DEV, FIX, VAL]
priority: P0
used_for:
  - 传感器订阅和解绑主示例
  - 校验生命周期内的注册与释放逻辑
load_when:
  - 需要落传感器订阅代码
avoid_when:
  - 当前不进入开发或验证阶段
supports_scenes:
  - HW-03
output_fields:
  - code_touchpoints
  - reuse_resources
  - implementation_notes
  - evidence_requirements
  - pass_criteria

External device resources

RSC_HW_07 External device reference

resource_id: RSC_HW_07
resource_type: reference
path: ./references/external_devices.md
phase_tags: [REQ, DEV, FIX, VAL]
priority: P1
used_for:
  - 设计外接设备连接、断开和热插拔策略
  - 定义外接设备断连后的恢复行为
load_when:
  - 命中 HW-04
avoid_when:
  - 当前不存在外设接入场景
supports_scenes:
  - HW-04
output_fields:
  - device_constraints
  - implementation_notes
  - root_cause_hypothesis
  - verification_matrix
  - residual_risks

Problem fix scenario library

See the complete problem fix scenarios (including positive and negative example code snippets) at camera-bug-fix-cases.md

Device-specific considerations

Wide fold (e.g., PuraX)

  • The outer screen may have only a front camera (currently only PuraX has this limitation)
  • Folded state: 1:1 aspect ratio
  • Unfolded state: 3:4 or 4:3 aspect ratio depending on rotation angle

Dual fold

  • Folded state: similar to a phone (3:4)
  • Unfolded state: larger screen, supports rotation (4:3)

Triple fold

  • F state (folded): similar to a phone (3:4)
  • M state (partially unfolded): medium screen (4:3)
  • G state (fully unfolded): largest screen, supports rotation (4:3)

Tablet

  • Large screen, supports rotation
  • 4:3 aspect ratio

2in1

  • Most have only a built-in front camera; a few also have a rear camera
  • External cameras are not within the scope of HW-02; they belong to HW-04
  • The screen is relatively large; the lg breakpoint layout is usually used

Stage output contract

REQ

  • Must output:active_phases、primary_phase、primary_scene、secondary_scenes
  • Must output:device_constraints、capability_boundary、acceptance_focus
  • Additional requirement: clearly specify the target hardware capabilities, the minimum supported device range, and the fallback method when unsupported

DEV

  • Must output:code_touchpoints、reuse_resources、implementation_notes、integration_risks
  • Additional requirement: clearly specify the capability detection entry point, enumeration entry point, and lifecycle binding point

FIX

  • Must output:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
  • Additional requirement: clarify whether the problem is missing capability judgment, incorrect enumeration, missing unbinding, hot-plug state not refreshed, stride not handled, or incorrect rotation angle calculation

VAL

  • Must output:verification_matrix、evidence_requirements、pass_criteria、residual_risks
  • Additional requirement: provide at least evidence of capability detection results, device enumeration results, and whether the fallback behavior is correct; camera scenarios need to cover multi-device, multi-fold-state, and multi-orientation verification