# NMRLink > JavaScript library for controlling a specific educational NMR apparatus developed by Yasushi Kondo (Kindai University). Use it to build custom browser UIs for device control, FID acquisition, FFT analysis, calibration, and T1/T2 measurements. ## Scope and environment - Actual measurements require the compatible physical NMR apparatus. This is not a universal interface for arbitrary NMR spectrometers or a quantum circuit execution SDK. - The apparatus is intended for student experiments and quantum information education. Distribution through an educational equipment vendor is planned. - Direct connection uses the Web Serial API in a supported desktop browser, over HTTPS or localhost. A serial port must be selected from a user click. - Linux users need permission to access the serial device. On Debian-based systems this may require dialout membership followed by desktop logout/login. Browser packaging may impose additional device access restrictions; do not assume a particular Snap workaround. - Framework independent JavaScript ES modules. No CommonJS build, TypeScript declarations, or runtime dependencies in nmrlink. - NMRLink and the original Python program are MIT licensed, with separate author notices. Original Python is in the GitHub original/ directory, not in the npm package. ## Install and imports npm install nmrlink For a browser app using a bundler such as Vite: ```js import { NMRController, analyzeMeasurement } from "nmrlink"; import { NMRGraphs } from "nmrlink/graphs"; import { saveMeasurement, readMeasurement, saveGraphPng } from "nmrlink/browser"; ``` For static HTML without a build, copy the entire packages/nmrlink/src directory beside your HTML and rename it nmrlink. Serve that working directory through a Web server and use these relative imports: ```js import { NMRController, analyzeMeasurement } from "./nmrlink/index.js"; import { NMRGraphs } from "./nmrlink/graphs.js"; import { saveMeasurement } from "./nmrlink/browser.js"; ``` Bare package names do not resolve in a plain browser without an import map or bundler. Do not serve a checkout containing private remote-server credentials. ## Minimal direct-connection UI The following HTML and JavaScript are for a bundler-based browser app. Parameter values are examples, not universal calibrated settings. ```html
未接続
``` ```js import { NMRController, analyzeMeasurement } from "nmrlink"; import { NMRGraphs } from "nmrlink/graphs"; import { saveMeasurement } from "nmrlink/browser"; const get = id => document.getElementById(id); const controller = new NMRController(); const graphs = new NMRGraphs({ fid: get("fid"), fft: get("fft") }); // 装置・試料に合わせて確認する値です。校正済みの値へ変更してください。 const parameters = { frequencyHz: 402000, pulse1Cycles: 21, phase1Degrees: 0, pulse2Cycles: 42, phase2Degrees: 90, pulseIntervalMs: 5, measurementIntervalMs: 200, scans: 128, }; controller.onStateChange(state => { get("connect").disabled = !state.canConnect; get("measure").disabled = !state.canMeasure; get("disconnect").disabled = !state.canDisconnect; }); controller.onError(error => { get("status").textContent = error.message; }); controller.onResult(record => { get("save").disabled = false; try { graphs.show(record, analyzeMeasurement(record)); get("status").textContent = "測定が完了しました。"; } catch (error) { graphs.clear(); get("status").textContent = `解析できませんでした:${error.message}`; } }); // ポート選択はクリックから直接呼び出します。 get("connect").onclick = () => controller.connect(); get("measure").onclick = () => controller.measure(parameters, { mode: "single" }); get("disconnect").onclick = () => controller.disconnect(); get("save").onclick = () => { if (controller.result) saveMeasurement(controller.result); }; ``` ## Operation contracts - NMRController is the convenient UI layer. connect(), measure(), disconnect(), and sweep methods return operation results: { ok: true, value } or { ok: false, error }. Check ok before displaying success. onError receives failures. - onStateChange runs immediately on subscription. Use canConnect, canMeasure, canDisconnect, busy and hasResult to control the UI. Read form fields before initiating the operation, because disabled fields are omitted by FormData. - onResult receives a measurement record. controller.result retains the latest successful record. Failed measurements do not replace it. - NMRDevice is the lower-level interface. Its async operations reject on error; use try/catch. Do not treat its return type as a controller operation result. - There is no immediate hardware stop command. Disconnect is not an emergency stop. Sweeps can stop after the current measurement completes. - Do not automatically retry a failed measurement or silently replay queued operations. - On UI teardown, wait for the active operation to finish, disconnect, then call graphs.dispose() and controller.dispose(). dispose() alone does not stop or disconnect hardware. ## Parameters and raw records All measurement parameters are required integers: - frequencyHz: 1..2147483647, Hz. - pulse1Cycles, pulse2Cycles: 0..32767, RF cycle counts, not microseconds. - phase1Degrees, phase2Degrees: 0, 90, 180, or 270 degrees. - pulseIntervalMs: 0..32767, ms. - measurementIntervalMs: 1..32767, ms. - scans: 1..32767, accumulation count. These are communication-format limits, not a guarantee of suitable physical operating conditions. A record contains source (instrument or demo), acquiredAt (UTC ISO timestamp), mode (single or double), parameters, points (2048), sampleIntervalMs (0.02), and raw (2048 pairs of channel values). Preserve raw, source, and acquisition conditions during analysis and saving. Do not overwrite raw with baseline-corrected values. ## Analysis, graphs, and saving ```js const analysis = analyzeMeasurement(record, { startMs: 1, endMs: 5, window: "hann", }); console.log(analysis.peak.hz); graphs.show(record, analysis); saveMeasurement(record); ``` analyzeMeasurement returns data, baseline, spectrum, and peak. Default baseline correction subtracts the mean of the final 100 points and truncates toward zero. FFT uses channel 1 + i * channel 2, a symmetric Hann window, and power-of-two zero padding. Analysis uses [startMs, endMs), with at least 4 samples. Peak frequency is an FFT-bin offset from the receiver frequency in Hz, not an absolute RF frequency or an interpolated estimate. NMRGraphs renders responsive SVG graphs at a fixed height. Defaults: FID 0..10 ms, FFT -10..10 kHz. The FID scale follows the analysis interval, so large early transients may be clipped. The analysis interval is highlighted. The colors option supports data1, data2 and fft. All graph APIs accept locale: "ja" (default) or "en" and a partial labels object. In NMRGraphs/createRecordPlots, use labels.fid and labels.fft with title, xLabel and yLabel. In the four curve functions, use labels: { title, xLabel, yLabel } directly. Labels are plain text, escaped in SVG; changing labels does not convert units. NMRGraphs also supports labels.fid.empty, labels.fft.empty, labels.peak.{empty,none,outside,value} and labels.status. The peak.value template supports {hz} and {outside}; status supports {tailPoints}, {displayEndMs}, {startMs}, {endMs}, {window}, {frequencyLimitKHz}. Omitted text uses the selected language. Unsupported locale/keys/placeholders or non-string labels throw TypeError. Set language when creating a view; dispose and recreate to switch it. nmrlink/graphs also exports createRecordPlots, createFrequencyPlot, createPulsePlot, createT1Plot and createT2Plot. These return SVG strings and can run in Node.js without a DOM. Use the graph reference pages for the input point structures; do not invent them. nmrlink/browser provides saveMeasurement(record), readMeasurement(file), saveGraphPng(svg, { filename, scale }), and formatFileTimestamp(acquiredAt). Saved filenames use JST while acquiredAt remains UTC. Reading saved JSON permits reanalysis without contacting the apparatus. ## Calibration and relaxation The root module exports frequency/pulse/T1/T2 sweep helpers, fitting functions and archive parsers. Consult the API reference and existing standard UI before implementing sweeps; reuse these helpers instead of duplicating serial commands or fit algorithms. - Frequency adjustment: Single measurements across a frequency range, compared within a specified spectral search band. - Pulse calibration: Single measurements across pulse1Cycles. Magnitude and common-phase signed signals are distinct. Do not independently phase-align each point if sign inversion is required. - T1: Double measurements, 180-degree pulse then tau then 90-degree pulse; fit A - B * exp(-tau / T1). - T2: Double measurements, 90-degree pulse then tau then 180-degree pulse. Echo analysis window follows the echo; fit against 2*tau using A * exp(-2*tau / T2). - Fit quality and acquisition-range warnings must remain visible. A fitted value is an estimate, not guaranteed calibration. ## Remote connection: unverified in a real environment nmrlink-server provides Node.js serial transport and Firebase remote operation. It is not published on npm; obtain it from the repository. Do not suggest npm install nmrlink-server as a supported installation path. Remote operation uses Firebase Authentication and Firestore, without billing registration, VPN, Cloud Functions or Cloud Storage. Device-side policy and single-user ownership control operation. UI-level hiding does not guarantee confidentiality against direct Firestore access. The remote setup has not been tested in a real deployment; prefer direct connection for actual use. Never expose service-account keys, .env.local, or access-policy.json in a static site. ## Documentation and examples - Documentation: https://masabando.github.io/nmrlink/en - Installation: https://masabando.github.io/nmrlink/en/guide/install - Supported browsers, Linux permissions and Snap: https://masabando.github.io/nmrlink/en/guide/browsers - First custom UI: https://masabando.github.io/nmrlink/en/guide/first - Measurement control and Node.js: https://masabando.github.io/nmrlink/en/guide/measurement - Signal analysis: https://masabando.github.io/nmrlink/en/guide/analysis - Graph previews and labels: https://masabando.github.io/nmrlink/en/guide/graphs - Save and load: https://masabando.github.io/nmrlink/en/guide/save - API index: https://masabando.github.io/nmrlink/en/reference/api - Analysis conventions: https://masabando.github.io/nmrlink/en/reference/analysis - Remote architecture (unverified): https://masabando.github.io/nmrlink/en/guide/remote - Remote administrator setup: https://masabando.github.io/nmrlink/en/guide/remote-admin - Remote client integration: https://masabando.github.io/nmrlink/en/guide/remote-ui - Standard Web UI: https://masabando.github.io/nmrlink/ui/ - Frequency tuning UI: https://masabando.github.io/nmrlink/ui/frequency/ - Pulse calibration UI: https://masabando.github.io/nmrlink/ui/pulse/ - T1 measurement UI: https://masabando.github.io/nmrlink/ui/t1/ - T2 measurement UI: https://masabando.github.io/nmrlink/ui/t2/ - Minimal custom UI source: https://github.com/masabando/nmrlink/tree/main/examples/direct - Standard measurement UI source: https://github.com/masabando/nmrlink/tree/main/website/components/measurement - Repository and license: https://github.com/masabando/nmrlink - Apparatus developer: https://researchmap.jp/kondo_yasushi The standard measurement UI uses one /ui/ page for both languages; use ?lang=en or ?lang=ja. Switching language preserves inputs, the connection and results. Frequency tuning uses /ui/frequency/, pulse calibration uses /ui/pulse/, T1 measurement uses /ui/t1/ and T2 measurement uses /ui/t2/, with the same language options. Client-side navigation between these five pages shares the device connection and retains each page's inputs/results. Finish active operations before switching. Japanese documentation has the same paths without /en. Library-created exceptions and warnings use English messages with stable codes. Graph locale only controls graph labels; localize user-facing errors separately. ## Error and warning contracts - Library-created errors retain their Error/TypeError/RangeError/AggregateError class and add code (a stable string) and details (an object). ERROR_CODES is exported from nmrlink; for example ERROR_CODES.INVALID_FFT_RANGE. - Translate user-facing messages by code, never by matching error.message. Unknown codes need a general localized fallback. English message wording is explanatory and may change. - Browser/OS, custom transport and user callback errors at operation boundaries are wrapped with English messages; cause retains the original exception. AggregateError.errors retains cleanup failures. - analyzePulseCalibration, analyzeT1 and analyzeT2 keep warnings as English strings and additionally return warningDetails: an array of { code, message, details } in the same order. Translate warningDetails by code. Old archives without warningDetails are reanalyzed normally. - Graph locale changes graph text only. It does not translate exceptions or warnings.