### Example qutestify.py Usage

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

This example demonstrates how to run the `qutestify.py` utility from the command line. It takes a test script file as an argument and reports the number of lines changed.

```bash
> python3 %QTOOLS%\qutest\qutestify.py test.py

QUTestestify utility 8.0.4
Copyright (c) 2005-2025 Quantum Leaps, www.state-machine.com
qutestifying: test.py
changed lines: 6.
```

--------------------------------

### QUTest Log File Example

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

This is an example of a generated QUTest log file. It shows the run ID, target, test group information, individual test results (PASS/FAIL), and a summary of the test run.

```text
Run ID    : 221221_161550
Target    : build/test_qutest.exe

===================================[group]====================================
test_assert.py

This test group contains tests that intenionally FAIL,
to exercise failure modes of the QUTest system.

[ 1]--------------------------------------------------------------------------
Expected assertion
                                                             [ PASS (  0.1s) ]
[ 2]--------------------------------------------------------------------------
Unexpected assertion (should FAIL!)
  @test_assert.py:22
exp: "0000000002 COMMAND CMD_A 0"
got: "0000000002 =ASSERT= Mod=test_qutest,Loc=100"
! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ![ FAIL (  0.2s) ]
[ 3]--------------------------------------------------------------------------
Simple passing test
                                                             [ PASS (  0.1s) ]
[ 4]--------------------------------------------------------------------------
Wrong assertion expectation (should FAIL!)
  @test_assert.py:32
exp: "0000000002 =ASSERT= Mod=test_qutest,Loc=200"
got: "0000000002 =ASSERT= Mod=test_qutest,Loc=100"
! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ![ FAIL (  1.1s) ]
[ 5]--------------------------------------------------------------------------
Simple passing test
                                                             [ PASS (  0.1s) ]

=================================[ SUMMARY ]==================================

Target ID : 221221_161031 (QP-Ver=720)
Log file  : ./qutest221221_161550.txt
Groups    : 1
Tests     : 5
Skipped   : 0
FAILED    : 2 [ 2 4 ]

==============================[ FAIL (  2.7s) ]===============================

```

--------------------------------

### Install qcalc from sources

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Installs the qcalc Python package directly from its source directory. This is useful for development or when installing a specific version not yet published to PyPI.

--------------------------------

### QView Python Script Example

Source: https://context7.com/quantumleaps/qtools/llms.txt

A basic Python script demonstrating the shebang line for a QView application. QView is a GUI tool for visualizing QS trace data.

```python
#!/usr/bin/env python

```

--------------------------------

### qcalc C-syntax expression examples

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Demonstrates various C-syntax expressions supported by qcalc, including bitwise operators, mixed number bases, integer division, and mathematical functions.

```plaintext
((0xBEEF << 16) | 1280) & ~0xFF
($1011 << 24) | (1280 >> 8) ^ 0xFFF0
(1234 % 55) + 4321//33
pi/6
pow(sin(ans),2) + pow(cos(ans),2)
```

--------------------------------

### Install qcalc using pip

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Installs the qcalc Python package from the Python Package Index (PyPI). This command makes the 'qcalc' command-line tool available system-wide.

```bash
pip install qcalc
```

--------------------------------

### Run installed qcalc command

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Invokes the qcalc calculator after it has been installed using pip or setup.py. This provides a convenient command-line interface for the calculator.

--------------------------------

### Generate QUTest Logs with make

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

This section explains how to generate QUTest log files using the `make` command. The `LOG=` symbol is used to specify the directory for the log files. Examples are provided for different directory specifications.

```makefile
[1] make LOG=.
[2] make LOG=../log
[3] make LOG=c:/cert/logs
```

--------------------------------

### Start QSPY Host Application for Real-Time Tracing

Source: https://context7.com/quantumleaps/qtools/llms.txt

QSPY is the foundational host-side utility for receiving, parsing, and displaying real-time software tracing data from embedded targets. It supports various connection types (serial, UDP) and output formats (text, binary, MATLAB, sequence diagrams).

```bash
# Start QSPY listening on a serial port (Windows)
qspy -c COM3 -b 115200

# Start QSPY listening on a serial port (Linux/macOS)
qspy -c /dev/ttyUSB0 -b 115200

# Start QSPY with UDP connection for embedded target
qspy -u 192.168.1.100 -p 6601

# Start QSPY with dictionary file and save output
qspy -c COM3 -b 115200 -d my_project.dic -o trace_output.txt

# Start QSPY and generate MATLAB output
qspy -c COM3 -b 115200 -m matlab_data.mat

# Start QSPY and generate sequence diagram output
qspy -c COM3 -b 115200 -s sequence.seq
```

--------------------------------

### Interactive Calculator REPL with Python

Source: https://context7.com/quantumleaps/qtools/llms.txt

Starts an interactive Read-Eval-Print Loop (REPL) for the qcalc calculator using Python. Allows for direct input of expressions, including hexadecimal, binary, and mathematical functions, with results displayed in multiple formats.

```python
python qcalc.py
> 0xFF + 1
= 256 | 0x0000'0100 | 0b00000000'00000000'00000001'00000000
> (1 << 16) - 1
= 65535 | 0x0000'FFFF | 0b00000000'00000000'11111111'11111111
> 0xDEADBEEF
= 3735928559 | 0xDEAD'BEEF | 0b11011110'10101101'10111110'11101111
> 0x12345678 & 0xFF00
= 22016 | 0x0000'5600 | 0b00000000'00000000'01010110'00000000
> sqrt(2)
= 1.4142135623730951
> 2**32
= 4294967296 | 0x0001'0000'0000'0000
= 0b00000000'00000000'00000000'00000001'00000000'00000000'00000000'00000000
> ans * 2
= 8589934592 | 0x0002'0000'0000'0000
> exit()
```

--------------------------------

### Run Specific QUTest Scripts via pip (Windows/Linux/macOS)

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

Executes specified test scripts (e.g., test_qk.py, test_mpu.py) using the 'qutest' command installed via pip, connecting to QSPY at a given UDP host and port. This command works on both Windows and Linux/macOS.

```shell
qutest -qlocalhost:7702 -oxc --  test_qk.py,test_mpu.py
```

--------------------------------

### Create and Draw on QWIN GUI Elements in C

Source: https://context7.com/quantumleaps/qtools/llms.txt

This C code snippet demonstrates how to initialize the QWIN GUI toolkit, create various graphical elements like LCD displays and buttons, and perform drawing operations on them. It includes setting up the main window, creating graphical and segment displays, and handling button states. The code relies on the 'qwin_gui.h' header and Win32 API functions.

```c
#include "qwin_gui.h"

// Create the main window and graphical elements
HWND mainWnd;
GraphicDisplay *lcd;
SegmentDisplay *seg;
OwnerDrawnButton *btn;

int main(void) {
    // Create main application window
    mainWnd = CreateWindow(...);

    // Create 128x64 graphical LCD display
    lcd = GraphicDisplay_create(
        mainWnd,          // Parent window
        10, 10,           // Position (x, y)
        128, 64,          // Size (width, height)
        IDC_LCD,          // Control ID
        bgColor           // Background color bitmap
    );

    // Create 7-segment display (4 digits)
    seg = SegmentDisplay_create(
        mainWnd,
        150, 10,          // Position
        4,                // Number of digits
        IDC_SEG           // Control ID
    );

    // Create owner-drawn button with custom bitmaps
    btn = OwnerDrawnButton_create(
        mainWnd,
        10, 100,          // Position
        60, 30,           // Size
        bmpUp,            // Bitmap for released state
        bmpDwn,           // Bitmap for pressed state
        IDC_BTN           // Control ID
    );

    // Draw on the graphical LCD
    GraphicDisplay_clear(lcd, 0);  // Clear with color 0
    GraphicDisplay_setPixel(lcd, 64, 32, 1);  // Set pixel
    GraphicDisplay_drawHLine(lcd, 0, 127, 0, 1);  // Horizontal line
    GraphicDisplay_drawVLine(lcd, 64, 0, 63, 1);  // Vertical line
    GraphicDisplay_drawRect(lcd, 10, 10, 50, 40, 1);  // Rectangle
    GraphicDisplay_drawCircle(lcd, 64, 32, 20, 1);  // Circle
    GraphicDisplay_redraw(lcd);  // Refresh display

    // Update segment display
    SegmentDisplay_setNum(seg, 1234);  // Show number
    SegmentDisplay_setSegment(seg, 2, 0x7F);  // Set individual segments

    // Handle button state
    if (OwnerDrawnButton_isPressed(btn)) {
        // Button is currently pressed
    }

    // Main message loop
    MSG msg;
    while (GetMessage(&msg, NULL, 0, 0)) {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    return 0;
}
```

--------------------------------

### QUTest CLI: Running Tests

Source: https://context7.com/quantumleaps/qtools/llms.txt

Illustrates various command-line options for running QUTest test scripts. This includes running all tests, specific scripts, and tests with host executables or remote targets.

```bash
# Run all test scripts (*.py) in current directory
python qutest.py

# Run specific test scripts
python qutest.py test_blinky.py test_dpp.py

# Run tests with host executable (for dual-targeting)
python qutest.py -e ./build/test_fixture.exe test_*.py

# Run tests with remote target via QSpy
python qutest.py -q localhost:7701 test_*.py

# Run with specific QSpy host and port
python qutest.py -q 192.168.1.100:7701:6601 -e ./test.exe test_*.py
```

--------------------------------

### QView DSL Commands Reference (Python)

Source: https://context7.com/quantumleaps/qtools/llms.txt

This section lists and describes various static methods provided by the QView library for interacting with a target system. These commands cover target control, sending commands, filter configuration, object selection, event operations, memory access, packet unpacking, and GUI utilities. The 'qunpack' utility is particularly useful for parsing packet data.

```python
# Target control
QView.reset_target()           # Reset the target
QView.tick(0)                  # Send tick rate 0
QView.tick(1)                  # Send tick rate 1

# Send command to target
QView.command(cmd_id, param1, param2, param3)
QView.command("MY_CMD", 100, 0, 0)  # Using command name from dictionary

# Filter control (same as QUTest)
QView.glb_filter(QView.GRP_ALL)
QView.glb_filter(QView.GRP_SM, QView.GRP_AO, -QView.GRP_QF)
QView.loc_filter(QView.IDS_ALL)
QView.ao_filter("Blinky_inst")

# Current object selection
QView.current_obj(QView.OBJ_SM, "Blinky_inst")
QView.current_obj(QView.OBJ_AO, "Blinky_inst")
QView.current_obj(QView.OBJ_AP, "myBuffer")
QView.query_curr(QView.OBJ_SM)

# Event operations
QView.publish("MY_SIG")                    # Publish to all subscribers
QView.publish("MY_SIG", pack("<II", 1, 2)) # With parameters
QView.post("MY_SIG")                       # Post to current AO
QView.init()                               # Init current SM
QView.dispatch("MY_SIG")                   # Dispatch to current SM

# Memory operations
QView.peek(offset, size, count)  # Read memory
QView.poke(offset, size, data)   # Write memory

# Packet unpacking utility
timestamp, obj, sig = QView.qunpack("TOS", packet_data)
# Format characters:
#   T = timestamp (target-dependent size)
#   O = object pointer (target-dependent size)
#   F = function pointer (target-dependent size)
#   S = signal (target-dependent size)
#   Z = zero-terminated string
#   B, H, I, Q = standard struct format chars

# GUI utilities
QView.print_text("Message to display")
QView.show_canvas()   # Show the canvas window
QView.show_frame()    # Show the frame window

```

--------------------------------

### QSPY C API: Configuration, Parsing, and Command Encoding

Source: https://context7.com/quantumleaps/qtools/llms.txt

This snippet demonstrates the core usage of the QSPY C API. It covers initializing QSPY with custom configuration and a parser callback, processing incoming trace data, looking up object and signal identifiers, encoding commands to send to the target, and cleaning up QSPY resources. It requires the 'qspy.h' header and assumes the existence of 'read_from_target' and 'send_to_target' functions.

```c
#include "qspy.h"

// Configure QSPY with target information
QSpyConfig config = {
    .qpDate = 241008,        // QP version date
    .qpVersion = 812,        // QP version number
    .endianness = 0,         // Little endian
    .objPtrSize = 4,         // 32-bit object pointers
    .funPtrSize = 4,         // 32-bit function pointers
    .tstampSize = 4,         // 32-bit timestamps
    .sigSize = 2,            // 16-bit signals
    .evtSize = 2,            // 16-bit event size
    .queueCtrSize = 1,       // 8-bit queue counters
    .poolCtrSize = 2,        // 16-bit pool counters
    .poolBlkSize = 2,        // 16-bit pool block size
    .tevtCtrSize = 2         // 16-bit time event counters
};

// Custom parser callback for application-specific records
int myCustomParser(QSpyRecord * const rec) {
    switch (rec->rec) {
        case 100: {  // QS_USER_00
            uint32_t timestamp = QSpyRecord_getUint32(rec, config.tstampSize);
            uint32_t counter = QSpyRecord_getUint32(rec, 4);
            printf("User record: ts=%u, counter=%u\n", timestamp, counter);
            return 1;  // Record handled
        }
        default:
            return 0;  // Record not handled
    }
}

int main(void) {
    // Initialize QSPY with configuration
    QSPY_config(&config, myCustomParser);

    // Process incoming data from target
    uint8_t buffer[512];
    uint32_t nBytes;

    while ((nBytes = read_from_target(buffer, sizeof(buffer))) > 0) {
        QSPY_parse(buffer, nBytes);
    }

    // Lookup dictionary entries
    KeyType obj = QSPY_findObj("Blinky_inst");
    if (obj != KEY_NOT_FOUND) {
        printf("Found object at address: 0x%llX\n", obj);
    }

    SigType sig = QSPY_findSig("TIMEOUT_SIG", obj);
    if (sig != SIG_NOT_FOUND) {
        printf("Found signal: %u\n", sig);
    }

    // Encode commands to send to target
    uint8_t cmd[64];
    uint32_t cmdLen;

    cmdLen = QSPY_encodeResetCmd(cmd, sizeof(cmd));
    send_to_target(cmd, cmdLen);

    cmdLen = QSPY_encodeTickCmd(cmd, sizeof(cmd), 0);
    send_to_target(cmd, cmdLen);

    // Cleanup
    QSPY_cleanup();
    return 0;
}

```

--------------------------------

### BDD-style Syntax for QTools (Alternative 1)

Source: https://context7.com/quantumleaps/qtools/llms.txt

Demonstrates the BDD-style syntax for defining test scenarios using GIVEN, WHEN, and THEN keywords. This approach enhances test readability and maintainability.

```qtools
# BDD-style syntax (Alternative 1)
SCENARIO("User logs in", NORESET)
GIVEN("User is on login page")
WHEN("User enters credentials")
THEN("User should see dashboard")
```

--------------------------------

### qcalc 64-bit range examples

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Shows examples of calculations that exceed the 32-bit integer range, demonstrating qcalc's automatic switch to 64-bit arithmetic and its output format for large numbers.

```plaintext
> 0xDEADBEEF << 27
= 501427843159293952 | 0x06F5'6DF7'7800'0000
= 0b00000110'11110101'01101101'11110111'01111000'00000000'00000000'00000000
> 0xDEADBEEF << 24
= 62678480394911744 | 0x00DE'ADBE'EF00'0000
= 0b00000000'11011110'10101101'10111110'11101111'00000000'00000000'00000000
> 0xDEADBEEF << 34
! out of range
```

--------------------------------

### Run qcalc standalone script

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Executes the qcalc Python script directly from its file path. This method does not require installation and is suitable for quick use or testing.

--------------------------------

### qcalc 'ans' variable examples

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Demonstrates the usage of the 'ans' variable in qcalc, which stores the result of the last computation, allowing for chained calculations and referencing previous results.

```plaintext
1/ans
log(ans)/log(2)
```

--------------------------------

### qcalc Syntax Error Example

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Demonstrates how qcalc reports a SyntaxError when an invalid expression is provided. The traceback shows the specific location of the error within the Python execution.

```python
> (2*4) + )
Traceback (most recent call last):
  File "C:\qp\qtools\qcalc\qcalc.py", line 54, in _main
    result = eval(expr)
  File "<string>", line 1
    (2*4) + )
            ^
SyntaxError: unmatched ')'
>
```

--------------------------------

### Run QUTest with Host Executable and QSPY Connection (Linux/macOS)

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

Executes all Python test scripts (*.py) using QUTest with a specified host executable, connects to QSPY on a given IP address, sets a log directory, clears the screen, and saves output to a file. This command is specific to Linux/macOS environments.

```shell
python3 $(QTOOLS)/qutest/qutest.py -ebuild/test_dpp -q192.168.1.100 -l../log -oco
```

--------------------------------

### Run QUTest with Host Executable and QSPY Connection (Windows)

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

Executes all Python test scripts (*.py) using QUTest with a specified host executable, connects to QSPY on a given IP address, sets a log directory, clears the screen, and saves output to a file. This command is specific to Windows environments.

```shell
python3 %QTOOLS%\qutest\qutest.py -ebuild/test_dpp.exe -q192.168.1.100 -l../log -oco
```

--------------------------------

### qcalc hexadecimal and binary number examples

Source: https://github.com/quantumleaps/qtools/blob/main/qcalc/README.md

Illustrates the use of hexadecimal (0x...) and binary (0b...) number formats within qcalc expressions, showcasing their integration with bitwise operations.

```plaintext
(0b0110011 << 14) & 0xDEADBEEF
(0b0010 | 0b10000) * 123
```

--------------------------------

### QUTest CLI: Execution Options

Source: https://context7.com/quantumleaps/qtools/llms.txt

Details command-line options for controlling QUTest execution, such as exit-on-fail, trace output, interactive mode, logging, and debug mode.

```bash
# Run with exit-on-fail option
python qutest.py -o x test_*.py

# Run with trace output enabled
python qutest.py -o t test_*.py

# Run with interactive mode after tests
python qutest.py -o i test_*.py

# Run with log file output
python qutest.py -l ./logs/ test_*.py

# Run in debug mode (waits for target)
python qutest.py -e DEBUG test_*.py

# Combined options: trace, exit-on-fail, clear QSPY screen
python qutest.py -o txc -l ./logs/ test_*.py

# Display version
python qutest.py -v
```

--------------------------------

### Filtering and Object Selection in QTools

Source: https://context7.com/quantumleaps/qtools/llms.txt

Demonstrates how to apply global and local filters, and select current objects for testing. These functions are essential for isolating specific components or behaviors during test execution.

```qtools
glb_filter(GRP_ALL)            # Enable all global filters
glb_filter(GRP_SM, GRP_AO)     # Enable SM and AO groups only
glb_filter(-GRP_QF)            # Disable QF group
loc_filter(IDS_ALL)            # Enable all local filters
ao_filter("Blinky_inst")       # Filter specific AO

current_obj(OBJ_SM, "Blinky_inst")  # Set current state machine
current_obj(OBJ_AO, "Blinky_inst")  # Set current active object
current_obj(OBJ_TE, "l_blinkyTimeEvt")  # Set current time event
current_obj(OBJ_AP, "myBuffer")    # Set current application object
query_curr(OBJ_SM)             # Query current SM state
```

--------------------------------

### ROM Filesystem Generator with QFSGen

Source: https://context7.com/quantumleaps/qtools/llms.txt

QFSGen generates C source files for ROM-based file systems, suitable for embedded web servers. It scans a directory recursively and creates C arrays containing file content and optional HTTP headers.

```bash
# Generate ROM filesystem from 'fs' directory (default)
qfsgen

# Generate from custom directory
qfsgen -d ./webpages

# Generate with HTTP headers included
qfsgen -h -d ./webpages

# Specify output file
qfsgen -d ./webpages -o fsdata.c

# Example output file (fsdata.c):
# static const unsigned char file_index_html[] = {
#     /* /index.html */
#     0x2F, 0x69, 0x6E, 0x64, 0x65, 0x78, 0x2E, 0x68, 0x74, 0x6D, 0x6C, 0x00,
#     /* HTTP header (if -h option used) */
#     0x48, 0x54, 0x54, 0x50, 0x2F, 0x31, 0x2E, 0x31, 0x20, ...
#     /* file content */
#     0x3C, 0x21, 0x44, 0x4F, 0x43, 0x54, 0x59, 0x50, 0x45, ...
# };
#
# const struct fsdata_file file_index_html_struct = {
#     NULL,
#     file_index_html,
#     file_index_html + 12,  /* data offset */
#     sizeof(file_index_html) - 12
# };
```

--------------------------------

### QUTest DSL Commands for Test Control and Event Handling

Source: https://context7.com/quantumleaps/qtools/llms.txt

QUTest provides a domain-specific language (DSL) with commands for managing test execution, dispatching events, setting filters, and performing memory operations. It supports traditional unit testing and BDD-style syntax.

```python
# Test control commands
test("Test name")              # Start a new test (resets target)
test("Test name", NORESET)     # Continue from previous state
skip(3)                        # Skip next 3 tests
expect("pattern*")             # Verify trace output (supports wildcards)
ensure(condition)              # Assert a condition is True

# Event commands
init()                         # Take initial transition in current SM
init("INIT_SIG")               # Init with signal name
dispatch("MY_SIG")             # Dispatch event to current SM
dispatch("MY_SIG", pack("<I", 123))  # Dispatch with parameters
post("MY_SIG")                 # Post event to current AO
publish("MY_SIG")              # Publish event to all subscribers

# Clock and timing
tick()                         # Trigger tick rate 0
tick(1)                        # Trigger tick rate 1
```

--------------------------------

### Run QUTest with Host Executable (Windows)

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

Executes all Python test scripts (*.py) in the current directory using QUTest, specifying a host executable (e.g., build/test_dpp.exe) as the test fixture. This command is specific to Windows environments.

```shell
python3 %QTOOLS%\qutest\qutest.py -ebuild/test_dpp.exe
```

--------------------------------

### Run QUTest with Host Executable (Linux/macOS)

Source: https://github.com/quantumleaps/qtools/blob/main/qutest/README.md

Executes all Python test scripts (*.py) in the current directory using QUTest, specifying a host executable (e.g., build/test_dpp) as the test fixture. This command is specific to Linux/macOS environments.

```shell
python3 $(QTOOLS)/qutest/qutest.py -ebuild/test_dpp
```