Configuration

bLIS Gateway uses a single YAML configuration file. By default, the install script places this file at /etc/blis-gateway/gateway.yaml. When running with Docker, mount it to /etc/blis-gateway/config.yaml. You can generate a default configuration file with:

blis-gateway config generate --output gateway.yaml --defaults

Minimal example

A working configuration requires three sections — input, lis, and instruments:

input:
  type: tcp

lis:
  endpoint: "https://your-blis-instance.example.com/api/messages"

instruments:
  - name: "Hematology-1"
    driver: "astm"
    input:
      port: 3000

Configuration reference

`input`

Controls how the gateway receives data from instruments.

Field	Type	Default	Description
`type`	`tcp` or `mqtt`	`tcp`	Transport protocol. Use `tcp` for direct instrument connections, `mqtt` for broker-based setups.
`listenOnly`	boolean	`false`	When `true`, the gateway receives and logs messages but does not send acknowledgments back to instruments. Useful for testing alongside an existing integration.

When type is mqtt, provide the mqtt section:

Field	Type	Default	Description
`mqtt.broker`	string	—	MQTT broker hostname.
`mqtt.port`	number	`1883`	MQTT broker port.
`mqtt.username`	string	—	Broker username.
`mqtt.password`	string	—	Broker password.
`mqtt.clientId`	string	auto-generated	Client ID for the MQTT connection.

`lis`

Defines the connection to your bLIS server.

Field	Type	Default	Description
`endpoint`	string	—	The bLIS API URL that receives instrument messages.
`timeout`	number	`5000`	Request timeout in milliseconds.
`retryAttempts`	number	`3`	Number of retry attempts if the request fails.
`retryDelay`	number	`1000`	Delay between retries in milliseconds.
`headers`	object	—	Additional HTTP headers (e.g., `Authorization: "Bearer ..."` ).

`instruments`

A list of instrument definitions. Each entry configures one instrument connection.

Field	Type	Default	Description
`name`	string	—	A unique, descriptive name for this instrument (e.g., `"Hematology-1"`).
`driver`	string	—	The driver to use. Determines the communication protocol and any vendor-specific handling. Common values: `astm`, `sysmex-xn`, `alinity-s`, `exl`, `clinitek`.
`logOnly`	boolean	`false`	When `true`, the gateway logs messages from this instrument but does not forward them to bLIS. Useful for testing a new instrument connection.
`respondOnLisFailure`	boolean	`false`	When `true`, the gateway sends a response to the instrument even if the bLIS request fails. When `false`, no response is sent and the instrument will time out, alerting the operator.
`description`	string	—	Optional description of the instrument.
`serialNumber`	string	—	Optional serial number for identification.
`apiKey`	string	—	API key for authenticating with bLIS on behalf of this instrument.

TCP input (when `input.type` is `tcp`)

Field	Type	Description
`input.port`	number	TCP port the gateway listens on for this instrument. Each instrument must use a unique port.
`input.ip`	string	Optional. Restrict connections to a specific instrument IP address.

MQTT input (when `input.type` is `mqtt`)

Field	Type	Description
`input.subscribeTopic`	string	MQTT topic for messages from the instrument to the gateway.
`input.publishTopic`	string	MQTT topic for messages from the gateway to the instrument.

`logging`

Controls log output, file rotation, and message persistence.

Field	Type	Default	Description
`level`	string	`info`	Log level: `debug`, `info`, `warn`, or `error`.
`logDir`	string	`/var/log/blis-gateway`	Directory for log files.
`logRetentionDays`	number	`10`	Number of days to keep log files before automatic cleanup.
`includeRawData`	boolean	`false`	Include raw hex data in logs. Enable this when troubleshooting instrument communication.

`logging.persistence`

Optional SQLite-based message storage for auditing and troubleshooting.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable message persistence.
`dbPath`	string	`/var/lib/blis-gateway/messages.db`	Path to the SQLite database file.
`retentionDays`	number	`30`	Number of days to keep stored messages. Set to `0` to keep messages indefinitely.

`web`

Controls the built-in web management dashboard.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable the web dashboard.
`port`	number	`8080`	Port for the web interface.
`hostname`	string	`0.0.0.0`	Hostname to bind to. Use `0.0.0.0` for all interfaces, or a specific IP to restrict access.

When enabled, open http://<gateway-host>:8080 in a browser to access the dashboard. The dashboard provides:

Real-time connection status for each instrument
Live log streaming
Message history and search
Trace viewer for end-to-end message tracking
Current gateway configuration

`service`

Optional metadata about the gateway instance.

Field	Type	Default	Description
`name`	string	`blis-gateway`	Service name.
`description`	string	`BLIS Gateway`	Service description.

Full example

input:
  type: tcp

lis:
  endpoint: "https://your-blis-instance.example.com/api/messages"
  timeout: 30000
  retryAttempts: 3
  retryDelay: 5000

instruments:
  - name: "Hematology-1"
    driver: "astm"
    input:
      port: 3000
      ip: "192.168.1.100"
    description: "Sysmex XN-1000 Hematology Analyzer"

  - name: "Chemistry-1"
    driver: "astm"
    logOnly: true
    input:
      port: 3001
    description: "Beckman Coulter AU680"

logging:
  level: "info"
  logDir: "./logs"
  logRetentionDays: 30
  includeRawData: true
  persistence:
    enabled: true
    dbPath: "./data/messages.db"
    retentionDays: 30

web:
  enabled: true
  port: 8080
  hostname: "0.0.0.0"

service:
  name: "BLIS Gateway"
  description: "Lab instrument communication gateway"

Validate your configuration

Run the validate command to check for errors before starting the gateway:

blis-gateway validate --config /etc/blis-gateway/gateway.yaml

The validator checks for:

YAML syntax errors
Missing required fields
Invalid values (e.g., port numbers out of range)
Duplicate instrument names or ports
Mismatched input types (e.g., TCP instruments with MQTT input)

Getting started

Integration

Setup

Minimal example

Configuration reference

`input`

`lis`

`instruments`

TCP input (when `input.type` is `tcp`)

MQTT input (when `input.type` is `mqtt`)

`logging`

`logging.persistence`

`web`

`service`

Full example

Validate your configuration

​Minimal example

​Configuration reference

​input

​lis

​instruments

​TCP input (when input.type is tcp)

​MQTT input (when input.type is mqtt)

​logging

​logging.persistence

​web

​service

​Full example

​Validate your configuration

Minimal example

Configuration reference

`input`

`lis`

`instruments`

TCP input (when `input.type` is `tcp`)

MQTT input (when `input.type` is `mqtt`)

`logging`

`logging.persistence`

`web`

`service`

Full example

Validate your configuration