To keep running normally, obnizOS reconnects or restarts at the following times.
Input Wait Timeout
If the device starts waiting for user input after startup, it times out after 30 seconds without any input and restarts. So even after an unexpected power cut, such as a power failure, the device does not stay stuck waiting for input.
Error Detection and Watchdogs
obnizOS monitors itself on three levels. Each level restarts the device when it detects a problem.
| Monitor | What it watches | Time until restart |
|---|---|---|
| (1) Hardware watchdog | The CPU keeps running | About 10 seconds (ESP32) or 9 seconds (ESP32-C3, ESP32-C6) |
| (2) Task monitor (FreeRTOS) | Tasks and interrupts are not stuck | 300 ms for an interrupt. A stuck task leads to a restart by (1). |
| (3) Communication monitor | The device keeps communicating with the server | 3 minutes online, 10 minutes when not connected |
(1) Hardware Watchdog
This is the watchdog timer built into the chip. It resets the chip when it is not fed for about 10 seconds on ESP32, or 9 seconds on ESP32-C3 and ESP32-C6.
obnizOS feeds it once per second from a dedicated task. When the CPU freezes and the feeding stops, the chip resets.
(2) Task Monitor (FreeRTOS)
obnizOS runs on FreeRTOS, and the ESP-IDF watchdogs check that tasks and interrupts are not stuck.
- When an interrupt does not finish within 300 ms, the system stops with an error (panic) and restarts.
- When a task keeps the CPU busy and other tasks cannot run, the task that feeds (1) also stops. The hardware watchdog then resets the chip.
(3) Communication Monitor
When the device does not communicate with the server for a certain time, obnizOS assumes that the network or modem is stuck, logs Hang Detect. Rebooting..., and restarts the device.
| State | Time until restart without communication |
|---|---|
| Online (connected to the server) | 3 minutes |
Not connected (offline, connecting, or disconnected with cloud.disconnect()) |
10 minutes |
- While online, every piece of data received from the server resets the timer, so it does not expire during normal operation. When nothing is received for 30 seconds, obnizOS sends a ping. When no reply arrives within 30 seconds (120 seconds on cellular), it closes the connection and reconnects. So a broken connection is usually detected well before the 3-minute limit.
- When a Lua plugin keeps the device offline on purpose, call
wdt.feed()at least once every 10 minutes to reset the timer. See Watchdog. - The same task that feeds (1) checks this timer. If that task stops, (1) resets the device.
External MCU (obniz Board 1Y)
obniz Board 1Y is also monitored by an external MCU. When needed, the external MCU resets the whole ESP32.
After a Restart by a Watchdog
The device restarts automatically, so no manual operation is needed to bring it back.
- A restart by (1) the hardware watchdog or by an error (panic) in (2) starts the device in Safe Mode. In Safe Mode, the Lua plugin is not loaded, and the device only tries to connect to the cloud. Safe Mode continues until the next restart. See Safe Mode for how to detect it from obniz.js and how to return to normal mode.
- A restart by (3) the communication monitor is a normal restart. The device starts in normal mode, and the Lua plugin runs.