PSLab App

Repository for the PSLab App for performing experiments with the Pocket Science Lab open-hardware platform.

This repository contains the PSLab application, a cross-platform app for performing science and engineering experiments using the Pocket Science Lab (PSLab) device. PSLab is an open-source hardware platform that combines multiple laboratory instruments into a single portable device, including an oscilloscope, multimeter, waveform generator, frequency counter, programmable voltage and current source, logic analyzer, I²C sensor interface, and many more experimental tools.

While the application primarily supports PSLab hardware, it also supports other compatible hardware boards, such as Labrador by EspoTek, expanding its capabilities for science and engineering experimentation across different hardware platforms.

The application provides an intuitive interface for interacting with supported instruments across multiple platforms.

Visit our website: https://pslab.io.

Download

The PSLab app is available for Android, iOS, Windows, macOS, Linux, and Web.

• Store listings and install guides: PSLab Application documentation
• Development builds (direct downloads): Download page

Sign up for the latest updates and test new features early by joining our beta program.

Buy

• You can get a Pocket Science Lab device from the FOSSASIA Shop.
• More resellers are listed on the PSLab website.

Communication

• The PSLab chat channel is on Gitter.
• Please also join us on the PSLab Mailing List.

Screenshots

Features

Instruments

Instrument	Description
Home Screen	Displays the status and version of the connected PSLab device.
Instruments	Provides access to PSLab instruments and experimental tools.
Oscilloscope	Visualizes variations in analog signals over time.
Multimeter	Measures voltage, current, resistance, and capacitance.
Logic Analyzer	Captures and displays digital signals for analyzing digital systems.
Wave Generator	Generates arbitrary analog and digital waveforms.
Power Source	Generates programmable voltage and current outputs.
Luxmeter	Measures ambient light intensity.
Barometer	Measures atmospheric pressure.
Accelerometer	Measures acceleration along different axes.
Gyrometer	Measures the rate of rotation.
Compass	Measures orientation relative to Earth's magnetic field.
Thermometer	Measures ambient temperature.
Gas Sensor	Detects gases such as NH₃, NOx, alcohol, benzene, smoke, and CO₂.
Robotic Arm Controller	Controls up to four servo motors of a robotic arm independently.
OLED Display	Displays graphics, animations, GIFs, and retro games on external I²C OLED displays.
Sound Meter	Measures ambient sound levels using the device microphone.

Supported Hardware

The PSLab app supports the following hardware devices:

Device	USB Vendor ID	USB Product ID	Firmware Requirement
PSLab v5	04d8	00df	Firmware v3.0 or higher
PSLab v6	10c4	ea60	Latest firmware recommended
EspoTek Labrador	03EB	2FE4	labrafrim_000_c03.hex

How to Use

PSLab

Android

To use the PSLab device with Android, you need:

• A PSLab device
• A USB OTG cable
• An Android device with USB Host (OTG) support
• The PSLab Android application

Connect the PSLab device to your Android device using the OTG cable. The application will automatically detect the device and establish communication.

iOS

Communicates with the PSLab device over Wi-Fi using an ESP-01 module. Compatibility may vary.

Windows, macOS, Linux, and Web

These platforms communicate with the PSLab device over USB serial. Before connecting the device, install the CP210x USB-to-UART Bridge Virtual COM Port (VCP) drivers for your operating system.

Download the drivers from:

https://www.silabs.com/software-and-tools/usb-to-uart-bridge-vcp-drivers?tab=downloads

Permissions

Android

The application requests the following permissions:

Permission	Purpose
Location	GPS logging and location-based features
Microphone	Audio oscilloscope functionality
Internet	Network connectivity
Storage	Reading and writing logged data
USB Host	Communication with supported USB hardware
Motion Sensors	Compass and motion-based features
Ambient Temperature Sensor	Device temperature measurements (optional)

iOS

The application requests the following permissions:

Permission	Purpose
Microphone	Audio oscilloscope functionality
Motion Sensors	Compass and motion-based features
Storage	Reading and writing logged data
Location	GPS logging and location-based features
Internet	Network connectivity

Desktop (Windows, macOS, Linux)

No runtime permissions are required.

Linux: Users must install the provided udev rules and add themselves to the dialout group to access USB serial devices.

Web

No runtime permissions are required.

EspoTek Labrador

The application also supports the EspoTek Labrador, an open-source electronic lab board that provides tools for electronics testing and experimentation.

For information about hardware, setup instructions, and supported capabilities, see:

• docs/espotek_labrador.md

Video Demo

• PSLab Android App Overview.
• Observing Sound Waveforms Using PSLab Device.
• Real-time Sensor Data Logging Using Pocket Science Lab.
• Generating and Observing Waveforms Using Pocket Science Lab.

Development Environment Setup

Project Overview

This is a Cross-platform application build with flutter and rust that supports:

• Android (primary platform)
• iOS (via Wi-Fi only)
• Linux
• macOS
• Windows
• Web

Required Software

Flutter & Dart

• Flutter (stable channel)
• Dart (bundled with Flutter)

Java

• Java (LTS version required for Android builds)

Rust

• Rust (stable toolchain required for Backend)

Flutter

The user interface and most of the application state management are implemented in Flutter. Flutter enables the application to run on multiple platforms from a single codebase while maintaining a consistent user experience.

Why Flutter?

• Cross-platform development for Android, iOS, Windows, macOS, Linux, and Web.

• A rich ecosystem of UI libraries and packages.

• High-performance rendering with a native-like user experience.

• Hot reload for faster development and debugging.

• Excellent integration with native code through the Foreign Function Interface (FFI), making it easy to communicate with the Rust-based serial communication backend.

  For setting up the Flutter development environment refer to:

• docs/flutter.md

Rust

The application uses a Rust-based serial communication backend to interface with PSLab hardware. Instead of relying directly on platform-specific hardware communication dependencies, all low-level serial communication is handled by the Rust backend.

Why Rust?

• Near bare-metal performance with minimal runtime overhead.
• Memory safety without requiring a garbage collector.
• Reliable and efficient handling of high-frequency serial data streams.
• Cross-platform support through a shared native backend for Flutter.
• Better maintainability for performance-critical hardware communication code.

For setting up the Rust development environment and building the backend, refer to:

• docs/rust.md

Project Setup

1. Clone the Repository

git clone https://github.com/fossasia/pslab-app.git
cd pslab-app

2. Install Dependencies

flutter pub get

3. Platform-Specific Setup for Testing locally

Android

No additional setup is required.

iOS (macOS only)

Install the CocoaPods dependencies:

cd ios
pod install
cd ..

Windows

No additional setup is required. If Windows does not automatically detect your PSLab device, install the appropriate USB drivers.

Linux

Install the provided udev rules and grant your user access to serial devices:

sudo cp linux/99-pslab.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

sudo usermod -a -G dialout $USER

Log out and log back in for the group changes to take effect.

Running the Application

Run the App

The following commands use the CLI. List available devices:

flutter devices

Run the application:

flutter run

Build

Debug

Use for development and debugging:

flutter build apk --debug

Profile

Use for performance testing and local release-like builds:

flutter build apk --profile

Note: Release builds are generated automatically through CI stored in the app branch.

Testing

Run all tests:

flutter test

Run integration tests:

flutter test integration_test/

Troubleshooting

Common Issues:

1. USB permissions on Linux:

   • Ensure udev rules are installed: ls -la /etc/udev/rules.d/99-pslab.rules
   • Check user is in dialout group: groups $USER

2. Flutter version mismatch:

   flutter channel stable
   flutter upgrade
   flutter pub get
   

3. iOS build issues:

   cd ios
   pod deintegrate
   pod install
   cd ..
   flutter clean
   flutter pub get
   

4. Android build issues:

   • Ensure an LTS Java version is installed: java -version
   • Clean build: flutter clean && flutter pub get

5. Git dependency issues:

   flutter pub deps
   flutter pub get
   

Verify Setup

Follow the steps below to confirm that your local development environment is correctly configured.

1. Check Flutter installation

flutter doctor

Resolve any critical issues reported by the command.

2. Install dependencies and run tests

flutter pub get
flutter test

3. Run the application

flutter run

Run the app on a connected physical device, emulator, or desktop target.

Translations

We use Weblate for managing translations.

If you want to help translate the app into your language, please visit the PSLab App project on Weblate.

Technical Details

The app uses the standard Flutter flutter_localizations package.

• Location: Translation files are stored in lib/l10n/ in .arb (Application Resource Bundle) format.
• Template: The source of truth is lib/l10n/app_en.arb.
• Contribution: While we prefer translations submitted via Weblate to avoid merge conflicts, you can also manually edit the .arb files and submit a Pull Request.

Contributions Best Practices

Code Practices

Please follow these best practices to make the review process easier for both contributors and reviewers. This allows us to focus on code quality.

• Follow the pull request template whenever you create a pull request.

• Always reference the related issue number at the top of the pull request description.

• If an issue does not already exist, create one before opening the pull request and link it in the description.

• Include screenshots or a short video demonstrating your changes whenever applicable, especially for UI-related changes.

• Always format your Dart code before committing:

  dart format .
  

• Ensure your code builds successfully and is free of warnings before pushing. Pull requests with build issues or warnings may fail the CI checks.

• Enable GitHub Copilot Review or ChatGPT Codex Review in your GitHub account. The AI reviewer may provide useful suggestions on your pull request. Address the relevant comments.

Branch Policy

We have the following branches

• main All development goes on in this branch. If you're making a contribution, you are supposed to make a pull request to Main. Make sure it passes a build checks.
• development-legacy Contains the legacy native Android app code.
• app Contains automatically generated build artifacts (APK, EXE, IPA, DMG, DEB, etc.) for testing. Anyone can download and install these artifacts directly without needing to build the project locally.

License

This project is currently licensed under the Apache License 2.0. A copy of LICENSE is to be present along with the source code. To obtain the software under a different license, please contact FOSSASIA.