feature: Update documentation.

Author: eleonel

docs/API.md

@@ -22,6 +22,7 @@ WebScreen exposes a comprehensive set of functions to JavaScript applications ru
   "display": {
     "brightness": 200
   },
+  "timezone": "EST5EDT,M3.2.0,M11.1.0",
   "script": "my_app.js"
 }
 ```
@@ -86,6 +87,56 @@ The following functions are available in your JavaScript applications:
 - **wifi_get_ip()**  
   Returns the local IP address as a string.
 
+### NTP Time Functions
+
+Time is automatically synchronized via NTP when the device connects to WiFi. The timezone is configured in `webscreen.json` using a POSIX TZ string (see the WebScreen Admin tool for a full dropdown of all timezones).
+
+- **ntp_synced()**
+  Returns `true` if NTP time has been synchronized, `false` otherwise. Always check this before using other time functions.
+  ```javascript
+  if (ntp_synced()) {
+    print("Time is available");
+  }
+  ```
+
+- **get_hours()**
+  Returns the current hour (0-23) in the configured timezone, or -1 if NTP is not synced.
+
+- **get_minutes()**
+  Returns the current minute (0-59), or -1 if NTP is not synced.
+
+- **get_seconds()**
+  Returns the current second (0-59), or -1 if NTP is not synced.
+
+- **get_year()**
+  Returns the current year (e.g. 2026), or -1 if NTP is not synced.
+
+- **get_month()**
+  Returns the current month (1-12), or -1 if NTP is not synced.
+
+- **get_day()**
+  Returns the current day of the month (1-31), or -1 if NTP is not synced.
+
+- **get_weekday()**
+  Returns the day of the week (0=Sunday, 6=Saturday), or -1 if NTP is not synced.
+
+- **get_epoch()**
+  Returns the current Unix timestamp in seconds, or -1 if time is not valid (before 2021).
+
+**Example: Simple Clock**
+```javascript
+// Wait for NTP sync
+if (wifi_status() && ntp_synced()) {
+  let h = get_hours();
+  let m = get_minutes();
+  let s = get_seconds();
+  let time_str = numberToString(h) + ":" +
+                 (m < 10 ? "0" : "") + numberToString(m) + ":" +
+                 (s < 10 ? "0" : "") + numberToString(s);
+  set_text(time_label, time_str);
+}
+```
+
 ### HTTP Functions
 
 - **http_get(url)**

docs/SerialCommands.md

@@ -61,6 +61,8 @@ WebScreen> /help
 /ping <host>             - Test network connectivity
 /backup [save|restore]   - Backup/restore configuration
 /brightness <0-255>      - Set display brightness
+/time                    - Show current device time
+/settime <epoch> [tz]    - Set device time from epoch
 /monitor [cpu|mem|net]   - Live system monitoring
 /reboot                  - Restart the device
 
@@ -368,6 +370,60 @@ Live Monitor - Press any key to stop
 - Debug WiFi connectivity issues
 - Performance profiling during development
 
+### Time Commands
+
+#### `/time`
+Displays the current device time, epoch timestamp, and day of week. Time is sourced from NTP (Network Time Protocol) and requires a WiFi connection for initial synchronization.
+
+**Usage:**
+```
+WebScreen> /time
+Current time: 2026-02-17 14:23:45
+Epoch: 1771337025
+Day of week: 2 (0=Sun)
+```
+
+**Notes:**
+- Returns an error if NTP has not synced yet
+- Time is displayed in the device's configured timezone
+- NTP automatically syncs when WiFi connects (server: `pool.ntp.org` by default)
+
+#### `/settime <epoch> [timezone]`
+Manually sets the device time from a Unix epoch timestamp, with an optional POSIX timezone string.
+
+**Usage:**
+```
+WebScreen> /settime 1771337025
+Time set: 2026-02-17 14:23:45
+
+WebScreen> /settime 1771337025 EST5EDT,M3.2.0,M11.1.0
+Time set: 2026-02-17 09:23:45
+```
+
+**Parameters:**
+- `epoch` - Unix timestamp in seconds (must be after 2021-01-01)
+- `timezone` - Optional POSIX TZ string that sets the device timezone
+
+**POSIX TZ String Examples:**
+| Location | POSIX TZ String |
+|---|---|
+| UTC | `UTC0` |
+| US Eastern | `EST5EDT,M3.2.0,M11.1.0` |
+| US Pacific | `PST8PDT,M3.2.0,M11.1.0` |
+| Buenos Aires | `<-03>3` |
+| Tokyo | `JST-9` |
+| London | `GMT0BST,M3.5.0/1,M10.5.0` |
+| Berlin | `CET-1CEST,M3.5.0,M10.5.0/3` |
+
+**Notes:**
+- The WebScreen Admin tool provides a timezone dropdown that maps IANA names to POSIX TZ strings automatically
+- Full POSIX TZ database: https://github.com/nayarsystems/posix_tz_db
+
+**Use Cases:**
+- Set time when WiFi/NTP is not available
+- Override timezone from the serial console
+- Used by the WebScreen Admin tool's "Sync Time to Device" feature
+
 ### Configuration Management
 
 #### `/config get <key>`