⚙️ Configuration
This documentation provides a comprehensive overview of all configuration options available in the Synapse library. Configuration variables can be set through environment variables, CLI switches, or configuration files in ini
, yaml
, and json
formats.
🗃️ Device Metadata
By default, the app will provide these values for the device metadata:
sw_version
: synapse library version numbermanufacturer
: "Digital Alchemy"name
: (your declared application name)
📝 Metadata Table
Field | Type | Description |
---|---|---|
configuration_url | string | A URL on which the device or service can be configured, linking to paths inside the Home Assistant UI |
manufacturer | string | The manufacturer of the device, will be overridden if manufacturer is set. |
model | string | The model of the device, will be overridden if model is set. |
name | string | Default name of this device, will be overridden if name is set. |
hw_version | string | The hardware version of the device. |
serial_number | string | The serial number of the device. Unlike a serial number in the identifiers set, this does not need to be unique. |
suggested_area | string | The suggested name for the area where the device is located. Use readable name, not area id ("Living Room" not "living_room") |
sw_version | string | The firmware version of the device. |
🔧 Configuration Table
Variable | Type | Default Value | Description |
---|---|---|---|
EMIT_HEARTBEAT | boolean | true | Emit a heartbeat pulse so the extension knows the service is alive |
EVENT_NAMESPACE | string | "digital_alchemy" | You almost definitely do not want to change this. Must be matched on the python integration side. |
HEARTBEAT_INTERVAL | number | 5 | Seconds between heartbeats |
METADATA_HOST | string | (none) | Host name to announce as |
METADATA_TITLE | string | (none) | Title for the integration provided by this app. Defaults to app name |
METADATA_UNIQUE_ID | string | (none) | A string to uniquely identify this application. Should be unique within home assistant, such as a uuid. Default value calculated from hostname + username + app_name |
PUBLISH_BONJOUR | boolean | true | Publish mDNS discovery topics to allow zeroconf discovery |
💡 Example Usage
🌍 Environment
Set up as an environment variable for your shell, then run the script
export EMIT_HEARTBEAT=false
tsx src/main.ts
Set up as an environment variable for just the single run
EVENT_NAMESPACE="magic_world" tsx src/main.ts
Use a
.env
file to set multiple variables
# .env file
EMIT_HEARTBEAT=false
EVENT_NAMESPACE="quantum_realm"
HEARTBEAT_INTERVAL=20
# --env-file provided by runtime will load extra vars
tsx --env-file .env src/main.ts
🎛️ CLI Switch
Provide your config as a switch
tsx src/main.ts --heartbeat_interval 10
📁 File
If your file does not have an extension, Configuration will do auto
📘 ini
.my_app_name
,~/.config/my_app_name
[synapse]
EMIT_HEARTBEAT=false
EVENT_NAMESPACE=quantum_realm
HEARTBEAT_INTERVAL=20
METADATA_HOST=server.local
METADATA_TITLE=Super_App
METADATA_UNIQUE_ID=unique-1234
PUBLISH_BONJOUR=false
📄 yaml
.my_app_name.yaml
synapse:
EMIT_HEARTBEAT: false
EVENT_NAMESPACE: "quantum_realm"
HEARTBEAT_INTERVAL: 20
METADATA_HOST: "server.local"
METADATA_TITLE: "Super App"
METADATA_UNIQUE_ID: "unique-1234"
PUBLISH_BONJOUR: false
🗃️ json
.my_app_name.json
{
"synapse": {
"EMIT_HEARTBEAT": false,
"EVENT_NAMESPACE": "quantum_realm",
"HEARTBEAT_INTERVAL": 20,
"METADATA_HOST": "server.local",
"METADATA_TITLE": "Super App",
"METADATA_UNIQUE_ID": "unique-1234",
"PUBLISH_BONJOUR": false
}
}
🔧 Example Metadata
const deviceMetadata: HassDeviceMetadata = {
configuration_url: "homeassistant://integrations/synapse",
manufacturer: "Magic Widgets Co.",
model: "Alpha 3000",
name: "Synapse Device",
hw_version: "1.0",
serial_number: "SN1234567890",
suggested_area: "Control Center",
sw_version: "2.1.4"
}