English
Voice Broadcast APP: Deployment and Activation
Broadcast messages are pushed from the platform to the phone over a persistent MQTT over WebSocket (wss) connection. The pipeline must be in place first, otherwise a device can activate successfully and still receive nothing; nine out of ten "activated but no broadcast" problems sit in this step.
Ops Panel Deployment Path
Ops panel / one-click deployment users do this on the "Gateway Management → MQTT Access" page (full guide: Gateway Management - MQTT Access):
- One-click apply: on the "Artemis MQTT Access" status card, click "One-Click Apply"; the panel applies the access configuration and creates the access account (
app-device); - Bind the access domain: enter a bare domain (e.g.
mqtt.example.com); the phone access address iswss://followed by that domain, with no port or path to append. The HTTPS certificate is configured on the outer gateway / load balancer / CDN; - Note down the access credentials: the "Access Credentials" card on the page shows the password of
app-device, which can be revealed and copied; - Fill it in on the platform side: on the admin panel "System Management → System Configuration → Platform Configuration → MQTT Access", enter the access address (
wss://mqtt.example.com), account and password, then save.
Access domain and configuration propagation
The phone keeps a persistent long connection to the message service, and most CDNs support long connections poorly (short timeouts, or disconnects), which causes frequent drops and missed broadcasts. Point the access domain at the origin IP, or terminate HTTPS on an outer gateway / load balancer that supports WebSocket. The access address and account are delivered at device activation; after changing the configuration, already-activated devices must be re-activated before they switch.
Self-Hosted Artemis
Source deployments already depend on Artemis. Add the following configuration to the broker; the snippets match what the panel injects automatically.
Version requirement: broker 2.53+
- Floor 2.53: the platform JMS client is paired with 2.53, and the topic-mapping semantics below (≥ 2.33, ARTEMIS-4532) are already included — below 2.33 the platform publish and the device subscription land on different addresses, and messages are silently lost with no error anywhere
- Recommended image
apache/artemis:2.57.0-alpine, matching the panel deployment baseline; since 2.50 the image has been renamed fromapache/activemq-artemistoapache/artemis, and the old name is no longer updated - Self-hosting 2.39+ on bare metal requires JDK 17; the container image bundles the runtime, no impact
Topic contract (Artemis 2.33+ / ARTEMIS-4532): devices subscribe to the slash topic daxpay/device/audio/{deviceNo} (/ is the MQTT hierarchy separator), and the broker maps it to the core address daxpay.device.audio.{deviceNo}; the platform publishes to a JMS Topic on the same address, and the ACL and address-setting match against the dot-separated multi-segment address.
① Open the MQTT over WebSocket port: add port 61614 inside the <acceptors> section of broker.xml:
xml
<acceptor name="mqtt-ws">tcp://0.0.0.0:61614?protocols=MQTT</acceptor>② Device message address policy: add inside <address-settings>; device topics are cleaned up automatically once unused and messages expire quickly:
xml
<address-setting match="daxpay.device.#"><auto-delete-addresses>true</auto-delete-addresses><auto-delete-queues>true</auto-delete-queues><expiry-delay>600000</expiry-delay></address-setting>③ Device address permission matrix: add inside <security-settings>; the platform (amq) may publish, and the access account (app-device) may only subscribe:
xml
<security-setting match="daxpay.device.#"><permission type="send" roles="amq"/><permission type="createAddress" roles="amq"/><permission type="consume" roles="app-device"/><permission type="createNonDurableQueue" roles="app-device"/><permission type="createDurableQueue" roles="app-device"/><permission type="createAddress" roles="app-device"/></security-setting>Permissions must be listed in full
security-setting matches the most specific address and does not inherit the permissions of the default section. Without send / createAddress for amq, the platform cannot publish; without createAddress for app-device, a phone subscribing before the platform is rejected. Neither failure shows a clear reason in the logs. When a roles attribute lists several roles they must be comma-separated (e.g. amq,app-device); a space-separated list silently fails on older versions.
④ Narrow the core port: remove MQTT from the protocols of the 61616 acceptor (if present), so 61614 becomes the only MQTT entry; acceptors without a protocols declaration need no change. ⑤ Create the access account (run inside the Artemis instance directory):
bash
cd /var/lib/artemis-instance && ./bin/artemis user add --user '<admin-user>' --password '<admin-password>' --user-command-user 'app-device' --user-command-password '<custom-access-password>' --role 'app-device'⑥ Restart Artemis for the configuration to take effect. ⑦ Expose the wss entry: in production, terminate HTTPS with nginx or another reverse proxy and forward to 61614; confirm the main app can reach this broker, then fill the wss:// address and the app-device account and password into the admin panel "Platform Configuration → MQTT Access". For internal debugging a temporary ws:// works; use wss:// in production:
nginx
location / {
proxy_pass http://127.0.0.1:61614;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
proxy_read_timeout 180s; proxy_send_timeout 180s; proxy_buffering off;
}Always use slash topics
The panel pins apache/artemis:2.57.0-alpine; other 2.3x/2.5x versions such as 2.44 also subscribe with slash topics. The old practice of "widening the consume/create permissions of the catch-all # section for app-device" is no longer recommended: it only bypasses the ACL, does not fix the address mapping of dot subscriptions, and opens subscription access to every address for the device account. If a subscription keeps failing, first check whether the subscription topic is in slash form, and whether the backend has been upgraded and the device re-activated.
Generating and Binding Devices on the Admin Panel
Admin panel "Virtual Devices → Device Management" (under the payment system menu):
- "Generate Device" creates a virtual device; the device number is generated by the system (starts with
VD); - Use "Bind Merchant" on the device row to assign the device to a merchant and specify the owning app; a device without a bound merchant cannot be activated;
- To verify the chain, use the "Test Broadcast" / "Test Print" entries on the device row, and test print lets you choose the paper width; unbind or delete a merchant's devices before deleting the merchant, since deleting a merchant does not clean up its devices automatically.
Activation by QR Scan
- The merchant panel "Merchant Center → Device Management → Virtual Devices" lists the bound devices, and each device row offers the activation QR code entry; the owning app, store binding and enable/disable state can also be adjusted here;
- Install the Voice Broadcast APP (Android phone; the server address is built into the installer at compile time);
- Open the APP and scan the activation QR code; the content is
daxpay:activate:{deviceNo}and carries only the device number; if scanning is not possible, enter the device number by hand on the activation page; - After activation the APP connects to the message pipeline and listens in the background, and exceptions along the way are shown on the page. Make a small payment (or tap "Test Broadcast") to verify: the phone should announce immediately, and print with a printer connected.
Per-App Broadcast and Print Control
Broadcast and receipt printing are controlled at the payment app level: "App Management" on both panels has two independent switches, "Voice Broadcast" and "Receipt Printing", so you can announce without printing or print without announcing; "Receipt Layout" currently has one built-in option, "Standard receipt". The admin panel configures this in the device section of "Merchants & Apps → App Configuration", the merchant panel in "Merchants & Apps → App Management".
App Usage Notes
- Keep-alive settings: follow the in-app guide to disable battery optimization for this app and allow self-start and background pop-ups (vendor paths differ slightly). After the system kills the app, reopening it restores listening;
- Connecting a printer: classic Bluetooth (SPP), USB and network (same LAN, enter IP and port, RAW TCP 9100) — three ways, and the form has a "Test Connection" button; the paper width must match the paper actually used;
- Re-activate after an environment switch: after switching to an installer that points at another environment, the APP asks for re-activation, which is expected; scan again;
- New phone and unbinding: the device management page supports "Re-activate on a new phone / Unbind"; scanning again rotates the key and kicks the old device offline;
- Diagnostics: the "Diagnostics" drawer checks the payment chain, background running, and broadcast and printing item by item, and supports copying the self-check report.
For troubleshooting entry points see Broadcast and Receipt Troubleshooting.