barcode-server

一个简单的守护进程，用于从USB条形码扫描仪读取条形码，并通过HTTP调用、websocket API或MQTT将它们暴露给其他服务。

功能

• 动态检测条形码扫描仪设备
• 通过REST API请求服务器信息
• 使用以下方式订阅条形码事件
  • Websocket API
• 使用以下方式推送条形码事件
  • HTTP请求
  • MQTT消息
• 通过Prometheus导出器获取统计信息

如何使用

设备访问权限

确保运行此应用程序的用户属于正确的小组，以便访问输入设备（通常为input），如下所示

sudo usermod -a -G input myusername

配置

barcode-server 使用 container-app-conf 通过YAML或TOML文件以及ENV变量提供配置。请参阅有关其的文档。

配置文件将在以下位置（按此顺序）搜索：

• ./
• ~/.config/
• ~/

查看此仓库中的示例 barcode_server.yaml。

本地

# create venv
python -m venv ./venv
# enter venv
source ./venv/bin/activate
# install barcode-server
pip install barcode-server
# exit venv
deactivate

# print help
./venv/bin/barcode-server -h

这将为您提供所有可用命令的概述

> ./venv/bin/barcode-server -h
Usage: barcode-server [OPTIONS] COMMAND [ARGS]...

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  config  Print the current configuration of barcode-server
  run     Run the barcode-server

Docker

默认情况下，将使用 run 命令启动 docker 镜像，这使得生产部署更加容易。启动 docker 容器时，请确保传递输入设备和配置文件

docker run -it --rm \
  --name barcode \
  --device=/dev/input \
  -v "/home/markus/.config/barcode_server.yaml:/app/barcode_server.yaml" \
  -e PUID=0 \
  -e PGID=0 \
  markusressel/barcode-server

注意：尽管 barcode-server 会不断尝试检测新设备，即使像上面那样传递 /dev/input，但由于 docker 的工作方式，新设备可能无法检测到。如果您需要实时检测设备，则必须使用本地方法。

可以在容器内使用 PUID 和 PGID 环境变量来指定应使用的用户和组 ID。

要覆盖默认命令，只需直接指定命令参数即可

docker run -it --rm \
  ...
  markusressel/barcode-server --help

Web服务器

默认情况下，Web服务器将在端口 9654 上监听 127.0.0.1。

授权

在配置中指定时，需要 API 令牌来授权客户端，该令牌在连接时必须使用 X-Auth-Token 标头传递。由于条形码扫描器不依赖于任何持久性，因此令牌在配置文件中指定，并且在运行时无法更改。

REST API

barcode-server 提供了一个简单的 REST API 来获取一些基本信息。此 API 不能 用于检索条形码事件。要执行此操作，您必须使用以下描述中的一种方法。

Websocket API

除了 REST API，barcode-server 还在 / 处公开了一个 WebSocket，可用于获取实时条形码扫描事件。

要连接到它，您必须提供以下内容：

• 一个包含 UUID（v4）的 Client-ID 标头
• (可选) 一个空的 Drop-Event-Queue 标头，以忽略连接之间发生的事件
• (可选) 一个 X-Auth-Token 标头，以授权客户端

在此 WebSocket 上接收到的消息是具有以下格式的 JSON 格式字符串

{
  "id": "33cb5677-3d0b-4faf-9dc4-d19a8ee7d8a1",
  "serverId": "cash-register-1",
  "date": "2020-08-03T10:00:00+00:00",
  "device": {
    "name": "BARCODE SCANNER BARCODE SCANNER",
    "path": "/dev/input/event3",
    "vendorId": "ffff",
    "productId": "0035"
  },
  "barcode": "4250168519463"
}

要测试连接，您可以使用例如 websocat

> websocat - autoreconnect:ws://127.0.0.1:9654 --text --header "Client-ID:dc1f14fc-a7a6-4102-af60-2b6e0dcf744c" --header "Drop-Event-Queue:" --header "X-Auth-Token:EmUSqjXGfnQwn5wn6CpzJRZgoazMTRbMNgH7CXwkQG7Ph7stex"
{"date":"2020-12-20T19:35:04.769739","device":{"name":"BARCODE SCANNER BARCODE SCANNER","path":"/dev/input/event3","vendorId":65535,"productId":53},"barcode":"D-t38409355843o52230Lm54784"}
{"date":"2020-12-20T19:35:06.237408","device":{"name":"BARCODE SCANNER BARCODE SCANNER","path":"/dev/input/event3","vendorId":65535,"productId":53},"barcode":"4250168519463"}

HTTP 请求

当配置时，您可以让 barcode-scanner 在扫描条形码时发出 HTTP 请求（默认为 POST），这提供了将条形码事件推送到不了解任何客户端的服务器的功能。请求的主体将包含与 WebSocket API 示例中相同的 JSON。

为此，只需将以下部分添加到您的配置中

barcode_server:
  [ ... ]
  http:
    url: "https://my.domain.com/barcode"

查看 示例配置 了解更多选项。

MQTT 发布

当配置时，您可以让 barcode-scanner 将条形码事件发布到 MQTT 代理。消息的有效负载将包含与 WebSocket API 示例中相同的 JSON。

为此，只需将以下部分添加到您的配置中

barcode_server:
  [ ... ]
  mqtt:
    host: "my.mqtt.broker"

查看 示例配置 了解更多选项。

统计信息

barcode-server 提供了一个 Prometheus 导出器（默认端口 8000），以提供一些统计见解。以下是一些（大多数）可用指标的简要概述

常见问题解答

我可以将条形码扫描器锁定到这个应用吗？

是的。大多数条形码扫描器通常像键盘一样工作，导致它们的输入被系统评估，这可能会使您的TTY或其他打开的程序变得杂乱。 barcode-server 将尝试 抓取 输入设备，使其成为这些设备所有传入输入事件的唯一接收者，这应该可以防止设备使您的TTY杂乱。

如果出于某种原因，这不适合您，请尝试以下方法

创建一个文件 /etc/udev/rules.d/10-barcode.rules

SUBSYSTEM=="input", ACTION=="add", ATTRS{idVendor}=="xxxx", ATTRS{idProduct}=="yyyy", RUN+="/bin/sh -c 'echo remove > /sys$env{DEVPATH}/uevent'"
SUBSYSTEM=="input", ACTION=="add", ATTRS{idVendor}=="xxxx", ATTRS{idProduct}=="yyyy", DEVPATH=="*:1.0/*", KERNEL=="event*", RUN+="/bin/sh -c 'ln -sf /dev/input/$kernel /dev/input/barcode_scanner'"

将 idVendor 和 idProduct 的值替换为您条形码扫描器的值（一个带前导零的4位十六进制值）。您可以在 barcode-reader 的日志输出中找到它们，或者使用连接到计算机的无线接收器执行 lsusb。

使用以下命令重新加载 udev 规则

udevadm control --reload

然后移除并重新插入无线接收器。现在您应该在 /dev/input/barcode_scanner 中有一个符号链接

ls -lha /dev/input/barcode_scanner

它可以在 barcode-server 配置的 device_paths 部分中使用。

来源：此 和 此

贡献

GitHub 是一个社交编码平台：如果您想编写代码，我鼓励您通过从该存储库的分支发送拉取请求来做出贡献。为错误和新功能创建 GitHub 问题跟踪，并就您感兴趣的问题发表评论。

许可证

barcode-server is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://gnu.ac.cn/licenses/>.