hgc-laser

Python driver for HG-C series laser displacement sensors. HG-C 系列激光位移传感器的 Python 驱动库。

Protocol: Modbus RTU · RS-485 · 115200 8N1 · FC03 read · FC10 write

pip install hgc-laser

---

Quick start / 快速开始

from hgc_laser import LaserDevice, SerialConfig

# Discover available serial ports / 发现可用串口
ports = LaserDevice.list_ports()
print(ports)  # [{"port": "COM4", "description": "...", "hwid": "..."}, ...]

# Connect and read displacement / 连接并读取位移
cfg = SerialConfig(port="COM4", baudrate=115200, slave_id=1)
with LaserDevice(cfg) as dev:
    result = dev.measure()
    print(f"{result.displacement_mm:.3f} mm")

    dev.set_precision_mode("low_speed_high_precision")  # or "standard" / "high_speed"
    dev.laser_off()

From environment variables / 通过环境变量配置

export HGC_LASER_PORT=COM4
export HGC_LASER_BAUD=115200
export HGC_LASER_SLAVE_ID=1

from hgc_laser import LaserDevice

with LaserDevice.from_env() as dev:
    print(dev.measure().displacement_mm, "mm")

---

GUI / 图形界面

A Tkinter-based test GUI (gui.py) that mimics LaserPoint.exe is included in the repo root.
仓库根目录附带一个基于 Tkinter 的测试图形界面（gui.py），外观仿照 LaserPoint.exe。

# Install first / 先安装
pip install -e .

# Launch (auto-detects serial ports) / 启动（自动检测串口）
python gui.py

# Or specify port / 或指定串口
python gui.py --port COM4 --baud 115200 --slave 1

GUI features / 界面功能:

Feature / 功能	Description / 说明
Port / Baud / Slave ID	Auto-populated port list / 自动填充串口列表
Connect / Disconnect	Open/close serial connection / 打开/关闭串口
Live measurement	Large mm display + µm readout / 大字体毫米 + 微米显示
Strip chart	Scrolling real-time line chart (200 samples) / 滚动实时折线图
Read Once / Stream	Single shot or continuous ~10 Hz polling / 单次或连续约 10 Hz 采集
Laser ON/OFF	Toggle laser emission / 切换激光发射
Precision mode	3-mode selector / 三档精度选择
Change Address	Write new slave address + power-cycle prompt / 写入新从站地址并提示重新上电
Change Baud	Write new baud code + power-cycle prompt / 写入新波特率并提示重新上电
Log panel	Timestamped operation log / 带时间戳的操作日志

No extra GUI dependencies — uses only stdlib tkinter.
无额外图形界面依赖，仅使用标准库 tkinter。

---

API reference / API 参考

LaserDevice

Method / 方法	Description / 说明
LaserDevice.from_env()	Create from environment variables / 从环境变量创建
connect() / disconnect()	Open / close serial port (also context manager) / 打开/关闭串口（也支持上下文管理器）
measure() → MeasurementResult	Read current displacement / 读取当前位移
stream(interval_s, count)	Yield measurements continuously at given poll rate / 按指定频率持续输出测量值
is_laser_on() → bool	True = laser ON / True 表示激光已开启
laser_on() / laser_off()	Control laser emission / 控制激光发射
get_precision_mode() → str	Read precision / response-time mode / 读取精度/响应时间模式
set_precision_mode(mode)	Set precision mode / 设置精度模式
get_address() → int	Read sensor Modbus slave address / 读取传感器 Modbus 从站地址
set_address(new_address)	Change sensor slave address (power-cycle required) / 修改从站地址（需重新上电）
get_baud() → int	Read configured baud rate / 读取当前波特率
set_baud(baud)	Change sensor baud rate (power-cycle required) / 修改波特率（需重新上电）

Continuous output / 连续输出

with LaserDevice(SerialConfig(port="COM4")) as dev:
    # Stream 200 samples at 20 Hz
    # 以 20 Hz 采集 200 个样本
    for sample in dev.stream(interval_s=0.05, count=200):
        print(f"{sample.displacement_mm:.3f} mm")

    # Indefinite stream — break when done / 无限流，按需停止
    for sample in dev.stream(interval_s=0.1):
        process(sample)
        if done:
            break

Change address / 修改地址

with LaserDevice(SerialConfig(port="COM4", slave_id=1)) as dev:
    dev.set_address(5)   # writes FC10 to register 0x0001
    # Power-cycle sensor, then reconnect with slave_id=5
    # 重新上电后，以 slave_id=5 重新连接

Change baud rate / 修改波特率

with LaserDevice(SerialConfig(port="COM4", slave_id=1)) as dev:
    dev.set_baud(9600)   # supported: 9600 / 19200 / 38400 / 57600 / 115200
    # Power-cycle sensor, then reconnect at the new baud rate
    # 重新上电后，以新波特率重新连接

MeasurementResult

result.displacement_um    # int — displacement in micrometres (signed) / 位移（微米，有符号）
result.displacement_mm    # float — displacement in millimetres / 位移（毫米）

SerialConfig

SerialConfig(
    port="COM4",       # serial port / 串口号
    baudrate=115200,   # default 115200 / 默认 115200
    bytesize=8,        # default 8
    parity="N",        # N / E / O
    stopbits=1,        # default 1
    timeout=1.0,       # seconds / 秒
    slave_id=1,        # Modbus slave address (1-247) / Modbus 从站地址
)

Low-level client / 底层客户端 (HgcModbusClient)

For direct register access / 直接寄存器访问:

from hgc_laser import HgcModbusClient, SerialConfig

cfg = SerialConfig(port="COM4", slave_id=1)
with HgcModbusClient(cfg) as client:
    values = client.read_holding_registers(address=0x0000, quantity=2)
    client.write_holding_registers(address=0x0007, values=[0x0000])  # laser ON

    # Address and baud management / 地址与波特率管理
    client.write_address(5)       # change slave address / 修改从站地址
    client.write_baud_code(0)     # 0 = 9600 baud / 波特率代码 0 = 9600

---

Register map / 寄存器映射表 (HG-C series manual)

Register / 寄存器	R/W	Description / 说明	Values / 值
0x0000–0x0001	R	Displacement measurement / 位移测量	Signed int32 µm / 有符号 int32 微米
0x0001	R/W	Modbus slave address / Modbus 从站地址	1–247
0x0002	R/W	Baud rate code / 波特率代码	0=9600 … 4=115200
0x0005	R/W	Zero calibration offset / 零点校准偏移
0x0007	R/W	Laser state / 激光状态	0x0000=ON, 0x0001=OFF
0x0008	R/W	Precision / response time / 精度/响应时间	0=low_speed, 1=standard, 2=high_speed

---

Development / 开发

git clone https://github.com/DodgeHo/hgc-laser-python
cd hgc-laser-python
pip install -e ".[dev]"
pytest -v        # runs fully offline — no hardware required / 完全离线运行，无需硬件

---

License / 许可证

MIT — see LICENSE. See NOTICE.md for legal attribution notes.