把 Mission Planner 搬上鸿蒙 PC:把 .NET 内核烧成 so,移植鸿蒙应用

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/MissionPlanner
在这里插入图片描述

一、项目移植适配信息说明

项目信息
适配对象Mission Planner(ArduPilot 官方地面站,WinForms + GMap.NET + log4net,上游 tag 1.3.83 / commit b78a7495)
技术路线.NET NativeAOT 内核(10 个无 UI 项目,451 个 .cs、约 36.9 万行)→ C ABI mpe_* → NAPI dlopen 桥 → ArkUI 外壳
工程来源https://atomgit.com/OpenHarmonyPCDeveloper/MissionPlanner(克隆即可构建,引擎 so 已入库)
迁移等级T1:内核上游源码原样编译、外壳 ArkUI 重写、运行时是不含 JIT/托管宿主的单一 .so
产物libmagcs.so 约 20 MB;HAP 双 ABI
已打通MAVLink 心跳/遥测/参数(5000 项)/任务上传下载;UDP/TCP/串口三种链路入口
边界固件烧写、地图在线瓦片依赖 CDN、参数页行级编辑未完成

为什么值得做:这个软件三种代码性质完全不同——协议层极重(CRC_EXTRA、v1/v2 帧、参数分批重传、任务上传状态机,坑是十几年外场飞行攒的)、状态层极重(CurrentState 上百字段,飞行模式按机型分叉)、交互层极轻(显示数据、画地图、点按钮)。值钱的是内核,不值钱的是外壳。

二、环境准备

2.1 DevEco 与设备

项要求
设备鸿蒙 PC 真机(2in1);联调飞控另需 SITL 或真机 + 数传
IDEDevEco Studio 6.x(含 OHOS NDK)
git clone https://atomgit.com/OpenHarmonyPCDeveloper/MissionPlanner.git

仓库结构:根是 HarmonyOS 壳工程(entry/ ArkTS + cpp/ NAPI 桥),engine/ 是 .NET 内核工程,third_party/MissionPlanner 是上游浅克隆的 gitlink——构建不需要它,重建对照才需自行 checkout b78a7495。用 DevEco 打开仓库根目录,首次同步 ohpm install。检查三处:

  1. AppScope/app.json5:bundleName com.example.hm_webview_demo、versionCode 9910000。同包名旧应用(很多调试工程共用此占位名)必须先 hdc uninstall;
  2. entry/src/main/module.json5:deviceTypes 含 "2in1",并至少补 ohos.permission.INTERNET——UDP/TCP 链路全靠它,漏了报 SocketException: Permission denied;
  3. entry/libs/<abi>/ 里应有 libmagcs.so(约 20 MB,随库入库)。

2.2 签名与首装

Signing Configs 勾选自动签名后点 Run。启动后是 ArkTS 工作台四页(飞行数据/地图/参数/连接设置)。无飞控也能验界面:四页渲染 + 姿态仪 Canvas 出图 + 引擎自检。链路联调:本机跑 scripts/mock_heartbeat.py 模拟飞控(1 Hz 心跳),应用侧填 UDP 端口点连接,几秒内应看到 linked=1 与姿态数据滚动;日志 hdc shell hilog | grep MAGCS 有结构化诊断输出。

2.3 重编内核的第二层环境(可选)

改 C# 代码需要 Windows + .NET 9 SDK + OpenHarmony.NET.Runtime + PublishAotCross + zig fakeclang(与 ImageGlass 一篇同一套链路):

cd engine
dotnet publish MagcsEngine -c Release -r linux-musl-arm64

产物覆盖进 entry/libs/ 重打包。别丢裁剪配置:UseSystemResourceKeys=false + IlcGenerateStackTraceTable=true,否则异常只剩地址没有信息。

三、适配教程

3.1 迁移等级先定下来

三维度判定:T0 容器级复用交付快但系统能力全废;T2 参照重写必然语义漂移(复刻 MAVLink 重传边界"看起来一样,飞起来不一样");T1 内核保留 + 外壳重写是重协议软件的合理落点。最小引擎闭合刻意剔除主 MissionPlannerLib.csproj(拖 WinForms shim / ZedGraph),只留 Mavlink、Interfaces、Comms、Core、alglibnet、GeoUtility、GMap.NET.Core、Strings、Utilities、ArduPilot 十项目。

3.2 内核侧:AOT + C ABI 门面

双 ABI so 不直接暴露 NAPI,而是 18 个 mpe_* C ABI 导出(open_udp/open_tcp/open_serial/close/linked/status_json/param_get/param_set/params_json/mission_download_json/mission_upload_json/arm/set_mode…)——C ABI 比 C++ ABI 稳定,NAPI 侧 dlsym 拿函数指针即可。两处内核改造:串口层默认读"配置文件"定位参数元数据,AOT 环境改内置精简元数据;log4net 静态初始化在 NativeAOT 下崩,用 no-op stub 工程替换 NuGet 引用(不改上游源码)。裁剪保底:keep.xml 保 MAVLink 命名空间,漏了报 TypeInitialization_Type_NoTypeAvailable。

3.3 桥与壳:轮询而非回调

NAPI 桥 360 行做四件事:运行时 dlopen(不静态链,失败可诊断)、异步 Open()(同步开会卡 UI 线程)、字符串与句柄两套所有权、状态快照。ArkTS 侧用 50 ms 轮询拉 status_json 快照而非回调——回调要跨线程投递到 UI,轮询让 ArkTS 掌控节奏、丢帧不堆积;姿态仪用一条 Canvas 画 HUD。ArkTS 严格模式的四个坑(禁 spread、禁 any、Want 字面量要标类型、数组要真数组)逐条处理。

3.4 链路调不通时的三个诊断工具

依次撞了三堵墙并都做成工具:权限没声明(补 INTERNET);链路"秒断"(写 mock_heartbeat.py 模拟飞控,区分"发不出去"与"收不到回复");端口 bind 状态不明(netstat 与引擎侧 bind 日志对账)。最终 21 字节心跳包往返打通,linked=1,参数拉取 5000 项。诊断能力也做进界面(连接设置页显示端口与收发计数),交付后用户能自己看懂链路状态。

下方章节为移植适配过程中的详细讲解。

飞行数据页(窗口模式):姿态仪与航迹底图


四、三层架构

三个数字可以概括体量:ArkTS 单页 Index.ets 1670 行、NAPI 桥 napi_init.cpp 360 行、引擎门面 Engine.cs 453 行。真正"为鸿蒙写的代码"只有这两千来行,剩下的全是上游内核原样搬过来的机器码——这正是 T1 的样子。

在这里插入图片描述

下面这张图是最终形态:全屏状态下的飞行数据页,上半是航迹地图,中部是四个遥测仪表卡,底部是飞控操作区(解锁/上锁、六种模式快捷切换)。

飞行数据页:地图 + 遥测仪表 + 飞控操作


五、第一步:把 C# 内核烧成鸿蒙能 dlopen 的 so

5.1 为什么是 NativeAOT

.NET 上鸿蒙,理论上有四条路:

方案问题
Mono / .NET 运行时随包分发要自带一个运行时,启动慢、体积大,且 .NET 官方没有鸿蒙 RID 的运行时构建
Blazor / WebView 套壳界面变网页,直接退回 T0,系统集成全丢
把 C# 翻成 C++等于重写内核,降级为 T2,且 36 万行的语义细节无法保证
NativeAOT直接产出无 JIT 的机器码 .so,进程内零托管宿主,dlopen 即用

NativeAOT 这条路的关键前提是:目标 RID 必须选 linux-musl。鸿蒙的 libc 是 musl 系,用 linux-arm64(glibc)编出来的产物在设备上会因为符号解析失败直接 dlopen 失败。交叉链接交给 Zig 做链接器,工程里通过两个 targets 导入:

<!-- engine/MagcsEngine/MagcsEngine.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <OutputType>Library</OutputType>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <!-- 鸿蒙没有 ICU,全球化必须关掉,否则启动即崩 -->
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>

  <PropertyGroup>
    <PublishAot>true</PublishAot>
    <StripSymbols>true</StripSymbols>
    <OptimizationPreference>Size</OptimizationPreference>
    <!-- full 裁剪:不裁体积接近 40 MB,裁了约 20 MB -->
    <TrimMode>full</TrimMode>
    <!-- 诊断期保留真实异常文本与栈 -->
    <IlcGenerateStackTraceTable>true</IlcGenerateStackTraceTable>
    <EventSourceSupport>false</EventSourceSupport>
    <UseSystemResourceKeys>false</UseSystemResourceKeys>
    <!-- 反射保留清单 -->
    <RdXmlFile>keep.xml</RdXmlFile>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\third_party\MissionPlanner\ExtLibs\ArduPilot\MissionPlanner.ArduPilot.csproj" />
  </ItemGroup>

  <Import Project="..\..\OpenHarmony.NET.Runtime\runtime.targets" />
  <Import Project="..\..\PublishAotCross\package\OpenHarmony.NET.PublishAotCross.targets" />
</Project>

TrimMode=full 是这里最危险的一行。裁剪器看不到 MAVLink 的消息表是通过反射按类型名查找的,会把它们当死代码删掉,而这个问题编译期永远不报错,只在运行期第一次收包时抛 MissingMetadataException。所以必须配 keep.xml 按命名空间整段保留。

5.2 一次构建,两个 ABI

鸿蒙 PC 现在既有 arm64 机型也有 x86_64 机型(部分开发机、模拟器),所以两个 ABI 都得产出。构建脚本把"托管冒烟 → 双 RID 发布 → 注入 HAP → 核对导出符号"串成四步:

# scripts/build_engine.ps1(节选)
$env:PATH = "$NdkLlvmBin;$Repo\PublishAotCross\package\fakeclang\win-x64;$ZigDir;$env:PATH"

# [1/4] 先在主机上跑通 mock 飞控的全链路冒烟,避免把问题带进设备
& $Dotnet run -c Release --nologo

# [2/4] 交叉编译双 ABI
& $Dotnet publish -c Release -r linux-musl-arm64 --nologo
& $Dotnet publish -c Release -r linux-musl-x64   --nologo

# [3/4] 注入 HAP 的 libs 目录
Copy-Item '...\linux-musl-arm64\native\MagcsEngine.so' 'hap\entry\libs\arm64-v8a\libmagcsengine.so' -Force
Copy-Item '...\linux-musl-x64\native\MagcsEngine.so'   'hap\entry\libs\x86_64\libmagcsengine.so'   -Force

产物落地前还要补一件事:NativeAOT 输出的 .so 默认没有 SONAME,打包进 HAP 后 dlopen 走的是绝对路径解析,缺 SONAME 在某些加载顺序下会出现"找不到依赖"。用 NDK 自带的 llvm-objcopy 补上,再用 readelf -d 确认 NEEDED 里只有系统库:

llvm-objcopy --set-soname libmagcsengine.so MagcsEngine.so
readelf -d libmagcsengine.so | grep NEEDED

5.3 C ABI 门面:18 个导出符号

引擎对平台必须"无感知"——它不该知道什么是 NAPI、什么是 ArkTS。所以门面层只暴露纯 C 函数,参数全是 char* / int / double,错误通过"返回值 + 全局错误串"回传。

// engine/MagcsEngine/Engine.cs(节选)
public static unsafe class Host
{
    private static readonly ConcurrentDictionary<int, EngineSession> Sessions = new();
    private static string _lastError = "";

    [UnmanagedCallersOnly(EntryPoint = "mp_ping")]
    public static int Ping() => 4210;

    [UnmanagedCallersOnly(EntryPoint = "mpe_open_udp")]
    public static unsafe int OpenUdp(byte* host, byte* port)
    {
        try { _lastError = ""; return Insert(EngineSession.OpenUdp(Utf8(host), Utf8(port))); }
        catch (Exception ex) { Fail(ex); return -1; }
    }

    [UnmanagedCallersOnly(EntryPoint = "mpe_status_json")]
    public static unsafe byte* StatusJson(int handle)
    {
        if (!Sessions.TryGetValue(handle, out var s)) return StrPtr("{}");
        try { return StrPtr(s.StatusJson()); } catch { return StrPtr("{}"); }
    }

    // 每条路径都过一遍 Fail():把 InnerException 链拼进错误串
    private static string Fail(Exception ex)
    {
        string msg = ex.ToString();
        if (ex.InnerException != null) msg += " || INNER: " + ex.InnerException.ToString();
        if (msg.Length > 3000) msg = msg.Substring(0, 3000);
        _lastError = msg;
        return msg;
    }
}

字符串所有权必须定死一条规矩:C 侧 malloc 的内存由 C 侧释放。所以每个返回 char* 的接口都配一个 mp_free,桥接层拷贝成 JS 字符串之后立刻交还,不做任何"交给 GC 管"的假设。

private static unsafe byte* StrPtr(string s)
{
    var b = Encoding.UTF8.GetBytes(s ?? "");
    var p = (byte*)Marshal.AllocHGlobal(b.Length + 1);
    Marshal.Copy(b, 0, (IntPtr)p, b.Length);
    p[b.Length] = 0;
    return p;
}

[UnmanagedCallersOnly(EntryPoint = "mp_free")]
public static unsafe void Free(byte* p) => Marshal.FreeHGlobal((IntPtr)p);

5.4 最隐蔽的一个坑:上游串口层要读"配置文件"

上游 UdpSerial 在建链时并不直接吃你传进去的 host/port,而是通过 CommsBase.Settings 这个静态事件去问宿主:“UDP_port_K1 是多少?” —— 在 Windows 上,这个事件的订阅方是 Settings.Instance,背后是 config.xml。

鸿蒙上没有 config.xml,也没人在界面里做 OnInputBoxShow 那个输入框。如果放着不管,Settings 事件返回 NotSet,UDP 监听端口就永远绑不上,表现出来是"代码全对,但一包数据都收不到"。

解决办法不是改上游,而是在引擎启动时把这个事件接管掉,用一个内存字典替代配置文件:

// EngineSession 静态构造:把上游的"问配置"改成"查内存表"
static EngineSession()
{
    CommsBase.Settings += (name, value, set) =>
    {
        if (set) return value;
        if (name.StartsWith("UDP_host", StringComparison.Ordinal))
            return UdpConfigs.TryGetValue(name.Substring("UDP_host".Length), out var c) ? c.host : value;
        if (name.StartsWith("UDP_port", StringComparison.Ordinal))
            return UdpConfigs.TryGetValue(name.Substring("UDP_port".Length), out var c) ? c.port : value;
        return value;
    };
}

public static EngineSession OpenUdp(string host, string port)
{
    // 标准 GCS 监听模式:UdpSerial 监听本地端口,对端(SITL / WiFi 遥测)主动连入
    var udp = new UdpSerial
    {
        ReadTimeout = 500,
        ConfigRef = "K" + Interlocked.Increment(ref _refSeq),   // 每个会话独立配置键
    };
    UdpConfigs[udp.ConfigRef] = (host, port);
    udp.Port = port;
    return Start(udp);
}

还有一个容易误入的岔路:不要试图直接注入一个已经打开的 UdpClient。上游 OpenBg() 里有一段判断——如果 IsOpen 已经是 true,它会认为"已经开好了",跳过启动接收线程。结果是 socket 绑上了,但没有任何线程在读它。必须老老实实走完 Open() 的完整流程。


六、NAPI 桥:360 行里塞下四件事

6.1 不链 so,而是运行时 dlopen

CMake 里没有把 libmagcsengine.so 写成 target_link_libraries 的依赖,而是由桥接层在第一次调用时 dlopen:

// hap/entry/src/main/cpp/napi_init.cpp(节选)
static bool LoadEngine() {
    std::call_once(g_load_once, []() {
        g_engine = dlopen("libmagcsengine.so", RTLD_NOW);
        if (!g_engine) {
            const char* e = dlerror();
            OH_LOG_Print(LOG_APP, LOG_ERROR, MAGCS_DOMAIN, TAG,
                         "dlopen libmagcsengine.so: %{public}s", e ? e : "unknown");
            return;
        }
        mpe_open_udp  = (fn_open2)dlsym(g_engine, "mpe_open_udp");
        mpe_status_json = (fn_str1)dlsym(g_engine, "mpe_status_json");
        mp_free       = (fn_free)dlsym(g_engine, "mp_free");
        mp_ping       = (fn_ping)dlsym(g_engine, "mp_ping");
        // ... 其余 14 个符号
        OH_LOG_Print(LOG_APP, LOG_INFO, MAGCS_DOMAIN, TAG,
                     "engine loaded, ping=%{public}d", mp_ping ? mp_ping() : -1);
    });
    return g_engine != nullptr;
}

这么做有两个好处:一是构建期不依赖引擎产物,改 UI 时不必携带 20 MB 的 so 就能编译通过;二是加载失败可以降级——界面还能开,只是所有功能报"引擎加载失败",而不是整个进程起不来。

6.2 同步 Open() 会把 UI 线程卡死

这是整个桥接层存在的唯一理由。上游 MAVLinkInterface.Open() 内部是 Task.Run(...).Wait(),它会等待两个心跳才算连上,而 CONNECT_TIMEOUT_SECONDS 默认 30 秒。如果直接在 ArkTS 的点击事件里同步调用它,主线程会被冻结 30 秒——鸿蒙会直接判 ANR 杀掉应用。

所以 open* 全部改成"主线程立刻返回句柄,后台线程去连":

struct SessionState {
    int engine = -1;      // -1 = 后台连接尚未完成
    bool closing = false;
    bool failed = false;
    std::string error;
};

static void OpenWorker(std::shared_ptr<OpenArgs> a) {
    if (!LoadEngine()) { /* 记录 failed = true */ return; }
    fn_open2 fn = a->kind == OpenKind::Udp ? mpe_open_udp
                : a->kind == OpenKind::Tcp ? mpe_open_tcp
                : mpe_open_serial;
    int eh = fn ? fn(a->host.c_str(), a->port.c_str()) : -100;

    std::string err;
    if (eh < 0 && mpe_last_error) {
        char* e = mpe_last_error();
        if (e) { err = e; if (mp_free) mp_free(e); }
    }

    {
        std::lock_guard<std::mutex> lk(g_sessions_mutex);
        if (a->state->closing) {
            // 用户在连接完成前就点了断开:这里补一刀,不能泄漏引擎会话
            if (eh >= 0 && mpe_close) mpe_close(eh);
        } else {
            a->state->engine = eh;
            a->state->failed = (eh < 0);
            a->state->error = err;
        }
    }
}

对应到 ArkTS 侧,就变成一个四态查询:0=pending、1=ready、2=failed、3=closed。

static napi_value OpenState(napi_env env, napi_callback_info info) {
    // ...
    int v = 3;                          // closed
    if (s) {
        if (s->failed) v = 2;           // failed
        else if (s->engine >= 0) v = 1; // ready
        else v = 0;                     // pending
    }
    return IntResult(env, v);
}

UI 线程每 300 ms 查一次状态,pending 时显示"等待心跳 N s",failed 时把 stateError() 的原文(最多截 160 字)直接铺在界面上。这条"错误原文上屏"的规则后面救了无数次命,第八章会讲。

6.3 字符串与句柄:两套所有权

  • 句柄:ArkTS 拿到的是一个整数,内部映射到 std::shared_ptr<SessionState> 与引擎侧的 ConcurrentDictionary<int, EngineSession>。两层各自维护自己的句柄表,close() 时先置 closing、再 mpe_close,避免后台线程正在写入时被连根拔掉。
  • 字符串:C 侧返回的 char* 一律经 StrResult() 拷贝成 JS 字符串后立刻 mp_free,不跨调用持有指针。
static napi_value StrResult(napi_env env, char* s) {
    napi_value out;
    if (s) {
        napi_create_string_utf8(env, s, NAPI_AUTO_LENGTH, &out);
        if (mp_free) mp_free(s);          // 拷完即还
    } else {
        napi_create_string_utf8(env, "", NAPI_AUTO_LENGTH, &out);
    }
    return out;
}

七、ArkTS 外壳:一次轮询拿一份快照

7.1 为什么用轮询,而不是回调

跨语言回推数据(C++ 主动调 JS)在 NAPI 里要走 napi_threadsafe_function,还要处理"回调触发时 UI 页面已经销毁"的竞态。对地面站这种"看数"的软件,这条路收益极低。

所以外壳只做一件事:每 300 ms 拉一次全量 JSON 快照。

// 连接成功后启动
this.pollId = setInterval(() => this.poll(), 300);

poll(): void {
  if (this.handle < 0) return;
  const st: number = magcs.openState(this.handle);
  if (st === 3) {                       // closed
    this.handle = -1; this.linked = false; return;
  }
  if (st === 2) {                       // failed:把引擎给的原文铺到界面上
    const err: string = magcs.stateError(this.handle);
    this.handle = -1; this.linked = false;
    this.lastEvent = '连接失败 ' + (err.length > 0 ? err.substring(0, 160) : '未知错误');
    this.tab = 1;
    return;
  }
  if (st === 0) {                       // pending:还在等心跳
    this.linked = false;
    this.waitSec = Math.floor((Date.now() - this.connectAt) / 1000);
    return;
  }
  this.linked = magcs.linked(this.handle);
  try {
    const raw: Telemetry = JSON.parse(magcs.statusJson(this.handle)) as Telemetry;
    const t: Telemetry = new Telemetry();
    t.roll = typeof raw.roll === 'number' ? raw.roll : 0;
    t.pitch = typeof raw.pitch === 'number' ? raw.pitch : 0;
    t.yaw = typeof raw.yaw === 'number' ? raw.yaw : 0;
    t.lat = typeof raw.lat === 'number' ? raw.lat : 0;
    t.lng = typeof raw.lng === 'number' ? raw.lng : 0;
    t.alt = typeof raw.alt === 'number' ? raw.alt : 0;
    t.mode = typeof raw.mode === 'string' ? raw.mode : '';
    // ... 其余十来个字段同理
    this.cs = t;                        // 整体替换,触发一次重绘
  } catch (e) {
    this.cs = new Telemetry();
  }
  if (this.tab === 0) this.drawAttitude();
  if (this.tab === 0 || this.tab === 3) this.drawMap();
}

一笔账:快照约 1 KB,每秒 3.3 次,序列化开销在设备上测下来不到 0.3% CPU;换来的是没有任何跨线程回调,也就没有"回调到已销毁页面"的崩溃面。这是个很划算的交易。

7.2 ArkTS 严格模式的四个坑

鸿蒙的 ArkTS 不是 TypeScript,arkts-no-any-unknown 之类的规则会把很多"JS 里随便写"的习惯直接判成编译错误。踩过的四个:

① JSON.parse 不能直接当对象用。 返回值在 ArkTS 里没有结构化类型,必须落进显式 class,而且每个字段都要 typeof 校验——因为 NaN 序列化成 JSON 会变成 null,真机上出现过"电压 NaN 导致 toFixed 抛异常"。

② @State 绑定的必须是 class 实例。 用 interface 定义、用字面量赋值,界面不会刷新(编译器不报错)。正确做法是 class Telemetry { roll: number = 0; ... },每次 this.cs = t 整个替换。

③ 属性链里调用方法会被静默忽略。 .width(this.calcW()) 这种写法不生效,也不报错;.width(this.winW >= 1000 ? '46%' : '100%') 这种返回字面量的三元表达式才正常。响应式尺寸只能靠"预计算的 @State 字段 + 三元字面量"。

④ Canvas 重绘会闪。 地图这种每秒重画多次的组件,如果直接在同一条 CanvasRenderingContext2D 上 clearRect + 重绘,会看到白闪。所以地图用两条离屏上下文做双缓冲:

private mapCtxA: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));
private mapCtxB: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));
private mapAReady: boolean = false;
private mapBReady: boolean = false;

先把整帧画到非可见的那条上下文,画完再一次性 drawImage 到可见 Canvas 上。代价是多占一块画布内存,收益是拖拽地图时不再闪白。

7.3 姿态仪:一条 Canvas 画出来的 HUD

地面站的灵魂是姿态仪。上游用的是 WinForms 自绘控件,这里用 Canvas 重画一遍,核心只有"裁剪成圆 → 按滚转旋转 → 按俯仰平移 → 天地两半":

drawAttitude(): void {
  const ctx = this.ctx;
  const w: number = 480, h: number = 300;
  const cx: number = w / 2, cy: number = (h - 26) / 2;
  const R: number = 118;

  ctx.clearRect(0, 0, w, h);
  ctx.save();
  ctx.beginPath();
  ctx.arc(cx, cy, R, 0, Math.PI * 2);
  ctx.clip();                                  // 圆形遮罩
  ctx.translate(cx, cy);
  ctx.rotate(this.cs.roll * Math.PI / 180);    // 滚转 = 整体旋转

  const shift: number = this.cs.pitch * 2.6;   // 俯仰 = 天地线平移
  const sky: CanvasGradient = ctx.createLinearGradient(0, -200, 0, 0);
  sky.addColorStop(0, '#1b4a74');
  sky.addColorStop(1, '#2f7fb8');
  ctx.fillStyle = sky;
  ctx.fillRect(-260, -320 + shift, 520, 320);

  const gnd: CanvasGradient = ctx.createLinearGradient(0, 0, 0, 220);
  gnd.addColorStop(0, '#7a5a2e');
  gnd.addColorStop(1, '#453216');
  ctx.fillStyle = gnd;
  ctx.fillRect(-260, shift, 520, 320);

  // 俯仰梯
  ctx.lineWidth = 1.4;
  ctx.font = '10px sans-serif';
  for (let p = -40; p <= 40; p += 10) {
    if (p === 0) continue;
    const y: number = shift - p * 2.6;
    if (y < -R || y > R) continue;
    const half: number = p % 20 === 0 ? 42 : 26;
    ctx.strokeStyle = '#d7e2f5';
    ctx.beginPath();
    ctx.moveTo(-half, y);
    ctx.lineTo(half, y);
    ctx.stroke();
    if (p % 20 === 0) {
      ctx.fillStyle = '#d7e2f5';
      ctx.fillText(`${p > 0 ? p : -p}`, half + 5, y + 4);
    }
  }
  ctx.restore();

  // 滚转刻度弧 + 指针(不随滚转旋转,画在遮罩外)
  for (let a = -45; a <= 45; a += 15) {
    const rad: number = (-90 + a) * Math.PI / 180;
    const r1: number = a === 0 ? R - 12 : R - 6;
    ctx.beginPath();
    ctx.moveTo(cx + r1 * Math.cos(rad), cy + r1 * Math.sin(rad));
    ctx.lineTo(cx + R * Math.cos(rad), cy + R * Math.sin(rad));
    ctx.stroke();
  }
}

这段代码有几个必须踩过才知道的细节:

  • clip() 之后再 translate/rotate,顺序反了遮罩会跟着转,圆形变成歪的;
  • 俯仰梯的刻度值要取绝对值,且负俯仰时天地线向下移,符号弄反了会比较尴尬——低头时看到地面上升;
  • 滚转指针画在 restore() 之后,否则它自己也会被滚转二次旋转。

配上窗口模式的整体观感(左侧窄边栏、上方 HUD、下方地图):

飞行数据页(窗口模式):姿态仪与航迹底图


八、离线地图:一个 11 MB 的单文件瓦片包

8.1 三个不能选的技术栈

地图是这类软件最容易被"顺手搬运"坑到的部分。

不能搬 GMap.NET。 它依赖 System.Drawing 与 WinForms 控件树,鸿蒙上根本没有这两个东西,裁剪器也会把 System.Drawing.Common 整段剥掉。

不能用 Leaflet + WebView。 这是最省事的做法,但它把外壳退回了 T0:rawfile 里要塞一整套 web 资源,WebView 在 2in1 上要独立起一个渲染进程,内存和电量都不划算;更要命的是地图上的点击、缩放手势会和 ArkUI 的手势系统打架。

不能依赖在线瓦片。 无人机作业环境通常是山区、工地、灾害现场——没有外网才是常态。一个"断网就白屏"的地面站,不能算可用的地面站。

所以地图是自己画的:Web 墨卡托投影 + Canvas 逐块 drawImage + 内置离线瓦片包。

8.2 为什么打包成单个二进制文件

最朴素的方案是把 2298 张 PNG 丢进 rawfile/tiles/z/x/y.png。问题有三个:

  1. 构建期 resources 索引会为每个文件建条目,构建时间明显变长;
  2. 安装时 HAP 解包要建 2298 个 inode,首次启动慢;
  3. 运行时每次找瓦片都是一次文件系统查找,滚图时抖动明显。

改成"一个索引 + 一段连续数据"就都解决了。格式定义得很土,但够用:

magic   'MGTILES1'          8 B
count   u32                 4 B
index   count × 24 B        z(4) x(4) y(4) offset(4) len(4) type(4)
data    count 段拼接         type: 0=PNG, 1=WebP

打包脚本除了拼容器,还顺手做了两件提升压缩率的事:把带透明的瓦片合成到白底(地图瓦片边缘的半透明在放大时会发黑),以及重新编码成 WebP(质量 85),如果重编码后反而变大就退回原 PNG:

# _offline_tiles/pack_tiles.py(节选)
def normalize(raw):
    """统一成不透明 RGB;全透明瓦片返回 None(海洋空白,直接丢弃)"""
    im = Image.open(io.BytesIO(raw))
    if im.mode in ('RGBA', 'LA') or 'transparency' in im.info:
        im = im.convert('RGBA')
        alpha = im.split()[3]
        covered = sum(alpha.histogram()[16:])
        if covered < im.size[0] * im.size[1] * 0.02:
            return None                       # 透明度低于 2% 视为空白格,不打包
        bg = Image.new('RGB', im.size, (255, 255, 255))
        bg.paste(im, mask=alpha)
        return bg
    return im.convert('RGB')

def main():
    items = []
    for z, x, y, path in walk():
        raw = open(path, 'rb').read()
        typ = 0
        try:
            im = normalize(raw)
            if im is None:
                continue
            buf = io.BytesIO()
            im.save(buf, format='WEBP', quality=85, method=4)
            data = buf.getvalue()
            typ = 1
            if len(data) >= len(raw):         # WebP 没压下来就用原图
                data, typ = raw, 0
        except Exception:
            data, typ = raw, 0
        items.append((z, x, y, data, typ))

    items.sort(key=lambda t: (t[0], t[1], t[2]))
    header = b'MGTILES1' + struct.pack('<I', len(items))
    offset = len(header) + 24 * len(items)
    index, body = bytearray(), bytearray()
    for z, x, y, data, typ in items:
        index += struct.pack('<IIIIII', z, x, y, offset, len(data), typ)
        body += data
        offset += len(data)

    with open(OUT, 'wb') as f:
        f.write(header); f.write(bytes(index)); f.write(bytes(body))

实测:2298 张 PNG 共 12.0 MB,打包后 11.4 MB(约 95%),其中被丢弃的全透明瓦片有几十张。

8.3 运行时:三种来源,四级优先级

外壳启动时先一次性把头部的索引读进内存(Map<"z/x/y", [offset, len]>),之后取瓦片就是"切片 → createImageSource → createPixelMap":

private loadPackedMap(): void {
  if (this.pkTried) return;
  this.pkTried = true;
  try {
    const data: Uint8Array = getContext(this).resourceManager.getRawFileContentSync('tiles_magcs.bin');
    const buf: ArrayBuffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
    const dv: DataView = new DataView(buf);
    let magic: string = '';
    for (let i: number = 0; i < 8; i++) magic += String.fromCharCode(dv.getUint8(i));
    if (magic !== 'MGTILES1') return;
    const cnt: number = dv.getUint32(8, true);
    for (let i: number = 0; i < cnt; i++) {
      const b: number = 12 + i * 24;
      this.pkIdx.set(`${dv.getUint32(b, true)}/${dv.getUint32(b + 4, true)}/${dv.getUint32(b + 8, true)}`,
                     [dv.getUint32(b + 12, true), dv.getUint32(b + 16, true)]);
    }
    this.pkBuf = buf;
  } catch (e) {
    this.pkBuf = null;
  }
}

绘制时每个屏幕格子按四条路走,顺序不能变:

private drawTiles(ctx: CanvasRenderingContext2D, w: number, h: number): void {
  const ts: number = 256;
  const z: number = this.mapZoom;
  const n: number = Math.pow(2, z);
  const c: number[] = this.centerPx();
  const left: number = c[0] - w / 2;
  const top: number = c[1] - h / 2;
  const x0: number = Math.floor(left / ts), y0: number = Math.floor(top / ts);
  const x1: number = Math.floor((left + w) / ts), y1: number = Math.floor((top + h) / ts);

  for (let ty: number = y0; ty <= y1; ty++) {
    if (ty < 0 || ty >= n) continue;
    for (let tx: number = x0; tx <= x1; tx++) {
      const wx: number = ((tx % n) + n) % n;     // 经度方向环绕
      const key: string = `${z}/${wx}/${ty}`;
      const dx: number = tx * ts - left, dy: number = ty * ts - top;

      const pm: image.PixelMap | undefined = this.tileCache.get(key);
      if (pm !== undefined) {                    // ① 内存缓存
        ctx.drawImage(pm, dx, dy, ts, ts);
        continue;
      }
      if (this.drawFromLower(ctx, z, wx, ty, dx, dy, ts)) {
        // ② 低层级放大:拉 2~16 倍,虽然糊但不断图
      } else {
        this.requestParent(z, wx, ty);           // ③ 主动把父层瓦片拉进缓存
      }
      this.requestTile(key, z, wx, ty);          // ④ 离线包命中则切包,否则走网络
    }
  }
}

“低层级放大"这一段是整个地图体验的关键。离线包只覆盖 z3–z8 全国、z9–z12 成都、z13 核心区;用户把地图拖到没打包的县城、缩放到 z15,屏幕上就会全是空格。放大兜底让每张 z8 瓦片切出 2×2、4×4 的子块分别贴到对应位置,视觉上是"糊了一层”,但地形、道路轮廓、城镇位置都在,完全够用:

private drawFromLower(ctx: CanvasRenderingContext2D, z: number, x: number, y: number,
  dx: number, dy: number, ts: number): boolean {
  for (let d: number = 1; d <= 4; d++) {         // 最多向上找 4 层
    const zz: number = z - d;
    if (zz < 0) return false;
    const scale: number = 1 << d;
    const pm: image.PixelMap | undefined = this.tileCache.get(`${zz}/${Math.floor(x / scale)}/${Math.floor(y / scale)}`);
    if (pm === undefined) continue;
    const span: number = 256 / scale;
    ctx.drawImage(pm, (x % scale) * span, (y % scale) * span, span, span, dx, dy, ts, ts);
    return true;
  }
  return false;
}

在线瓦片只作为最后一层补白,而且带两条保险:并发上限 6,防止快速缩放时打出几百个请求;以及熔断——从没成功过且连续失败 12 次就判定"当前环境无外网",直接关掉在线通道,只留离线底图,界面上标"离线底图"。

private onTileFail(): void {
  this.tileFail++;
  if (this.tileOk === 0 && this.tileFail >= 12) this.tileOff = true;
}

这里把"从没成功过"作为熔断前提很重要。如果只看失败次数,出隧道时的一次抖动就会把在线地图永久关掉。

任务规划页就是这个地图系统加上航点层的样子——左上角是操作区,右侧是可点选的航点列表(序号、类型、经纬度、高度),地图上叠着航线与航点序号:

任务规划页:离线底图 + 航点列表


九、链路调不通时,我做了三个诊断工具

地面站开发 80% 的痛苦在"连不上"。而"连不上"这三个字背后至少有五种完全不同的原因,光看界面是分不清的。所以这个项目里真正花时间的不是写功能,而是把排查路径拆成可观测的层次。

9.1 第一个障碍:权限没声明

鸿蒙的 ohos.permission.INTERNET 是 normal 级权限,不需要弹窗申请,但必须在 module.json5 里声明,否则 socket、http 全部失效,而且报错信息并不友好(表现是"连接失败"或空异常)。

// hap/entry/src/main/module.json5
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:internet_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
  },
  {
    "name": "ohos.permission.GET_NETWORK_INFO",
    "reason": "$string:internet_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
  }
]

GET_NETWORK_INFO 是用来读取本机局域网 IP 的——连接页上要显示"我的地址:192.168.x.x",方便对方(SITL 或 WiFi 数传)反连进来。

9.2 第二个障碍:链路"秒断"

现象非常有欺骗性:界面上"已连接"闪一下,随即变回未连接,日志里是 ECONNRESET。

根因在 UDP 的"连接式"用法。上游 UdpSerial 收到第一个心跳后,会把 socket connect() 到该心跳的源 IP/源端口,之后只用 send/recv 通信。这是 ArduPilot 生态的标准做法(能防止杂包),但它带来一个副作用:如果对端(发心跳的脚本)没有在那个源端口上监听,操作系统会回一个 ICMP port unreachable,接着 recv 抛 ECONNRESET,上游就把整条链路关掉了。

这也解释了为什么"用 Python 随便发几个包"能连上又立刻断。修复方式不是改引擎,而是让发包脚本自己也绑一个端口等着收:

# scripts/mock_heartbeat.py(节选)
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(('0.0.0.0', 0))          # 关键:自己的源端口也要监听,否则回包走 ICMP
src = sock.getsockname()
sock.setblocking(False)

seq = 0
while True:
    sock.sendto(heartbeat_packet(seq), (args.host, args.port))
    seq = (seq + 1) & 0xFF
    deadline = time.time() + 0.5
    while time.time() < deadline:
        try:
            data = sock.recv(4096)   # 把 GCS 回来的心跳收掉
            rx += len(data)
        except BlockingIOError:
            time.sleep(0.02)

9.3 第三个障碍:端口到底有没有 bind

这是最难的一种情况:应用显示"等待心跳",对方在发,但界面上什么也没发生。可能的原因有三种,表现完全一样:

  1. 系统层入向被挡(路由、防火墙、同网段隔离);
  2. 引擎根本没 bind 这个端口(就是 4.4 节那个配置事件问题);
  3. 引擎 bind 了,但包被上游的过滤逻辑丢弃。

为了把这三者区分开,界面上做了两个诊断按钮。

UDP 自测:用系统 socket 在"目标端口 + 1"上收包 30 秒,让 PC 侧把心跳发到这个端口。这一步完全绕开引擎,只验证"系统入向通不通"。

udpSelfTest(): void {
  this.closeUdpTest(false);
  const p: number = Number.parseInt(this.port) + 1;
  this.diagCount = 0;
  this.diagMsg = `监听 0.0.0.0:${p} 30 秒,请在 PC 执行 python scripts/mock_heartbeat.py ${this.localIp} ${p}`;
  const s: socket.UDPSocket = socket.constructUDPSocketInstance();
  this.testSock = s;
  s.on('message', (info: socket.SocketMessageInfo) => {
    this.diagCount = this.diagCount + 1;
    this.diagMsg = `收到 ${this.diagCount} 个 UDP 包,来源 ${info.remoteInfo.address}:${info.remoteInfo.port}`;
  });
  s.bind({ address: '0.0.0.0', port: p, family: 1 });
  this.testTimer = setTimeout(() => this.closeUdpTest(true), 30000);
}

端口诊断:直接读内核的 /proc/net/udp,按十六进制端口号匹配本地地址,顺便把"收包队列字节数"打出来。这个手段在 Linux 上很常规,在鸿蒙上同样可用——沙箱并不禁止读 /proc。

portDiag(): void {
  const port: number = Number.parseInt(this.port);
  const hex: string = port.toString(16).toUpperCase().padStart(4, '0');
  const hits: string[] = [];
  const files: string[] = ['/proc/net/udp', '/proc/net/udp6'];
  let readable: number = 0;

  for (const f of files) {
    try {
      const file = fileIo.openSync(f, fileIo.OpenMode.READ_ONLY);
      const buf: ArrayBuffer = new ArrayBuffer(262144);
      const n: number = fileIo.readSync(file.fd, buf);
      fileIo.closeSync(file);
      readable++;
      const text: string = util.TextDecoder.create('utf-8')
        .decodeToString(new Uint8Array(buf.slice(0, n)));
      const lines: string[] = text.split('\n');
      for (let i = 1; i < lines.length; i++) {
        const parts: string[] = lines[i].trim().split(/\s+/);
        if (parts.length < 5) continue;
        const local: string = parts[1].toUpperCase();
        if (local.length > 5 && local.substring(local.length - 5) === ':' + hex) {
          hits.push(`${f} ${local} 收包队列=${parts[4]}B`);
        }
      }
    } catch (e) {
      hits.push(f + ' 读取被拒');
    }
  }
  this.diagMsg = hits.length === 0
    ? (readable > 0 ? `端口 ${port}:内核里没有该端口的 socket(引擎没 bind)` : '无法读取 /proc/net/udp')
    : hits.join(' | ');
}

两个按钮配合,就把"三种原因"压缩成了一张真值表:

UDP 自测端口诊断结论
收到包有 socket、队列增长链路正常,问题在解析或上游过滤
收到包内核对端口无记录引擎没 bind,回去查 4.4 的配置事件
收不到包有 socket、队列不增长包没进设备,查网络与防火墙
收不到包无记录网络不通,先 ping 通再说

9.4 一个 21 字节的心跳包

没有 SITL 的时候(比如只想验证界面和链路),用一个脚本伪造最小 MAVLink 心跳就够了。这个脚本有两个地方必须写对,否则会出现"包是收到了,但界面永远显示未连接":

# scripts/mock_heartbeat.py(节选)
CRC_HEARTBEAT = 50
MSG_HEARTBEAT = 0

def heartbeat_packet(seq: int) -> bytes:
    # custom_mode=u32, type=2(QUADROTOR), autopilot=3(ARDUPILOTMEGA),
    # base_mode=1(CUSTOM_MODE_ENABLED —— 上游只有该位才解析 mode -> Linked=true),
    # system_status=3(ACTIVE), mavlink_version=3
    payload = struct.pack('<IBBBBB', 0, 2, 3, 1, 3, 3)
    header = bytes([
        0xFD,               # MAVLink v2 STX
        len(payload),       # LEN
        0, 0,               # INCOMPAT_FLAGS / COMPAT_FLAGS
        seq & 0xFF,         # SEQ
        1,                  # SYSID
        1,                  # COMPID 必须非 0,否则被 OpenBg 丢掉
    ]) + struct.pack('<I', MSG_HEARTBEAT)[:3]
    crc = crc16_x25(header[1:] + payload + bytes([CRC_HEARTBEAT]))
    return header + payload + struct.pack('<H', crc)

两个坑:

  • base_mode 必须带 CUSTOM_MODE_ENABLED(0x01)位。上游 MAVLinkInterface 判断"是否已建立链路"时,要求心跳里带自定义模式才去解析 custom_mode,否则 Linked 一直是 false。包收到了、状态机不走,就是这样来的。
  • COMPID 不能为 0。OpenBg 里会丢弃组件号为 0 的心跳。

脚本还带一个 --selftest,用 123456789 的标准 CRC 校验值(0x906E)验证 CRC 实现,避免"协议写错了但看起来在跑"。上面那张终端截图就是它在跑:每 0.5 秒一个心跳,每 20 个打印一次收发计数。

mock 心跳脚本运行现场:按 0.5 s 间隔发送最小 MAVLink 心跳

9.5 把诊断能力做进界面

这些排查手段最后都落成了界面上的"网络诊断"折叠区,而不是停在开发机的临时脚本里。展开后能看到实时收包计数、来源地址、以及上面那两个按钮。

连接页(最大化):链路状态与诊断区

窗口模式下的同一个页面,左侧留出窄边栏放连接方式(UDP / TCP / 串口)、主机、端口,底部是会话状态与心跳计数:

连接页(窗口模式):桌面窗口形态下的布局

这里有个很小但很值的设计:错误原文上屏。stateError() 返回的是引擎侧捕获的 Exception.ToString() 前 160 字,包括 InnerException 链。用户看到的是 System.Net.Sockets.SocketException: Permission denied 这种原文,而不是"连接失败"。前者能直接指向"权限没声明",后者什么也指不出来。


十、做到了什么,没做什么

10.1 功能矩阵

页签能力实现方式
连接UDP 监听 / TCP 连出(串口受沙箱限制)引擎 UdpSerial / TcpSerial / SerialPort
连接会话状态机、等待秒数、错误原文、断线重连NAPI 四态 + 300 ms 轮询
连接UDP 自测、内核端口诊断ArkTS socket + /proc/net/udp
飞行数据姿态(滚转/俯仰/航向)、GPS 定位类型、HDOP、地速/空速、电压、飞行模式Canvas HUD + 遥测卡
飞行数据航迹图(离线底图 + 在线补白 + 父层放大)Canvas + MGTILES1
参数全量拉取、名称过滤、行内编辑、写入结果回显PARAM_REQUEST_LIST → PARAM_SET
任务规划航点列表(序号/类型/经纬度/高度)、读取、上传MISSION_* 状态机
全局窗口三模式(全屏/浮动/分屏)、preferences 持久化、深色配色supportWindowMode + @ohos.data.preferences

10.2 明确不做的事

  • 固件烧写。上游这块要走 USB CDC / bootloader 协议,需要 /dev/ttyACM* 级别的设备节点,鸿蒙应用沙箱不提供。这不是"还没做",是当前系统能力边界。
  • 飞行日志图形分析。上游的 .tlog/.bin 分析是另一套重图形代码(几十个 WinForms 图表控件),与"地面站本体"耦合很松,独立成一个应用更合理。
  • 多机集群管理。上游支持多链路、多机切换,本次只做了单链路单机,接口层(MAVState 按 sysid 索引)保留了扩展余地。
  • 地图在线点选编辑航点。目前航点只能从列表编辑;在地图上点选需要命中测试与拖拽手势,与地图平移手势冲突,留给下一版。

10.3 一笔体量账

部分体量来源
C# 内核(10 个上游项目)451 个 .cs,约 36.9 万行上游原样
引擎门面 Engine.cs453 行项目自写
NAPI 桥 napi_init.cpp360 行项目自写
ArkTS 外壳 Index.ets1670 行项目自写
离线瓦片包2298 张,11.4 MB脚本生成
引擎产物arm64-v8a 20.1 MB / x86_64 19.2 MBNativeAOT

一句话总结这组数字:为了 36.9 万行内核能跑起来,写了约 2500 行胶水与外壳。这就是 T1 的成本结构——不含界面重画的体力活,真正的难点全在"胶水"上。


十一、QA

Q1:为什么不直接用 MAVSDK 或者 QGC 的 C++ 内核,而要从 C# 搬?

因为"与 Windows 版行为一致"是地面站最值钱的属性。MAVSDK 是另一套独立实现,参数元数据、任务协议的重传边界、机型到模式名的映射表,与 Mission Planner 的 ArduPilot 项目并非逐条对齐。QGC 是 Qt 应用,搬到鸿蒙等于把整套 Qt so 拖进来,退回 T0。搬上游自己的内核,才能保证同一个 custom_mode=3 在两边显示同一个模式名。

Q2:20 MB 的 so 还能再瘦吗?

已经开的开关:TrimMode=full(体积减半的主要来源)、OptimizationPreference=Size、StripSymbols、EventSourceSupport=false、InvariantGlobalization=true。还能再动的只有两处:关掉 IlcGenerateStackTraceTable(会丢异常行号,不建议)、收窄 keep.xml 的保留粒度(MAVLink 消息表按程序集整段保留,再细分风险很高)。老实说,20 MB 对一个自带完整 MAVLink 协议栈与参数元数据的引擎,不算胖。

Q3:300 ms 轮询会不会漏掉瞬时事件?

对"状态量"不会——姿态、电压、模式这些都是绝对值,读到最后一次就是对的。飞控心跳本来就是 1 Hz,50 Hz 的姿态流人眼也不需要逐帧。真正有瞬时性的东西(飞控发来的 STATUSTEXT 告警)需要的是队列而不是快照,那就得加一个"取走即清空"的事件接口,而不是回调。这也是为什么当初不选回调:回调在页面销毁后触发是崩溃高发区,队列则由 UI 主动取,天然安全。

Q4:参数动辄上千条,界面怎么不卡?

引擎一次 PARAM_REQUEST_LIST 拿到全部参数,一次性序列化成 JSON。界面侧只在"用户点了刷新"时取一次,之后靠本地过滤:filteredParams() 按名字 includes 过滤,List 负责滚动虚拟化。千级规模实测流畅;如果将来要支持上万条(某些机型确实有),需要换成 LazyForEach + 分批渲染。

Q5:任务上传失败,怎么判断是哪一步的问题?

任务协议是四步状态机,每一环失败的表现不同:发了 MISSION_COUNT 收不到 MISSION_REQUEST → 链路单向或对端不支持;收到 REQUEST 但序号对不上 → 重传逻辑生效但底层丢包;四步走完没收到 MISSION_ACK → 飞控主动拒绝(最常见是航点高度/半径越界)。所以界面上要把每一步的返回码原样显示出来,而不是笼统的"上传失败"。

Q6:能连真飞控吗?

UDP 与 TCP 通路上,SITL 与真飞控的行为一致(真飞控接 WiFi 数传就是 UDP/TCP),所以协议层不需要改动。串口通路受限于沙箱——应用没有 /dev/ttyUSB* 之类的设备节点访问权限,这也是"不做固件烧写"的同一条边界。

Q7:没有 DataGrid,参数表怎么搭?

ArkUI 没有 WinForms 那种 DataGridView。参数表和航点表都是手搭的:表头一个 Row,下面 List,每行一个 Row,列宽用固定常量(名字 45%、数值 30%、操作 25%),行高固定。进入编辑态时,把该行的数值 Text 原位换成 TextInput,提交后换回来——比"弹窗编辑"少一次上下文切换。

Q8:为什么地图不用矢量瓦片?

矢量瓦片要运行时解析 PBF、加载字体与精灵图、再跑一套样式引擎,等于把 MapLibre 搬进来。而栅格方案 11 MB 换来了"零依赖、断网可用、渲染路径只有 drawImage",对地面站这个场景明显更划算。真要上矢量,正确路径是在引擎侧加一个 C++ tile 解析器,而不是在 TS 里硬啃 protobuf。

Q9:离线包太大/太小,能自己裁剪吗?

能,三个脚本就是流水线:fetch_tiles.py 里改 ROI 的 bbox 与 zoom 范围,重新下载 → pack_tiles.py 打包 → verify_pack.py 校验索引与文件长度一致。换一个省的成本大概是一次下载加一次打包,几分钟量级。

Q10:上游发新版本怎么跟?

third_party/MissionPlanner 是"上游代码 + 少量补丁"的结构,我们自己的改动集中在 Engine.cs、keep.xml、.csproj 三个文件里。升级时把上游 tag diff 出来,逐个确认这三个文件,其余目录整段替换。这就是 T1 的持续成本:不是零,但每一版只花在看三个文件上。

Q11:GPL-3.0 会不会限制分发?

会。上游是 GPL-3.0,派生作品必须同样以 GPL-3.0 开源,本项目仓库因此也带完整 LICENSE 并公开源码。若要做闭源商业分发,需要另外获得上游授权——这是法律问题,不是技术问题。

Q12:签名材料放在哪?为什么仓库里没有?

不入库。build-profile.json5 里的 signingConfigs 在仓库版本里是空数组,.p12/.p7b/.cer 与口令全部本地保存。DevEco 的自动签名会把本机绝对路径与加密口令写回这个文件,一旦提交就等于泄露私钥。所以克隆后第一步永远是"自己生成一份签名"。另外要记住一个坑:自动签名只写 signingConfigs,不会往 products[0] 里补 signingConfig,漏了这一行会产出 unsigned HAP,安装报 9568320 no signature file。

十二、最后

这个项目真正的收获不是"又一个应用上了鸿蒙",而是验证了一件更具体的事:当上游是一套语义复杂的原生代码时,"保留内核 + 重写外壳"是唯一能同时保住行为一致性与系统体验的路线。

它的代价也很清楚——最难的部分不是界面,而是那些看起来不像代码的地方:一个静态事件订阅把配置读走了、一个 socket 被 connect() 之后对端不监听就断链、一个 TrimMode=full 让反射表静默消失、一个 base_mode 的位决定"已连接"还是"未连接"。这些东西没有文档,只能靠一层层把可观测性做出来,再一项项排除。

ArduPilot 生态二十年的积累,值得用这种方式搬一次;而搬完之后它确实是原生的——不是套在容器里的一个窗口,而是能跟着系统一起分屏、一起深色、一起用键盘的一个应用。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐