Configuration Options Reference

All configuration options are set in your pai.conf (Python/YAML/JSON) file or via environment variables prefixed with PAI_ (e.g. PAI_MQTT_ENABLE=True).

Configuration files are searched in this order: current directory, ~/.local/etc, /etc/pai, /usr/local/etc/pai. Supported formats are .conf / .py, .json, and .yaml.

Logging

LOGGING_LEVEL_CONSOLE

int

default:"logging.INFO"

Console log level. Use Python logging constants: logging.DEBUG (10), logging.INFO (20), logging.WARNING (30), logging.ERROR (40), logging.CRITICAL (50).

LOGGING_LEVEL_FILE

int

default:"logging.ERROR"

File log level. Same values as LOGGING_LEVEL_CONSOLE.

LOGGING_FILE

string | null

default:"None"

Path to the log file, e.g. /var/log/paradox.log. Set to None to disable file logging.

LOGGING_FILE_MAX_SIZE

int

default:"10"

Maximum log file size in MB before rotation. Range: 0–4294967295.

LOGGING_FILE_MAX_FILES

int

default:"2"

Number of rotated log files to keep. Range: 0–4294967295.

LOGGING_DUMP_PACKETS

bool

default:"False"

Dump raw packets to the log. Useful for low-level protocol debugging.

LOGGING_DUMP_MESSAGES

bool

default:"False"

Dump decoded messages to the log.

LOGGING_DUMP_STATUS

bool

default:"False"

Dump panel status to the log on every poll.

LOGGING_DUMP_EVENTS

bool

default:"False"

Dump full event details to the log.

DEVELOPMENT_DUMP_MEMORY

bool

default:"False"

Dump panel memory on startup. Development use only.

Connection

CONNECTION_TYPE

string

default:"Serial"

Transport type to use when connecting to the panel. Valid values: Serial, IP.

Serial connection

SERIAL_PORT

string

default:"/dev/ttyS1"

Pathname of the serial port device, e.g. /dev/ttyUSB0.

SERIAL_BAUD

int

default:"9600"

Baud rate of the serial port. Use 9600 for SP/MG panels. For EVO panels use 38400 (default EVO setting) or 57600. For EVO+ use 115200.

IP connection

IP_CONNECTION_HOST

string

default:"127.0.0.1"

Hostname or IP address of the IP150 module.

IP_CONNECTION_PORT

int

default:"10000"

TCP port of the IP150 module. Range: 1–65535.

IP_CONNECTION_PASSWORD

string | bytes | null

default:"paradox"

IP module password. The factory default is paradox.

IP_CONNECTION_SITEID

string | null

default:"None"

Paradox SITE ID for cloud-based connections. When set, PAI connects via the Paradox cloud instead of directly to the IP module.

IP_CONNECTION_EMAIL

string | null

default:"None"

Email address registered for the SITE ID connection.

IP_CONNECTION_PANEL_SERIAL

string | null

default:"None"

Panel serial number for multi-panel SITE ID setups. Set to None to use the first panel found.

IP_CONNECTION_BARE

bool

default:"False"

Connect directly to the panel without an IP150 module. Use this for serial-over-TCP tunnels.

Panel behavior

KEEP_ALIVE_INTERVAL

int

default:"10"

Interval in seconds between panel status polls.

IO_TIMEOUT

float

default:"0.5"

Timeout in seconds for individual I/O operations.

LIMITS

object

default:"{}"

Restrict which elements PAI monitors. By default all elements are monitored. Specify ranges or lists per element type.

pai.conf

LIMITS = {
    'zone': range(1, 17),      # Zones 1-16
    'partition': [1, 2],       # Partitions 1 and 2
    'user': [1, 2, 3, 4],
    'door': range(1, 32),
    'pgm': range(1, 17),
    'module': range(1, 17),
    'repeater': range(1, 9),
    'keypad': range(1, 9),
}

LABEL_ENCODING

string

default:"paradox-en"

Encoding used when decoding element labels from the panel. Use paradox-* values or any Python standard encoding.

LABEL_REFRESH_INTERVAL

int

default:"900"

Interval in seconds between full label refreshes from the panel. Default is 15 minutes (900 s). Range: 0–4294967295.

OUTPUT_PULSE_DURATION

float

default:"1"

Duration in seconds for a PGM output pulse command. Range: 0–4294967295.

SYNC_TIME

bool

default:"False"

Periodically synchronize the panel clock when drift exceeds SYNC_TIME_MIN_DRIFT.

SYNC_TIME_MIN_DRIFT

int

default:"120"

Minimum clock drift in seconds before triggering a time sync. Range: 120–4294967295.

SYNC_TIME_TIMEZONE

string

default:""

Timezone for panel time synchronization (e.g. Europe/London). Defaults to the PAI host timezone when empty.

PASSWORD

int | string | bytes | null

default:"None"

PC Password for panel communication. Set to None if the panel has no password configured. Found in Babyware under Panel Properties → PC Communication → PC Communication tab.

POWER_UPDATE_INTERVAL

int

default:"60"

Interval in seconds between reads of battery, DC, and VDC voltages. Range: 0–4294967295.

PUSH_POWER_UPDATE_WITHOUT_CHANGE

bool

default:"True"

Always push power voltage readings to interfaces even if the values have not changed.

PUSH_UPDATE_WITHOUT_CHANGE

bool

default:"False"

Always push all state updates to interfaces even if nothing has changed.

MQTT

MQTT_ENABLE

bool

default:"False"

Enable the MQTT interface.

MQTT_HOST

string

default:"127.0.0.1"

Hostname or IP address of the MQTT broker.

MQTT_PORT

int

default:"1883"

TCP port of the MQTT broker. When MQTT_TLS_CERT_PATH is set this becomes the TLS port. Range: 1–65535.

MQTT_TLS_CERT_PATH

string | null

default:"None"

Path to a CA certificate file for TLS connections, e.g. /etc/pai/certs/ca.pem. Set to None for plain TCP.

MQTT_KEEPALIVE

int

default:"60"

MQTT keepalive interval in seconds. Range: 1–3600.

MQTT_USERNAME

string | null

default:"None"

MQTT broker username. Set to None for unauthenticated connections.

MQTT_PASSWORD

string | null

default:"None"

MQTT broker password.

MQTT_RETAIN

bool

default:"True"

Publish all messages with the MQTT retain flag.

MQTT_QOS

int

default:"0"

MQTT QoS level for published messages. 0 = fire and forget, 1 = at least once, 2 = exactly once. Range: 0–2.

MQTT_PROTOCOL

string

default:"3.1.1"

MQTT protocol version. Valid values: 3.1, 3.1.1, 5.

MQTT_TRANSPORT

string

default:"tcp"

MQTT transport layer. Valid values: tcp, websockets.

MQTT_BIND_ADDRESS

string

default:""

Local network address to bind the MQTT client to. Empty string lets Paho choose automatically.

MQTT_BIND_PORT

int

default:"0"

Local port to bind the MQTT client to. 0 lets Paho choose automatically.

MQTT_REPUBLISH_INTERVAL

int

default:"43200"

Interval in seconds for republishing all state data to MQTT (default 12 hours). Range: 60–4294967295.

MQTT_PUBLISH_DEFINITIONS

bool

default:"False"

Publish element definitions (partition/zone/user metadata) to MQTT. Not required in most setups.

MQTT_USE_NUMERIC_STATES

bool

default:"False"

Publish 0 and 1 instead of False and True for boolean state values.

MQTT_TOGGLE_CODES

object

default:"{}"

Map of MQTT toggle codes for controlling outputs.

MQTT_DASH_PUBLISH

bool

default:"False"

Publish data in MQTT Dash format.

MQTT_DASH_TOPIC

string

default:"metrics/exchange/pai"

MQTT topic for MQTT Dash data.

MQTT_DASH_TEMPLATE

string

default:"/etc/pai/mqtt_dash.txt"

Path to the MQTT Dash template file.

MQTT_CHALLENGE_SECRET

string | null

default:"None"

Shared secret for MQTT command authorization challenge. When set, commands must include a valid HMAC challenge response.

MQTT_CHALLENGE_TOPIC

string

default:"challenge"

Sub-topic used for the MQTT command authorization challenge exchange.

MQTT_CHALLENGE_ROUNDS

int

default:"1000"

Number of HMAC rounds used in the challenge computation.

MQTT_PUBLISH_COMMAND_STATUS

bool

default:"False"

Publish the result of executed commands to MQTT_COMMAND_STATUS_TOPIC.

MQTT_COMMAND_STATUS_TOPIC

string

default:"command_status"

Sub-topic for command execution status messages.

MQTT topics

MQTT_BASE_TOPIC

string

default:"paradox"

Root prefix for all PAI MQTT topics.

MQTT_ZONE_TOPIC

string

default:"zones"

Sub-topic segment for zone state messages.

MQTT_PARTITION_TOPIC

string

default:"partitions"

Sub-topic segment for partition state messages.

MQTT_BUS_TOPIC

string

default:"buses"

Sub-topic segment for bus state messages.

MQTT_MODULE_TOPIC

string

default:"bus-module"

Sub-topic segment for bus module state messages.

MQTT_SYSTEM_TOPIC

string

default:"system"

Sub-topic segment for panel/system state messages.

MQTT_REPEATER_TOPIC

string

default:"repeaters"

Sub-topic segment for repeater state messages.

MQTT_USER_TOPIC

string

default:"users"

Sub-topic segment for user state messages.

MQTT_EVENTS_TOPIC

string

default:"events"

Sub-topic segment for event messages.

MQTT_CONTROL_TOPIC

string

default:"control"

Sub-topic segment for inbound control commands.

MQTT_DEFINITION_TOPIC

string

default:"definitions"

Sub-topic segment for element definition messages.

MQTT_OUTPUT_TOPIC

string

default:"outputs"

Sub-topic segment for PGM output state messages.

MQTT_DOOR_TOPIC

string

default:"doors"

Sub-topic segment for door state messages.

MQTT_KEYPAD_TOPIC

string

default:"keypads"

Sub-topic segment for keypad state messages.

MQTT_STATES_TOPIC

string

default:"states"

Sub-topic segment appended after each element name for state properties.

MQTT_RAW_TOPIC

string

default:"raw"

Sub-topic for raw event JSON messages.

MQTT_NOTIFICATIONS_TOPIC

string

default:"notifications"

Sub-topic for notification messages.

MQTT_SEND_PANIC_TOPIC

string

default:"panic"

Sub-topic for triggering a panic from MQTT.

MQTT_PUBLISH_RAW_EVENTS

bool

default:"True"

Publish raw event JSON to {base}/{events}/{raw}.

MQTT_INTERFACE_TOPIC

string

default:"interface"

Sub-topic for PAI interface status messages (PAI run state, availability).

MQTT_HOMEASSISTANT_CONTROL_TOPIC

string

default:"hass_control"

Sub-topic for Home Assistant specific control commands.

MQTT_HOMEASSISTANT_DISCOVERY_PREFIX

string

default:"homeassistant"

Root topic prefix used for Home Assistant MQTT discovery messages.

MQTT Home Assistant auto discovery

MQTT_HOMEASSISTANT_AUTODISCOVERY_ENABLE

bool

default:"False"

Publish Home Assistant MQTT discovery payloads so that partitions and zones appear automatically in HA.

MQTT_HOMEASSISTANT_CODE

string | null

default:"None"

Alarm code to embed in Home Assistant discovery payloads (used by the HA alarm panel card).

MQTT_HOMEASSISTANT_ENTITY_PREFIX

string

default:""

Prefix string for all Home Assistant entity names. Supports {serial_number} and {model} placeholders, e.g. Paradox {serial_number} .

MQTT_PREFIX_DEVICE_NAME

bool

default:"False"

Prefix entity names with the device ID (Paradox 12345678).

HOMEASSISTANT_PUBLISH_PARTITION_PROPERTIES

string[]

default:"['target_state', 'current_state']"

List of partition property names to publish for Home Assistant discovery.

HOMEASSISTANT_PUBLISH_ZONE_PROPERTIES

string[]

default:"['open', 'tamper']"

List of zone property names to publish for Home Assistant discovery.

Home Assistant notifications

Requires Home Assistant Supervisor (HASS.io) or a Long-Lived Access Token.

HOMEASSISTANT_NOTIFICATIONS_ENABLE

bool

default:"False"

Enable pushing PAI events as Home Assistant notifications.

HOMEASSISTANT_NOTIFICATIONS_API_URL

string

Home Assistant REST API endpoint for triggering notification services.

HOMEASSISTANT_NOTIFICATIONS_API_TOKEN

string

default:""

Long-Lived Access Token for authenticating with the HA API when not using Supervisor.

HOMEASSISTANT_NOTIFICATIONS_LOVELACE_URI

string

default:""

URI to open in the HA app when the notification is tapped.

HOMEASSISTANT_NOTIFICATIONS_NOTIFIER_NAME

string

default:"notify"

Name of the HA notifier service to call.

HOMEASSISTANT_NOTIFICATIONS_MIN_EVENT_LEVEL

string

default:"INFO"

Minimum event severity to send as a notification. Valid values: DEBUG, INFO, WARN, ERROR, CRITICAL.

HOMEASSISTANT_NOTIFICATIONS_EVENT_FILTERS

string[]

Tag-based event filters. Each entry is a comma-separated list of tags to match (prefix with - to exclude). Used when HOMEASSISTANT_NOTIFICATIONS_ALLOW_EVENTS is not set.

HOMEASSISTANT_NOTIFICATIONS_ALLOW_EVENTS

string[]

default:"[]"

Whitelist of regexp patterns matching type,label,property=value event strings. When set, overrides EVENT_FILTERS.

HOMEASSISTANT_NOTIFICATIONS_IGNORE_EVENTS

string[]

default:"[]"

Regexp patterns to exclude from events that matched ALLOW_EVENTS.

Pushbullet

PUSHBULLET_ENABLE

bool

default:"False"

Enable the Pushbullet interface.

PUSHBULLET_KEY

string

default:""

Pushbullet API authentication key.

PUSHBULLET_DEVICE

string

default:"pai"

Pushbullet device name to send notifications from.

PUSHBULLET_CONTACTS

string[]

default:"[]"

Pushbullet user identifiers allowed to receive notifications and send commands.

PUSHBULLET_MIN_EVENT_LEVEL

string

default:"INFO"

Minimum event severity for Pushbullet notifications. Valid values: DEBUG, INFO, WARN, ERROR, CRITICAL.

PUSHBULLET_EVENT_FILTERS

string[]

Tag-based event filters for Pushbullet.

PUSHBULLET_ALLOW_EVENTS

string[]

default:"[]"

Regexp whitelist for Pushbullet events.

PUSHBULLET_IGNORE_EVENTS

string[]

default:"[]"

Regexp exclusion list for Pushbullet events.

Pushover

PUSHOVER_ENABLE

bool

default:"False"

Enable the Pushover interface.

PUSHOVER_KEY

string

default:""

Pushover application token.

PUSHOVER_BROADCAST_KEYS

object[]

default:"[]"

List of Pushover user or group key objects to receive notifications. Each object has a user_key and devices field (* or a comma-separated list of device names).

pai.conf

PUSHOVER_BROADCAST_KEYS = [
    {'user_key': '<user_key>', 'devices': '*'}
]

PUSHOVER_MIN_EVENT_LEVEL

string

default:"INFO"

Minimum event severity for Pushover notifications. Valid values: DEBUG, INFO, WARN, ERROR, CRITICAL.

PUSHOVER_EVENT_FILTERS

string[]

Tag-based event filters for Pushover.

PUSHOVER_ALLOW_EVENTS

string[]

default:"[]"

Regexp whitelist for Pushover events.

PUSHOVER_IGNORE_EVENTS

string[]

default:"[]"

Regexp exclusion list for Pushover events.

Signal

SIGNAL_ENABLE

bool

default:"False"

Enable the Signal messenger interface.

SIGNAL_CONTACTS

string[]

default:"[]"

Signal contact phone numbers allowed to control the panel and receive event notifications.

SIGNAL_MIN_EVENT_LEVEL

string

default:"INFO"

Minimum event severity for Signal notifications. Valid values: DEBUG, INFO, WARN, ERROR, CRITICAL.

SIGNAL_EVENT_FILTERS

string[]

Tag-based event filters for Signal.

SIGNAL_ALLOW_EVENTS

string[]

default:"[]"

Regexp whitelist for Signal events.

SIGNAL_IGNORE_EVENTS

string[]

default:"[]"

Regexp exclusion list for Signal events.

GSM

GSM_ENABLE

bool

default:"False"

Enable the GSM/SMS interface.

GSM_MODEM_PORT

string

default:""

Serial port path for the GSM modem, e.g. /dev/ttyUSB0.

GSM_MODEM_BAUDRATE

int

default:"115200"

Baud rate for the GSM modem serial connection. Range: 9600–115200.

GSM_CONTACTS

string[]

default:"[]"

Phone numbers allowed to receive SMS notifications and send panel control commands.

GSM_MIN_EVENT_LEVEL

string

default:"CRITICAL"

Minimum event severity for GSM/SMS notifications. Valid values: DEBUG, INFO, WARN, ERROR, CRITICAL.

GSM_EVENT_FILTERS

string[]

default:"['live,zone,alarm,trigger']"

Tag-based event filters for GSM.

GSM_ALLOW_EVENTS

string[]

default:"[]"

Regexp whitelist for GSM events.

GSM_IGNORE_EVENTS

string[]

default:"[]"

Regexp exclusion list for GSM events.

IP interface

IP_INTERFACE_ENABLE

bool

default:"False"

Enable the IP socket interface that emulates an IP150 module.

IP_INTERFACE_BIND_ADDRESS

string

default:"0.0.0.0"

Local address for the IP interface to listen on.

IP_INTERFACE_BIND_PORT

int

default:"10000"

TCP port for the IP interface. Range: 1–65535.

IP_INTERFACE_PASSWORD

string | bytes | null

default:"paradox"

Password for authenticating clients connecting to the IP interface.

Interfaces

COMMAND_ALIAS

object

Aliases for text-based interface commands (Signal, Pushbullet, GSM). Maps short alias strings to full PAI commands.See Command Alias Reference for full details and available commands.

MQTT_COMMAND_ALIAS

object

Aliases for MQTT control topic commands. Maps external command names (e.g. Home Assistant / Homebridge state strings) to PAI partition commands.See Command Alias Reference for full details.

Configuration Reference

CLI Commands

Logging

Connection

Serial connection

IP connection

Panel behavior

MQTT

MQTT topics

MQTT Home Assistant auto discovery

Home Assistant notifications

Pushbullet

Pushover

Signal

GSM

IP interface

Interfaces

Build docs developers (and LLMs) love

Configuration Reference

CLI Commands

​Logging

​Connection

​Serial connection

​IP connection

​Panel behavior

​MQTT

​MQTT topics

​MQTT Home Assistant auto discovery

​Home Assistant notifications

​Pushbullet

​Pushover

​Signal

​GSM

​IP interface

​Interfaces

Build docs developers (and LLMs) love

Logging

Connection

Serial connection

IP connection

Panel behavior

MQTT

MQTT topics

MQTT Home Assistant auto discovery

Home Assistant notifications

Pushbullet

Pushover

Signal

GSM

IP interface

Interfaces