FRIENDS GUI: A Graphical User Interface for Data Collection and Visualization of Vaping Behavior from a Passive Vaping Monitor

Introduction

The global use of Electronic Nicotine Delivery Systems (ENDS), commonly known as e-cigarettes or vapes, has increased significantly in recent years. In 2020, approximately 68 million people were using ENDS worldwide, nearly twice the estimated 35 million users in 2015 [1, 2]. ENDS use has grown substantially since 2010 in the United States, with 8.1 million adults identified as users by 2018 [3, 4, 5]. As of 2021, 4.5% of U.S. adults reported current ENDS use, with the highest prevalence (11%) among young adults aged 18–24 [6]. Although ENDS are often promoted as a safer alternative to combustible cigarettes, studies have shown that their vapor contains harmful chemicals, including acetaldehyde and formaldehyde, which are associated with respiratory and cardiovascular diseases [7]. Nevertheless, emerging evidence also suggests that ENDS can support smoking cessation in adults [8].

A growing body of research has emphasized that vaping patterns – such as the frequency, timing, and duration of puffs – play a critical role in smoking cessation outcomes [9, 10, 11]. However, a lack of standardized, objective methods to measure vaping behavior hinders cross-study comparisons and limits understanding of usage trends [12]. Most studies rely heavily on self-reporting, which is inherently limited [13, 14]. Many relevant behavioral metrics, such as puff timing and duration, cannot be accurately self-reported, and recall errors further reduce the reliability of such data [15]. Even over a 4-hour session, self-reported puff counts correlated poorly with actual counts (r = 0.37) [16]. Taking inspiration from sensors designed for monitoring of cigarette smoking [17, 18], sensors offer a promising alternative for more accurate monitoring of ENDS use. For example, a system described in [19] enables detailed measurement of vaping behavior, including puff depth and intensity. However, its reliance on internal electrical connections limits its practical utility.

To address these challenges, the Flexible Robust Instrumentation of Electronic Nicotine Delivery Systems (FRIENDS) was developed as an open-source monitoring device that attaches externally to ENDS. FRIENDS integrates an electromagnetic (EM) sensor to detect puff events, a touch sensor to log when the device is held, and a thermistor to measure temperature changes during each puff and touch event. These components collectively record data to onboard memory with high-resolution (15μs) 64-bit extended POSIX timestamps with the event code.

This paper introduces the FRIENDS GUI, an open-source Python-based graphical user interface that supports seamless interaction with the FRIENDS device. The GUI facilitates data retrieval, processing, and conversion of raw binary logs into human-readable formats. It calculates key metrics such as event duration, enables users to set or synchronize device time, and supports flash memory management. The software also generates interactive, customizable visualizations that allow users to explore daily vaping patterns. Similar to other advanced processing tools [20, 21, 22, 23], the FRIENDS GUI aids in data-driven decision-making and supports refinement of experimental protocols.

Implementation and architecture

The FRIENDS system integrates hardware and software components to enable precise monitoring of vaping behavior. As shown in Figure 1, the core hardware includes an MSP430G2433 microcontroller connected to three sensors: an electromagnetic (EM) sensor for detecting atomizer activity during puffs, a touch sensor for identifying when the device is held, and a negative thermal coefficient (NTC) thermistor for measuring temperature at the mouthpiece. The device attaches adhesively to ENDS and logs the start and end times of puff, touch events as well as aerosol temperature in internal flash memory, supporting continuous data collection for up to 10 days (Figure 1a–b). The software components of the system have three primary responsibilities:

1. Data Collection Control: The software facilitates synchronization of the device’s internal clock with the host computer and clears flash memory before a new session. This ensures accurate timestamping and reliable data capture for all events.

2. Data extraction and conversion: The GUI extracts and decodes the binary data after data collection and provides key metrics, such as puff count, puff duration, and time of occurrence for a puff. Events are stored using extended POSIX timestamps (Figure 1d), which include event codes, standard time, and fractional seconds (Table 1). Temperature is sampled at the start and end of puff and touch events, with values ranging from 0 to 1024, calculated via an internal voltage divider circuit. Although not timestamped independently, these readings are used to improve puff classification accuracy and eliminate false positives (Algorithm 1 in Appendix). Converted timestamps and extracted data, including puff durations and timing, are displayed in human-readable formats (Figure 1e-f).

3. Visualization: The software generates 24-hour graphs showing puff, touch, and temperature data for the beginning and end of puffs. It also summarizes total puff duration and frequency per day (Figure 1g).

Figure 1

Graphical User Interface

User interaction with the FRIENDS system is facilitated through a graphical user interface (GUI), developed using Python 3.11 and the tkinter package. Multithreaded operations, implemented via Python’s threading library, allow real-time GUI responsiveness during serial communication. Data processing tasks such as timestamp conversion, event extraction, and formatting are handled using the Pandas and NumPy libraries, while Matplotlib is used for generating visualizations within the GUI. Figure 2 presents the GUI of the FRIENDS system, highlighting the key controls and data processing functions.

Figure 2

The GUI features five categories of widgets: (1) bars, (2) dropdown menus, (3) buttons, (4) entry fields, and (5) monitors, and the flow diagram in Figure 3 illustrates their functionalities.

Figure 3

Serial communication with the FRIENDS device is managed via the pyserial library. The “Connect” button establishes a link between the device and the host computer, and “Reload” refreshes the available COM port list.

Data collection is initialized by the “Start Data Collection” button, which clears the device’s flash memory and synchronizes its real-time clock with the host system. Users may also perform independent flash memory erasure (“Erase Flash”) or time synchronization (“Set Time”). The “Read Time” button displays the internal clock for verification purposes.

Data extraction begins by selecting “Read Data”, which initiates serial communication with the FRIENDS device. The device transmits 16-character hexadecimal records containing event type and timing, which are converted to extended POSIX timestamps (adjusted for local time), labelled by event type, and saved as a formatted text file (Figure 1d).

Data conversion runs automatically after extraction or can be triggered manually via the “File Conversion” button. Users may also access data using any open-source serial terminal emulator. Raw data from the FRIENDS device, saved in the text file, undergoes a multi-stage validation and cleaning process during pre-processing.

The software first checks for duplicate “Timestamps:” headers, which indicate that previously saved data may have been written again to the same file. If detected, a pop-up message alerts the user: “Multiple ‘Timestamps:’ headers detected: This indicates that the raw data was saved multiple times in the (input) text file. Please remove unwanted/unnecessary data from the text file.” Leading spaces are then removed and the data are screened for corrupt entries that may occur during serial transmission, such as empty lines, incomplete records (fewer than 16 characters) and lines with more than 16 characters. Event logs are validated using logical pairing rules: puff events (codes 1/2), touch events (codes 3/4), and temperature events (codes 5/6) must each appear as valid on–off pairs in correct sequence. If errors are detected, the user is notified with diagnostic information containing two lists: “Line numbers with missing event pairs,” which identifies lines with missing or incomplete event pairs, and “Line numbers with incomplete timestamps,” which identifies lines with malformed or incomplete timestamps (e.g., fewer than 16 characters) in the raw data file. Unmatched or incorrectly ordered event pairs are removed. Additional consistency rules discard puff or touch pairs lacking a corresponding temperature event pair and remove duplicate temperature entries until a new event block begins. After pre-processing, the data conversion involves two steps: (1) translating extended POSIX timestamps to human-readable time, and (2) calculating event durations (Figure 1d-f).

The pseudo-code of processing data, converting timestamps, and extracting information is presented in Algorithm 1, 2, and 3 in the Appendix, respectively.

Algorithm 1 processes extended POSIX timestamps using thermistor data when “Use Thermistor” is selected, improving puff detection for vape models where EM sensing is unreliable. Following testing across multiple vape models to determine cases in which puffs could be reliably detected using the FRIENDS device, a comprehensive library was developed that includes model-specific evaluations and identifies when thermistor data is required to improve puff detection performance [24]. A temperature difference threshold of 10 is used to filter false positives. For example, a vape that has been idle for a long period may have an ADC value around 500; a change of 10, from 500 to 490, corresponds to a temperature increase from 25.98 °C to 26.81 °C (0.83 °C). For a vape used recently, the baseline may be closer to 350; the same change of 10, from 350 to 340, corresponds to a temperature increase from 39.37 °C to 40.37 °C (1.00 °C). If “Use Thermistor” is not selected, noise is removed based on a default minimum puff duration of 400ms. Algorithm 2 converts 64-bit extended POSIX timestamps into local time. It parses the event code, standard POSIX value, and fractional seconds, converting them into a readable datetime format. Algorithm 3 calculates the duration of events by identifying ON/OFF event pairs (e.g., PUFF_ON/PUFF_OFF) and computing their temporal difference. All results are stored in structured data frames for further visualization and analysis.

Visualization and graph generation in the FRIENDS GUI is initiated automatically upon selecting the “Save data and generate plots” or “File Conversion” button. The software first performs timestamp conversion and event extraction, then categorizes events by date and generates a separate plot (puff events at the top, temperature in the middle, touch at the bottom) for each day (Figure 1g). Events are plotted on a 24-hour timeline (00:00 to 24:00). Users can customize plots by setting a minimum puff-duration threshold to display either all puff events or only those that meet the specified threshold.

Quality control

The FRIENDS software was validated using a SMOK NORD 5 ENDS device, which has a puff-initiation button and displays puff duration. Validation experiments were conducted four times daily-at midnight, morning, afternoon, and evening. Each session consisted of three sets of six puffs, lasting approximately 2, 3, and 4 seconds respectively, totaling 18 puffs per session. A 30-second gap separated each puff. It is important to note that no human participants were involved in the validation experiments. Puffs were triggered either by a button pressed on the vape or a mechanical vaping machine [25], and no human vaping intake occurred at any stage of the testing process. All experiments were recorded using the Zoom platform, with the camera directed at the NORD display and a shared window showing the real-time clock (https://clock.zone/) to log puff timing.

Actual puff timings (PUFF ON/OFF) and durations were extracted from the video recordings and compared with the data recorded by the FRIENDS device and processed by GUI. Table 2 summarizes this comparison. The FRIENDS system recorded a total puff duration of 230.76 seconds—99.46% of the actual 232.01 seconds and accurately detected all 72 puffing events. Seventeen false positives were captured, likely due to electromagnetic interference. The GUI’s filtering function, using a 1.0-second threshold, successfully identified and removed these events.

Table 3 presents the precision of timestamp conversion, showing small timing drifts of up to 10 seconds over a full day, which is acceptable for real-time monitoring.

Figure 4 illustrates puffing and touching events over a 24-hour period, with a zoomed-in view near the 1:30-hour mark. While puffs generally occurred ~30 seconds apart, a longer gap between puffs 5 and 6 and a likely false positive were observed.

Figure 4

This validation using 24-hour experimental data confirmed the software’s accuracy in timestamp conversion, data extraction, and graph generation, making it a practical tool for vaping behavior research across diverse study domains.

To verify the software’s error-handling capability, file A (error-free) and file B (corrupted version of file A with intentionally introduced errors) were prepared. First, file A was processed to generate the reference output A_out, which contains timestamps converted to a human-readable format and the extracted event information. Corruptions introduced in file B include truncated timestamps, missing log lines, unexpected indentation, and stripped prefix bytes. The corrupted file B was then processed by the software to generate B_out. Finally, B_out was compared with the reference output A_out using Python’s filecmp.cmp() [26] function, which compares two files by checking their size and contents and returns True if they are identical or False if any difference is detected. The comparison successfully confirmed that all introduced corruptions were detected, verifying the correctness of the software. Subsequently, we tested the consistency between the GUI executable and standalone scripts by running both on file B and comparing their output text files using the same Python’s filecmp module. The comparison confirmed that both implementations produced identical results for the same input file. However, formal automated unit testing is acknowledged as a limitation of the current release and is planned for inclusion in future versions; in the current version, this gap is partially mitigated by comprehensive end-to-end validation of the full processing pipeline, which verifies the integrated performance of all key components under realistic usage conditions.

Operating system

The software is compatible with any operating system that supports a standard Python installation, including the three major platforms: macOS, Windows, and Linux.

Programming language

Python 3.11 or higher.

Additional system requirements

Input device: FRIENDS monitor.

Dependencies

Establishing device communication requires installation of FTDI VCP (Virtual COM Port) drivers on the computer where the FRIENDS GUI software is running. All necessary Python packages are specified in the requirements.txt file located in the root directory of the repository, allowing for reproducible setup. Key dependencies include Tkinter, NumPy, Matplotlib, Datetime, and Pyserial.

The FRIENDS GUI is standalone software built with Tkinter. Note that Tkinter availability depends on the operating system. The library is included with standard Python installations on Windows but may require separate installation on macOS systems, particularly when Python is installed via Homebrew (e.g., brew install python-tk). Linux users may similarly need to install it via their package manager (e.g., sudo apt-get install python3-tk on Debian/Ubuntu-based systems).

List of contributors

1. Shehan Irteza Pranto: Algorithm development, Software development, Experimental Design and Execution, Formal analysis, Writing (original draft)

2. Brett Fassler: Software enhancement, Contribution to algorithm development, Writing (review and editing).

3. Md Rafi Islam: Contribution to software testing and validation, Writing (review and editing)

4. Ashley Schenkel: Project coordination

5. Larry W. Hawk: Supervision, Writing (review and editing)

6. Edward Sazonov: Conceptualization, Experimental Design, Supervision, Funding acquisition, Writing (review and editing)

Software location

Language

English