Troubleshooting

Troubleshooting

This page collects the usual problems - a device that does not show up, missing permissions, firmware that is too old, a trigger that never fires, streams that stop early, decoders - and says where the logs are and how to report a problem.

openSciLab 0.1 is a beta, and much of the new firmware has not been checked on real hardware yet. If something fails on a board but works with the matching simulator, please report it.

The application does not start

• Windows stops it with SmartScreen, macOS refuses an app that is not signed, Linux lacks FUSE for the AppImage or a library of Qt (could not load the Qt platform plugin "xcb"): see Installation → First start.
• macOS, running from source: Could not find the Qt platform plugin "cocoa". iCloud Drive marked the files of the virtual environment as hidden. openSciLab copies the Qt plugins to ~/Library/Caches/openSciLab/qt-plugins by itself; if even that fails it says so and suggests chflags -R nohidden on the plugin folder. The lasting fix is a virtual environment iCloud ignores (python -m venv .venv.nosync && ln -s .venv.nosync .venv).
• Settings or window look wrong: View → Layout → Reset layout puts the window back, a right click on a tool bar → Reset toolbar the bar, Defaults in the settings every setting. A settings file that cannot be read is kept as <name>.bad next to the new one. To try a start with fresh settings without losing the old ones, set OPENSCILAB_SETTINGS_DIR to an empty folder.

A device does not appear in the device list

The device list (Devices in the sidebar, part Available) shows only devices openSciLab can use:

• Pico boards with the openSciLab Pico firmware (USB ID 1209:3020), as openSciLab Pico on and the port,
• Arduino boards, recognised by their USB identifiers, as Arduino on and the port,
• DSLogic analyzers, Rigol oscilloscopes with the bridge app, connected remote devices,
• entries to add a device by hand (Network device..., Multiple devices..., Rigol oscilloscope by address...) and the simulators.

Other serial ports are left out on purpose. Check, in this order:

1. Wait or press Refresh. The list looks for devices every 2 seconds (Settings → Devices → Look for devices every).
2. The cable. Many USB cables only charge; try one that carries data.
3. Linux permissions. Without the group dialout (uucp on Arch) the ports cannot be opened: sudo usermod -aG dialout "$USER", then log in again. Right after plugging in, ModemManager may probe a new /dev/ttyACM* port for a few seconds.
4. The firmware. A Pico in bootloader mode or with other firmware (e.g. MicroPython) is not listed; a notice below the list says so and offers Install firmware.... A board with an older analyzer firmware is listed, but asks for an update when connected (see below). Devices → Connected hardware lists every board and device on the computer with its firmware; its State column says up to date, update available, no openSciLab firmware or board not recognised. See Firmware.
5. Devices in the network. A Pico W is added with Network device... (address and port), a Rigol without the bridge app with Rigol oscilloscope by address.... Remote devices only connect when Settings → Remote devices → Accept remote devices is on, with the same port and token on both sides. A firewall must let the connection through; macOS 15 asks once whether openSciLab may find devices on the local network.
6. DSLogic: it needs a udev rule on Linux and the WinUSB driver on Windows, and DSView must not use it at the same time; see DSLogic.

When connecting fails, the reason is shown in red below the device list (… could not be connected: …). A device that was unplugged or stopped answering is marked on its card (… does not answer. Check the connection, then Reconnect.); press Reconnect.

Firmware too old (or missing)

Every version of openSciLab works only with the firmware it comes with (the Pico firmware speaks protocol 8). A board with older firmware - also that of PiPiLogicAnalyzer or of the original LogicAnalyzer - is recognised, but only to offer the update: connecting it shows Firmware update needed. Update firmware... opens Connected hardware; press Update firmware in the board's row. Capture settings and profiles are kept. All boards of a multi device set need the same firmware.

If the update itself fails:

• There is no firmware image for this board: the application found no images. The builds contain them; from source, unpack openSciLab-firmware-pico-uf2.zip into firmware/uf2/ (see Installation).
• The bootloader cannot tell a Pico from a Pico W (or a Pico 2 from a Pico 2 W), so openSciLab asks Which board is it?. An image for the wrong chip (RP2040 or RP2350) is refused.
• The board does not reappear: on Linux the bootloader drive (RPI-RP2, RP2350) has to be mounted below /media, /run/media or /mnt. As a last resort hold BOOTSEL while plugging the board in and copy the .uf2 file onto the drive by hand (Firmware).
• Arduino boards are flashed with avrdude, bossac or esptool. … is not installed means the tool was not found: install it, or put it into the folder tools of the settings directory.

The trigger never fires

While the data view waits, its state says Armed, waiting for the trigger; Stop (Shift+F5) ends the wait. Then:

• Is the signal there at all? Capture once with the trigger None: start capturing at once and look at the channel. Check GND between board and circuit.
• Edge: the right channel, and Falling edge ticked or not.
• Pattern: a pattern compares levels, not edges, and fires as soon as the channels match; if they match already when the capture starts, it fires at once. The pattern starts at First channel and runs over consecutive channels of one trigger group (on a Pico channels 1-21 or 22-24); the dialog names the usable channels.
• External trigger: on a Pico the trigger input is GP1, a 3.3 V input - 5 V signals need a level shifter or a divider.
• Multi device set: the board of the trigger channel evaluates the trigger and has to capture at least one channel itself.
• Sequences: a stage with a time limit that runs out starts the sequence over.
• Streams of a Pico have no trigger of their own; Evaluate the trigger in the application looks for the trigger in the stream instead (see Data view).
• Flows and the command line: a capture in a flow waits until it triggers or the flow is stopped (openscilab run --timeout gives up after a number of seconds); openscilab-cli capture --timeout stops a capture that did not trigger.
• Simulators: check the Signals tab - with Nothing connected every channel stays low.

A stream stops early (overflow)

A stream sends the samples over USB while capturing. When the device produces more than the connection or the computer takes, it ends early with a message such as The USB connection could not keep up with the stream, so it stopped early. Lower the rate or capture fewer channels. The samples received until then are kept.

• Stay within the limits. A Pico streams 800 kB/s: 800 kHz with 8 channels, 400 kHz with 16, 200 kHz with 24 - over USB only, not over WiFi and not as a multi device set. An Arduino Uno streams far less (about 11.5 kB/s). For short, fast captures use the buffer mode (Buffer (device memory) under Acquisition) instead.
• Let openSciLab read the device undisturbed. Settings → Devices → Read devices on USB in a process of their own (on by default) keeps drawing, flows and scripts from delaying the reading. Read devices with a higher priority also helps on a busy computer (macOS and Linux ask for the administrator's password).
• The computer: avoid hubs shared with cameras or disks, close programs that load the CPU, and record long streams to a fast disk.
• To see how a flow copes with an overflow, use a simulator: Devices → Simulate faults, the simulator, Overflow the next stream.

Protocol decoders

A decoder is missing. Help → Decoder search paths... shows how many decoders were loaded and from which folders. Own decoders are ordinary sigrok decoders - a folder with __init__.py and pd.py - in the folder decoders of the settings directory (or a folder given with --decoders or OPENSCILAB_DECODERS). Give yours an id of its own: for the same id the shipped decoder is found first. Decoders are loaded once; restart openSciLab after changing one. A decoder whose Python files cannot be imported is left out of the list: Help → Decoder search paths... names it with the error (the log has it too); try it in sigrok-cli or PulseView.

A decoder shows nothing or nonsense.

• Open its settings (Decoder settings in the Decoders tab) and check the channels and options (baud rate, bit order, clock polarity …).
• Capture at least four times faster than the fastest signal of the bus.
• The first frame is often cut off by the start of the capture; look at the following ones, or use a trigger.
• With Decode automatically switched off, press Decode now.

Decoders are Python code that is executed: only add decoders you trust. More in Protocol decoders; for the C64 bus see C64 bus.

Where the logs are

What	Where
Problems of flows, the steps of a running flow, the application log	View → Console (Ctrl+J), tabs Problems (a double-click shows the node), Execution and Log
Everything about a device	its device card, tab Details → Copy the details
The communication with the devices	start with --debug-driver: driver_debug.log in the settings directory
An error nobody caught (the status bar said An error occurred)	crash.log in the settings directory, with the traceback; Help → Open the log folder opens it
A crash of the application itself (it vanished)	faults.log in the settings directory: the stacks at the moment it died, also of a device process
A device process that stopped answering	the device is shown as disconnected after 10 s without a sign of life, or when a call took longer than 60 s; the application log says so. Connect it again
Command line errors	one line on stderr; OPENSCILAB_TRACEBACK=1 shows the traceback

To start a build with --debug-driver: openSciLab.exe --debug-driver in the folder on Windows, /Applications/openSciLab.app/Contents/MacOS/openSciLab --debug-driver on macOS, the AppImage with --debug-driver on Linux. Devices on USB are read in a device process of their own, which passes on warnings and errors only; for the full log of a Pico, Arduino or DSLogic, switch off Settings → Devices → Read devices on USB in a process of their own and connect the device again while you record.

The settings directory is %APPDATA%\openSciLab (Windows), ~/Library/Application Support/openSciLab (macOS) or ~/.config/openSciLab (Linux).

Reporting a problem

Open an issue with

• the version (Help → About openSciLab) and the operating system,
• the device and its details (Copy the details on the Details tab),
• what you did, what you expected and what happened,
• if possible a capture file (.lac) or a flow that shows it, and the log.

Security problems do not belong in an issue; see SECURITY.md.