Foundation is a web-based truck scale management application for weighing inbound and outbound trucks, tracking transactions, and generating reports. It runs on ASP.NET Core 8 with a SQLite database and supports touchscreen kiosk terminals with remote ticket printing via Raspberry Pi.
- Features
- Deployment Guides
- Deploy Script Reference
- Server Management
- Configuration
- Troubleshooting
- Architecture
- Development
- License
- Real-Time Scale Display — Live weight readings from connected scales with motion/error status
- Multiple Scales — Named site scales (grain-management style): operators pick the scale on the weigh forms, each kiosk is mapped to a scale, and every ticket records which scale captured each weighment
- Weigh In / Weigh Out — Record inbound and outbound truck weights with automatic net weight calculation
- Inbound & Completed Trucks — Track trucks currently on-site and view completed transactions
- Reports — Date-range filtering, group by (Customer, Carrier, Commodity, etc.), export to Excel and PDF
- Master Data Tables — Manage Customers, Carriers, Trucks, Commodities, Locations, and Destinations (tabs follow field visibility; dropdown custom fields get their own tab)
- Custom Fields — Admin-defined ticket fields (text, dropdown, integer, decimal with min/max) that appear on the weigh forms, grids, kiosk prompts, and printed tickets — placeable anywhere in the ticket designer
- Field Ordering — Standard and custom fields share one sort order that drives the weigh forms, with the two form columns kept balanced automatically
- Kiosk Mode — Touchscreen-optimized interface for unattended scale houses (1280x800 resolution)
- Remote Printing — Print tickets to thermal printers via Raspberry Pi print agents over SignalR
- Ticket Designer — Edit ticket layouts with the built-in DevExpress Report Designer
- Driver Signature Capture — Operator-device overlay or a remote signature-pad tablet (opened by scanning a QR code on the Setup page)
- User Login & Roles — Optional login with User, Manager, and Admin roles
- Customizable — Themes, custom icons, configurable kiosk prompts, and editable ticket templates; Setup changes auto-save
- Demo Mode — Built-in scale simulator for testing without hardware, one independent simulator per defined scale
Pick the path that matches where the app will run. Each guide is self-contained — follow it end to end.
| Target | When to use it | Guide |
|---|---|---|
| Debian cloud server (Vultr, etc.) | Internet-facing site with a real domain and HTTPS. Required if you need access from outside the LAN or want Let's Encrypt SSL. | docs/deploy-vultr.md |
| Raspberry Pi on the LAN (HTTP) | Single weigh station, operators on the same local network, no domain or certificate. Reachable at http://truckscale.local. |
docs/deploy-pi.md |
| Raspberry Pi kiosk display | A second Pi (per kiosk display) wired to the scale-house TV. Boots straight into Chromium pointed at <server>/Kiosk with a watchdog that restarts the browser on outage. Bootstrap is a one-shot paste into Raspberry Pi Connect; install.sh prompts for the kiosk PIN, service-id, and printer-id and assembles the full URL. |
RaspberryPiKiosk/README.md |
After the app is running, see Server Management for updates and routine ops, and Configuration for app settings.
Field commissioning tip: to configure a headless Pi's network from a phone (tech access point + browser-based Wi-Fi/ethernet setup and connectivity test), install pi-network-setup on the Pi alongside the app.
Deploy Pis clone private GTMichelli-Dev repos over plain HTTPS using a
GitHub App installation token instead of PATs or SSH keys. A one-time
bootstrap per Pi installs a git credential helper that mints short-lived
tokens from the App's private key — after that, git clone / git pull of
any org repo just works on the box:
scp scripts/setup-pi-github-app.sh scripts/michelli-github-app-token.sh \
scripts/git-credential-michelli.sh /path/to/michelli-app.pem admin@<pi>:/tmp/
ssh admin@<pi> "sudo bash /tmp/setup-pi-github-app.sh --install-id <ID> --pem /tmp/michelli-app.pem"Full walkthrough — including creating the GitHub App the first time (org settings → Developer settings → GitHub Apps, Contents: Read-only) — in docs/pi-git-auth.md.
All scripts are in the deploy/ folder:
| Script | Windows | Description |
|---|---|---|
deploy/publish.sh |
deploy/publish.bat |
Builds the web app for Linux and creates a deployment tarball |
deploy/install.sh |
— | Installs on the server (Nginx, SSL, systemd service) |
deploy/deploy.sh |
deploy/deploy.bat |
One-step deploy: builds, uploads, and installs remotely |
deploy.sh options:
./deploy/deploy.sh <user@host> [options]
Options:
--domain <domain> Domain name for Let's Encrypt SSL
--email <email> Email for Let's Encrypt notifications
--port <port> App listen port (default 5110)
--key <ssh-key> SSH key file for authentication
Examples:
# With Let's Encrypt HTTPS (recommended for production)
bash deploy/deploy.sh admin@149.28.xxx.xxx --domain scale.yourcompany.com --email admin@yourcompany.com
# With SSH key instead of password
bash deploy/deploy.sh admin@149.28.xxx.xxx --domain scale.yourcompany.com --email admin@yourcompany.com --key ~/.ssh/id_rsa
# Self-signed cert (LAN only, no domain needed)
bash deploy/deploy.sh admin@192.168.1.100One command deploys or updates everything on a scale-house Pi — the web app (built locally, pushed over SSH) plus the Scale Reader Service, Web Print Service, and pi-network-setup tech access point (cloned and built on the Pi; requires the GitHub App bootstrap once per Pi):
bash deploy/deploy-pi-all.sh admin@<pi-ip>Defaults: services point at http://127.0.0.1 (same-Pi web app) and the
printer queue is TicketPrinter. Options: --server-url, --printer-name,
--key, and --skip-web / --skip-scale / --skip-print / --skip-net
to deploy a subset. Re-running is safe — every installer preserves its
database/settings.
For internal-network Pi installs of the full web app — Kestrel serves plain HTTP directly on port 80, no nginx and no SSL:
| Script | Description |
|---|---|
deploy/publish-pi-web.sh |
Builds the web app for Raspberry Pi (arm64) and creates a tarball |
deploy/install-pi-web.sh |
Installs on the Pi (systemd service, no nginx) |
deploy/deploy-pi-web.sh |
One-step deploy: builds, uploads, and installs remotely |
deploy-pi-web.sh options:
./deploy/deploy-pi-web.sh <user@host> [options]
Options:
--port <port> App listen port (default 80)
--key <ssh-key> SSH key file
--rebuild-db Delete and recreate the database (WARNING: deletes all data)
Example:
bash deploy/deploy-pi-web.sh admin@192.168.1.60To commission the Pi's network connection in the field without a monitor, see pi-network-setup.
| Script | Description |
|---|---|
deploy/publish-pi.sh |
Builds the print agent for Raspberry Pi (arm64) |
deploy/install-pi.sh |
Installs print agent with CUPS on the Pi |
deploy/deploy-pi.sh |
One-step deploy to a Pi |
deploy-pi.sh options:
./deploy/deploy-pi.sh <user@host> [options]
Options:
--server <url> Foundation server URL (e.g. https://scale.yourcompany.com)
--printer <name> CUPS printer name (run 'lpstat -p' on the Pi to find it)
--printer-id <1|2> 1 = Inbound kiosk, 2 = Outbound kiosk (default 1)
--key <ssh-key> SSH key file
Example:
bash deploy/deploy-pi.sh pi@192.168.1.50 --server https://scale.yourcompany.com --printer Zebra_LP2844 --printer-id 1Unlike the print agent, the kiosk has no separate publish/deploy scripts — the operator clones the repo on the kiosk Pi itself (via Raspberry Pi Connect) and runs install.sh interactively. See RaspberryPiKiosk/README.md for the full bootstrap walkthrough.
| Script | Description |
|---|---|
RaspberryPiKiosk/install.sh |
One-time setup. Prompts for Server URL, Kiosk PIN, Service ID, Printer ID; verifies connectivity; installs Chromium + curl + unclutter; registers the watchdog autostart entry; suppresses gnome-keyring popups |
RaspberryPiKiosk/kiosk-loop.sh |
The watchdog. Launches Chromium in --kiosk mode at the assembled URL and restarts it after UNREACHABLE_THRESHOLD seconds of server outage |
RaspberryPiKiosk/kiosk-stop |
Pause the kiosk (writes STOP flag, kills Chromium, loop stays alive) |
RaspberryPiKiosk/kiosk-start |
Resume after a pause |
RaspberryPiKiosk/uninstall.sh |
Remove the autostart entry |
Run on the kiosk Pi:
cd ~/foundation/RaspberryPiKiosk
./install.sh
sudo rebootinstall.sh prompts for four values (all but the first are optional):
| Prompt | Becomes URL parameter | Default on re-run |
|---|---|---|
| Server URL | base URL | last value used |
| Kiosk PIN | ?pin=… (required when User Login is on) |
last value used |
| Service ID | ?service-id=… (Browser or blank for browser-print) |
last value used |
| Printer ID | ?printer-id=… (e.g. Zebra_LP2844) |
last value used |
After deployment, use these commands on the server:
# Check if the app is running
sudo systemctl status foundation
# View live logs
sudo journalctl -u foundation -f
# Restart the app
sudo systemctl restart foundation
# Stop the app
sudo systemctl stop foundationWhen the project has been updated (new features, bug fixes, etc.), follow these steps to deploy the latest version to your server:
1. Pull the latest code on your local development machine:
cd foundation
git pull2. Rebuild and deploy to the server:
Windows (Command Prompt):
deploy\publish.bat
deploy\deploy.bat admin@149.28.xxx.xxx --domain yourDNSName.scaledata.net --email admin@yourcompany.com
Linux / Mac / Git Bash:
bash deploy/publish.sh
bash deploy/deploy.sh admin@149.28.xxx.xxx --domain yourDNSName.scaledata.net --email admin@yourcompany.comOr as a single step (the deploy script will run publish automatically if the tarball doesn't exist):
Windows:
del deploy\foundation-deploy.tar.gz
deploy\deploy.bat admin@149.28.xxx.xxx --domain yourDNSName.scaledata.net --email admin@yourcompany.com
Linux / Mac / Git Bash:
rm -f deploy/foundation-deploy.tar.gz
bash deploy/deploy.sh admin@149.28.xxx.xxx --domain yourDNSName.scaledata.net --email admin@yourcompany.comWhat's preserved during updates:
- Your database (
Foundation.db) — all transactions, master data, and settings- Custom ticket templates in the
Reports/folder- Nginx configuration and SSL certificates
What gets replaced:
- Application binaries and static files
- The systemd service file
3. Verify the update by checking the version in the browser footer or running:
ssh admin@149.28.xxx.xxx 'sudo systemctl status foundation'cd foundation
git pull
bash deploy/publish-pi.sh
bash deploy/deploy-pi.sh pi@192.168.1.50 --server https://yourDNSName.scaledata.net --printer Zebra_LP2844 --printer-id 1The Pi agent's appsettings.json (ServerUrl, PrinterName, PrinterId) is preserved during updates.
| Path | Contents |
|---|---|
/opt/foundation/ |
Application files |
/opt/foundation/Foundation.db |
SQLite database (preserved on updates) |
/opt/foundation/Reports/ |
Custom ticket templates (preserved on updates) |
/etc/systemd/system/foundation.service |
Systemd service file |
/etc/nginx/sites-available/default |
Nginx reverse proxy config |
/etc/letsencrypt/ |
SSL certificates (auto-renewed) |
Edit /opt/foundation/appsettings.json on the server:
{
"ShowResetDatabase": false,
"DatabaseProvider": "SQLite",
"ConnectionStrings": {
"SQLite": "Data Source=Foundation.db"
}
}| Setting | Description |
|---|---|
ShowResetDatabase |
Show/hide the database reset buttons on the Setup page (true for testing, false for production) |
DatabaseProvider |
SQLite (default) or MariaDB |
MaxScales |
Maximum number of site scales that can be defined on the Scale page (default 4) |
After editing, restart the service:
sudo systemctl restart foundationNavigate to Setup in the web interface to configure. Changes auto-save — there is no Save button; a "Saved ✓" indicator confirms each change (text fields save when you leave them). Changing the theme reloads the page so it applies immediately.
- Company & Ticket — Header lines (company name, address, phone), ticket numbering
- System — Demo mode, kiosk count (0/1/2), login mode, theme, custom icon, driver signature capture (the Remote Signature Pad option shows a QR code — scan it with the tablet to open the pad, no typing)
- Fields — Show/hide the standard fields, set the sort order for standard and custom fields (one shared scale, so a custom field can slot between built-ins), and manage custom fields (text, dropdown, integer/decimal with min/max/precision, required, show-on-ticket, kiosk prompting)
- Kiosk Prompts — Which fields to show on the kiosk touchscreen
- Ticket Designers — Edit the layout of printed tickets
The Scales page (System → Options → Scales) manages the named site scales:
- Each scale has a name (what operators see and what tickets record), a hardware feed (a scale reported by a connected Scale Reader Service), an order, and an active flag. A scale with no hardware feed is driven by the per-scale simulator in Demo Mode.
- The weigh forms show a scale picker when more than one scale is active; the choice is remembered per browser. The dashboard's live weight display follows the same selection.
- Kiosks are mapped to a scale in the Launch Kiosk dialog (or via
?scale-id=<id>in the kiosk URL); each kiosk reads and records weights from its mapped scale. - Every ticket stores the scale name per weighment (In Scale / Out Scale). Manually entered weights record no scale.
- Each scale can have its own inbound and outbound ticket printers (optional). Auto-printed tickets go to the capturing scale's printer; scales without one use the site-wide defaults from the Printers page. Explicit kiosk printer choices (Launch Kiosk dialog) still take precedence.
- In Demo Mode each scale has its own independent simulator — the simulator panels (header bar, Get Weight dialog, kiosk) drive whichever scale is selected.
Custom fields marked Show on printed ticket print in one of two ways:
- Auto-append (default): a
Name: valuerow is added near the bottom of the ticket for every field with a value. - Designer placement: every ticket-eligible custom field appears in the Ticket Designer's Field List as a parameter named
cf_<FieldName>(non-alphanumerics become underscores). Drag it into the layout and save — the value then prints at that exact spot and the auto-appended row for that field is suppressed. Fields you don't place keep auto-appending, so existing layouts never change behavior.
Dropdown-type custom fields also get their own tab on Edit Tables for managing the choice list (add, rename, delete, drag to reorder) without opening Setup.
Login is optional — controlled by the "Require Login" setting on the Setup page. When disabled, all features are accessible without authentication.
Default admin credentials:
- Username:
admin - Password:
michelli
Support backdoor account (for recovery if admin is locked out):
- Username:
support - Password:
Scale_Us3r - This account has Admin role, does not appear in the user list, and cannot be edited or deleted.
Roles:
| Role | Access |
|---|---|
| User | Weigh trucks in and out, view dashboard, reports, inbound/completed trucks |
| Manager | Everything User can do + edit master data tables (customers, carriers, etc.) |
| Admin | Everything Manager can do + Setup page + user management |
Password Reset: Admins can reset any user's password from the Setup > Manage Users page. The password is reset to michelli and the user must change it on next login. There is no email-based recovery (the system may not have internet access).
Kiosk Access with Login Enabled: Kiosks don't use the login screen. Instead, pass the Kiosk PIN code as a URL parameter:
https://your-server/Kiosk?pin=12345
The default PIN is 12345. Change it on the Setup page. The PIN is stored as a browser cookie so subsequent requests don't need it.
Three other optional query parameters select which print service and scale handle this kiosk:
https://your-server/Kiosk?service-id=office-1&printer-id=BIXOLON_BK3&scale-id=2&pin=12345
service-id— name of the Print/Camera Service instance (matches what's shown in the Setup page).Browseror blank means browser-print.printer-id— physical printer the service drives (e.g.Zebra_LP2844).Browserfor browser-print.scale-id— the site scale this kiosk reads and records (the id from the Scales page). Omitted = the default (first active) scale. The Launch Kiosk dialog fills this in automatically on multi-scale sites.
If you're deploying a Pi-driven kiosk display, RaspberryPiKiosk/install.sh prompts for all three values and assembles the full URL — no need to hand-edit it into the boot config.
Scale brand / model / protocol metadata (baud rate, parity, weight regex, etc.) does not live in this repo. It lives in a separate public repo:
GTMichelli-Dev/device-definitions → file scales/scale-models.json
How the running system picks it up
The Scale Reader Service fetches the file via HTTPS from https://raw.githubusercontent.com/GTMichelli-Dev/device-definitions/main/scales/scale-models.json whenever:
- The service starts up.
- The web app's Scale Management page calls
RequestScaleBrandsover SignalR — this happens automatically on page load and on every click of the Refresh Definitions button at the top of that page. - Anyone hits
GET http://<scale-host>:5220/api/status/brands.
The result is also written to scale-models.json next to the service's .exe as a fallback cache.
Adding or editing a definition
- Edit
scales/scale-models.jsonin thedevice-definitionsrepo and push tomain. - Verify the raw URL serves your change (there's sometimes a 1–2 min CDN delay):
curl https://raw.githubusercontent.com/GTMichelli-Dev/device-definitions/main/scales/scale-models.json
- Open the Scale Management page in the web app. The header pill labelled Definitions turns:
- Green — "Definitions: live (N)" when the service successfully refreshed from GitHub.
- Yellow — "Definitions: cached (N)" when the service couldn't reach GitHub and is serving its on-disk fallback. Hover for the underlying error.
- If the pill is yellow, click Refresh Definitions after fixing connectivity, or restart the service:
Restart-Service ScaleReaderService
Where the URL is configured
appsettings.json (in the Scale Reader Service install folder) seeds the URL on first run, but BrandsCache.RefreshAsync() reads the live value from the service's own Settings table. To check the URL the service is actually using:
curl http://<scale-host>:5220/api/settingsIf it points at a fork or stale URL, update it via the same endpoint (PUT /api/settings), e.g.:
curl -X PUT http://<scale-host>:5220/api/settings \
-H "Content-Type: application/json" \
-d '{"brandsUrl":"https://raw.githubusercontent.com/GTMichelli-Dev/device-definitions/main/scales/scale-models.json"}'The PUT triggers an internal service restart so the new value takes effect. On some installs that restart is a hard process exit — if
systemctl status scale-reader-serviceshows it stopped afterwards, runsudo systemctl start scale-reader-serviceto bring it back.
If a new version requires database schema changes that can't be auto-migrated, use the --rebuild-db flag:
deploy\deploy.bat admin@149.28.xxx.xxx --domain basic.scaledata.net --email admin@example.com --rebuild-db
WARNING: This deletes the existing database and creates a fresh one. All transactions, master data, and users will be lost. Back up first if needed.
The app runs in Development mode by default (shows full error details). If you've switched to Production mode and need to see errors, either check the logs:
ssh admin@149.28.xxx.xxx
sudo journalctl -u foundation -fOr temporarily switch back to Development mode:
sudo nano /etc/systemd/system/foundation.serviceChange ASPNETCORE_ENVIRONMENT=Production to Development, then:
sudo systemctl daemon-reload
sudo systemctl restart foundationRemember to set it back to
Productionwhen done troubleshooting.
This means ports 80/443 are blocked. The deploy script opens these automatically via iptables, but if it still fails:
ssh admin@149.28.xxx.xxx
sudo iptables -I INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -I INPUT -p tcp --dport 443 -j ACCEPTAlso verify DNS is pointing to the server:
nslookup yourDNSName.scaledata.net
The deploy script checks DNS before deploying. If it fails, make sure:
- You created an A record in your DNS provider pointing to the server IP
- You waited for propagation (typically 1-5 minutes, up to 1 hour)
- Run
nslookup yourDNSName.scaledata.netand confirm it returns the correct IP
┌─────────────────────────────────────────────┐
│ Debian Server │
│ │
│ Nginx (port 80/443) │
│ ├── HTTPS termination (Let's Encrypt) │
│ ├── Reverse proxy → localhost:5110 │
│ └── WebSocket passthrough (SignalR) │
│ │
│ Foundation.Web (port 5110) │
│ ├── ASP.NET Core 8 / Kestrel │
│ ├── SQLite database │
│ ├── DevExpress Report Engine │
│ └── SignalR Hub (real-time updates) │
│ │
└──────────────────┬──────────────────────────┘
│ SignalR (WebSocket)
│
┌──────────┴──────────┐
│ │
┌───────┴───────┐ ┌────────┴────────┐
│ Raspberry Pi │ │ Raspberry Pi │
│ (Inbound) │ │ (Outbound) │
│ PrinterId: 1 │ │ PrinterId: 2 │
│ CUPS → Printer│ │ CUPS → Printer │
└────────────────┘ └─────────────────┘
- .NET 8 SDK
- Git
git clone https://github.com/GTMichelli-Dev/foundation.git
cd foundation/web/Foundation.Web
dotnet runOpen http://localhost:5110 in your browser.
Enable Demo Mode in Setup to use the built-in scale simulator.
Copyright 2026 Michelli Weighing & Measurement. All rights reserved.