1. 项目概述
7Semi ADXL335 Accelerometer 是一款面向嵌入式平台的轻量级模拟加速度传感器驱动库，专为 ADXL335 这一经典三轴模拟输出 MEMS 加速度计设计。该库并非基于数字通信协议（如 I²C 或 SPI），而是直接采集 X、Y、Z 三路模拟电压信号，通过微控制器内置 ADC 进行数字化处理，最终输出原始采样值或经线性换算后的加速度物理量。其核心价值在于极简硬件依赖、零协议栈开销、确定性采样时序，适用于对实时性、资源占用和硬件成本敏感的工业传感节点、姿态检测模块、振动监测终端及教育实验平台。
ADXL335 本身是一款由 Analog Devices（ADI）推出的低功耗、高稳定性模拟加速度传感器芯片，采用单电源供电（3.3 V 或 5 V），内置信号调理电路与缓冲输出级。其 X/Y/Z 三轴输出为比例式模拟电压：当某轴加速度为 0 g 时，对应输出电压为 VCC/2；加速度每变化 ±1 g，输出电压相应偏移约 ±300 mV（典型值，具体取决于供电电压与器件批次）。该特性决定了其天然适配于具备 10-bit 或更高精度 ADC 的 MCU，无需外部运放或电平转换电路，可实现“传感器—MCU”直连架构。
本库虽以 Arduino 平台为初始目标，但其底层设计完全遵循嵌入式通用范式——所有硬件抽象层（HAL）调用均封装为可移植接口，不依赖 Arduino 特定 API（如analogRead()的内部实现细节被显式隔离）。这意味着开发者可轻松将其迁移至 STM32 HAL/LL 库、ESP-IDF、nRF SDK 或裸机环境，仅需重写read_analog_channel()这一基础函数即可完成平台适配。
2. 硬件接口与电气特性解析
2.1 引脚定义与连接拓扑
ADXL335 模块（7Semi 封装版）共 5 个引脚，其功能与推荐连接方式如下表所示：
| 模块引脚 | 功能说明 | 推荐 MCU 连接 | 电气约束 |
|---|---|---|---|
| VCC | 电源输入 | 3.3 V 或 5 V 稳压源 | 必须使用低噪声 LDO 供电；若 MCU 为 3.3 V 系统，严禁接 5 V，否则损坏芯片 |
| GND | 模拟地 | MCU 模拟地（AGND） | 必须与 VCC 地同源，避免地环路引入共模噪声 |
| X-OUT | X 轴模拟电压输出 | MCU ADC 通道 0（如 A0） | 输出阻抗约 32 kΩ，需确保 ADC 输入阻抗 ≥ 100 kΩ（绝大多数 MCU 满足） |
| Y-OUT | Y 轴模拟电压输出 | MCU ADC 通道 1（如 A1） | 同上，建议使用独立 ADC 采样序列以消除通道间串扰 |
| Z-OUT | Z 轴模拟电压输出 | MCU ADC 通道 2（如 A2） | Z 轴在静止状态下通常输出略高于 VCC/2（因重力分量），需在软件中校准 |
关键工程提示：
- 电源去耦：在 VCC 引脚就近（≤ 2 mm）并联 0.1 μF 陶瓷电容 + 10 μF 钽电容至 GND，抑制高频噪声对模拟输出的影响。
- ADC 参考电压：强烈建议使用 MCU 内部高精度参考电压（如 STM32 的 VREFINT 或 ESP32 的 Vref=1.1 V），而非默认 VCC 作为 ADC 基准。若必须使用 VCC，则需确保其纹波 < 10 mVpp。
- 布线原则：X/Y/Z 模拟走线应远离高速数字信号线（如 USB、SPI、时钟），长度尽量相等，避免形成天线效应。
2.2 输出电压-加速度转换模型
ADXL335 的输出遵循严格的线性关系，其数学模型为：
$$ V_{out} = V_{bias} + S \times a $$
其中：
- $V_{out}$：实测模拟输出电压（单位：V）
- $V_{bias}$：零加速度偏置电压 = $V_{CC} / 2$（理想值，实际存在 ±15 mV 偏差）
- $S$：灵敏度 = $300 , \text{mV/g}$（典型值，数据手册标称范围：270–330 mV/g）
- $a$：实际加速度（单位：g）
将此模型映射至 MCU ADC 数字域，设 ADC 分辨率为 $N$ bit（Arduino Uno 为 10-bit，即 $2^{10}=1024$），参考电压为 $V_{ref}$，则数字读数 $D$ 与加速度 $a$ 的关系为：
$$ D = \frac{V_{out}}{V_{ref}} \times (2^N - 1) = \frac{V_{bias} + S \times a}{V_{ref}} \times 1023 $$
解出 $a$ 得：
$$ a = \frac{V_{ref}}{S} \times \left( \frac{D}{1023} - \frac{V_{bias}}{V_{ref}} \right) = \frac{V_{ref}}{S} \times \frac{D - D_{bias}}{1023} $$
其中 $D_{bias} = \frac{V_{bias}}{V_{ref}} \times 1023$ 为零 g 对应的数字偏移值。该公式是后续所有校准与单位转换的基础。
3. 软件架构与 API 设计
3.1 类结构与初始化流程
库以 C++ 类ADXL335封装全部功能，其构造函数接受三个 ADC 通道编号，明确绑定物理引脚与逻辑轴：
// 构造函数声明（7semi_ADXL335.h） class ADXL335 { public: ADXL335(uint8_t xPin, uint8_t yPin, uint8_t zPin); bool begin(); // 初始化，执行自检与零点校准 void readRaw(int16_t* x, int16_t* y, int16_t* z); // 读取原始 ADC 值（0–1023） void readG(float* x, float* y, float* z); // 读取加速度值（g 单位） void calibrateZeroG(); // 执行静态零点校准（需传感器静止放置） private: uint8_t _xPin, _yPin, _zPin; int16_t _xOffset, _yOffset, _zOffset; // 校准后零点偏移 float _sensitivity; // 灵敏度系数（mV/g → V/g） };begin()函数执行关键初始化：
- 调用
analogReference(DEFAULT)或analogReference(INTERNAL)设置 ADC 参考电压； - 调用
analogReadResolution(10)确保 10-bit 分辨率（对支持可变分辨率的 MCU）； - 执行三次
analogRead()并取平均，获取初始零点偏移存入_xOffset等成员变量； - 返回
true表示初始化成功，false表示读取异常（如引脚未连接）。
3.2 核心 API 详解
readRaw()—— 原始数据采集
此函数执行三通道同步（或准同步）ADC 采样，返回未经任何处理的数字值。其实现严格遵循最小化延迟原则：
// 7semi_ADXL335.cpp 关键片段 void ADXL335::readRaw(int16_t* x, int16_t* y, int16_t* z) { // 为减少通道间采样时序差，按固定顺序快速读取 *x = analogRead(_xPin); *y = analogRead(_yPin); *z = analogRead(_zPin); }注意：Arduino
analogRead()默认采样时间为 ~100 μs/通道，三通道总耗时约 300 μs。若需更高时间一致性，可在begin()中预配置 ADC 寄存器启用扫描模式（如 STM32 HAL 的HAL_ADC_Start_DMA()），但本库为保持跨平台简洁性，采用顺序读取。
readG()—— 物理量转换
该函数将原始 ADC 值转换为标准 g 单位，应用前述数学模型：
void ADXL335::readG(float* x, float* y, float* z) { int16_t rawX, rawY, rawZ; readRaw(&rawX, &rawY, &rawZ); // 使用校准偏移与灵敏度计算加速度 const float Vref = 5.0f; // 实际应根据硬件设置动态获取 const float S_mV_per_g = 300.0f; const float S_V_per_g = S_mV_per_g / 1000.0f; *x = (Vref / S_V_per_g) * (rawX - _xOffset) / 1023.0f; *y = (Vref / S_V_per_g) * (rawY - _yOffset) / 1023.0f; *z = (Vref / S_V_per_g) * (rawZ - _zOffset) / 1023.0f; }calibrateZeroG()—— 动态零点校准
此函数要求传感器在无振动、水平静止状态下运行，采集 32 次样本并取中位数，有效抑制随机噪声与温漂影响：
void ADXL335::calibrateZeroG() { const uint8_t SAMPLES = 32; int16_t xBuf[SAMPLES], yBuf[SAMPLES], zBuf[SAMPLES]; for (uint8_t i = 0; i < SAMPLES; i++) { readRaw(&xBuf[i], &yBuf[i], &zBuf[i]); delay(10); // 间隔 10 ms，避免 ADC 过热 } _xOffset = medianFilter(xBuf, SAMPLES); _yOffset = medianFilter(yBuf, SAMPLES); _zOffset = medianFilter(zBuf, SAMPLES); }medianFilter()为库内建的中值滤波函数，比均值滤波更能抵抗脉冲干扰。
3.3 配置参数与可移植性接口
为支持非 Arduino 平台，库预留了硬件抽象层（HAL）钩子。开发者需在移植时重写以下弱符号函数：
// 在平台特定文件中实现 __attribute__((weak)) int16_t adxl335_hal_read_adc(uint8_t channel) { // 示例：STM32 HAL 实现 HAL_ADC_Start(&hadc1); HAL_ADC_PollForConversion(&hadc1, HAL_MAX_DELAY); return HAL_ADC_GetValue(&hadc1); } __attribute__((weak)) void adxl335_hal_delay_ms(uint16_t ms) { HAL_Delay(ms); }所有analogRead()调用均被替换为adxl335_hal_read_adc()，delay()替换为adxl335_hal_delay_ms()。这种设计使库在保持 Arduino 兼容性的同时，具备向裸机或 RTOS 环境无缝迁移的能力。
4. 工程实践：从裸机到 FreeRTOS 集成
4.1 STM32 HAL 裸机移植实例
以 STM32F103C8T6（Blue Pill）为例，需完成以下步骤：
- 硬件配置：在 STM32CubeMX 中启用 ADC1，配置 PA0/PA1/PA2 为 ADC 通道 0/1/2，采样时间设为 55.5 cycles（保证精度）；
- HAL 层实现：
// adxl335_stm32_hal.c #include "stm32f1xx_hal.h" extern ADC_HandleTypeDef hadc1; int16_t adxl335_hal_read_adc(uint8_t channel) { ADC_ChannelConfTypeDef sConfig = {0}; sConfig.Channel = channel; sConfig.Rank = 1; sConfig.SamplingTime = ADC_SAMPLETIME_55CYCLES_5; HAL_ADC_ConfigChannel(&hadc1, &sConfig); HAL_ADC_Start(&hadc1); HAL_ADC_PollForConversion(&hadc1, HAL_MAX_DELAY); return HAL_ADC_GetValue(&hadc1); }- 主循环集成：
ADXL335 acc(A0, A1, A2); // 通道编号映射为 0,1,2 int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_ADC1_Init(); if (!acc.begin()) { Error_Handler(); // 初始化失败处理 } while (1) { float x, y, z; acc.readG(&x, &y, &z); printf("ACC: X=%.3fg Y=%.3fg Z=%.3fg\r\n", x, y, z); HAL_Delay(100); } }4.2 FreeRTOS 多任务协同方案
在资源受限的 FreeRTOS 系统中，推荐采用“生产者-消费者”模式分离采集与处理：
// 定义队列 QueueHandle_t accQueue; // 采集任务（高优先级，周期 10 ms） void vAccelTask(void *pvParameters) { ADXL335 acc(A0, A1, A2); acc.begin(); TickType_t xLastWakeTime = xTaskGetTickCount(); while (1) { float data[3]; acc.readG(&data[0], &data[1], &data[2]); // 发送至队列，非阻塞 if (xQueueSend(accQueue, data, 0) != pdPASS) { // 队列满，丢弃旧数据 } vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(10)); } } // 处理任务（低优先级） void vProcessTask(void *pvParameters) { float data[3]; while (1) { if (xQueueReceive(accQueue, data, portMAX_DELAY) == pdPASS) { // 执行姿态解算、阈值判断、数据打包等 if (fabsf(data[2]) > 1.2f) { // Z 轴超 1.2g 触发事件 triggerShockAlarm(); } } } } // 创建任务 accQueue = xQueueCreate(10, sizeof(float) * 3); xTaskCreate(vAccelTask, "ACC", 128, NULL, 3, NULL); xTaskCreate(vProcessTask, "PROC", 128, NULL, 1, NULL);此架构确保 ADC 采样严格按时序执行，而复杂计算在低优先级任务中异步完成，避免阻塞实时采集路径。
5. 校准方法与精度优化策略
5.1 两步校准法（推荐工业级应用）
ADXL335 的实际灵敏度与零点存在个体差异，仅靠单次calibrateZeroG()不足以满足 ±0.1 g 精度需求。推荐采用以下两步法：
第一步：六面静态校准（确定零点与比例因子）
将传感器牢固固定于精密转台，依次使 X/Y/Z 轴分别垂直向上、向下（共 6 个方位），每个方位静止 5 秒后记录readRaw()值。设某轴向上读数为 $D_{+g}$，向下为 $D_{-g}$，则：
- 零点偏移：$D_{bias} = \frac{D_{+g} + D_{-g}}{2}$
- 比例因子：$K = \frac{D_{+g} - D_{-g}}{2 \times 1023}$ （单位：g/LSB）
第二步：温度补偿（针对宽温域应用）
ADXL335 的零点温漂典型值为 1.5 mg/°C。若工作温度范围为 -20°C 至 +70°C，需外置温度传感器（如 DS18B20），建立零点偏移与温度的线性关系：
$D_{bias}(T) = D_{bias}(25°C) + \alpha \times (T - 25)$，其中 $\alpha \approx 1.5$ LSB/°C。
5.2 噪声抑制技术
- 硬件滤波：在 X/Y/Z 输出端各并联 10 nF 陶瓷电容至 GND，构成 RC 低通滤波器（截止频率 ≈ 500 Hz），抑制高频开关噪声；
- 软件滤波：在
readG()后追加一阶 IIR 滤波：filtered_x = 0.95f * filtered_x + 0.05f * raw_x;
时间常数约 20 ms，有效平滑机械振动； - 采样同步：若系统存在 PWM 或通信中断，将
readRaw()放置于SysTick中断服务程序（ISR）中，确保严格周期采样，避免相位抖动。
6. 典型故障诊断与解决方案
| 现象 | 可能原因 | 排查步骤 | 解决方案 |
|---|---|---|---|
| 所有轴读数恒为 0 或 1023 | 电源未接或 GND 虚焊 | 用万用表测 VCC-GND 电压；检查模块底部焊点 | 重新焊接 GND 引脚；确认电源电压在 3.3±0.3 V 或 5.0±0.5 V 范围内 |
| Z 轴读数显著高于 X/Y（静止时） | 未校准或安装倾斜 | 水平放置模块，运行calibrateZeroG() | 执行六面校准；检查 PCB 是否弯曲导致 Z 轴偏置 |
| 读数剧烈跳变（>50 LSB） | 电源噪声或 ADC 参考不稳 | 示波器观测 VCC 纹波；测量 Vref 引脚电压 | 加强电源去耦；改用内部参考电压；避免与电机共用电源 |
| X/Y 轴读数相同且不随运动变化 | X/Y 引脚短路或 MCU ADC 通道故障 | 断开模块，测量 X-OUT/Y-OUT 对地电压是否独立变化 | 更换模块；检查 MCU 引脚是否被其他外设复用 |
终极验证方法：将模块置于已知加速度场中测试。例如，将 Z 轴垂直向上静置，理论值应为 +1.000 g；水平旋转 90° 后，X 或 Y 轴应显示 +1.000 g。偏差 > 0.05 g 即需重新校准。
本库的设计哲学是“以最简硬件达成最高确定性”，它不追求花哨的 FIFO 或中断触发，而是将工程师的注意力拉回模拟信号链的本质——电源质量、接地设计、ADC 配置与物理校准。当你的项目需要在 8-bit AVR 上稳定运行十年，或在 -40°C 工业现场持续监测振动频谱，ADXL335 与这套经过验证的驱动方案，依然是值得信赖的基石。
