QR Code Scanner Widget

Who it’s for

Dashboard authors who need someone to scan a QR code straight into ThingsBoard ask “how do I turn a scanned code into an attribute update or an RPC call without building my own camera integration?” They are usually building for a field technician checking an asset tag, a warehouse worker confirming a bin or pallet, or an operator logging in at a shared terminal by badge. The scan has to work on a phone, a tablet, or a laptop webcam, without any device-specific setup.

What it does

A warehouse worker scans a bin label reading BIN-004521. The widget calls onScanSuccess with that text, the raw decode result, and ctx — the handler can write it to an attribute, send an RPC, or call any other dashboard API, in the same function, with no rule chain in between.

• Two scan modes in one widget — a live camera feed or an uploaded image. Restrict Supported scan types to one mode and the switch between them disappears
• Picks the rear camera automatically — when a device has more than one camera, the widget looks for a label containing “back”, “rear” or “environment” and starts on that one; a dropdown lets you switch cameras at any time, even mid-scan
• Flashlight and zoom appear only when the camera supports them — no dead buttons on hardware that can’t do either
• Pauses after every successful scan — scanning stops the instant a code is decoded and stays stopped until someone taps resume, so one scan can’t trigger the handler twice
• Runs your own JavaScript on every result — onScanSuccess and onScanFailure receive the decoded text, the raw result, and the widget’s ctx, so you decide what a scan does
• Scans whatever is in front of the camera or in the uploaded image, one at a time; it does not keep a scan history or process a batch of images in one go

Requirements

Camera mode needs a secure context — the dashboard served over HTTPS, or opened at localhost — and the browser must grant camera permission when asked. Without both, camera mode fails immediately; Image mode keeps working either way, since it only reads a file the user picks.

How to set up

Scan handlers

Setting	Default	Effect
onScanSuccess	Shows a toast with the decoded text	Runs every time a code is decoded. Receives the decoded text, the raw decode result, and ctx. The field can’t be left empty, but it ships pre-filled with this default, so the widget works before you touch it
onScanFailure	Not set	Runs only on a genuine scan error. The scanning library reports “nothing found yet” many times a second while it searches for a code — that noise is filtered out before it reaches this handler

Scan mode & camera access

Setting	Default	Effect
Supported scan types	Camera & Image	Sets which mode or modes are offered. Camera or Image alone removes the mode switch
Ask user to start scan	On	Shows a “Start scanning” button and waits for a tap before requesting the camera or opening the file picker. Off, camera mode requests access as soon as the widget loads

While you are editing the dashboard, the camera never starts on its own, even with Ask user to start scan off — you still get a “Start” button, so arranging the widget doesn’t trigger a permission prompt every time you open the editor. It starts normally once the dashboard is being viewed.

How to customize

• To hide the flashlight control even on cameras that support it — turn off Show flashlight button when supported.
• To hide the zoom slider even on cameras that support it — turn off Show zoom slider when supported.

Tips

• Scanning stays paused after a successful read until someone taps resume — there’s no automatic resume, so don’t rely on the widget picking scanning back up by itself.
• Switching cameras from the dropdown restarts the video feed rather than just relabeling it, so a scan already in progress on the old camera is interrupted.
• A small API is exposed at ctx._qr — list cameras, read the active one, switch cameras, or check whether the widget is currently scanning. Use it if you want a header button or a custom action to control the camera instead of the built-in selector.
• Flashlight and zoom support come from the camera and the browser, not from this widget — a laptop webcam, for example, rarely reports either as supported, no matter the settings.