Weegschalen Integreren met Uw Software via een API

Wat een weegschaal-API doet

Een weegschaal-API (application programming interface) stelt uw eigen software in staat gewichten en records van een weegschaal uit te lezen en er commando's naar te sturen, met gebruik van een gedocumenteerde, machineleesbare interface in plaats van een display af te lezen (screen-scraping) of een printerstream te ontleden. Met een API kan een vangstregistratieprogramma, een besturing van een verpakkingslijn of een dashboard aan de wal de weegschaal gebruiken als databron en als bestuurbaar apparaat.

Oudere integraties leunden op een continue seriële uitvoer: de weegschaal stuurde meerdere keren per seconde een tekstregel met het gewicht via RS232, en het ontvangende programma ontleedde deze. Dat werkt nog steeds, maar het gaat maar één kant op en het formaat verschilt per fabrikant. Een netwerk-API voegt gestructureerde data toe (meestal JSON), toegang tot opgeslagen records en presets, en een vastgelegde manier om commando's te geven. De fysieke kant van die verbinding komt aan bod in RS232, Ethernet, USB, Wi-Fi of Bluetooth LE: een Interface Kiezen voor uw Weegschaal.

Typische endpoints en functies

De meeste weegschaal-API's bieden dezelfde vijf groepen functies: live gewicht, stabiliteit en status, presets, logs, en commando's zoals nul, tarra en print.

Onderstaande tabel is een algemene illustratie van hoe een dergelijke API doorgaans is opgebouwd. Dit is niet het schema van een specifiek product, ook niet van WPL.

Twee principes maken zo'n API voorspelbaar. Data lezen gebruikt veilige methoden die niets op de weegschaal wijzigen; presets wijzigen of commando's geven gebruikt methoden waarvan het effect gedocumenteerd is. HTTP-semantiek, inclusief welke methoden veilig en idempotent zijn, is gedefinieerd in RFC 9110. Veel leveranciers beschrijven hun HTTP-API's in het OpenAPI Specification-formaat, waarmee clientcode kan worden gegenereerd en verzoeken gevalideerd kunnen worden.

Voorbeeldpayloads

Een live-gewichtsrespons moet de waarde, de eenheid, een tijdstempel en de status bevatten die nodig zijn om te bepalen of de waarde gebruikt mag worden.

Uitsluitend een illustratief voorbeeld, niet het daadwerkelijke API-schema van WPL:

{

"scale_id": "scale-03",

"timestamp": "2026-09-14T06:42:17.250Z",

"net": 5.120,

"tare": 0.450,

"unit": "kg",

"stable": true,

"zero": false,

"check": "ok",

"preset": "COD-GUT-5KG"

}

De velden die het meest van belang zijn voor integratie zijn stable en timestamp. Een programma dat een doosgewicht registreert, mag alleen een meting accepteren die als stabiel is gemarkeerd, en moet tijdstempels vergelijken om een verouderde waarde te herkennen wanneer de verbinding hapert. Gewichten moeten JSON-getallen zijn met een vaste eenheid, geen strings met de eenheid erachter geplakt, zodat ze zonder parsen kunnen worden opgeteld (RFC 8259).

Een commando-uitwisseling, opnieuw als illustratief voorbeeld:

POST /commands

{ "command": "tare", "request_id": "7f3c-0192" }

200 OK

{ "request_id": "7f3c-0192", "result": "done", "tare": 0.450, "unit": "kg" }

De request_id stelt de client in staat het antwoord aan zijn verzoek te koppelen en stelt de weegschaal in staat een herhaling te herkennen van een commando dat al is uitgevoerd, zodat een verloren antwoord over een slechte verbinding niet tot een tweede tarrering leidt.

Polling versus push

Polling betekent dat de client de weegschaal met tussenpozen om data vraagt; push betekent dat de weegschaal data stuurt zodra er iets verandert. Polling is eenvoudiger te bouwen, push is efficiënter voor live waarden en gebeurtenissen.

De kosten van polling zijn gemakkelijk te onderschatten. Vijf keer per seconde live gewicht pollen levert 432.000 verzoeken per dag per client op. Voor een live weergave is dat acceptabel op een lokaal netwerk; via een satellietverbinding niet. Een praktisch patroon is push of snelle polling aan boord te gebruiken voor weergaven en besturing, en afgeronde records met tussenpozen uit het logboek te verzamelen voor alles wat het schip verlaat.

Live waarden versus records

Behandel het live gewicht als weergavewaarde en het logboek als de bron van waarheid (system of record). Als uw software eigen records opbouwt uit gepollde live waarden, kan het wegingen tussen pollingmomenten missen of dezelfde doos tweemaal registreren. Geregistreerde records met een unieke record-ID uit het logboek van de weegschaal lezen voorkomt beide problemen. Wat die records moeten bevatten, staat beschreven in Weegdata Loggen op Zee.

Commando's, veiligheid en toegangscontrole

Externe commando's zijn krachtig en moeten worden beperkt: een nul of tarra die op het verkeerde moment wordt verzonden, verstoort stilzwijgend elke volgende weging.

• Controleer de toestand voordat u handelt. Nul alleen een lege, stabiele weegschaal; tarreer alleen met de verpakking op het platform en een stabiele aflezing.
• Bevestig het resultaat. Lees de status na een commando in plaats van te veronderstellen dat het is geslaagd.
• Maak herhalingen onschadelijk. Gebruik request-ID's of idempotente bewerkingen zodat een herhaald verzoek hetzelfde effect heeft als één verzoek.
• Authenticeer en beperk toegang. Scheid leestoegang van commando- en preset-bewerkingsrechten; stel weegschalen niet rechtstreeks bloot aan het internet.
• Log commando's. Externe nul-, tarra- en presetwijzigingen horen in de audit trail, samen met de client die ze verzond.

Richtlijnen voor het beheren van cyberrisico's aan boord van schepen worden door de IMO gepubliceerd in de richtlijnen voor maritiem cyberrisicobeheer.

Integratie stap voor stap

Een betrouwbare weegschaalintegratie volgt een vaste volgorde van documentatie tot veldtest.

1. Verkrijg de API-documentatie voor het exacte weegschaalmodel en de softwareversie.
2. Inventariseer de data die uw software nodig heeft en koppel elk item aan een API-veld, inclusief eenheden en decimalen.
3. Bepaal per datastroom of u polt, abonneert of logs uitleest.
4. Gebruik record-ID's om imports idempotent te maken en hiaten te detecteren.
5. Behandel onstabiele metingen, overbelasting, verbindingsverlies en timeouts expliciet.
6. Synchroniseer klokken en sla UTC-tijdstempels op.
7. Test aan boord met het echte netwerk, niet alleen op kantoor, inclusief verbindingsverlies tijdens een dienst.
8. Leg de gebruikte API-versie vast, zodat een latere software-update op wijzigingen kan worden gecontroleerd.

Hoe WPL dit aanpakt

WeightControl bevat een geïntegreerde API die data teruggeeft in JSON. Hiermee kan externe software het huidige gewicht, de status van de gewichtssorteerder en de stabiliteitsindicatie opvragen, presets laden en bewerken, het laatste geregistreerde logrecord en alle opgeslagen logs uitlezen, en commando's geven zoals Nul, Print en Tarra. WeightControl draait op de R10-weegschaal zelf of als externe applicatie die meerdere weegschalen beheert. Documentatie wordt bij elk model meegeleverd; neem voor details en updates contact op met info@wpl-industries.com. De WeightControl IOT-module is als optie beschikbaar op de M2, M3, M5 en M6 series; zie de hub data-integratie voor de bredere architectuur.