Differences

This shows you the differences between two versions of the page.

--- blocks:drivers:troubleshooting [2018-01-12 19:54]
admin created
+++ blocks:drivers:troubleshooting [2024-10-25 06:00] (current)
admin Bad link
@@ Line 1: / Line 1: @@
-===== Troubleshooting =====
+====== Troubleshooting ======
+This article provides some pointers on what to do when a driver doesn't work at all, or doesn't perform as expected. It's primarily written for driver developers, but may be useful also in other cases when you're just trying to use an existing driver.
-==== Driver Script Errors ====
+===== Loading Errors =====
-====  Runtime Errors ====
+There may be syntax errors, or other fatal errors, that stop your driver from getting off the ground. While the TypeScript language, compiler and associated development tools, help you out with avoiding and fixing many errors, such errors can still occur in ways that are undetected by the development tools.
-====  Logging ====
+:!: You're strongly advised to test a new driver on your local computer before deploying it to a production Blocks server. A poorly written driver can cause the server to misbehave, and may affect the performance of other functions in Blocks.
+If a driver doesn't work at all, check the log file of the computer running Blocks. This file is located here, under the home directory of the user under which Blocks is running:
+	PIXILAB-Blocks-root/logs/latest.log
+Open a terminal window ("Terminal" on MacOS or Linux and "Powershell" on Windows). Use the //cd// command to move into the "logs" directory mentioned above. Then type the following command on MacOS:
+	tail -20 -f latest.log
+Or, under Windows Powershell:
+	Get-Content latest.log –Wait
+This shows the last few lines of the log file, which may reveal any errors encountered loading the driver.
+===== Runtime Errors =====
+The driver may load OK, but yet malfunction at some point. Here too, the log file is your best friend. Keep a close eye on the log file while using the driver to see if any errors appear related to the driver.
+In some cases, errors may be triggered by data received from the device being controlled. Hence, you may need to exercise all functions of the driver to see if any errors occur.
+=====  Writing Log Messages =====
+While developing a driver, you may want to display its internal state to see how it's behaving. You can use any of the standard //console.log// style functions to do so, as defined in the //system/PIXI.d.ts// file.
+:!: In order to see the output of //log, info// or //warn//, you must increase the log level, as described below.
+<code>
+/** Log functions take one or many values, which will be concatenated
+    with a space as separator.
+ */
+interface console {
+  log(...toLog: string[]):void;    // Synonymous with info
+  info(...toLog: string[]):void;    // Log as info message
+  error(...toLog: string[]):void;    // Log as error message
+  warn(...toLog: string[]):void;    // Log as warning message
+}
+</code>
+:!: You may want to remove, or comment out, any logging calls in your driver once you get it working. This avoids unwanted noise in the log file, and may slightly improve the performance of your driver.
+==== Increasing the Log Level ====
+Most troubleshooting methods involve viewing Blocks log file. By default, this log file contains only errors encountered while running Blocks. In some cases, you may want to increase the verbosity of the logging. This can be done by adding the following lines to a file named //config.yml//, located in the //PIXILAB-Blocks-root// directory in the home directory of the current user:
+<code>
+# Logging verbosity level. Specify one of ERROR, WARN, INFO
+logging:
+  loggers:
+    Script: INFO  # Verbose logging for scripts/drivers
+</code>
+If the file doesn't exist, create it using a plain text editor. Copy and paste the code above into the file The default value for the verbosity is ERROR, which logs only errors. For more details, change this to //WARN// to also include warnings, or to //INFO// for miscellaneous information, including logging you do using any //console.log// statements in your driver. Restart the Blocks server after making any changes to the config.yml file.
+:!: Setting the logging level to INFO may write lots of details to the log file. While you may want it set to INFO while developing drivers, or to troubleshoot other issues, you should set it back to WARN or ERROR for normal use of Blocks.
+===== Viewing the Log Remotely =====
+While a separate development computer is preferable for driver development, you may sometimes run into issues with a production server, requiring you to access its log file. If so, you can either access the server locally, viewing the log file as described above. Or you can access the log file remotely, as described [[blocks:server:advanced_server_configuration#viewing_logs_in_webmin|here]].
+==== Archived Log Files ====
+If you want to investigate an error that occurred some time ago, the information may no longer be in the //latest.log// file. If so, Blocks keep an archive of recent log files next to the //latest.log// file. Those files are compressed. Transfer the log file to a separate computer, unpack it, and view it there using a plain text editor.
+===== Reloading Changes Automatically =====
+When you change drivers, you must normally restart Blocks for those changes to take effect. As this can make the development more time consuming, an alternative is to enable automatic reloading of scripts. This is also done in the //config.yml// file mentioned above, by adding the following lines:
+<code>
+scripting:
+  watchFiles: true
+</code>
+Remember to restart Blocks after changing the //config.yml// file to make it take effect.