Output target protocols usage and configuration

Example use cases

• Real-time video augmentation: Synchronising low-latency visual overlays with moving objects.
• Interactive visitor tracking: Triggering location-based media or exhibits in venues such as museums.
• Access control systems: Managing automated entry gates and security zoning using positioning data.

Configuration requirements

• IP address: The destination IP address.
• Port: The communication port used by the destination application.

Technical considerations:

• Data size limitation: Large UDP messages will fail to transmit if the payload size exceeds the network Maximum Transmission Unit (MTU) limits or maximum UDP packet boundaries. This can occur when combining extensive message batching with highly detailed JSON formats.
• Unreliable transport: UDP is a connectionless protocol that does not guarantee delivery. Packets can be dropped on congested networks without triggering a retransmission.
• Security and encryption: The UDP stream is unencrypted. Quuppa does not support encryption for UDP output targets, including application-level encryption or Datagram Transport Layer Security (DTLS). This is a primary reason to use this protocol only within a local network.

Example use cases

MQTT is an industry-standard protocol for IoT integrations, suitable for various network conditions. This is the Quuppa-recommended integration method for most use cases across different sectors and industries.

• Manufacturing and Industry 4.0: Tracking components, vehicles, and work-in-progress (WIP) in real-time across complex assembly environments, such as automotive, aerospace or specialised vehicle production plants.
• Logistics and warehouse digitisation: Managing high-volume parcel sorting, yard operations, and maintaining active digital shadows of inventory.
• Cross-sector asset tracking and safety: Monitoring the real-time location of personnel and high-value equipment in diverse settings, including healthcare, smart buildings, heavy engineering facilities and deep underground mining operations.

Configuration requirements

• Hostname or IP address (required): Enter the hostname or IP address of your MQTT server.
• Communication port (required): Enter the communication port.
• Scheme (tcp, ssl, ws, or wss) (required): Select the communication Scheme (tcp, ssl, ws, or wss).
• Client ID (defaults to target name) (optional): Enter a Client ID for your MQTT publisher client. If left empty, the system uses the target name as the Client ID.
• Topic prefix (optional): Enter a Custom topic prefix to add custom levels before the predefined Quuppa topic structure.
• Retain flag (optional): Select the Retain last message to retain the last message sent.
• Username (optional): Enter the Username to authenticate the publisher client.
• Password for authentication (optional): Enter the Password to authenticate the publisher client.

Technical considerations

The Quuppa MQTT publisher organises telemetry data using a semi-predefined topic hierarchy based on the data stream type and configured trigger modes.

• Quality of Service (QoS) levels: The Quuppa MQTT publisher implementation transmits all messages using QoS 0. This setting is fixed and cannot be changed. Quuppa outputs high-volume, real-time transient data, does not cache or persist unsent messages, and does not manage subscribing endpoints. Higher QoS levels are unsupported, as they require message persistence and acknowledgement tracking. If the receiving end becomes unavailable, queued messages would be serialised to disk, which could potentially exhaust local system resources.
• Certificate management: For secure SSL or WSS connections, the Quuppa Positioning Engine (QPE) relies on the host operating system's trust store to verify the MQTT broker's identity. The Quuppa Site Planner (QSP) and Quuppa Positioning Engine (QPE) do not feature a graphical interface for certificate uploads. Mutual TLS (mTLS) authentication is supported exclusively in the Quuppa Enterprise edition.

• Tag data topics: For individual asset tag tracking, the Quuppa MQTT publisher uses a predefined topic structure in the following format: quuppa/apidata/<project-key>/<payload|location|taginfo>/<format-name>/<tag-id>. You can add a custom prefix to this topic structure.

  The <payload|location|taginfo> variable depends on the trigger mode configured in the target. The following specific configurations must be used: payload for interval trigger mode, location for location-related triggers, and taginfo for the lastSeenUpdate trigger.

• Positioning Engine (PE) format topics: For system-level positioning engine data, the predefined topic structure is: quuppa/apidata/<project-key>/<peInterval>/<format-name>. You can add a custom prefix to this topic structure.
• Locator format topics: For locator-level data, the predefined topic structure is: quuppa/apidata/<project-key>/<locatorInterval>/<format-name>. You can add a custom prefix to this topic structure.

Example use cases

• Sepioo/PDi digital display control: Allows sending digital display control messages (e.g., page change or update) directly to Sepioo Cloud based on location events.
• Telemetry data: Delivering low-frequency telemetry, such as Locator information and Quuppa Positioning Engine (QPE) information to external monitoring systems.
• Event-driven integration: Integrating with third-party applications and alerting systems, or other custom event-driven platforms.

System availability and UI restrictions

• Quuppa Site Planner (QSP) and API: You can configure the HTTP protocol for both Classic and Enterprise projects when you use the QSP application or the Quuppa API.
• Web console user interface: You can create or manage HTTP POST targets via the web browser interface for Enterprise (QSM) projects only. This option is not available in the Classic web user interface.

Technical considerations

• Infrequent use only: HTTP POST is a high-overhead transport protocol intended strictly for sending data infrequently. Do not use this protocol for continuous, high-throughput data transmission. An overloaded HTTP request stream can "clog" both the QPE and the receiving side, leading to system failures.
• Denial of Service (DoS) risk: If you configure a tag output target to send data on every position update, the system can generate hundreds or thousands of requests per second. This action can cause a DoS condition on the receiving application server. Use caution when using this method for sending tag data.
• Request frequency management: Message batching (for example, 1000 location events in a single message) or strict triggering and filtering rules should be applied to ensure manageable request frequency. For further details on configuring batching, filtering, and logic rules, see the Create Output Target for Location Update Event (The Logic Rules).
• Encryption and authentication: When using the secure HTTPS protocol, QPE is required to verify the identity of the receiving server. The server certificate must have a valid certification path to a root certificate authority (CA) in the Java Virtual Machine (JVM) trust store. If using a self-signed certificate, you must manually add the root CA to the trust store. You can include additional authentication details, such as basic authentication credentials or a bearer token, in the request headers or the request body.

Configuration requirements

• URL: Specify the endpoint URL for the data.
• Request headers: You can define submitted request headers as key-value pairs based on the requirements of the receiving application. The Quuppa system does not automatically determine or populate these parameters, but if left blank, the HTTP library will add certain headers automatically.
• Request body: The request body contains the actual data payload. The payload content is determined by the output format (for example, DefaultPEInfo) and format type (JSON, CSV or custom format type). The defined output format is written directly into the body of the HTTP POST request.

Create an HTTP POST output target

The target uses a custom peinfo output format, JSON format type, an interval trigger mode with a 10 s interval, and a maximum batch size of 1. The URL and request headers are defined as follows:

URL: https://example.server.com/quuppa/peinfo

Headers: “Content-Type”=”application/json; charset=utf-8”, “Cache-Control”=”no-cache, no-store”, “Authorization”=” Bearer 2054ee7c1833ea82ecdfcf12a3a3b9d9d38a43cefe2038a7d0e1191f983042a”

The HTTP POST target is created below via the createOutputTarget API. The same target could also be created in the Quuppa Site Planner.

http://localhost:8080/qpe/createOutputTarget?name=peinfo-http-post&format=peinfo&type=json&target=httppost&type=json&triggerMode=interval&interval=10&maxBatchSize=1&url=https%3A%2F%2Fexample.server.com%2Fp%2Fquuppa%2Fpeinfo&headers=%22Content-Type%22%3D%22application%2Fjson%3B%20charset%3Dutf-8%22%2C%20%22Cache-Control%22%3D%22no-cache%2C%20no-store%22%2C%20%22Authorization%22%3D%22Bearer%2054ee7c1833ea82ecdfcf12a3a3b9d9d38a43cefe2038a7d0e1191f983042a%22

After the target has been started, QPE will post data to the defined URL every 10 seconds.

Posts

Sent request headers

Sent request body

                {
                "qpeVersion": "9.6.0-8ee58047",
                "diskFree": 149590773760,
                "running": true,
                "mode": "Normal",
                "startTS": 1780556770390,
                "projectVersion": "261",
                "packetsPerSecond": 252.0,
                "udpRX": 0.4,
                "udpTX": 0,
                "dfPacketsPerSecond": 241.4,
                "dataPacketsPerSecond": 10.6,
                "tcpRX": 0,
                "tcpTX": 0,
                "qpeLossRate": 0,
                "networkLossRate": 0,
                "tagsOnline": 605,
                "tagIssues": null,
                "memoryAllocated": 1124073472,
                "memoryFree": 629145600,
                "memoryUsed": 494927872,
                "memoryMax": 12469665792,
                "portalClockDelta": 157,
                "systemTS": 1780557730686,
                "fileSyncStatus": "Ok",
                "fileSyncError": "",
                "networkInterfaceStatus": [
                {
                "status": "Up",
                "error": null,
                "ip": "192.168.10.1",
                "mask": "255.255.255.0"
                }
                ],
                "issues": [],
                "cpuLoad": 0.48,
                "warnings": [],
                }
            

Example use cases

• Process analysis and optimisation: Retaining long-term tracking telemetry to analyse and optimise industrial, logistics, or operational workflows.
• Retail store customer flow analysis: Accumulating historical location data to evaluate foot traffic patterns, dwell times, and shopper behaviour over extended periods.

Configuration requirements

• Folder: The local directory path where the data files will be stored.
• Filename prefix: The string prefixed to the beginning of all generated file names.
• Entries per file: Defines the maximum number of log entries written to a single file before the system closes it and creates a new one.
• Include header: A toggle to include a column header as the first line of the file. Although the output data can be written in both CSV and JSON format, the header is always written exclusively in CSV format.

Technical considerations

• Disk space management: The system features no automated storage management. The QPE writes data continuously while active; therefore, the user must monitor host storage levels and implement external retention or rotation mechanisms. Local disk space exhaustion will prevent data allocation and can cause the host operating system to terminate processes, resulting in a QPE crash and broader system instability.
• Data and header formatting: Output data payloads support both CSV and JSON format types. If the "Include header" option is enabled, the header block, which contains output format definitions, PE version numbers, and metadata, is written exclusively in CSV format, regardless of the payload configuration. Downstream automated parsing applications must be programmed to process this initial CSV line when consuming JSON file targets.