settings.js.example

// =============================================================================
// cgateweb Configuration - Starter Settings
// =============================================================================
// cgateweb already ships a working settings.js pointing at 127.0.0.1, so it
// runs out of the box - edit that file to point at your own setup. This
// template is here for starting a config from scratch: its connection values
// are deliberate placeholders, so an unedited copy fails validation loudly
// rather than retrying a stranger's address forever.
//
// This is a STARTER config: the handful of settings a standalone install
// actually needs to get going, with the optional features commented out.
// For the complete list of settings and their defaults, see docs/SETTINGS.md.
//
// Anything not set here falls back to the defaults in src/defaultSettings.js.
// cgateweb warns on start about any setting name it does not recognise, so a
// typo is caught rather than silently ignored.

// =============================================================================
// C-Gate Connection (Required)
// =============================================================================

// C-Gate server IP address - the machine running Clipsal's C-Gate software.
// This MUST be changed; cgateweb refuses to start while it is the placeholder.
exports.cbusip = 'your-cgate-ip';

// C-Gate project name, exactly as it appears in C-Bus Toolkit (usually
// uppercase). Letters, digits and underscores only.
exports.cbusname = 'YOUR_PROJECT';

// C-Gate command port - cgateweb sends commands here.
exports.cbuscommandport = 20023;

// C-Gate event port - cgateweb reads C-Gate's status change stream here.
// This is 20025, NOT 20023 or 20024. If you point it at the wrong port your
// lights will still respond to commands, but no state will ever come back.
exports.cbuseventport = 20025;

// C-Gate access control credentials (only if your C-Gate requires them).
// exports.cgateusername = 'cgate_user';
// exports.cgatepassword = 'cgate_password';

// =============================================================================
// MQTT Broker (Required)
// =============================================================================

// MQTT broker address - 'hostname:port'.
exports.mqtt = 'localhost:1883';

// MQTT authentication (uncomment if your broker requires it).
// exports.mqttusername = 'homeassistant';
// exports.mqttpassword = 'your_mqtt_password';

// Set the MQTT retain flag on values published from C-Gate, so Home Assistant
// sees the last known state after a restart instead of 'unknown'.
exports.retainreads = true;

// =============================================================================
// Logging
// =============================================================================

// One of: 'error', 'warn', 'info', 'debug', 'trace'. Use 'debug' to see every
// MQTT and C-Gate message while troubleshooting.
// The LOG_LEVEL environment variable overrides this for a single run, e.g.
//   LOG_LEVEL=debug npm start
exports.log_level = 'info';

// =============================================================================
// Message Throttling
// =============================================================================

// Minimum interval between outbound messages, in milliseconds. Stops a burst
// of commands from flooding C-Gate. 200ms = 5 messages per second.
exports.messageinterval = 200;

// =============================================================================
// Startup and Periodic State Polling
// =============================================================================

// Network and application to query for current device levels, as
// 'network/application'. 254/56 is lighting on the default network.
exports.getallnetapp = '254/56';

// Query all device levels when the bridge starts, so Home Assistant comes up
// in sync with the actual state of the bus.
exports.getallonstart = true;

// How often to repeat that query, in seconds. Catches anything missed while
// the bridge or broker was down. Null or 0 disables periodic polling.
exports.getallperiod = 3600;

// =============================================================================
// Home Assistant MQTT Discovery
// =============================================================================

// Publish discovery messages so Home Assistant creates the entities for you.
exports.ha_discovery_enabled = true;

// Discovery topic prefix. A standard Home Assistant install uses
// 'homeassistant'.
exports.ha_discovery_prefix = 'homeassistant';

// C-Bus networks to scan during discovery. Usually just [254].
exports.ha_discovery_networks = [254];

// --- Application to entity type mapping ---
//
// Lighting (application 56) is always discovered as dimmable 'light' entities
// and is not configurable. The settings below map your other applications onto
// other entity types; each one is off until you set it.

// Groups on this application become 'cover' entities (blinds, shutters,
// garage doors). 203 is the usual choice, but C-Bus calls 203 Enable Control -
// a general purpose application. Only set this if your covers really are on it.
// exports.ha_discovery_cover_app_id = '203';

// Groups on this application become on/off 'switch' entities.
// exports.ha_discovery_switch_app_id = '203';

// Groups on this application become 'switch' entities driving relay channels.
// exports.ha_discovery_relay_app_id = '1';

// Groups on this application become motion 'binary_sensor' entities.
// exports.ha_discovery_pir_app_id = '36';

// Groups on this application become keypad/scene 'event' + 'button' entities.
// Typically 202.
// exports.ha_discovery_trigger_app_id = '202';

// =============================================================================
// C-Bus Labels (Optional)
// =============================================================================

// Path to the JSON file holding your imported group labels. Set this to give
// discovered entities their Toolkit names, and to let the web UI save edits.
// exports.cbus_label_file = '/var/lib/cgateweb/cbus-labels.json';

// =============================================================================
// Web UI and API (Optional)
// =============================================================================

// Status page and label-editing API.
exports.web_port = 8080;

// Bind to loopback only. Change this only if you understand the consequences -
// the API can modify your labels.
exports.web_bind_host = '127.0.0.1';

// API key required for write requests (POST/PUT/PATCH) when the web UI is
// reached directly.
// exports.web_api_key = 'replace_with_a_long_random_key';

// WARNING: enabling this lets ANYONE who can reach web_port modify your labels
// without any authentication. Leave it off unless the port is fully isolated.
// exports.web_allow_unauthenticated_mutations = true;

// =============================================================================
// Specialised C-Bus Applications (Optional)
// =============================================================================

// --- Air Conditioning (native, application 172) ---
// Read thermostat temperature, mode, setpoint and fan state.
// exports.cbus_aircon_app_id = '172';

// WARNING: enabling this lets Home Assistant WRITE to your live heating and
// cooling - mode and setpoint changes reach the plant. Requires
// cbus_aircon_app_id above.
// exports.cbus_aircon_control_enabled = true;

// --- Security (application 208) ---
// Alarm zone sensors are read-only and ON by default. Set this to '0' to turn
// zone discovery off entirely.
// exports.cbus_security_app_id = '208';

// WARNING: enabling this lets anything that can publish to the panel command
// topic ARM your alarm - the arm command carries no PIN on the C-Bus network.
// exports.cbus_security_control_enabled = true;

// WARNING: enabling this allows DISARM as well. C-Bus has no disarm command,
// so the PIN is typed at the panel via keypad emulation and therefore crosses
// your MQTT broker on every disarm. Only on a broker you trust, ideally with
// TLS. Requires cbus_security_control_enabled above.
// exports.cbus_security_disarm_enabled = true;

// WARNING: enabling this allows arming PAST AN OPEN ZONE (the panel's '#'
// key). The alarm then reports armed while that door or window is not covered.
// Requires cbus_security_control_enabled above.
// exports.cbus_security_bypass_enabled = true;

// --- Measurement (application 228) ---
// Decode analogue sensor readings (temperature, power, light level) into
// 'sensor' entities. Also allows injecting readings onto the bus.
// exports.cbus_measurement_app_id = '228';

// --- Enable Control extra verbs (typically application 203) ---
// MQTT-only SET/LABEL/REMOVE (ON/OFF/RAMP already work without this).
// REMOVE deletes the C-Gate group object; the MQTT payload must be ON.
// exports.cbus_enable_control_app_id = '203';

// =============================================================================
// Reference
// =============================================================================

/*
Common C-Bus application IDs:
- 1    = Relay (on/off, no dimming)
- 36   = Trigger / PIR sensors
- 56   = Lighting (dimmable, most common)
- 172  = Air Conditioning
- 202  = Trigger control (keypads, scenes)
- 203  = Enable Control (often used for motors and blinds)
- 208  = Security
- 228  = Measurement

Common C-Bus network IDs:
- 254  = Default network (most installations)
- 255  = Secondary network (larger installations)

Addresses are network/application/group, e.g. 254/56/4 is group 4 of the
lighting application on network 254.

MQTT topics for that group:
- cbus/write/254/56/4/switch -> control it (payload ON or OFF)
- cbus/write/254/56/4/ramp   -> dim it (payload 0-100, optionally with a
                                ramp time, e.g. "75,4s")
- cbus/read/254/56/4/state   -> its state (ON or OFF)
- cbus/read/254/56/4/level   -> its brightness (0-100)
*/