Update user manual

Document scripts puzzle-passwd and puzzle-ntpcfg.
Document command REALTIME?.

doc/user_manual.md

@@ -211,7 +211,20 @@ to open the USB serial port of the Red Pitaya.
 Set the baud rate to 115200 bps, character format to `8N1`.
 
 Press Enter to get a login prompt on the console.
-Use login `root` with password `root`.
+
+Login as user `root`.
+The default password is `root`.
+
+### Changing the password
+
+The default login password is `root`, but this can be changed.
+
+To change the password, login on the console and run the command `puzzle-passwd`.
+The tool will prompt to type a new root password.
+The changed password will be persistently stored on the SD card.
+
+Do not use the normal Unix command `passwd`.
+This tool does not write the new password to the SD card; therefore the changes will be forgotten after reboot.
 
 
 ## Network access
@@ -241,16 +254,47 @@ This is the same host name as used by the official Red Pitaya software.
 It is possible to run an SSH server on the Red Pitaya.
 This can be used to remotely log in on the Linux system.
 
-To login via SSH, use username `root` with password `root`.
+To login via SSH, use username `root` and the same password used for logging in via the USB console.
 
-For security reasons, the SSH server is disabled by default.
+The default password is `root`.
+It is recommended to change the password before enabling SSH access.
 An SSH server with an easy-to-guess password should never be connected to an untrusted network.
 
-If you want to use the SSH server, you have to enable it explicitly.
+For security reasons, the SSH server is disabled by default.
-To enable the SSH server, login on the USB console as described above.
+If you want to login via SSH, it must be enabled explicitly.
-Then run the following command: `puzzle-sshcfg enable` .
+Use the following steps to enable the SSH server:
-Finally, run `reboot` to reboot the Red Pitaya.
+
+ - Login on the USB console as described above.
+ - Set a safe password by running command: `puzzle-passwd`
+ - Enable the SSH server by running command: `puzzle-sshcfg enable`
+ - Reboot the Red Pitaya by running command: `reboot`
+
 From this point onward, the SSH server will be started automatically during boot.
+You can again use the command `puzzle-sshcfg` to disable SSH access.
+
+### NTP configuration
+
+Optionally, an NTP server may be configured to synchronize the system clock via the network.
+Without an NTP server, the system clock of the Red Pitaya is initialized to the year 1970 on power-on.
+
+The only feature that uses the system clock is the remote control command `REALTIME?` .
+If this command is used, configuring an NTP server is necessary to get correct results.
+If this command is not used, synchronizing the system clock is not important.
+
+To configure an NTP server, use the following steps:
+
+ - Login on the Red Pitaya via USB console or SSH as described above.
+ - Run the command `puzzle-ntpcfg server <IP-address>` .
+
+This command configures Chrony to synchronize to the specified NTP server.
+The configuration is also written to the SD card and used during boot.
+
+Optionally, a poll interval can be specified as a power of 2 in seconds.
+For example: `puzzle-ntpcfg server <IP-address> poll 5` specifies a poll interval of 32 seconds.
+
+Sub-millisecond accuracy can be achieved with an NTP server in the local network and `poll 0` (poll each second).
+Poll intervals shorter than 64 seconds must only be used with a dedicated NTP server in the local network.
+Using such short poll intervals with a public NTP server is considered abuse.
 
 
 ## Data stream protocol
@@ -330,6 +374,7 @@ In the response string, such data elements are separated by space characters.
 | `*IDN?`                   | Instrument identification. |
 | `RESET`                   | Restore default settings. |
 | `TIMESTAMP?`              | Timestamp counter. |
+| `REALTIME?`               | System time and timestamp counter. |
 | `AIN:CHANNELS:COUNT?`     | Number of input channels. |
 | `AIN:CHANNELS:ACTIVE`     | Number of active input channels. |
 | `AIN:CHn:RANGE`           | Analog input range. |
@@ -391,6 +436,23 @@ Any ongoing analog acquisition is stopped.
 Query: `TIMESTAMP?` <br>
 Response: decimal integer, representing the current timestamp in units of 8 ns.
 
+### `REALTIME?`
+
+Query: `REALTIME?` <br>
+Response: system time and firmware timestamp, separated by a space character.
+
+The system time is represented as a floating point number denoting the number of seconds since 1970-01-01 00:00 UTC (ignoring leap seconds).
+
+The firmware timestamp is represented as a decimal integer denoting the current timestamp in units of 8 ns.
+
+This command is only useful if the Red Pitaya is configured to synchronize its system clock via NTP.
+Without NTP, the system time of the Red Pitaya will be incorrect and essentially meaningless.
+
+The system time and firmware timestamp are captured nearly simultaneous, but not exactly simultaneous.
+The mismatch between these two time values is almost always less than 10 microseconds.
+The overall accuracy of the system time is limited by the synchronization via NTP.
+In practice, sub-millisecond accuracy is possible with an NTP server in the local network.
+
 ### `AIN:CHANNELS:COUNT?`
 
 Query: `AIN:CHANNELS:COUNT?` <br>