How gipson-dev/py232-scale works
1. Overall shape
- PY 232 Scale is a Windows-only desktop application with a single-user GUI.
- The app sits between a serial-connected scale and an Excel workbook output used as a printable QC checklist.
2. Entry point and app composition
- main.py is the startup entry point and likely wires together the GUI and core logic.
- The core runtime is split into two main modules:
- scale_logger/gui.py for the desktop interface
- scale_logger/core.py for scale parsing and workbook/log processing
3. User interface layer
- The GUI is built with PySide6.
- It manages:
- project/item entry
- live scale display
- captured weight tables
- settings dialogs/menus
- log open/save/print actions
- theme switching and console visibility
- The UI is the main orchestration layer that reacts to user actions and incoming scale data.
4. Serial input boundary
- The app communicates with the scale over a Windows COM port using pyserial.
- The serial boundary is configurable by:
- port
- baudrate
- DTR
- RTS
- A receive loop reads raw lines from the device, and the app can also run COM-port and receive tests for troubleshooting.
5. Scale parsing and normalization
- scale_logger/core.py contains the logic that interprets raw scale output.
- It supports both numeric weight lines and ticket-style text lines such as Net: 0.177kg.
- Parsed readings are normalized into values the GUI and workbook logic can use.
6. Logging/workbook subsystem
- Workbook generation and updates use openpyxl.
- Each log is an .xlsx file with two main sheets:
- QC Form for the printable checklist
- Raw Data for timestamped captured readings and raw serial lines
- The workbook appears to be created from or aligned with weight_qc_checklist_template.xlsx.
7. Capture and item workflow
- The app records up to three weights per item.
- For each completed item, the logic:
- sorts the three readings
- marks the lowest as Low
- marks the highest as High
- updates summary totals for all low/high readings
- This means the app has a stateful “current log / current item / current captures” flow rather than a stateless import/export model.
8. Editing and continuation flow
- Existing logs can be reopened and edited.
- The app supports correcting:
- item names/descriptions
- individual captured weights
- continuing an item with new captures
- When edits happen, the workbook logic rebuilds low/high markings and summary totals, so the spreadsheet is treated as the source of truth after reopening.
9. Persistence and filesystem boundary
- Logs are automatically saved into a Logs folder.
- The folder location depends on deployment mode:
- beside the executable for packaged builds
- in the project directory for source runs
- File naming is sequential, like Weight_QC_Form 1.xlsx, Weight_QC_Form 2.xlsx, etc.
10. Printing boundary
- Printing is handled directly from the application, without requiring Excel.
- The app sends the printable QC Form worksheet to a selected Windows printer.
- This is a separate external boundary from the workbook file itself: save first, then print the worksheet.
11. Debugging and operator support tools
- com_port_test.py and recieve_test.py are standalone helper scripts for serial testing.
- The GUI also exposes these capabilities through menus, which suggests the serial layer is a common operational risk and intentionally surfaced for support.
12. Packaging and deployment
- The project is packaged with PyInstaller using:
- py232_scale.spec for a folder-based distribution
- py232_scale_onefile.spec for a single-file executable
- Build scripts (build_exe.bat, setup.bat, run.bat) are supporting tooling, not runtime subsystems.
- This is a desktop-distribution architecture, not a service or web deployment.
13. Key architectural boundaries for a diagram
- Operator/UI boundary: user enters items, captures weights, edits logs, prints reports
- Serial device boundary: COM port stream from the scale into the app
- Workbook boundary: in-memory log state written to .xlsx
- Filesystem boundary: Logs folder for persisted files
- Printer boundary: direct Windows print output from QC Form
14. Primary data flow
- User defines a job in the GUI → app opens/configures serial port → live scale readings stream in → user captures up to three readings per item → core logic classifies/sorts readings and updates workbook → workbook is saved to Logs → user may reopen/edit/print the same file later.
Main entry points: gui.py GUI · core.py Core · main.py Startup · build_exe.bat Build script
Components 15
Application runtime
Desktop app entrypoint, UI, and core log/workbook logic.
External boundaries
Hardware, filesystem, workbook, and printer interfaces.
- Scale · Windows COM-port scale stream consumed by the app.
- Printer · Selected Windows printer used to print the QC form sheet.
- Logs folder · Persistent location for saved workbook logs.
- Workbook · In-memory and persisted QC log workbook with printable and raw-data sheets.
weight_qc_checklist_template.xlsx - Template · Checklist template used to seed or align generated workbooks.
weight_qc_checklist_template.xlsx
Packaging and support
Build and diagnostic helpers around the desktop distribution.
- COM test · Standalone script for port troubleshooting.
com_port_test.py - Receive test · Standalone script for receive-loop troubleshooting.
recieve_test.py - Folder build · PyInstaller spec for folder-based distribution.
py232_scale.spec - One-file build · PyInstaller spec for single-file executable distribution.
py232_scale_onefile.spec - Build script · Helper script for building the executable.
build_exe.bat - Setup script · Helper script for preparing the project environment.
setup.bat - Run script · Helper script for launching the app from source or distribution.
run.bat
Connections 18
- Startup → GUI: starts · Launch entrypoint initializes the desktop interface.
- Startup → Core: wires · Startup connects UI events to the core processing logic.
- GUI → Core: calls · UI delegates parsing, capture, edit, and workbook actions to core logic.
- GUI → Scale: opens · User configures and starts the COM-port connection from the interface.
- Scale → Core: streams · Raw scale lines flow into parsing and normalization.
- Core → Workbook: updates · Captured readings and item state are written into the workbook model.
- Workbook → Template: based on · Generated logs align with the checklist template structure.
- Core → Logs folder: saves to · Completed logs are persisted as sequential XLSX files.
- GUI → Logs folder: opens · Operator can reopen existing logs for edit/continue workflows.
- Core → Printer: prints · Printable QC sheet is sent directly to a Windows printer.
- GUI → Printer: triggers · Print action is exposed through the operator interface.
- GUI → COM test: surfaces · Troubleshooting access is exposed from the desktop menus.
- GUI → Receive test: surfaces · Receive-loop diagnostics are exposed from the desktop menus.
- Folder build → Startup: packages · Folder distribution bundles the application entrypoint.
- One-file build → Startup: packages · Single-file distribution bundles the application entrypoint.
- Build script → Folder build: uses · Build helper invokes packaging configuration.
- Build script → One-file build: uses · Build helper supports alternate packaging mode.
- Setup script → Run script: supports · Environment setup enables local execution workflow.