updated readme.md
This commit is contained in:
@@ -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
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user