d-dispensing documentation
Administration & installation guide
Who this guide is for: IT administrators and technical owners who set up, operate and update d-dispensing at a site. Prerequisites: basic Windows or Linux server administration, networking and serial device connectivity.
1
System architecture
| Component | Count | Role | Connections |
|---|---|---|---|
| Site server | 1 per plant | Production orders and BOMs from the ERP; tolerance checks; booking transaction to ERP and WMS; audit trail; licence check; serves the operator UI | ERP (myfactory or weclapp), WMS (xstorage, with myfactory), station agents (inbound), browsers (inbound) |
| Station agent | 1 per bench | Serial scale connection; label printing (ZPL); durable local store (outbox) for weighings; update verification | Scale (serial), printer (network), site server (outbound only) |
| Operator UI | 1 per bench | Terminal in a full-screen browser; no installation | Site server |
Data flow of a weighing: scale → station agent (store durably) → print label → site server (booking to ERP + WMS in one transaction, audit-trail entry). Without a server connection the record stays in the outbox and is transmitted idempotently later.
2
System requirements
Site server
- OS: Windows Server or Linux [Engineering: supported versions]; JDK [Engineering: version]
- Database: [Engineering: embedded or external? product/version]
- Network access to the ERP (myfactory and xstorage, or weclapp) [Engineering: protocols/ports]
- Inbound port for station agents and browsers [Engineering: port, TLS termination]
- Resources: [Engineering: CPU/RAM/disk recommendation]
Station agent (bench)
- Windows or Linux [Engineering: versions], JDK [Engineering: version]
- Serial port (RS-232 or USB-serial adapter) to the scale
- Network access to the label printer (ZPL, [Engineering: port 9100?]) and outbound to the site server
- Local storage for the outbox [Engineering: path, size recommendation]
- Browser in full-screen/kiosk mode [Engineering: tested browsers]
Supported devices
Scales: serial industrial scales from Mettler Toledo, Sartorius, RHEWA and more. Further manufacturers are easily added as drivers in the driver layer; the terminal stays unchanged. Printers: Zebra network printers with ZPL. Scanners: barcode scanners in keyboard mode [Engineering: suffix/configuration].
3
Installation
3.1 Site server
- 01Install the JDK and set
JAVA_HOME. - 02Unpack the application artifact into the target directory [Engineering: path].
- 03Create the configuration [Engineering: file, keys]: database, ERP access (myfactory or weclapp), WMS access (xstorage, with myfactory), port, TLS, site identifier.
- 04Review tolerance parameters. Defaults: single weighing max. 104 % of remaining; position closure 98–102 % of target; warnings at 50 % and 95 %. Changes only after QA approval and with a change-control entry.
- 05Set up the service (Windows service / systemd) [Engineering: unit/service definition].
- 06Start and verify the operator UI is reachable in a browser.
- 07Verify ERP and WMS connectivity with a test order [Engineering: test mode].
3.2 Station agent
- 01Install the JDK.
- 02Unpack the agent artifact [Engineering: path].
- 03Configure [Engineering: file]: site server address, station identifier, serial port and scale model, printer address, outbox path.
- 04Connect the scale; align protocol parameters (baud rate etc.) on the scale and in the configuration.
- 05Set up and start the service.
- 06Verify: live weight visible in the terminal; test label printable [Engineering: test function]; station shows "Online" on the server.
3.3 Bench browser
Start the browser in kiosk/full-screen mode with the terminal URL of the site server [Engineering: URL scheme, station mapping]. Configure autostart. Light/dark mode is stored per bench in the browser.
4
Integration
ERP: myfactory
The site server uses a dedicated adapter owning the booking transaction end to end: reading production orders and BOMs, writing the stock movement per weighing. [Engineering: required rights, endpoints, master-data requirements – especially GHS data and container/Quant identifiers in the material master]
WMS: xstorage
Stock booking in the same transaction as the ERP booking [Engineering: details].
ERP: weclapp
A dedicated weclapp adapter with the same booking transaction per weighing. weclapp has no container barcodes: instead of a Quant, the operator scans the product number and the storage place, and the server checks the pair against weclapp's own stock. [Engineering: required rights, API access, master-data requirements]
Further systems
The integration layer (ErpPort) is deliberately narrow and implementation-agnostic. Further ERP/WMS adapters are possible but not available today. Enquiries to D-Automation.
5
Operation
5.1 Monitoring
Station status on the site server [Engineering: view/endpoint]; outbox depth per station (records not yet transmitted) [Engineering: visibility]; logs [Engineering: paths, rotation] – note: logs are not the audit trail.
5.2 Failure behaviour
| Failure | Behaviour | Action |
|---|---|---|
| Network/server during a weighing | Weighing finishes, stored locally, labelled; booking caught up idempotently | Restore connection; outbox drains automatically |
| Network/server, no order open | New orders and logins not possible (by design) | Restore connection |
| Scale unreachable | No live weight; weighing not possible | Check cable/port/protocol |
| Printer unreachable | Record is stored; label missing | Check printer; reprint [Engineering: function] |
| ERP/WMS unreachable | Server holds the booking [Engineering: behaviour] | Restore ERP availability |
5.3 Backup
Back up the site server database including the audit trail regularly [Engineering: procedure]. Station outbox directories hold only temporarily untransmitted records; they must never be deleted manually.
5.4 Audit trail
Every weighing, refusal, licence check and update is an entry in a hash-chained audit trail with trusted timestamp. QA export: [Engineering: function/format]. Checkpoints for verification: [Engineering: procedure]. The audit trail is never rotated and must not be edited.
6
Software updates
Releases are distributed as Ed25519-signed manifests. At the station:
- 01Fetch the manifest; verify the signature before parsing anything.
- 02Fetch the artifact; verify size and checksum – truncated or tampered responses are rejected.
- 03Stage the artifact; activate only at a safe point: no open weighing, no records in the outbox.
7
Licensing
Ground rule: a licence problem never stops a weighing – not the one in progress, not its label, not its booking, not a queued record replaying after an outage.
- The site verifies a signed, offline-checkable entitlement against its own clock; no internet connection needed.
- 3 weeks before expiry: warning. After expiry: 2-week grace period. Then: no new production orders – weighings in progress unaffected.
- All licence checks are in the audit trail.
8
Security
- Station agents: outbound only; no inbound ports at the bench.
- Site server: only component with ERP/WMS access; credentials [Engineering: storage/encryption].
- Tolerance checks server-side; the browser is a display and input layer only.
- Updates cryptographically verified (signature → size → checksum).
- Audit trail hash-chained; tampering detectable.
- User management and roles [Engineering: scope].
9
Migrating from an existing terminal
d-dispensing has been running daily at several manufacturers since 2015, with several million production orders processed; every release goes through hundreds of automated tests before it ships. Recommended approach for replacing your current terminal: pilot bench with defined period, comparison of records, risk-based qualification (see QA & Compliance Brief), cutover with rollback plan. For every batch it must be clear which system provides the leading record.
10
Demo environment
At /demo/ the real terminal component runs against a simulated scale, printer and order book – no backend, part of the static build. The scenario (orders, materials, containers) is maintained in a seed file [Engineering: path]; a customer-specific demo is a content change.
Version: draft 0.1, September 2026.