簡介面向Airoha洛達AB1568藍牙耳機應用開發(fā)的PDF技術文檔適合TWS耳機固件、嵌入式藍牙開發(fā)及方案定制崗位的工程師與進階學習者用于建立從硬件啟動到應用層功能落地的完整知識框架。壓縮包內僅含1個PDF文件大小約9.58MB內容按工程專題組織覆蓋上電執(zhí)行函數、mk文件宏定義、app活動行為、ANC模式切換、LED呼吸燈、充電參數監(jiān)測、超時與事件管理、Airoha API、回調注冊、自動關機、配對時間、開機提示電量、清除配對列表、鏈路重連、UI Shell、SideTone、音頻路徑、DUT測RF、硬件復位、PEQ及通話降噪等模塊。已有374人學習可作為項目開發(fā)與調試時按問題檢索的參考手冊。其目錄結構將芯片啟動、事件驅動、降噪算法與低功耗配置串聯起來便于讀者對照接口文檔和模塊實現排查細節(jié)、補齊知識短板適合作為開發(fā)過程中的案頭查詢資料。1. 一個按鍵按下去為什么要在四個模塊里繞一圈做 Airoha AB1568 藍牙耳機開發(fā)最容易翻車的不是降噪算法而是一條按鍵事件到底走了幾層才落到濾波器上。三連擊 POWER 鍵提示音響了模式也切了耳朵里卻一點變化都沒有——這個現象背后壓著三件事編譯期的宏有沒有把代碼編進去、UI Shell 的活動有沒有收到這條事件、NVR 里的參數有沒有真的寫進芯片。把這三層拆開看耳機固件的黑匣子就打開了一半剩下的都是細節(jié)。2. 上電第一行代碼宏在哪個 mk 文件里決定哪段代碼存在很多人調固件的第一反應是打開工程找main然后發(fā)現自己改的那段代碼根本沒有被編譯。AB1568 的啟動流程是兩段式的上電后先跑apps目錄下 bootloader 的main再由它把控制權交給apps下對應工程earbuds或headset的main最后由apps_inits把各種應用模塊拉起來。這條流水線上每一段都可能被條件編譯掐斷而決定掐不掐的那個開關不在.c文件里在 GCC 目錄下的某個 mk 文件里。理解這件事的價值在于它把你對“代碼為什么沒生效”的排查順序從“翻代碼”改成“先確認這段代碼是否存在于最終鏡像”。嵌入式里最貴的 bug 不是邏輯寫錯而是邏輯壓根沒進二進制。2.1 兩段 main 的接力與條件編譯的斷點bootloader 的 main 負責的是很底層的事時鐘、電源、存儲介質自檢然后判斷要不要進 FOTA 流程。這個判斷本身也是條件編譯的——只有在 GCC 目錄下的 mk 文件里定義了BL_FOTA_ENABLEbl_fota_process這個函數才會被編譯成真正的代碼。也就是說你把升級邏輯寫得再漂亮宏沒開那段函數體在預處理階段就被整段抹掉了鏈接器連符號都看不見。常見的實現思路是mk 文件里的CFG_XXX y這類寫法最終會被構建腳本翻譯成編譯命令行的-DXXX交給預處理器。所以“宏定義在哪里”這個問題的答案永遠是“在本次編譯實際引用的那個 mk 文件里”而不是“在工程目錄里搜到的那個”。/* 這段代碼是否存在于固件取決于 BL_FOTA_ENABLE 是否在本次編譯的 mk 中被定義 */ #ifdef BL_FOTA_ENABLE /* 只有宏打開時這個函數體才會被編譯器看到 */ bl_fota_process(); #endif上面這段沒有參數需要解釋重點在語義#ifdef之外是運行時判斷#ifdef之內是編譯期存在性判斷。前者錯了能在 log 里看到分支沒走后者錯了連 log 都不會有因為那段代碼不存在。這也是為什么“加了打印卻沒輸出”有時候根本不是串口問題。進到應用層之后apps_inits統(tǒng)一初始化各應用模塊其中就包含所有活動行為的初始化。初始化順序在這里是有講究的誰先注冊事件組誰就能更早收到開機階段拋出的廣播事件。順序不對你會看到某些模塊在開機頭幾百毫秒里“反應遲鈍”而幾百毫秒之后一切正?！@類現象很容易被當成玄學。2.2 build.sh list宏到底落在哪個 mk同一套 SDK 里通常并存多個板級工程和多個產品工程編譯哪個工程、用哪個 mk由構建腳本的參數決定。先列出來看清楚比在目錄里翻文件可靠得多。# 列出當前 SDK 支持的編譯目標以及每個目標實際引用的 mk 文件 ./build.sh list # 輸出里重點看兩列工程名、對應的 feature_xx.mk # 當前頭戴耳機基于 ab1565_ab1568_evk 開發(fā)板衍生 # 對應到 ab1568_evk 板級下的 headset_ref_desgin 工程 # 該工程編譯時引用的是 feature_68_evk 這個 mk命令本身只有一句關鍵是讀輸出的方式不要只看工程名匹配要看板級前綴。ab1565_ab1568_evk是開發(fā)板名ab1568_evk是落到具體芯片型號的板級目錄產品工程名headset_ref_desgin只是它的一個子項。三者對不上你改的 mk 就不是本次編譯用的那個。確認之后打開feature_68_evk.mk能看到現成的宏定義也可以往里加新的。比如 ANC 相關的MTK_ANC_ENABLE在這個文件里已經是開啟狀態(tài)——這意味著 ANC 的按鍵處理分支是存在的問題不可能出在“沒編進去”這一層。這個判斷很省時間一次確認直接排除掉一整類可能性。2.3 增量編譯與 mk 變更的沖突改 mk 之后不 clean 就 build是血淚經驗級別的坑。構建系統(tǒng)對.c文件的依賴關系跟蹤得很細但對 mk 文件的變更往往只做粗粒度判斷甚至完全依賴時間戳。結果就是宏已經改了目標文件卻沒重新生成你燒進去的還是舊鏡像。# 改過任何 mk 文件之后的標準動作 ./build.sh clean ./build.sh ab1568_evk headset_ref_desgin這兩條命令的含義很直白但順序不能省。clean清掉的是中間產物和最終鏡像確保下一次編譯完整展開所有 mk。省掉它的代價是幾十分鐘的迷惑你明明改了宏行為卻一點沒變于是開始懷疑芯片、懷疑工具鏈、懷疑人生。另外一個細節(jié)是宏的作用域。寫在 mk 里的宏是全局的寫在某個模塊自己的 mk 片段里的宏只影響該模塊。同一個宏名在兩處出現且值不同最終生效的取決于鏈接順序和包含順序這種沖突不會有任何警告。所以新增宏之前先在feature_68_evk.mk里搜一遍名字比事后查行為異常便宜得多。3. UI Shell 事件框架一條事件為什么所有活動都能收到耳機固件里最像“操作系統(tǒng)”的部分就是這套 UI Shell。它把一個個界面抽象成活動activity每個活動有自己的事件組和處理函數。系統(tǒng)產生事件時不是點對點投遞而是把事件拋出去所有活動都能監(jiān)聽到屬于自己事件組的才處理。這個設計看著低效實際上解決了嵌入式 UI 里最麻煩的問題狀態(tài)切換時的責任歸屬。3.1 活動棧ui_shell_start_activity 申請的那個 itemui_shell_start_activity做的事情是在活動棧里申請一個空閑 item把活動的描述結構掛上去。這個棧決定了“誰在前臺”。app_preproc_activity_proc是主進程負責管理和調配其它子進程比如app_home_screen_idle_activity_proc這類具體界面。開機后系統(tǒng)會拉起很多不同的進程每個進程里有不同的事件組形成一張扁平的監(jiān)聽網。/* 活動的事件處理表事件組 ID 與處理函數的對應關系 */ static const ui_shell_event_handler_t home_screen_handlers[] { { KEY_EVENT_GROUP, app_home_screen_proc_key_event_group }, /* 按鍵類事件 */ { ANC_EVENT_GROUP, app_home_screen_proc_anc_event_group }, /* ANC 狀態(tài)變化 */ { TIMER_EVENT_GROUP, app_home_screen_proc_timeout_event }, /* 超時類事件 */ }; /* 啟動活動在活動堆里申請一個空閑 item并把處理表注冊進去 */ ui_shell_start_activity(app_home_screen_idle_activity_proc, home_screen_handlers, ARRAY_SIZE(home_screen_handlers), false);上面兩個調用的語義是先聲明“我關心哪幾類事件、分別交給誰處理”再聲明“我現在進入活動?！薄５谌齻€參數是處理表長度最后一個布爾量在不同 SDK 版本里可能是“是否獨占前臺”之類的開關入參順序也常有調整理解成“注冊范圍 前臺聲明”這兩件事就夠了。真正要記住的是處理表在注冊時就被固定下來活動運行期間不會再變。3.2 事件的三段式send、init_input_msg、remove事件的生命周期被拆成三個明確的動作。ui_shell_send_event負責投遞攜帶事件組、事件 ID、payload 大小和優(yōu)先級ui_shell_init_input_msg是接收側的統(tǒng)一入口把底層消息隊列里的事件取出來分派給活動ui_shell_remove_event則是后悔藥——把還沒被消費的事件從隊列里摘掉。/* 投遞一條按鍵事件不來自中斷、優(yōu)先級普通、屬于按鍵事件組 */ ui_shell_send_event(false, /* 是否來自中斷上下文 */ EVENT_PRIORITY_NORMAL, KEY_EVENT_GROUP, /* 事件組決定誰來處理 */ KEY_EVENT_ANC_SWITCH, /* 事件 ID具體是什么事 */ payload, /* 附帶數據可為 NULL */ sizeof(payload), NULL, 0); /* 后悔藥場景已經切換舊事件不該再被處理 */ ui_shell_remove_event(KEY_EVENT_GROUP, KEY_EVENT_ANC_SWITCH);參數里最關鍵的是事件組和事件 ID 的組合。事件組是路由依據事件 ID 是業(yè)務依據。同一個事件 ID 掛在不同事件組下會走到完全不同的處理函數這種“同名不同命”的情況在多人協作的工程里非常常見也是事件丟了的經典原因。false這個參數表示調用上下文不是中斷如果你在中斷里直接發(fā)事件并傳true行為會更接近“延后到安全上下文處理”。傳錯的后果不是崩潰而是偶發(fā)的、難復現的事件丟失。3.3 廣播式投遞的代價與邊界廣播的好處是解耦新增一個活動不需要修改發(fā)送方。代價是每個活動都要對不屬于自己的事件做一次快速丟棄而且“誰在前臺誰處理”這條隱含規(guī)則沒有被框架強制。當兩個活動同時存在于棧上、又都注冊了同一個事件組就會出現同一條按鍵被處理兩次的現象——比如降噪模式連跳兩格。ui_shell_remove_event的存在就是為了補這個洞在狀態(tài)切換的瞬間把上一條還沒被消費完的事件摘掉避免它在新的上下文里被執(zhí)行。我一般會這么理解這套框架廣播負責“送達”活動棧負責“當前誰該管”remove負責“別管過期的”。三者缺一個行為就會在某些邊角場景里歪掉。判斷一條事件有沒有人處理最直接的辦法是在ui_shell_init_input_msg的分派路徑上加一行 log打印事件組和事件 ID。有投遞記錄但沒有處理記錄說明當前棧上沒有活動注冊該事件組兩者都有但業(yè)務沒反應問題就在處理函數內部跟框架無關。這條分界線劃清楚排查效率會差好幾倍。4. ANC 模式切換從 key_action 到 ANC 濾波器組ANC 是耳機固件里鏈路最長的一個功能它橫跨按鍵、事件框架、服務層和聲學參數四層。任何一層斷掉用戶聽到的都是“沒效果”但從代碼上看每一層都“跑過了”。4.1 硬件通路FF、FB、FBC 和主麥各管什么音頻通路分 Line-in 和 BT 兩種輸入。降噪側用的是 FF 麥前饋朝外拾環(huán)境噪和 FB 麥反饋朝耳道拾殘余噪FBC 是 FB 的補償通路。整機上有 4 個麥克風用于降噪另有 1 個主麥負責說話拾音配 2 個振動喇叭和 2 個聲音喇叭。分工很清楚ANC 降噪用 FF 和 FB通話降噪用 talk 麥加 FF。config tool 上有三個參數頁ANC含 FF 與 FB、FBC、Passthrough通透。它們和用戶感知的“模式”不是一一對應關系模式是給用戶按的參數頁是給聲學工程師調的。一個 ANC 模式背后會同時用到 ANC 頁和 FBC 頁的參數通透模式背后是 Passthrough 頁的參數。把這層關系理順才看得懂后面濾波器編號的分配邏輯。4.2 key_action 的四種語義與映射文件按鍵事件進來后先進_proc_key_event_group處理。這條路徑能不能走通前提是MTK_ANC_ENABLE已經打開——在feature_68_evk.mk里確認過是開的。所有 ANC 相關行為最終都收斂到app_home_screen_process_anc_and_pass_through這一個函數里靠key_action的值區(qū)分意圖。/* key_action 的四種語義對應 config tool 里配置的按鍵行為 */ switch (key_action) { case KEY_ANC: /* 單純 ANC 開 / 關不碰通透 */ target_anc_type (target_anc_type ANC_OFF) ? ANC_ON : ANC_OFF; break; case KEY_PASS_THROUGH: /* 單純通透開 / 關 */ target_anc_type (target_anc_type PT_OFF) ? PT_ON : PT_OFF; break; case KEY_SWITCH_ANC_AND_PASSTHROUGH: /* 三段循環(huán)全關 - 通透 - ANC */ target_anc_type next_in_cycle(target_anc_type); break; case KEY_BETWEEN_ANC_PASSTHROUGH: /* 兩段來回只在通透和 ANC 之間切 */ target_anc_type (target_anc_type ANC_ON) ? PT_ON : ANC_ON; break; } /* 模式和濾波器 ID 一起下發(fā)服務層據此選參數組 */ app_anc_service_enable(target_anc_type, target_filter_id);四個分支的差別不在代碼量而在狀態(tài)機的拓撲三段循環(huán)有三個穩(wěn)定態(tài)兩段切換只有兩個。選錯語義用戶按三下會回到原點或者卡在通透出不來——這類“手感問題”最后都會被當成 bug 報上來。按鍵行為和key_action的綁定寫在customerized_key_config.c里。這個文件是產品差異化的集中地不同客戶的長按、雙擊、三連擊語義都在這里分叉。改這里之前先確認MTK_ANC_ENABLE否則你會改了一個根本不會被編譯進去的分支。4.3 app_anc_service_enable模式與濾波器枚舉的對應服務層拿到target_anc_type和target_filter_id后去 NVR 里取對應的參數組下發(fā)給 DSP。濾波器用枚舉表示AUDIO_ANC_CONTROL_ANC_FILTER_DEFAULT的值是 1AUDIO_ANC_CONTROL_PASS_THRU_FILTER_DEFAULT的值是 9。這兩個數字不是隨手寫的它們對應 NVR 里參數塊的編號。NVR 里的濾波器按四組組織每組包含左右耳各一套組內容說明Filter 1FF1(L/R) FB1(L/R) FBC1(L/R)第一組 ANC 參數Filter 2FF2(L/R) FB2(L/R) FBC2(L/R)第二組 ANC 參數Filter 3FF3(L/R) FB3(L/R) FBC3(L/R)第三組 ANC 參數Filter 4FF4(L/R) FB4(L/R) FBC4(L/R)第四組 ANC 參數把 tool 界面上的 L 和 R 疊在一起看四組結構的對稱性就出來了。切換 ANC 模式時看 loganc_result里三個模式循環(huán)出現每次都會帶上當前使用的 filter id。這個字段是排查“切了但沒效果”的第一手證據id 變了說明鏈路通到了服務層沒變說明卡在按鍵或狀態(tài)機。4.4 NVR 參數從 config tool 到芯片的那一段三連擊 POWER有提示音沒有降噪效果——這是最典型的一類現象。原因往往極其樸素用 config tool 打開工程的download目錄ANC 模式下的參數是空的。代碼路徑全對參數沒寫DSP 拿到的是一組零。修復流程是把聲學調好的 ANC 參數nvr 文件導入工程或者直接在 tool 上調整然后先 Write NV 再 Reset把 FF、FB、FBC 和 AiroThru 參數寫進耳機。之后循環(huán)三連擊能聽出不同模式的降噪差異才算真正打通。參數寫進去之后還需要能讀懂它。NVR 里的數值是高字節(jié)在前并且用有符號定點表示直接按十六進制讀會得到離譜的結果。def parse_component_gain(word: str) - float: 解析 NVR 里的 component gain 字段返回 dB 值 # 芯片存儲是高字節(jié)在前先按字節(jié)反轉 swapped bytes.fromhex(word)[::-1].hex() raw int(swapped, 16) # 有符號 16 位超過 0x7FFF 說明是負數減 65536 還原 if raw 0x7FFF: raw - 0x10000 return raw / 100.0 # 單位是 0.1 dB換算成 dB # 以 0xE1E5 10FF 1400 D8DC D8DC 為例 print(parse_component_gain(10FF)) # -2.4 dB對應 component gain -240 print(parse_component_gain(1400)) # 0.2 dB對應 component gain 20關鍵在兩步字節(jié)反轉和有符號還原。10FF反轉成FF10十進制是 65296減 65536 得 -240除以 100 就是 -2.4 dB。1400反轉成0014十進制 20不用減直接是 0.2 dB。后面兩段D8DC D8DC按同樣的規(guī)則解讀字段順序照著 tool 里顯示的順序讀就行。這套解析邏輯值得單獨寫成腳本的原因很實際調音階段你會反復對比“tool 里顯示的”和“芯片里存的”是否一致。手算一次兩次還行改十幾次參數之后必然出錯而錯的方向還挺隱蔽——正負號搞反降噪曲線就整條翻過來。5. 排查清單ANC 沒效果、宏不生效、參數回滾的五個常見坑這一章的五條記錄都來自實際調試現場共同點是代碼看起來沒問題現象卻穩(wěn)定復現。每條按現象、原因、解決三段寫方便對號入座。5.1 有提示音、沒降噪參數沒寫進芯片現象三連擊 POWER 鍵提示音響了log 里anc_result也在三個模式之間循環(huán)但左右耳聽感完全沒變化。原因用 config tool 打開工程download目錄ANC 模式下沒有參數。代碼路徑通了服務層也執(zhí)行了但下發(fā)給 DSP 的是一組全零系數。降噪算法在零系數下等價于直通所以“切了等于沒切”。解決導入聲學調好的 nvr 文件或者直接在 tool 上調整 ANC、FBC、Passthrough 三頁參數然后 Write NV再 Reset。重置這一步不能省部分參數在初始化階段才被讀取不 Reset 就只能等下次上電。驗證方式是循環(huán)三連擊聽感上能區(qū)分出不同模式的降噪強度差異。5.2 改了宏沒生效改的不是本次編譯的 mk現象在某個 mk 文件里加了宏定義重新編譯燒錄行為毫無變化或者鏈接時報某個符號未定義。原因工程里存在多個 mk 文件本次編譯實際引用的是另一個。比如產品工程是headset_ref_desgin板級前綴是ab1568_evk最終落到feature_68_evk這個 mk而你改的是隔壁板級目錄下的同名文件。解決先跑./build.sh list從輸出里確認工程名與 mk 的對應關系再去改那個文件。改完必須 clean 再 build因為 mk 變更不一定觸發(fā)目標文件重建。符號未定義這個報錯反而是好事它至少告訴你“這段代碼確實被條件編譯切掉了”最怕的是行為靜默改變連報錯都沒有。5.3 參數回滾只改了 download沒改 XML 和 bin現象參數在 tool 里調好了也 Write NV 驗證過效果。重新編譯工程、燒錄之后ANC 又回到舊參數。原因Write NV 寫的是耳機里的 NVR 區(qū)不是工程代碼。重新編譯會用工程里的 XML 和filesystem.bin重新生成download目錄把之前的改動覆蓋掉。有一批 NV key 是存在filesystem.bin里的光改 XML 不換 bin參數只更新一半。解決用 Special_Export 導出變更到文件會得到 4 個文件用 Save 方式保存成 download 則是 3 個文件其中 syskey 和 bin 是一致的。把導出的syskey.xml里變更的 key 逐個更新到工程的幾個nvkey.xml中——注意syskey.xml里有的 keyIDnvkey.xml里不一定有沒有的要新增已有的要替換比如 ANC 參數涉及的0xEE00~0xEEFF段在nvkey.xml里就沒有。同時替換filesystem.bin再 clean build。5.4 按鍵無響應事件發(fā)出去了沒人接現象按鍵 log 有ui_shell_send_event也調了處理函數里的斷點卻從不命中。換個界面再按偶爾又能響應。原因事件是廣播的但只有當前處于活動棧前臺、且注冊了對應事件組的活動才會處理。當前如果停在配對界面或產測界面home screen 的處理表根本沒參與分派。另一種情況是事件組 ID 用錯發(fā)到了另一個組名下。解決在ui_shell_init_input_msg的分派路徑上打一行 log同時打印事件組和事件 ID對比活動注冊表里的事件組。有投遞無分派就是路由問題有分派無業(yè)務響應才是處理函數的問題。另外在狀態(tài)切換的地方補ui_shell_remove_event把過期事件摘掉避免它在新上下文里被誤執(zhí)行。5.5 超時時間不準tick 單位和宏的換算現象自動關機、配對超時、鏈路丟失重連這些功能實際觸發(fā)時間跟配置值對不上有時差好幾倍。原因配置項的單位是毫秒底層定時器按 tick 計數中間有一次換算。有人在宏里直接填了毫秒數卻沒走換算宏或者在改 tick 頻率之后忘了同步改配置值。解決把所有超時相關的宏集中看一遍確認單位是毫秒還是 tick換算系數跟當前 tick 頻率是否匹配。驗證方式是掐表設一個 30 秒的超時實際測一次觸發(fā)點差一個數量級就是單位問題差幾秒就是 tick 精度問題。自動關機還涉及關機前的提示音和 LED 狀態(tài)收尾時間設置過短會在提示音播到一半時斷電聽感上像是“關機有雜音”。6. 參數固化還是 FOTA 下發(fā)NVKEY 的兩條路怎么選ANC 參數最終要落到耳機里有兩條路編譯進固件或者通過 FOTA 更新 NV key。兩者的取舍不在技術難度而在迭代節(jié)奏。維度固化到 XML/binFOTA 更新 NVKEY生效時機整包燒錄后生效單獨下發(fā)不用重燒固件產線適配量產程序直接編譯一致性好需要額外的下發(fā)工具鏈迭代速度慢每次改參數都要 clean build快適合調音階段反復試回滾成本重燒整包再下發(fā)一次舊參數調音階段我傾向于走 FOTA/Write NV 這條路改一次參數聽一次效果不用等編譯。定版之后必須固化到 XML 和filesystem.bin讓產線拿到的每一臺耳機參數完全一致——參數固化到代碼里的價值不是“省事”而是“可復現”。驗證是否真的固化了方法很樸素clean build 生成新的download用 config tool 打開看 ANC 參數是不是剛才導入的那一版如果不是說明 XML 沒更新全或者filesystem.bin沒替換。再狠一點的驗證是把耳機擦除后重新燒錄讀回 NV key 跟預期值逐字節(jié)比對比肉耳聽降噪靠譜得多。踩過一次坑之后我就養(yǎng)成了習慣每次改 NV 參數先問自己一句“這是要驗證還是要定版”驗證走 Write NV定版走 Special_Export XML/bin 替換兩條路絕不混用。混用的后果是某天發(fā)現倉庫里的參數和產線耳機對不上而沒人記得是哪次改的。從那以后我每次動 NV key 都強制走一遍“導出、更新 XML、替換 bin、clean build、tool 復核”這五步一步不跳。希望幫到你。本文還有配套的精品資源點擊獲取