Forem: QuecPython

PWM- Pulse Width Modulation

QuecPython — Thu, 09 Apr 2026 08:08:59 +0000

ow PWM Works & Common Applications

Pulse Width Modulation (PWM) is a very effective technology that uses the digital output of a microprocessor to control analog circuits, widely used in measurement, communication, industrial control, and so on. The frequency of PWM refers to the number of times in 1 second that the signal goes from a high level to a low level and back to a high level, that is the exact periods in a secondPWM with Hz. The period unit of PWM is time, which refers to the time length of the signal from high level to low level and then to high level. The period is represented by T=1/f, f, while the f refers to the frequency. If the frequency is 50Hz, the one period will be 20ms. As a result, there are 50PWM periods per second. The pulse width with a unit of time is the duration of the high level in one period. Duty ratio refers to the ratio of the time of the high level to the entire period time in a pulse period, and the unit is % (0%-100%).

See following diagram:

In the figure above:

T: period
W: pulse width
ton: high level stage
toff: low level stage

See following formulas:

T=ton+toff, frequency
f=1/T
duty ratio =W/T

For example, T is 10ms and W is 8ms, then the duty cycle is 8/10= 80%, which is a pulse signal with a duty ratio of 80%.

Under the appropriate signal frequency, the effective voltage output can be changed by changing the duty cycle. Assuming that the high level of the IO port is 5V and the low level is 0V, the analog voltage signal simulated by digital signal is obtained by changing the duty ratio of the square wave output from the IO port. At a certain frequency, the duty ratio is 50%, and the simulated output

voltage of 2.5V can be obtained; When the duty ratio is 75%, the simulated output voltage of 3.75V can be obtained; When the duty ratio is 25%, a simulated 1.25V output voltage can be obtained. As shown in the picture below:

The PWM is widely used in motor control, steering manipulation, breathing light and screen back-light control.

PWM API Illustration

Create PWM object and initialize

It is necessary to create PWM object before deploying it.

The PWMn refers to supported PWM number while the output frequency, whose unit is Hz, will be in a form of float (I.e. 100.0 indicates 100Hz). In terms of duty, it owns a input range 0~100. The 50 means the duty ratio is 50%.

According to PWM clock source, target frequency and duty, the Clock divide factor, PRD value and duty register value will be calculated.

The division factor is selected from minimum to maximum. Once the clock source is divided by n, if the maximum value of PRD is not bigger than target output frequency, the n division will be adapted. Assuming that the clock frequency in PWM is represented by f, then clock frequency will be f/n in a method of n division, the PRD value will be manifested by (f/n)/frequency and the duty register value is equal to PRD value *duty.

The clock source of PWM will be 13 M or 26 M normally. When the output frequency is adjacent to clock source, the error in waveform will be fatal. Thus, it is suggested to control the frequency in 1MHz.

Enable PWM output

This interface shall be called if it is needed to enable PWM output. The frequency and duty are optional parameters. If there is no need to upload parameter, it will output according to the parameter set in stage of creating object. It it is needed to upload both parameters, it will output in accordance with uploaded parameters.

Example：

Disable PWM output:

This interface will be called if it is needed to stop PWM output.

Applicable Scenario

Drive motor

Necessary materials: EC600U module, Motor and Panel

How it works：

Take 24V DC motor as an example, connect 24V DC power supply at both ends of the motor, the motor will rotate at full speed, if the 24V voltage is reduced to 2/3, that is, 16V, then the motor will run at 2/3 of the full speed. It is obvious that if it is needed to adjust the speed of the motor, you only need to control the voltage at both ends of the motor, the higher the voltage, the faster the motor speed.

For DC motor, when providing power to the motor, the motor will rotate, but it will speed up gradually. When suddenly stopping the power supply to the motor, the motor will not stop due to the effect of inductance to prevent current mutation, and maintain the original speed. As a result, the speed of the motor is the average voltage output during the cycle back and forth. So in essence, our speed regulation is to put the motor in a state that seems to stop and not stop, rotate in full speed and not full speed, then the average speed in a cycle is the speed of our duty ratio.

In summary, the PWM will output pulse of a certain frequency. The greater the duty ratio, the greater the average voltage provided to the motor, the higher the motor speed. On the contrary, the lower the duty cycle, the smaller the average voltage provided to the motor, and the lower the motor speed. The normal PWM frequency is 6~16kHz.

HW connection: Design circuit in accordance with the specific motor interface

Example: Control the speed from minimum to maximum

Adjust screen luminance

Necessary materials: EC600U module, LCD Display

How it works :

PWM light adjustment mode: The luminance of the back-light is actually fixed, it is to adjust the

screen luminance by controlling the length of time that the back-light is turned on and off periodically. Take 75% luminance as a example, that means in each unduly short time period, the back-light will be on during 75% of the time and off in 25% of the time. Owing to the visual retention effect, It seems that the screen is always on at 75% luminance, but in fact it is blinking in a pace of "on→ off → on→ off" with 100% luminance. The luminance of the screen is controlled by adjusting the duty ratio to control the proportion of time between the screen on and off in specific period,

HW Connection: Conduct circuit design according to specific LCD back-light interface

Example: Control screen luminance from dim to bright then to dim periodically.

FAQ

How to adjust duty dynamically？

After creating PWM object, it is available to adjust duty ratio via PWM.Open() instead of creating object each time. E.g. It is valid to set the duty ratio as 50% via PWM.Open(100,0,50), and 25% via PWM.Open(100,0,25).

Range of PWM Output frequency

EC200A/EC600N/EC800N/EG912N: 1Hz~1MHz

EC200U/EC600U/EG915U: 100Hz~1MHz

BG95：293Hz-600kHz.

GPIO- General-Purpose Input/Output

QuecPython — Thu, 09 Apr 2026 07:55:13 +0000

Basic Knowledge

It will benefit us a lot by learning about basic knowledge on GPIO.

Framework

The GPIO (Abbreviation of General-purpose input/output), a kind of input/output interface for general data, communicates with external electrical components or devices, which can be deployed in micro-processor, micro-controller, and other embedded systems.

See basic diagram as below：

I/O pin: The actual HW interface in a microprocessor or microcontroller that connects to an external device. Each GPIO pin can be programmed in input or output mode.

Protection diode: One special diode that protects the I/O pin in a microcontroller or microprocessor from influence caused by voltage kick-out or ESD.Pull-up/down resistor: It sets the status of the GPIO pin in IDLE or in a condition of an invisible input signal.

The Pull-up resistor will connect the GPIO pin to the positive to set it as the default high-level status. While the Pull-down resistor will connect the GPIO pin to the GND to set it as the default low-level status. Both of them will be controlled by a register configured by SW.

P-MOS and N-MOS: The circuit with P-MOS and N-MOS will facilitate GPIO with "Push-pull" and"Open-drain" modes.

TTL Schmitt trigger: Process noise or unstable input data. It will eliminate the noise of the data signal based on the highest threshold and the lowest threshold to provide a more accurate digital signal.

Output driver: Control the voltage and current of the GPIO pin in output mode.

Input receiver: Process input signal from the GPIO pin. In most cases, one TTL Schmitt trigger will be embedded to eliminate the noise of the digital signal.

Working mode

Floating input

Called as Hi-Z, it means the GPIO pin will be floating without being pulled to any logic level. In this status, the GPIO pin can pick up voltage noise easily and read random value. Therefore, please avoid it unless given reason.

The contents highlighted by a yellow background illustrate the data transmission channel. The external level signal will enter the internal chip via the I/O with number ①; After that, it will be reformed bySchmitt trigger with number ②, the signal will arrive at the "Input data register" with number ③, and ends at the other terminal (Number ④) of the "Input data register". Thus, it is available to read the level change of I/O via the internal data bus as you wish.

Pull-up input

The pull-up resistor is linked between GPIO pin and VDD. Therefore, under the circumstance that the GPIO pin is not driven by the device actively, it will be pulled up to logic high level. In the condition that the default status of the GPIO pin is high level, please configure it as pull-up mode.

Compared with the aforementioned floating input, one pull-up resistor ranged 30KΩ~50KΩ isconnected in data channel. In the condition that there is no signal input in I/O, the level in the input terminal can be maintained high (The VDD goes through a pull-up resistor). In addition, when the level input in I/O is low, the level in input terminal will be low as well.

Pull-down input

The pull-down resistor is linked between GPIO pin and VSS. Therefore, under the circumstances that the GPIO pin is not driven by device actively, it will be pulled down to logic low level. In the condition that the default status of GPIO pin is low level, please configure it as pull-down mode.

In terms of input pull-down mode, one pull-down resistor ranged 30KΩ~50KΩ is linked in the data channel.

Analog input

There is neither pull-up resistor nor pull-down resistor and the signal will enter analog input channel without going through Schmitt trigger. Normally, it will be used in ADC data sampling.

Open-Drain output

In Open-Drain output mode, the GPIO pin will pull down voltage actively via connecting to GND instead of pulling up. If it is needed to pull up voltage, one extra pull-up resistor shall be connected to the power supply. It will be applied in I2C communication normally, among which, multiple devices can share one data cable synchronously.

In condition that the CPU writes into data via "Bit set/reset registers" or "Output data register" with the levelnumber ①, this data bit will be transferred to I/O with number ④ via the "output control circuit“with number ②. If the logic "1" is written by CPU, the N-MOS with number ③ will be off and thelevel in I/O is determined by external pull-up resistor. While the logic "0" is written, the N-MOS withnumber ③ will be on and the level in I/O will be pulled down to zero correspondingly.

As above figure shows, the Schmitt trigger is switched on, which means the CPU can monitor theI/O on other side of "Input data register". Based on this characteristic, it is also available toimplement the virtual bilateral communication in I/O. Assuming that the CPU outputs logic "1", thelevel in I/O will be determined by external circuit completely since the N-MOS with Number ③ is off. Therefore, the CPU is capable to read the external circuit signal in "Input data register" instead of the logic "1" outputted by itself.

Push-pull output

In Push-Pull output mode, the GPIO pin will drive high level or low level actively. That means the GPIO can not only push the voltage to high level but also pull voltage to low level. This mode can provide a powerful driver, which is suitable for load such as LED and motor.

The most prominent characteristic of push-pull output lies in that it can output high leveland low level truly. Moreover, it is equipped with driver in both levels.

Interrupt Framework

Interrupt Mask Register: This register will mask or disable dedicated interrupt for sake of preventing it from triggering interrupt service routine (Abbreviated as ISR hereinafter). When the certain bit is set as 1, the corresponding interrupt will be masked.

Pending Request Register: This register will store the pending interrupt request. Once the valuein corresponding bit is 1, which means the relevant interrupt is pending.

Software Interrupt Event Register: This register allows software to generate interrupt. The interrupt service routine (ISR) related to dedicated interrupt will be triggered by writing into this register.

Rising Trigger Selection Register: This register will trigger interrupt in rising edge of signal.

Falling Trigger Selection Register: This register will trigger interrupt in falling edge of signal.

Edge Detector Circuit: This is HW circuit, which will trigger interrupt by detecting the change inrising edge or falling edge.

Timing Mask Register: This register will mask the interrupt generated in specific time. Normally, itwill eliminate the interrupt triggered in a error way.

Pulse Generator: It will generate a series of pulse in HW, which will trigger timing or synchronized events, including interrupt.

NVIC (Nested Vectored Interrupt Controller): As a part of ARM Cortex-M, it will manage interrupts, especially the nested and interrupt vector, that is the pointer points at interrupt service routine.

Function Multiplexing

In embedded systems, including plenty of micro-controllers and micro-processors, some dedicated physical pins can be configured as different functions, that is called Pin Multiplexing.

Then, how to understand it? The key point is to learn that some pins can be converted among different HW components, resulting in huger flexibility in stage of HW design. The purpose of pin multiplexing is to reduce space and cost since the quantity of physical pins will be decreased.

The physical pins of an embedded chip may be designed to switch among several functions:

General data Input/output as GPIO
As a part of SPI interface, it will communicate with other SPI devices
As a part of UART interface, it will used in serial communication
Or it is endowed with other specialized functions such as ADC input or PWM output.

In stage of embedded system design, it is possible to configure these pins according to HW and SW demands. In addition, it is also allowed by some embedded platforms to convert these pins dynamically when operating, providing much flexibility.

Absolutely, each coin has two sides, the pin multiplexing also owns limitation. I.e. one pin is not allowed to execute two or dmore functions at the same time. Therefore, please take it into consideration during the period of system design. Moreover, the pin multiplexing management will induce the system complexity and more SWs are demanded to configure and use these pins properly.

Debounce

Button debounce is common issue when processing mechanical button input in the corresponding system. Due to its characteristic, the touch point will be opened or closed for several times in a rapid way when pressing or releasing button, resulting in multiple level change in ultra-short time,that is called "bounce". The system may mistake the button for being pressed or released more than once if the bounce is not eliminated. Therefore, please take measures to eliminate or reduce it at least.

Normally, it is divided into two classes- HW debounce and SW debounce.

HW debounce

The purpose of HW debounce is to process the bounce caused by mechanical button and acquire one stable and undisturbed level signal. See following common methods.

RC filter:

Component:

Resistor(R): Connect to one end of button
Capacitor(C): Connect with the other end of button to GND

Characteristic:

- LPF (low-pass filter): Due to its structure, the RC filter will allow the low frequency signal topass and filter high frequency signal

Operation:

When the button is pressed or released, the capacitor will start charging or discharging. Therefore, for rapid voltage changes (such as those due to contact bounce), the RC filter smooths these changes, thereby preventing misjudgments.
The strength of this smoothing effect is determined by the RC time constant (τ = R×C). This time constant represents the time it takes the capacitor to charge to 63.2% of its initial voltage.

Common parameters:

Resistor(R): 1kΩ ~10kΩ
Capacitor(C): 0.1µF~10µF

Advantage:

Simplicity: Only two basic components are needed
Economy: Both resistor and capacitor are low-cost
Effectiveness: In terms of majority of common applications, the debounce capability is sufficient.

Disadvantage:

Delay: The ultra huge RC time constant will cause unnecessary delay in button response.
Environment sensitivity: The variation in temperature and humidity may influence the capacitor value and debounce effect further.
Not all applications can be applied: For quick-response application, the RC filter will not be the optimum selection.

If the RC filter is taken in HW debounce solution, the suitable resistor and capacitor values are important since it will filter bounce effectively without inducing excessive response delay at the same time. Therefore, in design stage, it is necessary to test different combinations of R and C to achieve the optimum debounce effect.

Schmitt Trigger:

Component:

Schmitt trigger: In essential, it is a power comparator with dual thresholds. Due to its characteristic, it can not only be one independent component but also a part of a microcontroller.

Characteristic:

Dual threshold: The main characteristic of Schmitt trigger lies in that it owns two thresholds, Vt+ & Vt-.

Operation:

Once the input voltage rises and surpasses the Vt+, the output will switch to high status.
Once the input falls and is lower than Vt-, the output will switch to low status.
This characteristic can guarantee that the output status will not change if any minor change in input voltage so as to filter bounce effectively.Common parameter Vt+ & Vt-: The gap between two thresholds is called as hysteresis or dead zone.

Common parameter:

Vt+ & Vt-: The gap between two thresholds is called as hysteresis or dead zone.

Advantage:

Perfect debounce: Owing to dual threshold characteristic. the Schmitt trigger is endowedwith powerful tolerance in input noise and bounce.
Explicit output: The output will be either low or high level, which will not fluctuate betweenthem.
Widespread application: The input of GPIO in multiple micro-controllers are embedded withoptional Schmitt trigger.

Disadvantage:

Possible delay: In some cases, if the change in input signal is slow, the trigger will cause a minor delay.
Inadequate fast signal: In terms of signal with high frequency, the Schmitt trigger will not be the optimum since it will lead to signal distortion
Cost: Although many micro-controllers are embedded with Schmitt trigger. If the external trigger is needed, the cost will increase as well.

_As for selected debounce method and component value, please consider the bounce frequency and duration.

If RC filter is deployed, please confirm the RC time constant can eliminate bounce without unduly delaying the button response.

If it works in environment with noise, please consider other elements such as external EMI (Electromagnetic Interference)

The test plays a vital role. After the design is complete, the system should be tested enough to ensure that the debounce circuit will work properly under all expected conditions._

Shunt capacitor

Component:

Capacitor (C): Connect with key directly. Normally, it will connect with one terminal of button and the GND.

Characteristic:

Delayed charging/discharging: Owing to its characteristic, the capacitor should take time in charging and discharging

Operation:

Under the circumstance that the button is not pressed yet, the capacitor will in discharging status.
Once the button is pressed, it will spend certain time in charging till the capacitor is full, which will do a favor in filtering the short bounce that may occur.
Similarly, when the button is released, the capacitor will discharge in due time so as to eliminate possible bounce.

Common parameters:

Capacitor (C): 1nF ~10µF. The specific value is determined by dedicated demand and the frequency of key bounce.

Advantage:

- Simplicity: Only one capacitor is needed and the connection is simple as well
- Low cost: The capacitor is cheap and easy to acquire.
- Apparent effect: It will debounce heavily in terms of most of common button bounces.

Disadvantage:

Possible delay: Ultra-huge capacitor will lead to obvious delay in key response.
Environment sensitivity: The variation in temperature and humidity may influence the capacitor value and debounce effect further.
Power noise: If the power noise is generated by other components in system, this shunt capacitor may magnify the noise.
Not all applications can be applied: For quick-response application, this method will not be the optimum.

RS trigger:

Component:

RS trigger: Normally, the basic bistable circuit is made by two NAND gates or NOR gates.
Two Inputs: R (Reset) & S (Set)。
Two outputs: Q & ~Q (Inversion of Q)。

Characteristic:

Bistable: The RS trigger always owns two stable output statuses

Operation:

In condition that the input in S is 1 and the input of R is 0. the output of Q will be 1 while the Q will be 0.
In condition that the input in R is 1 and the input of S is 0. the output of Q will be 0 while the Q will be 1.
Under the circumstance that both inputs are 0, the RS trigger will maintain current status
Under the circumstance that both inputs are 1, this status is not allowed and uncertain output will be triggered probably.

In order to eliminate button bounce, the RS trigger can be configured as the situation that only when the button is truly pressed or released can the status be changed. Any momentary bounce related to button will not change the output of RS trigger, leading to effective debounce.

Common parameter:

Input logic level
For RS trigger of NAND, the common logic level is 1
For RS trigger of NOR, the common logic level is 0

Advantage:

High effective debounce: The RS trigger provides stable output for the button no matter how noisy the input.
Explicit output status: There will be high or low output in any given time.
Low cost: The RS trigger can be built by basic logic gate.

Disadvantage:

Complexity: Compared with simple shunt capacitor or Schmitt trigger, more components and more complex traces are needed.
Impermissible status: There exists one impermissible status in RS trigger, please avoid in stage of design.
Power supply demand: Appropriate power shall be provided for RS trigger

Proprietary debouncer

_There are some proprietary debouncers such as MAX6816, MAX6817 and MAX6818 in market. The filter and Schmitt trigger involved in these ICs can be valid to connect to button and provide stable data output.

As for selected debounce method and component value, please consider the bounce frequency and duration.

If RC filter is deployed, please confirm the RC time constant can eliminate bounce without unduly delaying the key response.

If it works in environment with noise, please consider other elements such as external EMI (Electromagnetic Interference)

The test plays a vital role. After the design is complete, the system should be tested enough to ensure that the debounce circuit will work properly under all expected conditions._

SW debounce

This method will eliminate button bounce via algorithm and logic in SW. Compared with former method, it provides more flexibility in terms of different applications and conditions as well as burden increased.

See common embedded SW debounce methods:

### Delay
Operation:

Once the button status changes (i.e., changes from never-pressed status to pressed status),the program will wait one predetermined delay time instead of responding this change immediately. After this delay is over, the program will detect button status again. If the button status maintains, this operation will be considered as valid and the program will respond it. Otherwise, it will be taken as error or bounce, resulting in no response

Advantage:

1.Simple implementation: The delay will be simplest and targeted SW debounce method by adding one delay function after the button status is changed.
2.No extra resource is needed: Compared with other methods such as counter or FSM, neither extra storage nor counting resource are needed in this method.

Disadvantage:

Response delay: Since it is needed to wait predetermined delay time to confirm the pressed action, the response delay will be caused.
CPU time consumption: If the busy-waiting is used to implement delay, it will be a failure for CPU to execute any task in this period, which is unacceptable in embedded system with restricted resources.
Unreliability: If the bounce lasts longer than the predetermined delay time, this method may still produce an error. In addition, if the delay time is set too long, you may miss the rapid continuous button action

Counter

Operation:

When it detects the button status change, the system will not confirm immediately. Instead, one counter will be initiated. In following consecutive tests, if the button status keeps changing, the value in counter will increase corresponding. While the button returns to original status, the counter will be reset instead. Only under the circumstance that the value in counter reaches the pre-determined threshold can the button status change be considered as the true press and responded by system. Thus, the momentary bounce will not reach the threshold of counter and it can't be mistaken for a valid button action.

Advantage:

Perfect reliability: Compared with simple delay debounce, it will filter the momentary bounce more reliably.
Perfect response: If the button is pressed consecutively, the system will confirm this action in a relatively short time to provide faster response.
Flexibility: It is available to adjust counter threshold via actual need to adapt to different button and bounce characteristic.

Disadvantage:

Resource consumption: It is needed to arrange one counter for each button or one global counter for system, which may consumer extra storage and counting resource.
Complexity: Compared with simple delay debounce, the debounce by counter will be more complex actually, especially in scenario that needs multiple keys.
Possible delay: If the predetermined threshold in counter is unduly high, it will cause delayed response in system and bad user feeling.

HTTP Communication

QuecPython — Thu, 09 Apr 2026 07:21:43 +0000

Introduction to HTTP

HTTP Protocol

HTTP (Hyper Text Transfer Protocol) is a communication protocol that allows clients to request and access server resources through URLs (Uniform Resource Locators). This protocol is based on the client-server model and organizes requests and responses in text format. The communication model is as follows:

HTTP is commonly used for web page
acquisition and form submission based on browsers, file upload and download, mobile applications, and data reporting for IoT devices.

Request and Response Messages

Request Message

The format of an HTTP request message is as follows:

Request line: The request line, consisting of the method, URL, and Version fields.
Method: Request method. Commonly used methods include GET, POST, PUT, HEAD, DELETE, etc. See details below.
URL: Uniform Resource Locator, used to identify the path of server resources.
Version: Protocol version, currently the commonly used version is HTTP/1.1.
Header lines: Request headers, consisting of one or more header fields, each with the format header field name: value.
Head field name: The name of the head field.
Value: The value of the header field.
Entity body: The message body, which is the main text of the message passed to the server.

Note that sp represents a space, cr lf represents a carriage return and line feed. There must be a blank line between the request headers and the message body, i.e., the blank line in the figure.

Here is an example of a request message:

Response Message

The format of an HTTP response message is as follows:

Version: Protocol version, currently the commonly used version is HTTP/1.1.
Status code: Response status code, details are provided below.
Phrase: Reason phrase.
Header lines: Response headers, consisting of one or more header fields, each formatted as header field name: value.
Head field name: The name of the head field.
Value: The value of the header field.
Entity body: The message body, which is the message content of the server response.

Note that sp represents a space, cr lf represents a carriage return and line feed. There must be a blank line between the response headers and the message body, as shown in the diagram.

Here is an example of a response message:

HTTP Request Methods

The commonly used HTTP methods include GET, POST, PUT, HEAD, and DELETE.

GET: The most commonly used method in HTTP requests, used to request resources from the server.
HEAD: Verify the validity of a URL and retrieve information such as the last modified date of a resource, which is similar to the GET method, but without returning the message body.
PUT: Upload resources to the server. Create a resource if no resource exists; otherwise, replace the resource.
POST: Modify server resources. Create a resource if no resource exists; otherwise, update the resource.
DELETE: Deletes a resource, the opposite of the PUT method.

HTTP Status Codes

The first line of a server's response message is the status line, which includes the status code and reason phrase to inform the client of the result of the request.

For more details about the HTTP protocol, please refer to the official documentation of the Internet Engineering Task Force (IETF).

The difference and relation between HTTP and TCP protocols:

_- HTTP is based on the TCP protocol.

TCP is a byte stream protocol, and it is difficult for users to determine the boundaries of business data. While HTTP has a specific message format, and message length can be specified by the Content-Length: ${Length} header, or the data encoding format can be specified by the Transfer-Encoding:chunked header. Both can identify message boundaries. QuecPython modules support parsing both Content-Length: ${Length} and Transfer-Encoding: chunked._

HTTP Application Examples

Query Weather
Amap Weather Query Open API:

北京 can be replaced with the name of other cities in China.

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: