Debugging & Troubleshooting

No program works flawlessly on the first attempt. Debugging is an essential part of working with Coldwave Script. The language provides simple but effective tools for this: PRINT for output, clear runtime error messages from the VM, and systematic debugging strategies.

PRINT & Logging

PRINT is primarily intended as a debugging tool in the web-based Script Editor, where programs can be executed directly and log output is shown in the editor console.

PROGRAM  
    DIM x AS INT = 5  
    PRINT "x=", x   ' Output in editor: x= 5  
END PROGRAM

On embedded devices, there is typically no direct console. PRINT may have no visible effect there or may only be used internally for diagnostics.
For persistent field logging, use Coldwave's normal telemetry and event mechanisms instead.

Guidelines:

• Use PRINT sparingly, especially inside loops.
• Mark debugging output with clear prefixes:

PRINT "[DBG] counter=", counter

Common VM Error Messages

Coldwave Script checks for typical runtime errors. An unhandled error currently causes the Script VM to stop execution entirely.
A runtime error code is reported via telemetry, which can be processed by the Coldwave backend.

Examples:

Message (Example)	Meaning	Fix
Division by zero	Denominator = 0	Check first: IF b <> 0 THEN …
Unknown symbol	Variable not defined	Declare variable using DIM
Wrong parameter type	Argument type mismatch	Convert using TO_* or change type
Block not instantiated	Block called without DIM	Always instantiate first

Recommendation: Guard critical operations (division, array access, block calls) and ensure loops always have a fixed upper bound (WCET).

Systematic Debugging Strategy

1. Reduce to minimal example — shrink program until the issue is reproducible.
2. Add PRINT statements — inspect intermediate values.
3. Check parameters — verify type and range.
4. Verify loop bounds — ensure loops terminate predictably.

Examples

Example 1: Division by Zero

PROGRAM  
    DIM a AS INT = 10  
    DIM b AS INT = 0  
    PRINT a / b ' Error: Division by zero  
END PROGRAM

Solution:

IF b <> 0 THEN  
    PRINT a / b  
ELSE  
    PRINT "Division by zero prevented"  
END IF

Example 2: Missing Block Instantiation

PROGRAM  
    TON(IN = TRUE, PT = T#1000ms) ' Error!  
END PROGRAM

Solution:

PROGRAM  
    DIM T AS TON    
    T(IN = TRUE, PT = T#1000ms)  
END PROGRAM

Checklist

• Program does not start → check for END PROGRAM.
• Values look wrong → print intermediate values.
• Look up VM error code in the table.
• Verify loops have upper bounds.
• Always instantiate blocks with DIM.

Summary

• PRINT is the primary debugging tool.
• VM error messages are clear and guide error isolation.
• Systematic debugging saves time: isolate → print → verify.
• Common issues: division by zero, missing DIM, wrong type.
• The checklist helps resolve most problems quickly.