DEV Community: QuecPython

Watchdog Timer

QuecPython — Wed, 08 Apr 2026 07:57:46 +0000

Overview

For cellular communication modules, the watchdog is a hardware or software monitoring mechanism used to monitor the module's operating status. When the module gets stuck in a deadlock due to external interference or program errors, the watchdog automatically triggers a module restart to restore the module's operating status.

The following terms are generally used to describe the triggering and resetting behavior of a watchdog:

Bite: Refers to the action of the watchdog triggering a module restart.
Feed: Refers to the action of resetting the watchdog status of the module (to notify the watchdog that it is still running normally).

Hardware Watchdog

Principle of hardware watchdog: A typical hardware watchdog mainly consists of a hardware timer, input, and output. Its input is connected to the module's IO, and the output is connected to the module's RESET pin. The hardware timer of the watchdog keeps increasing, and when it exceeds the threshold time, it triggers a module reset through the output pin (this is called "bite").

A normally running module should periodically output a signal to the watchdog through IO, which resets the watchdog timer before it reaches the threshold (i.e., "feeding the dog"). Therefore, when the module is running normally, the timer should not reach the threshold.

When the module is running abnormally and fails to reset the watchdog timer within the specified time, the module's RESET pin is triggered, causing a reset.

Quecpython communication modules generally have a built-in watchdog, and software watchdogs can also be implemented in the application. Why do we need an external watchdog? This is because whether it is a built-in watchdog or a software watchdog, they both need to go through the initialization process when the module starts up. If these two watchdogs have not finished initializing and there are exceptions or blocking situations, only an external watchdog can play a role.

Typical hardware watchdog diagram:

As shown in the diagram, the basic structure of a hardware watchdog is like this. WDI is the input, and RESET is the output. When WDI detects a level change, it is considered as feeding the dog and clears the timer's count. If the dog is not fed within a certain period of time, the timer will time out and trigger a module restart through the RESET pin.

Software Watchdog

Principle of software watchdog: Similar to a hardware watchdog, a software watchdog is implemented using a software timer. It is generally used to monitor the running of specific threads, and the monitored threads need to reset the timer regularly.

In some cases, some business threads become blocked or exit abnormally, but the whole system remains normal and cannot trigger the protection mechanism of a hardware watchdog. A software watchdog can monitor one or several specific threads and trigger a reset when these threads encounter exceptions.
Typical software watchdog diagram:

As shown in the diagram, a software watchdog generally runs in a daemon thread. Its basic logic is shown in the diagram. The watchdog thread runs with the business and functions like a timed heartbeat. Most of the time, it is in sleep mode and performs the counter check action during the heartbeat. When the counter reaches zero, a reset is triggered.

The watchdog monitors a specific business thread, which means that this specific business thread needs to perform the feeding action, i.e., resetting the watchdog timer regularly. If this thread exists abnormally or becomes blocked, it cannot reset the watchdog timer. When the watchdog thread's counter decreases to 0, a reset is triggered.

As a daemon thread, it is important to note that if the feeding thread exits actively, the watchdog thread must also be stopped to prevent false triggering of a reset.

Built-in Watchdog in the Module

Cellular modules generally have a built-in hardware watchdog, which mainly monitors the running of the RTOS. When the watchdog bites, it may trigger a reset or a watchdog interrupt. The feeding mechanism is usually implemented by the task with the lowest priority, and system crashes, long-term CPU usage by threads or interrupts can all trigger the watchdog bite.

Compared to a general hardware watchdog, the built-in watchdog usually starts with the module's CPU and needs to obtain the clock source from the module (a hardware watchdog usually has its own clock source). In addition to triggering a RESET, the action of the watchdog bite can also choose to trigger a watchdog interrupt (used for outputting debug information or entering dump mode).

Timing Diagram of Watchdog Biting due to an Infinite Loop:

During normal operation, the low-priority feeding thread runs periodically, with most of the time being idle. When a business thread enters an infinite loop, the feeding thread cannot preempt the CPU and cannot perform the feeding action. When the watchdog times out, a reset or a watchdog interrupt is triggered.

Underlying Runaway:

Due to memory trampling, electromagnetic interference, and other factors, the data in memory becomes corrupted, causing the CPU to fetch an incorrect program address and run into abnormal logic, resulting in a deadlock or infinite loop, which leads to a watchdog timeout.

Precautions for Application Programming:

Since the built-in watchdog is designed for the RTOS, we cannot control the feeding action at the application layer. Therefore, we need to avoid situations where the business occupies the CPU for a long time, mainly to avoid deadlocks and infinite loops, including the following points:

Try to eliminate possible infinite loop logic in the business.
Set reasonable blocking or sleep in the business to ensure that low-priority tasks can be scheduled normally.
For necessary loops, add safety measures. For example, add a loop counter in the loop body, so even if an infinite loop occurs, it can be exited after a certain number of iterations.
Check mutexes to ensure that their usage is paired. Deleting a thread that holds a lock without releasing the mutex it holds will cause the threads that are mutually exclusive with it to be unable to run. Be sure to release the mutex held by the thread before deleting it.

Cases not covered by the built-in watchdog:
The built-in watchdog initializes during startup, so it actually cannot protect against exceptions or blocking in the startup process. This defect should be noted in scenarios where multiple power cycles are required, and an external watchdog is needed to solve this problem.

External Watchdog Solution

Recommended Watchdog Chip:

TPS3823-33DBVR
Working voltage: DC 1.1V~5V
Maximum feeding time: 1.6S
Reset pin: Low-level effective
Current consumption: 15uA

Feeding the External Watchdog under Special Circumstances:

During the boot-up process, If the boot process time will be significantly longer than the threshold value that triggers the watchdog to bite, it is necessary to trigger a WDI level change in the boot or delay the effective time of the watchdog.
During the FOTA process: Use the callback of the FOTA progress to operate the WDI interface level change. When FOTA has not adapted the callback and cannot operate IO, you need to find a way to stop the operation of the watchdog.
You can choose a watchdog with a longer maximum feeding time, so that its feeding time is longer than the boot-up and FOTA time. This method is applicable to both situations above, but the disadvantage is that it takes a long time to reset when an exception occurs.

Typical Circuit Design for Whether the Watchdog Is Effective:
Use a transistor, when the gate is connected to a high level, the watchdog and the RESET pin of the module are conductive.

External Watchdog Feeding Routine:

Software Watchdog Solution:

The software watchdog is generally run in a daemon thread, which can cover scenarios where the business thread is abnormally blocked or exits (but the system remains running normally

Software Watchdog Example & In-business Feeding Example:

## Frequently Asked Questions

How to determine the feeding interval for the software watchdog?

There are three principles to consider:

The feeding interval must be longer than the single execution time of the business code. Otherwise, even if the watchdog is fed within the business thread, a restart will be triggered before the next feeding.
The feeding interval is also the heartbeat interval of the daemon thread. It is recommended to be an integer multiple of the heartbeat interval of the business thread. This allows the module to handle both the business and watchdog heartbeats when it wakes up, reducing the number of wake-ups and reducing power consumption.
The feeding interval needs to match the business requirements. A too-long feeding interval will result in a long waiting time for recovery when an exception occurs.

How to feed the watchdog during FOTA?

Control the feeding IO through the FOTA progress callback.
For modules without FOTA progress callbacks, temporarily disable the watchdog. The circuit design can refer to the "External Watchdog Solution" section.

How to determine if an external watchdog is needed?

An external watchdog is needed when the product requires high reliability.
For products that frequently power on and off the module, there is a higher possibility of triggering the failure of the internal watchdog. In this case, an external watchdog is needed.

MQTT Application Note

QuecPython — Wed, 08 Apr 2026 07:38:42 +0000

This document provides a detailed introduction on how to use the MQTT protocol for communication in QuecPython. It includes an overview of the protocol, environment setup, code examples, and result demonstrations.

Overview

MQTT is a lightweight messaging protocol designed to facilitate reliable communication between devices in Internet of Things (IoT) applications. It operates on a publish-subscribe pattern, involving communication between an MQTT server (broker or server) and multiple MQTT clients.The MQTT protocol encompasses the following characteristics:

Lightweight: The design of the MQTT protocol is simple, with minimal protocol header overhead, making it suitable for resource-constrained devices and networks.
Low Bandwidth Consumption: MQTT employs binary encoding, effectively utilizing network bandwidth.
Asynchronous Communication: The client can publish and subscribe to messages at any time without waiting for responses from the MQTT server.
Publish-Subscribe Pattern: The message publisher releases messages to specific topics, while the subscriber subscribes to topics of interest. This pattern supports loose coupling, communication, and flexible message delivery.

MQTT Application Scenarios

MQTT plays a significant role in various fields, including the Internet of Things (IoT), sensor networks, remote monitoring and control, real-time data transmission, message push and notifications, connected vehicles, and energy management. Its lightweight nature, low bandwidth consumption, and reliable message delivery mechanism make MQTT a preferred communication protocol in many applications. Here are some commonly used scenarios:

Internet of Things (IoT): MQTT is one of the most commonly used communication protocols in IoT applications. It is suitable for scenarios involving a large number of connected devices, offering reliable message delivery and real-time communication. MQTT's lightweight nature allows it to operate in resource-constrained devices and network environments, while supporting the publish-subscribe pattern and asynchronous communication, enabling devices to exchange information, monitor, and control in real time.
Sensor Networks: MQTT can be employed for data collection and real-time monitoring in sensor networks. Sensors can publish data to specific topics, and subscribers can subscribe to topics of interest to receive sensor data. MQTT's low bandwidth consumption and efficient message delivery mechanism make it a reliable choice for data transmission in sensor networks.
Remote Monitoring and Control: MQTT makes remote monitoring and control straightforward and reliable. Real-time monitoring of device status, sensor data, and remote control can be performed through MQTT. This is highly beneficial in applications such as smart homes, smart cities, and industrial automation etc..
Real-time Data Transmission: MQTT's asynchronous communication mechanism makes it well-suited for real-time data transmission scenarios. It can transmit data with minimal latency, enabling real-time monitoring and communication. For instance, in financial trading systems, MQTT can be used to transmit real-time market data to trading systems and investors.
Message Push and Notifications: MQTT's publish-subscribe pattern makes it an ideal choice for message push and notifications. The server can publish messages to specific topics, and subscribers will receive these messages in real time. This is valuable for push notifications in applications, chat applications, and real-time data updates.
Connected Vehicles (Connected Car): MQTT can be employed for communication between vehicles and between vehicles and cloud platforms. It can support functionalities such as vehicle status monitoring, vehicle diagnostics, and remote control, enhancing vehicle safety and efficiency.
Energy Management: MQTT can be used for data transmission in energy monitoring and management systems. Through MQTT, real-time energy consumption data can be transmitted to monitoring and analysis systems for energy consumption optimization and monitoring purposes.

MQTT Communication Mechanism

In MQTT, communication is accomplished through TCP connections between clients and the server. The client initiates a connection request by sending a CONNECT message and then sendsvarious operational messages, such as SUBSCRIBE, PUBLISH, UNSUBSCRIBE, once the connectionis established.

Publishers, when sending messages to a specific topic, transmit the message content along with the specific topic to the MQTT server. The server then delivers the message to all subscribers who have subscribed to that topic.

Subscribers use the SUBSCRIBE message to subscribe to topics of interest, specifying the topic and desired QoS level. Upon receiving a subscription request, the server records the subscriber'ssubscription information and forwards relevant messages to the subscriber when the messagesare published.

MQTT also supports retained messages, where a publisher can send a retained message and set the retained flag. The retained message is stored by the server and sent to subscribers who subscribe to the relevant topic. This allows new subscribers to receive the latest retained message.

Additionally, MQTT provides the mechanism of persistent sessions. Persistent sessions allow clients to maintain their subscription and publication state information when reconnecting. This ensures that important messages are not lost.

Through these mechanisms, MQTT achieves reliable message delivery, decoupling, and asynchronous real-time communication. It is suitable for scenarios such as IoT, sensor networks, and real-time data transmission. MQTT offers a flexible communication model and mechanismsthat enable efficient message interactions between devices and applications.

MQTT Client: An MQTT client refers to a device or application that connects to an MQTT server. Each client is identified by a unique client identifier, which is used by the server to distinguish and differentiate between different clients. In QuecPython, we use umqtt to implement MQTT clients. A connection object is created by passing initialization parameters,and for more details, click here.

MQTT Application

The module uses umqtt of QuecPython to set up the MQTT Client B, connects to the server and subscribes to Topic B. This will work in coordination with Client A to complete the message push and receive process. Please note that for using MQTT functionality in QuecPython, you need to ensure the following:

Download QuecPython Firmware: Depending on your module model, flash the QuecPython firmware into your device.
Connect to the Network: Ensure that your device is properly connected to the network.

Once you have confirmed that the device's network is functioning properly, you can create anMQTT object with the umqtt API. See as follows: