Trends and signals

Scope `<smart-scope>`

Scope is an oscilloscope display for time-domain signals.

JavaScript TypeScript Angular React Vue Blazor

<smart-scope> · 25 properties, 11 methods, 2 events · source/modules/smart.scope.js

Usage in React

The React wrapper is the Scope component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.

import { Scope } from 'smart-industrial/react/scope';

const ref = useRef<Scope>(null);

<Scope ref={ref} sampleRate={42}
    onChannelVisibilityChange={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.push({});

Properties

Prop	Type, default	Description
`channels`	array	Sets or retrieves the channels as [{ field, label, unit, color, voltsPerDivision, offset, visible }]. field is the key under which a pushed block carries the samples of the channel. A voltsPerDivision of null autoscales the channel; offset is in divisions from the centre line. Assign a new array to update the component.
`sampleRate`	number 1	Sets or retrieves the sample rate in samples per second. The timebase, the trigger's holdoff and every measurement follow from it. A value that is not a positive, finite number is taken as 1, with one console warning.
`timePerDivision`	number 0.001	Sets or retrieves the timebase in seconds per horizontal division. One screen is this times horizontalDivisions. A value that is not a positive, finite number is taken as 1 ms, with one console warning. A screen holds at most 2 000 000 samples; a longer timebase at the sample rate is shortened to fit, and the header shows the timebase drawn.
`horizontalDivisions`	number 10	Sets or retrieves how many divisions the graticule has across. From 1 to 100: a larger value draws 100, and NaN, Infinity or a value below 1 draws the default 10, with one console warning.
`verticalDivisions`	number 8	Sets or retrieves how many divisions the graticule has down. From 1 to 100: a larger value draws 100, and NaN, Infinity or a value below 1 draws the default 8, with one console warning.
`triggerSource`	string	Sets or retrieves the field the trigger watches. Empty triggers on the first channel.
`triggerLevel`	number 0	Sets or retrieves the level the source has to cross, in the source's units. Drawn as an arrow at the right edge and a dotted line.
`triggerEdge`	ScopeTriggerEdge rising	Sets or retrieves which way the source has to cross the level.
`triggerMode`	ScopeTriggerMode auto	Sets or retrieves the behaviour without a trigger. auto free-runs and captures the newest screen when nothing has triggered for about two screens; normal keeps the last capture until the next trigger; single captures once and stops until run or single arms the trigger again.
`triggerPosition`	number 0.1	Sets or retrieves the horizontal position of the trigger point on the screen, from 0 at the left edge to 1 at the right edge. 0.1 leaves one division of pre-trigger data, which shows what happened before the edge.
`holdoff`	number 0	Sets or retrieves how long after a trigger, in seconds, another is ignored, for a burst or a pulse train where only the first edge should trigger.
`triggerHysteresis`	number 0	Sets or retrieves how far past the level, in the source's units, the signal has to have been on the near side and has to reach on the far side for a crossing to count. A spike that pokes through the level and falls back is not an edge. The trigger point stays at the level crossing.
`historyLength`	number 0	Sets or retrieves how many samples each channel's ring keeps. 0 keeps four screens' worth. A block larger than the ring keeps only its newest samples. At most 8 000 000 samples per channel; a larger value (Infinity included) holds 8 000 000.
`mode`	ScopeMode yt	Sets or retrieves the display mode. yt draws every channel against time; xy draws the second channel against the first, for Lissajous figures and I-V curves.
`cursorA`	number	Sets or retrieves the first time cursor, in seconds from the trigger. null hides it. With both cursors set the readout shows their interval, its reciprocal, and each channel's value at each cursor.
`cursorB`	number	Sets or retrieves the second time cursor, in seconds from the trigger. null hides it.
`measurements`	array ["vpp","vrms","frequency"]	Sets or retrieves the automatic measurements shown in the readout for each visible channel: vpp, vrms, vmean, vmax, vmin, frequency, period, riseTime, fallTime and dutyCycle. The frequency is measured from mid-level crossings with hysteresis, averaged over every full period in the record; rise and fall times are measured from 10% to 90% on the first edge.
`showGrid`	boolean true	Determines whether the graticule is drawn.
`showLegend`	boolean true	Determines whether the channel legend is shown. The legend has one button per channel with its scale, which shows or hides the channel.
`showMeasurements`	boolean true	Determines whether the measurement readout is shown.
`showTriggerMarkers`	boolean true	Determines whether the trigger level and trigger time are marked on the graticule.
`paused`	boolean false	Determines whether pushed blocks are dropped. The display holds its last capture.
`label`	string	Sets or retrieves the scope's name, shown in the header and in the accessible name.
`precisionDigits`	number 3	Sets or retrieves how many significant figures a value is printed with in the readouts. Clamped to 1-21 when formatting; a value that is not a number shows 3.
`lineWidth`	number 1.4	Sets or retrieves the width of a trace in pixels.

Methods

Method	Description
`push(block: object): boolean`	Appends a block of samples per channel and runs the trigger over it. Returns false when the scope is paused, has no channels, or the block is empty. A null, empty, non-numeric or infinite sample is no reading: a gap in the trace and in every measurement, never 0. `block` object { field: samples, .. } with an array or typed array per channel, or a plain array for a single-channel scope, which goes to the first channel.
`clear(): void`	Removes every sample and the capture.
`run(): void`	Re-arms the trigger and resumes after stop or a single capture.
`stop(): void`	Stops capturing until run or single is called.
`single(): void`	Arms the trigger for one capture and then stops.
`forceTrigger(): boolean`	Captures the newest screen regardless of the trigger. Returns false when there is nothing to capture.
`autoSet(): void`	Sets the timebase to show two or three cycles of the trigger source and the scale of every channel to fill about six divisions, based on the record on screen. This is the Auto Set function of an oscilloscope. The timebase is set only from a frequency measure() accepts, on the source's new scale - from the screen, or else from the whole ring; with none (DC, noise, a single transient) the timebase is left unchanged.
`capture(): object`	Returns the record on screen as { time, sampleRate, triggerIndex, triggered, channels }, where channels maps each field to a copy of its samples and time is the start of the record relative to the trigger, in seconds. Returns null before the first capture.
`measure(field?: string): object`	Returns the automatic measurements of the captured record for one channel as { vmax, vmin, vpp, vmean, vrms, frequency, period, riseTime, fallTime, dutyCycle }, with NaN where a measurement is undefined. Frequency, period and duty cycle are measured from rising mid-level crossings with hysteresis and are NaN (shown as "--") unless the swing is at least a fifth of a division on the channel's scale, the record holds at least two full periods, and the periods agree within 25 % - so DC, noise and a single transient have no frequency. The duty cycle is taken over the whole periods. Rise and fall time are NaN when the swing is too small to have edges. Returns null before any capture. `field` string The channel's field. Defaults to the trigger source.
`toggleChannel(index: number, visible?: boolean): void`	Shows or hides one channel and raises the channelVisibilityChange event. `index` number Which channel. `visible` boolean Force a state instead of toggling.
`invalidate(): void`	Redraws the plot on the next animation frame, so that many pushes between two frames cost one draw.

Events

The data of an event is in event.detail. trigger reports a screen the scope has already captured, and in single mode the scope stops itself after it. channelVisibilityChange follows a channel the scope has already shown or hidden in channels.

Event	Description and detail
`onTrigger` trigger	This event is triggered on every capture, on a trigger, or on an auto free-run. `triggered` boolean True for a real trigger, false for an auto free-run capture. `source` string The field triggered on. `level` number The trigger level. `time` number The record's start relative to the trigger, in seconds.
`onChannelVisibilityChange` channelVisibilityChange	This event is triggered when a channel is shown or hidden from the legend or through toggleChannel. `index` number Which channel. `field` string The channel's field. `visible` boolean Whether it is now drawn.

Types

`type ScopeTriggerEdge`

'rising' | 'falling'

`type ScopeTriggerMode`

'auto' | 'normal' | 'single'

`type ScopeMode`

'yt' | 'xy'

CSS variables

The component declares 4 CSS variables; the CSS page shows how to set them.

--smart-scope-height --smart-scope-plot-background --smart-scope-grid-color --smart-scope-axis-color