English | 简体中文
Start with the root first-run guide: prepare a compatible OpenTest from source, build FFT, import it, and complete a real microphone measurement with saved-result reopening. Read the dev-kit guide for public APIs. This tutorial then covers a small FFT change and a new plugin identity with one measurement contribution.
my-fft-tools below is a tutorial directory you create, not another supplied plugin. It retains FFT computation while teaching registration and packaging. A different business algorithm needs its own configuration, validation, execution, results, and host capability checks.
For everyday source development, use installed-content development: install the package once, then use dev / dev:watch to deploy into the active installed directory. Backend changes require a host backend restart; frontend changes require a full page refresh. Version bumps and import steps below apply to package delivery verification.
Paths in this section are relative to plugins/fft-tools.
| Stage | File and behavior |
|---|---|
| Declaration | plugin.json connects fftMeasure, contributions/measure/fft-measure, backend handler fftMeasure, and config version "1". |
| Default values | frontend/src/contributions/measure/fft-measure/model.ts defines defaultFftConfig, including overlap: 50. Java measurement/FftMeasurement.java supplies defaults through metadata() and builds the initial configuration through initialConfiguration(). |
| Parameter editing | frontend/src/contributions/measure/fft-measure/setting.vue edits fftConfig. Its index.ts adapts the host's business config to signalAnalysisConfig.fftConfig and emits update:config; selected channel IDs arrive separately. |
| Parameter validation | The frontend editor validates parameter shapes, the Java provider validates business constraints before execution, and the manifest configuration version rejects incompatible configurations. |
| Java input and validation | backend/src/main/java/com/opentest/plugins/fft/measurement/FftDashboardConfig.java reads collectConfig and plugin-owned signalAnalysisConfig.fftConfig; fftConfig() also accepts the retained flat compatibility slot. FftMeasurement.validateExecution() rejects non-finite overlap or values outside 0 <= overlap < 100. |
| Execution and persistence | FftDashboardProvider.execute(ExecutionContext) prepares inputs and compiles a PipelinePlan. FftMeasurement.buildPipeline() selects the self-spectrum or BK pipeline for the supported live or recorded input purpose. Nodes call public algorithm services and emit results; the host provides devices and persistence facilities. |
The frontend registration's providerId and Java FftMeasurement.ID are both com.opentest.fft-tools:fft-measure. FftToolsPlugin.register() passes its metadata and initial configuration to MeasureProviderRegistration. Use the registered provider and its metadata. A hardcoded host dashboard type is not a substitute for registration.
Historical replay and export recalculation use the measurement Provider recorded-input purposes; see FftDashboardProvider. Register passive algorithm identity, unit and trigger rules with measureResultCatalogs and MeasurementResultCatalog. Missing result facts use the normal Provider describeResult query with the same strict configuration binding. Catalog interpretation must not create execution resources or register independent analysis tasks. Rebuild the host and plugins against the matching public API.
File output is part of the plugin pipeline: connect PersistWaveformSinkProcessor to the frozen outputs.rawChannels() only when the operation needs original WAV files. Historical recalculation and continuous display must not reconnect that recording branch. An execution ID does not imply a published measurement: RT60 and sound-power background capture select ExecutionRecordMode.NONE and keep their shared crybin results without opening internal raw WAV output. Formal capture keeps its explicit original-waveform branch; shared result scope alone does not decide record publication.
For a first exercise, change the measurement default overlap from 50 to 25 percent:
- In
frontend/src/contributions/measure/fft-measure/model.ts, change thedefaultFftConfig.overlapvalue to25. - In
backend/src/main/java/com/opentest/plugins/fft/measurement/FftMeasurement.java, changedefaults.put("overlap", 50)inmetadata()todefaults.put("overlap", 25). - Keep existing configurations intact. This changes new-measurement defaults, not previously saved project settings, the overlap validation range, or other parameter editors' defaults. No configuration version change is needed for this default-only exercise.
- Extend the frontend workspace tests and Java provider tests to check the default used for a newly created measurement and retention of an explicit saved value. Keep validation coverage for valid overlap and rejected out-of-range values. Use existing tests under the measurement contribution and
backend/src/test/java/com/opentest/plugins/fft/FftHandlersTest.javaas references. - Before distributing the changed FFT, choose an unused version higher than the version already installed, and align
plugin.json,frontend/package.json, and the plugin'sbackend/pom.xmlfor that release. Check their actual values first; the installation package version comes fromplugin.json. Keep SDK/API versions unchanged.
From the plugin repository root:
node tools/build.mjs fft-toolsLoad the higher-version package with the same plugin ID and completely restart to apply the upgrade. Create a new measurement and confirm the default is 25; reopen an existing configuration and confirm it retains its explicitly saved value. Complete acquisition, normal stopping and result reopening. A successful test/build alone does not verify the UI and device path. Returning from mutable installed-content development to strict startup instead requires normal uninstall and reinstall.
Start from a working FFT source revision. In the plugin repository root, copy its tracked files to a new directory without copying node_modules, dist, or Java target outputs:
$sourcePrefix = 'plugins/fft-tools/'
$newPluginDirectory = 'plugins/my-fft-tools'
if (Test-Path -LiteralPath $newPluginDirectory) {
throw 'The destination already exists; choose a new plugin directory.'
}
$sourceFiles = @(git -c core.quotepath=false ls-files -- plugins/fft-tools)
if ($LASTEXITCODE -ne 0 -or $sourceFiles.Count -eq 0) {
throw 'Cannot enumerate tracked FFT source files.'
}
foreach ($sourceFile in $sourceFiles) {
if (-not $sourceFile.StartsWith($sourcePrefix)) {
throw "Unexpected source path: $sourceFile"
}
$destinationFile = Join-Path $newPluginDirectory $sourceFile.Substring($sourcePrefix.Length)
New-Item -ItemType Directory -Force -Path (Split-Path -Parent $destinationFile) | Out-Null
Copy-Item -LiteralPath $sourceFile -Destination $destinationFile -ErrorAction Stop
}This copies the working contents of tracked files, including your tracked-file edits; new untracked files are not included. Review the source state first. Keep dev-kit and tools at the repository root. Keep the complete package-local frontend/src/shared tree: measurement UI depends on it.
The current build tools require a directory matching ^[a-z][a-z0-9-]+$ and pluginId = com.opentest.<directory>. For this example use com.opentest.my-fft-tools. An arbitrary namespace such as com.example.* is not supported by these tools without a separate tooling change.
All paths below are inside plugins/my-fft-tools. Use version 0.1.0 for this new identity.
| Location | Exact change |
|---|---|
plugin.json |
Set pluginId to com.opentest.my-fft-tools, version to 0.1.0, and entryPoints.backend.java.jar to backend/opentest-my-fft-tools.jar. Keep the compatible host range, manifest/API versions, and empty dependencies / conflicts. |
frontend/package.json |
Set name to @opentest-plugin/my-fft-tools-frontend and version to 0.1.0. Keep the local dev-kit dependencies and locked tool versions. |
frontend/index.ts |
Change the activation identity check from com.opentest.fft-tools to com.opentest.my-fft-tools. Change stylesheet path ./fft-tools.css to ./my-fft-tools.css. |
frontend/vite.config.ts |
Change build.lib.cssFileName from fft-tools to my-fft-tools. Keep ES output and the Vue/UI external mappings. |
frontend/src/contributions/measure/fft-measure/index.ts |
Change measureRegistration.providerId to com.opentest.my-fft-tools:fft-measure. |
backend/src/main/java/com/opentest/plugins/fft/measurement/FftMeasurement.java |
Change ID to com.opentest.my-fft-tools:fft-measure, exactly matching the frontend; registration reads this class's metadata. |
backend/pom.xml |
Set artifactId and build.finalName to opentest-my-fft-tools; set the project version to 0.1.0. Keep SDK dependency version 2.5.0 and provided. |
frontend/locales/en-US.json and zh-CN.json |
Set plugin.name, plugin.description, and measure.fft.title to distinguish your plugin, for example My FFT / 我的 FFT. The existing keys can remain because language lookup is bound to plugin identity. |
| Copied tests | Update identity/provider fixtures, stylesheet assertions, and registration expectations as described below. |
For the smallest exercise, retain Java's private package com.opentest.plugins.fft, class FftToolsPlugin, and matching manifest mainClass. The JAR artifact and public plugin/provider identities change independently of those internal names. If you later rename the Java package, refactor both main and test source directories, every package/import and fully qualified class reference, and manifest mainClass together. Renaming a public class also requires renaming its .java file.
Do not replace every occurrence of fft. Keep fftConfig, the numerical parameter types, FFT result names, and the existing computational settings. The metadata's scene and processingCapability remain fft for this exercise because it reuses FFT UI behavior and host capabilities. Result ownership is a separate identity: change the catalog and result-definition algorithm codes together as specified below. Internal contribution IDs and component paths can remain when all declarations agree. Documentation language does not require changing localization.defaultLocale from zh-CN.
The new exercise exposes only the existing measurement implementation. Make these four edits together:
- In
plugin.json, replace thecontributionsobject with:
{
"measureModules": [
{
"id": "fftMeasure",
"titleKey": "measure.fft.title",
"frontendComponent": "contributions/measure/fft-measure",
"backendHandler": "fftMeasure",
"configVersion": "1"
}
]
}This replaces only contributions, not the complete manifest. Keep both required entry points and all language/file references.
-
In
frontend/index.ts, retaincontext.measure.register(...), language setup/cleanup, stylesheet loading/error cleanup, and the returneddispose(). -
Keep the
indexandcontributions/measure/fft-measurelibrary entries infrontend/vite.config.ts. -
Java
FftToolsPlugin.register()registers the measurement withregistry.measureProvider(...)and its passive result catalog withregistry.measureResultCatalogs(...). Retain the catalog: saved-result access resolves ownership through its algorithm identity. For this new plugin, choose an unused algorithm identity such asmy-fftand change these together:FftAnalysisCatalog.algorithmId()andFftTableDefinitionResolver.ALGORITHMmust both becomemy-fft.- The
DashboardDefinitionalgorithm-code arguments inFftMeasurementandBkFftDefinitionmust also becomemy-fft, for consistent self-spectrum and BK definitions. - Update catalog expectations and saved/current-result fixtures to use
my-fft; keepMeasureProviderMetadata.sceneandprocessingCapabilityasfft. The configuration's FFT selector is not a substitute for the result ownership code.
Only changing the catalog or deleting its registration leaves results dependent on the original FFT. This exercise creates new measurements; it does not migrate the original plugin's saved records.
The current SDK has no independent offline-analysis entry. Keep indexed language keys aligned with actual usage and parameter-compatible in both locales.
| Test | Required expectation |
|---|---|
frontend/src/activation.test.ts |
New identity/provider/CSS; exactly one measurement registration; both language subscriptions and stylesheet disposed |
frontend/src/contributions/measure/fft-measure/workspace.test.ts |
New plugin/provider identity and metadata matching the Java provider |
frontend/src/contributions/measure/fft-measure/__tests__/index.test.ts |
Update old plugin/provider fixtures to the actual new identity |
backend/src/test/java/com/opentest/plugins/fft/FftHandlersTest.java |
Check the measurement Provider identity and passive catalog declarations; no independent analysis handler is registered |
Search the copied source and tests for remaining com.opentest.fft-tools, opentest-fft-tools, and fft-tools.css references. Review matches individually; no remaining public identity or output-name reference should point to the original plugin. Keep business contract names intentionally retained above.
Declare exportable waveforms as ResultType.WAVEFORM. Every member must explicitly use
ChannelDirection.INPUT or ChannelDirection.OUTPUT when constructing ResultChannelDefinition;
missing directions fail immediately when the waveform ResultSetDefinition is created.
Input and output members may coexist in the same result. There is no additional JSON export switch.
Implement DashboardProvider.describeResult to reconstruct the selected saved result from the
query's configuration, result identity/parameters and channel facts. Preserve its result code,
hash and type; do not use the current editable dashboard or invoke whole-table reconciliation.
The host lists saved waveform results, retains unavailable entries with a reason, and requires
every selected member's source file to be available before starting any export in that batch.
SDK, host and plugins must be rebuilt together; old development records are not migrated.
From the plugin repository root:
node tools/build.mjs my-fft-tools
if ($LASTEXITCODE -ne 0) { throw 'Tutorial plugin build failed.' }
Get-Item -LiteralPath .\dist\com.opentest.my-fft-tools-0.1.0.otplugin
Get-Content -LiteralPath .\dist\my-fft-tools-package.jsonProceed only after the full build succeeds. With unchanged dependency declarations the copied frontend lockfile remains usable; intentional SDK/dependency changes require the reviewed update process in the dev-kit guide.
Distinct pluginId and providerId values and an independent, consistently declared catalog/result algorithm identity are prerequisites for coexistence with the original FFT. Duplicate provider identities cause DASHBOARD_PROVIDER_DUPLICATE; catalog algorithm identities are also unique across active plugins. There is no numeric dashboard mapping. Verify coexistence and independent result access with the steps below before treating the copied plugin as usable.
Keep FFT business configuration fields unchanged for this exercise, and handle catalog algorithm identities as described above. No numeric mapping is required. Keep valuable existing projects separate from your tutorial test project.
After importing the new package and restarting:
- Plugin Management must show
com.opentest.my-fft-tools, version0.1.0, and your display name as active. - Open a new test project. The measurement entry should use your localized title and its registered provider; the exercise must not add its own offline-analysis or signal-analysis entry.
- Follow the microphone procedure using this new measurement entry. Select the physical input in both the project and measurement settings, observe live spectra, stop normally, and reopen the same result after a full restart.
- With both plugins enabled, confirm their measurement entries and result ownership remain separate. Disable the original FFT and completely restart; the tutorial plugin must still acquire, save, reopen, and export its own results. Re-enable FFT afterward. A result still tagged
fftdoes not pass this check. - Switch language and reopen the workspace. Check titles, retained settings, resource cleanup and failure/cancellation behavior. Review host logs if a contribution or capability fails.
The sample still uses FFT host services and entitlements. A new package ID does not provide a new numerical algorithm or remove authorization requirements.
Before introducing a new parameter, trace its UI value, configuration version, frontend validation, Java type/validation, execution use and saved-result behavior. Before adding another contribution, implement and test its frontend factory and backend handler, then declare it consistently in the manifest and Vite entries. There is no generator command in this repository.
Use public SDK/UI capabilities. Create independent instances per page/workspace, dispose subscriptions and chart handles, and respect host cancellation. Do not copy host pages, bundle a second Vue/LightningChart runtime, shade Java SDK classes, or call private host stores/desktop bridges. Read the SDK boundaries when deciding which context owns an operation.
For review, include the manifest/version change, relevant tests, successful full build output and the host scenarios actually checked. Real device acquisition and reopening are separate from component tests and packaging. Do not report an unexecuted clean-clone or hardware check as passed.
Use pnpm build:signed <plugin> --platform windows for a signed build, or pnpm package:signed for existing compiled outputs. See native signing for configuration, platforms, caching and host verification.