Command and Real-time Acquisition in Parallelized PYthon (CRAPPY)

Crappy is an open-source Python framework for command and data acquisition on experimental setups. A Crappy test is a Python script assembled from Blocks that acquire measurements, drive actuators, process data, display signals, or save results. Links carry labeled data between these Blocks.

Crappy is developed at LaMCube, a mechanical research laboratory in Lille, France, where it is used mainly for materials testing.

Why use Crappy?

As experimental setups grow, coordinating instruments from different vendors, organizing acquisition and commands, and reproducing the same test procedure can become increasingly difficult. Commercial packages may tie a setup to a specific ecosystem, while writing a complete control application from scratch requires time and software expertise.

Crappy provides a common, modular framework for these tasks. Ready-to-use Blocks can be combined and replaced as an experiment evolves, and users can use included hardware drivers or integrate custom devices. Because each test is an ordinary Python script, its complete workflow can be saved, shared, and repeated. Crappy is also designed to use computer resources efficiently, helping beginners and experts build responsive experiments without having to write the underlying software.

What can Crappy do?

• Acquire measurements from sensors and laboratory instruments
• Drive actuators and build feedback loops
• Capture, process, display, and record images
• Display and save experimental data as it is acquired
• Integrate custom hardware and processing code for user-specific needs
• Run on Linux, Windows, macOS, and Raspberry Pi

Installation

Crappy requires Python 3.11 or newer and NumPy 2.0 or newer. Install it from PyPI with:

python -m pip install crappy

The default graphical interfaces in Crappy use PyQt6 and PyQtGraph. Install these GUI dependencies with:

python -m pip install PyQt6 pyqtgraph

See the installation guide for platform-specific instructions and optional dependencies.

Example script

This example reads the computer's memory usage, displays it live, records it in data.csv, and stops automatically after ten seconds. It requires no physical hardware, but uses PyQtGraph and PyQt6 for the graph and psutil for the simulated input:

python -m pip install pyqtgraph PyQt6 psutil

import crappy

if __name__ == '__main__':
  acquisition = crappy.blocks.IOBlock('FakeInOut', labels=('t(s)', 'ram(%)'))
  graph = crappy.blocks.Grapher(('t(s)', 'ram(%)'))
  recorder = crappy.blocks.Recorder('data.csv', labels=('t(s)', 'ram(%)'))
  stop = crappy.blocks.StopBlock('t(s) > 10')

  crappy.link(acquisition, graph)
  crappy.link(acquisition, recorder)
  crappy.link(acquisition, stop)

  crappy.start()

Refer to the documentation for a detailed explanation of each Block's purpose and capability.

Documentation and support

Start with Is Crappy right for you? for a broader overview of the framework, its intended uses, and its limits.

• The tutorials provide guided introductions to common tasks and custom objects
• The examples provide complete scripts organized by task, with and without physical hardware
• The core concepts explain how Blocks, Links, labels, and test lifecycles fit together
• The hardware matrix lists the available drivers and their known platform and backend support
• The API reference documents the arguments and methods of Crappy's public objects

If something does not work as expected, consult the troubleshooting guide first. The support and reporting guide then explains where and how to ask a question, report a bug, or share hardware compatibility results.

Usage questions are welcome in GitHub Discussions. Use the issue tracker for reproducible bugs and hardware compatibility reports.

Citing Crappy

If Crappy contributes to published research, please cite:

Couty V., Witz J.-F., Martel C. et al. Command and Real-Time Acquisition in Parallelized Python, a Python module for experimental setups. SoftwareX 16, 2021. doi:10.1016/j.softx.2021.100848

See the citation guidance and CITATION.cff for structured metadata.

License

Crappy is distributed under the GNU General Public License v2.0 or later.

Copyright © 2015–present, Laboratoire Mécanique de Lille and contributors.