QMK 固件 IS31FL3737 驅(qū)動(dòng)完全指南I2C 12×12 LED 矩陣芯片的配置、接線映射與 API 詳解【免費(fèi)下載鏈接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families項(xiàng)目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文圍繞 QMK 固件倉(cāng)庫(kù)中 Lumissil IS31FL3737 驅(qū)動(dòng)docs/drivers/is31fl3737.md展開(kāi)系統(tǒng)講解這款 I2C 12×12 LED 矩陣芯片在鍵盤(pán)固件中的啟用方式、I2C 地址配置、PWM 頻率與去鬼影電阻調(diào)節(jié)、LED 輸出映射以及驅(qū)動(dòng)層完整的 C API。讀完本文你將能夠獨(dú)立為單色背光LED Matrix或 RGB 矩陣RGB Matrix鍵盤(pán)接入 IS31FL3737并理解驅(qū)動(dòng)源碼層面的緩沖與分頁(yè)機(jī)制。一、芯片與驅(qū)動(dòng)概覽IS31FL3737 是 Lumissil 出品的一款 I2C 接口 12×12 LED 矩陣驅(qū)動(dòng)芯片數(shù)據(jù)手冊(cè)見(jiàn) IS31FL3737 Datasheet。QMK 對(duì)它的支持具有以下能力邊界最多支持4 片IS31FL3737 級(jí)聯(lián)每片芯片可驅(qū)動(dòng)144 顆單色 LED每片芯片也可按 RGB 方式驅(qū)動(dòng)48 顆 RGB LED每顆占用 R/G/B 三個(gè)通道驅(qū)動(dòng)代碼位于 drivers/led/issi/ 目錄包含單色is31fl3737-mono.c/.h與 RGBis31fl3737.c/.h兩套實(shí)現(xiàn)。在 QMK 中IS31FL3737 并非只能裸調(diào)當(dāng)你通過(guò)RGB_MATRIX_IS31FL3737或LED_MATRIX_IS31FL3737選項(xiàng)使用 RGB Matrix 或 LED Matrix 功能時(shí)驅(qū)動(dòng)會(huì)被自動(dòng)編譯并通過(guò)統(tǒng)一的驅(qū)動(dòng)接口間接調(diào)用。以 quantum/rgb_matrix/rgb_matrix_drivers.c 為例is31fl3737_init_drivers、is31fl3737_flush、is31fl3737_set_color、is31fl3737_set_color_all被注冊(cè)為驅(qū)動(dòng)回調(diào)單色路徑quantum/led_matrix/led_matrix_drivers.c則注冊(cè)is31fl3737_set_value與is31fl3737_set_value_all。二、啟用驅(qū)動(dòng)獨(dú)立使用與隨特性自動(dòng)編譯2.1 通過(guò) LED/RGB Matrix 自動(dòng)引入如果你的鍵盤(pán)已經(jīng)啟用了 LED Matrix 或 RGB Matrix 功能并在配置中把驅(qū)動(dòng)指定為is31fl3737那么驅(qū)動(dòng)源碼會(huì)被構(gòu)建系統(tǒng)自動(dòng)加入無(wú)需手動(dòng)編寫(xiě)rules.mk。此時(shí)請(qǐng)直接使用 LED/RGB Matrix 提供的 API 操作燈光效果。2.2 獨(dú)立使用Standalone如果需要繞過(guò)矩陣特性、直接操作驅(qū)動(dòng)請(qǐng)?jiān)阪I盤(pán)的rules.mk中添加COMMON_VPATH $(DRIVER_PATH)/led/issi SRC is31fl3737-mono.c # For single-color SRC is31fl3737.c # For RGB I2C_DRIVER_REQUIRED yes其中單色鍵盤(pán)添加is31fl3737-mono.cRGB 鍵盤(pán)添加is31fl3737.c兩者也可按需同時(shí)保留但通常二選一I2C_DRIVER_REQUIRED yes會(huì)拉入 QMK 的 I2C 主控層對(duì)應(yīng) drivers/i2c_master.h這是驅(qū)動(dòng)與芯片通信的前提。三、基礎(chǔ)配置項(xiàng)啟用驅(qū)動(dòng)后在鍵盤(pán)的config.h中按需定義以下宏DefineDefaultDescriptionIS31FL3737_SDB_PINNot defined連接到驅(qū)動(dòng)芯片 shutdown 引腳的 GPIOIS31FL3737_I2C_TIMEOUT100I2C 傳輸超時(shí)時(shí)間毫秒IS31FL3737_I2C_PERSISTENCE0I2C 傳輸失敗后的重試次數(shù)IS31FL3737_I2C_ADDRESS_1Not defined驅(qū)動(dòng) 0 的 I2C 地址IS31FL3737_I2C_ADDRESS_2Not defined驅(qū)動(dòng) 1 的 I2C 地址IS31FL3737_I2C_ADDRESS_3Not defined驅(qū)動(dòng) 2 的 I2C 地址IS31FL3737_I2C_ADDRESS_4Not defined驅(qū)動(dòng) 3 的 I2C 地址IS31FL3737_PWM_FREQUENCYIS31FL3737_PWM_FREQUENCY_8K4_HZLED 的 PWM 頻率僅 IS31FL3737B 支持IS31FL3737_SW_PULLUPIS31FL3737_PUR_0_OHMSWx引腳的上拉電阻值IS31FL3737_CS_PULLDOWNIS31FL3737_PDR_0_OHMCSx引腳的下拉電阻值IS31FL3737_GLOBAL_CURRENT0xFF全局電流控制值0~255上述默認(rèn)值在源碼 drivers/led/issi/is31fl3737.c 中通過(guò)#ifndef ... #define ...方式兜底定義這意味著即使你不寫(xiě)這些宏驅(qū)動(dòng)也能以默認(rèn)參數(shù)工作。3.1 硬件相關(guān)IS31FL3737_SDB_PINIS31FL3737_SDB_PIN用于控制芯片的 shutdown 引腳。定義后驅(qū)動(dòng)在is31fl3737_init_drivers()中會(huì)先把該引腳配置為輸出并拉高見(jiàn) drivers/led/issi/is31fl3737.c使芯片退出硬件關(guān)斷狀態(tài)。未定義時(shí)驅(qū)動(dòng)跳過(guò)該步驟需要硬件上自行處理 SDB 引腳。3.2 I2C 可靠性參數(shù)IS31FL3737_I2C_TIMEOUT單次 I2C 寫(xiě)操作的超時(shí)閾值默認(rèn) 100 msIS31FL3737_I2C_PERSISTENCE傳輸重試次數(shù)默認(rèn) 0不重試。設(shè)置為大于 0 時(shí)源碼會(huì)循環(huán)嘗試直至成功或耗盡次數(shù)見(jiàn)is31fl3737_write_register()中基于#if IS31FL3737_I2C_PERSISTENCE 0的分支drivers/led/issi/is31fl3737.c。四、I2C 尋址配置IS31FL3737 根據(jù)ADDR引腳的接法可選用4 種 7 位 I2C 地址。在config.h中將IS31FL3737_I2C_ADDRESS_nn 為驅(qū)動(dòng)索引 1~4設(shè)為下列值之一DefineValueIS31FL3737_I2C_ADDRESS_GND0x50IS31FL3737_I2C_ADDRESS_SCL0x55IS31FL3737_I2C_ADDRESS_SDA0x5AIS31FL3737_I2C_ADDRESS_VCC0x5F這些常量同樣定義在 drivers/led/issi/is31fl3737.h。需要注意兩點(diǎn)驅(qū)動(dòng)數(shù)量由地址宏自動(dòng)推導(dǎo)源碼通過(guò)#if defined(IS31FL3737_I2C_ADDRESS_4) ... #elif defined(IS31FL3737_I2C_ADDRESS_1)鏈?zhǔn)脚袛郿rivers/led/issi/is31fl3737.h定義到ADDRESS_n即聲明有 n 片驅(qū)動(dòng)。因此多片級(jí)聯(lián)時(shí)必須從ADDRESS_1開(kāi)始連續(xù)定義。I2C 總線地址是 8 位形式驅(qū)動(dòng)在寫(xiě)寄存器時(shí)執(zhí)行i2c_write_register(i2c_addresses[index] 1, ...)把 7 位器件地址左移一位拼成帶讀寫(xiě)位的 8 位地址drivers/led/issi/is31fl3737.c。真實(shí)鍵盤(pán)示例keyboards/zsa/planck_ez/config.h單驅(qū)動(dòng)IS31FL3737_I2C_ADDRESS_1 IS31FL3737_I2C_ADDRESS_GNDkeyboards/mt/mt84/config.h雙驅(qū)動(dòng)ADDRESS_1 GND、ADDRESS_2 VCC。五、PWM 頻率調(diào)節(jié)IS31FL3737BIS31FL3737B 支持通過(guò)配置寄存器調(diào)整 LED 的 PWM 頻率。在config.h中加入#define IS31FL3737_PWM_FREQUENCY IS31FL3737_PWM_FREQUENCY_8K4_HZ合法取值如下DefineFrequencyIS31FL3737_PWM_FREQUENCY_8K4_HZ8.4 kHz (默認(rèn))IS31FL3737_PWM_FREQUENCY_4K2_HZ4.2 kHzIS31FL3737_PWM_FREQUENCY_26K7_HZ26.7 kHzIS31FL3737_PWM_FREQUENCY_2K1_HZ2.1 kHzIS31FL3737_PWM_FREQUENCY_1K05_HZ1.05 kHz從源碼看PWM 頻率最終被寫(xiě)入 Function 頁(yè)的配置寄存器((IS31FL3737_PWM_FREQUENCY 0b111) 3) | 0x01drivers/led/issi/is31fl3737.c即把頻率編碼0b000~0b100左移 3 位放入 PFS 位域同時(shí)將最低位置 1 以解除軟件關(guān)斷。若你的板子使用 IS31FL3737B 且對(duì)刷新率/噪聲有要求可通過(guò)此宏調(diào)節(jié)更高頻率可減少人耳可聞噪聲但會(huì)以功耗為代價(jià)。實(shí)際項(xiàng)目示例keyboards/frooastboard/walnut將頻率設(shè)為IS31FL3737_PWM_FREQUENCY_26K7_HZ見(jiàn) keyboards/frooastboard/walnut/config.h。六、去鬼影De-Ghosting電阻配置LED 矩陣掃描時(shí)相鄰行/列可能因寄生路徑出現(xiàn)“鬼影”微亮。IS31FL3737 允許分別配置SWy引腳的上拉電阻和CSx引腳的下拉電阻來(lái)抑制該現(xiàn)象。原理細(xì)節(jié)可參考數(shù)據(jù)手冊(cè)第 23 頁(yè)。在config.h中設(shè)置#define IS31FL3737_SW_PULLUP IS31FL3737_PUR_0_OHM #define IS31FL3737_CS_PULLDOWN IS31FL3737_PDR_0_OHMIS31FL3737_SW_PULLUP合法值DefineResistanceIS31FL3737_PUR_0_OHMNone (默認(rèn))IS31FL3737_PUR_0K5_OHM0.5 k?IS31FL3737_PUR_1K_OHM1 k?IS31FL3737_PUR_2K_OHM2 k?IS31FL3737_PUR_4K_OHM4 k?IS31FL3737_PUR_8K_OHM8 k?IS31FL3737_PUR_16K_OHM16 k?IS31FL3737_PUR_32K_OHM32 k?IS31FL3737_CS_PULLDOWN合法值DefineResistanceIS31FL3737_PDR_0_OHMNone (默認(rèn))IS31FL3737_PDR_0K5_OHM0.5 k?IS31FL3737_PDR_1K_OHM1 k?IS31FL3737_PDR_2K_OHM2 k?IS31FL3737_PDR_4K_OHM4 k?IS31FL3737_PDR_8K_OHM8 k?IS31FL3737_PDR_16K_OHM16 k?IS31FL3737_PDR_32K_OHM32 k?這些取值在頭文件中以 3 位二進(jìn)制常量定義drivers/led/issi/is31fl3737.h初始化時(shí)分別寫(xiě)入 Function 頁(yè)的IS31FL3737_FUNCTION_REG_SW_PULLUP0x0F與IS31FL3737_FUNCTION_REG_CS_PULLDOWN0x10寄存器。七、全局電流控制IS31FL3737_GLOBAL_CURRENT控制CSx引腳吸收的電流取值 0~255默認(rèn)最大0xFF。降低該值可以整體調(diào)暗所有 LED 的亮度上限。在config.h中#define IS31FL3737_GLOBAL_CURRENT 0xFF寫(xiě)入位置為 Function 頁(yè)的IS31FL3737_FUNCTION_REG_GLOBAL_CURRENT0x01寄存器drivers/led/issi/is31fl3737.c。注意它與 PWM 占空比是兩個(gè)獨(dú)立維度全局電流限制“最大亮度”P(pán)WM 決定“當(dāng)前亮度”。八、ARM/ChibiOS 平臺(tái)的 I2C 配置在 ARMChibiOS平臺(tái)上僅定義上述宏還不夠。你需要根據(jù)鍵盤(pán)對(duì)應(yīng)的 ChibiOS 板級(jí)配置在鍵盤(pán)層面啟用并配置 I2C 外設(shè)。具體包括 I2C 引腳的復(fù)用alternate function、時(shí)鐘頻率等這部分屬于平臺(tái)級(jí)配置與驅(qū)動(dòng)本身解耦。AVR 平臺(tái)通常無(wú)需額外步驟。九、LED 映射把每個(gè)輸出綁到 LED 索引驅(qū)動(dòng)本身不知道你的 PCB 上哪顆 LED 接在哪個(gè)引腳因此必須在鍵盤(pán)源文件keyboard.c中定義映射表把“LED 索引 → 驅(qū)動(dòng)編號(hào) PWM 寄存器地址”對(duì)應(yīng)起來(lái)。9.1 RGB 驅(qū)動(dòng)const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] { /* Driver * | R G B */ {0, SW1_CS1, SW1_CS2, SW1_CS3}, // etc... };上例中驅(qū)動(dòng) 0 的 LED 索引 0 其 R/G/B 三個(gè)通道的陰極都接到SW1引腳陽(yáng)極分別接到CS1、CS2、CS3引腳。9.2 單色驅(qū)動(dòng)單色驅(qū)動(dòng)的原理相同只是每個(gè) LED 只有一個(gè)通道const is31fl3737_led_t PROGMEM g_is31fl3737_leds[IS31FL3737_LED_COUNT] { /* Driver * | V */ {0, SW1_CS1}, // etc... };9.3 映射值含義與寄存器索引SWx_CSy這類符號(hào)并非任意名稱而是直接對(duì)應(yīng)芯片 PWM 寄存器地址例如SW1_CS1 0x00、SW1_CS12 0x0D、SW12_CS12 0xBD完整定義見(jiàn) drivers/led/issi/is31fl3737.h。這些數(shù)值與數(shù)據(jù)手冊(cè)第 15 頁(yè) Figure 9 中 PWM 寄存器索引一一對(duì)應(yīng)。映射時(shí)請(qǐng)對(duì)照你的 PCB 原理圖確認(rèn)每顆 LED 的陰極SW 行與陽(yáng)極CS 列實(shí)際接法再填表。IS31FL3737_LED_COUNT在啟用 RGB Matrix / LED Matrix 時(shí)分別由RGB_MATRIX_LED_COUNT/LED_MATRIX_LED_COUNT提供見(jiàn) drivers/led/issi/is31fl3737.h 與 drivers/led/issi/is31fl3737-mono.h因此獨(dú)立使用時(shí)你也要在別處定義該宏。十、源碼級(jí)原理寄存器分頁(yè)與緩沖機(jī)制理解驅(qū)動(dòng)的行為有助于排查問(wèn)題。IS31FL3737 采用分頁(yè)寄存器架構(gòu)通過(guò)命令寄存器0xFD切換頁(yè)面切換前需先向?qū)戞i寄存器0xFE寫(xiě)入解鎖魔數(shù)0xC5Page 0 — LED ControlLED 開(kāi)關(guān)On/Off控制共 24 個(gè)寄存器Page 1 — PWM每通道 8 位 PWM 亮度寄存器空間為 192 字節(jié)實(shí)際使用 144Page 2 — Auto Breath自動(dòng)呼吸模式驅(qū)動(dòng)默認(rèn)保持 PWM 模式未單獨(dú)配置Page 3 — Function配置寄存器含配置0x00、全局電流0x01、SW 上拉0x0F、CS 下拉0x10、復(fù)位0x11。初始化流程drivers/led/issi/is31fl3737.c為先選 LED Control 頁(yè)關(guān)閉所有 LED → 選 PWM 頁(yè)把所有 PWM 清 0 → 選 Function 頁(yè)寫(xiě)入去鬼影電阻、全局電流最后通過(guò)配置寄存器解除軟件關(guān)斷并wait_ms(10)等待芯片喚醒。注釋特別說(shuō)明之所以最后解除關(guān)斷是為了避免芯片帶著寄存器中的臟數(shù)據(jù)驅(qū)動(dòng) LED。驅(qū)動(dòng)還維護(hù)了兩套軟件緩沖pwm_buffer與led_control_buffer并帶有臟標(biāo)記dirty flagis31fl3737_set_color()/is31fl3737_set_value()只改寫(xiě)緩沖并置臟不會(huì)立即刷新到芯片is31fl3737_update_pwm_buffers()僅在緩沖為臟時(shí)才切換 PWM 頁(yè)并以 16 字節(jié)為一組共 12 次傳輸批量寫(xiě)入is31fl3737_update_led_control_registers()同理刷新 LED 控制寄存器頭文件注釋提醒update_pwm_buffers不應(yīng)在中斷如定時(shí)器中斷中調(diào)用應(yīng)在矩陣掃描間隙的空閑期調(diào)用drivers/led/issi/is31fl3737.h。十一、API 參考以下為驅(qū)動(dòng)對(duì)外公開(kāi)的 C API單色/RGB 兩套頭文件均聲明見(jiàn) drivers/led/issi/is31fl3737.h 與 drivers/led/issi/is31fl3737-mono.h。struct is31fl3737_led_t描述單顆 LED 通道與其所屬驅(qū)動(dòng)的結(jié)構(gòu)體。成員uint8_t driver所屬驅(qū)動(dòng)索引取值 0~3位域2 bituint8_t r紅色通道的 PWM 寄存器地址僅 RGB 驅(qū)動(dòng)uint8_t g綠色通道的 PWM 寄存器地址僅 RGB 驅(qū)動(dòng)uint8_t b藍(lán)色通道的 PWM 寄存器地址僅 RGB 驅(qū)動(dòng)uint8_t vLED 的 PWM 寄存器地址僅單色驅(qū)動(dòng)。RGB 版結(jié)構(gòu)體定義見(jiàn) drivers/led/issi/is31fl3737.h單色版為{uint8_t driver; uint8_t v;}drivers/led/issi/is31fl3737-mono.h。void is31fl3737_init(uint8_t index)初始化指定索引的 LED 驅(qū)動(dòng)應(yīng)最先調(diào)用。參數(shù)uint8_t index驅(qū)動(dòng)索引0~3。void is31fl3737_write_register(uint8_t index, uint8_t reg, uint8_t data)向指定寄存器寫(xiě)入一個(gè)字節(jié)。參數(shù)uint8_t index驅(qū)動(dòng)索引uint8_t reg寄存器地址uint8_t data要寫(xiě)入的值。void is31fl3737_select_page(uint8_t index, uint8_t page)切換當(dāng)前配置頁(yè)。參數(shù)uint8_t index驅(qū)動(dòng)索引uint8_t page目標(biāo)頁(yè)號(hào)對(duì)應(yīng)IS31FL3737_COMMAND_*常量。void is31fl3737_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)設(shè)置單顆 LED 的顏色僅 RGB 驅(qū)動(dòng)。不會(huì)立即生效完成后需調(diào)用is31fl3737_update_pwm_buffers()刷新。參數(shù)int indexLED 索引即g_is31fl3737_leds數(shù)組下標(biāo)uint8_t red紅色值uint8_t green綠色值uint8_t blue藍(lán)色值。void is31fl3737_set_color_all(uint8_t red, uint8_t green, uint8_t blue)設(shè)置所有 LED 的顏色僅 RGB 驅(qū)動(dòng)。內(nèi)部循環(huán)調(diào)用is31fl3737_set_color()。參數(shù)uint8_t red/uint8_t green/uint8_t blueRGB 值。void is31fl3737_set_value(int index, uint8_t value)設(shè)置單顆 LED 的亮度僅單色驅(qū)動(dòng)。不會(huì)立即生效需隨后調(diào)用is31fl3737_update_pwm_buffers()。參數(shù)int indexLED 索引uint8_t value亮度值。void is31fl3737_set_value_all(uint8_t value)設(shè)置所有 LED 的亮度僅單色驅(qū)動(dòng)。參數(shù)uint8_t value亮度值。void is31fl3737_set_led_control_register(uint8_t index, bool red, bool green, bool blue)配置單顆 LED 的 LED Control 寄存器開(kāi)關(guān)僅 RGB 驅(qū)動(dòng)。不會(huì)立即生效需調(diào)用is31fl3737_update_led_control_registers()。實(shí)現(xiàn)上按reg 通道寄存器地址 / 8、bit 地址 % 8定位到對(duì)應(yīng)控制位drivers/led/issi/is31fl3737.c。參數(shù)uint8_t indexLED 索引bool red是否啟用紅色通道bool green是否啟用綠色通道bool blue是否啟用藍(lán)色通道。void is31fl3737_set_led_control_register(uint8_t index, bool value)配置單顆 LED 的 LED Control 寄存器僅單色驅(qū)動(dòng)。不會(huì)立即生效需調(diào)用is31fl3737_update_led_control_registers()。參數(shù)uint8_t indexLED 索引bool value啟用或禁用該 LED。void is31fl3737_update_pwm_buffers(uint8_t index)把 PWM 緩沖刷新到驅(qū)動(dòng)芯片僅在緩沖為臟時(shí)執(zhí)行實(shí)際傳輸。參數(shù)uint8_t index驅(qū)動(dòng)索引。void is31fl3737_update_led_control_registers(uint8_t index)把 LED Control 緩沖刷新到驅(qū)動(dòng)芯片僅在緩沖為臟時(shí)執(zhí)行。參數(shù)uint8_t index驅(qū)動(dòng)索引。void is31fl3737_flush(void)對(duì)所有已啟用驅(qū)動(dòng)調(diào)用一次is31fl3737_update_pwm_buffers()是 RGB/LED Matrix 框架中統(tǒng)一的刷新入口。十二、典型接入流程小結(jié)要在 QMK 鍵盤(pán)上點(diǎn)亮 IS31FL3737完整步驟如下確認(rèn) PCB 上芯片的ADDR引腳接法確定 I2C 地址在rules.mk中啟用驅(qū)動(dòng)或通過(guò)RGB_MATRIX_IS31FL3737/LED_MATRIX_IS31FL3737自動(dòng)引入在config.h中定義IS31FL3737_I2C_ADDRESS_1多片則繼續(xù)定義到_n按需調(diào)整IS31FL3737_PWM_FREQUENCY、IS31FL3737_SW_PULLUP、IS31FL3737_CS_PULLDOWN、IS31FL3737_GLOBAL_CURRENT、IS31FL3737_SDB_PIN對(duì)照原理圖在keyboard.c中編寫(xiě)g_is31fl3737_leds[]映射表ARM 平臺(tái)按需完成 I2C 外設(shè)的板級(jí)配置參考 docs/drivers/i2c.md編譯燒錄并驗(yàn)證亮度與顏色若出現(xiàn)鬼影再逐步調(diào)大去鬼影電阻值。按照上述流程配合 QMK 的 LED Matrix / RGB Matrix 上層框架即可讓單色背光或 RGB 燈效在 IS31FL3737 驅(qū)動(dòng)的鍵盤(pán)上穩(wěn)定運(yùn)行。【免費(fèi)下載鏈接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families項(xiàng)目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考