Getting Started

Overview

Smart.Industrial is a set of 54 Web Components for HMI, SCADA and test and measurement applications: faceplates, alarm management, process mimics, trends, instrument displays, statistical process control, machine state and electronic signatures. The components are built on the Smart UI framework and are distributed as the smart-industrial NPM package.

The package is independent from smart-webcomponents. It does not contain the Grid, the Scheduler or the other components of the Smart UI suite, and the suite package does not contain the Industrial components. An application that uses both installs both packages. The two packages can be loaded on the same page.

This guide covers:

• Installation
• Package contents
• A first screen
• Loading individual components
• Next steps
• TypeScript
• Angular, React, Vue and Blazor
• License key

Installation

Install the package with npm:

npm install smart-industrial

Package contents

A first screen

A page needs the base theme, the elements stylesheet and the script. The elements stylesheet is required: the theme provides the CSS variables and the elements stylesheet provides the styles of the components.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.default.css" />
    <link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.industrial-elements.css" />
    <script src="node_modules/smart-industrial/source/smart.industrial.js"></script>
</head>
<body>
    <!-- interactive: the faceplate raises setpointChange only while it is set -->
    <smart-faceplate id="tic101" tag="TIC-101" description="Reactor temperature" unit="°C"
                     process-value="72.4" setpoint="75" output="41.2" mode="auto" interactive></smart-faceplate>

    <smart-status-tile label="Feed flow" value="78.4" unit="m³/h" state="ok" trend="flat"></smart-status-tile>

    <script>
        document.getElementById('tic101').addEventListener('setpointChange', function (event) {
            // Write the requested value to the control system here. Then set the
            // setpoint property from the value the control system reports.
            console.log('Requested setpoint:', event.detail.value);
        });
    </script>
</body>
</html>

The event handler above shows the convention of the components that act on a plant: the component raises a request event and the application confirms the value. A faceplate, a device control, a selector switch, a state machine, a jog panel or a momentary button does not change its own value when the operator acts on it, and the alarm grid, the alarm banner and the annunciator do not change an alarm when it is acknowledged. The component raises a request event, the application writes the value to the plant, and the application sets the property from the value the plant reports. This way the screen always shows the actual state of the plant, also when a write is rejected. The faceplate and the device control raise requests only when interactive is set; the state machine has it set by default.

The input controls are the exception: the knob, the bar graph, the bit field, the thermometer, the panel meter and the numeric keypad take the operator's value themselves and raise change after it, like a form input (the bar graph, bit field, thermometer and panel meter only when interactive is set). An application that writes such a value to a plant does it from the change event and sets the value back if the write fails.

Loading individual components

Each file under source/modules/ is a self-contained ES module, so a page can load only the components it uses. A module carries the script of its component, not its styles: the page loads the same two stylesheets as above.

<link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.default.css" />
<link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.industrial-elements.css" />
<script type="module" src="node_modules/smart-industrial/source/modules/smart.alarmgrid.js"></script>
<script type="module" src="node_modules/smart-industrial/source/modules/smart.alarmbanner.js"></script>

<smart-alarm-banner id="banner"></smart-alarm-banner>
<smart-alarm-grid id="alarms"></smart-alarm-grid>

The modules that are not components are loaded the same way. smart.industrial.connect.js, smart.industrial.units.js, smart.industrial.audit.js, smart.industrial.ai.js and smart.spc.js carry the framework and register on Smart.Industrial. smart.dsp.js and smart.decimate.js carry nothing but their functions: loaded after a module that brings the framework they register Smart.DSP and Smart.Utilities.Decimate, and loaded alone they are available as window.SmartDSP and window.SmartDecimate. The engineering maths guide shows how to load them in a Worker or in Node.

For pages that cannot load stylesheets, for example a portal page or a widget embedded in another application, the files under source/components/ contain the component, its stylesheet, the theme and the Industrial CSS variables in one script and render in shadow DOM. Each file defines the component tag with ui- after the prefix:

<script src="node_modules/smart-industrial/source/components/smart.ui.stacklight.js"></script>

<smart-ui-stack-light label="Filler 2" state="running"></smart-ui-stack-light>

The wrapper forwards attributes, properties, methods and events to the <smart-stack-light> element inside its shadow root. The inner element is also available through the nativeElement property.

Next steps

• Data. The components are set through properties. The Connect module routes tags from a WebSocket, an SSE stream, an HTTP poll or a custom client into component properties, including data quality and staleness.
• Display frame. smart-hmi-shell provides the ISA-101 display frame: a header, navigation with alarm counts, a main area and an alarm footer. The Themes and Styling guide describes the stylesheets and the ISA-101 themes.
• Records. Where a change has to be attributable, the E-Signature, Signature Block and Audit Trail components provide the client-side parts of 21 CFR Part 11. The Part 11 statement lists what the components provide and what the application has to provide.

TypeScript

The TypeScript definitions are included in the package. Import the component types from smart-industrial/source/typescript/smart.industrial with import type: the definitions have no code, and a project with verbatimModuleSyntax, the Vite default, rejects a plain import of a type.

import type { Trend } from 'smart-industrial/source/typescript/smart.industrial';

const trend = document.querySelector('smart-trend') as Trend;

trend.pens = [{ field: 'temperature', label: 'TIC-101.PV', unit: '°C', min: 0, max: 150 }];
trend.push({ timestamp: Date.now(), temperature: 72.4 });

The definitions also extend document.createElement() and document.querySelector(), so document.querySelector('smart-trend') is typed as Trend without a cast.

Angular, React, Vue and Blazor

The components are standard Custom Elements and can be used in any framework. Typed Angular and React wrappers are included in the package as smart-industrial/angular and smart-industrial/react. The Blazor components are in the Smart.Blazor.Industrial NuGet package. The frameworks guide describes the installation and the imports for each framework.

License key

Without a valid license key the components run in evaluation mode: the first component that checks the key shows a link to the license page and a "Rate us on GitHub" link at the bottom of the page for about ten seconds, and writes an evaluation notice to the browser console. The components themselves are not limited. Set the key once, before the first component renders. On a page that loads the bundle with a script tag, set it before the script, or put it on <body>:

<script>window.Smart = { License: 'YOUR-KEY' };</script>
<script src="node_modules/smart-industrial/source/smart.industrial.js"></script>

<body smart-license="YOUR-KEY">

window.Smart.License = 'YOUR-KEY' before the bundle has loaded throws, because window.Smart does not exist yet. In Angular, React and Vue applications the imports run first and create window.Smart, so set the property in the application's bootstrap file, after the imports and before the first component renders:

window.Smart.License = 'YOUR-KEY';

In Blazor, set Smart.Blazor.Industrial.License.Key = "YOUR-KEY"; in Program.cs. A single element can also be given the key through its unlockKey property.

The license agreement is EULA.pdf in the package; it allows the use of a trial version for evaluation, for 30 days. For pricing and license terms, contact sales@jqwidgets.com.