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.

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.

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.

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.

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.

/** 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
}

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.

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:

# Logging verbosity level. Specify one of ERROR, WARN, INFO
logging:
  loggers:
    Script: INFO  # Verbose logging for scripts/drivers

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.

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 here.

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.

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:

scripting:
  watchFiles: true

Remember to restart Blocks after changing the config.yml file to make it take effect.