> ## Documentation Index > Fetch the complete documentation index at: https://docs.blis.app/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Configure bLIS Gateway with a YAML configuration file. 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: ```bash theme={null} blis-gateway config generate --output gateway.yaml --defaults ``` ## Minimal example A working configuration requires three sections — `input`, `lis`, and `instruments`: ```yaml theme={null} 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://: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 ```yaml theme={null} 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: ```bash theme={null} 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)