Debugging and Troubleshooting

Debugging and Troubleshooting

This page collects common issues, debugging tools, and configuration tips.

Common issues and solutions

Feature not loading

Symptoms:

• Feature doesn't appear in HA configuration options.

Things to check:

• AVAILABLE_FEATURES registration in const.py
• feature factory function exists and imports correctly
• HA logs for import/initialization errors
• feature folder structure is correct

Entities not created

Symptoms:

• Feature is enabled but no entities appear.

Things to check:

• feature enabled + device selected in the options flow
• SimpleEntityManager logs for entity creation/removal issues
• device discovery is working

JavaScript cards not loading

Symptoms:

• Card doesn’t appear, or you see errors in the UI.

Things to check:

• asset deployment completed successfully
• files exist under config/www/ramses_extras/
• browser console for JS errors
• feature is UI-enabled
• hard refresh your browser cache

If the browser console shows 404s like:

• /local/ramses_extras/v0.13.1/helpers/main.js

Then Home Assistant still has a legacy Lovelace resource entry pointing to an old, versioned URL. Remove any /local/ramses_extras/v... entries and add the stable bootstrap resource (type: module):

• /local/ramses_extras/helpers/main.js?v=<version>

Also restart HA and your hard-reload your browser

WebSocket command failures

Symptoms:

• WebSocket commands return errors or time out.

Things to check:

• command handler is registered during setup
• required parameters are present and valid
• device_id exists and is formatted correctly
• HA logs for WebSocket-related errors

Performance issues

Symptoms:

• Slow entity changes, high memory usage, laggy UI.

Things to try:

• use bulk operations for entity changes where supported
• cache frequently accessed data
• reduce UI update frequency where appropriate

Debug tools

SimpleEntityManager

• Use validation on startup to troubleshoot missing/extra entities.
• Inspect logs around entity creation/removal.
• Confirm the device feature matrix state is what you expect.

WebSocket testing

• Use callWebSocket() in browser console to test commands.

Message listener debug

• Inspect registered listeners via RamsesMessageBroker helper methods.

RamsesBaseCard debug logging

Frontend debug output can be enabled via:

window.ramsesExtras = window.ramsesExtras || {};
window.ramsesExtras.debug = true;

This flag is normally driven by integration options and pushed via the ramses_extras_options_updated event.

Working debug tool examples

SimpleEntityManager validation (Python)

entity_manager = SimpleEntityManager(hass)
await entity_manager.validate_entities_on_startup()

WebSocket testing (browser console)

const result = await callWebSocket(hass, {
  type: 'ramses_extras/default/get_bound_rem',
  device_id: '32:153289'
});
console.log(result);

Debug configuration

Debug configuration

Logging configuration

Enable detailed logging in Home Assistant configuration:

# configuration.yaml
logger:
  default: info
  logs:
    custom_components.ramses_extras: debug
    custom_components.ramses_extras.framework: debug
    custom_components.ramses_extras.features: debug

Integration advanced settings

Note: For complete advanced settings and configuration options, see Advanced Settings.

Ramses Extras provides integration-level settings (via the options flow) that affect both backend and frontend debugging:

• debug_mode

  • Stored in the config entry options for legacy compatibility
  • Derived from frontend_log_level == "debug"
  • Exposed to the frontend as window.ramsesExtras.debug

• frontend_log_level

  • Stored in the config entry options
  • Exposed to the frontend as window.ramsesExtras.frontendLogLevel
  • Controls browser console logging for Ramses Extras cards/editors (frontend)

• log_level

  • Stored in the config entry options
  • Applied at runtime to the integration logger custom_components.ramses_extras

These settings are pushed to the frontend via the HA event ramses_extras_options_updated.

Relationship to Home Assistant "Debug Logging"

Home Assistant has a built-in logging system (configured via the logger: section in YAML, or via enabling debug logging for specific integrations). That mechanism controls backend Python logging and is the authoritative way to get full server-side debug output.

Ramses Extras also has integration options that are related but distinct:

• debug_mode (Ramses Extras option)

  • Legacy boolean for frontend verbosity and is exposed as window.ramsesExtras.debug.
  • Derived from frontend_log_level.
  • Does not automatically change Home Assistant logger configuration.

• frontend_log_level (Ramses Extras option)

  • Controls frontend verbosity (e.g. RamsesBaseCard console logging) and is exposed as window.ramsesExtras.frontendLogLevel.

• log_level (Ramses Extras option)

  • Adjusts the runtime log level for custom_components.ramses_extras.
  • This is a convenience for the integration but is still separate from HA's global logger: config.

In practice:

• Use HA logger: / integration debug logging when you need backend diagnostics.
• Use frontend_log_level when you need frontend diagnostics (cards/editors).

Debug tools summary

1. SimpleEntityManager Debug: Use validate_entities_on_startup() to check entity consistency
2. WebSocket Testing: Use callWebSocket() function to test WebSocket commands
3. Message Listener Debug: Use RamsesMessageBroker.instance.getListenerInfo() for message routing
4. Device Enumeration Debug: Check logs for device enumeration and handler execution
5. ha-sim Test Tool: Run python -m tools.ha_sim_test from the ramses_extras repo for automated end-to-end testing on the ha-sim container. See HA-Sim Test Tool for details. Generates log + summary reports in ~/.local/share/ramses_extras/ha_sim_reports/. Back to: Home Prev: Development Guide Next: API Reference