templates/tools/dsview/README.md

# DSView as an embedded Windows instrument panel

Upstream: https://github.com/DreamSourceLab/DSView, revision `2e9e2c8e`.
The GPL-3.0-or-later application and its private Qt 5/Python runtime stay in
a separate process. `setgui-host.patch` adds the Windows host protocol and
fixes the missing Windows CMake inputs. No DSView DLL is loaded into Qt 6.

`python/logic_analyzer/dsview_host.py` contains the reusable environment,
process/window ownership and close-message helpers. The consuming GUI owns
the stylesheet, window surface and lifecycle.

## Build

MSYS2 UCRT64 packages (install with `pacman -S --needed`):

```text
mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake
mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-pkgconf
mingw-w64-ucrt-x86_64-qt5-base mingw-w64-ucrt-x86_64-qt5-svg
mingw-w64-ucrt-x86_64-qt5-winextras mingw-w64-ucrt-x86_64-glib2
mingw-w64-ucrt-x86_64-libusb mingw-w64-ucrt-x86_64-fftw
mingw-w64-ucrt-x86_64-boost mingw-w64-ucrt-x86_64-python
```

```powershell
python tools/dsview/build.py --source C:/path/to/DSView --output C:/path/to/runtime --msys-root C:/msys64
```

The builder checks the revision, applies the patch only after `git apply
--check`, and accepts an already applied patch. It never resets the source
checkout. Close the built DSView before rebuilding.

Successful builds write `host-build.json`, recording the recipe digest (patch,
packager, adapters and shared cores) and the native EXE digest. Consumers can
call `runtime_is_current(output)` before packaging to detect an old component
even if the host-protocol version is unchanged. SETGUI's normal EXE builder
automatically rebuilds an installed stale runtime and refuses to package it if
the update fails. A runtime built before this stamp was added is rebuilt once.

## Host protocol 1

- Create a native child surface owned by the host process.
- Start `DSView.exe --embed-parent <decimal HWND>` with its private runtime
  as working directory and a sanitized environment.
- `DSVIEW_HOST_STYLE` points to the UTF-8 Qt stylesheet; `DSVIEW_CAPTURE_DIR`
  supplies the initial open/save/export directory.
- Wait for `DSVIEW_READY <HWND>` on stdout, then validate both the window PID
  and its parent before accepting it.
- The child fits the surface, inherits visibility, and exits if the parent
  window disappears. It uses separate settings under `SET/SETGUI-DSView`.
- Write `CLOSE\n` to the child's stdin to close normally. Keep the host
  alive while DSView's save dialog is open. Forced termination is only a
  fallback for host shutdown or a failed start.
- Write `ADD_DECODER <id>\n` to open the normal decoder configuration dialog.
  The host must be ready, in digital mode and not capturing. Stacked decoders
  automatically include the matching UART/CAN base decoder.
- New hosts announce `DSVIEW_CAPABILITIES OPEN_FILE` after the ready message.
  `OPEN_FILE <base64 UTF-8 path>\n` opens a DSL recording without restarting
  the child. It returns `DSVIEW_FILE_RESULT ok|busy|save|error`. A capture,
  save operation or modal dialog prevents replacement. Unsaved hardware data
  retains the normal save prompt.
- In embedded mode File в†’ Open accepts CSV and emits
  `DSVIEW_IMPORT_CSV <base64 UTF-8 path>` for conversion by SETGUI. The shared
  `python/logic_analyzer/csv_import.py` streams CSV into temporary DSL v3
  blocks in two passes, with progress/cancellation and bounded memory.
  Times are read as decimal picoseconds; front-to-front intervals are exact.
  The initial state may extend by less than one sample to align the grid;
  the final state pads to 64 samples. Original offset metadata is retained.
- Embedded mode disables Qt's quit-on-last-window policy: the child is a
  `Qt::Tool`, so accepting/rejecting a modal dialog must not quit the process.
- `--host-version` returns `DSView host protocol 1`. An optional
  `DSVIEW_HOST_SCREENSHOT` environment variable saves one render artifact
  after startup for native integration tests.

Tested SDK: GCC 16.2, Qt 5.15.19, Python 3.14.7, Windows x64. This runtime
requires Windows 10/11; it does not add Windows 7 support.

## SET decoders

The **Sigma-delta** decoder (`sigma_delta`) reconstructs a clocked one-bit
DATA/CLK stream using sinc1/2/3 decimation. It includes sampling-edge and polarity
selection, normalized samples, voltage scaling and clock/output-rate annotations.
See [sigma-delta settings](decoders/sigma_delta/README.md).

`decoders/` contains the sigrok front ends for `gate_driver_timing` (1SP0635 /
1SD536F2), `set_uart` (SET v1/v2, ProtoCAN bridge), `set_can` (ProtoCAN, SET v2,
Balsam), and `pm35_uart` (TMS320F28335 MODBUS 03/06).
Their parsing cores are maintained only in `python/logic_analyzer/decoders`.
The builder copies those files verbatim to `decoders/common/setgui_decoders`
inside the runtime. No GUI imports or external Python installation are needed.
The adapters originate from `DSLogic_Logic_2/dslogic_script/dsview_decoders`.

IGBT offers `ORPHAN minimum pulse width (ns, 0 = off)` for all profiles.
Only uncorrelated pulses strictly shorter than this duration are omitted from
annotations; zero preserves the original behavior. ACK measurements/errors,
FAULT and lone edges with unknown pulse duration remain visible. This does
not modify the captured signal or debounce Vin1/Vstat.

The independent **Transistor pair** decoder measures mintime, OFF time,
deadtime in both directions, overlap, frequency and duty. It requires only
Vin1/Vin2. **IGBT 1SP/1SD** retains Vin1/Vstat ACK and full-cycle checks.
See [pair settings](decoders/transistor_pair/README.md) and
[driver settings](decoders/gate_driver_timing/README.md).

Run `python -m unittest discover -s tools/dsview/tests` for packet, CRC,
segmentation, timing-profile and sigrok API boundary tests. SETGUI's
`--check-dsview` sets `DSVIEW_HOST_CHECK` to a report file and exercises native
decoder dialogs, single/all removal with Yes/No, stacking and child lifetime.
The check saves decoder dialog screenshots alongside the report.

## Application protocols from templates

SET CAN includes the current shared parsers and dictionaries. Select
`Protocol / протокол` in the decoder settings:

- `protocan` / `devboard`: ProtoCAN/SETCAN, GAS, Settings, boot services,
  discrete and analog messages, device names and assigned GAS IDs.
- `balsam`: Balsam 167, including the actual rotating wire-word order and
  separate operator-panel IDs.
- `ump-protocan`: UMP 1/2 with the explicitly selected `gas167` local map or
  `assigned` global IDs. Assigned IDs do not imply firmware support.
- `deif`: DEIF XDi-192 / CANopen with STD CAN frames and physical values.
- `legacy`: explicitly select a project from the shared catalog:
  Буксир, СЭДБМ, Ледокол, Бальзам, 23550, 23550.X, 23550.2, Янтарь, 23550 БСУ.
- `set-v2`: segmented SET v2, with CRC, sequence and timeout checks.
- `auto`: Balsam IDs, the SET v2 transport prefix, otherwise ProtoCAN.
  Project-specific legacy formats and UMP maps always require explicit selection.

Frames, Fields, Registers, Payload and Errors are separate annotation rows.
SET UART can apply the same non-segmented CAN profiles inside the AA55 bridge;
its Bridge settings select the profile, project and UMP map/node.

TMS UART stacks on UART and reads `TMS_TO_TERMINAL` using the shared terminal
parser. Choose a preset layout or `custom` with discrete-byte/analog-word
counts, plus MODBUS or CCITT-FALSE CRC. For a 22220 reply, select `custom`,
70 discrete bytes and 80 analog words. RX/TX buffers are independent;
UART errors and configured gaps discard incomplete data. Only frames with
valid CRC are emitted. This decoder covers terminal telemetry layouts;
variable-length TMS bootloader/memory exchanges are not terminal telemetry.

`protocol-files.json` is the single payload manifest for the embedded builder
and the standalone installer. Canonical Python modules and JSON maps are
copied unchanged into the private decoder runtime; no GUI imports or external
Python packages are required. Restart DSView after updating the decoders.

## Annotation search

The patch searches every enabled result column of the selected decoder and
every annotation label, including short waveform labels such as `ORPHAN`.
Matching is case insensitive; warning columns are enabled by default. Explicitly
hidden columns remain excluded until enabled in Decoding Results settings.
Enter (including the Windows popup editor), the magnifier and the next arrow
navigate forward; the previous arrow navigates backward. Matches are counted
per annotation, ordered by sample time, and wrap around. Tooltips show all
label variants. A nonempty query displays a compact match-only table: one
annotation per row, with its row title and matching label. Clearing the query
restores the source table; a query with no matches displays an empty list.
Click/arrow navigation maps each result back to the original annotation.
Numeric `AA-BB-CC` sequences are still supported; other hyphens
are literal. Search runs in short GUI-thread timer steps, invalidates indices
on model resets, and refreshes when decoding reaches 100 percent.

After rebuilding, verify with an IGBT recording containing an uncorrelated
Vstat pulse: search `ORPHAN`, `orphan`, and `Unexpected Vstat`; each should
select the same warning and show its waveform region. Also check Enter from
the popup editor, magnifier/arrow wraparound, a missing query, clearing/changing
the query during a long search, changing columns/decoders, and removing the
decoder while searching. Confirm numeric sequences and literal `CAN-FD` labels
still work. Source syntax checks do not replace this native GUI check.

## Install analyzers into standalone DSView (Windows)

The adapters in `tools/dsview/decoders` and portable cores in
`python/logic_analyzer/decoders` are shared with the embedded build.
No analyzer implementation is maintained in the consuming GUI.

```powershell
.\tools\dsview\install_decoders.ps1 -DsViewPath 'C:\Program Files\DSView'
```

Close DSView first. An elevated PowerShell is needed if the installation
folder is protected. Add `-CheckOnly` to validate source files and the target
layout without writing. Python/MSYS2 and a DSView rebuild are not required.
The target must contain DSView.exe and decoders/common.

Installs gate_driver_timing, set_uart, set_can and pm35_uart, with unchanged
cores under decoders/common/setgui_decoders. Existing unrelated files are
preserved. Replaced files are backed up under set-decoder-backups next to
DSView.exe; failed copies trigger rollback. Keep backups for manual recovery.
To restore, close DSView and copy the backup contents over decoders.

Restart DSView, add the UART or CAN base decoder and stack SET/PM35 on top.
Gate timing consumes logic channels directly. This installs decoders only;
it does not install the SETGUI host patch, menus or CSV import.

Installer tests run under Windows PowerShell against temporary targets and
check isolated imports, updates, backups, copy-failure rollback and validation:

```powershell
python -m unittest discover -s tools/dsview/tests -p test_install_decoders.py -v
```

## Decoder panel and selector

Embedded DSView does not restore standalone toolbar/dock layout. The Decoders
panel can extend to the top row of the DSView controls; its upper splitter
still allows reducing its height. SETGUI's own folder and tab rows remain
outside the native component.

The decoder selector starts with **Пользовательские**: IGBT 1SP/1SD,
Transistor pair, SET UART, SET CAN and PM35 UART. **Стандартные** contains the remaining
decoders. Search matches names and IDs in both sections and hides empty
section headings. The changes are packaged in `decoder-panel.patch`.


## Шины 96-контактного интерфейса: Plates PBus / Plates SBus

В общую ведомость поставки включены `plates_pbus` и `plates_sbus`.
Они устанавливаются вместе с остальными анализаторами, включаются в
будущую сборку embedded DSView и работают непосредственно с logic-каналами.
Назначение сигналов, формат обмена, параметры CRC/ACK и ограничения захвата
описаны в [PLATES_BUSES.md](PLATES_BUSES.md).

В checkout SETGUI запуск `buildb_bat/INSTALL_DSVIEW_DECODERS.bat` без
параметров выбирает `dist/dsview`; при отсутствии полного компонента там
проверяется `src/gui_desktop/native/dsview`. Выбранный путь печатается до
копирования. Для отдельной установки передать `-DsViewPath` с её каталогом.
Для записи в защищённый Program Files требуются права администратора;
обновление декодеров не требует записи в сам `DSView.exe`.
Перед установкой закрыть целевой DSView, затем открыть его снова.
Добавление пакетов обновляет Python-декодеры без пересборки EXE;
изменение раздела «Пользовательские» применяется при следующей нативной сборке.

## Фазные токи асинхронного двигателя

**PWM motor currents** (`pwm_motor`) оценивает линейные Ia/Ib/Ic в амперах
по ШИМ двухуровневого или трёхуровневого инвертора, полному напряжению звена
и параметрам короткозамкнутого асинхронного двигателя. Входы: три верхние
команды, шесть команд P/N или двенадцать затворов NPC. Скорость ротора
задаётся постоянной; доступны звезда/треугольник и начальные токи/поток.

[Назначение входов, параметры и ограничения](decoders/pwm_motor/README.md).
Цветные кривые и шкала ампер требуют `motor-currents.patch`, который штатный
рецепт применяет после остальных графических патчей. Адаптер и общее ядро
входят в общую ведомость установки. Проверка:
`python -m unittest discover -s tools/dsview/tests -p test_pwm_motor.py -v`.
Нативная проверка готовой DSL-записи:
`python tools/dsview/tests/check_motor_native.py --runtime <dsview> --capture <motor.dsl> --output <artifacts>`.

## PWM waveform / ШИМ → синус

Double-click an individual decoder plot to open it in a separate scope window.
The decoder label context menu offers the same action for each visible plot.
Combined A/B/C opens as one scope; split phases, theta and carrier open separately.
Wheel zoom, drag to pan, full-record fit, amplitude fit, physical Y range and
phase visibility affect only the extra window. It shares the decoder's indexed
results and follows input colours; removing the source decoder closes the scope.
The build includes `decoder-scope.patch` and `native/decoder_scope.h`.

Native interaction check (a 120000-sample DSL with the motor decoder last):
`python tools/dsview/tests/check_decoder_scope_native.py --runtime <dsview> --capture <example.dsl> --output <artifacts>`.

Декодер восстанавливает кривые заполнения для 1–3 цифровых входов.
В SETGUI он находится в меню **Анализаторы SET → ШИМ → синус · 1–3 канала**.
[Настройки, режимы и ограничения](decoders/pwm_waveform/README.md).
Сборка включает `pwm-waveform.patch`; один установщик Python-декодеров
не добавляет графическую отрисовку в старый DSView.