Short history of CocoSoft: toward smart fluidic control

CocoSoft is the software that has controlled our lab instruments for years, and the direct ancestor of PalmSoft, PalmChrom's control software. Here's its story. Five years ago I wrote a paper entitled 'short story of CocoSoft', where I explained its architecture and control potential; regretfully it was never published, so it becomes this blog entry instead. Please be forgiving for the outdated references; I may update them in the close future. Enjoy the read!

12 years ago, the first lines of the software CocoSoft were written as a temporary solution for an instrumental bottleneck. 34 updates bring CocoSoft 1.0 from Visual Basic 6.0 in a technically demanding frame, to CocoSoft 7.6 self-contained, in Python3 with PyQt6 for GUI and real time plots, minimized command set and configuration behind the curtains. Thanks to the feedback of many collaborators, nowadays it has become an automation suite able to control the instruments from different manufacturers and to process data at real time, so that the hardware execution is modified in an unattended manner. The continuous operation of the so-called 'smart methods' allow high-throughput analysis or database generation in ecological or clinical analysis, as demonstrated recently in Oliver et al. 2019.

In this entry we go through the history of CocoSoft and its evolution from actuating a single valve at predefined times to automating smart biochemical analysis and the release as free and open-source software. We also include examples, tips and tricks to control common fluidic actuators and detectors, as well as for stepping into microfluidics. We hope that this contribution inspires bioanalytical scientists to introduce the automation and smart methods in their routine workflows.

The story of CocoSoft begins with the creation of the flow Injection and trace analysis (FI-TRACE) research group in the University of the Balearic Islands, specialized in the automation of environmental and clinical analysis. The new hardware from Fialab included the control software WinFIA 5.0, which could send RS232 commands, but the impossibility of changing the communication parameters (9600, 8N1 per default) as well as the impossibility to send non-printable characters (e.g. ASCII 10 or 13) prevented the control of our old Crison instruments. Other standalone alternatives as Autoanalysis 5.0 from Sciware and FloZF from Global FIA were overkill for the reduced functionality that we needed. The solution was to develop our own program. The first lines of code in Visual Basic 6.0 for dispensing 10 mL of diluent upon mouse click were successful on the 14th of December of 2011.

The first compiled version was controlling a valve module from Crison, comprising a stream selector and a 6 position injector: Mohr, Miró, and Limbeck 2017. It could turn the valves at the given times and include time delays. It was not user friendly because the characters to be sent through the RS232 port had to be typed manually, but they could be included and recovered from a .txt file. The update with more reliable delay instructions, and the time-efficient control of a syringe pump opened the door to the parallelization of our routine methods based on Sequential Injection Analysis platforms (Ruzicka and Marshall 1990). The idle status of the pump was confirmed prior sending further instructions with an every-second query. Different version of the instrument firmware had usually different status query characters, so the software had to be recoded for every hardware reconfiguration. The software was enhanced till version 2.0 for Cocovi-Solberg, Rosende, and Miró 2014, including beeps, loops, nestable routines, conditionals, basic arithmetic, use of variables and a cleaner interface with menus. In version 3.0, a generic communication wizard was implemented. The operator could preconfigure up to 10 instruments with their respective communication ports, parameters, and status assessment instructions, and only needed to select instrument and type the characters to send. Those characters could be consulted in dedicated dialogs, so the user required the hardware manual no more.

Next big step was the translation to Python programming language with fluidic-object oriented philosophy (Cuadrado, De Castro, and Gómez-Nieto 2006). Typing manually the characters to send was a cumbersome task, even if the instructions could be consulted in the same software, so from the version 4.0, the program was basically an open source and multiplatform Python sandbox in which the instruments were imported as Python modules. Several instruments of the same type could be used by duplicating the file corresponding to the desired instrument, and changing its name to avoid conflicts, providing capacity for limitless instruments connected simultaneously. It was executed in Windows XP, 7, 10, Ubuntu and Debian, in desktop computers, laptops and even microcomputers as a BeagleBone Black furnished with a 7" touchscreen for portable applications. Upon loading CocoSoft, those modules were imported and the functions appeared readable to the user (Fangohr 2004), who could select them with a click, avoiding the typing of machine instructions. The basic working mechanism was to execute a single line of code at a time, wait for a suitable answer and then continue with the next instruction. This one-liner restriction of the Python syntaxis allowed a visual follow of the method execution, but forced the creation of non-pythonic flow structures, as starting and ending instructions for conditionals and loops. On the other side, all fluidic instructions were available through clicks on a dedicated window, where the operator required only to input the arguments in the brackets of the given function. For example, dispensing an amount of liquid could be achieved by clicking on the syringe pump, then on the 'dispense' command; the instruction 'syringe.dispense()' was inserted in the current mouse position of the textbox. Then the user introduced the argument e.g. 'syringe.dispense(100)' for dispensing 100 µL. Version 4.3 was the longer lasting mainstream version, which included the previous with a minimalist interface, and some useful tools as a terminal window, plot capacity through the matplotlib libraries and logging of all executed instructions. It centralized all the operations of the fluidics laboratory.

The user creates in the friendly interface a set of instructions that will be executed sequentially and can saved and reloaded at any time, that is, the method. Those instructions are addressed to fluidic actuators, detectors, or provide extra flow control as delays, loops, conditionals, or calculations. To prevent the freezing of the GUI, the communication procedures are carried in a parallel thread, thanks to a single shot timer. After an instruction has been executed, Cocosoft updates the highlighting (to keep visual track of the method execution) and executes the next instruction. If the instruction was manipulating user-defined variables, as in data acquisition or calculations, the variables display is updated. The instructions addressed to actuators that require a significant amount of time for their execution, are written in a way that prevent the GUI freezing: the first call to the function starts the fluidic operation (e.g. dispensing some volume), and the focus is returned to the main program, while successive calls serve to assess if the execution is finished. Only when the instrument responds that is idle, CocoSoft procedes with the next instruction. This execution is aided by the common pause and stop function. If the method is manually stopped, CocoSoft sends orders to the instrument to halt the mechanical parts for preventing spills or crush danger with moving parts as e.g., syringe plungers and autosamplers or turning off high voltage power supplies.

The version 4.3 was the longer lasting stable version and was published as a lab automation suite with teaching capabilities: Cocovi-Solberg and Miró 2015. Our colleagues with microfluidic experience provided a positive feedback highlighting the clean and user-friendly interface. The main drawback was that the module system was not straightforward to use. Users preferred to keep using old modules rather than installing and configuring the new ones. They also adapted their own open-source modules adding functionalities dedicated to specific assays, ending up in a bunch of modules of unpredictable performance.

Version 5 coped with that mess by exchanging the module approach for a class-based structure, that is, instruments were no more external modules that were imported, but their functions were included in the main program. An external configuration file was created upon hardware rearrangement, that was loaded in the next sessions. The so-created configuration files could be shared between users without risking of damaging the source code, and all the extensions were available anytime, without the need of downloading them upon hardware rearrangement. The GUI was optimized and cleaned, maintaining stacked widgets, splitters, and a reduced set of big textless icons over other widget containers as docks, tabs, toolboxes and grids. Only a reduced set of instructions was kept for every instrument (see section 'programmatically convoluted command set').

The main problem was still the installation. Since the main program and the extension modules were Python scripts, the user should install Python beforehand, as well as all the dependencies as Qt4.8 and PyQt4 for the Graphic User Interface (GUI), matplotlib, scipy and numpy for the plotting or pyserial for the serial communications to name a few. It was strongly recommended to install the full PythonXY bundle, that included all the previous, so the small size of the CocoSoft software (39.2 kb) was engrossed by more than 400 Mb of ancillary software. In some cases, the restriction to install external software in computers of the academic institutions was also a drawback for the distribution. Version 6 was compiled and offered as a single executable file with zero dependences, which seems to be a successful strategy for the survival of tailor made software (Sheldrick 2008). Now it is possible to download CocoSoft as .exe file and execute it without installation, even from a memory stick, which allows its use in computers where the user has no right to install software. Two minor disadvantages were pointed out: Compiling it for the Windows ecosystem prevented its execution in Linux, but we received no negative feedback, probably due to the monopoly of Windows in the laboratory computers. The second one regarded the transparency of the code when providing it already compiled, which was a step backward in IT trends according to the collaborators with a programming background. Because of that, the source code was available for download for the users who prefered to compile it themselves or to execute the software in the classical real-time interpreted version. The first compiled version weighed 62.9 Mb. Several libraries were substituted by custom code. Matplotlib was substituted by a QPainter event on an empty widget and the data treatment routines of Numpy were exchanged for custom functions (see Real-time data processing section). The size reduced to 12.3 Mb for the 6.2 release, and increased again to 47.4 Mb in the 7.6 version, which included .dll control for the Ocean Optics USB2000 and USB4000 spectrophotometers, ADU200 relay plate and LabJack U12.

Fluidic components based on microcontrollable electronics offer a very broad command set, which can be overwhelming for non-specialists: most of the options are never used, while a handful of them are eternally repeated. For example, in the sequential injection analysis (Ruzicka and Marshall 1990), the whole method consists in turning the selector position, and aspirating or dispensing a volume at a preselected flowrate; the options to set the pump acceleration, the turning direction of the valve, or to send the piston to an absolute position are never used. In order to reduce the command set and make it less error prone, from CocoSoft 4 on, the command set was convoluted behind the curtains. This novelty had mixed reactions, being the users with an engineering background more critical. Finally, the complete command set was maintained, but the extra benefits of the convoluted instructions were kept.

An adapted version of the code is shown in Table 1 as proof of concept. Table 2 exemplifies the instructions required before and after using the enhanced command set. In this paragraph we will describe briefly how this command set helps developing faster and less verbose methods that are less error prone. The instruction called ‘Delay until done’ in Fialab’s WinFIA or ‘Exclusive mode’ in Sciware’s Autoanalysis are used for waiting until the current instruction has finished before sending the next one; since they are used always, they could be set to execute automatically after every pump movement. Sometimes it is needed to pump a big amount of carrier and the syringe pump must be refilled many times; with the enhanced instruction no significant difference is noticed against continuous pumps. Telling the pump to dispense continuously could be done by e.g., omitting the argument. This also allows a faster method development and prevents method halting by errors if the needed argument is omitted. Finally, the main selector and the syringe head valve movements are entangled, so when the main selector moves, the head valve must be connecting the pump to the selector. This step is mandatory and could be done automatically. Operations requiring dispensing at constant pressure (Chocholouš, Šatínský, and Solich 2019 and Chocholouš, Solich, and Šatínský 2007) can be controlled by a closed loop algorithm. Simply, the new desired flowrate is updated on-the-fly after multiplying the actual speed by the desired/actual pressure ratio (proportional control). A maximum acceleration threshold should be included for preventing damaging the hardware.

Smart methods refer to the unattended self-modification of the control method based on the system feedback. The variable level of complexity of those methods allow to substitute the human input in virtually any analysis. During the years we utilized two different approaches. In the first one, the decision taking algorithm is an integral part of the measurement, as found on the first paper of CocoSoft (Cocovi-Solberg and Miró 2015) in which a proportional method is used for controlling the pH of a soil extraction. The proper pH control is mandatory for accurate bioaccessibility assessment and depends mainly on the carbonate content of the sample, a priory unknown. Another example of the same approach can be found in Oliver et al. 2020, where the initial stabilization period for the cell surrogates is also unknown, and thus, in the classical approach, the analysis has to be performed by a colleague who checks periodically for the stabilization of the biochemical medium prior adding further reagents. In both cases the use of a smart algorithm allows to process samples sequentially without human intervention and updating a results file as soon as further analysis are finished, ultimating the throughput of the system since it can work continuously (e.g., overnight or over weekend). The calculations used for those control methods can be of varying complexity, but usually are based on basic arithmetic.

The other approach in which the smart methods are useful is as a quality control of the whole sample set by automating the validation statistics and in worst case, repeating the analysis of some of the samples. In Vida et al. 2016, a high statistic load was expected for assessing the contribution of many variables. 6 time-points of an extraction kinetic were evaluated for 2 different analytes and 2 different soils. Every analysis was made per triplicate and for every combination, 3 different regression models had to be evaluated, that is, 36 regressions of 6 points each. For avoiding this cumbersome task, a non-linear regression tool was added to CocoSoft, which evaluated unattended all possible combinations, reporting only the kinetic parameters of the best fit for every soil / analyte combination. This new function was used for comparing the fitting to different equations. CocoSoft selected the best fit from 3 different exponential functions describing the extraction from a single environmental compartment, plus an independent term, or two different compartments. Those fits were compared using the R2adj statistic. The parameter and deviations of the best fit were automatically shown in the screen and exported as a text file without user intervention.

The non-linear regression tool was introduced in the CocoSoft version 5 and was based on a custom coded Nelder-Mead (Simplex) algorithm without expansions nor contractions. The method behaved properly as far as the initial conditions were not close to the search border. The best obtained points were analytically refined by fitting to a second order model. The parameters and deviations obtained allowed to calculate automatically the R2, R2adj (for comparing between models with different parameter count), probability of Goodness-Of-Fit and probability of Lack-Of-Fit (if replicates were available). For the last two we included the scipy libraries, that granted access to Fischer-Snedecor testing. When reporting the results, the deviations of the fit parameters are as important as the parameters themselves, so their calculation was implemented with a Monte Carlo algorithm. This strategy was computationally expensive, and prevented the real-time data analysis, which had to be performed at the end of the experimental part (Cocovi-Solberg, Rosende, and Miró 2014). For improving the speed of the calculation, the Nelder-Mead/Montecarlo scheme was exchanged for the optimize.leastsq() function from the scipy library; already available in CocoSoft.

As described in the "origin" section, the dependencies significantly increased the size of the main file, so in version 6.0, the scipy and numpy libraries were substituted by custom code. Student's and F distributions were obtained through the incomplete beta functions, pythonizing the Numerical Recipes in C (Press et al. 2002). The optimize.leastsq() function was substituted by a custom Gauss-Newton implementation, that contrary to the Newton Raphson does not require second derivatives. The Jacobian matrix is calculated by finite differences, perturbing the parameters of the last fitted parameters by 10-10 in both directions, well within the machine precision. Moore-Penrose pseudoinverse and Gauss-Jordan elimination are then used for obtaining the new parameters. The deviations are calculated from the curvature matrix, that is, an inverted Hessian. This hessian is however approximated by the Jacobian and its transpose. All the results were thoroughly compared against other statistical programs with old sample sets before releasing the CocoSoft version. The reduction of external libraries for mathematical calculations increased the source code in 70 lines but saved 51 Mb. In all the described cases of smart methods, the limiting factor is the access to real-time data, which is described in the next section.

The communication protocols of detectors are sometimes provided by the manufacturers, which allows for a straightforward implementation of the data acquisition procedures. However, often is not possible to do so due to software or hardware protection, and usually the reverse engineering provokes de warranty and service expiration. We herein describe some alternatives used in CocoSoft for acquiring data at real time.

Directly through the instrument communications

In this approach, the communication protocol is available, and the user codes the suitable functions to acquire the data at real time. Usually, the required code consists merely in opening a serial port, read the data in the income buffer and format this data. Data often include a beginning or terminating character, fixed length, or separators. We obtained that functionality with the Python-built-in 'split()' combined with subsampling a set of characters from a string and converting the data into an integer or floating-point number. This was done in the CocoSoft proof of concept (Cocovi-Solberg and Miró 2015) for acquiring at real time the pH from an Eutech PC2700 pH meter. Detectors which provide higher information density per time unit as e.g., CCD based spectrophotometers use a compression algorithm to avoid the transmission bottleneck. In this case it is necessary to know the compression algorithm, usually provided by the manufacturer, and implementable through arithmetic or bitwise operations, also included in Python built ins.

Analog to digital converters

Sometimes the communication protocol is not available, but the instrument can be configured to provide the analytical signal as an analog output, especially old instruments. An example can be found in Miquel Oliver et al. 2020 with a Jasco 4000 flow fluorimeter for studying membranotropic effects of emerging pollutants in cell surrogates. Those analog outputs can be read with a commercial or tailor-made ADC, both cases resorting to the serial communication for transmitting the data to CocoSoft. Open-source microcontroller boards as Arduino, Feather or Pycom offer readily RS232 communications through a virtual COM port in USB and are very flexible to implement actuators and sensors. In that case, a LoPy4 board was used to digitalize two analog signals and recalibrated itself for compensating the temperature drift before every biochemical measure. 1024 analytical signals were averaged for every transmitted measurement, achieving higher resolution than the default 12-bit ADC; virtually 12 + 0.5 * log2(1024) = 17 bits.

Accessing result or temporary files

CocoSoft can open and save files through the one-line instructions, and this has been useful to access data obtained by another program. For example, if the chromatographic software is programmed to automatically integrate the chromatogram and export the retention time and peak area to a predefined file, CocoSoft could be programmed to open that file, parse the desired peak area, and adapt the execution of the next fluidic step e.g., sample preparation. For example, the sample could be analyzed once again after proper dilution so that the peak area falls in the middle of the calibration curve.

Simulating clicks in the screen

In Kaewwonglo, Oliver, Cocovi-Solberg, 2019, the UV-Vis spectra of a nanoparticle enhanced ELISA had to be recorded periodically in order to study the hypsochromic shift of a localized surface plasmon resonance, but the communication protocol of the spectrometer was not available. We introduced the 'Click()' function that simulates a human click in the pixel coordinates provided. The sample was prepared and injected in the flow cell of the photometer. CocoSoft simulated clicks on the data acquisition software, on the 'current spectrum' window, and on the 'snapshot' button. At the end of the experiment CocoSoft clicked in the 'export all as csv' button, and the data was saved. The accumulated spectra were cleared before starting the new experiment. One drawback is that the success of this approach is window-layout dependent. If the computer is in use by a human, the clicks could be done in the wrong window. To this end, the instruction 'Minimize_all()' was introduced: prior to the clicks, all windows are minimized, and then the first click will be used for maximizing the correct window. The same approach was used for an anodic stripping voltammetry in Cocovi-Solberg et al. 2018. The Click() function started the preconcentration step, the sample was perfused through the detection cell, and afterwards the stripping step was also triggered with the 'Click()' instruction.

Comment on multithreading

Often the data must be acquired while the fluidic components are in use. To ease this task, an enhanced plotting capability was introduced in CocoSoft through the 'timeout' parameter for updating the plot periodically; the data can be real-time accessed through a variable named after the plot title.

We hope that the previous text inspires bioscientists to introduce the automation in their laboratories for the sake of improved sample throughput or generation of custom libraries. First experiments in microfluidics and smart methods can be setup with a minimum inexpensive hardware and a user-friendly software like CocoSoft.

Regarding the hardware, countless different techniques have been reported during the last years (Vakh et al. 2016; Horstkotte, Miró, and Solich 2018; Flow Injection Tutorial and Programable flow injection analysis), but the flexibility and simplicity of the Sequential Injection Analysis (Ruzicka and Marshall 1990) is, from our point of view, unparalleled. Note that this setup is ubiquitous in our laboratories in the shape of automatic burettes or autosamplers which can, if properly controlled, automate virtually any biochemical assay. Dedicated companies as Global FIA or FIAlab, provide integrated solutions and a very friendly support for users without previous experience. For users with more experience or with very specific needs, directly contacting the fluidic component manufacturers as the VICI group, TECAN or IDEX is another option. TECAN has been monopolizing the market with their CAVRO syringe pumps models XP3000 and XCalibur. VICI and IDEX valves are present in all commercial chromatographic autosamplers. IDEX introduced some years ago a series of pumps providing 30 bars of pressure; VICI has always monopolized the low-pressure valve market and recently introduced continuous pumps which will be a game changer in the short-term future microfluidics, especially the model M6HP, reaching 100 bars of pressure, allowing the integration of chromatography in classical SIA schemes, or also the new TrueNano pumps, reaching 1500 bars for capillary UHPLC. We have also acquired second-hand fluidic components from online shopping platforms as eBay. Those items usually have a warranty and can be acquired for a reduced fraction of the original price.

Commercial solutions tend to have their own control software. We develop and maintain CocoSoft as a solution when the integration of hardware of different manufacturers is not possible. New users are welcome to try the plethora of available instruments, considering that the bottleneck is always the same: the instrument may not yet be supported. We strongly invite uses to contact the author for integrating new instruments in CocoSoft when the communication protocol is available. Another solution is that the user develops its own software, which has been a common praxis for high quality data generation (Sklenarova et al. 2002, Knochen, Caamaño, and Bentos 2011, Frank et al. 2006. Even non-experienced users can code simple programs resorting to communications and data treatment in a couple of days. To this end, Python has been proven to be a language very suitable for beginners (Fangohr 2004) thanks to its high readability and conciseness; a fast search in the internet returns plenty of free courses.

For the ultimate experienced users, DIY hardware as syringe actuators (Samokhin 2020; Garcia, Liu, and Derisi 2018; Han et al. 2016), valves (Wang et al. 2017; Su, Hsia, and Sun 2014) or autosamplers (Carvalho et al. 2020) can be fabricated in house, resorting to 3D printing technology or standard mechanic components that can be found in online hardware stores as e.g. stepper motors, flat, linear and roller bearings, ball-screw actuators or spring washers. The motor control can be done though e.g., Arduino or Feather boards, the latter being programmable in Python. Microcontroller kits are very popular and can be online ordered for less than 50 € and include comprehensive starting guides.

Hardware (second hand or tailor made) and software (freeware or self-coded) can be inexpensive but will require time until the first publishable data is produced, especially for the users not skilled in the art. The training of a laboratory technician or PhD student in basic electronics, Python programming 3D printing and mechanical workshop abilities can be regarded as an investment in the mid-term problem solving capabilities of the research group.

CocoSoft project started 12 years ago as a control software for off-the-shelf fluidic components. Its evolution has been fostered by the need of integrating more components and making it increasingly unattended through the execution of smart methods. Collaborators' feedback showed a preference for easy installation through zero dependencies and a clean interface, with as many cumbersome procedures taken away from the analyst as possible, which is understandable since in the fluidic domain operations are usually repeated very often during method development and thus, even small optimizations have a strong influence in the workload. The project will be maintained and improved but is also expected to string along a hardware standardization as seen in other fields, from which the author and collaborators highlight the Sequential Injection Analysis platform. We would like to encourage (bio)analytical scientist of environmental and clinical background to introduce the automation in their research lines, since the high complexity of those samples, the high number of samples requiring cumbersome preparation and the ease of hyphenation to instrumental analysis equipment propose microfluidics as an excellent platform for reducing costs and maximizing the throughput of the laboratory.