🖨️ TSC-Print-Middleware

零驱动 TSC 打印机 USB 中间件 - 模板化打印 | RESTful API | 开箱即用

English | 简体中文

TSC-Print-Middleware 是一个零驱动 USB 打印中间件，专为 TSC 热敏标签打印机设计。基于 Python 和 FastAPI 构建，提供 RESTful API 实现模板化标签打印，支持文本、条形码和二维码。无需安装驱动程序，通过 USB 直接通信。适用于 Windows 平台的仓库管理、库存系统、物流自动化和资产标签打印场景。

核心技术: Python 3.10+ | FastAPI 0.120 | USB 通信 | TSPL 打印语言 | 模板引擎

✨ 特性

🚀 零驱动 - 无需安装打印机驱动，USB 直接通信
🎨 模板系统 - 5 种预设模板 + 完全自定义布局
🌐 RESTful API - FastAPI 提供标准 HTTP 接口
🇨🇳 完美中文支持 - Windows 宋体字库
📦 开箱即用 - pip install 一键安装
🔧 高度灵活 - 从简单到复杂，满足各种需求

📸 演示

预设模板效果

┌─────────────────────┐
│                     │
│    单行文本居中      │
│                     │
└─────────────────────┘

┌─────────────────────┐
│    第一行文本        │
├─────────────────────┤
│    第二行文本        │
└─────────────────────┘

┌─────────────────────┐
│    ████████████     │
│    ██ QR CODE ██    │
│    ████████████     │
│                     │
│      产品名称        │
└─────────────────────┘

🎯 应用场景

✅ 仓库物料标签打印
✅ 商品条码/二维码打印
✅ 快递单号打印
✅ 资产管理标签
✅ 库存盘点标签

🚀 快速开始

环境要求

操作系统: Windows 10/11
Python: 3.10 或更高版本
打印机: TSC 系列打印机（USB 连接）
系统依赖: VC2015-2022 x86 运行库

安装步骤

1. 克隆项目

git clone https://github.com/你的用户名/TSC-Print-Middleware.git
cd TSC-Print-Middleware

2. 创建虚拟环境

python -m venv venv
venv\Scripts\activate

3. 安装依赖

pip install -r requirements.txt

4. 启动服务

python main.py

服务将在 http://localhost:8000 启动

访问 http://localhost:8000/docs 查看交互式 API 文档 📖

📚 模板系统

TSC-Print-Middleware 提供 5 种打印模板，从简单到复杂，满足各种需求。

1️⃣ single-text - 单行文本

单行文本水平垂直居中

import requests

requests.post("http://localhost:8000/print", json={
    "template": "single-text",
    "print_list": [
        {"text": "物料编号: A12345"}
    ]
})

2️⃣ double-text - 双行文本

每张纸打印两行文本（上下布局）

requests.post("http://localhost:8000/print", json={
    "template": "double-text",
    "print_list": [
        {"text1": "第一行文本"},
        {"text2": "第二行文本"}
    ]
})

3️⃣ qrcode-with-text - 二维码+文本

二维码在上，文本在下，中心对齐

requests.post("http://localhost:8000/print", json={
    "template": "qrcode-with-text",
    "print_list": [
        {
            "qrcode": "https://example.com/product/12345",
            "text": "产品编号: 12345"
        }
    ]
})

4️⃣ barcode-with-text - 条形码+文本

条形码在上，文本在下，中心对齐

requests.post("http://localhost:8000/print", json={
    "template": "barcode-with-text",
    "print_list": [
        {
            "barcode": "1234567890",
            "text": "订单号: 1234567890"
        }
    ]
})

5️⃣ custom - 完全自定义布局

高级用户可以完全控制每个元素的位置和样式

requests.post("http://localhost:8000/print", json={
    "template": "custom",
    "layout": {
        "width": 100,
        "height": 80,
        "elements": [
            {
                "type": "text",
                "x": 100,
                "y": 100,
                "text": "自定义标题",
                "font_size": 56,
                "font_name": "宋体"
            },
            {
                "type": "qrcode",
                "x": 300,
                "y": 300,
                "content": "https://example.com",
                "size": 10
            },
            {
                "type": "barcode",
                "x": 100,
                "y": 600,
                "content": "123456789",
                "height": 80,
                "barcode_type": "128"
            }
        ]
    },
    "qty": 1
})

🔧 API 接口

基础接口

GET `/` - 服务信息

curl http://localhost:8000/

GET `/health` - 健康检查

curl http://localhost:8000/health

POST `/test` - 测试 USB 连接

curl -X POST http://localhost:8000/test

打印接口

POST `/print` - 统一打印接口

详细文档请查看 API.md

📖 配置说明

纸张配置

在 config.py 中修改默认纸张尺寸：

DEFAULT_WIDTH = "100"   # 标签宽度(mm) - 10cm
DEFAULT_HEIGHT = "80"   # 标签高度(mm) - 8cm

DPI 设置

根据你的打印机型号调整 DPI：

# TTE-344/345 (300 DPI)
DPI_RATIO = 11.81  # dots per mm

# TTP-244/247 (203 DPI)
# DPI_RATIO = 8.0

# TTP-644 (600 DPI)
# DPI_RATIO = 23.62

模板参数

修改预设模板的字体大小、间距等参数：

# single-text & double-text
TYPE1_FONT_HEIGHT = 56  # 字体高度
TYPE1_FONT_NAME = "宋体"

# qrcode-with-text & barcode-with-text
TYPE2_FONT_HEIGHT = 48
TYPE2_QR_SIZE = 12  # 二维码大小

🏗️ 架构设计

┌─────────────────┐      HTTP/JSON       ┌──────────────────────┐
│   前端应用       │ ─────────────────>  │  FastAPI Service     │
│  (任何语言)      │                      │   TSC-Print-MW       │
└─────────────────┘                      └──────────────────────┘
                                                   │
                                                   │ pythonnet
                                                   │ + tsclib
                                                   ▼
                                         ┌──────────────────────┐
                                         │   TSC Printer        │
                                         │   (USB Connection)   │
                                         └──────────────────────┘

核心技术栈:

FastAPI - Web 框架
pythonnet - Python 与 .NET 互操作
tsclib - TSC 打印机控制库

🛠️ 高级用法

批量打印

所有模板都支持批量打印：

# 批量打印10个二维码标签
requests.post("http://localhost:8000/print", json={
    "template": "qrcode-with-text",
    "print_list": [
        {"qrcode": f"https://example.com/{i}", "text": f"产品-{i}"}
        for i in range(1, 11)
    ]
})

坐标系统

原点: 左上角 (0, 0)
单位: dots（点）
转换公式: dots = mm × DPI_RATIO
示例: 100mm × 11.81 = 1181 dots (300 DPI)

自定义元素

文本元素

{
  "type": "text",
  "x": 100, // X坐标 (dots)
  "y": 100, // Y坐标 (dots)
  "text": "文本内容",
  "font_size": 48, // 字体大小 (12-120)
  "font_name": "宋体" // 字体名称
}

二维码元素

{
  "type": "qrcode",
  "x": 200, // X坐标
  "y": 200, // Y坐标
  "content": "二维码内容", // URL或文本
  "size": 10 // 单元宽度 (1-10)
}

条形码元素

{
  "type": "barcode",
  "x": 100, // X坐标
  "y": 400, // Y坐标
  "content": "123456789", // 条形码内容
  "height": 80, // 高度 (30-300)
  "barcode_type": "128" // 类型 (128, EAN13等)
}

📦 项目结构

TSC-Print-Middleware/
├── main.py              # FastAPI 应用入口
├── printer.py           # 打印机核心模块
├── config.py            # 配置文件
├── requirements.txt     # 依赖管理
├── test_print.py        # 测试脚本
├── README.md            # 项目说明
├── API.md               # API 文档
├── LICENSE              # MIT 许可证
├── CHANGELOG.md         # 变更日志
├── CONTRIBUTING.md      # 贡献指南
└── examples/            # 示例代码
    ├── python_client.py
    └── javascript_client.js

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

快速贡献步骤

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

❓ 常见问题

1. 找不到打印机

问题: 提示 "USB 打印机连接失败"

解决:

检查打印机是否通过 USB 连接到电脑
确认打印机电源已开启
检查 Windows 设备管理器中是否识别到打印机

2. 中文乱码

问题: 打印的中文显示为乱码或方块

解决:

确认 Windows 系统已安装宋体字库
检查 Python 环境编码为 UTF-8
在 config.py 中尝试其他中文字体（如"微软雅黑"）

3. 打印位置偏移

问题: 打印内容位置不准确

解决:

检查 DPI_RATIO 是否与你的打印机型号匹配
执行纸张校准：python -c "from printer import calibrate_paper; calibrate_paper()"
调整 config.py 中的 PRINT_MARGIN 参数

4. 依赖安装失败

问题: pip install -r requirements.txt 失败

解决:

确保已安装 VC2015-2022 x86 运行库
使用管理员权限运行命令提示符
尝试单独安装 pythonnet: pip install pythonnet==3.0.5

📝 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🙏 致谢

FastAPI - 现代化的 Web 框架
pythonnet - Python 与 .NET 互操作
TSC - TSC 打印机

📮 联系方式

问题反馈: GitHub Issues
功能建议: GitHub Discussions

⭐ 如果这个项目对你有帮助，请给个 Star！

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.cursor		.cursor
.github		.github
examples		examples
.gitignore		.gitignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
config.py		config.py
main.py		main.py
printer.py		printer.py
requirements.txt		requirements.txt
test_print.py		test_print.py

License

chenchen0501/TSC-Print-Middleware

Folders and files

Latest commit

History

Repository files navigation