Abhard Configuration Reference

Settings live in abhard.yaml. A configuration the service creates for itself holds no devices, and its whitelist is widened to the /24 of whichever network card the service could identify.

An example covering every supported device ships with the program — /usr/share/doc/abhard/examples/abhard.yaml.example on Linux, C:\Program Files\Abacus\Tools\examples\abhard.yaml.example on Windows.

The `main` block

Key	Default	Description
`port`	`4601`	Port the service listens on
`whitelist`	`127.0.0.1`	Allowed addresses, semicolon-separated. Accepts single addresses (`127.0.0.1`), ranges (`172.27.0.2-10`) and subnets (`192.168.50.0/24`)
`logfile`	`abhard.log`	Log file name
`event_socket`	`true`	Enable the event channel
`event_socket_host`	detected automatically	The address the service hands to cash desks as the event-channel endpoint
`event_socket_port`	`4651`	Event channel port
`event_socket_ping_idle`	`4`	Seconds of silence after which the cash desk is pinged

The event channel

The event channel is a permanent TCP connection over which the service pushes barcode scans to the cash desk without being asked. The desk that connected last takes the scans; the other connected desks get none until they claim them again. A desk that fails to answer a ping within two seconds is treated as gone and disconnected.

The service listens on every network card but advertises exactly event_socket_host. Automatic detection takes the first 192.168.* address, then any non-local one, and only then 127.0.0.1. On a machine with several network cards it can pick the wrong one — the cash desks then receive an unusable address and never connect. Set it explicitly in that case.

Devices

devices is a sequence; each entry describes one device.

Key	Required	Description
`name`	Yes	Device name; the cash desk and the log refer to the device by it. An entry without a name is skipped
`type`	Yes	`scaner`, `printer`, `scales`, `prro`
`subtype`	Yes	See below; not needed for `scales`

The remaining keys depend on the type/subtype pair. Valid pairs: scaner/serial, scaner/hid, scaner/devfile, printer/escpos, printer/dummy, scales, prro/eusign, plus any type with subtype: redirect. An unknown pair is skipped with a warning in the log — the service starts, the device simply is not there.

The scanner type is spelled scaner, with one n. scanner is an unknown type.

Shared RS-232 parameters

Apply to scaner/serial and to scales.

Key	Default	Description
`device`	—	Serial port: `/dev/ttyS0`, `COM1`
`baudrate`	`9600`	Baud rate
`bits`	`8`	Data bits
`parity`	`N`	`N` · `E` · `O` · `S` · `M`
`stopbits`	`1`	Stop bits
`softflow`	`false`	XON/XOFF flow control
`hardflow`	`false`	RTS/CTS flow control

`scaner/serial`

Barcode scanner on a serial port. It takes no parameters beyond the RS-232 ones. While the device file is missing the scanner reports "Not found" and the service retries every second — a scanner unplugged and plugged back in recovers on its own.

`scaner/hid` — Linux only

USB scanner driven directly through libusb.

Key	Default	Description
`vendor_id`	—	Vendor code, hexadecimal, no `0x` prefix: `0536`
`product_id`	—	Model code, same form: `01b3`

lsusb prints both.

`scaner/devfile` — Linux only

USB scanner read through a device file.

Key	Default	Description
`device`	—	Device file path: `/dev/hidraw0`

`printer/escpos`

ESC/POS receipt printer.

Key	Default	Description
`device`	—	Device file: `/dev/usb/lp0`, `COM2`
`width`	`40`	Characters per line; long lines wrap and separator rules are drawn to this width
`codepage`	(none)	Printer codepage number. If unset, the printer keeps whatever it is currently set to
`softrender`	`false`	`true` — the service draws the QR code and sends it as an image; needed for printers with no QR command of their own
`feed_lines`	`3`	Lines to feed before the receipt is cut

`printer/dummy`

Saves receipts as text files instead of printing them. Useful for checking the cash desk configuration where there is no printer yet.

Key	Default	Description
`target_dir`	(none)	Where to put the files. If unset, the receipt goes to the log
`width`	`40`	Characters per line

`scales`

Scales on a serial port. They need no subtype.

Key	Default	Description
`model`	`VTA16`	`VTA16` or `DigiDS`
`timeout`	`5000`	Milliseconds to wait for the scales before returning an error

Plus the RS-232 parameters; device defaults to /dev/ttyS0 for scales.

`prro/eusign`

Ukrainian software fiscal register. What the cash desk does with it is covered in the PRRO section.

Key	Default	Description
`key_path`	—	Private key file
`key_password`	—	Key passphrase
`certs_path`	program directory	Directory with certificates and revocation lists
`lib_path`	`/opt/abacus/lib/`	Signing library directory. If it does not exist, the `lib/` subdirectory of the program directory
`proxy_address`	(none)	Proxy server through which the tax service is reachable
`proxy_port`	`0`	Proxy port
`proxy_user`	(none)	Proxy user
`proxy_pass`	(none)	Proxy password
`timeout_ms`	`30000`	Milliseconds to wait for the tax service
`http_retries`	`2`	How many times to repeat a request that did not get through
`http_retry_delay_ms`	`1000`	Pause between retries

A path that does not start at the root or a drive letter is resolved against the program directory.

`subtype: redirect`

A device physically attached to another cash desk — scanner, printer, scales or PRRO. Instead of working with hardware the service returns the address of that abhard, and the request is carried out there.

Key	Default	Description
`redirect_url`	—	Base address of the remote abhard
`redirect_name`	—	Name of the device on it

subtype: redirect overrides type, so the rest of that type's parameters have no effect here. What this requires on the Launcher side is covered in the Launcher section.

Access tokens

Neither the installer nor the administrator creates the abhard.json token file. The service starts out unclaimed, and the first admin client takes it over: activating the services in the Sklad configuration editor (or initialising from the Launcher) receives an administrator token from the service, then issues per-worker tokens and stores them in the database. No key is ever copied by hand.

A service can only be claimed while the token file is absent. After that a previously issued administrator token is required, and a repeated initialisation answers "already initialised".

Role	Permissions
`administrator`	Everything, including issuing and revoking tokens
`worker`	All hardware operations; cannot issue or revoke tokens
`probationer`	Same as `worker`, but cannot produce a Z-report

A token with no expiry date never expires. An expired token is rejected and removed from the file at once.

Example

main:
  port: 4601
  whitelist: '127.0.0.1;192.168.50.0/24;172.27.0.2-10'
  logfile: 'abhard.log'
  event_socket: true
  event_socket_host: '192.168.50.10'
  event_socket_port: 4651
  event_socket_ping_idle: 4

devices:
  - name: 'main_scaner'
    type: 'scaner'
    subtype: 'serial'
    device: '/dev/ttyS0'
    baudrate: 9600

  - name: 'usb_scaner'
    type: 'scaner'
    subtype: 'hid'
    vendor_id: '0536'
    product_id: '01b3'

  - name: 'main_printer'
    type: 'printer'
    subtype: 'escpos'
    device: '/dev/usb/lp0'
    width: 42
    feed_lines: 3

  - name: 'shared_printer'
    type: 'printer'
    subtype: 'redirect'
    redirect_url: 'http://192.168.50.4:4601'
    redirect_name: 'main_printer'

  - name: 'main_scales'
    type: 'scales'
    device: '/dev/ttyS1'
    model: 'DigiDS'
    timeout: 5000

  - name: 'main_prro'
    type: 'prro'
    subtype: 'eusign'
    key_path: 'keys/pb_0123456789.jks'
    key_password: 'Password1234'
    certs_path: 'cert/'

Checking it works

$KEY is any valid token of the service.

curl -H "X-API-KEY: $KEY" http://192.168.50.10:4601/api/status

One record per device: name, type, state and last error. A device missing from the answer was never created — look for the warning in the log. /api/list returns every available request.

PRRO has a connectivity check of its own:

# check now (the numbers in the answer are per-stage timings)
curl -H "X-API-KEY: $KEY" http://192.168.50.10:4601/api/prro/main_prro/selftest/run

# recent document submission attempts
curl -H "X-API-KEY: $KEY" "http://192.168.50.10:4601/api/prro/main_prro/history?limit=20"

After three consecutive failures the service runs that check by itself; the result stays available at /api/prro/<name>/selftest.

A 401 means a missing or invalid token; a 403 means an address absent from the whitelist, or an action this token's role may not perform.

Abhard Configuration Reference

The main block

The event channel

Devices

Shared RS-232 parameters

scaner/serial

scaner/hid — Linux only

scaner/devfile — Linux only

printer/escpos

printer/dummy

scales

prro/eusign

subtype: redirect