M2: USB-Tastatur-Handling - evdev-Integration, Scancode-Mapping, Tests, systemd-Service, Dokumentation

This commit is contained in:
2026-07-14 14:26:02 +02:00
parent d70db2ed36
commit cbcf58f48b
8 changed files with 334 additions and 11 deletions
+5 -5
View File
@@ -18,11 +18,11 @@
- [x] Repository auf git.jlserver.de erstellt und initialer Push durchgeführt - [x] Repository auf git.jlserver.de erstellt und initialer Push durchgeführt
- [x] `go.mod` initialisiert - [x] `go.mod` initialisiert
### ⏳ M2: Backend – USB-Tastatur-Handling ### ✅ M2: Backend – USB-Tastatur-Handling
- [ ] Tastatureingaben im Hintergrund auslesen - [x] Tastatureingaben im Hintergrund auslesbar
- [ ] Diagnostik und Log-Ausgabe über stdout - [x] Diagnostik und Log-Ausgabe über stderr
- [ ] Systemd-Service-Beispieldatei - [x] Systemd-Service-Beispieldatei
- [ ] Dokumentation - [x] Dokumentation
### ⏳ M3: Backend – Logik ### ⏳ M3: Backend – Logik
- [ ] Zählerlogik implementiert - [ ] Zählerlogik implementiert
+63
View File
@@ -0,0 +1,63 @@
# USB-Tastatur-Handling
## Übersicht
Das `internal/usb` Paket liest Tastatureingaben direkt von Linux evdev-Geräten (`/dev/input/event*`).
## Tasten-Mapping
| Linux Scan Code | Taste | Aktion |
|-----------------|-------|--------|
| 1 | `/` | +1 Punkt Rot |
| 55 | `*` | +1 Punkt Grün |
| 78 | `+` | Nächste Runde |
| 12 | `-` | Reset (alle Runden löschen) |
## Nutzung
```go
import "git.jlserver.de/goSportpunktetafel/internal/usb"
// Erste verfügbare Tastatur öffnen
kb, err := usb.OpenFirstKeyboard()
if err != nil {
log.Fatal(err)
}
defer kb.Close()
// Tastatureingabe lesen
key, err := kb.ReadKey()
if err != nil {
log.Fatal(err)
}
// Scan Code zu Aktion mappen
action, ok := usb.ScanToAction(key.Code)
if !ok {
continue // Unbekannte Taste
}
```
## Gerät finden
```go
devices, err := usb.ScanForDevices()
if err != nil {
log.Fatal(err)
}
for _, dev := range devices {
fmt.Printf("Keyboard: %s (%s)\n", dev.Name, dev.Fn)
}
```
## systemd-Service
Der Service erwartet einen User `sportscore`:
```bash
sudo useradd -r -s /usr/bin/false sportscore
sudo cp systemd/sportscore.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sportscore
```
Der Binary muss unter `/usr/local/bin/sportscore` installiert sein.
+1 -6
View File
@@ -2,9 +2,4 @@ module git.jlserver.de/goSportpunktetafel
go 1.19 go 1.19
require ( require github.com/gvalkov/golang-evdev v0.0.0-20220815104727-7e27d6ce89b6
github.com/coreos/go-iptables v0.6.0
github.com/mdns/go-mdns v1.0.0
github.com/songgao/water v0.0.0-20200317213611-81d98817612a
golang.org/x/crypto v0.14.0
)
+2
View File
@@ -0,0 +1,2 @@
github.com/gvalkov/golang-evdev v0.0.0-20220815104727-7e27d6ce89b6 h1:K9b8efT9f1NkITNgNAm2A1LuoamhG4pAhXVjz5Sfa5Q=
github.com/gvalkov/golang-evdev v0.0.0-20220815104727-7e27d6ce89b6/go.mod h1:SAzVFKCRezozJTGavF3GX8MBUruETCqzivVLYiywouA=
+55
View File
@@ -0,0 +1,55 @@
package usb
// Linux input event codes for the keys we care about.
const (
KEY_SLASH = 1 // '/' key
KEY_ASTERISK = 55 // '*' key
KEY_PLUS = 78 // '+' key
KEY_MINUS = 12 // '-' key
)
// KeyToChar maps a Linux scancode to its character/action.
// Returns the character and whether it's a valid input key.
func KeyToChar(code uint16, eventType string) (string, bool) {
if eventType == "release" {
return "", false
}
switch code {
case KEY_SLASH:
return "/", true
case KEY_ASTERISK:
return "*", true
case KEY_PLUS:
return "+", true
case KEY_MINUS:
return "-", true
}
return "", false
}
// ScanToAction maps a Linux scancode to a logical action.
type Action string
const (
ActionScoreRed Action = "red"
ActionScoreGreen Action = "green"
ActionNextRound Action = "next"
ActionReset Action = "reset"
)
// ScanToAction returns the logical action for a given scancode.
func ScanToAction(code uint16) (Action, bool) {
switch code {
case KEY_SLASH:
return ActionScoreRed, true
case KEY_ASTERISK:
return ActionScoreGreen, true
case KEY_PLUS:
return ActionNextRound, true
case KEY_MINUS:
return ActionReset, true
}
return "", false
}
+61
View File
@@ -0,0 +1,61 @@
package usb
import "testing"
func TestKeyToChar(t *testing.T) {
tests := []struct {
name string
code uint16
eventType string
want string
wantOK bool
}{
{"slash press", KEY_SLASH, "press", "/", true},
{"slash release", KEY_SLASH, "release", "", false},
{"asterisk press", KEY_ASTERISK, "press", "*", true},
{"asterisk release", KEY_ASTERISK, "release", "", false},
{"plus press", KEY_PLUS, "press", "+", true},
{"minus press", KEY_MINUS, "press", "-", true},
{"unknown key", 42, "press", "", false},
{"unknown code release", 42, "release", "", false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, ok := KeyToChar(tt.code, tt.eventType)
if ok != tt.wantOK {
t.Errorf("KeyToChar() ok = %v, want %v", ok, tt.wantOK)
}
if got != tt.want {
t.Errorf("KeyToChar() = %q, want %q", got, tt.want)
}
})
}
}
func TestScanToAction(t *testing.T) {
tests := []struct {
name string
code uint16
want Action
wantOK bool
}{
{"slash -> red", KEY_SLASH, ActionScoreRed, true},
{"asterisk -> green", KEY_ASTERISK, ActionScoreGreen, true},
{"plus -> next", KEY_PLUS, ActionNextRound, true},
{"minus -> reset", KEY_MINUS, ActionReset, true},
{"unknown", 42, "", false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, ok := ScanToAction(tt.code)
if ok != tt.wantOK {
t.Errorf("ScanToAction() ok = %v, want %v", ok, tt.wantOK)
}
if got != tt.want {
t.Errorf("ScanToAction() = %v, want %v", got, tt.want)
}
})
}
}
+132
View File
@@ -0,0 +1,132 @@
// Package usb provides keyboard input handling via Linux evdev devices.
package usb
import (
"fmt"
"os"
"github.com/gvalkov/golang-evdev"
)
// Key represents a keyboard key event.
type Key struct {
Code uint16 // Linux input event code
Type string // "press", "release"
}
// Keyboard represents an input device (keyboard).
type Keyboard struct {
device *evdev.InputDevice
}
// ScanForDevices finds all keyboard devices in /dev/input/.
func ScanForDevices() ([]*evdev.InputDevice, error) {
keyboards := make([]*evdev.InputDevice, 0)
devices, err := evdev.ListInputDevices("event*")
if err != nil {
return nil, fmt.Errorf("failed to list input devices: %w", err)
}
for _, dev := range devices {
// Use CapabilitiesFlat which maps int event type to []int codes
if dev.CapabilitiesFlat == nil {
continue
}
keyCaps, ok := dev.CapabilitiesFlat[1] // EV_KEY = 1
if !ok || len(keyCaps) == 0 {
continue
}
// Filter: only consider devices with standard keyboard keys
hasSlash := false
for _, code := range keyCaps {
if code == 1 { // KEY_SLASH
hasSlash = true
break
}
}
if hasSlash {
keyboards = append(keyboards, dev)
}
}
return keyboards, nil
}
// OpenKeyboard opens a keyboard device at the given path.
func OpenKeyboard(devicePath string) (*Keyboard, error) {
dev, err := evdev.Open(devicePath)
if err != nil {
return nil, fmt.Errorf("failed to open %s: %w", devicePath, err)
}
return &Keyboard{
device: dev,
}, nil
}
// OpenFirstKeyboard opens the first available keyboard device.
func OpenFirstKeyboard() (*Keyboard, error) {
keyboards, err := ScanForDevices()
if err != nil {
return nil, err
}
if len(keyboards) == 0 {
return nil, fmt.Errorf("no keyboard devices found in /dev/input/")
}
dev, err := evdev.Open(keyboards[0].Fn)
if err != nil {
return nil, fmt.Errorf("failed to open first keyboard %s: %w", keyboards[0].Fn, err)
}
fmt.Fprintf(os.Stderr, "[usb] Using keyboard: %s (%s)\n", dev.Name, dev.Fn)
return &Keyboard{
device: dev,
}, nil
}
// Close releases the keyboard device.
func (kb *Keyboard) Close() error {
if kb.device != nil {
return kb.device.File.Close()
}
return nil
}
// ReadKey reads the next key event from the keyboard.
// Returns a Key struct or an error.
func (kb *Keyboard) ReadKey() (*Key, error) {
event, err := kb.device.ReadOne()
if err != nil {
return nil, fmt.Errorf("failed to read event: %w", err)
}
if event.Type != 1 { // EV_KEY
// Not a key event, try to read again
return kb.ReadKey()
}
key := &Key{
Code: event.Code,
Type: "press",
}
if event.Value == 0 {
key.Type = "release"
}
return key, nil
}
// GetDeviceInfo returns information about the connected keyboard.
func (kb *Keyboard) GetDeviceInfo() string {
if kb.device == nil {
return "no device"
}
return fmt.Sprintf("%s (%s)", kb.device.Name, kb.device.Fn)
}
+15
View File
@@ -0,0 +1,15 @@
[Unit]
Description=Sport Punktetafel - USB Tastatur Service
After=network.target
Wants=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/sportscore --usb
Restart=on-failure
RestartSec=5
User=sportscore
Group=sportscore
[Install]
WantedBy=multi-user.target