Skip to main content
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.
FieldTypeDefaultDescription
typetcp or mqtttcpTransport protocol. Use tcp for direct instrument connections, mqtt for broker-based setups.
listenOnlybooleanfalseWhen 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:
FieldTypeDefaultDescription
mqtt.brokerstring—MQTT broker hostname.
mqtt.portnumber1883MQTT broker port.
mqtt.usernamestring—Broker username.
mqtt.passwordstring—Broker password.
mqtt.clientIdstringauto-generatedClient ID for the MQTT connection.

​
lis

Defines the connection to your bLIS server.
FieldTypeDefaultDescription
endpointstring—The bLIS API URL that receives instrument messages.
timeoutnumber5000Request timeout in milliseconds.
retryAttemptsnumber3Number of retry attempts if the request fails.
retryDelaynumber1000Delay between retries in milliseconds.
headersobject—Additional HTTP headers (e.g., Authorization: "Bearer ..." ).

​
instruments

A list of instrument definitions. Each entry configures one instrument connection.
FieldTypeDefaultDescription
namestring—A unique, descriptive name for this instrument (e.g., "Hematology-1").
driverstring—The driver to use. Determines the communication protocol and any vendor-specific handling. Common values: astm, sysmex-xn, alinity-s, exl, clinitek.
logOnlybooleanfalseWhen true, the gateway logs messages from this instrument but does not forward them to bLIS. Useful for testing a new instrument connection.
respondOnLisFailurebooleanfalseWhen 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.
descriptionstring—Optional description of the instrument.
serialNumberstring—Optional serial number for identification.
apiKeystring—API key for authenticating with bLIS on behalf of this instrument.

​
TCP input (when input.type is tcp)

FieldTypeDescription
input.portnumberTCP port the gateway listens on for this instrument. Each instrument must use a unique port.
input.ipstringOptional. Restrict connections to a specific instrument IP address.

​
MQTT input (when input.type is mqtt)

FieldTypeDescription
input.subscribeTopicstringMQTT topic for messages from the instrument to the gateway.
input.publishTopicstringMQTT topic for messages from the gateway to the instrument.

​
logging

Controls log output, file rotation, and message persistence.
FieldTypeDefaultDescription
levelstringinfoLog level: debug, info, warn, or error.
logDirstring/var/log/blis-gatewayDirectory for log files.
logRetentionDaysnumber10Number of days to keep log files before automatic cleanup.
includeRawDatabooleanfalseInclude raw hex data in logs. Enable this when troubleshooting instrument communication.

​
logging.persistence

Optional SQLite-based message storage for auditing and troubleshooting.
FieldTypeDefaultDescription
enabledbooleanfalseEnable message persistence.
dbPathstring/var/lib/blis-gateway/messages.dbPath to the SQLite database file.
retentionDaysnumber30Number of days to keep stored messages. Set to 0 to keep messages indefinitely.

​
web

Controls the built-in web management dashboard.
FieldTypeDefaultDescription
enabledbooleanfalseEnable the web dashboard.
portnumber8080Port for the web interface.
hostnamestring0.0.0.0Hostname 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.
FieldTypeDefaultDescription
namestringblis-gatewayService name.
descriptionstringBLIS GatewayService 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)