Troubleshooting and FAQ

Troubleshooting and FAQ

Connection

The Connect button does nothing / there's no port pop-up. Use Chrome, Edge, Opera or Brave (see Getting Started). Firefox and Safari don't support Web Serial. The page must be served over HTTPS or from localhost/file://.

My adapter isn't in the port list. Install the USB-UART driver (CH340, CP210x, FTDI) for your OS, and check that no other program (Arduino IDE, serial monitor) has the port open.

On Linux I get "permission denied". Add your user to the serial group (dialout on Debian/Ubuntu, uucp on Arch) and log in again.

No or bad data

Nothing appears in the log.

• Swap TX and RX — they must cross.
• Check the sensor has the right supply voltage and a common ground.
• Some sensors need a command before sending anything; make sure you picked the correct model.
• Check the baud rate in the sensor definition.

Every packet shows ❌ Bad checksum.

• Wrong sensor variant selected (e.g. SenseAir S8 004-0-0053 vs 004-0-0017).
• Frame length or start byte is off — frames look shifted in the log.
• Byte-stuffing is needed but not configured.
• eval and compare are compared with strict equality (===), so they must return the same type: 1 === true is false.

Values are wildly wrong. Check byte order (big- vs little-endian), signed vs unsigned, and scaling factors against the datasheet. Use >>> 0 to force 32-bit unsigned values.

My SEN55 doesn't answer at all. The SEL pin (pin 5) must be floating at power-up for UART mode; tied to GND it starts in I²C mode. SEL is only read at power-up, so power-cycle the sensor after changing it. See SEN5x UART Protocol.

My SEN55 shows huge values for the first few seconds. Right after start, the sensor reports "unknown" as 0xFFFF / 0x7FFF, which decode to values like 6553.5 µg/m³ or 163.8 °C. They disappear once the sensor has valid data.

Custom JSON

My JSON file doesn't load.

• Validate it at https://jsonlint.com.
• Don't write raw hex numbers (0x42); use 66 or "0x42".
• All expressions must be strings.
• Open the browser DevTools console (F12) for error details.

My inherited sensor behaves like the parent. The inherits_from value must match the parent's name exactly. Look for "Base sensor not found" in the console. See Inheritance.

My multi-command sensor stops after init or returns garbage. Increase postDelay_ms values; many sensors need tens to hundreds of milliseconds per command. Remember start_command is ignored in multi-command mode. See Multi-Command Sensors.

Webhooks

I get 429 Too Many Requests. Increase the webhook interval. See Webhooks.

Placeholders are sent as null. Use the signal name without the unit in brackets, spelled exactly as in the chart signal list.

General

Does it work offline? Yes, after the page has loaded (and with a local sensors.json if the default list can't be fetched). Only webhooks need a network.

Is my data sent anywhere? No, except when you enable webhooks, which are routed through the configured CORS proxy.

Can I use it on a phone? The supported targets are desktop Chromium browsers. Web Serial support on mobile is limited, so a desktop or laptop is recommended.

Still stuck? Open an issue with your browser version, sensor model, adapter and a few lines from the log.