Hardlink

Hardlink is the Windows hotel-kiosk service for K720 card dispensing, door-key encoding, room-ticket and payment-receipt printing, and terminal payments. It supports Assa Abloy, Omnitec, Salto, TLJ and dormakaba lock servers, and CreditCall (ChipDNA), Dojo and PayBridge payment providers.

Build and run

Run from the repository root on Windows with Go 1.23.2 or newer and access to the private Gitea modules. The entry point is cmd/hardlink, not the repository root.

go build -mod=readonly -o hardlink.exe ./cmd/hardlink
go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release
./hardlink.exe

preauth-release.exe is a separate task for releasing due CreditCall preauthorizations; the HTTP service does not run it automatically.

Start Hardlink with the deployment directory as its working directory:

hardlink/
  hardlink.exe
  config.yml
  TicketLayout.xml
  ChipDNAClient/                 # Required for CreditCall
    ChipDnaClient.exe
    ... SDK dependencies and terminal configuration
  hardlink-preauth-release/
    preauth-release.exe
    config.yml                  # Configuration for the separate release task
  logs/

config.yml and the ChipDNA executable path are relative to the working directory. TicketLayout.xml is loaded beside the Hardlink executable. Configure the release task's working directory to contain its own config.yml.

The HTTP server binds to :<port> on all interfaces; the default port is 9091.

Configuration

Example config.yml for card issuance and printing:

port: 9091
lockType: "assaabloy"
lockservUrl: "http://192.168.4.109:4000"
encoderAddr: "1"
dispensPort: "COM9"
dispensAddr: "15"
printerName: "EPSON TM-T82II Receipt"
logdir: "./logs"
isPayment: false
  • lockType is required: assaabloy, omnitec, salto, tlj or kaba.
  • cert supplies the certificate value used by TLJ's GuestCard API.
  • dispensAddr is the two-character serial device address.
  • printerName must match an installed Windows printer.
  • Payment setup additionally uses isPayment, hotel, kiosk, cmsurl and, when CMS does not select a provider, paymentProvider (creditcall, dojo or paybridge). Provider-specific terminal settings are read from CMS.
  • SQL configuration uses dbport, dbname, dbuser and dbpassword; configure these for monetary CreditCall PREAUTH persistence and the release task.
  • senderroremails contains recipients for operational error emails.
  • timeoutSeconds defaults to 300 for the generic payment handler. CreditCall retains its independent 300-second start/confirmation call bounds.

Example TicketLayout.xml:

<LayoutOptions>
  <LogoPath>C:/Logo/logo.png</LogoPath>
  <TopMostText>Welcome to the hotel</TopMostText>
  <BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
  <BeforeDirectionsText></BeforeDirectionsText>
  <HotelSpecificDetails>Hotel information</HotelSpecificDetails>
  <CheckOutTimeText>Check Out Time</CheckOutTimeText>
  <RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
</LayoutOptions>

Door cards and K720 recovery

POST /issuedoorcard accepts Content-Type: application/json:

{
  "roomField": "101",
  "checkinTime": "2026-10-23 15:00:00 +0100",
  "checkoutTime": "2026-10-24 11:00:00 +0100",
  "followStr": "0"
}

Times use 2006-01-02 15:04:05 -0700. A successful response is:

{"code":200,"message":"Card issued successfully"}

Errors use the same code/message JSON structure with an HTTP error status. Exact physical empty (0x38) during preparation returns 503; preparation exhaustion and encoding errors return 502.

The serial worker exclusively owns AP, RS, FC7 and FC0 communication. Preparation uses fresh AP observations, a 32-second preparation budget, one-second polling, and at most three RS/shake recoveries. A valid encoder position permits encoding immediately. Uncertain or unusable observations after FC7 share a four-second window before an uncertain handoff may permit one encoding attempt.

Only an uncertain handoff enables recovery concurrently with the single LockSequence. It carries forward the shakes already used and runs the remaining RS -> 2-second settle -> AP -> FC7 -> AP recovery sequence. Encoder confirmation stops recovery, including before FC7 if the diagnostic AP confirms the card. Unusable diagnostic AP is logged; it does not create a new fatal encoding error. There is no second LockSequence or extra plain FC7 retry.

When LockSequence returns, the handler cancels and joins recovery before one FC0 delivery attempt. Caller cancellation stops recovery; already-started encoding retains its original lock-server timeout and result. Recovery/FC0 errors do not replace that result. Successful encoding keeps the existing best-effort next-card prestage. Idle maintenance and passive status polling remain separate from the foreground issuance operation.

See the K720 dispenser contract for status classifications, clearance rules, recovery limits and cancellation. Concurrent recovery still requires validation with the physical K720 and lock server.

Room tickets

POST /printroomticket accepts Content-Type: application/xml:

<roomdetails>
  <customername>John Doe</customername>
  <checkoutdatetime>24/10/2026 11:00 am</checkoutdatetime>
  <roomno>103</roomno>
  <roommap>map.png</roommap>
  <roomdirections>Follow the corridor...</roomdirections>
</roomdetails>

Success returns HTTP 200 with:

{"code":200,"message":"Print job sent successfully"}

The printer package loads the ticket layout, renders ESC/POS text and raster images, and sends the output to the configured Windows printer.

Payments

Endpoint Request Purpose
POST /api/payment/sale JSON SALE streaming for CreditCall, Dojo or PayBridge
POST /api/payment/preauth JSON CreditCall PREAUTH/account-verification streaming
POST /takepayment text/xml Legacy CreditCall SALE
POST /takepreauth text/xml Legacy CreditCall PREAUTH/account verification

The streaming endpoints return application/x-ndjson: progress frames followed by a final result. CreditCall's structured final frame uses result; Dojo/PayBridge use their existing response frame. Progress is observational and never determines payment success or failure.

SALE JSON example (integer minor units):

{"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"}

CreditCall monetary PREAUTH JSON example (string fields):

{"amount":"3100","transactionType":"Sale","checkoutDate":"2026-10-24 00:00:00 +0000"}

Zero-value account verification:

{"amount":"","transactionType":"AccountVerification","checkoutDate":""}

CreditCall SALE confirms approved starts; PREAUTH does not confirm. PREAUTH uses the provider-returned TRANSACTION_TYPE and TOTAL_AMOUNT. Approved returned ACCOUNT VERIFICATION needs no amount and is not persisted. Approved returned SALE schedules persistence using the returned amount; it never substitutes the request amount. SQL failures fall back to preauth_spool.ndjson in logdir. The current SQL release date is checkout plus 96 hours, using the existing local-midnight date conversion.

After financial dispatch, a kiosk disconnect stops stream delivery without cancelling CreditCall result processing, SALE confirmation, receipts or PREAUTH persistence scheduling. Never restart a transaction or fall back to a legacy endpoint because streaming delivery failed.

Deploy a matching ChipDNAClient build: Hardlink starts ./ChipDNAClient/ChipDnaClient.exe and calls it on 127.0.0.1:18181. That deployed EXE must include TRANSACTION_TYPE and optional TOTAL_AMOUNT in its streaming allowlist; an older build can support SALE while breaking PREAUTH classification.

See CreditCall streaming for frame schemas, progress ownership and timeout details. The current SQL implementation in internal/db/db.go defines release scheduling.

Additional endpoints

Endpoint Purpose
/dispenserstatus Cached stock/status in a code/message JSON response
POST /testissuedoorcard Diagnostic issuance path; not the normal delivery workflow
/ping-pdq Read ChipDNA terminal status
POST /logerror Receive ChipDNA error notifications

Logging

JSON logs are written to <logdir>/hardlink.log. Weekly rotation uses local Monday midnight and retains hardlink.1.log through hardlink.13.log. The separate release task writes preauth-release.log with the same rotation policy.

K720 logs include uncertain handoff, raw AP status/classification, RS/FC7 attempts, remaining shake budget, recovery stop reason and encoding duration. PREAUTH logs include processor result/type, transaction reference, approval/persistence decision, missing fields, and SQL/spool outcomes without card or receipt payloads.

Verification

Use repository-local build and temporary caches from PowerShell:

New-Item -ItemType Directory -Force .cache/go-build, .cache/tmp | Out-Null
$env:GOCACHE = Join-Path $PWD '.cache/go-build'
$env:GOTMPDIR = Join-Path $PWD '.cache/tmp'

go test -mod=readonly -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -race -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -count=1 -skip '^Test_SendMail$' ./...
go vet -mod=readonly ./...
go build -mod=readonly ./...
git diff --check

Test_SendMail sends real email and is excluded from offline verification. Automated tests do not replace physical dispenser, encoder, terminal or printer validation.

Deployment

Production deployment uses Salt. Build the intended revision and deploy the versioned Windows package through the Salt repository and Hardlink pillar.

Where installed, local release tooling is invoked as bash ./winbuild.sh <version> from the development branch. It builds Hardlink and the release task, packages the existing ChipDNAClient/ directory into hardlink_windows_<version>.zip, and copies it to salt/hardlink/files. It also checks out/pulls the Salt and pillar repositories and commits/pushes the package in Salt; it does not create a Git tag. Ensure ChipDNAClient/ contains the intended build before packaging.

Update pillar/hardlink/init.sls to select the package version, then apply the Hardlink state to the intended hosts:

salt '<target-minion>' state.apply hardlink
S
Description
No description provided
Readme
665 KiB
Languages
Go 100%