基于Adafruit CLUE与BLE CSC服务构建自行车传感器数据采集系统

1. 项目概述：打造你的专属自行车数据仪表盘

如果你和我一样，既喜欢折腾硬件，又是个骑行爱好者，那么把两者结合起来，做一个能实时显示速度和踏频的自行车码表，绝对是件充满乐趣的事。市面上成熟的码表产品很多，但它们往往是个“黑盒子”，你只知道结果，却不知道数据是怎么来的。而今天我们要聊的，就是如何用一块开源硬件开发板——Adafruit CLUE，通过蓝牙低功耗（BLE）技术，直接“对话”你的自行车传感器，把最原始的转数数据抓取出来，并显示在一块小屏幕上。这不仅仅是复现一个功能，更是深入理解物联网设备如何通信、数据如何从物理世界被感知并数字化的绝佳实践。

整个项目的核心，是理解并运用一个名为“Cycling Speed and Cadence”（CSC）的标准化蓝牙服务。无论是Wahoo Blue SC这类二合一传感器，还是独立的踏频、速度计，只要它们支持BLE和CSC规范，就都能成为我们的数据源。我们将使用CircuitPython这一对初学者极其友好的微控制器编程环境，在CLUE这块集成了屏幕、蓝牙和多种传感器的板子上，编写代码来扫描、连接传感器，并持续读取车轮和曲柄的累计转数。最终，这些原始数据会实时显示在CLUE自带的彩色屏幕上。虽然我们这次只显示原始转数，但这恰恰是所有高级计算（如实时速度、平均踏频）的基石。掌握了数据获取，后续你想怎么玩都可以。

2. 核心硬件与软件栈解析

2.1 硬件选型：为什么是Adafruit CLUE？

工欲善其事，必先利其器。选择Adafruit CLUE作为本项目的主控板，是基于几个非常实际的考量。

首先，集成度极高。CLUE板载了Nordic nRF52840芯片，这是一颗支持蓝牙5.0的低功耗微控制器，BLE通信能力是其原生强项，无需额外模块。同时，它拥有一块1.3英寸的彩色TFT屏幕，分辨率是240x240，足够清晰地显示几行文本数据，这省去了我们外接显示屏的麻烦。对于自行车码表这种需要便携和实时查看的应用，自带屏幕是巨大的优势。

其次，开发体验友好。CLUE完全兼容CircuitPython，这意味着你可以像操作U盘一样，把代码文件（code.py）拖到板子的CIRCUITPY盘符里，它就会自动运行。没有复杂的编译、烧录过程，调试信息可以直接通过串口输出，对新手和快速原型开发极其友好。

最后，生态支持完善。Adafruit为其硬件提供了高质量的CircuitPython库支持。对于本项目至关重要的adafruit_ble库以及专门为CSC服务封装的adafruit_ble_cycling_speed_and_cadence库，都由Adafruit官方维护，稳定性和易用性有保障。adafruit_clue库更是封装了屏幕、传感器等所有板载资源的简单调用方法，让我们能专注于业务逻辑。

注意：市面上也有一些其他优秀的开发板，如ESP32系列，其蓝牙功能同样强大且性价比更高。但CLUE的优势在于“开箱即用”的完整性和Adafruit生态对CircuitPython的深度优化，这对于希望快速实现功能、减少底层调试时间的开发者来说，是更高效的选择。

2.2 传感器选择：理解CSC服务的两种实现

自行车速度踏频传感器的核心是检测旋转。根据检测原理，主要分为磁铁式和惯性测量单元（IMU）式。

磁铁式传感器，如Wahoo Blue SC，是经典设计。它包含两个部分：一个主体（内含霍尔传感器和电路）和一对磁铁。一个磁铁安装在车轮辐条上，另一个安装在曲柄上。每当磁铁经过传感器主体，霍尔传感器就会产生一个脉冲信号，电路将其计为一次“转数事件”。这种方案原理简单，抗干扰强，精度高，但安装需要调整磁铁与传感器的间隙（通常2-5mm），略显繁琐。

IMU式传感器，如Wahoo RPM Speed/Cadence，则更加智能。它内部集成了加速度计和陀螺仪，通过算法识别车轮或曲柄特有的旋转模式，从而计算转数。它的最大优点是安装方便，只需用扎带固定在辐条或曲柄上即可，无需对齐磁铁。但其功耗可能略高，且在极端颠簸环境下算法可能受干扰。

无论哪种类型，只要它们通过蓝牙广播并遵循Cycling Speed and Cadence (CSC) GATT服务规范，我们的CLUE就能识别并连接。这个规范由蓝牙技术联盟（Bluetooth SIG）制定，确保了不同品牌设备间的互操作性。在代码中，我们正是通过寻找广播中包含CyclingSpeedAndCadenceServiceUUID的设备来锁定目标的。

2.3 软件环境：CircuitPython与关键库

CircuitPython是MicroPython的一个分支，专为教育和小型物联网设备优化。它的哲学是“简单”：去掉复杂的环境配置，让编程回归到编辑文本文件本身。

对于本项目，你需要准备以下软件环境：

1. CircuitPython固件：从circuitpython.org下载对应CLUE的最新.uf2文件。
2. 代码编辑器：推荐Mu Editor，它内置了串口监视器和CircuitPython模式，非常适合交互式调试。当然，任何纯文本编辑器（如VS Code、Sublime Text）也都可以。
3. 项目库文件：这是项目的核心依赖。你需要将以下几个库文件或文件夹放入CLUE板CIRCUITPY盘符下的lib文件夹中：
   • adafruit_ble：提供核心的BLE通信功能。
   • adafruit_ble_cycling_speed_and_cadence：专门用于解析CSC服务的库，封装了数据解析的复杂细节。
   • adafruit_clue：简化CLUE板载资源（如屏幕）操作的库。
   • adafruit_display_text、adafruit_bus_device等（通常作为adafruit_clue的依赖会自动包含或需要单独安装）。

最省事的方法是下载项目方提供的“项目包”（Project Bundle），它通常是一个ZIP文件，解压后包含了所有必需的库文件和主程序code.py，直接复制到CIRCUITPY根目录即可。

3. BLE通信与CSC服务深度剖析

3.1 BLE基础概念：GAP与GATT

要读懂代码，必须先理解蓝牙低功耗（BLE）通信的两个基本模式：GAP和GATT。你可以把它们想象成社交活动中的两个阶段。

GAP（通用访问配置文件）负责“广播和发现”，相当于社交场合中的“自我介绍”环节。在这个阶段，设备（称为外设，Peripheral，比如我们的自行车传感器）会周期性地向外广播一个小数据包，里面包含了自己的名字（设备名）、能提供什么服务（比如“我这里有CSC服务”）、以及如何连接等信息。而我们的CLUE板，在这个阶段扮演中心设备（Central）的角色，它打开收音机（开始扫描），监听周围所有的广播，并从中筛选出我们感兴趣的目标（即广播了CSC服务的设备）。

GATT（通用属性配置文件）则负责“建立连接后的深度交流”。一旦CLUE（中心设备）决定与某个传感器（外设）连接，双方的角色会进行一次转换。连接后，提供数据的一方（传感器）被称为服务器（Server），而请求数据的一方（CLUE）则被称为客户端（Client）。所有的数据交换都在GATT框架下进行，其核心结构是“服务-特征值-描述符”层级模型。

3.2 CSC服务的数据结构

对于自行车传感器，它提供的GATT服务就是“Cycling Speed and Cadence Service”。在这个服务下，定义了多个特征值（Characteristic），每个特征值承载一类具体数据。对我们最重要的两个是：

1. CSC测量特征值（CSC Measurement）：这是数据流的核心。它是一个“通知”（Notify）类型的特征值，意味着服务器（传感器）会在有新数据时（比如转数更新），主动推送（通知）给已订阅的客户端（CLUE），无需CLUE反复询问。这个特征值里封装的数据结构包括：

   • cumulative_wheel_revolutions：车轮累计转数（32位无符号整数）。这是从传感器启动或上次清零以来，车轮转过的总圈数。
   • last_wheel_event_time：上次车轮事件时间（16位无符号整数，单位1/1024秒）。记录最后一次检测到磁铁或旋转事件的时间戳。
   • cumulative_crank_revolutions：曲柄累计转数（16位无符号整数）。
   • last_crank_event_time：上次曲柄事件时间（16位无符号整数，单位1/1024秒）。

   有了累计转数和对应的时间戳，我们就可以计算出瞬时速度或踏频。例如，速度 = (本次转数 - 上次转数) * 车轮周长 / (本次时间 - 上次时间)。本项目先专注于获取这些原始值。

2. CSC特征值（CSC Feature）：这是一个“读取”（Read）类型的特征值，客户端可以读取它以了解传感器支持哪些功能，例如是否支持车轮转速数据、是否支持曲柄转速数据等。

3. 传感器位置特征值（Sensor Location）：这也是一个“读取”类型的特征值，告知客户端踏频传感器预设的安装位置（如“右曲柄”）。

我们的代码利用adafruit_ble_cycling_speed_and_cadence库，自动完成了对CSC测量特征值的订阅和数据结构解析，我们直接访问measurement_values属性就能拿到一个包含上述所有字段的对象，非常方便。

4. 代码逐行详解与实战操作

4.1 项目初始化与库导入

让我们打开核心的code.py文件，从开头看起。

import time from adafruit_clue import clue import adafruit_ble from adafruit_ble.advertising.standard import ProvideServicesAdvertisement from adafruit_ble.services.standard.device_info import DeviceInfoService from adafruit_ble_cycling_speed_and_cadence import CyclingSpeedAndCadenceService

• import time：用于在循环中添加延迟（time.sleep(0.1)），控制数据读取频率，避免程序跑飞和过度消耗CPU。
• from adafruit_clue import clue：导入CLUE库，我们将使用其中的clue.simple_text_display来快速创建文本显示界面。
• import adafruit_ble：导入BLE核心库，创建蓝牙无线电对象。
• ProvideServicesAdvertisement：这是一个用于过滤扫描结果的类。我们只关心那些在广播包中声明了自己提供某些服务的设备。
• DeviceInfoService：设备信息服务，用于在连接后读取传感器的制造商信息等。
• CyclingSpeedAndCadenceService：这是本项目的主角，用于识别和连接CSC传感器。

接下来初始化显示和蓝牙：

clue_data = clue.simple_text_display(title="Cycle Revs", title_scale=1, text_scale=3, num_lines=3) ble = adafruit_ble.BLERadio()

clue.simple_text_display创建了一个简单的文本显示对象，参数定义了标题、标题和正文的字体缩放，以及显示的行数（3行，我们用来显示车轮转数、曲柄转数，可能还有状态信息）。ble = adafruit_ble.BLERadio()实例化了蓝牙无线电对象，它是所有BLE操作（扫描、连接）的入口。

4.2 BLE扫描与连接流程

代码的主循环始于一个while True，这意味着如果连接断开，它会自动重新开始扫描。

while True: print("Scanning...") advs = {} for adv in ble.start_scan(ProvideServicesAdvertisement, timeout=5): if CyclingSpeedAndCadenceService in adv.services: print("found a CyclingSpeedAndCadenceService advertisement") advs[adv.address] = adv ble.stop_scan()

1. ble.start_scan(ProvideServicesAdvertisement, timeout=5)：开始扫描，持续5秒。ProvideServicesAdvertisement过滤器确保我们只接收那些广播了服务信息的设备，提高效率。
2. 遍历扫描到的每一个广播对象adv。检查CyclingSpeedAndCadenceService是否在adv.services列表中。如果在，说明这个设备是我们要找的自行车传感器。
3. 使用设备的MAC地址adv.address作为键，将广播对象存入advs字典。用地址作为键可以自动去重，避免同一个设备因多次广播而被重复记录。
4. 5秒后，ble.stop_scan()停止扫描。

实操心得：扫描超时时间timeout=5是个经验值。太短可能错过设备，太长会让用户等待过久。在实际产品中，你可能需要设计一个更智能的扫描策略，比如持续扫描直到找到设备，或者提供手动触发扫描的按钮。

扫描结束后，如果advs字典不为空，就开始连接：

cyc_connections = [] for adv in advs.values(): cyc_connections.append(ble.connect(adv)) print("Connected", len(cyc_connections))

这里用一个列表cyc_connections来保存所有的连接对象。代码遍历所有找到的传感器广播，并尝试连接。这里的设计支持连接多个传感器（例如独立的速感和踏频），adafruit_ble库会管理这些连接。

连接成功后，可以尝试读取设备信息（非必须，但有助于调试）：

for conn in cyc_connections: if conn.connected: if DeviceInfoService in conn: dis = conn[DeviceInfoService] try: manufacturer = dis.manufacturer except AttributeError: manufacturer = "(Manufacturer Not specified)" print("Device:", manufacturer)

这段代码检查连接是否有效，并尝试获取DeviceInfoService来打印制造商信息。注意这里用了try...except，因为并非所有设备都完整提供该服务。

4.3 数据订阅与显示循环

连接建立后，代码为每个连接获取其CSC服务对象，并进入一个内部循环，持续读取数据：

cyc_services = [] for conn in cyc_connections: cyc_services.append(conn[CyclingSpeedAndCadenceService])

conn[CyclingSpeedAndCadenceService]是一种便捷的语法，通过连接对象直接获取对应的服务实例。

核心的数据读取循环如下：

while True: still_connected = False wheel_revs = None crank_revs = None for conn, svc in zip(cyc_connections, cyc_services): if conn.connected: still_connected = True values = svc.measurement_values if values is not None: if values.cumulative_wheel_revolutions: wheel_revs = values.cumulative_wheel_revolutions if values.cumulative_crank_revolutions: crank_revs = values.cumulative_crank_revolutions if not still_connected: break if wheel_revs: clue_data[0].text = "Wheel: {0:d}".format(wheel_revs) clue_data.show() if crank_revs: clue_data[2].text = "Crank: {0:d}".format(crank_revs) clue_data.show() time.sleep(0.1)

1. svc.measurement_values：这是最关键的一行。它返回一个对象，包含了从传感器最新通知中解析出的所有数据。如果传感器还没有新数据，它可能是None。
2. 我们分别检查cumulative_wheel_revolutions和cumulative_crank_revolutions是否存在（不为None），并将其赋值给临时变量。这里的设计考虑了可能只有一个传感器（只有速度或只有踏频）的情况。
3. still_connected标志用于监控是否所有连接都已断开。如果全部断开，则跳出内部循环，回到外部的扫描循环。
4. 如果获取到转数值，就更新CLUE屏幕上对应的行。clue_data[0]和clue_data[2]对应初始化时定义的第1行和第3行文本。clue_data.show()用于将更改刷新到屏幕上。
5. time.sleep(0.1)让循环每秒运行大约10次，这个频率对于显示转数来说绰绰有余，且不会给处理器带来太大负担。

5. 硬件连接、部署与调试实录

5.1 传感器安装与供电

在给CLUE烧录代码之前，先处理好传感器。

1. 传感器安装：根据你的传感器类型（磁铁式或IMU式），参照说明书将其安装在自行车上。对于磁铁式，确保磁铁与传感器主体的间隙在2-5mm内，且车轮/曲柄旋转时能稳定触发。安装后，可以手动转动车轮或曲柄，观察传感器指示灯是否正常闪烁（表示在检测和发送信号）。
2. CLUE供电：CLUE可以通过Micro-USB接口供电，但为了便携性，更推荐使用电池。将2节AAA电池装入电池盒，用JST PH连接线接到CLUE的BAT端口。CLUE的功耗在屏幕常亮和BLE通信时相对较高，两节AAA碱性电池大约能提供数小时的续航。对于长时间骑行，建议使用大容量的锂电池组。

5.2 代码部署与首次运行

1. 按照前述“软件环境”部分，将项目包的所有文件（特别是code.py和lib文件夹）复制到CLUE的CIRCUITPY驱动器根目录。
2. 复制完成后，CLUE会自动重启并运行新的code.py。此时，屏幕会显示“Cycle Revs”标题，下方区域空白。
3. 打开一个串口终端（如Mu Editor的串口面板，或Putty、screen等工具），连接到CLUE的串口（如COMx或/dev/ttyACM0）。你将看到程序输出的调试信息。
4. 转动自行车的曲柄（对于踏频传感器）或车轮（对于速度传感器）。许多传感器有自动休眠功能，需要转动一下来“唤醒”它们并开始广播。
5. 观察串口终端和CLUE屏幕。终端会打印“Scanning...”，几秒后如果找到设备，会打印“found a...”和“Connected”。随后，当你转动车轮或曲柄时，终端和屏幕会开始更新显示累计转数。

5.3 常见问题与排查技巧

在实际操作中，你可能会遇到一些问题。下面是一个快速排查指南：

深度调试技巧：如果你想更深入地了解BLE通信过程，可以借助手机App如nRF Connect（由Nordic Semiconductor开发）。用它扫描并连接你的自行车传感器，你可以直观地看到设备广播的所有服务（Service）和特征值（Characteristic），甚至手动读取或订阅数据。这能帮你验证传感器本身是否工作正常，以及它提供的服务UUID是否与代码中寻找的（CyclingSpeedAndCadenceService）一致。这是一个极其强大的硬件调试工具。

6. 项目优化与扩展思路

现在，你已经成功读取并显示了原始转数。这个基础项目就像搭好了一个稳固的脚手架，接下来可以在上面建造更丰富的功能。

1. 计算并显示实时速度与踏频这是最直接的扩展。你需要知道车轮的周长（单位：米）。可以通过测量轮胎规格计算（如700x23C的周长约2.1米），或者更准确地，在地上滚一圈测量。 在代码中，你需要记录上一次的转数last_wheel_revs和事件时间last_wheel_time。当收到新数据时：

时间差 = (当前事件时间 - 上次事件时间) / 1024.0 （单位：秒） 转数差 = 当前累计转数 - 上次累计转数 瞬时速度（米/秒） = (转数差 * 车轮周长) / 时间差 瞬时速度（公里/小时） = 瞬时速度（米/秒） * 3.6

踏频的计算同理，使用曲柄转数和时间差。注意处理传感器刚启动或数据重置的情况（累计转数可能从0开始或回绕）。

2. 增加数据持久化与简单统计为CLUE添加一个SD卡模块，就可以将每次骑行的数据（时间戳、转数、计算出的速度/踏频）以CSV格式记录到文件中。后期可以导入到电脑用Excel或Python进行数据分析，计算平均速度、最大速度、骑行距离等。

3. 改善用户界面当前的简单文本显示可以升级为图形化界面。利用adafruit_display_shapes和adafruit_display_text库，你可以绘制模拟表盘、数字仪表、甚至实时曲线图。CLUE的屏幕虽然小，但足以展示关键信息。

4. 低功耗优化目前的代码循环time.sleep(0.1)，屏幕常亮，功耗较高。对于电池供电，可以优化：

• 屏幕控制：在无新数据更新一段时间后，调低屏幕亮度或关闭屏幕，通过按键或传感器信号唤醒。
• BLE连接参数：在连接稳定后，可以尝试协商更长的连接间隔（Connection Interval），让无线电模块更多时间休眠。这需要在BLE连接参数上进行更底层的设置。
• 处理器休眠：在等待数据的间隙，让MCU进入轻睡眠模式。

5. 多传感器融合与告警CLUE板本身还集成了加速度计、陀螺仪、气压计等传感器。你可以融合这些数据，实现更多功能：

• 自动暂停/继续：通过加速度计判断自行车是否处于静止状态，自动暂停计时和速度计算。
• 坡度估算：结合速度变化和气压实测海拔变化，粗略估算当前坡度。
• 摔车检测与告警：通过陀螺仪和加速度计数据突变，检测可能的摔车事件，并触发声光告警（CLUE有蜂鸣器）或记录事件点。

这个项目的真正价值在于，它为你打开了一扇门，让你能够基于真实的物理信号，通过标准的无线协议，构建一个完全受你控制的智能设备。从读取几个数字开始，到构建一个功能丰富的个性化骑行电脑，中间的所有步骤，都充满了学习和创造的乐趣。