树莓派4B连接摇杆模块实战：从ADC选型到Python控制类封装

1. 从游戏手柄到硬件交互：为什么树莓派需要摇杆？

如果你手头有一块树莓派4B，并且已经玩腻了点亮LED、读取温湿度这些基础操作，那么是时候给它增加点“互动性”了。JoyStick摇杆，这个我们从小在游戏手柄上就无比熟悉的部件，绝不仅仅是用来打游戏的。在树莓派的世界里，它摇身一变，成为一个极其直观、低成本且功能强大的模拟量输入设备。

想象一下，你可以用它来控制一个机器人小车的行进方向和速度，或者用它作为一台自制数控雕刻机的操纵杆，甚至用它来调整一个智能家居中控台的参数旋钮。与简单的数字按钮（只有开/关两种状态）不同，摇杆输出的是一组连续的、可变的模拟信号。这组信号通常对应着二维平面上的X轴和Y轴坐标，有些摇杆还集成了一个下压按钮（Z轴）。这种连续的输入能力，使得摇杆在需要精细控制或连续反馈的应用场景中无可替代。

树莓派4B本身并没有内置的模拟信号输入引脚（ADC），这是它与Arduino等微控制器的一个关键区别。因此，要让树莓派“读懂”摇杆，我们需要一个“翻译官”——模数转换器（ADC）。最常用、也最经济实惠的方案就是PCF8591或ADS1115这类ADC芯片。本课的核心，就是打通从摇杆物理摆动，到ADC芯片采样，再到树莓派Python程序解读的完整链路。整个过程不仅涉及硬件连接、电路理解，更关乎如何编写稳定、可靠的软件来读取和处理模拟信号，这正是嵌入式开发从“玩具”迈向“工具”的关键一步。

2. 硬件选型与连接：不只是插上线那么简单

在动手焊接或插线之前，搞清楚你手中的“兵器”至关重要。市面上常见的摇杆模块主要分为两种类型，它们的输出信号有本质区别，直接决定了后续的电路和代码设计。

2.1 认识两种主流的摇杆模块

第一种是模拟量摇杆模块。这是最经典、也是最符合我们认知的摇杆。它内部通常是两个独立的电位器（可变电阻），分别对应X轴和Y轴。当你推动摇杆时，电位器的阻值连续变化。模块上通常会集成一个简单的分压电路，将变化的电阻值转换为0V到VCC（通常是3.3V或5V）之间变化的电压信号输出。所以，这类模块会引出5根线：VCC（电源正极）、GND（电源负极）、VRx（X轴模拟电压输出）、VRy（Y轴模拟电压输出）和SW（摇杆下压按钮的数字信号输出，按下时通常接地）。它的输出是连续的模拟电压，必须依赖ADC芯片才能被树莓派读取。

第二种是摇杆传感器模块。这种模块内部已经集成了ADC芯片（常见的是ADS1115的变种）和微处理器。它不再输出原始的模拟电压，而是通过I2C或SPI等数字通信协议，直接输出已经转换好的数字坐标值。你只需要连接VCC、GND、SDA、SCL四根线到树莓派，就能在程序中直接读取坐标。这种模块省去了外接ADC的麻烦，但价格稍高，且灵活性较低（例如，采样率、增益可能被固定）。

对于学习和理解底层原理而言，我强烈推荐从第一种模拟量摇杆模块配合独立ADC芯片开始。这能让你清晰地看到信号从模拟到数字的完整转换过程，遇到问题时也更容易分段排查。

2.2 ADC芯片的选择：PCF8591 vs. ADS1115

既然选择了模拟量摇杆，ADC芯片就是必需品。这里有两个主流候选：

• PCF8591：一款8位精度、4通道的ADC（也带1路DAC，但此处用不到）。价格极其低廉（通常几毛钱），通过I2C通信。8位精度意味着它能把0-3.3V的电压分成2^8=256个等级，每个等级约代表0.0129V（3.3V/256）。对于很多要求不高的控制应用（如遥控小车），这已经足够了。它的优点是便宜、接口简单。
• ADS1115：一款16位精度、4通道的ADC，同样通过I2C通信。16位精度提供了2^16=65536个等级，分辨率高达0.00005V（3.3V/65536）。这意味着它的读数要精细得多，抖动更小，能感知更微小的摇杆移动。如果你的项目需要高精度定位（比如绘图仪），ADS1115是更好的选择。它的价格是PCF8591的十倍左右，但依然在可接受范围。

我个人的建议是：如果预算允许，直接上ADS1115。更高的精度能带来更平滑的控制体验，减少软件滤波的处理压力，而且其库更稳定，抗干扰能力也更强。PCF8591在读数时偶尔会出现较大的跳变，需要你在代码中做更多的平滑处理。

2.3 实战接线图与安全注意事项

我们以模拟量摇杆模块+ADS1115模块+树莓派4B的组合为例，进行连接。请务必在断电状态下操作！

接线清单：

• 树莓派4B 主板 x1
• 模拟量摇杆模块 x1
• ADS1115模块 x1
• 杜邦线（母对母）若干

连接步骤：

1. 为ADS1115供电：将ADS1115模块的VDD引脚连接到树莓派的3.3V引脚（物理引脚1或17）。非常重要：必须接3.3V！因为ADS1115的I2C通信电平需要与树莓派GPIO的3.3V电平匹配，接5V可能会损坏树莓派。
2. 共地：将ADS1115的GND、摇杆模块的GND，一同连接到树莓派的任意GND引脚（例如物理引脚6, 9, 14, 20等）。
3. 连接I2C总线：将ADS1115的SCL和SDA分别连接到树莓派的SCL（物理引脚5/GPIO3）和SDA（物理引脚3/GPIO2）。
4. 为摇杆供电：将摇杆模块的VCC连接到树莓派的3.3V或5V。这里有一个关键选择：
   • 接3.3V：摇杆输出的电压范围是0-3.3V，与ADS1115的输入范围完美匹配，读数最准确。
   • 接5V：摇杆输出的电压范围是0-5V。此时，绝对不能直接将VRx/VRy接到ADS1115上，因为ADS1115的输入电压不能超过电源电压(VDD=3.3V)。你需要用两个电阻组成分压电路（例如，将5V分压至3.3V以下）才能接入。为了简化，强烈建议初学者将摇杆VCC接3.3V。
5. 连接信号线：将摇杆模块的VRx和VRy分别连接到ADS1115的任意两个模拟输入通道，例如A0和A1。
6. 连接按钮（可选）：将摇杆模块的SW引脚连接到树莓派的一个GPIO（如GPIO17/物理引脚11），并通过一个上拉电阻（软件或硬件）连接到3.3V。当按钮按下时，该引脚被拉低（接地），程序可检测到低电平。

注意：接线时务必仔细核对引脚。接错电源线是烧毁设备的最快途径。建议使用不同颜色的杜邦线区分电源（红色）、地线（黑色）和信号线（黄、绿等）。

3. 软件环境搭建与基础测试

硬件连接无误后，我们进入软件层面。树莓派系统（以Raspbian/Raspberry Pi OS为例）已经为我们准备好了大部分基础设施。

3.1 启用I2C接口并安装驱动库

首先，确保树莓派的I2C接口已启用。在终端中执行：

sudo raspi-config

依次选择Interface Options->I2C->Yes启用它。重启后，可以通过命令ls /dev/i2c-*来检查，如果看到/dev/i2c-1则说明启用成功。

接下来，安装Python的ADS1115驱动库。我们使用Adafruit_ADS1x15这个广泛使用的库。

sudo apt update sudo apt install python3-pip pip3 install adafruit-circuitpython-ads1x15

这个库依赖于Adafruit_Blinka，它提供了CircuitPython在树莓派上的兼容层，通常pip会自动安装其依赖。

3.2 编写第一个读数脚本：理解原始数据

让我们先写一个最简单的脚本，看看ADS1115读到的“原始值”是什么样子。创建一个文件，比如joystick_test.py。

import time import board import busio import adafruit_ads1x15.ads1115 as ADS from adafruit_ads1x15.analog_in import AnalogIn # 创建I2C总线对象 i2c = busio.I2C(board.SCL, board.SDA) # 创建ADS1115对象，默认I2C地址是0x48 ads = ADS.ADS1115(i2c) # 如果你用的是ADS1015（12位精度），则使用 ADS.ADS1015(i2c) # 设置增益（GAIN），这决定了ADC的量程。 # GAIN=1 对应 +/-4.096V，这是我们接3.3V时的安全选择。 ads.gain = 1 # 创建两个模拟输入通道对象，分别对应我们接线的A0和A1 chan_x = AnalogIn(ads, ADS.P0) # A0 接摇杆X轴 (VRx) chan_y = AnalogIn(ads, ADS.P1) # A1 接摇杆Y轴 (VRy) print("按下 Ctrl+C 退出程序") try: while True: # 读取原始值（16位有符号整数，范围 -32768 到 32767） raw_x = chan_x.value raw_y = chan_y.value # 读取电压值（单位：伏特） voltage_x = chan_x.voltage voltage_y = chan_y.voltage print(f"X: {raw_x:6d} ({voltage_x:.3f}V) | Y: {raw_y:6d} ({voltage_y:.3f}V)") time.sleep(0.5) # 每秒读取2次 except KeyboardInterrupt: print("\n程序结束")

运行这个脚本：python3 joystick_test.py。现在，尝试推动摇杆，观察终端输出的变化。

你会观察到什么？当摇杆处于中心位置（通常有个弹簧会自动回中）时，voltage_x和voltage_y应该都在1.65V左右（3.3V的一半）。向一个方向推动，对应轴的电压会从1.65V向0V或3.3V变化。raw_value则是ADC芯片根据这个电压转换出的数字，其范围与增益(GAIN)设置有关。这是我们所有控制逻辑的“原材料”。

4. 数据处理与校准：从原始电压到可用坐标

直接使用原始电压或数值是不方便的。我们更希望得到像“X轴：-100到100”，“中心点是0”这样直观的坐标。这就需要校准和映射。

4.1 校准：找到每个轴的极限值与中心值

摇杆的物理特性决定了，即使它在中心，输出电压也可能不是精确的1.65V。而且，由于电位器工艺和电路误差，它向两个方向能到达的最大/最小电压也可能不对称。因此，校准是必不可少的一步。

我们需要获取三个关键值：min（最小值）、max（最大值）、center（中心值）。修改上面的测试脚本，加入校准环节。

import time, board, busio import adafruit_ads1x15.ads1115 as ADS from adafruit_ads1x15.analog_in import AnalogIn i2c = busio.I2C(board.SCL, board.SDA) ads = ADS.ADS1115(i2c) ads.gain = 1 chan_x = AnalogIn(ads, ADS.P0) chan_y = AnalogIn(ads, ADS.P1) # 初始化校准变量 cal_x = {'min': 32767, 'max': -32768, 'center': 0} cal_y = {'min': 32767, 'max': -32768, 'center': 0} print("=== 摇杆校准开始 ===") print("请缓慢地将摇杆向各个方向推到极限，并绕圈转动几次。") print("持续约10秒后，程序会自动记录最大最小值并计算中心。") print("完成后请按 Ctrl+C。") start_time = time.time() try: while time.time() - start_time < 10: # 校准10秒 raw_x = chan_x.value raw_y = chan_y.value # 更新最小值 if raw_x < cal_x['min']: cal_x['min'] = raw_x if raw_y < cal_y['min']: cal_y['min'] = raw_y # 更新最大值 if raw_x > cal_x['max']: cal_x['max'] = raw_x if raw_y > cal_y['max']: cal_y['max'] = raw_y time.sleep(0.05) # 快速采样 # 计算中心值（假设松开后摇杆会自动回中，此时读取的值作为中心） print("\n请松开摇杆，让其回到中心位置，等待3秒...") time.sleep(3) cal_x['center'] = chan_x.value cal_y['center'] = chan_y.value print("\n=== 校准结果 ===") print(f"X轴 - 最小值: {cal_x['min']}, 最大值: {cal_x['max']}, 中心值: {cal_x['center']}") print(f"Y轴 - 最小值: {cal_y['min']}, 最大值: {cal_y['max']}, 中心值: {cal_y['center']}") # 可以将这些值保存到文件，以后直接加载，无需每次校准 with open('joystick_calibration.txt', 'w') as f: f.write(f"{cal_x['min']},{cal_x['max']},{cal_x['center']}\n") f.write(f"{cal_y['min']},{cal_y['max']},{cal_y['center']}\n") print("校准数据已保存到 joystick_calibration.txt") except KeyboardInterrupt: print("\n校准被用户中断。")

运行这个校准脚本，并按照提示操作。完成后，你会得到一组属于你这个特定摇杆模块的“身份参数”。请务必保存好这个文件。

4.2 映射：将原始值转换为标准坐标

有了校准数据，我们就可以编写一个映射函数，将任意时刻读取的原始值，转换到一个我们定义的标准范围内，例如-100 到 100，其中0代表中心。

这里的关键是处理不对称的范围。摇杆向左推到底的原始值（min）到中心值（center）的距离，可能不等于中心值到向右推到底（max）的距离。简单的线性映射(raw - center) / (max - min) * 200 - 100会导致中心点不在0，或者极限值到不了-100/100。

一个更健壮的映射方法是分段线性映射：

def map_joystick_value(raw_val, cal_dict, output_range=(-100, 100)): """ 将原始ADC值映射到指定的输出范围。 :param raw_val: 当前读取的原始值 :param cal_dict: 包含‘min’， ‘max’， ‘center’的字典 :param output_range: 目标输出范围，默认为(-100, 100) :return: 映射后的整数值 """ out_min, out_max = output_range center = cal_dict['center'] if raw_val <= center: # 在中心点左侧（或下方） input_range = center - cal_dict['min'] if input_range == 0: # 防止除零 return out_min # 映射到 [out_min, 0] return int((raw_val - cal_dict['min']) / input_range * (0 - out_min) + out_min) else: # 在中心点右侧（或上方） input_range = cal_dict['max'] - center if input_range == 0: return out_max # 映射到 [0, out_max] return int((raw_val - center) / input_range * (out_max - 0))

这个函数会判断当前值在中心点的哪一侧，然后分别用该侧的输入范围进行映射，确保中心点严格对应0，并且两个极限值能到达-100和100。

4.3 死区处理：消除中心点附近的抖动

即使摇杆在物理上回到了中心，ADC读数和我们的映射值也可能在0附近微小波动（比如在-2到+2之间跳动）。这在控制应用中会导致电机或舵机在“停止”指令下仍然微微颤动。我们需要引入“死区”概念。

死区是一个阈值，当映射后的坐标绝对值小于这个阈值时，我们强制将其视为0。

def apply_deadzone(value, deadzone_threshold=5): """ 应用死区过滤。 :param value: 映射后的坐标值 :param deadzone_threshold: 死区阈值，默认为5（即坐标在-5到5之间视为0） :return: 应用死区后的值 """ if abs(value) < deadzone_threshold: return 0 return value

将映射和死区处理集成到主循环中，我们就能得到稳定、可用的摇杆坐标了。

5. 构建一个完整的摇杆控制类

将上述所有功能封装成一个类，会让后续的项目开发变得非常清晰和方便。下面是一个功能完整的摇杆类示例，它包含了初始化、校准数据加载/保存、实时读取并返回处理后的坐标等功能。

import time, board, busio import adafruit_ads1x15.ads1115 as ADS from adafruit_ads1x15.analog_in import AnalogIn class Joystick: def __init__(self, i2c_bus=None, address=0x48, x_channel=ADS.P0, y_channel=ADS.P1): """ 初始化摇杆对象。 :param i2c_bus: 可传入一个已创建的I2C对象，默认为None会自动创建。 :param address: ADS1115的I2C地址，默认为0x48。 :param x_channel: X轴连接的ADS1115通道，默认为A0。 :param y_channel: Y轴连接的ADS1115通道，默认为A1。 """ if i2c_bus is None: self.i2c = busio.I2C(board.SCL, board.SDA) else: self.i2c = i2c_bus self.ads = ADS.ADS1115(self.i2c, address=address) self.ads.gain = 1 # +/-4.096V self.chan_x = AnalogIn(self.ads, x_channel) self.chan_y = AnalogIn(self.ads, y_channel) # 校准数据 self.cal_x = {'min': 0, 'max': 0, 'center': 0} self.cal_y = {'min': 0, 'max': 0, 'center': 0} self.deadzone = 5 self.output_range = (-100, 100) def calibrate(self, duration=10): """执行校准流程，持续 duration 秒。""" print("开始校准，请将摇杆推到所有极限位置并旋转...") self.cal_x = {'min': 32767, 'max': -32768} self.cal_y = {'min': 32767, 'max': -32768} start = time.time() while time.time() - start < duration: raw_x = self.chan_x.value raw_y = self.chan_y.value self.cal_x['min'] = min(self.cal_x['min'], raw_x) self.cal_x['max'] = max(self.cal_x['max'], raw_x) self.cal_y['min'] = min(self.cal_y['min'], raw_y) self.cal_y['max'] = max(self.cal_y['max'], raw_y) time.sleep(0.05) print("请松开摇杆回中...") time.sleep(3) self.cal_x['center'] = self.chan_x.value self.cal_y['center'] = self.chan_y.value print(f"校准完成。X: {self.cal_x}, Y: {self.cal_y}") return self.cal_x, self.cal_y def save_calibration(self, filename='joystick_cal.txt'): """保存校准数据到文件。""" with open(filename, 'w') as f: f.write(f"{self.cal_x['min']},{self.cal_x['max']},{self.cal_x['center']}\n") f.write(f"{self.cal_y['min']},{self.cal_y['max']},{self.cal_y['center']}\n") print(f"校准数据已保存至 {filename}") def load_calibration(self, filename='joystick_cal.txt'): """从文件加载校准数据。""" try: with open(filename, 'r') as f: lines = f.readlines() x_vals = list(map(int, lines[0].strip().split(','))) y_vals = list(map(int, lines[1].strip().split(','))) self.cal_x = {'min': x_vals[0], 'max': x_vals[1], 'center': x_vals[2]} self.cal_y = {'min': y_vals[0], 'max': y_vals[1], 'center': y_vals[2]} print(f"校准数据已从 {filename} 加载。") return True except FileNotFoundError: print(f"错误：找不到校准文件 {filename}。请先运行 calibrate()。") return False except Exception as e: print(f"加载校准文件时出错：{e}") return False def _map_value(self, raw_val, cal_dict): """内部方法：根据校准字典映射单个值。""" out_min, out_max = self.output_range center = cal_dict['center'] if raw_val <= center: input_range = center - cal_dict['min'] if input_range == 0: return out_min mapped = (raw_val - cal_dict['min']) / input_range * (0 - out_min) + out_min else: input_range = cal_dict['max'] - center if input_range == 0: return out_max mapped = (raw_val - center) / input_range * (out_max - 0) return int(mapped) def _apply_deadzone(self, value): """内部方法：应用死区。""" if abs(value) < self.deadzone: return 0 return value def read(self): """ 读取并处理摇杆状态。 :return: 一个字典，包含处理后的x, y坐标以及原始电压值。 """ raw_x = self.chan_x.value raw_y = self.chan_y.value volt_x = self.chan_x.voltage volt_y = self.chan_y.voltage # 映射坐标 mapped_x = self._map_value(raw_x, self.cal_x) mapped_y = self._map_value(raw_y, self.cal_y) # 应用死区 final_x = self._apply_deadzone(mapped_x) final_y = self._apply_deadzone(mapped_y) return { 'x': final_x, 'y': final_y, 'raw_x': raw_x, 'raw_y': raw_y, 'voltage_x': volt_x, 'voltage_y': volt_y } # 使用示例 if __name__ == "__main__": js = Joystick() # 尝试加载已有校准，如果不存在则执行一次校准 if not js.load_calibration(): js.calibrate(duration=8) js.save_calibration() js.deadzone = 5 # 可根据手感调整死区大小 print("开始读取摇杆坐标（应用了死区）。按 Ctrl+C 退出。") try: while True: data = js.read() # 只显示处理后的坐标，更清晰 print(f"X: {data['x']:4d}, Y: {data['y']:4d}", end='\r') # \r 使输出在同一行刷新 time.sleep(0.1) except KeyboardInterrupt: print("\n程序结束。")

这个类提供了完整的封装。在你的机器人或控制项目中，只需要初始化一个Joystick对象，然后在主循环中调用js.read()，就能轻松获取到稳定、校准好的x和y坐标值，直接用于控制逻辑。

6. 项目实战：用摇杆控制一个模拟的机器人小车

为了将所学知识串联起来，我们设计一个简单的模拟项目：用摇杆控制一个在命令行中“移动”的机器人小车。这个项目不涉及真实的电机，但包含了完整的控制逻辑，你可以轻易地将其替换成对真实电机驱动板（如L298N、TB6612）的GPIO控制。

我们的控制逻辑设计如下：

• Y轴（前后）：控制小车的前进/后退速度。向前推，速度为正（前进）；向后拉，速度为负（后退）。推力越大，速度绝对值越大。
• X轴（左右）：控制小车的转向。向左推，左转；向右推，右转。推动幅度越大，转向角速度越大。
• 混合控制：当同时推动X和Y轴时，实现差速转向。例如，向前并向右推，右侧轮子速度减慢，左侧轮子速度加快，实现向右转弯前进。

这是一个典型的“双电机差速驱动”模型。我们假设小车有两个独立的驱动轮。

import time from joystick_class import Joystick # 假设上面的类保存为 joystick_class.py class SimulatedRobot: def __init__(self): self.left_speed = 0 # 左轮目标速度，范围 -100 到 100 self.right_speed = 0 # 右轮目标速度，范围 -100 到 100 self.max_speed = 100 def calculate_speeds(self, joy_x, joy_y): """ 根据摇杆坐标计算左右轮速度。 这是一个简单的差速算法。 :param joy_x: 摇杆X坐标 (-100 ~ 100) :param joy_y: 摇杆Y坐标 (-100 ~ 100) """ # 将摇杆的二维坐标转换为速度和转向 # 基础速度分量来自Y轴（前后） base_speed = joy_y # 转向分量来自X轴（左右）。我们让一个轮子加速，另一个减速。 # 这里使用一个简单的比例混合。turn_factor 可调整转向灵敏度。 turn_factor = 0.5 turn_effect = joy_x * turn_factor # 计算每个轮子的速度 # 左轮速度 = 基础速度 + 转向影响（向左转时，joy_x为负，turn_effect为负，左轮应减速） # 右轮速度 = 基础速度 - 转向影响（向左转时，右轮应加速以产生差速） left = base_speed + turn_effect right = base_speed - turn_effect # 确保速度不超过最大范围 self.left_speed = max(-self.max_speed, min(self.max_speed, int(left))) self.right_speed = max(-self.max_speed, min(self.max_speed, int(right))) def update_display(self): """在命令行模拟显示小车状态。""" # 用简单的字符表示速度和方向 left_dir = 'F' if self.left_speed > 0 else 'B' if self.left_speed < 0 else 'S' right_dir = 'F' if self.right_speed > 0 else 'B' if self.right_speed < 0 else 'S' print(f"[L:{left_dir}{abs(self.left_speed):3d}] [R:{right_dir}{abs(self.right_speed):3d}]", end='\r') def main(): # 初始化摇杆和机器人 joystick = Joystick() robot = SimulatedRobot() # 加载校准 if not joystick.load_calibration(): print("未找到校准文件，请先运行校准程序。") return print("模拟机器人控制已启动。使用摇杆控制，按 Ctrl+C 退出。") print("Y轴控制前后速度，X轴控制转向。") try: while True: # 读取摇杆 data = joystick.read() joy_x, joy_y = data['x'], data['y'] # 计算电机速度 robot.calculate_speeds(joy_x, joy_y) # 更新显示（在实际项目中，这里应调用驱动电机的函数） robot.update_display() # 控制循环频率 time.sleep(0.05) # 约20Hz except KeyboardInterrupt: print("\n\n模拟结束。") # 在实际硬件中，这里应发送停止指令给电机 print("机器人已停止。") if __name__ == "__main__": main()

运行这个模拟程序，你会在命令行看到随着你推动摇杆，左右轮的“速度”和“方向”在实时变化。这完全模拟了真实小车底盘的控制逻辑。当你将robot.update_display()和速度计算部分，替换成向电机驱动板发送PWM信号的代码时，一个真实的遥控小车就诞生了。

7. 进阶话题与故障排查

掌握了基础应用后，我们可以探讨一些更深入的问题和常见坑点。

7.1 信号噪声与软件滤波

即使使用了高精度的ADS1115，读取到的数值也可能存在细微的、快速的跳动（噪声）。除了硬件上确保电源稳定、连线牢固外，软件滤波是提升稳定性的有效手段。最简单的是一阶低通滤波（指数平滑），它用一个简单的公式来平滑数据：

filtered_value = alpha * new_raw_value + (1 - alpha) * previous_filtered_value

其中alpha是一个介于0和1之间的系数（如0.3）。alpha越大，对新值的响应越快，但平滑效果越弱；alpha越小，曲线越平滑，但延迟越大。你可以在Joystick类的read方法内部加入这个滤波逻辑，对raw_x和raw_y进行平滑后再进行映射和死区处理。

7.2 摇杆按钮的读取与防抖

许多摇杆模块集成了一个下压按钮（SW）。它是一个数字输入，按下时连接GND（低电平），松开时由于模块内部或外部上拉电阻而处于高电平。在树莓派上读取它，需要配置一个GPIO引脚为输入模式并启用内部上拉。

import digitalio from board import * # 初始化按钮引脚，假设接在GPIO17（物理引脚11） button_pin = D17 # 根据实际连接修改 button = digitalio.DigitalInOut(button_pin) button.direction = digitalio.Direction.INPUT button.pull = digitalio.Pull.UP # 启用内部上拉电阻 # 在主循环中读取 while True: if not button.value: # 按钮按下时为低电平 print("按钮被按下！") # 这里可以添加防抖逻辑 time.sleep(0.05)

按钮防抖是必须的。机械触点闭合时会产生快速的通断抖动，程序可能会在几毫秒内检测到多次按下。简单的防抖方法是：当检测到按下状态后，等待一段时间（如50毫秒）再次检测，如果状态依然是按下，才认为是有效按键。

7.3 常见问题与排查清单

1. 读取的值全是0或固定不变：

   • 检查I2C连接：运行sudo i2cdetect -y 1命令，查看ADS1115的地址（默认0x48）是否出现在列表中。如果没有，检查接线、电源，并确认I2C已启用。
   • 检查电源：确认ADS1115的VDD接的是3.3V，摇杆VCC接的是3.3V或5V（配合分压电路）。
   • 检查信号线：确认VRx、VRy正确连接到了ADS1115的A0, A1，而不是接反或接触不良。

2. 数值跳动剧烈，无法稳定：

   • 电源噪声：尝试给树莓派和ADC模块使用独立、稳定的电源，或在线路上加滤波电容。
   • 软件滤波：如7.1所述，增加低通滤波算法。
   • 检查接地：确保所有设备的GND都良好地连接到一起（共地）。

3. 摇杆推到极限，坐标值到不了-100或100：

   • 校准不充分：在校准过程中，确保将摇杆缓慢且彻底地推到每个方向的物理极限。
   • 硬件限制：有些廉价摇杆的电位器物理范围可能达不到完整的0-VCC电压。校准程序记录的min和max就是它的实际范围，映射函数会处理这种情况，极限值可能对应-95和95，这在实际使用中完全可以接受。

4. 中心点漂移：

   • 这是模拟电位器的通病，受温度和使用寿命影响。定期重新校准可以解决。在要求高的场合，可以在程序中加入“自动回中校准”逻辑：当检测到摇杆在很小范围内长时间无变化时，自动将这个位置的平均值更新为新的中心点。

从硬件连接到软件处理，从原始数据到精准坐标，再到封装成类并投入实际项目，这套流程覆盖了树莓派使用摇杆的完整知识链。最关键的一步永远是动手：接好线，运行代码，观察数据，然后根据现象去调整和优化。当你看到命令行中随着你手腕晃动而流畅变化的数字，或者你制作的小车听话地前进转弯时，这种软硬件结合的成就感，正是树莓派编程最大的乐趣所在。