# lamp_runtime

**Repository Path**: nicholas3388/lamp_runtime

## Basic Information

- **Project Name**: lamp_runtime
- **Description**: 四博智联智能台灯，开源代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Lamp

![](./assets/banner.jpg)

四博AI台灯是一个基于 [LeLamp](https://github.com/humancomputerlab/LeLamp) 台灯修改的开源项目。完善了视觉功能，修改了硬件方案中UVC摄像头和音频扩展板与WS2812的DMA资源共用带来的问题，接入了国产模型：GLM智普大模型。


* 其对中文的理解能力更好；
* 其次GLM部分版本模型完全免费使用，适合初学者入门学习；
* 第三是GLM带有ServerVAD功能，无需本地做唤醒词处理，降低客户端开发难度和硬件成本。

作为LeLamp的衍生版本，本项目修改了原代码在树莓派3B上的部分问题。



## 一、 概述

项目基于python编程，硬件资源包含以下部分:

- 五个STS3215串口总线舵机
- 音频扩展板 (含麦克风和单声道喇叭)
- WS2812灯板
- UVC摄像头模块
- 主控树莓派开发板（zero2w/3b/4b/5）
- DCDC降压模块
- 舵机控制板

<p align="center">
  <img src="./assets/product.png" alt="实物图">
</p>

台灯支持大模型在线实时对话+本地小模型推理，实现五轴联动的人类跟踪效果和手势识别、动作捕捉回放等功能。效果演示：

<div align="center">
  <a href="https://v.youku.com/v_show/id_XNjU1MTM2NzkxMg==.html?playMode=pugv&frommaciku=1">
    <img src="./assets/snapshot.png" width="400"/>
  </a>
</div>

## 二、 代码结构

```
ai_lamp/
├── lelamp_main.py         # 主程序入口
├── message_handler.py	   # 大模型消息处理
├── camera_stream.py	   # 摄像头实时视频推流
├── pyproject.toml         # 项目配置文件和安装依赖
├── lelamp/                # Core package
│   ├── setup_motors.py    # 电机管理和设置
│   ├── calibrate.py       # 电机校准
│   ├── list_recordings.py # 动作列表
│   ├── record.py          # 动作捕捉存储
│   ├── replay.py          # 动作回放
│   ├── follower/          # follower模式
│   ├── leader/            # Leader模式
│   └── test/              # 硬件功能单元测试
└── uv.lock                # uv文件
```

## 三、 硬件系统框图

<p align="center">
  <img src="./assets/system.png" alt="系统框图">
</p>

## 四、 软件运行环境设置

### 4.1 系统安装

#### 4.1.1 操作系统

##### 4.1.1.1 树莓派方案（model 3B/4B/5）

Windows环境下系统安装方式：

* 下载树莓派官方烧录软件pi imager

* 根据步骤下载烧录最新系统镜像（选择64bit系统镜像），带桌面版本或者Lite版本都可以。目前为止测试过的可用系统版本：Trixie/Bookworm

##### 4.1.1.2 瑞芯微RK3588方案（Radxa Rock5C）

* 下载瑞莎公司推荐的烧录软件： BalenaEtcher

* 烧录瑞莎公司提供的Debian系统镜像

#### 4.1.2 网络设置

树莓派中有多种接入网络的方法，可根据情况使用以下方式：

(1) 网线接入。这种方式仅适用于树莓派3b/4b/5等带网口的开发板，Zero2W仅提供WiFi接入。

(2) WiFi接入。通过WiFi入网，需要设置连接热点和密码。设置或修改热点有下面几种方法：

* 可以在使用imager软件烧录镜像时，在烧录步骤中根据提示设置好；

* 也可以烧录后，接入HDMI通过外接屏幕键盘，登录树莓派系统使用nmcli命令修改热点或者在具备图形界面的系统中进入系统设置修改热点；

* 还有一种方式是通过通过外接TTL转USB接入个人电脑，通过串口登录树莓派系统后使用nmcli命令修改热点

接入网络后才能使用大模型各种功能。

### 4.2 需要安装的工具包和SDK

#### 4.2.1 UV包管理工具

进入树莓派系统控制台，执行下列命令按照UV。

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

国内有可能无法自动下载安装，可以使用本仓库中tools目录下提供的安装包，根据下面方法手动安装UV。

```bash
cd /your_dir/lamp_runtime/tools
```

解压UV压缩包：

```bash
tar -xvf uv-aarch64-unknown-linux-gnu.tar
```

安装UV：

```bash
sudo install uv-aarch64-unknown-linux-gnu/uv /usr/local/bin/
```

测试UV：

```bash
uv --version #输出下面类似版本信息则说明uv可正常使用：uv 2025xxxxx
```

安装portaudio
```
sudo apt install portaudio19-dev -y
```


#### 4.2.2 下载GLM模型的python客户端SDK

从GLM代码仓库下载代码：

```bash
git clone https://github.com/MetaGLM/glm-realtime-sdk.git
```

#### 4.2.3 安装fswebcam

```bash
# 1. 更新软件源列表
sudo apt update
# 2. 安装 fswebcam
sudo apt install -y fswebcam
# 3. 验证安装（查看版本）
fswebcam --version
```

#### 4.2.4 树莓派3b/4b/5上关闭3.5mm耳机口音频输出

由于树莓派3b/4b/5的3.5mm音频输出口使用了pwm外设，与seeed 2mic扩展板上的音频芯片io冲突，所以需要禁用树莓派上的耳机口输出功能。

通过aplay -l命令查看，如果输出结果有Headphones这个设备，说明目前系统是启用了耳机口输出功能。输出信息如下：
```
**** List of PLAYBACK Hardware Devices ****
card 0: Headphones [bcm2835 Headphones], device 0: bcm2835 Headphones [bcm2835 Headphones]
  Subdevices: 8/8
  Subdevice #0: subdevice #0
  Subdevice #1: subdevice #1
  Subdevice #2: subdevice #2
  Subdevice #3: subdevice #3
  Subdevice #4: subdevice #4
  Subdevice #5: subdevice #5
  Subdevice #6: subdevice #6
  Subdevice #7: subdevice #7
card 1: vc4hdmi [vc4-hdmi], device 0: MAI PCM i2s-hifi-0 [MAI PCM i2s-hifi-0]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
```

打开系统配置文件
```bash
sudo nano /boot/firmware/config.txt
```

找到dtparam=audio=on这一行，并注释掉即可。
```
#dtparam=audio=on
```

注释后，按ctrl+o保存配置；然后ctrl+x退出nano编辑，然后可以重启树莓派

重启后，通过aplay -l命令查看是否还有Headphones这个设备，没有则说明关闭成功。

#### 4.2.5 打开SPI接口功能（RK3588方案无需执行本节操作）

该功能已不使用。使用ESP32模块控制外设。

台灯使用的ws2812灯带可以通过SPI/PWM等多种方式控制，推荐使用SPI方式

对于PI5，由于硬件更新，无法再使用原有的rpi_ws281x库对灯板进行控制。需要改用pi5neo。

在Pi5中，先删除rpi_ws281x: `uv pip uninstall rpi_ws281x`，再安装：`uv pip install pi5neo`，然后使用对应的rgb_service.py

##### 4.2.5.1 树莓派开启SPI
SPI方式控制时，需要先打开树莓派的SPI接口。通过下面命令进入图像界面设置
```
sudo raspi-config
```

上下方向键选择 Interface Options（接口选项），找到SPI相关选项，选择enable即可。通过下面命令确认spi设备是否打开
```
ls /dev/spi*
```

然后需要禁用/dev/spidev0.1节点，因为树莓派的主 SPI0 总线有两个片选（Chip Select）引脚：CE0 和 CE1。只需要一个片选，否则会导致灯光控制异常。
编辑/boot/firmware/config.txt文件。确保有下面两行：
```
dtparam=spi=on
dtoverlay=spi0-1cs
```
##### 4.2.5.2 设置SPI参数
对应16颗灯珠，需要较大的缓存，设置bufsiz大小

* 1. 编辑启动参数
sudo nano /boot/firmware/cmdline.txt
 在末尾(同一行!)加上空格 + spidev.bufsiz=32768

* 2. 编辑 config.txt
固定GPU时钟频率（树莓派4/5无需设置）
sudo nano /boot/firmware/config.txt
* 在文件末尾加上:
```
 core_freq=250
 core_freq_min=250
```

* 3. 重启系统
```
sudo reboot
```

#### 4.2.6 配置Seeed ReSpeaker 2-Mics Pi HAT （RK3588方案无需执行本节操作）
* 获取设备dts
```
curl https://raw.githubusercontent.com/Seeed-Studio/seeed-linux-dtoverlays/refs/heads/master/overlays/rpi/respeaker-2mic-v2_0-overlay.dts -o respeaker-2mic-v2_0-overlay.dts
dtc -I dts respeaker-2mic-v2_0-overlay.dts -o respeaker-2mic-v2_0-overlay.dtbo
sudo dtoverlay respeaker-2mic-v2_0-overlay.dtbo
sudo cp respeaker-2mic-v2_0-overlay.dtbo /boot/firmware/overlays
```
* 设置config.txt
```
sudo tee -a /boot/firmware/config.txt >/dev/null <<'EOF'
dtoverlay=respeaker-2mic-v2_0-overlay
dtoverlay=i2s-mmap
EOF
```

配置完上述步骤后，使用命令`aplay -l`应该能看到下面的音频设备信息：
```
card 2: seeed2micvoicec [seeed2micvoicec], device 0: 1f000a4000.i2s-tlv320aic3x-hifi tlv320aic3x-hifi-0 [1f000a4000.i2s-tlv320aic3x-hifi tlv320aic3x-hifi-0]
Subdevices: 1/1
Subdevice #0: subdevice #0
```

最后可以通过命令`alsamixer -c 2`设置音量大小以及开启录音（capture），默认音量line，以及capture是显示“MM”，即静音状态、非录音状态，需要打开到音量和capture录音功能。否则无声音或无法录音。上述命令中-c表示音频设备通道，需要对应你的系统中查询到的设备号。

### 4.3 GLM模型设置

#### 4.3.1 SDK安装

安装python版本SDK到lamp的虚拟环境中（先执行source .venv/bin/activate激活lelamp_runtime的虚拟环境）：

```bash
cd glm-realtime-sdk/python

uv pip install -e /home/pi/source/python/glm-realtime-sdk/python/glm_directory
```
上面的`/home/pi/source/python/glm-realtime-sdk/python/glm_directory`改成你的GLM python SDK所在目录


SDK的bug修改：
在glm_realtime_sdk中，找到models.py文件并打开，找到下面这一句：
```
model: Literal["whisper-1"]
```

并修改为：
```
model: Literal["whisper-1", "standard"]
```

安装zai-sdk
```
uv pip install zai-sdk
```

#### 4.3.2 修改模型配音风格

找到lelamp_main.py文件中下面代码，修改voice为其他风格即可，具体设置的字符内容，需要查询智普大模型SDK中支持的配音。
```
session_message = SessionUpdateMessage(
	session=SessionUpdateParams(
		instructions=agent_prompt,
		input_audio_format="wav",
		output_audio_format="pcm",
		voice="male-qn-daxuesheng",
		modalities={"audio", "text"},
		turn_detection=ServerVAD(),
		beta_fields={"chat_mode": "audio", "tts_source": "e2e", "auto_search": False, "greeting_config": {"enable": True, "content": "你好主人，我是你的智能台灯，你可以叫我小智"}},
		tools=[light_on_tool, light_off_tool, light_to_red, look_and_describe_tool, action_negitive, action_yes, action_look_up],
	)
)
```

#### 4.3.3 设置模型提示词

找到lelamp_main.py文件中`SessionUpdateMessage`的设置代码，将其输入参数session中的`instructions`字段设置为你的提示词即可

### 4.4 运行环境部署

#### 4.4.1 安装环境依赖工具

使用UV安装依赖库

```bash
# If on your personal computer
uv sync
```

树莓派中需要下面附加库，瑞芯微平台无需这些附件。

```
# If on Raspberry Pi
uv sync --extra hardware
```

#### 4.4.2 设置运行参数与大模型平台KEY

在主控系统中，下载的lamp_runtime仓库代码根目录下创建参数文件： .env

请根据你的系统中的目录结构修改下面命令路径

```
nano /home/radxa/source/lamp_runtime/.env
```

文件中添加智普平台的API_KEY：
```
LELAMP_MOTOR=1
LELAMP_AUDIO=1
ZHIPU_API_KEY="Your_Key"
LELAMP_RKNN_MODEL=/home/radxa/source/python/lamp_runtime/models/RetinaFace.rknn
```

其中LELAMP_MOTOR用于调试舵机，当设置LELAMP_MOTOR=0时，系统启动时不初始化舵机。类似的，当LELAMP_AUDIO=0时不初始化音频采集传输到大模型平台。

最后使能参数：

```
source /home/radxa/source/lamp_runtime/.env
```

### 4.5 ESP32模块

ESP32模块主要负责灯板、LED、毫米波雷达、麦克风阵列（用于声源定位，暂未加入该功能）等外设控制。

模块程序的编译与烧录请参考仓库：https://gitee.com/nicholas3388/lamp_esp32_module

程序烧录使用乐鑫官方烧录工具

### 4.6 瑞芯微方案启用通讯串口UART4

瑞芯微方案使用UART4串口与ESP32模块串口通讯，UART4默认没启用，需要启用后才能正常通信。

在rk3588主控的控制台执行命令进入系统设置界面：

`sudo rsetup`

选择Overlay设置，启用UART4-M2:

```
┌──────────────────────────────────┤ RSETUP ├──────────────────────────────────┐
│ Below are the overlays compatible with your hardware.                        │
│ Press Space to select.                                                       │
│                                                                              │
│    [ ] Enable UART2-M0                                                ▒      │
│    [*] Enable UART4-M2                                                ▒      │
│    [ ] Enable I2C1-M0                                                 ▒      │
│    [ ] Enable SPI3-M1                                                 ▒      │
│    [ ] Enable PCIe2x1l2                                               ▒      │
│    [ ] Enable PWM1-M1                                                 ▒      │
│    [ ] Radxa Camera 4K                                                ▒      │
│    [ ] Radxa Display 8 HD                                             ▒      │
│    [ ] Radxa Display 10 FHD                                           ▒      │
│    [ ] Disable LED                                                    ▒      │
│                                                                              │
│                      <Ok>                      <Cancel>                      │
└──────────────────────────────────────────────────────────────────────────────┘
```

设置Overlay之后需要重启系统才能生效，并正常使用UART4串口。

## 五、 整机调试

### 5.1 电源要求

使用的ST3215舵机是7.4v（19kg扭矩）供电，输入电压范围在5v~8.4v之间，建议输入电压与电机匹配，推荐7.5v的电源适配器。当所有硬件模块接入，使用WiFi连接时，电机转动时，功耗达到最大，可能达到2A以上，所以建议使用7.5v/5A规格的适配器。若电源功率达不到要求可能导致WiFi无法正常连接，或者电机转动不到位或动作执行延迟缓慢等现象。

如果使用的ST3215是12v（30kg扭矩）规格的，则对应更换12v/5A规格的电源适配器。

### 5.2 电机设置与校准

设备安装完成后，必须进行电机编号和校准后才能进行动作捕捉，否则执行的动作组将无法与录入动作一致。

#### 5.2.1 电机编号
在安装之前，需要先设置电机编号，因为编号设置需要将电机逐一接入驱动板连接树莓派进行设置。执行下面命令进行编号设置。
```
uv run -m lelamp.setup_motors --id your_lamp_name --port the_port_found_in_previous_step
```

编号设置过程中，将依次设置电机5~1，5号舵机对应最顶部连接灯头的舵机（wrist head）；1号舵机对应最底部的舵机（base yaw）


#### 5.2.2 Leader与follower

#### 5.2.3 零位校准


### 5.3 单元测试

#### 5.3.1 灯光测试

在工程根目录下，执行命令测试灯光：
```
sudo uv run -m lalamp.test.test_rgb
```

执行后依次亮红绿蓝灯。

#### 5.3.2 音频测试

执行命令：
```
uv run -m lelamp.test.test_audio
```

#### 5.3.3 摄像头测试

执行命令抓拍图片：
```
fswebcam --no-banner -r 1280x720 -S 5 output.jpg
```

照片保存在当前目录下

#### 5.3.4 电机测试

执行命令：
```
uv run -m lelamp.test.test_motors --id your_lamp_name --port port_your_servo_driver_is_connected_to
```

#### 5.3.5 大模型接入测试

### 5.4 主程序运行

设置开机启动

## 六、 功能扩展

* 代码兼容Lerobot机器人，只需更换灯光罩为机械手即可改造成Lerobot机械臂。

* 本地训练部署小模型，支持huggingface的预训练模型，实现特定场景的机械臂抓取功能。

* 摄像头视频流传输。

## 七、 更多即将更新的功能

### 7.1 动作优化

提供更拟人化的动作序列

### 7.2 机械结构优化

* 修改外观结构和关节连接，隐藏电机和线路，调整云台结构，使得结构更美观；

* 使用连杆结构或者蜗杆减速机加编码器的结构，减少抖动和噪音，结构更稳固耐用，实现工业级稳定性。

### 7.3 低成本方案

兼容使用性价比更高的电机和主控芯片方案，降低成本，提供商业落地

### 7.4 大算力版本，边缘计算实现离线AI

兼容性能更强的主板，实现大模型本地化部署推理，脱离网络支持离线运行，保证隐私和数据安全。

### 7.5 提供更多大模型和扩展功能的接入

如接入OpenClaw，OpenAI等……

### 7.6 声源定位功能

加入声源定位功能。

## 八、 常见问题

### 8.1 UV安装速度太慢

直接解压仓库中提供的UV压缩包并安装使用

### 8.2 使用replay命令回放动作组的执行速度很慢

### 8.3 pip命令找不到的问题

```bash
# 确保虚拟环境已激活
python -m ensurepip --upgrade
# 验证
pip3 --version
```

### 8.4 pyaudio问题

### 8.5 树莓派上使用ttl2usb的串口终端设置