How artisan-roaster-scope/artisan works
Purpose and Runtime
Artisan is a cross-platform Python desktop application for recording, analyzing, and controlling coffee-roasting profiles. It combines a Qt GUI, live device acquisition, roast-event workflows, profile persistence/import-export, and optional cloud-connected business features. Primary launch path: src/artisan.py, which delegates application orchestration to src/artisanlib/main.py. Packaging targets Windows, macOS, Linux, and Raspberry Pi via PyInstaller/spec and platform scripts.
Application Shell and UI
The central application/controller layer manages startup, settings, windows, and user-driven roast operations. src/artisanlib/main.py is the primary coordinator; src/artisanlib/canvas.py provides the interactive roast graph/visual scope; src/artisanlib/dialogs.py hosts configuration and operational dialogs. Qt Designer sources and generated UI modules support specialized widgets: src/ui/SetupWidget.ui, src/uic/SetupWidget.py.
Live Acquisition and Device Boundary
Hardware communication is isolated behind ports, device adapters, and asynchronous transport. Core connectivity includes src/artisanlib/comm.py, src/artisanlib/async_comm.py, and src/artisanlib/ports.py. Protocol-specific boundaries include Modbus (src/artisanlib/modbusport.py), Siemens S7 (src/artisanlib/s7port.py), MQTT (src/artisanlib/mqttport.py), WebSockets (src/artisanlib/wsport.py), BLE (src/artisanlib/ble_port.py), and Phidgets (src/artisanlib/phidgets.py). Vendor adapters translate machine-specific protocols into the application’s readings/control model, e.g. src/artisanlib/giesen.py, src/artisanlib/aillio_r2.py, and src/artisanlib/santoker.py.
Roast Session Data Flow
During a roast, sampled device values feed the canvas and derived calculations; user/device events annotate the profile; alarms and automation can issue actions. Event and phase state are managed by src/artisanlib/events.py and src/artisanlib/phases.py; alarms by src/artisanlib/alarms.py; signal cleanup/derived processing by src/artisanlib/filters.py and src/artisanlib/curves.py. This is the key real-time boundary: acquisition/control must remain resilient and non-blocking while Qt renders and records the session.
Control and Automation
PID logic converts configured setpoints and measured process values into machine commands through the communications layer. Core modules are src/artisanlib/pid.py, src/artisanlib/pid_control.py, and src/artisanlib/command_utility.py. Alarms, event buttons, replay/program features, and predefined machine setup files provide higher-level control behavior. Bundled setup presets are data-driven assets under src/includes/Machines/, for example src/includes/Machines/Giesen/W15A.aset.
Profiles, Persistence, and Reporting
Roast profiles are loaded, saved, compared, transformed, and exported through src/artisanlib/roastlog.py, src/artisanlib/roastpath.py, and src/artisanlib/comparator.py. The repository includes .alog profile assets and import coverage for third-party formats, with adapters such as src/artisanlib/cropster.py, src/artisanlib/ikawa.py, and src/artisanlib/stronghold.py. HTML/report presentation assets reside in src/includes/report-template.htm and src/includes/roast-template.htm.
External Service Integration
The optional Artisan Plus domain is a separate package boundary under src/plus/. It handles account/authentication, remote API connection, synchronization, and business objects: src/plus/connection.py, src/plus/sync.py, src/plus/controller.py. It supports inventory, blends, roast data, schedules, stock, and notifications without being the core local roasting runtime.
Distribution and Embedded Assets
Runtime assets include translations in src/translations/, themes in src/includes/Themes/, roast wheels in src/Wheels/, and generated help modules in src/help/. Platform packaging is defined by src/artisan-win.spec, src/artisan-mac.spec, src/artisan-linux.spec, plus scripts such as src/build-linux.sh. Linux installation includes udev rules for USB hardware access at src/debian/etc/udev/rules.d/99-artisan.rules.
Main entry points: main.py Application coordinator · comm.py Communications core · events.py Events and phases · filters.py Signal processing
Components 21
Desktop Runtime
- Application entry
src/artisan.py - Application coordinator · Owns startup, settings, windows, and roast operations.
src/artisanlib/main.py - Roast canvas · Renders the live roast graph and visual scope.
src/artisanlib/canvas.py - Operational dialogs
src/artisanlib/dialogs.py - Setup widget
src/ui/SetupWidget.ui
Device Integration
- Communications core · Coordinates ports and non-blocking acquisition.
src/artisanlib/comm.py - Async transport
src/artisanlib/async_comm.py - Port abstraction
src/artisanlib/ports.py - Protocol transports
src/artisanlib/modbusport.py - Roaster adapters · Maps machine protocols to readings and controls.
src/artisanlib/giesen.py - Machine presets
src/includes/Machines/Giesen/W15A.aset
Roast Session
- Events and phases
src/artisanlib/events.py - Signal processing · Cleans samples and derives roast metrics.
src/artisanlib/filters.py - Alarms
src/artisanlib/alarms.py - PID control · Converts process values and setpoints into machine commands.
src/artisanlib/pid_control.py
Profiles & Services
- Profile persistence · Loads, saves, transforms, and exports roast profiles.
src/artisanlib/roastlog.py - Third-party importers
src/artisanlib/cropster.py - Report templates
src/includes/report-template.htm - Artisan Plus · Provides authentication, sync, and business objects outside the local roast runtime.
src/plus/controller.py
Distribution Assets
- Runtime assets
src/translations - Platform packaging · Builds Windows, macOS, Linux, and Raspberry Pi distributions.
src/artisan-win.spec
Connections 23
- Application entry → Application coordinator: launches
- Application coordinator → Roast canvas: drives
- Application coordinator → Operational dialogs: opens
- Operational dialogs → Setup widget: uses
- Application coordinator → Communications core: starts acquisition
- Communications core → Async transport: uses
- Communications core → Port abstraction: manages
- Port abstraction → Protocol transports: connects through
- Protocol transports → Roaster adapters: supports
- Machine presets → Roaster adapters: configures
- Communications core → Signal processing: sampled values
- Signal processing → Roast canvas: derived curves
- Events and phases → Roast canvas: annotates
- Application coordinator → Events and phases: records operations
- Signal processing → Alarms: monitors values
- Alarms → PID control: triggers actions
- PID control → Communications core: issues commands
- Events and phases → Profile persistence: records profile
- Profile persistence → Third-party importers: imports formats
- Profile persistence → Report templates: renders reports
- Application coordinator → Artisan Plus: optional integration
- Platform packaging → Application entry: bundles
- Platform packaging → Runtime assets: includes