Installation

Installation

This page covers where to download openSciLab, what to do on the first start on Windows, macOS and Linux, how to run it from source, and how to update it.

openSciLab 0.1 is a beta. The application and the simulators are covered by automated tests. The firmware is built for every supported board and runs in host tests and simulators, but much of the new firmware (Pico protocol 8, the Arduino firmware, the Rigol bridge app) has not been checked on real hardware yet. You can try everything without hardware first; see Getting started.

Downloads

Ready-to-run builds are on the releases page. The first release under the name openSciLab is 0.1.0b1, marked as a pre-release.

System	File	How to start
Windows (x64)	openSciLab-<version>-windows-x64.zip	unzip, run openSciLab\openSciLab.exe
macOS (Apple Silicon)	openSciLab-<version>-macos-arm64.dmg	open, drag openSciLab.app to Applications
macOS (Intel)	openSciLab-<version>-macos-x64.dmg	as above (tagged releases only)
Linux (x86_64)	openSciLab-<version>-linux-x86_64.AppImage	make it executable and run it
Linux (x86_64)	openSciLab-<version>-linux-x86_64.tar.gz	unpack, run openSciLab/openSciLab

Further files of a release:

File	Contents
openSciLab-firmware-pico-uf2.zip	the openSciLab Pico firmware for every board (openSciLab-pico_<BOARD>[_Turbo].uf2)
openSciLab-firmware-arduino.zip	the openSciLab Arduino firmware images
openSciLab-bridge.apk	the bridge app for Rigol DHO900 oscilloscopes
SHA256SUMS.txt	checksums of all files

The applications contain everything they need: Python, Qt, the protocol decoders, the example library and all Pico firmware images. Nothing else has to be installed, and the application writes the matching firmware onto a Pico itself (see Firmware). The Pico zip is only needed to flash by hand or when running from source; the Arduino images and the bridge app are separate downloads for those devices.

latest-build: every push to main updates the pre-release latest-build. Its files carry a version such as 0.1.0b1-dev.1a2b3c4 (the commit). It is the newest state and is not tested beyond the automated tests; it has no Intel build for macOS.

To check a download, compare its checksum with SHA256SUMS.txt:

shasum -a 256 openSciLab-0.1.0b1-macos-arm64.dmg      # macOS
sha256sum openSciLab-0.1.0b1-linux-x86_64.AppImage   # Linux
certutil -hashfile openSciLab-0.1.0b1-windows-x64.zip SHA256   # Windows

First start

The builds are not code-signed, so every system warns once.

Windows

1. Unzip openSciLab-<version>-windows-x64.zip into a folder of your choice (not into the zip view of the Explorer).
2. Start openSciLab\openSciLab.exe.
3. SmartScreen reports an unknown publisher: choose More info → Run anyway.

Pico boards and Arduino boards appear as COM ports without a driver. A DreamSourceLab DSLogic needs the WinUSB driver; see DSLogic.

macOS

1. Open the .dmg and drag openSciLab.app to Applications.

2. Start it. macOS refuses the first start of an app that is not signed:

   • macOS 14 and earlier: right-click the app → Open, then Open again.
   • macOS 15 and later: after the first attempt, open System Settings → Privacy & Security, scroll down to the message about openSciLab and choose Open Anyway.

3. If macOS reports the app as damaged, remove the quarantine flag the download left on it:

   xattr -dr com.apple.quarantine /Applications/openSciLab.app

Serial ports of Pico and Arduino boards (/dev/cu.usbmodem…) need no driver and no permission. For devices in the network (Pico W, Rigol oscilloscope, remote devices) macOS 15 may ask whether openSciLab may find devices on the local network; allow it.

Linux

1. Make the AppImage executable and start it:

   chmod +x openSciLab-0.1.0b1-linux-x86_64.AppImage
   ./openSciLab-0.1.0b1-linux-x86_64.AppImage

   An AppImage needs FUSE. Where it is missing (containers, some minimal installations), install the FUSE package of your distribution, start it with --appimage-extract-and-run, or use the .tar.gz instead: unpack it and run openSciLab/openSciLab.

2. Allow access to serial ports once. Boards appear as /dev/ttyACM* or /dev/ttyUSB*, which belong to the group dialout on Debian, Ubuntu and Fedora (uucp on Arch):

   sudo usermod -aG dialout "$USER"

   Log out and in again for the group to take effect.

3. If Qt stops with could not load the Qt platform plugin "xcb", the system lacks a library Qt needs. On Debian and Ubuntu:

   sudo apt-get install libxcb-cursor0 libxkbcommon-x11-0 libegl1 libgl1 libfontconfig1 libdbus-1-3

A DSLogic needs a udev rule; see DSLogic. To flash a Pico, its bootloader drive (RPI-RP2 or RP2350) has to be mounted below /media, /run/media or /mnt, which desktop systems do by themselves.

Running from source

Requirements: Python 3.10 or newer and Git. The Python packages (PySide6-Essentials, NumPy, pyserial, pyusb, libusb-package, PyYAML) are installed by pip.

git clone https://github.com/deckerjulian/openSciLab.git
cd openSciLab
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
openscilab                         # or: python -m openscilab

Install with -e (editable) from the clone: the protocol decoders and the example library are read from the repository folders. The installation also provides the command line, openscilab-cli and openscilab run … (see Scripting); on Windows, openscilab-gui starts the application without a console window.

On Linux, Qt needs the system libraries listed under Linux above.

Firmware images. The repository does not contain the built firmware. To install firmware from an application running from source, unpack openSciLab-firmware-pico-uf2.zip of the release into firmware/uf2/ of the clone (or into the folder firmware of the settings directory), or build it yourself with firmware/build_all.sh (see firmware/README.md).

macOS with iCloud Drive. If the clone lives in a synced folder ("Desktop & Documents"), iCloud marks the files in .venv as hidden, and Qt skips hidden plugins. openSciLab detects this and loads the plugins from a copy in ~/Library/Caches/openSciLab/qt-plugins. Cleaner is a virtual environment iCloud ignores:

python -m venv .venv.nosync && ln -s .venv.nosync .venv

Developers: pip install -e ".[dev]" adds pytest and ruff; QT_QPA_PLATFORM=offscreen pytest runs the test suite. A packaged application is built on the target system with:

python -m pip install -r requirements.txt pyinstaller pillow
python packaging/make_icons.py build/icons
python -m PyInstaller packaging/openscilab.spec --noconfirm   # result in dist/

Options when starting

The application takes a few options, in a packaged build as well (openSciLab.exe on Windows, /Applications/openSciLab.app/Contents/MacOS/openSciLab on macOS, the AppImage on Linux):

openscilab capture.lac                      # open files on start-up
openscilab --decoders /path/to/decoders     # an extra folder of protocol decoders (repeatable)
openscilab --debug-driver                   # log the device communication to driver_debug.log

openscilab --help lists them (from source, or on macOS and Linux in a terminal).

Where openSciLab keeps its files

What	Where
Settings, profiles, simulator settings, logs	the settings directory: %APPDATA%\openSciLab (Windows), ~/Library/Application Support/openSciLab (macOS), ~/.config/openSciLab (Linux)
Saved projects, save dialogs without a project	~/Documents/openSciLab (changed in Settings → Data)

The environment variable OPENSCILAB_SETTINGS_DIR points openSciLab to another settings directory, for example to start once with fresh settings.

Updating

• Builds: download the new version and replace the old one (the folder on Windows, the app on macOS, the AppImage on Linux). Settings, profiles and projects stay where they are.
• From source: git pull, then pip install -e . again (the dependencies may have changed).
• Firmware: every version of openSciLab works only with the firmware it comes with. When a new version brings new firmware, a board with the older one is offered the update when you connect it, and Devices → Connected hardware shows update available in its row; see Firmware.

There is no update check in the application; watch the releases or the changelog.

To remove openSciLab, delete the application and, if you want, the settings directory and ~/Documents/openSciLab.