{"id":16526093,"url":"https://github.com/markusressel/barcode-server","last_synced_at":"2025-04-05T16:04:46.386Z","repository":{"id":38237918,"uuid":"304391193","full_name":"markusressel/barcode-server","owner":"markusressel","description":"A simple daemon to expose USB Barcode Scanner data to other services using Websockets, Webhooks or MQTT.","archived":false,"fork":false,"pushed_at":"2024-10-23T20:08:30.000Z","size":1048,"stargazers_count":66,"open_issues_count":0,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-24T07:28:37.056Z","etag":null,"topics":["asyncio","barcode","barcode-events","barcode-reader","barcode-scanner","barcode-server","http","mqtt","mqtt-client","python","python3","qrcode","server","websocket","websocket-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markusressel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["markusressel"]}},"created_at":"2020-10-15T16:50:05.000Z","updated_at":"2024-10-23T20:08:33.000Z","dependencies_parsed_at":"2023-10-14T19:01:23.490Z","dependency_job_id":"82cc06d3-7f80-4299-a554-a537dbfec7ca","html_url":"https://github.com/markusressel/barcode-server","commit_stats":{"total_commits":239,"total_committers":4,"mean_commits":59.75,"dds":0.6276150627615062,"last_synced_commit":"7fc6f3e04b85790a92944052a61c2e746a73ce39"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2Fbarcode-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2Fbarcode-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2Fbarcode-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusressel%2Fbarcode-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusressel","download_url":"https://codeload.github.com/markusressel/barcode-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361615,"owners_count":20926642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","barcode","barcode-events","barcode-reader","barcode-scanner","barcode-server","http","mqtt","mqtt-client","python","python3","qrcode","server","websocket","websocket-api"],"created_at":"2024-10-11T17:26:01.425Z","updated_at":"2025-04-05T16:04:46.364Z","avatar_url":"https://github.com/markusressel.png","language":"Python","readme":"# barcode-server [![Code Climate](https://codeclimate.com/github/markusressel/barcode-server.svg)](https://codeclimate.com/github/markusressel/barcode-server)\n\nA simple daemon to read barcodes from USB Barcode Scanners\nand expose them to other service using HTTP calls, a websocket API or MQTT.\n\n[![asciicast](https://asciinema.org/a/366004.svg)](https://asciinema.org/a/366004)\n\n# Features\n\n* [x] Autodetect Barcode Scanner devices on the fly\n* [x] Request Server information via [REST API](#rest-api)\n* [x] Subscribe to barcode events using\n    * [x] [Websocket API](#websocket-api)\n* [x] Push barcode events using\n    * [x] [HTTP requests](#http-request)\n    * [x] [MQTT messages](#mqtt-publish)\n* [x] Get [statistics](#statistics) via Prometheus exporter\n\n# How to use\n\n## Device Access Permissions\n\nEnsure the user running this application is in the correct group for accessing\ninput devices (usually `input`), like this:\n\n```\nsudo usermod -a -G input myusername\n```\n\n## Configuration\n\n**barcode-server** uses [container-app-conf](https://github.com/markusressel/container-app-conf)\nto provide configuration via a YAML or TOML file as well as ENV variables. Have a look at the\n[documentation about it](https://github.com/markusressel/container-app-conf).\n\nThe config file is searched for in the following locations (in this order):\n\n* `./`\n* `~/.config/`\n* `~/`\n\nSee [barcode_server.yaml](/barcode_server.yaml) for an example in this repo.\n\n## Native\n\n```shell\n# create venv\npython -m venv ./venv\n# enter venv\nsource ./venv/bin/activate\n# install barcode-server\npip install barcode-server\n# exit venv\ndeactivate\n\n# print help\n./venv/bin/barcode-server -h\n```\n\nThis will give you an overview of all available commands:\n\n```shell\n\u003e ./venv/bin/barcode-server -h\nUsage: barcode-server [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --version   Show the version and exit.\n  -h, --help  Show this message and exit.\n\nCommands:\n  config  Print the current configuration of barcode-server\n  run     Run the barcode-server\n```\n\n## Docker\n\nThe docker image will by default be launched with the `run` command, making it easier\nfor production deployment. When starting the docker container, make sure to pass through\ninput devices as well as the configuration file:\n\n```shell\ndocker run -it --rm \\\n  --name barcode \\\n  --device=/dev/input \\\n  -v \"/home/markus/.config/barcode_server.yaml:/app/barcode_server.yaml\" \\\n  -e PUID=0 \\\n  -e PGID=0 \\\n  markusressel/barcode-server\n```\n\n**Note:** Although **barcode-server** will continuously try to detect new devices,\neven when passing through `/dev/input` like shown above, new devices can not be detected\ndue to the way docker works. If you need to detect devices in real-time, you have to use\nthe native approach.\n\nThe user and group id that should be used within the container can be specified using the\n`PUID` and `PGID` environment variables.\n\nTo override the default command, simply specify command arguments directly:\n\n```shell\ndocker run -it --rm \\\n  ...\n  markusressel/barcode-server --help\n```\n\n# Webserver\n\nBy default the webserver will listen to `127.0.0.1` on port `9654`.\n\n## Authorization\n\nWhen specified in the config, an API token is required to authorize clients, which must\nbe passed using a `X-Auth-Token` header when connecting. Since barcode-scanner doesn't rely on any\npersistence, the token is specified in the configuration file and can not be changed on runtime.\n\n## Rest API\n\n**barcode-server** provides a simple REST API to get some basic information.\nThis API can **not** be used to retrieve barcode events. To do that you have to use one of\nthe approaches described below.\n\n| Endpoint   | Description                               |\n|------------|-------------------------------------------|\n| `/devices` | A list of all currently detected devices. |\n\n## Websocket API\n\nIn addition to the REST API **barcode-server** also exposes a websocket at `/`, which can be used\nto get realtime barcode scan events.\n\nTo connect to it, you have to provide\n\n* a `Client-ID` header with a UUID (v4)\n* (optional) an empty `Drop-Event-Queue` header, to ignore events that happened between connections\n* (optional) an `X-Auth-Token` header, to authorize the client\n\nMessages received on this websocket are JSON formatted strings with the following format:\n\n```json\n{\n  \"id\": \"33cb5677-3d0b-4faf-9dc4-d19a8ee7d8a1\",\n  \"serverId\": \"cash-register-1\",\n  \"date\": \"2020-08-03T10:00:00+00:00\",\n  \"device\": {\n    \"name\": \"BARCODE SCANNER BARCODE SCANNER\",\n    \"path\": \"/dev/input/event3\",\n    \"vendorId\": \"ffff\",\n    \"productId\": \"0035\"\n  },\n  \"barcode\": \"4250168519463\"\n}\n```\n\nTo test the connection you can use f.ex. `websocat`:\n\n```\n\u003e 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\"\n{\"date\":\"2020-12-20T19:35:04.769739\",\"device\":{\"name\":\"BARCODE SCANNER BARCODE SCANNER\",\"path\":\"/dev/input/event3\",\"vendorId\":65535,\"productId\":53},\"barcode\":\"D-t38409355843o52230Lm54784\"}\n{\"date\":\"2020-12-20T19:35:06.237408\",\"device\":{\"name\":\"BARCODE SCANNER BARCODE SCANNER\",\"path\":\"/dev/input/event3\",\"vendorId\":65535,\"productId\":53},\"barcode\":\"4250168519463\"}\n```\n\n## HTTP Request\n\nWhen configured, you can let **barcode-scanner** issue a HTTP request (defaults to `POST`) when a\nbarcode is scanned, which provides the ability to push barcode events to a server that is unaware\nof any client. The body of the request will contain the same JSON as in the websocket API example.\n\nTo do this simply add the following section to your config:\n\n```yaml\nbarcode_server:\n  [ ... ]\n  http:\n    url: \"https://my.domain.com/barcode\"\n```\n\nHave a look at the [example config](barcode_server.yaml) for more options.\n\n## MQTT Publish\n\nWhen configured, you can let **barcode-scanner** publish barcode events to a MQTT broker.\nThe payload of the message will contain the same JSON as in the websocket API example.\n\nTo do this simply add the following section to your config:\n\n```yaml\nbarcode_server:\n  [ ... ]\n  mqtt:\n    host: \"my.mqtt.broker\"\n```\n\nHave a look at the [example config](barcode_server.yaml) for more options.\n\n## Statistics\n\n**barcode-server** exposes a prometheus exporter (defaults to port `8000`) to give some statistical insight.\nA brief overview of (most) available metrics:\n\n| Name                                | Type    | Description                                     |\n|-------------------------------------|---------|-------------------------------------------------|\n| websocket_client_count              | Gauge   | Number of currently connected websocket clients |\n| devices_count                       | Gauge   | Number of currently detected devices            |\n| scan_count                          | Gauge   | Number of times a scan has been detected        |\n| device_detection_processing_seconds | Summary | Time spent detecting devices                    |\n| rest_endpoint_processing_seconds    | Summary | Time spent in a rest command handler            |\n| notifier_processing_seconds         | Summary | Time spent in a notifier                        |\n\n# FAQ\n\n## Can I lock the Barcode Scanner to this application?\n\nYes. Most barcode readers normally work like a keyboard, resulting in their input being evaluated by\nthe system, which can clutter up your TTY or other open programs.\n**barcode-server** will try to _grab_ input devices, making it the sole recipient of all\nincoming input events from those devices, which should prevent the device from cluttering\nyour TTY.\n\nIf, for some reason, this does not work for you, try this:\n\nCreate a file `/etc/udev/rules.d/10-barcode.rules`:\n\n```\nSUBSYSTEM==\"input\", ACTION==\"add\", ATTRS{idVendor}==\"xxxx\", ATTRS{idProduct}==\"yyyy\", RUN+=\"/bin/sh -c 'echo remove \u003e /sys$env{DEVPATH}/uevent'\"\nSUBSYSTEM==\"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'\"\n```\n\nReplace the `idVendor` and `idProduct` values with the values of your barcode reader (a 4 digit hex value with leading\nzeros).\nYou can find them in the log output of **barcode-reader** or using `lsusb` with the wireless receiver attached to your\ncomputer.\n\nReload udev rules using:\n\n```\nudevadm control --reload\n```\n\nthen remove and reinsert the wireless receiver.\nYou should now have a symlink in `/dev/input/barcode_scanner`:\n\n```\nls -lha /dev/input/barcode_scanner\n```\n\nwhich can be used in the `device_paths` section of the **barcode-server** config.\n\nSource: [This](https://serverfault.com/questions/385260/bind-usb-keyboard-exclusively-to-specific-application/976557#976557)\nand [That](https://stackoverflow.com/questions/63478999/how-to-make-linux-ignore-a-keyboard-while-keeping-it-available-for-my-program-to/63531743#63531743)\n\n# Contributing\n\nGitHub is for social coding: if you want to write code, I encourage contributions\nthrough pull requests from forks of this repository. Create GitHub tickets for\nbugs and new features and comment on the ones that you are interested in.\n\n# License\n\n```text\nbarcode-server is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n","funding_links":["https://github.com/sponsors/markusressel"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusressel%2Fbarcode-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusressel%2Fbarcode-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusressel%2Fbarcode-server/lists"}