Skip to content
Spectoda Documentation

How to check free RAM on a controller

A practical Studio workflow for checking TNGL project size and remaining free RAM in an ESP Controller through USB serial.

What this workflow shows

Section titled “What this workflow shows”

During diagnostics, watch two different values:

  • Parsed TNGL Bytes length = the size of the compiled TNGL bytecode that Studio sends to the Controller
  • HEAP = how much free internal RAM the Controller currently has available

These values are related, but they are not the same:

  • TNGL bytes describe the size of the resulting project bytecode
  • HEAP describes the runtime memory reserve still available on the Controller

If you only need to know the project size, watch Parsed TNGL Bytes length. If you need to know whether the Controller is approaching a memory limit, focus mainly on HEAP, WM and LB.

The key practical rule:

  • Parsed TNGL Bytes length cannot be used directly to calculate how much RAM the Controller consumes on the heap

One value describes the resulting bytecode size; the other shows currently free runtime memory. There is no simple 1:1 conversion between them.

Section titled “Recommended Controller config settings”

For diagnostics, it is usually enough to enable debug output and keep the standard serial workflow:

{
  "console": {
    "debug": 3
  },
  "serial": {
    "debug": true,
    "baudrate": 1500000
  }
}

Practical meaning of these fields:

  • console.debug: 3 enables the INFO log level
  • serial.debug: true sends debug output into the serial workflow
  • serial.baudrate: 1500000 is the currently verified speed used for this smoke-tested workflow
  • serial.enable does not need to be set explicitly because the standard default setup usually keeps the serial workflow enabled

Step-by-step workflow

Section titled “Step-by-step workflow”
  1. Connect the Controller to your computer through USB.
  2. Open Spectoda Studio in a browser that supports Web Serial.
  3. Open the browser developer console (DevTools -> Console).
  4. Connect to the Controller through the serial connector.
  5. Upload the project or keep the Controller connected for a few seconds.
  6. Watch the logs in the browser console.

What you will see in the console

Section titled “What you will see in the console”

When writing the project, you will typically see something like:

> Preprocessing TNGL code...
> Parsed TNGL Bytes length: 13938
> Reading TNGL fingerprint from Controller...

After connecting through serial debug, the Controller periodically prints memory state, for example:

[Spectoda_ESP32] HEAP: 183456, WM: 175920, LB: 124688

Firmware prints this HEAP log roughly every 10 seconds during normal operation. During an OTA update, the periodic output is temporarily paused.

How to read HEAP, WM and LB

Section titled “How to read HEAP, WM and LB”
ValueMeaningPractical reading
HEAPcurrently free internal RAMbasic information about the Controller’s current memory reserve
WMminimum free RAM since the last boota more important safety indicator showing the lowest reserve reached
LBlargest continuous free memory blockhelps reveal fragmentation even when total HEAP still looks acceptable

In practice:

  • if Parsed TNGL Bytes length grows, the project size is growing
  • if HEAP drops significantly after upload or while a scenario is running, the project or runtime logic is memory-heavy
  • if mainly WM drops, the Controller has already reached a lower reserve during operation than the current HEAP alone shows
  • if LB is much smaller than HEAP, the issue may be memory fragmentation rather than the total number of free bytes

How to tell that you are close to the limit

Section titled “How to tell that you are close to the limit”

There is no universal magic number that applies to all projects. It depends on the firmware, hardware, plugins and what Berry does at runtime.

The main warning signs are:

  • Parsed TNGL Bytes length keeps growing over time and each project change reduces the reserve
  • HEAP drops too low after project upload or continues to fall during runtime
  • WM keeps getting worse and does not stabilize
  • LB is noticeably small compared to the total HEAP
  • the Controller starts crashing, rebooting or showing errors while Berry logic runs
Section titled “Recommended diagnostic workflow”

To check whether a project is still safely within limits:

  1. write down Parsed TNGL Bytes length after upload
  2. watch several HEAP log cycles
  3. run a typical scenario that stresses the project in practice
  4. compare how HEAP, WM and LB changed

If the values stabilize with enough reserve, the project is probably still in a reasonable operating range. If they keep getting worse, simplify the Berry logic, reduce allocations or split the project.

After diagnostics

Section titled “After diagnostics”

Keep debug mode enabled only for the measurement and diagnostics period. For normal operation, reduce logging again so the serial workflow stays readable and is not flooded with unnecessary debug output.

Section titled “Related pages”