updated readme.md

This commit is contained in:
2026-10-23 14:33:24 +01:00
parent 8c5e61efd0
commit 568adc034b
+220 -104
View File
@@ -1,153 +1,269 @@
# Access Point # Hardlink
This service handles door card issuance and room ticket printing for hotels. It interacts with the card dispenser over serial, the Assa Abloy lock server, and prints receipts. 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.
## Deployment ## Build and run
We use Salt for deployment. To build and deploy a new version: 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.
1. **Push your branch** with a meaningful commit message: ```powershell
```bash go build -mod=readonly -o hardlink.exe ./cmd/hardlink
git push origin <branch> go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release
``` ./hardlink.exe
2. **Tag and build**: ```
```bash
./tagbuild.sh `preauth-release.exe` is a separate task for releasing due CreditCall
``` preauthorizations; the HTTP service does not run it automatically.
This script:
- Builds the latest `hardlink.exe` binary Start Hardlink with the deployment directory as its working directory:
- Tags the repository with the new version
- Copies `hardlink_<tag>.exe` to `salt/hardlink/files` ```text
3. **Commit the new binary** in Salt: hardlink/
```bash hardlink.exe
cd salt config.yml
git add hardlink/files/hardlink_<tag>.exe TicketLayout.xml
git commit -m "added hardlink" ChipDNAClient/ # Required for CreditCall
git push ChipDnaClient.exe
``` ... SDK dependencies and terminal configuration
4. **Update pillar** (`pillar/hardlink/init.sls`) to point to the new version. hardlink-preauth-release/
5. **Apply the state** on your hosts: preauth-release.exe
```bash config.yml # Configuration for the separate release task
salt '*' state.apply hardlink 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 ## Configuration
Place `config.yml` alongside `hardlink.exe`: Example `config.yml` for card issuance and printing:
```yaml ```yaml
port: 9091 port: 9091
lockType: "assaabloy"
lockservUrl: "http://192.168.4.109:4000" lockservUrl: "http://192.168.4.109:4000"
encoderAddr: "1" encoderAddr: "1"
dispensPort: "COM9" dispensPort: "COM9"
dispensAddr: "15" dispensAddr: "15"
printerName: "EPSON TM-T82II Receipt" printerName: "EPSON TM-T82II Receipt"
logdir: "./logs" logdir: "./logs"
isPayment: false
``` ```
Provide `TicketLayout.xml` for print layout: - `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`:
```xml ```xml
<LayoutOptions> <LayoutOptions>
<LogoPath>C:/Logo/logo.png</LogoPath> <LogoPath>C:/Logo/logo.png</LogoPath>
<TopMostText>Welcome to The Bike and Boot</TopMostText> <TopMostText>Welcome to the hotel</TopMostText>
<BeforeRoomNumberText>Your room number is</BeforeRoomNumberText> <BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
<BeforeDirectionsText></BeforeDirectionsText> <BeforeDirectionsText></BeforeDirectionsText>
<HotelSpecificDetails>This is the hotel details section</HotelSpecificDetails> <HotelSpecificDetails>Hotel information</HotelSpecificDetails>
<CheckOutTimeText>Check Out Time</CheckOutTimeText> <CheckOutTimeText>Check Out Time</CheckOutTimeText>
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath> <RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
</LayoutOptions> </LayoutOptions>
``` ```
## Build & Run ## Door cards and K720 recovery
```bash `POST /issuedoorcard` accepts `Content-Type: application/json`:
# Install dependencies
go mod tidy
# Build the executable ```json
go build -o hardlink.exe {
"roomField": "101",
# Run "checkinTime": "2026-10-23 15:00:00 +0100",
./hardlink.exe "checkoutTime": "2026-10-24 11:00:00 +0100",
"followStr": "0"
}
``` ```
The HTTP server listens on `http://localhost:<port>` (default `9091`). Times use `2006-01-02 15:04:05 -0700`. A successful response is:
## API Endpoints ```json
{"code":200,"message":"Card issued successfully"}
```
### 1. Issue Door Card 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`.
- **Endpoint**: `POST /issuedoorcard` The serial worker exclusively owns AP, RS, FC7 and FC0 communication. Preparation
- **Headers**: `Content-Type: application/json` uses fresh AP observations, a 32-second preparation budget, one-second polling,
- **Body**: and at most three RS/shake recoveries. A valid encoder position permits encoding
```json immediately. Uncertain or unusable observations after FC7 share a four-second
{ window before an uncertain handoff may permit one encoding attempt.
"roomField": "101",
"checkinTime": "2025-04-08 11:16:05 +0100",
"checkoutTime": "2025-04-08 12:00:00 +0100",
"followStr": "0"
}
```
- **Responses**:
- `200 OK`
```json
{ "Code": 200, "Message": "Card issued successfully" }
```
- `4XX` / `5XX`
```json
{ "Code": <status>, "Message": "<error>" }
```
### 2. Print Room Ticket 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.
- **Endpoint**: `POST /printroomticket` When `LockSequence` returns, the handler cancels and joins recovery before one
- **Headers**: `Content-Type: application/xml` FC0 delivery attempt. Caller cancellation stops recovery; already-started encoding
- **Body**: retains its original lock-server timeout and result. Recovery/FC0 errors do not
```xml replace that result. Successful encoding keeps the existing best-effort next-card
<roomdetails> prestage. Idle maintenance and passive status polling remain separate from the
<customername>John Doe</customername> foreground issuance operation.
<checkoutdatetime>16/05/2025 11:00 am</checkoutdatetime>
<roomno>103</roomno>
<roommap>map.png</roommap>
<roomdirections>Follow corridor...</roomdirections>
</roomdetails>
```
- **Responses**:
- `200 OK`
```json
{ "Code": 200, "Message": "Print job sent successfully" }
```
- `4XX` / `5XX`
```json
{ "Code": <status>, "Message": "<error>" }
```
## Packages See the [K720 dispenser contract](internal/dispenser/K720_DISPENSER_CONTRACT.md)
for status classifications, clearance rules, recovery limits and cancellation.
Concurrent recovery still requires validation with the physical K720 and lock server.
### `main` ## Room tickets
- Entry point: reads config, sets up logging, initializes dispenser and lock server, loads print layout, and starts HTTP server.
### `dispenser` `POST /printroomticket` accepts `Content-Type: application/xml`:
- Communicates with the card dispenser via serial port.
- Commands: check status, move card, eject card.
### `lockserver` ```xml
- Manages TCP connection to the Assa Abloy lock server. <roomdetails>
- Sends heartbeat and encoding commands. <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>
```
### `printer` Success returns HTTP `200` with:
- Loads `TicketLayout.xml` into `LayoutOptions`.
- Provides `printLogo`, `printMap`, `BuildRoomTicket`, `SendToPrinter`.
- Converts images to ESC/POS raster commands with dithering and transparency support.
### `cmstypes` ```json
- Defines JSON and XML payload structures for door cards and room details. {"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):
```json
{"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"}
```
CreditCall monetary PREAUTH JSON example (string fields):
```json
{"amount":"3100","transactionType":"Sale","checkoutDate":"2026-10-24 00:00:00 +0000"}
```
Zero-value account verification:
```json
{"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](CREDITCALL_STREAMING.md) 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 ## Logging
Logs are written in JSON format to `<logdir>/hardlink.log`. 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.
MIT © FutureSens Systems ## Verification
Use repository-local build and temporary caches from PowerShell:
```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:
```bash
salt '<target-minion>' state.apply hardlink
```