1. 新版SDK命名说明

2023年9月发布的SDK整合了AD14N / AC104N / AD15N / AD17N / AD18N的工程，SDK命名为 AD1x-4578_AC104-release_v1.8.0 ，其含义为：

AD1x-4578：代表AD14、AD15、AD17、AD18N

AC104：代表AC104

v1.8.0：表示当前SDK版本号

新版本SDK名称说明

2. 环境介绍

本章节主要介绍软硬件开发环境。

2.1. 硬件环境介绍

AD系列硬件开发环境使用不同的开发板，包括不同底板和顶板。以下芯片适用于AD系列在线文档说明。

适用本文的芯片

AD14N / AC104N

AD15N

AD17N

AD18N

2.1.1. AD14N AC104N硬件开发环境

AD14N芯片框图如下图所示：

AD14N，AC104N使用的硬件环境开发板由底板和顶板两部分组成。

底板包含的模块如下图所示：

其中模块：

模块

模块详情

MIC模块

MIC输入引脚固定为PB01，偏置电压可由MICLDO（PA15）或MICBIAS（PA13）提供，也可以使用外部偏置，不占用芯片I/O口；

LINEIN模块

LINEIN输入引脚可选AUX0（PA13）或AUX1（PA14），需将对应引脚与AUX_OUT短接；

Audio PA功放模块

单端DAC输出引脚为PB0，需将PA_IN与PB0短接；

Class-D APA模块

差分DAC输出引脚为DACN和DACP；

LED模块

该模块的3个LED灯都是高电平点亮；

红外模块

该模块用于接收红外信号，需将IRVDD与VDDIO短接；

按键模块

该模块有4个AD按键以及4个I/O按键，其中AD按键外接10k上拉电阻；

电源模块

供电可通过正极接“VUSB”，负极接“GND”实现，且需要将VBAT和VUSB短接、HPVDD和VBAT短接；

USB模块

该模块可以用来通信USB设备，或给开发板下载程序以及供电；

TF卡模块

该模块支持驱动一线模式的TF卡；

外挂FLASH模块

该模块可挂载一颗存放资源的FLASH；

顶板包含的模块如下图所示：

顶板的“FLASH工作模式以及供电方式选择区”可以选择FLASH是跑1线模式还是2线模式，并且可以选择POWER引脚供电使用VDDIO还是PD4引脚。

系统flash单双线配置及flash电源配置：

使用USB升级FLASH的时候，插入USB线连电脑和开发板，按住“FLASH短路按键”不松手之后再短按“复位按键”复位系统，之后松开“FLASH短路按键”就可以进入升级，此时电脑可以正常出现设备盘符即是操作成功了。

2.1.2. AD15N硬件开发环境

AD15N芯片框图如下图所示：

AD15N使用的硬件环境开发板由底板和顶板两部分组成。

底板包含的模块如下图所示：

其中模块：

模块

模块详情

Class-D APA模块

差分DAC输出引脚为DACN和DACP；

红外模块

该模块用于接收红外信号，需将IRVDD与VDDIO短接；

LED模块

该模块的3个LED灯都是高电平点亮；

按键模块

该模块有8个AD按键，外接10k上拉电阻；

TF卡模块

该模块支持驱动一线模式的TF卡；

外挂FLASH模块

该模块可挂载一颗存放资源的FLASH；

电源模块

AD15N USB口只用来供电，芯片自身并没有USB模块。特别地，AD150开发烧写使用串口升级方式，供电使用USB UPDATER插入USB口供电，并且USB UPDATER TX接到开发板的PB9。

顶板包含的模块如下图所示：

AD15N使用串口方式升级，升级时候并不需要按着Update，只需要点击运行升级脚本，USB UPDATER就会让开发板自动进入升级模式了。

顶板的“FLASH工作模式以及供电方式选择区”可以选择FLASH是跑1线模式还是2线模式，并且可以选择POWER引脚供电使用VDDIO还是PD4引脚。

2.1.3. AD17N硬件开发环境

AD17N芯片框图如下图所示：

AD17N使用的硬件环境开发板由底板和顶板两部分组成。

底板包含的模块如下图所示：

其中模块：

模块

模块详情

Class-D APA模块

差分输出引脚为APAN和APAP；

红外模块

该模块用于接收红外信号，需将IRVDD与VDDIO短接；

LED模块

该模块的3个LED灯都是高电平点亮；

按键模块

该模块有8个AD按键，外接10k上拉电阻；

外挂FLASH模块

该模块可挂载一颗存放资源的FLASH；

电源模块

AD17N USB口只用来供电，芯片自身并没有USB模块。特别地，AD17N开发烧写使用串口升级方式，供电使用USB强制升级工具插入USB口供电，并且USB强制升级工具TX接到开发板的PB1。

顶板包含的模块如下图所示：

AD17N使用串口方式升级，升级时候并不需要按着Update，只需要点击运行升级脚本，USB强制下载工具就会复位开发板让其进入升级模式。

顶板的“FLASH工作模式以及供电方式选择区”可以选择FLASH是跑1bit模式还是2bit模式，并且可以选择POWER引脚供电使用VDDIO还是芯片PD4(SPFG)引脚。

2.1.4. AD18N硬件开发环境

AD18N芯片框图如下图所示：

AD18N使用的硬件环境开发板由底板和顶板两部分组成。

底板包含的模块如下图所示：

其中模块：

模块

模块详情

USB模块

该模块可以用来通信USB设备，或给开发板下载程序以及供电；

外挂FLASH模块

该模块可挂载一颗存放资源的FLASH；

Audio PA功放模块

单端模拟DAC输出引脚为AIN7，需将PA_IN与AIN7短接；

Class-D APA模块

差分输出引脚为APAN和APAP；（耳机座子接APA）

电源模块

供电可通过接USB线或者Type-C线实现，且需要将+5V和VPWR短接、HPVDD和VPWR短接；

按键模块

该模块有4个AD按键，外接10k上拉电阻与不同阻值的下拉电阻；同时还有4个独立IO按键；

LCD断码屏模块

该模块支持最多4com * 12seg的段码屏；

红外模块

该模块用于接收红外信号，需将IRVDD与IOVDD短接；

LED模块

该模块的3个LED灯都是高电平点亮；

顶板包含的模块如下图所示：

AD18N使用USB升级，升级前需接入USB强制下载工具并进入下载模式。（下载器红灯常量即进入下载模式），再使用Codeblock编译下载即可；

顶板的“FLASH工作模式以及供电方式选择区”可以选择FLASH是跑1bit模式还是2bit模式，并且可以选择POWER引脚供电使用VDDIO还是芯片PD4(FSPG)引脚。

顶板的“PA7 & PA8外接32K晶振选择”可以选择顶板的PA7、PA8直接接到底板的PA7、PA8，还是直接接到外挂32K晶振引脚；

2.2. SDK工程与配置

目前AD14N / AD15N / AC104N / AD17N支持的工程如下：

芯片/工程

app_mg

simple

mbox_mg

mcu

voice_toy

AD14N / AC104N

√

√

√

√

√

AD15N

√

√

√

√

AD17N

√

√

AD18N

√

√

app_mg应用工程：
该工程有完整玩具功能，能实现解码、编码录音、MIDI、LINEIN等功能；同时将VM、按键、休眠应用在工程中。

simple示例工程：
该工程可实现解码、扩音功能等功能；未将VM、按键、休眠应用在工程中，但是相关代码能在工程中直接调用使用。

芯片/工程

支持的SDK版本

AD14N

ad140-release_v1.0.0 ~ v1.4.0、开源sdk_v1.0.0 ~ v1.6.0

AD15N

ad150-release_v1.0.0 ~ v1.4.0、开源sdk_v1.0.0 ~ v1.6.0

mbox_mg应用工程：
该工程有完整插卡音箱功能，能实现标准MP3、WAV解码、FM、USB从机、录音、扩音功能等功能；同时将VM、升级、按键、休眠应用在工程中。

芯片/工程

支持的SDK版本

AC104N

ac104-release_v1.0.0 ~ v1.4.0、开源SDK_v1.6.0 ~ 至今最新版本

voice_toy应用工程：
该工程有完整发声玩具功能，在simple工程基础上集成了app_mg功能；能实现解码、MIDI功能；同时将VM、按键、休眠应用在工程中。

芯片/工程

支持的SDK版本

AD14/15/17/18/AC104

AD1x-457_AC104-release_v1.7.0 ~ 至今最新版本

mcu应用工程：
该工程为MCU工程，仅初始化串口打印、时钟、电源、异常等模块，不包含其他功能。

2.2.1. 应用配置文件《app_config.c》介绍

应用配置文件《app_config.c》能配置与系统相关的配置：

1、中断优先级；

注：控制各个模块的中断优先级！

2、LRC_TRIM_DISABLE：LRC校准时钟，LRC必须经过了烧写器校准后才能使用

①　FALSE：使用LRC校准时钟偏差，生产必须选择FALSE；

②　TRUE：不使用LRC校准时钟偏差；

注：默认开启LRC校准时钟，时钟不准的芯片一定要过烧写器校准！

3、MM_ASSERT：MALLOC内部断言使能

①　FALSE：关闭malloc内部断言；

②　TRUE：打开malloc内部断言，默认打开；

4、MIC_CAPLESS_EN：MIC省电容使能

①　FALSE：不省电容；

②　TRUE：省电容；

注：省电容方案底噪较大，不建议使用！

5、MIC_RES_BUILT_IN：MIC电路偏置方式

①　0：使用MICLDO（PA15）提供偏置电压，需短接V_MIC和MICLDO；

②　1：使用MICBIAS（PA13）提供偏置电压，需短接MIC和MICBIAS；

③　2：不使用内部偏置（不占用I/O口）；

6、MIC_LDO_V：MICLDO增益“MIC_0DB”

注：此选项只在MIC_RES_BUILT_IN == 0时起作用，以下为千欧姆

①　0 : 1.8V；

②　1 : 2.1V；

③　2：2.4V；

④　3：2.7V；

7、MIC_RES_IN：MICBIAS电路内置偏置电阻挡位选择

注：此选项只在MIC_RES_BUILT_IN == 1时起作用，以下为千欧姆

value

kkilohm

value

kkilohm

0b00100

7;

0b00101

1.555;

0b00110

2.916;

0b00111

1.186;

0b01000

NA;

0b01001

3;

0b01010

6;

0b01011

2.428;

0b00000

NA;

0b00001

2;

0b00010

5;

0b00011

1.425;

0b01100

8;

0b01101

2.555;

0b01110

3.916;

0b01111

2.186;

0b10000

NA;

0b10001

3.5;

0b10010

6.5;

0b10011

2.926;

0b10100

8.5;

0b10101

3.055;

0b10110

4.416;

0b10111

2.686;

0b11000

NA;

0b11001

2.6;

0b11010

5.6;

0b11011

2.208;

0b11100

7.6;

0b11101

2.4;

0b11110

3.73;

0b11111

1.99;

0b000001

0.85;

0b0000001

0.35

8、MIC_0DB：MIC前级增益

value

db

0

6db

1

0db

9、MIC_PGA_G：MIC后级增益

value

db

0b0000

0db

0b0001

2db

0b0010

4db

…

…

0b1110

28db

10、AUDIO_ADC_SR_COR：录音采样率纠错使能

①　FALSE：关闭自动纠错，当录音设置的采样率不在AUDIO ADC工作的范围内时，返回错误，启动AUDIO ADC失败；

②　TRUE：开启纠错，当录音设置的采样率不在AUDIO ADC工作的范围内时，将采样率设置在AUDIO_ADC_SR对应的值！如果AUDIO_ADC_SR正确那么启动成功，否则失败；

11、AUDIO_ADC_SR：录音采样率纠错值

①　采样率：8000

②　采样率：12000

③　采样率：16000

④　采样率：24000

⑤　其他：非法值

12、AUDIO_VCMCAP：VCM是否挂电容，挂了电容后音质会有较大提升：

①　FALSE：没有挂电容；

②　TRUE：有挂电容；

注：只有部分封装有将VCMCAP引脚引出，详情请看具体芯片封装原理图！

13、ADC_VBG_TRIM_EN：内部VBG校准使能

①　FALSE：使用默认值校准；

②　TRUE：使用烧写值校准，生产必须选择TRUE；

14、GPIO_CRITICAL_OPT：GPIO中断临界保护使能

①　FALSE：关闭GPIO中断临界保护；

②　TRUE：打开GPIO中断临界保护；

15、MAINTRACK_USE_CHN：MIDI乐谱使用主轨道选择

①　0：用track号来区分；

②　1：用channel号来区分；

16、MAX_DEC_PLAYER_CNT：MIDI乐谱解码最大同时发声key数

①　范围：1~31，会影响到midi乐谱解码运算buff大小；

17、MAX_CTR_PLAYER_CNT：MIDI琴最大同时发声key数

①　范围：1~31，会影响到midi琴解码运算buff大小；

18、dev_update_use_eeprom：设备升级占用区域，占用的区域数据是失效

①　0：占用VM区域（一般用于AD14N的内置flash录音）；

②　1：占用EEPROM区域（一般用于VM记忆）；

19、dev_update_keep_io_status：设备升级I/O保持使能

①　0：不保持I/O，升级时复位I/O；

②　1：保持I/O，升级过程中I/O保持升级前状态；

20、ufw_vid_need_to_be_different：设备升级对ufw升级文件的vid要求

①　0：升级文件vid与当前设备vid相同才可升级；

②　1：升级文件vid与当前设备vid不同才可升级；

③　2：升级文件vid > 当前设备vid才可升级；

④　3：升级文件vid < 当前设备vid才可升级；

注：vid在isd_config.ini文件中修改！

21、config_asser：内核异常打印“config_asser”。

①　0：关闭内核异常打印;

②　1：开启内核异常打印;

注：生产的工程要关闭内核异常打印，内核异常打印会关闭看门狗并且while(1)停留！

22、libs_debug：打印总开关

①　FALSE：关闭打印;

②　TRUE：开启打印;

23、log_tag_const_x_yyyy：分支打印开关，仅仅在打印总开关打开的时候有效

①　x=i：控制打印函数（log_info / log_info_hexdump）的打印开关;

②　x=d：控制打印函数（log_debug / log_debug_hexdump）的打印开关;

③　x=e：控制打印函数（log_error / log_error_hexdump）的打印开关;

④　x=c：控制打印函数（log_char）的打印开关;

⑤　yyyy：控制相应的打印块;

注：若要打开相应打印，将CONFIG_DEBUG_LIBS(0)改为CONFIG_DEBUG_LIBS(1)即可！

2.2.2. 应用配置文件《app_config.h》介绍

应用配置文件《app_config.h》能配置与系统相关的配置：

2.2.2.1. 串口配置

1、UART_TX_OUTPUT_CH_EN：串口打印输出任意引脚使能

①　DISABLE：使用固定引脚输出，默认串口引脚AD14 / AC104：PA4，AD15N：PA6;

②　ENABLE：使能串口任意引脚输出，输出到;UART_OUTPUT_CH_PORT定义的引脚；

注：使能串口输出任意引脚会占用一路output channal通路！

2、UART_OUTPUT_CH_PORT：串口打印输出引脚选择，不可选择芯片没有的I/O口;

2.2.2.2. 按键配置

注：按键部分功能需要在key.h中配置！

配置项目

含义

AD_KEY_CH_SEL

AD按键采集引脚选择，可查看adc_drv.h中支持的引脚通道

IR_KEY_IO_SEL

红外按键捕获引脚选择，会占用一路input channal通路

IR_KEY_IO_SEL

红外按键捕获引脚选择，会占用一路input channal通路

X_ADC_CH_SEL & Y_PORT_SEL

X_ADC_CH_SEL

X轴要求选择支持ADC的I/O；

Y_PORT_SEL

Y轴选择普通I/O

TOUCH_KEY_SEL

触摸按键I/O口选择

KEY_VOICE_EN

触摸按键I/O口选择

2.2.2.3. 低功耗配置

1、POWER_WAKEUP_IO：低功耗唤醒I/O选择，请查看power_api.c中的配置

2.2.2.4. SD模块配置

1、TFG_SD_EN：SD卡模块使能（新版本SDK在app_moduels.h中定义该宏）

2、SPI_SD_IO_REUSE：外挂FLASH与SD卡模块I/O复用使能

2.2.2.5. USB模块配置

1、TCFG_PC_ENABLE：PC模块使能

2、TCFG_USB_EXFLASH_UDISK_ENABLE：外掛FLASH模拟U盘使能

3、TCFG_UDISK_ENABLE：U盘模块使能

2.2.2.6. 外挂FLASH配置（FLASH Configuration）

AD17N / AD18N支持任意I/O映射，外挂flash I/O需要在device_list.c中指定；

1、TCFG_FLASH_SPI_TYPE_SELECT：spi选择

①　1：选择硬件spi，固定I/O口，可查看device_list.c或者芯片原理图的spi模块引脚；

②　0：选择软件spi，可指定任意I/O口；

2、TFG_SPI_UNIDIR_MODE_EN：外挂flash运行1bit模式选择

①　1：使能外挂flash 1bit模式；

②　0：不使能外挂flash 1bit模式；

3、HW_SPI_WORK_MODE & SPI_READ_DATA_WIDTH：spi模式

①　SPI_MODE_BIDIR_1BIT：全双工，di接收，do发送；

②　SPI_MODE_UNIDIR_1BIT：半双工，do分时接收/发送；

③　SPI_MODE_UNIDIR_2BIT：半双工，di & do共2bit分时接收/发送；

4、SPI_CS_PORT_SEL：spi cs引脚选择

5、软件spi配置：

①　A_CLK_BIT & A_CLK_PORT(x)：软件spi CLK引脚选择；

②　A_DO_BIT & A_DO_PORT(x)：软件spi DO引脚选择；

③　A_DI_BIT & A_DI_PORT(x)：软件spi DI引脚选择；

④　SOFT_SPI_WORK_MODE：软件spi模式，可选择1bit或者2bit模式；

2.2.2.7. Mbox_mg工程独有的配置

宏定义

含义

LED_5X7

LED数码管使能，会占用部分I/O，请查看mbox_main.h中的引脚分布

BREAK_POINT_AUTO_SAVE

实时断点保存使能

POWERDOWN_UDISK_MODE_EN

U盘进入powerdown使能

FM_SD_IO_REUSE

FM与SD卡模块I/O复用使能

LINEIN_DET_MULT_SD

SD卡模块与LINEIN检测I/O复用使能

2.2.3. 应用APP配置文件《app_modules.h》介绍

各个工程下有对应cpu的应用配置文件《app_modules.h》，其中的宏定义能配置支持的编解码格式、以及APP模式相关的配置；每一个配置项都可独立开关，关闭没有用到的宏定义，可以 * 减少生成的代码量，节省程序空间和运行空间 * 。

该文件中出现的宏，即该工程拥有的功能；对于默认为0的宏，使能为1即可正常使用；

2.2.3.1. 解码模块

宏定义

含义

DECODER_UMP3_EN

UMP3解码使能；

DECODER_MP3_ST_EN

标准MP3解码使能（mbox独有）；

DECODER_WAV_EN

WAV解码使能（mbox独有）；

DECODER_F1A_EN

F1A解码使能；

DECODER_MIDI_EN

MIDI解码使能；

DECODER_MIDI_KEYBOARD_EN

MIDI琴解码使能；

DECODER_A_EN

A格式解码使能；

HAS_MIO_EN

MIO功能使能；

2.2.3.2. 音频算法模块

宏定义

含义

AUDIO_SPEED_EN

变速变调算法使能

SPEAKER_EN

扩音使能；

VO_PITCH_EN

变音算法使能；

PCM_EQ_EN

EQ算法使能；

ECHO_EN

ECHO算法模块使能；

2.2.3.3. 驱动模块功能

宏定义

含义

EXT_FLASH_EN

外挂FLASH使能，使用外挂FLASH需要打开该宏；

TFG_SD_EN

SD卡模块使能，使用SD卡需要打开该宏；

UART_UPDATE_EN

带电池串口升级使能；

2.2.3.4. 芯片应用功能

宏定义

含义

RECORD_MODE_EN

录音模式使能；

LINEIN_MODE_EN

LINEIN（AUX）模式使能；

SIMPLE_DEC_EN

多路解码模式使能；

LOUDSPEAKER_EN

扩音模式使能；

FM_EN

FM模块使能；

app_modules.h配置

2.2.4. CodeBlocks工程宏定义介绍

除了app_config.c、app_config.h和app_modules.h中的配置外，部分模块总开关放在CodeBlocks工程的宏定义中，不使用某些模块时，将宏关闭可以节约代码量；

在没有app_modules.h的旧版本SDK中，模块宏需要在CodeBlocks工程的宏定义中关闭。

2.2.4.1. 芯片Codeblocks宏定义功能

宏定义

含义

AUDIO_ADC_EN

AUDIO ADC使能；

ENCODER_EN

编码使能，有该配置即支持编码功能；

EEPROM_EN

EEPROM使能，使用EEPROM需要打开该宏，并在SDK工程中添加相应的c文件以及h文件；

2.3. 新版本SDK工程裁切（2023年7月发布的SDK起始）

从2023年7月发布的AD1x-457_AC104-release_v1.7.0起始，SDK添加了app_modules.h模块管理机制；

裁切工程只需将app_modules.h中需要关闭的宏定义配置为0即可；

2.4. 旧版本SDK工程裁切

2.4.1. 如何将解码格式从工程中移除

旧版本发布的SDK里面支持F1A、UMP3、A、midi四种格式，AD15N支持F1A、A、MIDI三种格式，在开发过程中如果不需要支持某些格式，那么可以将相关的代码删除。这样可以极大的节省生成的代码大小；

下面以移除MIDI解码格式为例介绍，主要分四步：

①　将相关的宏定义清0；

②　移除相关的库文件；

③　移除相关的源文件；

④　删除其资源定义；

2.4.1.1. 裁切解码第一步

打开<Project build option>窗口，将需要MIDI格式相应的宏定义设置为0:

2.4.1.2. 裁切解码第二步

上一步打开的<Project build option>窗口中删除MIDI的库包含:

2.4.1.3. 裁切解码第三步

移除工程目录app\src\common\decoder\list\下的解码源文件;

2.4.1.4. 裁切解码第四步

在文件app\post_build\sh54\app_ld.c中删除相关格式用到的资源定义，切记此文件在不可放在工程中编译，如果添加进了工程，一定要将其编译和链接包含取消掉.

2.4.2. 如何将压缩格式从工程中移除

目前发布的AD14N SDK里面支持UMP3、A两种格式的压缩，AD15N不支持录音压缩，在开发过程中如果不需要支持某些格式，那么可以将相关的代码删除。这样可以极大的节省生成的代码大小；

下面以移除UMP3压缩格式为例介绍，主要分三步：
①　移除相关的库文件； ②　移除相关的源文件； ③　删除源码使用到的地方定义；

2.4.2.1. 裁切压缩第一步

打开<Project build option>窗口，删除mp3编码库的库包含：

注：部分宏配置需要在《app_modules.h》中关闭！详情请见上文《裁切解码第一步》

2.4.2.2. 裁切压缩第二步

移除工程目录app\src\common\decoder\list\下的压缩源文件：

2.4.2.3. 裁切压缩第三步

在文件app\post_build\sh54\app_ld.c中删除相关格式用到的资源定义，切记此文件在不可放在工程中编译，如果添加进了工程，一定要将其编译和链接包含取消掉。

2.4.2.4. 裁切压缩第四步

修改一些编译错误，这里主要指在在程序中对编码接口的调用: