Skip to content

Commit 1f61684

Browse files
fpistmfpistm
authored
Merge pull request #292 from fpistm/IWDG-234
Add built-in IWatchdog library to expose the IWDG component.
2 parents 7dfccee + c1b0dae commit 1f61684

File tree

6 files changed

+454
-0
lines changed

6 files changed

+454
-0
lines changed

‎libraries/IWatchdog/README.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
## IWatchdog Library V1.0.0 for stm32 Arduino core
2+
3+
**Written by:** _Venelin Efremov_ and _Frederic Pillon_
4+
5+
### Requirement
6+
* [Arduino_Core_STM32](https://github.com/stm32duino/Arduino_Core_STM32) version > 1.3.0
7+
8+
### What is the IWatchdog library.
9+
10+
Th IWatchdog library provides an interface to the independent watchdog module (IWDG) inside STM32 chips.
11+
The IWDG module is used in production systems to generate a reset signal to the CPU in case some
12+
catastrophic event causes the software to become "stuck" or unresponsive.
13+
14+
The IWDG module contains a count-down timer. The module would generate a reset condition when the timer
15+
reaches zero. In normal operation mode the software running on the CPU would reload the timer periodically to
16+
prevent the reset condition from happening. However if a software bug or other error causes the CPU to
17+
execute a different code path for too long, the reload would not happen and the IWDG module would reset the CPU.
18+
19+
### How to use it
20+
The IWatchdog is a built-in library included with the STM32 core package. To add its functionality to your sketch
21+
you will need to reference the library header file. It is done by adding: `#include <IWatchdog.h>`
22+
23+
```Arduino
24+
#include <IWatchdog.h>
25+
26+
void setup() {
27+
...
28+
// Initialize the IWDG with 4 seconds timeout.
29+
// This would cause a CPU reset if the IWDG timer
30+
// is not reloaded in approximately 4 seconds.
31+
IWatchdog.begin(4000000);
32+
}
33+
34+
void loop() {
35+
...your code here...
36+
// make sure the code in this loop is executed in
37+
// less than 2 seconds to leave 50% headroom for
38+
// the timer reload.
39+
IWatchdog.reload();
40+
}
41+
42+
```
43+
44+
### Library functions
45+
46+
#### Preinstantiate Object
47+
48+
A default instance is available: `IWatchdog`
49+
50+
```Arduino
51+
IWatchdogClass IWatchdog = IWatchdogClass();
52+
```
53+
54+
#### Predefined values
55+
56+
* Minimal timeout in microseconds: `IWDG_TIMEOUT_MIN`
57+
* Maximal timeout in microseconds: `IWDG_TIMEOUT_MAX`
58+
59+
#### `void begin(uint32_t timeout, uint32_t window = IWDG_TIMEOUT_MAX)`
60+
61+
The `begin()` function would initialize the IWDG hardware block.
62+
63+
The `timeout` parameter is in microseconds and set the timer reset timeout.
64+
When the timer reaches zero the hardware block would generate a reset signal
65+
for the CPU.
66+
67+
When specifying timeout value plan to refresh the timer at least twice
68+
as often. The `reload()` operation is not expensive.
69+
70+
The downside of selecting a very large timeout value is that your system
71+
may be left in a "stuck" state for too long, before the reset is
72+
generated.
73+
74+
Valid timeout values depends of the LSI clock. Typically, it is 32kH value are between
75+
125µs and 32,768ms (~32.8 seconds). The precision depends of the timeout values:
76+
77+
| timeout value range | timeout value precision |
78+
| ------------------- |:-----------------------:|
79+
| 125µs - 512ms | 125µs
80+
| 513ms - 1024ms | 250µs
81+
| 1025ms - 2048ms | 500µs
82+
| 2049ms - 4096ms | 1ms
83+
| 4097ms - 8192ms | 2ms
84+
| 8193ms - 16384ms | 4ms
85+
| 16385ms - 32768ms | 8ms
86+
87+
The optional `window` parameter is in microseconds and must be less than `timeout`.
88+
If the window option is enabled, the counter must be refreshed inside the window;
89+
otherwise, a system reset is generated.
90+
91+
**Note:**
92+
Window feature is not available for all STM32 series.
93+
94+
Calling the `begin()` method with value outside of the valid range
95+
would return without initializing the watchdog timer.
96+
97+
**WARNING:**
98+
*Once started the IWDG timer can not be stopped. If you are
99+
planning to debug the live system, the watchdog timer may cause the
100+
system to be reset while you are stopped in the debugger. Also consider
101+
the iwatchdog timer implications if you are designing a system which puts
102+
the CPU in sleep mode.*
103+
104+
#### `void reload()`
105+
106+
The `reload()` method reloads the counter value.
107+
108+
Once you have initialized the IWDG you **HAVE** to call `reload()`
109+
periodically to prevent the CPU being reset.
110+
111+
#### `void set(uint32_t timeout, uint32_t window = IWDG_TIMEOUT_MAX)`
112+
113+
The `set()` method allows to set the timeout and window values.
114+
115+
The `timeout` and optional `window` parameters are the same than `begin()` method.
116+
117+
#### `void get(uint32_t* timeout, uint32_t* window = NULL)`
118+
119+
The `get()` method allows to get the current timeout and window values
120+
currently set.
121+
122+
The `timeout` and optional `window` pointers to get values are in microseconds.
123+
124+
#### `bool isEnabled()`
125+
126+
The `isEnabled()` method returns status of the IWDG block. If enabled or not.
127+
128+
#### `bool isReset(bool clear)`
129+
130+
The `isReset()` method checks if the system has resumed from IWDG reset.
131+
132+
The optional `clear` parameter allow to clear IWDG reset flag if true. Default: false.
133+
134+
#### `void clearReset()`
135+
136+
The `clearReset()` method clears IWDG reset flag.

‎libraries/IWatchdog/examples/IWDG_Button/IWDG_Button.ino

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/*
2+
IWatchdog + Button
3+
4+
This example code is in the public domain.
5+
6+
The code demonstrates the use of a independent watchdog timer.
7+
The watchdog timer is initialized with timeout of 10 seconds.
8+
Every time the button is pressed, the watchdog timer is reset.
9+
If left unattended the system would reset itself about every 10 seconds.
10+
11+
You would have to keep pressing the button frequently (< 10 seconds apart)
12+
to prevent the system from reseting itself.
13+
14+
You would recognize the reset condition when the LED blinks few times quickly.
15+
16+
This is not a practical example, in real code you would reset the watchdog
17+
timer in the main loop without requiring user input.
18+
19+
The code is modified version of the code from:
20+
http://www.arduino.cc/en/Tutorial/Button
21+
*/
22+
23+
#include <IWatchdog.h>
24+
25+
#ifdef USER_BTN
26+
const int buttonPin = USER_BTN;
27+
#else
28+
const int buttonPin = 2;
29+
#endif
30+
31+
#ifdef LED_BUILTIN
32+
const int ledPin = LED_BUILTIN;
33+
#else
34+
const int ledPin = 13;
35+
#endif
36+
37+
static int default_buttonState = LOW;
38+
39+
void setup() {
40+
pinMode(ledPin, OUTPUT);
41+
pinMode(buttonPin, INPUT);
42+
43+
if (IWatchdog.isReset(true)) {
44+
// LED blinks to indicate reset
45+
for (uint8_t idx = 0; idx < 5; idx++) {
46+
digitalWrite(ledPin, HIGH);
47+
delay(100);
48+
digitalWrite(ledPin, LOW);
49+
delay(100);
50+
}
51+
}
52+
53+
// Read default state of the pushbutton
54+
default_buttonState = digitalRead(buttonPin);
55+
56+
// Init the watchdog timer with 10 seconds timeout
57+
IWatchdog.begin(10000000);
58+
// or with a 2 seconds window
59+
// IWatchdog.begin(10000000, 2000000);
60+
61+
if (!IWatchdog.isEnabled()) {
62+
// LED blinks indefinitely
63+
while (1) {
64+
digitalWrite(ledPin, HIGH);
65+
delay(500);
66+
digitalWrite(ledPin, LOW);
67+
delay(500);
68+
}
69+
}
70+
}
71+
72+
void loop() {
73+
// Compare current button state of the pushbutton value:
74+
if (digitalRead(buttonPin) == default_buttonState) {
75+
digitalWrite(ledPin, LOW);
76+
} else {
77+
digitalWrite(ledPin, HIGH);
78+
79+
// Uncomment to change timeout value to 6 seconds
80+
//IWatchdog.set(6000000);
81+
82+
// Reload the watchdog only when the button is pressed
83+
IWatchdog.reload();
84+
}
85+
}

‎libraries/IWatchdog/keywords.txt

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#######################################
2+
# Syntax Coloring Map For IWatchdog
3+
#######################################
4+
5+
#######################################
6+
# Datatypes (KEYWORD1)
7+
#######################################
8+
9+
IWatchdog KEYWORD1
10+
11+
#######################################
12+
# Methods and Functions (KEYWORD2)
13+
#######################################
14+
15+
begin KEYWORD2
16+
set KEYWORD2
17+
get KEYWORD2
18+
reload KEYWORD2
19+
isEnabled KEYWORD2
20+
isReset KEYWORD2
21+
clearReset KEYWORD2
22+
23+
#######################################
24+
# Constants (LITERAL1)
25+
#######################################
26+
27+
IWDG_TIMEOUT_MIN LITERAL1
28+
IWDG_TIMEOUT_MAX LITERAL1
29+
IS_IWDG_TIMEOUT LITERAL1

‎libraries/IWatchdog/library.properties

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name=IWatchdog
2+
version=1.0.0
3+
author=Venelin Efremov, Frederic Pillon
4+
maintainer=stm32duino
5+
sentence=Enables support for independent watchdog (IWDG) hardware on STM32 processors.
6+
paragraph=Independent watchdog (IWDG) is a hardware timer on the chip which would generate a reset condition if the time is not reloaded withing the specified time. It is generally used in production systems to reset the system if the CPU becomes "stuck".
7+
category=Timing
8+
url=
9+
architectures=stm32

0 commit comments

Comments
 (0)