Help Center
Help & Guides
Guides for every Kieomo app. Pick an application below to see getting started steps, everyday workflows, and important settings.
Kieomo Wega
Installation
Installation & Requirements
1. Requirements: Windows 10/11 (or Linux/macOS), Python 3.9+, and (optional) a CH340/CP210x/FTDI USB-to-Serial driver for RS232 scales plus a MySQL server.
2. Run from source: create a venv (python -m venv .venv), activate it, then pip install -r requirements.txt; copy .env.example to .env and fill it in; run python main.py.
3. Build binaries: py -3.9 compile.py (Windows + Linux via WSL) — other options: --windows-only, --manylinux, --wsl-distro, --upx. Output goes to C:\temp\dist\<os>.
4. Linux binaries: install Qt runtime dependencies with bash setup.sh on the target server.
5. A desktop shortcut is created on first run; a telemetry consent dialog also appears on first run.
2. Run from source: create a venv (python -m venv .venv), activate it, then pip install -r requirements.txt; copy .env.example to .env and fill it in; run python main.py.
3. Build binaries: py -3.9 compile.py (Windows + Linux via WSL) — other options: --windows-only, --manylinux, --wsl-distro, --upx. Output goes to C:\temp\dist\<os>.
4. Linux binaries: install Qt runtime dependencies with bash setup.sh on the target server.
5. A desktop shortcut is created on first run; a telemetry consent dialog also appears on first run.
Reports & Dashboard
Reports & Dashboard
1. Reports menu > Dashboard: KPIs + charts (daily trend, cargo distribution, top partners, transaction status) with date range filters and PDF export.
2. Transaction Report has three modes: Transaction Recap, Cargo Detail (per item), and Summary Recap, with combined filters (date, terminal, status, driver, partner, cargo, area, grade, document type, custom fields).
3. Comparison dashboards are available per Terminal, Cargo, Partner, Driver, Grade, Area, Document Type, Vehicle, and Deduction.
4. Exports support CSV, Excel (XLSX), and PDF; Excel/PDF exports include all columns including cargo line items.
5. Per-transaction exports are saved to exports/YYYY/MM/<terminal>/<ticket>/.
2. Transaction Report has three modes: Transaction Recap, Cargo Detail (per item), and Summary Recap, with combined filters (date, terminal, status, driver, partner, cargo, area, grade, document type, custom fields).
3. Comparison dashboards are available per Terminal, Cargo, Partner, Driver, Grade, Area, Document Type, Vehicle, and Deduction.
4. Exports support CSV, Excel (XLSX), and PDF; Excel/PDF exports include all columns including cargo line items.
5. Per-transaction exports are saved to exports/YYYY/MM/<terminal>/<ticket>/.
Master Data
Master Data
1. The Master Data menu contains: Drivers, Areas, Cargo, Partners, Document Types, Grades, Vehicles, Reference Documents, and Users.
2. Every master window has Add, Edit, Delete, and Reload buttons plus a search box.
3. Cargo and Grade store default Deduction percentages (e.g. moisture/shrinkage); they automatically reduce Net and appear on tickets, reports, Remote View, and webhooks.
4. Document Types have a Max Age (days) that filters overly old reference documents.
5. Items can be deactivated (not deleted) so they remain readable on old transactions.
2. Every master window has Add, Edit, Delete, and Reload buttons plus a search box.
3. Cargo and Grade store default Deduction percentages (e.g. moisture/shrinkage); they automatically reduce Net and appear on tickets, reports, Remote View, and webhooks.
4. Document Types have a Max Age (days) that filters overly old reference documents.
5. Items can be deactivated (not deleted) so they remain readable on old transactions.
Vehicle Master (Tare)
1. Store the vehicle weight (KG) per plate, owner (Own / Partner), the "Gross editable" checkbox, and a note.
2. A plate registered with no running transaction goes straight to WEIGH-OUT mode: Gross is filled from the master, Tare from the indicator, and the transaction is saved directly as COMPLETED.
3. When "Gross editable" is unchecked, the master value is locked (a single weighing is enough); the checkbox is only auto-checked for new vehicle records.
4. On a running weigh-in transaction, Tare is filled automatically from the master and locked when that checkbox is off.
2. A plate registered with no running transaction goes straight to WEIGH-OUT mode: Gross is filled from the master, Tare from the indicator, and the transaction is saved directly as COMPLETED.
3. When "Gross editable" is unchecked, the master value is locked (a single weighing is enough); the checkbox is only auto-checked for new vehicle records.
4. On a running weigh-in transaction, Tare is filled automatically from the master and locked when that checkbox is off.
Getting Started
Getting Started with Kieomo Wega
1. Install the Wega app on a PC connected to the weighbridge, launch it, and sign in with the account provided by the admin (default: user "admin", password "admin123" — change it immediately).
2. Complete the initial setup in Settings: company profile, terminal ID, transaction numbering, and the scale connection (RS232 serial indicator or TCP/IP network).
3. Prepare master data: vehicles (tare weight per plate), cargo, grades, partners, drivers, and document types.
4. When the MySQL server is unreachable, the app automatically switches to a local database (offline mode); transactions are stored and sync automatically once the connection is restored.
5. Contact the Kieomo team at our official email for license activation and support.
2. Complete the initial setup in Settings: company profile, terminal ID, transaction numbering, and the scale connection (RS232 serial indicator or TCP/IP network).
3. Prepare master data: vehicles (tare weight per plate), cargo, grades, partners, drivers, and document types.
4. When the MySQL server is unreachable, the app automatically switches to a local database (offline mode); transactions are stored and sync automatically once the connection is restored.
5. Contact the Kieomo team at our official email for license activation and support.
Login & User Roles
1. Enter your Username and Password. On a fresh install the default account is user "admin", password "admin123" — change it immediately via Account > Change Password.
2. Roles: admin (all menus including Master Data, Settings, and User Management), supervisor (operator + master data + delete transactions), operator (transaction input only).
3. If the username/password is wrong, the login window stays open and the fields are cleared so you can retry.
4. Forgot password: reset with the tool "python tools/reset_password.py" (source) or create a new user in Settings > User Management.
2. Roles: admin (all menus including Master Data, Settings, and User Management), supervisor (operator + master data + delete transactions), operator (transaction input only).
3. If the username/password is wrong, the login window stays open and the fields are cleared so you can retry.
4. Forgot password: reset with the tool "python tools/reset_password.py" (source) or create a new user in Settings > User Management.
Troubleshooting
Troubleshooting
1. "PySide6 is not installed" — run pip install -r requirements.txt.
2. Forgot the login password — reset with the python tools/reset_password.py tool or create a new user in Settings > User Management.
3. COM port not found — check the USB-to-Serial driver in Device Manager (Ports COM & LPT).
4. Cannot connect to MySQL — make sure the server is up and credentials are correct in Settings > Database; an OFFLINE indicator means the server is unreachable.
5. Linux binary shows no UI — run bash setup.sh to install the Qt runtime dependencies.
6. MySQL password does not carry over when .env is copied to another machine — re-enter it via Settings > Database > Test Connection > Save (encryption is machine-bound).
2. Forgot the login password — reset with the python tools/reset_password.py tool or create a new user in Settings > User Management.
3. COM port not found — check the USB-to-Serial driver in Device Manager (Ports COM & LPT).
4. Cannot connect to MySQL — make sure the server is up and credentials are correct in Settings > Database; an OFFLINE indicator means the server is unreachable.
5. Linux binary shows no UI — run bash setup.sh to install the Qt runtime dependencies.
6. MySQL password does not carry over when .env is copied to another machine — re-enter it via Settings > Database > Test Connection > Save (encryption is machine-bound).
Settings
Scale Indicator (Serial / Network)
1. Settings > Serial: choose the indicator source — Serial Port (RS232) or TCP/IP (Network) — and the protocol (auto-detect, Yaohua XK3190, or custom regex).
2. Full serial parameters: baudrate (2400–115200), data bits, parity, stop bits, and command mode with a read interval.
3. "Share to Network" broadcasts indicator data (JSON lines) over UDP/TCP to other computers — default port 8020, serial sources only.
4. "Indicator Preview" panel: click Start Preview to open the port without saving; it shows connection status (CONNECTED / LISTENING / UDP ACTIVE), weight, and raw frame logs.
5. Port/baudrate changes apply immediately without restart; the active source is shown in the bottom status bar (RS232 / TCP host:port / Stream).
2. Full serial parameters: baudrate (2400–115200), data bits, parity, stop bits, and command mode with a read interval.
3. "Share to Network" broadcasts indicator data (JSON lines) over UDP/TCP to other computers — default port 8020, serial sources only.
4. "Indicator Preview" panel: click Start Preview to open the port without saving; it shows connection status (CONNECTED / LISTENING / UDP ACTIVE), weight, and raw frame logs.
5. Port/baudrate changes apply immediately without restart; the active source is shown in the bottom status bar (RS232 / TCP host:port / Stream).
Camera / CCTV
1. Settings > Camera/CCTV: set the number of cameras (0 = no camera; the panel is hidden and auto-capture is off), up to 6 cameras (RTSP/IP/ONVIF/NVR/Webcam).
2. Auto-capture on weighing (optional): all cameras snap a photo when the WEIGH-IN/WEIGH-OUT button is pressed; photos are stored in the transaction folder.
3. Camera N Streaming (checkbox per camera): allows the camera to be viewed from other computers on the Camera/CCTV page of Remote View (MJPEG live stream + snapshot, protected by the same token).
4. On the main window: double-click a camera to enlarge it (popup); the Capture All button saves snapshots from every camera.
2. Auto-capture on weighing (optional): all cameras snap a photo when the WEIGH-IN/WEIGH-OUT button is pressed; photos are stored in the transaction folder.
3. Camera N Streaming (checkbox per camera): allows the camera to be viewed from other computers on the Camera/CCTV page of Remote View (MJPEG live stream + snapshot, protected by the same token).
4. On the main window: double-click a camera to enlarge it (popup); the Capture All button saves snapshots from every camera.
Printer & Ticket Format
1. Settings > Printer: three print modes — Save to File (exports/ folder), Direct to Printer (ESC/POS over a serial port + baudrate), or System Printer (driver: Render Driver for laser/inkjet, RAW ESC/POS for thermal).
2. Use the Test Print and Reload Port & Printer buttons; printer status appears in the bottom bar (Printer: ACTIVE / INACTIVE).
3. Ticket Format: create and select your own ticket templates (header/body/footer), preview, and ticket copies.
4. On the transaction form: PREVIEW to inspect the ticket, PRINT to print it directly.
2. Use the Test Print and Reload Port & Printer buttons; printer status appears in the bottom bar (Printer: ACTIVE / INACTIVE).
3. Ticket Format: create and select your own ticket templates (header/body/footer), preview, and ticket copies.
4. On the transaction form: PREVIEW to inspect the ticket, PRINT to print it directly.
REST API
1. Settings > API: enable the REST API, set the port, tokens (master / rw / ro), read-only mode, and security (rate limit, IP bypass, IP filter whitelist/blacklist).
2. General CRUD endpoints: GET/POST/PUT/PATCH/DELETE /api/<table>[/<id>] (whitelisted tables) plus /api/tables and /api/system_info.
3. Authentication: Authorization: Bearer <token> header or X-API-Key. Secret columns (tokens, passwords) are redacted in responses.
4. Open http://<IP>:<PORT>/api for interactive documentation with cURL, PHP, Python, and JavaScript examples.
2. General CRUD endpoints: GET/POST/PUT/PATCH/DELETE /api/<table>[/<id>] (whitelisted tables) plus /api/tables and /api/system_info.
3. Authentication: Authorization: Bearer <token> header or X-API-Key. Secret columns (tokens, passwords) are redacted in responses.
4. Open http://<IP>:<PORT>/api for interactive documentation with cURL, PHP, Python, and JavaScript examples.
Webhook
1. Settings > Webhook: send transaction data (weigh_in and weigh_out) to an external URL over HTTP POST/PUT/PATCH.
2. Authentication: Basic, Bearer, or API Key (custom header).
3. A retry queue exists with attempt limits, backoff, and a maximum queue size; you can manually resend and see pending status in the webhook queue window.
4. Use the webhook test button and payload preview before going live.
2. Authentication: Basic, Bearer, or API Key (custom header).
3. A retry queue exists with attempt limits, backoff, and a maximum queue size; you can manually resend and see pending status in the webhook queue window.
4. Use the webhook test button and payload preview before going live.
Remote View (Browser Monitoring)
1. Settings > Remote View: enable the monitoring page (default port 8080), set auto-refresh (seconds), header/footer, and Custom CSS & JavaScript.
2. Open http://<COMPUTER_IP>:<PORT> from a browser on another device in the same network; access is protected by a token (fail-closed, auto-generated).
3. Transactions page: latest transaction cards, search (ticket, plate, container, document number, driver, partner, cargo), terminal filter, pagination.
4. Dashboard page: KPIs + charts (daily trend, busy hours, gross/net/tare, cargo, area, partner, per terminal, status) with date filters.
5. Camera/CCTV page: MJPEG live streams + snapshots only for cameras whose streaming is enabled.
6. Dark/light theme is stored per browser; the page auto-refreshes at the configured interval.
2. Open http://<COMPUTER_IP>:<PORT> from a browser on another device in the same network; access is protected by a token (fail-closed, auto-generated).
3. Transactions page: latest transaction cards, search (ticket, plate, container, document number, driver, partner, cargo), terminal filter, pagination.
4. Dashboard page: KPIs + charts (daily trend, busy hours, gross/net/tare, cargo, area, partner, per terminal, status) with date filters.
5. Camera/CCTV page: MJPEG live streams + snapshots only for cameras whose streaming is enabled.
6. Dark/light theme is stored per browser; the page auto-refreshes at the configured interval.
Database & Offline Mode
1. Settings > Database: choose SQLite (local) or MySQL (multi-terminal). Databases are created automatically on first run.
2. The MySQL password is stored encrypted (Windows DPAPI system key, "enc:" prefix), not as plain text. The Test Connection button tests without saving.
3. Automatic fallback: when MySQL is unreachable, the app switches to local SQLite (offline); transactions can still be recorded.
4. When the connection returns, the app detects it automatically, sends all offline transactions (failed ones are kept and retried), then goes back online.
5. Bottom bar indicator: MySQL ONLINE (green), MySQL OFFLINE (red), MySQL ONLINE — syncing (N) (yellow), or DB: SQLite.
6. Database changes apply only after the app is restarted.
2. The MySQL password is stored encrypted (Windows DPAPI system key, "enc:" prefix), not as plain text. The Test Connection button tests without saving.
3. Automatic fallback: when MySQL is unreachable, the app switches to local SQLite (offline); transactions can still be recorded.
4. When the connection returns, the app detects it automatically, sends all offline transactions (failed ones are kept and retried), then goes back online.
5. Bottom bar indicator: MySQL ONLINE (green), MySQL OFFLINE (red), MySQL ONLINE — syncing (N) (yellow), or DB: SQLite.
6. Database changes apply only after the app is restarted.
Transactions
Weigh-In (Gross)
1. On the transaction form, enter the vehicle plate number. If the plate is already registered in the vehicle master, the master weight is used automatically.
2. Press the WEIGH-IN button — the current scale reading becomes the Gross weight and the transaction starts (status IN_PROGRESS).
3. Fill in the rest: cargo, partner, document type + number, entry/exit areas, driver, grade, and custom fields.
4. Press SAVE — a ticket number is created, the transaction enters the queue, and the webhook (if enabled) fires with event=weigh_in.
5. Without a connected indicator, weights can still be entered manually.
2. Press the WEIGH-IN button — the current scale reading becomes the Gross weight and the transaction starts (status IN_PROGRESS).
3. Fill in the rest: cargo, partner, document type + number, entry/exit areas, driver, grade, and custom fields.
4. Press SAVE — a ticket number is created, the transaction enters the queue, and the webhook (if enabled) fires with event=weigh_in.
5. Without a connected indicator, weights can still be entered manually.
Weigh-Out (Tare / Net)
1. Select the departing vehicle from the Vehicle Queue (or type the same plate on the form).
2. Press WEIGH-OUT — the current reading becomes the Tare and Net is calculated automatically: Gross − Tare, minus Deductions when the cargo/grade has them.
3. Press SAVE — the transaction becomes COMPLETED and the ticket can be printed; the webhook (if enabled) fires with event=weigh_out.
4. Vehicles registered in the master with no running transaction go straight into this mode: Gross from master, Tare from the indicator, saved directly as COMPLETED (no queue).
5. Use PREVIEW to inspect the ticket before printing, or PRINT to print it directly (to printer or file per settings).
2. Press WEIGH-OUT — the current reading becomes the Tare and Net is calculated automatically: Gross − Tare, minus Deductions when the cargo/grade has them.
3. Press SAVE — the transaction becomes COMPLETED and the ticket can be printed; the webhook (if enabled) fires with event=weigh_out.
4. Vehicles registered in the master with no running transaction go straight into this mode: Gross from master, Tare from the indicator, saved directly as COMPLETED (no queue).
5. Use PREVIEW to inspect the ticket before printing, or PRINT to print it directly (to printer or file per settings).
Step Weighing (Split Mode)
1. Check Split Mode on the transaction form before weighing in; the Add Stage button becomes active (accent color).
2. For each vehicle stage (e.g. long/combination vehicles), press Add Stage — the current scale reading is added as one stage; the total of all stages becomes the Gross.
3. Weigh-out can also be staged: select the running transaction, check Split Mode, then press Add Stage for each outgoing stage (the total becomes Tare).
4. The split stage lists (split_weights and split_weights_out) appear on the ticket and in Remote View.
2. For each vehicle stage (e.g. long/combination vehicles), press Add Stage — the current scale reading is added as one stage; the total of all stages becomes the Gross.
3. Weigh-out can also be staged: select the running transaction, check Split Mode, then press Add Stage for each outgoing stage (the total becomes Tare).
4. The split stage lists (split_weights and split_weights_out) appear on the ticket and in Remote View.
Vehicle Queue
1. The right panel shows vehicles being processed; use the search box to filter quickly.
2. Display modes (the "View" combo): Table, Card, Compact List, or Monitor Mode — the choice persists across sessions.
3. Card mode is responsive: 3 columns on wide windows, 2 on narrow ones, adjusting as the window is resized.
4. The Terminal filter (All / specific terminal) appears when more than one terminal exists; monitoring a remote terminal auto-refreshes the queue.
5. Click a row to load its data into the form; double-click to view its cargo items; the gear button configures visible columns.
6. Queue load is controlled in Settings > Terminal: Day Range and Max Records (heavy-load notification defaults to 1000 records).
2. Display modes (the "View" combo): Table, Card, Compact List, or Monitor Mode — the choice persists across sessions.
3. Card mode is responsive: 3 columns on wide windows, 2 on narrow ones, adjusting as the window is resized.
4. The Terminal filter (All / specific terminal) appears when more than one terminal exists; monitoring a remote terminal auto-refreshes the queue.
5. Click a row to load its data into the form; double-click to view its cargo items; the gear button configures visible columns.
6. Queue load is controlled in Settings > Terminal: Day Range and Max Records (heavy-load notification defaults to 1000 records).