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:
|
||||
```bash
|
||||
git push origin <branch>
|
||||
```
|
||||
2. **Tag and build**:
|
||||
```bash
|
||||
./tagbuild.sh
|
||||
```
|
||||
This script:
|
||||
- Builds the latest `hardlink.exe` binary
|
||||
- Tags the repository with the new version
|
||||
- Copies `hardlink_<tag>.exe` to `salt/hardlink/files`
|
||||
3. **Commit the new binary** in Salt:
|
||||
```bash
|
||||
cd salt
|
||||
git add hardlink/files/hardlink_<tag>.exe
|
||||
git commit -m "added hardlink"
|
||||
git push
|
||||
```
|
||||
4. **Update pillar** (`pillar/hardlink/init.sls`) to point to the new version.
|
||||
5. **Apply the state** on your hosts:
|
||||
```bash
|
||||
salt '*' state.apply hardlink
|
||||
```
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
Place `config.yml` alongside `hardlink.exe`:
|
||||
Example `config.yml` for card issuance and printing:
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
<LayoutOptions>
|
||||
<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>
|
||||
<BeforeDirectionsText></BeforeDirectionsText>
|
||||
<HotelSpecificDetails>This is the hotel details section</HotelSpecificDetails>
|
||||
<HotelSpecificDetails>Hotel information</HotelSpecificDetails>
|
||||
<CheckOutTimeText>Check Out Time</CheckOutTimeText>
|
||||
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
|
||||
</LayoutOptions>
|
||||
```
|
||||
|
||||
## Build & Run
|
||||
## Door cards and K720 recovery
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
go mod tidy
|
||||
`POST /issuedoorcard` accepts `Content-Type: application/json`:
|
||||
|
||||
# Build the executable
|
||||
go build -o hardlink.exe
|
||||
|
||||
# Run
|
||||
./hardlink.exe
|
||||
```json
|
||||
{
|
||||
"roomField": "101",
|
||||
"checkinTime": "2026-10-23 15:00:00 +0100",
|
||||
"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`
|
||||
- **Headers**: `Content-Type: application/json`
|
||||
- **Body**:
|
||||
```json
|
||||
{
|
||||
"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>" }
|
||||
```
|
||||
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.
|
||||
|
||||
### 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`
|
||||
- **Headers**: `Content-Type: application/xml`
|
||||
- **Body**:
|
||||
```xml
|
||||
<roomdetails>
|
||||
<customername>John Doe</customername>
|
||||
<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>" }
|
||||
```
|
||||
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.
|
||||
|
||||
## 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`
|
||||
- Entry point: reads config, sets up logging, initializes dispenser and lock server, loads print layout, and starts HTTP server.
|
||||
## Room tickets
|
||||
|
||||
### `dispenser`
|
||||
- Communicates with the card dispenser via serial port.
|
||||
- Commands: check status, move card, eject card.
|
||||
`POST /printroomticket` accepts `Content-Type: application/xml`:
|
||||
|
||||
### `lockserver`
|
||||
- Manages TCP connection to the Assa Abloy lock server.
|
||||
- Sends heartbeat and encoding commands.
|
||||
```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>
|
||||
```
|
||||
|
||||
### `printer`
|
||||
- Loads `TicketLayout.xml` into `LayoutOptions`.
|
||||
- Provides `printLogo`, `printMap`, `BuildRoomTicket`, `SendToPrinter`.
|
||||
- Converts images to ESC/POS raster commands with dithering and transparency support.
|
||||
Success returns HTTP `200` with:
|
||||
|
||||
### `cmstypes`
|
||||
- Defines JSON and XML payload structures for door cards and room details.
|
||||
```json
|
||||
{"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
|
||||
|
||||
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