Skip to content

Module Debugging

Jump to bottom Edit New page
Kristjan ESPERANTO edited this page Dec 21, 2024 · 7 revisions

General Debug Tips

  • Remove (or disable) all other modules (except clock) to make it start/run faster and to isolate your module under development.
  • Run your MM in server mode, allowing you to still use your RPi (or what have) in GUI mode. CPU resource utilization is also somewhat reduced in server mode.
  • To prevent unnecessary headaches, utilize automated "linters" when possible before deploying and running your code.
  • Create automated unit and integration tests to protect against unintentional breakages of working features and regression defects.

Automated Testing vs. Manual Debugging

There is a distinction between the terms "testing" and "debugging". Usually, debugging refers to manually interacting with the application to provoke and analyze its behavior in an attempt to find defects or missing requirements. Conversely, automated testing involves the creation or utilization of code which validates the syntax and function of your application.

Automated Testing & Validations

Static code analysis (commonly referred to as "linting") involves a scan and validation of your files against a set of specific set of rules - usually common violations. These scans can be conducted either with a locally installed or a website "linter".

Automated config file validation

There is already a local linter installed which can automatically check the MM configuration file. It is invoked with npm run config:check, example output below:

user@hostmachine:~/MagicMirror$ npm run config:check

> magicmirror@2.1.3 config:check /home/daddle/MagicMirror
> node tests/configs/check_config.js

Checking file...  /home/daddle/MagicMirror/config/config.js
Line 30 col 9 Expected '}' to match '{' from line 28 and instead saw 'distance'.
Line 30 col 17 Expected '}' to match '{' from line 25 and instead saw ':'.
Line 30 col 19 Expected ']' to match '[' from line 24 and instead saw 'miles'.
Line 35 col 6 Missing semicolon.
Line 35 col 5 Unrecoverable syntax error. (55% scanned).
user@hostmachine:~/MagicMirror$

Automated JS file validation

Utilize a JS linter, such as eslint.org and the ESLint on npm.

Manual Debugging

This method is tedious, time-consuming, and usually the most frustrating method of troubleshooting. As it can take several seconds and even minutes to restart your MM, it may be a bottleneck for development efficiency. Automated testing and validation are faster, cheaper, and reusable.

There are at least 2-3 methods to debugging modules:

  1. Directly on MM itself (native mode)
  2. Directly on MM itself (server mode)
  3. As a node server or on a different machine [TBA]
  • It's especially beneficial while debugging at runtime to isolate the module under development by disabling all other modules (except clock). Isolation avoids the startup and performance impact of other modules.

Server-mode debugging

  • Run your MM in server mode, allowing you to still use your RPi (or what have) in GUI mode. CPU resource utilization is also somewhat reduced in server mode.
  • To debug your JS and view console.log() output, use your browser's Developer Tools (usually activated by CTRL-SHIFT-i).

Logging

Logging Errors and Info to the "console"

It is usually unclear to first-time users what or where the "console" is. The primary reason for this is that it depends on what, where, and how the log call gets produced.

Logging From MMM-your-module.js

Although there are several variations of JS console.log() calls, to keep things as simple as possible, MM core provides a few logging wrappers that you can use in your core MMM-something.js code. These are:

Log.info('info');  # To log to stdout
Log.log('log');     # To log to stdout
Log.error('error');  # To log to stderr

By default, these log entries will go to the "browser" web console which can be accessed from the DevTools. To start MagicMirror with DevTools open, run npm start dev from the MagicMirror folder. If you wish to send these browser logs to the normal console (or PM2 Log Files), add export ELECTRON_ENABLE_LOGGING=true to the top of ~/MagicMirror/run-start.sh and restart.

Logging From node-helper.js

These are not available (AFAIK) if you are using a node_helper.js, so you'll have to use the standard JS loggers there. As mentioned, there are quite a few variations of these (and they result in varying success rates) depending on where you want the message to appear.

  • Do you want your log message to go to the Browser (DevTools) log?
  • Do you want your log message to go to the MagicMirror debug log?
    Such as in: ~/.pm2/logs/mm-error-0.log (stderr?) or ~/.pm2/logs/mm-out-0.log (stdout?), when running MM using pm2.
  • Do you want the logs to show up when running in: npm start dev?

The one logger that always seem to do the trick is:

console.error(any... data)
console.dir(any item, optional object? options)

You may also want to take a look at the MMM-Logging 3rd-party module, which will add timestamps and additional formatting to your console.error(), or console.log() calls.

Reviewing logs written to disk

Check your PM2 logs with pm2 logs mm or check the log files in their locations:

  • /home/pi/.pm2/pm2.log
  • /home/pi/.pm2/logs/mm-error-0.log
  • /home/pi/.pm2/logs/mm-out-0.log

Conclusion

There are probably many other and better ways to check and debug. So please add and edit this page or file an issue with info for improving debugging.

Further Reading

Add a custom footer
Add a custom sidebar
Clone this wiki locally