Tuya Pulsar Cloud Messaging Technical Guide: Protocol Selection, Fine-Grained Filtering, and Delivery Pipeline Troubleshooting

Overview

Tuya Pulsar Cloud Messaging is a device event message queue service built on Apache Pulsar. It gives developers real-time push and persistent delivery for device events such as status changes, online/offline transitions, and alerts. The service is designed for high performance, horizontal scalability, and multi-tenant isolation.

As the number of connected devices grows and high-frequency reporting devices become more common, controlling message volume and improving integration efficiency become critical engineering concerns. This guide covers three dimensions: protocol selection, message filtering strategy, and delivery pipeline troubleshooting.

1. Integration Architecture

1.1 End-to-End Pipeline

IoT Device → Tuya Cloud Platform → Pulsar Message Queue → Consumer SDK → Developer Business System
                                            │
                                   ┌────────┴────────┐
                                   │  Filter Rule     │
                                   │  Engine          │
                                   │ (bizCode /       │
                                   │  attribute-level)│
                                   └─────────────────┘

1.2 Integration Steps

Step	Action	Notes
1	Create a cloud project	Tuya Cloud Developer Platform (platform.tuya.com)
2	Enable message subscription	Select the message types to subscribe to
3	Integrate the consumer SDK	Integrate the Pulsar consumer-side SDK
4	Configure filter rules	Apply fine-grained filtering by bizCode and attribute

2. Protocol Selection

2.1 Protocol Version Comparison

Tuya Pulsar supports two message push protocols. Choosing the wrong one results in duplicate message delivery:

Protocol Version	Use Case	Example Protocol Code
IoT Core new protocol	Using the new IoT Core connection service (device and space APIs)	1001
Legacy protocol	Using the legacy home and asset model	20

2.2 Selection Principles

• Choose the protocol that matches the API version you are actually using — avoid configuring both protocols simultaneously
• The same semantic event is expressed differently in each protocol (e.g., IoT Core’s deviceOnline vs. the legacy online) — the data structures differ but the meaning is the same
• Correct protocol selection can reduce message delivery volume by 50%

2.3 Protocol Code Reference

Event Type	IoT Core Protocol Code	Legacy Protocol Code	Semantic
Device online	1001 (deviceOnline)	20 (online)	Device connects to the network
Status report	1001 (statusReport)	4 (report)	Device attribute change
…	…	…	…

For the complete protocol code reference, see the Tuya developer documentation.

3. Fine-Grained Message Filtering

3.1 Filter Levels

Tuya Pulsar supports two levels of filter granularity:

Level 1: bizCode-level filtering (message type)
    └── Level 2: Attribute-level filtering (message content fields)

3.2 bizCode-Level Filtering

Subscribe only to the message types your business needs; ignore irrelevant events:

bizCode	Meaning	Typical Use Case
statusReport	Device status report	Sensor data, switch state changes
online	Device online	Device network-join monitoring
offline	Device offline	Offline alerting
bindUser	Device binding	User activation statistics
delete	Device deletion	Device lifecycle management

Configuration example — subscribe only to device binding and deletion:

Subscribe bizCode: [bindUser, delete]
Filter out: statusReport, online, offline, ...

3.3 Attribute-Level Filtering

For high-frequency message types (e.g., statusReport), further filtering by device attribute is supported:

Scenario: A device reports multiple status attributes (temperature, battery, switch state, fault code, etc.), but the business only cares about fault alerts.

bizCode: statusReport
Attribute filter: fault  (receive only fault alert attribute reports)
Filter out: temperature, battery, switch_1, ...

3.4 Per-Product Differentiated Configuration

Independent filter rules can be configured for each product:

Product	Subscribed bizCodes	Attribute Filter
Product A (monitoring & alerts)	statusReport	fault
Product B (data analytics)	statusReport	feed_report, feed_amount
Product C (lifecycle management)	bindUser, delete	—

3.5 Filtering Impact

• Filtered messages do not incur charges
• Real-world case: fine-grained configuration reduced message volume by 35% and saved approximately 20% in consumer-side infrastructure costs

4. Delivery Pipeline Troubleshooting

4.1 Log Trace Tool

When message delivery is abnormal, the delivery pipeline log can pinpoint the issue.

Entry point: Cloud Development → Cloud Monitoring → Server-side Message Logs

Function: View the complete delivery pipeline from Tuya Cloud to Pulsar and identify the exact reason a message was not received.

Note: This feature is included in the IoT Core service.

4.2 Delivery Status Reference

Status	Meaning	Action
Delivered	Message has reached Pulsar	Check whether the consumer is pulling messages correctly
Consumed	Consumer has acknowledged (ACK)	Normal — no action needed
Unconsumed	Message backlog	Check consumer SDK running state
Filtered	Matched a filter rule	Verify whether the filter configuration is as intended

4.3 Common Issue Checklist

Steps to diagnose unprocessed messages:

Step	Check	Notes
1	Is the consumer SDK running?	Confirm the process is healthy
2	Is the consumption logic sending ACK promptly?	Missing ACK causes redelivery
3	Is the consumption logic blocked?	Synchronous blocking causes message backlog
4	Network connectivity	Check network between the consumer and the Pulsar cluster

ACK mechanism:

Pulsar delivers message → Consumer SDK receives → Business logic processes → Sends ACK
                                                                          ↑
                                                        Must explicitly acknowledge after processing
                                                        Unacknowledged messages will be redelivered

4.4 Consumer Best Practices

Practice	Description
Async processing	Avoid blocking the consumption logic to prevent message backlog
Timely ACK	Acknowledge immediately after processing to avoid redelivery
Idempotent design	Consumption logic must be idempotent to handle message redelivery
Error isolation	Failure processing a single message must not block subsequent messages
Monitoring and alerting	Monitor consumption lag and backlog size

5. Cost Optimization Strategy Summary

Strategy	Expected Impact	Implementation Effort
Choose the correct protocol version	50% reduction in duplicate messages	Low (one-time configuration)
bizCode-level filtering	Eliminate irrelevant message types	Low (platform configuration)
Attribute-level filtering	Precise pruning of high-frequency messages	Medium (requires business analysis)
Per-product differentiated rules	Independent optimization per product	Medium
Async processing on the consumer side	Reduced infrastructure resource consumption	Medium (code optimization)

Combined optimization results (real-world case): 35% reduction in message volume, 20% reduction in consumer-side infrastructure costs.

6. Resources

Resource	Description
Tuya Cloud Developer Platform	https://platform.tuya.com/
Pulsar message queue documentation	https://developer.tuya.com/cn/docs/iot/message-service?id=K95zu0nzdw9cd