Docs / Contact / devices/troubleshooting

Troubleshooting

I don't see a Device tab

Three gates, in order:

1. The entity must be MQTT-enabled and not a group. Fanouts are routing targets, not hardware.
2. You need edit permission on the entity. Provisioning binds hardware and writes credentials, so viewers don't get the tab. Ask an admin for edit rights on the entity.
3. The tab renders a fallback if your browser has no WebSerial. See below.

"This browser doesn't support WebSerial"

Chrome, Edge, Opera, and Firefox 144+ implement WebSerial. Safari and iOS do not. There is no flag or extension that changes this.

Two ways forward: reopen the page in a supported browser, or use tendrl-dev-mcp. The same binary offers a CLI and an MCP server, so you can drive the board from a terminal or from an AI assistant with no browser involved.

Connect fails, or the port isn't listed

• Something else owns the port. Only one program can hold a serial port. Close mpremote, Thonny, the OpenMV IDE, the Arduino serial monitor, or any screen/minicom session on that board, then retry.
• It's a charge-only cable. Very common, and it looks exactly like a dead board. Try a different USB cable.
• Linux permissions. Your user needs access to the tty device, usually by joining the dialout group (sudo usermod -aG dialout $USER), then logging out and back in.
• No USB-serial driver. Some boards use a CH340 or CP210x bridge that older systems don't ship a driver for.

The board connects but doesn't identify itself

The tab enters the raw REPL to ask the board what it is. If the board is stuck in a tight loop from a previous main.py, it may never answer. Use Reset, which pulses the hardware reset pin and works even when the device is frozen, or hold the interrupt while it boots.

A board that connects but shows raw platform strings instead of a friendly name simply has no profile. It still works; you just don't get firmware downloads for it.

Flashing can't connect to the boot ROM

Put the board into bootloader mode by hand: hold BOOT while plugging it in, or hold BOOT and tap RESET. See Flashing MicroPython.

Remember that flashing is ESP32-family only. Pico W uses UF2; OpenMV uses the OpenMV IDE.

After a flash the board stays on "Connecting…" or won't respond

Right after a flash the chip often comes up in the ROM bootloader instead of MicroPython, so it's silent and the tab can't identify it. This is why the flasher asks you to unplug the board and plug it back in: a fresh power-up boots the new firmware cleanly. Do the replug, then click Connect again. On native-USB boards (ESP32-S2/S3) the replug is mandatory, since their USB re-enumerates on reset. If it's still silent, press the board's RESET button once after replugging.

Provisioning fails with "ROMFS is not enabled on this device"

The Tendrl firmware (ROMFS) install needs a MicroPython build with a ROM partition. If you see this, the board is running stock firmware without one. Choosing Tendrl firmware normally flashes the right build for you first: let it run the flash + replug step, then it deploys the SDK. If you flashed a plain micropython.org build yourself, either re-provision with Tendrl firmware, or pick Existing firmware to install into the filesystem instead.

On OpenMV this option isn't offered at all, and shouldn't be forced. OpenMV's ROM partition ships full of the camera's built-in ML models, so there's no room for the SDK; OpenMV installs precompiled .mpy into /flash/lib instead. See Install paths by board.

The SDK won't install over Wi-Fi (mip)

On OpenMV, it can't. OpenMV's MicroPython firmware ships without the mip module, so no on-device installer exists, and it isn't needed: the Device tab pushes precompiled .mpy over serial instead, which is the normal OpenMV path. If you need to install by hand, run mpremote from your computer to copy the files over USB:

mpremote connect auto mip install --target=/flash/lib https://app.tendrl.com/api/public/sdk/v1/latest/mpy/package.json

On other boards, a mip install failure is almost always Wi-Fi: the device has to reach your Tendrl server to fetch packages. Check the credentials you provisioned, and watch the Terminal for the join attempt.

The device provisioned but never comes online

Watch the Terminal after the reset. In order, you should see the Wi-Fi join, then the MQTT connect.

• Stuck at Wi-Fi: wrong SSID or password, or a 5 GHz-only network. Most of these boards are 2.4 GHz only.
• Wi-Fi joins, MQTT doesn't: the most common cause is a stale API key. If the key was rotated after this device was provisioned, its old secret is dead; re-provision with the current one.
• Nothing at all: check that main.py doesn't crash before the client starts. Open it in Files and run it manually to see the traceback.

Once a board is reporting reliably, an offline alert is how you find out about the next time it stops, without watching the Entities list.

I unchecked an add-on but its files are still there

Use Full redeploy rather than Sync changes. Sync only rewrites files that are missing or have changed size, which misses a same-size edit. Note that both modes delete deselected packages, but deletion is bounded by the managed set, so your on-device databases and your own modules are never touched. See What will change.

A camera resolution is greyed out

Either it's above your sensor's known ceiling (the sensor chip is read at connect, and OpenMV camera modules are swappable, so this is about the sensor and not the board), or the sensor rejected it earlier in this session and it's been remembered. See Resolution and quality.

Capture fails with a frame buffer error

Drop the JPEG quality or the resolution. On sensors with a hardware JPEG encoder the frame buffer is bounded, and a busy scene at a large framesize can overflow it even below the quality cap of 95.

The camera preview froze

Something took the REPL. A running script, a provisioning run, or a file operation all preempt the browser-driven live loop, and the loop deliberately stops when you switch away from the tab so it isn't burning frames in the background. Come back to the tab and start it again.

← Back to Contact docs