Skip to content

Ramses Debugger

Jump to bottom
Willem edited this page Oct 15, 2026 · 5 revisions

Ramses Debugger

Diagnostic and observability tools for troubleshooting your ventilation system.

Overview

The Ramses Debugger provides real-time insight into your FAN system, RF traffic, and Ramses Extras internal state. Use it to diagnose issues, verify configuration, and understand how components interact.

Cards Provided

The Ramses Debugger feature includes four diagnostic cards:

1. Ramses Traffic Analyser

Spreadsheet-like view of RF communications between devices:

  • Real-time traffic matrix – Shows message flow between all devices
  • Aggregated statistics – Total packets, verbs, codes per flow
  • Live updates – Subscribes to traffic for continuous monitoring
  • Filtering – Filter by device, code, or verb

2. Ramses Log Explorer

Browse and search Home Assistant log files:

  • Log file listing – Available log files in your HA instance
  • Tail viewing – View recent log entries
  • Search functionality – Find specific patterns or errors
  • Context extraction – Get relevant log sections for troubleshooting
  • Log upload – Upload new log files to the ramses logs folder for processing and database inclusion

3. Ramses Packet Log Explorer

Explore the ramses packet/message log file:

  • Packet log access – Read the ramses packet log directly
  • Message parsing – View decoded packet information
  • Timeline view – See packet sequence and timing

4. Ramses Humidity Diagnostics

Detect where the FAN's reported "outdoor" relative humidity is actually measured — on the untreated outdoor air, or in the supply duct after the heat exchanger/bypass (as seen on Orcon and ClimaRad units). This decides which temperature the outdoor absolute humidity must be paired with.

How to use:

  1. Configure the card with your device_id.
  2. Run the fan on High with the bypass open for ~15 minutes — the card has Fan HIGH + Bypass open and Restore buttons, or do it manually.
  3. Click Analyze to inspect recorder history for the window.
  4. The result shows which temperature pairing keeps the dewpoint most stable (supply vs outdoor), the supporting numbers, and the recommended Sensor Control setting. If the supply pairing wins, an Apply now button can set outdoor absolute humidity → Internal (from FAN's supply flow) directly.

See Sensor Control for background on the sensor-placement issue.

WebSocket Commands

The Ramses Debugger provides these WebSocket commands:

Traffic Commands

  • traffic_get_stats – Get traffic statistics and flow data
  • traffic_reset_stats – Clear all traffic counters
  • traffic_subscribe_stats – Subscribe to live traffic updates

Log Commands

  • log_list_files – List available log files
  • log_get_tail – Get recent entries from a log file
  • log_search – Search within log files

Packet Log Commands

  • packet_log_list_files – List available packet log files
  • packet_log_get_messages – Get messages from packet log

Cache Commands

  • cache_get_stats – Get debugger cache statistics
  • cache_clear – Clear the debugger cache

Config Commands

  • config_export – Export configuration as YAML
  • config_diagnostics – Get configuration diagnostics
  • config_import – Import configuration (with validation)

Adding the Debugger Cards

To Your Dashboard

Add each card separately:

# Traffic Analyser
type: custom:ramses-traffic-analyser

# Log Explorer
type: custom:ramses-log-explorer

# Packet Log Explorer
type: custom:ramses-packet-log-explorer

Or add via UI:

  1. Edit dashboard
  2. Add card → Search for "Ramses" to see all debugger cards

Common Diagnostic Tasks

"Is my FAN responding?"

  1. Open the Ramses Traffic Analyser
  2. Look for traffic flows from your FAN device ID
  3. Check packet counts and timestamps
  4. Use traffic_get_stats to get detailed flow information

"Why isn't my REM working?"

  1. Check Traffic Analyser – Is the REM sending packets?
  2. Look for flows between REM and FAN devices
  3. Check if packets are one-way only (possible binding issue)
  4. Use Log Explorer to search for REM-related errors

"What's happening in the logs?"

  1. Open Ramses Log Explorer
  2. Search for device IDs or error messages
  3. Use tail view to see recent activity
  4. Filter by log level or time range

"I have a new log file to analyze"

  1. Upload your log file to the ramses logs folder
  2. The file will be automatically processed and included in the database
  3. Once processed, the log file will appear in the Ramses Log Explorer file listing
  4. You can then search, tail, and analyze the uploaded log using the standard log explorer features

"What packets were exchanged?"

  1. Open Ramses Packet Log Explorer
  2. Browse the packet timeline
  3. Filter by device or command code
  4. See decoded packet contents and timestamps

WebSocket Commands Reference

Traffic Commands

Command Purpose
ramses_extras/ramses_debugger/traffic/get_stats Get traffic statistics
ramses_extras/ramses_debugger/traffic/reset_stats Reset traffic counters
ramses_extras/ramses_debugger/traffic/subscribe_stats Subscribe to live updates

Log Commands

Command Purpose
ramses_extras/ramses_debugger/log/list_files List available log files
ramses_extras/ramses_debugger/log/get_tail Get recent log entries
ramses_extras/ramses_debugger/log/search Search in logs

Packet Log Commands

Command Purpose
ramses_extras/ramses_debugger/packet_log/list_files List packet log files
ramses_extras/ramses_debugger/packet_log/get_messages Get packet messages

Cache Commands

Command Purpose
ramses_extras/ramses_debugger/cache/get_stats Get cache statistics
ramses_extras/ramses_debugger/cache/clear Clear cache

Config Commands

Command Purpose
ramses_extras/ramses_debugger/config/export Export configuration
ramses_extras/ramses_debugger/config/diagnostics Get config diagnostics
ramses_extras/ramses_debugger/config/import Import configuration

Traffic Statistics

The Traffic Collector tracks RF traffic metrics:

  • Flows – Unique (src, dst) pairs observed
  • Total count – All packets processed
  • By code – Count of each Ramses command code
  • By verb – Count of each message verb (RQ/RP/I)
  • Per-flow details – Last seen, verbs, codes for each flow

The collector maintains:

  • Flow limits – Maximum unique flows tracked (default 2000)
  • Message buffer – Recent messages for query
  • Subscription support – Live updates to subscribers

View with:

{
  "type": "ramses_extras/ramses_debugger/traffic/get_stats"
}

Reset with:

{
  "type": "ramses_extras/ramses_debugger/traffic/reset_stats"
}

Performance Notes

  • Traffic logging has minimal overhead
  • Statistics collection is always active
  • Debugger card updates in real-time via WebSocket
  • No impact on RF network performance

Troubleshooting the Debugger Itself

"Debugger card doesn't load"

  • Verify Ramses Extras is properly loaded
  • Check browser console for JavaScript errors
  • Clear browser cache and reload

"Commands return no data"

  • Verify Ramses Extras is configured
  • Check that feature is enabled for the device
  • Review Home Assistant logs for errors

"Traffic log is empty"

  • Verify ramses_cc is receiving RF traffic
  • Check that FAN/REM devices are powered on
  • Look at ramses_cc logs directly: /config/ramses_log
  • Ensure TrafficCollector is started (check HA logs)

Related Documentation

Back to: Home | Prev: HVAC Fan Card | Next: Hello World

Ramses Extras Wiki

Features

Misc

Architecture

Reference

Clone this wiki locally