Skip to main content

⚙️ 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 number
  • manufacturer: "Digital Alchemy"
  • name: (your declared application name)

📝 Metadata Table

FieldTypeDescription
configuration_urlstringA URL on which the device or service can be configured, linking to paths inside the Home Assistant UI
manufacturerstringThe manufacturer of the device, will be overridden if manufacturer is set.
modelstringThe model of the device, will be overridden if model is set.
namestringDefault name of this device, will be overridden if name is set.
hw_versionstringThe hardware version of the device.
serial_numberstringThe serial number of the device. Unlike a serial number in the identifiers set, this does not need to be unique.
suggested_areastringThe suggested name for the area where the device is located. Use readable name, not area id ("Living Room" not "living_room")
sw_versionstringThe firmware version of the device.

🔧 Configuration Table

VariableTypeDefault ValueDescription
EMIT_HEARTBEATbooleantrueEmit a heartbeat pulse so the extension knows the service is alive
EVENT_NAMESPACEstring"digital_alchemy"You almost definitely do not want to change this. Must be matched on the python integration side.
HEARTBEAT_INTERVALnumber5Seconds between heartbeats
METADATA_HOSTstring(none)Host name to announce as
METADATA_TITLEstring(none)Title for the integration provided by this app. Defaults to app name
METADATA_UNIQUE_IDstring(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_BONJOURbooleantruePublish 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"
}