Operator screens and process graphics
Device Control <smart-device-control>
DeviceControl is a faceplate for a discrete device such as a motor, a pump or an on/off valve.
<smart-device-control> · 19 properties, 6 methods, 6 events · source/modules/smart.devicecontrol.js
Usage in React
The React wrapper is the DeviceControl 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 { DeviceControl } from 'smart-industrial/react/devicecontrol';
const ref = useRef<DeviceControl>(null);
<DeviceControl ref={ref} tag={'P-2101A'} interactive={true}
onCommandRequest={(event: CustomEvent) => console.log(event.detail)} />
// methods are called on the wrapper the ref holds, which calls the element
ref.current?.requestCommand('value');
Properties
| Prop | Type, default | Description |
|---|---|---|
tag | string | Sets or gets the device tag, the first word of the accessible name and of every event. |
description | string | Sets or gets the description shown beside the tag. |
kind | DeviceControlKind | Sets or gets the device type: motor, pump or generic devices are started and stopped, a valve is opened and closed. |
state | DeviceControlState | Sets or gets the device feedback as reported by the plant: running, stopped, starting, stopping, open, closed, opening, closing, fault or unknown. Feedback that matches the pending request completes the request. A fault is announced to assistive technology. |
commanded | string | Sets or gets the last command reported by the plant (start, stop, open or close), shown as the filled command button. A command reported by the plant replaces a pending request from the screen. |
mode | DeviceControlMode | Sets or gets who commands the device: auto (the sequence), manual (the operator), local (a field switch; the screen can request stop or close only) or outOfService. Set by the application in response to the modeRequest event. |
availableModes | array | Sets or gets the modes the operator may ask for, shown as buttons. An entry that is not a string is skipped. |
quality | DeviceControlQuality | Sets or gets the quality of the feedback: good, uncertain, bad or stale. Anything but good is shown as a badge and read out. Start and open are refused while the quality is bad or stale. Bad or stale feedback is drawn as not live: the lamp hollow and dashed, the state word grey and italic. |
interlocked | boolean | Sets or gets whether an interlock holds the device: start and open are refused while it does, and the reason is shown. |
interlockReason | string | Sets or gets the interlock's reason, in plain language. |
permissives | array | Sets or gets the start permissives as [{ label, met }]. Start and open are refused while one is not met, naming it. A permissive is met only when met is true, a non-zero number, or one of the strings 'true', '1', 'yes', 'on' or 'met'; 'false', 0, 'off', null and anything else are not met. An entry that is not an object is skipped. |
discrepancy | boolean | Sets or gets the application's finding that the feedback disagrees with the command, started, still stopped, shown as an alarm on the faceplate. |
faultText | string | Sets or gets the fault's text, shown and announced with the fault state. |
runHours | number? | Sets or gets the device's run hours, shown as a counter when given. |
startCount | number? | Sets or gets the number of starts, shown as a counter when given. |
interactive | boolean | Sets or gets whether the screen may command the device at all. Off by default: a command requested from a faceplate the application has not enabled is refused with a reason. |
pendingTimeout | number | Sets or gets how long a request is shown as on its way before it is dropped and writeTimeout fires, in milliseconds. A pending request keeps its deadline when the element is moved to another parent. |
showPermissives | boolean | Sets or gets whether the permissives are listed on the faceplate. |
compact | boolean | Sets or gets the compact form, for a strip of devices along an overview. It hides the description, the commanded text, the permissives and the counters, and keeps the tag, the quality badge, the mode chip, the lamp, the state, the notice, the commands (with Reset while faulted) and the mode buttons. |
Methods
| Method | Description |
|---|---|
requestCommand(command: string): void | Requests a command: start or stop, open or close. Raises the commandRequest event and shows the command as pending, or raises the blocked event with the reason when the command cannot be requested. A command the device kind does not take, such as open on a pump, is ignored without an event. The same command requested again within one second, or a start or open that is already pending, is dropped. A command the feedback already reports, such as start on a running pump, raises commandRequest without being shown as pending. Does nothing while the faceplate is disabled.command string The command. |
requestMode(mode: string): void | Requests a change of mode by raising the modeRequest event. The application responds by setting the mode property. Does nothing when the faceplate is not interactive or is disabled, when the mode is not in availableModes, or when it is already the current mode.mode string One of the availableModes. |
requestReset(): void | Requests a fault reset by raising the resetRequest event, while the state is fault. Does nothing when the faceplate is not interactive or is disabled. |
refuse(reason: string): void | Called by the application when it does not carry out the pending request. The request is no longer shown as pending and the reason is shown instead.reason string Why, in plain language. |
pendingCommand(): string | Returns the command shown as pending, or null. |
canRequest(command: string): boolean | Returns whether a command could be requested now. Stop and close need an interactive, enabled faceplate, in any mode. Start and open also need manual mode, live feedback (quality not bad or stale), no interlock and every permissive met. Returns false for a command the device kind does not take.command string The command. |
Events
The data of an event is in event.detail. commandRequest, modeRequest and resetRequest are requests: the device control raises them only while interactive is true, shows a command as pending, and keeps state and mode until the application sets them. A command still pending after pendingTimeout raises writeTimeout, blocked reports a refused command, and stateChange reports a new state from the application.
| Event | Description and detail |
|---|---|
onCommandRequest | This event is triggered when a command is requested. The application writes the command to the plant and reports the feedback through the state property; until then the faceplate shows the command as pending.tag string The device tag.command string start, stop, open or close. |
onModeRequest | This event is triggered when a mode is requested. The application answers by setting mode.tag string The device tag.mode string The requested mode. |
onResetRequest | This event is triggered when a fault reset is requested.tag string The device tag. |
onBlocked | This event is triggered when a start, stop, open or close command could not be requested: the screen is not interactive, or, for start and open, the device is not in manual or is under local control, the feedback is bad or stale, an interlock holds it, or a permissive is not met.tag string The device tag.command string The command.reason string Why, in plain language. |
onWriteTimeout | This event is triggered when a pending request got no feedback within pendingTimeout and was dropped.tag string The device tag.command string The command that was pending. |
onStateChange | This event is triggered when the feedback state changes.tag string The device tag.state string The new state.oldState string The previous state. |
Types
type DeviceControlKind
'motor' | 'pump' | 'valve' | 'generic'
type DeviceControlState
'running' | 'stopped' | 'starting' | 'stopping' | 'open' | 'closed' | 'opening' | 'closing' | 'fault' | 'unknown'
type DeviceControlMode
'auto' | 'manual' | 'local' | 'outOfService'
type DeviceControlQuality
'good' | 'uncertain' | 'bad' | 'stale'
CSS variables
The component declares 10 CSS variables; the CSS page shows how to set them.
--smart-device-width --smart-device-lamp-size --smart-device-panel --smart-device-header --smart-device-border --smart-device-ok --smart-device-warning --smart-device-critical --smart-device-accent --smart-device-neutral