HarmonyOS APP开发：UWB超宽带定位与精确定位

核心要点：本文深入讲解基于HarmonyOS的UWB（Ultra-Wideband）超宽带定位技术，涵盖UWB物理层原理、TWR/TDoA测距算法、3D定位实现、FiRa协议标准，以及在HarmonyOS APP中的完整开发流程。UWB定位精度可达厘米级（0.1-0.3m），是高精度室内定位的终极方案。

一、背景与动机

1.1 为什么需要UWB定位

在前两篇文章中，我们分别介绍了蓝牙信标定位（1-5m精度）和WiFi指纹定位（3-10m精度）。这些技术满足了一般的室内导航需求，但在以下场景中，厘米级精度不可或缺：

UWB超宽带技术正是为这些高精度场景而生。

1.2 UWB技术概述

UWB（Ultra-Wideband，超宽带）是一种使用极低功率密度、极宽频带的无线通信技术。根据FCC定义，UWB信号的带宽至少为500MHz，或相对带宽（信号带宽/中心频率）大于20%。

UWB vs 窄带信号对比：

1.3 UWB定位的物理基础

UWB定位的精度源于其极宽的信号带宽。根据雷达分辨率公式：

$$\Delta d = \frac{c}{2B}$$

其中$c$为光速，$B$为信号带宽。当$B = 500\text{MHz}$时：

$$\Delta d = \frac{3 \times 10^8}{2 \times 500 \times 10^6} = 0.3\text{m}$$

当$B = 1\text{GHz}$时，分辨率可达0.15m。这就是UWB实现厘米级定位的物理基础。

二、核心原理

2.1 UWB信号体制

UWB有两种主要信号体制：

IR-UWB（Impulse Radio UWB）：发射极窄脉冲（纳秒级），直接利用脉冲的时间信息进行测距。FiRa联盟标准采用此方案。

MB-OFDM UWB：使用多频带正交频分复用，数据速率高但测距精度不如IR-UWB。

当前室内定位主流采用IR-UWB方案。

2.2 TWR双向测距

TWR（Two-Way Ranging，双向测距）是UWB最常用的测距方式，通过消息往返时间计算距离。

sequenceDiagram
    participant Tag as 标签(Tag)
    participant Anchor as 基站(Anchor)

    Note over Tag,Anchor: TWR测距流程

    Tag->>Anchor: POLL (t1)
    Note right of Anchor: 记录接收时间 t2

    Anchor->>Tag: RESPONSE (t3)
    Note left of Tag: 记录接收时间 t4

    Anchor->>Tag: FINAL (t5)
    Note left of Tag: 记录接收时间 t6

    Note over Tag,Anchor: 计算飞行时间
    Note over Tag: Tprop = ((t4-t1) - (t3-t2) +<br/>((t6-t1) - (t5-t2))) / 4
    Note over Tag: d = Tprop × c

    classDef tagStyle fill:#1a1a2e,stroke:#e94560,color:#eee,stroke-width:2px
    classDef anchorStyle fill:#16213e,stroke:#0f3460,color:#eee,stroke-width:2px

标准TWR测距公式：

单次TWR：

$$T_{prop} = \frac{(t_4 - t_1) - (t_3 - t_2)}{2}$$

双次TWR（消除时钟漂移误差）：

$$T_{prop} = \frac{(t_4 - t_1) - (t_3 - t_2) + (t_6 - t_1) - (t_5 - t_2)}{4}$$

距离：$d = T_{prop} \times c$，其中$c = 3 \times 10^8$ m/s

2.3 TDoA定位

TDoA（Time Difference of Arrival，到达时间差）是另一种UWB定位方式，不需要标签与基站之间的双向通信，适合大规模标签追踪。

flowchart TB
    A["标签发射UWB脉冲"] --> B["基站A接收<br/>时间 t_A"]
    A --> C["基站B接收<br/>时间 t_B"]
    A --> D["基站C接收<br/>时间 t_C"]
    A --> E["基站D接收<br/>时间 t_D"]

    B --> F["计算时间差<br/>Δt_AB = t_A - t_B"]
    C --> F
    D --> G["计算时间差<br/>Δt_AC = t_A - t_C"]
    E --> G

    F --> H["双曲线交点<br/>确定2D位置"]
    G --> H

    H --> I["3D定位<br/>(x, y, z)"]

    classDef tag fill:#533483,stroke:#e94560,color:#eee,stroke-width:2px
    classDef anchor fill:#16213e,stroke:#0f3460,color:#eee,stroke-width:2px
    classDef calc fill:#0f3460,stroke:#4ade80,color:#eee,stroke-width:2px
    classDef result fill:#1a1a2e,stroke:#e94560,color:#eee,stroke-width:2px

    class A tag
    class B,C,D,E anchor
    class F,G calc
    class H,I result

TDoA的优势：

• 标签功耗极低：只需发射脉冲，不需要接收
• 容量大：支持数千个标签同时定位
• 基站需要时钟同步：所有基站必须纳秒级同步

2.4 AoA角度定位

AoA（Angle of Arrival，到达角）利用天线阵列测量信号到达角度，结合距离信息可实现仅用2个基站完成2D定位。

$$\theta = \arctan\left(\frac{\Delta \phi}{2\pi d / \lambda}\right)$$

其中$\Delta \phi$为相邻天线元的相位差，$d$为天线间距，$\lambda$为波长。

2.5 FiRa协议标准

FiRa（Fine Ranging）联盟定义了UWB测距的互操作标准，HarmonyOS的UWB API遵循FiRa规范：

• FiRa 1.0：基础测距（TWR）
• FiRa 2.0：增强测距 + AoA + 安全测距
• FiRa CSML： Consortium Secure Measurement Layer，安全测距层

三、代码实战

3.1 UWB权限声明

// src/main/module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "requestPermissions": [
      {
        "name": "ohos.permission.ACCESS_UWB",
        "reason": "$string:uwb_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.ACCESS_BLUETOOTH",
        "reason": "$string:bluetooth_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

3.2 UWB会话管理与TWR测距

// UWBRangingManager.ets - UWB测距管理器
import { uwb } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// UWB测距配置
interface UWBRangeConfig {
  sessionId: number;          // 会话ID
  anchorAddress: string;      // 基站设备地址
  channel: number;            // UWB通道（5/6/8/9）
  preambleIndex: number;      // 前导码索引
  rangingInterval: number;    // 测距间隔(ms)
}

// 测距结果
interface UWBRangeResult {
  anchorAddress: string;      // 基站地址
  distance: number;           // 距离(米)
  azimuth: number;            // 方位角(度)
  elevation: number;          // 仰角(度)
  rssi: number;               // 信号强度
  confidence: number;         // 置信度
  timestamp: number;          // 时间戳
}

// 基站坐标信息
interface AnchorInfo {
  address: string;            // UWB设备地址
  x: number;                  // X坐标(米)
  y: number;                  // Y坐标(米)
  z: number;                  // Z坐标(米)
  channel: number;            // UWB通道
  name: string;               // 基站名称
}

export class UWBRangingManager {
  private sessions: Map<number, uwb.UwbSession> = new Map();
  private rangeResults: Map<string, UWBRangeResult> = new Map();
  private anchors: Map<string, AnchorInfo> = new Map();
  private isRanging: boolean = false;
  private onRangeUpdate?: (results: UWBRangeResult[]) => void;

  // 注册基站信息
  registerAnchor(anchor: AnchorInfo): void {
    this.anchors.set(anchor.address, anchor);
    console.info(`[UWB] 注册基站: ${anchor.name} (${anchor.address})`);
  }

  // 批量注册基站
  registerAnchors(anchors: AnchorInfo[]): void {
    anchors.forEach(a => this.registerAnchor(a));
  }

  // 设定测距结果回调
  setOnRangeUpdate(callback: (results: UWBRangeResult[]) => void): void {
    this.onRangeUpdate = callback;
  }

  // 创建UWB测距会话
  async createSession(config: UWBRangeConfig): Promise<boolean> {
    try {
      // 检查UWB是否可用
      const isAvailable = uwb.isUwbAvailable();
      if (!isAvailable) {
        console.error('[UWB] UWB不可用，请检查设备是否支持UWB');
        return false;
      }

      // 创建会话参数
      const sessionConfig: uwb.UwbSessionConfig = {
        sessionId: config.sessionId,
        sessionType: uwb.SessionType.RANGING_SESSION,
        channel: config.channel,
        preambleIndex: config.preambleIndex,
      };

      // 创建UWB会话
      const session = uwb.createUwbSession(sessionConfig);
      this.sessions.set(config.sessionId, session);

      // 注册测距结果回调
      session.on('rangingResult', (result: uwb.RangingResult) => {
        this.handleRangingResult(result);
      });

      // 启动测距
      session.startRanging({
        sessionId: config.sessionId,
        peerAddress: config.anchorAddress,
        rangingInterval: config.rangingInterval,
      });

      console.info(`[UWB] 会话已创建: sessionId=${config.sessionId}`);
      return true;
    } catch (error) {
      const err = error as BusinessError;
      console.error(`[UWB] 创建会话失败: ${err.code} - ${err.message}`);
      return false;
    }
  }

  // 处理测距结果
  private handleRangingResult(result: uwb.RangingResult): void {
    const rangeResult: UWBRangeResult = {
      anchorAddress: result.peerAddress,
      distance: result.distanceMm / 1000.0, // 毫米转米
      azimuth: result.azimuth ?? 0,
      elevation: result.elevation ?? 0,
      rssi: result.rssi ?? -100,
      confidence: result.confidence ?? 0,
      timestamp: Date.now()
    };

    this.rangeResults.set(result.peerAddress, rangeResult);

    // 通知更新
    if (this.onRangeUpdate) {
      this.onRangeUpdate(Array.from(this.rangeResults.values()));
    }
  }

  // 批量启动多基站测距
  async startMultiAnchorRanging(intervalMs: number = 200): Promise<void> {
    if (this.isRanging) {
      return;
    }

    this.isRanging = true;
    let sessionId = 1;

    for (const [address, anchor] of this.anchors) {
      const config: UWBRangeConfig = {
        sessionId,
        anchorAddress: address,
        channel: anchor.channel || 9,
        preambleIndex: 10,
        rangingInterval: intervalMs,
      };

      await this.createSession(config);
      sessionId++;
    }

    console.info(`[UWB] 已启动 ${this.anchors.size} 个基站测距`);
  }

  // 停止所有测距
  stopAllRanging(): void {
    for (const [sessionId, session] of this.sessions) {
      try {
        session.stopRanging({ sessionId });
        session.off('rangingResult');
        console.info(`[UWB] 会话 ${sessionId} 已停止`);
      } catch (error) {
        console.warn(`[UWB] 停止会话 ${sessionId} 失败: ${error}`);
      }
    }
    this.sessions.clear();
    this.rangeResults.clear();
    this.isRanging = false;
  }

  // 获取当前测距结果
  getRangeResults(): UWBRangeResult[] {
    return Array.from(this.rangeResults.values());
  }

  // 获取基站信息
  getAnchors(): AnchorInfo[] {
    return Array.from(this.anchors.values());
  }

  // 是否正在测距
  isRangingActive(): boolean {
    return this.isRanging;
  }
}

3.3 3D定位算法

// UWBPositionSolver.ets - UWB 3D定位算法
import { UWBRangeResult, AnchorInfo } from './UWBRangingManager';

// 3D定位结果
interface Position3D {
  x: number;
  y: number;
  z: number;
  accuracy: number;          // 估计精度(米)
  anchorCount: number;       // 参与定位的基站数
  timestamp: number;
}

export class UWBPositionSolver {
  private anchors: Map<string, AnchorInfo> = new Map();
  // 历史位置（用于平滑）
  private positionHistory: Position3D[] = [];
  private maxHistorySize: number = 5;
  // EKF状态
  private ekfState: Float64Array | null = null;
  private ekfCovariance: Float64Array | null = null;

  // 设置基站信息
  setAnchors(anchors: AnchorInfo[]): void {
    this.anchors.clear();
    anchors.forEach(a => this.anchors.set(a.address, a));
  }

  // 三边定位（3D）
  trilaterate3D(rangeResults: UWBRangeResult[]): Position3D | null {
    // 收集有效测距数据
    const validRanges: Array<{
      x: number; y: number; z: number;
      distance: number;
      address: string;
    }> = [];

    for (const result of rangeResults) {
      const anchor = this.anchors.get(result.anchorAddress);
      if (anchor && result.distance > 0 && result.distance < 50) {
        validRanges.push({
          x: anchor.x,
          y: anchor.y,
          z: anchor.z,
          distance: result.distance,
          address: result.anchorAddress
        });
      }
    }

    // 3D定位至少需要4个基站
    if (validRanges.length < 4) {
      // 降级为2D定位
      return this.trilaterate2D(validRanges);
    }

    // 使用加权最小二乘法求解
    return this.weightedLeastSquares3D(validRanges);
  }

  // 加权最小二乘3D定位
  private weightedLeastSquares3D(
    ranges: Array<{ x: number; y: number; z: number; distance: number }>
  ): Position3D {
    const n = ranges.length;
    const x1 = ranges[0].x;
    const y1 = ranges[0].y;
    const z1 = ranges[0].z;
    const d1 = ranges[0].distance;

    let sumAxx = 0, sumAxy = 0, sumAxz = 0;
    let sumAyy = 0, sumAyz = 0, sumAzz = 0;
    let sumBx = 0, sumBy = 0, sumBz = 0;

    for (let i = 1; i < n; i++) {
      const xi = ranges[i].x;
      const yi = ranges[i].y;
      const zi = ranges[i].z;
      const di = ranges[i].distance;

      const weight = 1.0 / (di * di + 1e-6);

      const ax = 2 * (xi - x1);
      const ay = 2 * (yi - y1);
      const az = 2 * (zi - z1);
      const b = d1 * d1 - di * di + xi * xi - x1 * x1 + yi * yi - y1 * y1 + zi * zi - z1 * z1;

      sumAxx += weight * ax * ax;
      sumAxy += weight * ax * ay;
      sumAxz += weight * ax * az;
      sumAyy += weight * ay * ay;
      sumAyz += weight * ay * az;
      sumAzz += weight * az * az;
      sumBx += weight * ax * b;
      sumBy += weight * ay * b;
      sumBz += weight * az * b;
    }

    // 求解3x3线性方程组（使用Cramer法则）
    const A = [
      [sumAxx, sumAxy, sumAxz],
      [sumAxy, sumAyy, sumAyz],
      [sumAxz, sumAyz, sumAzz]
    ];
    const B = [sumBx, sumBy, sumBz];

    const det = this.determinant3x3(A);
    if (Math.abs(det) < 1e-10) {
      // 奇异矩阵，使用简单平均
      return this.simpleAverage(ranges);
    }

    const x = this.determinant3x3([
      [B[0], A[0][1], A[0][2]],
      [B[1], A[1][1], A[1][2]],
      [B[2], A[2][1], A[2][2]]
    ]) / det;

    const y = this.determinant3x3([
      [A[0][0], B[0], A[0][2]],
      [A[1][0], B[1], A[1][2]],
      [A[2][0], B[2], A[2][2]]
    ]) / det;

    const z = this.determinant3x3([
      [A[0][0], A[0][1], B[0]],
      [A[1][0], A[1][1], B[1]],
      [A[2][0], A[2][1], B[2]]
    ]) / det;

    // 计算残差估计精度
    let residualSum = 0;
    for (const range of ranges) {
      const dx = x - range.x;
      const dy = y - range.y;
      const dz = z - range.z;
      const estimatedDist = Math.sqrt(dx * dx + dy * dy + dz * dz);
      residualSum += Math.abs(estimatedDist - range.distance);
    }

    const position: Position3D = {
      x: Math.round(x * 1000) / 1000,
      y: Math.round(y * 1000) / 1000,
      z: Math.round(z * 1000) / 1000,
      accuracy: Math.round((residualSum / n) * 1000) / 1000,
      anchorCount: n,
      timestamp: Date.now()
    };

    // 历史平滑
    this.positionHistory.push(position);
    if (this.positionHistory.length > this.maxHistorySize) {
      this.positionHistory.shift();
    }

    return this.smoothPosition(position);
  }

  // 2D降级定位
  private trilaterate2D(
    ranges: Array<{ x: number; y: number; z: number; distance: number }>
  ): Position3D | null {
    if (ranges.length < 3) {
      // 不足3个基站，使用最近邻法
      if (ranges.length === 0) return null;

      const nearest = ranges.reduce((min, r) => r.distance < min.distance ? r : min);
      return {
        x: Math.round(nearest.x * 100) / 100,
        y: Math.round(nearest.y * 100) / 100,
        z: Math.round(nearest.z * 100) / 100,
        accuracy: nearest.distance,
        anchorCount: ranges.length,
        timestamp: Date.now()
      };
    }

    // 2D三边定位（忽略z坐标）
    const x1 = ranges[0].x;
    const y1 = ranges[0].y;
    const d1 = ranges[0].distance;

    let sumAxx = 0, sumAxy = 0, sumAyy = 0;
    let sumBx = 0, sumBy = 0;

    for (let i = 1; i < ranges.length; i++) {
      const xi = ranges[i].x;
      const yi = ranges[i].y;
      const di = ranges[i].distance;
      const weight = 1.0 / (di * di + 1e-6);

      const ax = 2 * (xi - x1);
      const ay = 2 * (yi - y1);
      const b = d1 * d1 - di * di + xi * xi - x1 * x1 + yi * yi - y1 * y1;

      sumAxx += weight * ax * ax;
      sumAxy += weight * ax * ay;
      sumAyy += weight * ay * ay;
      sumBx += weight * ax * b;
      sumBy += weight * ay * b;
    }

    const det = sumAxx * sumAyy - sumAxy * sumAxy;
    if (Math.abs(det) < 1e-10) {
      return this.simpleAverage(ranges);
    }

    const x = (sumAyy * sumBx - sumAxy * sumBy) / det;
    const y = (sumAxx * sumBy - sumAxy * sumBx) / det;

    return {
      x: Math.round(x * 100) / 100,
      y: Math.round(y * 100) / 100,
      z: ranges[0].z, // 使用第一个基站的z坐标
      accuracy: 0.3,
      anchorCount: ranges.length,
      timestamp: Date.now()
    };
  }

  // 3x3行列式计算
  private determinant3x3(m: number[][]): number {
    return m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1])
      - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0])
      + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0]);
  }

  // 简单加权平均
  private simpleAverage(
    ranges: Array<{ x: number; y: number; z: number; distance: number }>
  ): Position3D {
    let totalWeight = 0;
    let wx = 0, wy = 0, wz = 0;

    for (const r of ranges) {
      const weight = 1.0 / (r.distance + 0.1);
      wx += weight * r.x;
      wy += weight * r.y;
      wz += weight * r.z;
      totalWeight += weight;
    }

    return {
      x: Math.round((wx / totalWeight) * 100) / 100,
      y: Math.round((wy / totalWeight) * 100) / 100,
      z: Math.round((wz / totalWeight) * 100) / 100,
      accuracy: ranges[0].distance,
      anchorCount: ranges.length,
      timestamp: Date.now()
    };
  }

  // 位置平滑（指数移动平均）
  private smoothPosition(current: Position3D): Position3D {
    if (this.positionHistory.length < 2) {
      return current;
    }

    const alpha = 0.6; // 平滑因子
    const prev = this.positionHistory[this.positionHistory.length - 2];

    return {
      ...current,
      x: alpha * current.x + (1 - alpha) * prev.x,
      y: alpha * current.y + (1 - alpha) * prev.y,
      z: alpha * current.z + (1 - alpha) * prev.z,
    };
  }

  // 清除历史
  clearHistory(): void {
    this.positionHistory = [];
  }
}

3.4 UWB定位主页面

// pages/UWBPositioningPage.ets - UWB定位主页面
import { UWBRangingManager, AnchorInfo, UWBRangeResult } from '../service/UWBRangingManager';
import { UWBPositionSolver, Position3D } from '../service/UWBPositionSolver';

@Entry
@Component
struct UWBPositioningPage {
  @State currentPosition: Position3D | null = null;
  @State rangeResults: UWBRangeResult[] = [];
  @State isRanging: boolean = false;
  @State statusText: string = '未启动';
  @State accuracyText: string = '--';

  private rangingManager: UWBRangingManager = new UWBRangingManager();
  private positionSolver: UWBPositionSolver = new UWBPositionSolver();

  aboutToAppear(): void {
    // 注册UWB基站（模拟工厂车间布局）
    const anchors: AnchorInfo[] = [
      { address: 'AA:BB:CC:DD:EE:01', x: 0, y: 0, z: 3, channel: 9, name: '基站A-东北角' },
      { address: 'AA:BB:CC:DD:EE:02', x: 20, y: 0, z: 3, channel: 9, name: '基站B-西北角' },
      { address: 'AA:BB:CC:DD:EE:03', x: 20, y: 15, z: 3, channel: 9, name: '基站C-西南角' },
      { address: 'AA:BB:CC:DD:EE:04', x: 0, y: 15, z: 3, channel: 9, name: '基站D-东南角' },
      { address: 'AA:BB:CC:DD:EE:05', x: 10, y: 7.5, z: 3, channel: 9, name: '基站E-中心' },
    ];

    this.rangingManager.registerAnchors(anchors);
    this.positionSolver.setAnchors(anchors);

    // 设定测距回调
    this.rangingManager.setOnRangeUpdate((results: UWBRangeResult[]) => {
      this.rangeResults = results;
      this.currentPosition = this.positionSolver.trilaterate3D(results);
      if (this.currentPosition) {
        this.accuracyText = `±${this.currentPosition.accuracy * 100}cm`;
      }
    });
  }

  aboutToDisappear(): void {
    this.rangingManager.stopAllRanging();
  }

  build() {
    Column() {
      // 顶部标题
      this.TitleBar()

      // 3D坐标显示卡片
      this.Position3DCard()

      // 基站测距列表
      this.AnchorRangeList()

      // 控制按钮
      this.ControlButtons()
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0a0a1a')
  }

  @Builder
  TitleBar() {
    Row() {
      Text('UWB超宽带定位')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .fontColor('#ffffff')
      Blank()
      Row() {
        Circle()
          .width(8)
          .height(8)
          .fill(this.isRanging ? '#4ade80' : '#ef4444')
          .margin({ right: 6 })
        Text(this.statusText)
          .fontSize(13)
          .fontColor(this.isRanging ? '#4ade80' : '#94a3b8')
      }
    }
    .width('100%')
    .padding({ left: 20, right: 20, top: 16, bottom: 8 })
  }

  @Builder
  Position3DCard() {
    Column() {
      Text('3D坐标')
        .fontSize(12)
        .fontColor('#94a3b8')
        .margin({ bottom: 8 })

      if (this.currentPosition) {
        Row() {
          this.CoordinateAxis('X', this.currentPosition.x, '#ef4444')
          this.CoordinateAxis('Y', this.currentPosition.y, '#4ade80')
          this.CoordinateAxis('Z', this.currentPosition.z, '#3b82f6')
        }
        .width('100%')
        .justifyContent(FlexAlign.SpaceAround)

        // 精度指示
        Row() {
          Text('定位精度')
            .fontSize(12)
            .fontColor('#94a3b8')
          Text(this.accuracyText)
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .fontColor('#4ade80')
            .margin({ left: 8 })
        }
        .margin({ top: 12 })
      } else {
        Text('等待定位...')
          .fontSize(20)
          .fontColor('#475569')
          .margin({ top: 20, bottom: 20 })
      }
    }
    .width('100%')
    .padding(20)
    .margin({ left: 16, right: 16, top: 12 })
    .borderRadius(16)
    .backgroundColor('rgba(30, 41, 59, 0.8)')
    .backdropBlur(20)
    .border({ width: 1, color: 'rgba(148, 163, 184, 0.1)' })
  }

  @Builder
  CoordinateAxis(label: string, value: number, color: string) {
    Column() {
      Text(label)
        .fontSize(11)
        .fontColor(color)
        .fontWeight(FontWeight.Bold)
      Text(`${value.toFixed(3)}m`)
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .fontColor('#ffffff')
        .margin({ top: 4 })
    }
    .alignItems(HorizontalAlign.Center)
  }

  @Builder
  AnchorRangeList() {
    Column() {
      Text('基站测距')
        .fontSize(16)
        .fontWeight(FontWeight.Medium)
        .fontColor('#ffffff')
        .margin({ bottom: 8 })

      List() {
        ForEach(this.rangeResults, (result: UWBRangeResult) => {
          ListItem() {
            this.AnchorRangeItem(result)
          }
        }, (result: UWBRangeResult) => result.anchorAddress)
      }
      .width('100%')
      .layoutWeight(1)
      .divider({ strokeWidth: 1, color: 'rgba(148, 163, 184, 0.06)' })
    }
    .width('100%')
    .layoutWeight(1)
    .padding({ left: 16, right: 16, top: 16 })
  }

  @Builder
  AnchorRangeItem(result: UWBRangeResult) {
    Row() {
      // 距离指示
      Column() {
        Text(`${(result.distance * 100).toFixed(1)}cm`)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .fontColor('#e2e8f0')
        Text(`${result.distance.toFixed(3)}m`)
          .fontSize(11)
          .fontColor('#64748b')
          .margin({ top: 2 })
      }
      .alignItems(HorizontalAlign.Start)
      .width('30%')

      // 方位角
      Column() {
        Text(`方位 ${result.azimuth.toFixed(1)}°`)
          .fontSize(12)
          .fontColor('#94a3b8')
        Text(`仰角 ${result.elevation.toFixed(1)}°`)
          .fontSize(12)
          .fontColor('#64748b')
          .margin({ top: 2 })
      }
      .alignItems(HorizontalAlign.Start)
      .layoutWeight(1)

      // 信号质量
      Column() {
        Text(`${result.rssi} dBm`)
          .fontSize(11)
          .fontColor('#64748b')
        // 置信度条
        Row() {
          Row()
            .width(`${result.confidence * 100}%`)
            .height(4)
            .borderRadius(2)
            .backgroundColor('#4ade80')
        }
        .width(60)
        .height(4)
        .borderRadius(2)
        .backgroundColor('rgba(148, 163, 184, 0.2)')
        .margin({ top: 4 })
      }
      .alignItems(HorizontalAlign.End)
    }
    .width('100%')
    .padding({ top: 10, bottom: 10 })
  }

  @Builder
  ControlButtons() {
    Row() {
      Button(this.isRanging ? '停止测距' : '开始测距')
        .width('80%')
        .height(48)
        .fontSize(16)
        .fontWeight(FontWeight.Medium)
        .fontColor('#ffffff')
        .backgroundColor(this.isRanging ? '#dc2626' : '#7c3aed')
        .borderRadius(24)
        .onClick(() => {
          if (this.isRanging) {
            this.rangingManager.stopAllRanging();
            this.isRanging = false;
            this.statusText = '已停止';
          } else {
            this.rangingManager.startMultiAnchorRanging(200);
            this.isRanging = true;
            this.statusText = '测距中';
          }
        })
    }
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .padding({ top: 16, bottom: 24 })
  }
}

四、踩坑与注意事项

4.1 UWB硬件兼容性

关键问题：并非所有HarmonyOS设备都支持UWB。

支持UWB的设备特征：

• 需要内置UWB芯片（如NXP SR150/SR250、Qorvo DW3000系列）
• 目前华为Mate系列部分高端机型支持
• HarmonyOS NEXT设备支持度更高

兼容性检查：

// 检查UWB可用性
const isAvailable = uwb.isUwbAvailable();
if (!isAvailable) {
  // 降级到蓝牙/WiFi定位
  console.warn('UWB不可用，降级到蓝牙定位');
}

4.2 时钟漂移与校准

UWB测距精度受本地时钟精度影响。典型晶振精度±20ppm，在1ms测距间隔中可能产生20ns误差（约6米）。

解决方案：

• 使用**双次TWR（DS-TWR）**消除时钟漂移误差
• 定期校准时钟偏移
• 使用TCXO（温度补偿晶振）替代普通晶振

4.3 NLOS（非视距）问题

UWB信号虽然穿透能力强，但在NLOS条件下，信号传播路径变长，测距结果偏大。

NLOS检测方法：

1. RSSI异常检测：NLOS下RSSI显著低于预期
2. 信道脉冲响应（CIR）分析：NLOS下多径分量增多
3. 运动一致性检测：连续测距值出现非物理跳变

NLOS缓解策略：

• 基站部署在高处且无遮挡的位置
• 使用更多基站冗余（至少6个），NLOS时剔除异常基站
• 引入NLOS偏差补偿模型

4.4 多径抑制

UWB的极宽带宽本身具有多径分辨能力，但在复杂室内环境中仍需额外处理：

4.5 UWB通道选择

FiRa标准定义了多个UWB通道，不同通道特性不同：

建议：在中国和大部分地区，优先使用通道9。

4.6 安全性考虑

UWB测距涉及位置隐私和安全：

1. 中继攻击（Relay Attack）：攻击者转发UWB信号，伪造距离信息
   • 防御：使用FiRa CSML安全测距层，加密测距消息
2. 位置隐私泄露：UWB定位精度极高，可能暴露用户精确位置
   • 防御：仅在用户授权后启用UWB，支持隐私模式
3. 设备仿冒：伪造基站或标签身份
   • 防御：使用设备证书和双向认证

五、HarmonyOS 6适配

5.1 UWB API增强

HarmonyOS 6对UWB API进行了重要增强：

// HarmonyOS 6 UWB增强API
import { uwb } from '@kit.ConnectivityKit';

// 新增：AoA角度测量
const aoaConfig: uwb.AoAConfig = {
  enableAzimuth: true,     // 启用方位角测量
  enableElevation: true,   // 启用仰角测量
  antennaArray: uwb.AntennaArrayType.CIRCULAR_4,  // 天线阵列类型
};

// 新增：安全测距
const secureConfig: uwb.SecureRangingConfig = {
  enableSecureRanging: true,
  sessionKey: new Uint8Array([/* 128-bit密钥 */]),
  cipherSuite: uwb.CipherSuite.AES128_CCM,
};

// 新增：多会话管理
const multiSessionConfig: uwb.MultiSessionConfig = {
  maxSessions: 8,
  sessionSchedule: uwb.ScheduleType.ROUND_ROBIN,
};

5.2 后台UWB定位

// HarmonyOS 6 后台UWB定位
import { backgroundTaskManager } from '@kit.BackgroundTasksKit';

// UWB长时任务
async function startBackgroundUWB(): Promise<void> {
  backgroundTaskManager.startBackgroundRunning(
    getContext(),
    backgroundTaskManager.BackgroundMode.BLUETOOTH_INTERACTION,
    wantAgent
  );

  // 低功耗UWB测距配置
  const lowPowerConfig: UWBRangeConfig = {
    sessionId: 1,
    anchorAddress: 'AA:BB:CC:DD:EE:01',
    channel: 9,
    preambleIndex: 10,
    rangingInterval: 1000,  // 后台降低测距频率
  };
}

5.3 UWB与数字钥匙

HarmonyOS 6增强了UWB数字钥匙能力，支持CCC（Car Connectivity Consortium）数字钥匙3.0规范：

// HarmonyOS 6 数字钥匙
import { digitalKey } from '@kit.ConnectivityKit';

// 注册数字钥匙
async function registerCarKey(): Promise<void> {
  const keyConfig: digitalKey.DigitalKeyConfig = {
    keyType: digitalKey.KeyType.UWB_BLE_NFC,  // UWB+BLE+NFC三模
    vehicleId: 'VIN_XXXXXXXX',
    secureChannel: digitalKey.SecureChannel.UWB,
  };

  await digitalKey.registerKey(keyConfig);
}

六、总结

本文系统讲解了基于HarmonyOS的UWB超宽带定位技术，核心要点回顾：

flowchart TB
    subgraph UWB定位系统
        direction TB
        A["UWB硬件初始化"] --> B["创建测距会话"]
        B --> C["TWR双向测距"]
        C --> D["多基站距离采集"]
        D --> E{"基站数≥4?"}
        E -- 是 --> F["3D三边定位"]
        E -- 否 --> G["2D降级定位"]
        F --> H["位置平滑"]
        G --> H
        H --> I["3D坐标输出<br/>(x, y, z)"]
    end

    classDef process fill:#16213e,stroke:#0f3460,color:#eee,stroke-width:2px
    classDef decision fill:#0f3460,stroke:#e94560,color:#eee,stroke-width:2px
    classDef output fill:#1a1a2e,stroke:#4ade80,color:#eee,stroke-width:2px
    classDef start fill:#533483,stroke:#e94560,color:#eee,stroke-width:2px

    class A,B start
    class C,D process
    class E decision
    class F,G process
    class H process
    class I output

UWB定位最佳实践：

1. 基站部署：至少4个基站，呈四面体分布，高度2.5-4米，确保LOS覆盖
2. 通道选择：中国地区优先通道9（8GHz）
3. 测距频率：实时定位200ms间隔，追踪场景500ms-1s间隔
4. 冗余设计：部署6+基站，NLOS时自动剔除异常基站
5. 安全防护：启用FiRa CSML安全测距，防止中继攻击

UWB定位是当前室内定位精度最高的技术方案，在智能汽车数字钥匙、工业4.0、仓储物流等高价值场景有不可替代的地位。随着HarmonyOS设备UWB芯片的普及，UWB定位将迎来更广泛的应用。下一篇文章将探讨室内导航与路径规划，将定位能力转化为实用的导航服务。