ButtonTask v2

Configurable touch-screen button panel for embedded Linux (Qt5 + QML), with a companion Flask web configurator. Both share a single JSON config file.

Features

• Dynamic list of buttons (1..N), each fires HTTP GET/POST on tap
• Per-button trigger mode: press-and-hold (DelayButton-style, animated progress ring, configurable hold duration) or plain click — set in both editors
• Layout: grid (configurable column count) or list
• Configurable background: animated gradient, solid color or image
• Configurable feedback ring: color and width of the OK / error glow around buttons
• In-app settings dialog (tabbed pages): CRUD buttons, drag-and-drop reorder, layout/background/feedback/password, Ethernet configuration and update info
• Web configurator (Flask blueprints + tabbed UI + SortableJS): same operations remotely, plus icon upload, Ethernet configuration and OTA updates
• Main-screen tabs: buttons panel / BLE sensors table (MAC, battery, reading, RSSI)
• BLE GATT collector (collector/, bless + BlueZ): accepts sensor reports, 4-slot registry, advertising mirror; status shared via /opt/buttontask/run/
• Ethernet configuration via NetworkManager (nmcli) from the web UI
• OTA software update with automatic rollback on a failed launch (health-check)
• Hot reload: app picks up config changes via QFileSystemWatcher

Layout

ButtonTask/
  CMakeLists.txt        Qt5 build
  main.cpp
  src/                  C++ sources (ConfigManager, ButtonsModel, ButtonController,
                        SettingsContainer, SystemInfo, SensorsBridge)
  collector/            BLE GATT collector (bless/BlueZ peripheral, N=4 slots)
  qml/                  Main.qml, SensorsPage.qml, BackgroundLayer.qml, ButtonDelegate.qml, SettingsDialog.qml
    components/         BackHeader.qml, LabeledSlider.qml
    settings/          MainPage / ButtonsPage / LayoutPage / BackgroundPage /
                       FeedbackPage / NetworkInfoPage / UpdatePage / ButtonEditorDialog
  resources/            qml.qrc, icons.qrc
  config/config.json    default config (shipped next to the binary)
  webconfig/            Flask service (modular):
    app.py             application factory + /healthz
    config_store.py    load/save/defaults (in sync with C++ ensureDefaults)
    auth.py            login/logout/session
    api.py             buttons/layout/background/feedback/settings/icons
    network.py         Ethernet via nmcli
    updater.py         OTA upload + status
    paths.py           install layout helpers
    templates/ static/ *.service, requirements.txt
    scripts/           bt-netconfig, bt-update, bt-service, buttontask.sudoers,
                       make-package.sh

The Qt app reads the config from (in order of priority):

1. --config <path> command-line argument
2. BUTTONTASK_CONFIG environment variable
3. <applicationDir>/config/config.json (default)

The Flask service reads the same paths.

Building (embedded Linux, Qt5)

sudo apt install qtbase5-dev qtdeclarative5-dev \
                 qml-module-qtquick-controls2 qml-module-qtquick-layouts \
                 qml-module-qtgraphicaleffects qml-module-qtqml-models2 \
                 cmake build-essential

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
sudo make install

Binary lands in /usr/local/bin/ButtonTask. To run on a framebuffer/EGL device:

QT_QPA_PLATFORM=eglfs ButtonTask --config /opt/buttontask/config/config.json

Web configurator

cd webconfig
pip3 install -r requirements.txt
BUTTONTASK_CONFIG=../config/config.json python3 app.py

Open http://<device-ip>:8080. Login: admin + the password from settings.password.

Web port (settings.webPort): use 1024 or higher (default 8080). On Linux, ports 1–1023 are privileged: the web service runs as the unprivileged buttontask user and cannot bind to them unless the systemd unit grants CAP_NET_BIND_SERVICE (see webconfig/buttontask-web.service). Setting e.g. port 80 without that capability causes Permission denied and a restart loop.

Deployment with systemd (versioned layout)

The device uses an A/B-style versioned layout so OTA updates can roll back:

/opt/buttontask/
  versions/<ver>/   ButtonTask + webconfig/   (one dir per deployed version)
  current -> versions/<ver>                    (active version symlink)
  config/  icons/   shared, never replaced by an update
  run/              qt.alive heartbeat, update-status.json
  scripts/          bt-netconfig, bt-update, bt-service (root-owned)

First install:

sudo useradd -r -s /bin/false buttontask
sudo mkdir -p /opt/buttontask/{versions/2.0,config,icons,run,scripts}
sudo cp build/ButtonTask /opt/buttontask/versions/2.0/
sudo cp -r webconfig /opt/buttontask/versions/2.0/
sudo ln -sfn /opt/buttontask/versions/2.0 /opt/buttontask/current
sudo cp config/config.json /opt/buttontask/config/

# privileged helpers (root-owned) + sudoers whitelist
sudo install -m 0755 webconfig/scripts/bt-netconfig webconfig/scripts/bt-update \
                     webconfig/scripts/bt-service webconfig/scripts/bt-set-master \
                     webconfig/scripts/bt-settime webconfig/scripts/bt-reboot \
                     webconfig/scripts/bt-access webconfig/scripts/bt-brightness \
                     /opt/buttontask/scripts/
sudo /opt/buttontask/scripts/bt-set-master 'your-emergency-password'
sudo install -m 0440 webconfig/scripts/buttontask.sudoers /etc/sudoers.d/buttontask
sudo chmod 0440 /etc/sudoers.d/buttontask
sudo visudo -cf /etc/sudoers.d/buttontask

sudo chown -R buttontask:buttontask /opt/buttontask
sudo chown root:root /opt/buttontask/scripts/bt-*   # scripts must be root-owned

# Qt eglfs needs a writable runtime dir for the unprivileged user
sudo mkdir -p /tmp/runtime-buttontask
sudo chown buttontask:buttontask /tmp/runtime-buttontask
sudo chmod 0700 /tmp/runtime-buttontask

# eglfs grabs KMS/DRM directly; disable the desktop display manager
sudo systemctl disable display-manager
sudo systemctl stop display-manager

sudo cp webconfig/buttontask.service /etc/systemd/system/
sudo cp webconfig/buttontask-web.service /etc/systemd/system/
sudo cp webconfig/buttontask-collector.service /etc/systemd/system/
# BLE collector needs BlueZ + bless (see collector/requirements.txt / wheels/)
sudo usermod -aG bluetooth buttontask
# auto-restart bluetoothd after crashes (stock unit has no Restart=)
sudo install -D -m0644 webconfig/bluetooth.service.d/override.conf \
    /etc/systemd/system/bluetooth.service.d/override.conf
sudo systemctl daemon-reload
sudo systemctl enable --now bluetooth buttontask buttontask-web buttontask-collector

# verify sudoers (should succeed without a password prompt)
sudo -u buttontask sudo -n /opt/buttontask/scripts/bt-netconfig eth0 dhcp

Touchscreen (device-specific override)

The base buttontask.service does not hardcode a touch device path because the eventN number varies between boards. Copy the example override and set the correct event for your touchscreen:

# find the touchscreen event number
grep -l -E 'ABS_X|ABS_MT_POSITION' /sys/class/input/event*/device/capabilities/abs 2>/dev/null \
  | sed 's|.*/input/event||;s|/device.*||'

sudo mkdir -p /etc/systemd/system/buttontask.service.d
sudo cp /opt/buttontask/current/webconfig/buttontask.service.d/override.conf.example \
        /etc/systemd/system/buttontask.service.d/override.conf
# edit override.conf — replace event1 with the number found above
sudo systemctl daemon-reload && sudo systemctl restart buttontask

Migrating an already-deployed device

If the device was installed from an older guide, apply these fixes:

# 1. sudoers (fixes "sudo: a password is required" in web network config)
sudo install -m 0440 /opt/buttontask/current/webconfig/scripts/buttontask.sudoers \
                     /etc/sudoers.d/buttontask
sudo chmod 0440 /etc/sudoers.d/buttontask
sudo visudo -cf /etc/sudoers.d/buttontask

# 2. runtime dir
sudo mkdir -p /tmp/runtime-buttontask
sudo chown buttontask:buttontask /tmp/runtime-buttontask
sudo chmod 0700 /tmp/runtime-buttontask

# 3. display manager
sudo systemctl disable --now display-manager

# 4. updated unit + touch override (see above)
sudo cp /opt/buttontask/current/webconfig/buttontask.service /etc/systemd/system/
sudo systemctl daemon-reload

# 5. icons — until OTA with the path-resolution fix, set absolute iconsDir:
#    "iconsDir": "/opt/buttontask/icons" in /opt/buttontask/config/config.json

sudo systemctl restart buttontask-web buttontask

Troubleshooting

/usr/bin/env: 'bash\r': No such file or directory

Shell scripts were saved with Windows CRLF line endings. On the device, fix in place:

sudo sed -i 's/\r$//' /opt/buttontask/scripts/bt-*

Or re-copy the scripts from a repo checkout with LF endings (see .gitattributes).

sudo: a password is required (web → Сеть)

• sudo visudo -cf /etc/sudoers.d/buttontask must pass without errors
• web service must run as buttontask: systemctl show -p User buttontask-web
• helper scripts must be root-owned: ls -la /opt/buttontask/scripts/bt-*
• test manually: sudo -u buttontask sudo -n /opt/buttontask/scripts/bt-netconfig eth0 dhcp

QML Image: Cannot open: file:///./icons/...

• Icons are stored in /opt/buttontask/icons/ (shared, outside the version dir)
• Set "iconsDir": "/opt/buttontask/icons" in config, or deploy a build with the C++ path-resolution fix (relative ./icons is resolved against BUTTONTASK_ROOT, same as the web configurator)

Touch not working

• Check the override at /etc/systemd/system/buttontask.service.d/override.conf
• Re-detect the event number (see Touchscreen section above)
• Ensure the buttontask user is in supplementary groups video render input (set in buttontask.service)

Network configuration (Ethernet)

Open the web UI → tab Сеть. It reads the live state via nmcli and can apply DHCP or a static IP/prefix/gateway/DNS. The change is performed by the root helper bt-netconfig (whitelisted in sudoers); the unprivileged web service never touches the network directly. The same settings can also be applied from the device itself via the in-app Сеть page (it calls the same bt-netconfig helper through sudo, so the Qt UI must run as the buttontask user covered by the sudoers rule).

OTA software update

Build a package and upload it from the web UI → tab Обновление:

./webconfig/scripts/make-package.sh 2.1 build dist
# -> dist/buttontask-2.1.tar.gz  (+ sha256 to paste for integrity)

On upload, bt-update (detached, root) extracts the package into versions/<ver>, syncs webconfig/scripts/bt-* and sudoers into /opt/buttontask/scripts/ and /etc/sudoers.d/, flips the current symlink, restarts both services, then runs a health-check: the web /healthz must answer, the Qt UI heartbeat (run/qt.alive) must be fresh, and the buttontask unit must be active within BUTTONTASK_HEALTH_TIMEOUT (default 30s). If any check fails it automatically switches current back to the previous version and restarts. Progress is shown live and is also readable in the app's Обновление page.

Display / GUI watchdog

Targets "backlight on, no picture until power re-plug" (seen on PoE sites: a supply dip can reset the MIPI-DSI panel while the RK3566 keeps running). Three layers:

Layer	What hangs	Detection	Action
Hardware watchdog (system.conf.d/buttontask-watchdog.conf)	kernel / systemd	/dev/watchdog not pinged for 20 s	board reset
buttontask.service + SdWatchdog	Qt GUI / render thread / GPU	no frame swapped for 30 s (WATCHDOG=1 sent per real frame)	systemd kills + restarts the UI
buttontask-displaywatch (bt-displaywatch, root)	panel / DRM pipeline	kernel DRM/DSI timeouts; eth link down→up (PoE dip hint); UI restart storm; UI stuck stopping	panel re-init (stop UI → fb0/blank 4→0 → start UI); repeated → reboot (max 3/day)

Manual recovery on a dark screen: hold one finger for 10 s in the bottom-left corner (72×72 px; touch usually still works on a dark panel). The corner is shielded by an empty MouseArea, so a button under it never fires (and does not react to touches inside the corner). The panels in use are single-touch (1 slot), hence no multi-finger gesture. Same from a shell: sudo /opt/buttontask/scripts/bt-displaywatch recover.

Incident log: /var/log/buttontask/display-incidents.log (bt-displaywatch status), also in the journal of buttontask-displaywatch. At every boot it records whether the previous boot ended cleanly or abruptly (power cut / hang), plus the last display/link kernel events of that boot.

Tunables (env in a unit drop-in): DISPLAYWATCH_LINK_RECOVER=0 disables the re-init on link flap; DISPLAYWATCH_RECOVER_GAP, ..._RECOVER_MAX, ..._RESTART_MAX, ..._REBOOT_MAX — see the script header.

Delivered by OTA: bt-update installs the units and the watchdog config (sync_system); on devices whose OTA ran an older bt-update, the web service runs bt-update sync-system at start. A changed buttontask.service applies to the UI from its next restart (or reboot).

LCD brightness

Web UI → Система → «Яркость экрана», or the on-device settings menu. Uses /sys/class/backlight/ via the privileged helper bt-brightness (percent 0–100, stored in settings.brightness, restored when web/Qt start).

OTA packages sync bt-* helpers and sudoers via bt-update. On devices that still run an older bt-update (before helper sync), run once after the first OTA that includes this feature:

sudo install -m0755 /opt/buttontask/current/webconfig/scripts/bt-* \
                    /opt/buttontask/scripts/
sudo install -m0440 /opt/buttontask/current/webconfig/scripts/buttontask.sudoers \
                    /etc/sudoers.d/buttontask
sudo visudo -cf /etc/sudoers.d/buttontask
sudo -u buttontask sudo -n /opt/buttontask/scripts/bt-brightness status

JSON config schema

{
  "version": 2,
  "layout": {
    "mode": "grid",          // "grid" | "list"
    "columns": 2,            // grid only
    "spacing": 10,
    "showLabels": true
  },
  "background": {
    "type": "gradient",      // "gradient" | "solid" | "image"
    "color1": "#00007b",
    "color2": "#7b007b",
    "animated": true,
    "imagePath": ""          // filename inside iconsDir
  },
  "feedback": {
    "okColor": "#00cc44",    // ring/glow color on success
    "errorColor": "#cc2200", // ring/glow color on error
    "okWidth": 6,            // ring width (px) on success
    "errorWidth": 6,         // ring width (px) on error
    "glowRadius": 20         // glow radius (0 disables the glow)
  },
  "settings": {
    "darkMode": true,
    "password": "admin",     // shared with web auth
    "kioskMode": false,
    "iconsDir": "/opt/buttontask/icons",   // dir for user icons & background images
    "webPort": 8080          // use >= 1024 (1–1023 need root / CAP_NET_BIND_SERVICE)
  },
  "buttons": [
    {
      "id": "uuid",
      "label": "Кнопка",
      "iconPath": "cleaner1.png",  // relative to iconsDir, or absolute
      "action": {
        "type": "http_get",         // "http_get" | "http_post"
        "url": "http://server/btn",
        "headers": {},              // e.g. {"Authorization": "Bearer <token>"}
        "body": "",
        "timeoutMs": 7000,          // optional request timeout (default 7000)
        "acceptAnyResponse": false  // optional: true = any HTTP reply is success
      },
      "feedback": {
        "successText": "Отправлено",
        "errorText": "Ошибка",
        "fadeMs": 5000
      },
      "trigger": {
        "mode": "hold",          // "hold" (press-and-hold) | "click"
        "holdMs": 800            // hold duration in ms before it fires
      }
    }
  ]
}

Notes

• Both Qt and Flask write the config atomically (QSaveFile / os.replace).
• Qt watches the file via QFileSystemWatcher and reloads automatically when the web configurator saves changes.
• Button success criteria: a request is green on a 1xx/2xx/3xx HTTP reply (redirects are followed) and red on 4xx/5xx or a transport failure (timeout / connection refused / DNS). Set action.acceptAnyResponse: true to treat any received HTTP reply as success (only timeouts/refused fail), and action.timeoutMs to tune the timeout. Add an API key/token via action.headers if the target endpoint requires one.
• Web configurator endpoints are all session-protected (@login_required after password login); only /healthz is public (it exposes just ok + version, used by the OTA rollback health-check).
• Default credentials are admin / admin — change on first run.
• v1 (Android/RS485/voice) was removed; only the icon set was kept.