Skip to content

Voice Broadcast APP: Design Architecture ​

Updated: 11/10/26, 10:51:10 AM

This page explains where broadcast messages are published, which components they pass through, and how they become sound and receipts on the phone. For deployment steps see Deployment and Activation.

Components and Chain ​

RoleResponsibilityBoundary
Payment platformDecides the payment result, publishes broadcast messages, renders the receipt command streamMessages are published by device number, never broadcast
Artemis brokerAccepts MQTT over WebSocket connections, maps topics to core addressesThe device account can only subscribe, never publish
Voice Broadcast APPSubscribes, decrypts, announces, takes the receipt commands and prints, reports the ackNo local layout, never guesses the amount
PrinterOutputs the receipt from the ESC/POS command streamPaper width must match the APP setting

Message Channel Topics and Contract ​

Devices subscribe to a slash topic, while the platform publishes to a dot-separated multi-segment core address; the broker maps both to the same address (Artemis 2.33+ / ARTEMIS-4532):

DirectionValueNotes
Device subscription (delivered at activation)daxpay/device/audio/{deviceNo}The APP subscribes as-is; / is the MQTT hierarchy separator
Broker core addressdaxpay.device.audio.{deviceNo}The slash topic maps to a multi-segment address; ACL / address-setting match against it
Platform publish (JMS Topic)daxpay.device.audio.{deviceNo}Same address as the subscription queue, routed directly by the broker

The broker core prefix is daxpay.device.; both the ACL and the address policy match against this prefix.

Do not subscribe with a dot topic, and do not publish the escaped literal

Artemis 2.33+ handles topics per the official MQTT semantics: / is the hierarchy separator, while . is a literal character escaped as \.. If a device subscribes to the dot topic daxpay.device.audio.{deviceNo}, it actually lands on the single-segment address daxpay\.device\.audio\.{deviceNo}, does not match security-setting match="daxpay.device.#", and the subscription is rejected (SUBACK 0x80). If the platform publishes to the escaped literal, it is not the same address as the multi-segment queue created by the slash subscription, and messages are silently left with no receiver. The topic in the device credential is fixed at activation; after any topic contract change, existing devices must be activated again once.

Platform Renders the Receipt, the APP Is Only a Dumb Pipe ​

Receipts are not laid out on the phone. The platform renders the layout into an ESC/POS command stream and delivers it in the printData field, with both the 58mm and the 80mm stream provided together:

  • The APP picks the stream for the paper width set on the device, decodes and outputs it as-is, with no second layout pass;
  • Layout changes only touch the platform side; the APP does not need a matching upgrade;
  • The same applies to voice: the broadcast clips are built into the APP, so it does not depend on phone TTS and does not use mobile data.

The print channel supports classic Bluetooth SPP, USB and network printers (RAW TCP 9100). A print failure only affects the receipt; it does not affect the voice broadcast already played or the payment result.

Activation, Acknowledgement and Heartbeat ​

  1. The admin panel generates a device and binds it to a merchant; the merchant panel shows the activation QR code, whose content is daxpay:activate:{deviceNo} and carries only the device number;
  2. After scanning, the APP calls /client/device/audio/** to complete activation; the same endpoint family also carries the broadcast acknowledgement and reprint data fetch. The endpoints are anonymous but protected by HMAC signature verification and rate limits (10 requests per minute per IP, 20 requests per minute per device);
  3. The activation response delivers the MQTT access address, access account and subscription topic, and the APP uses them to establish the wss long connection;
  4. After a broadcast, the APP reports an ack and keeps a heartbeat every 5 minutes; the admin panel and the merchant panel show online status from it;
  5. After repeated decryption failures the APP trips a circuit breaker and guides the user to re-activate, instead of retrying on wrong credentials.

Device credentials are stored locally encrypted with Android Keystore AES-256-GCM; payment history is written to disk as monthly JSON for in-app queries. Re-activation rotates the secret, and the old device goes offline with it.

Design Constraints ​

  • Subscribe only, never publish: the access account has no publish permission on the message service, which prevents forged payment messages;
  • Server address injected at compile time: the APP offers no runtime address input; changing environments requires a new installer and re-activation, which keeps credentials from mixing across environments;
  • Topic fixed at activation: after a topic contract change, existing devices must be re-activated before they can use the new topic;
  • API orders muted by default: orders from the online API and EasyPay sources are not announced or printed; the feature targets manual cashier scenarios;
  • Source delivery: the source code is delivered as source with the Ecosystem Extension Pack (source-code license included).