API Reference

MQTT Connector

class pynhc2.MQTTConnector(broker, jwt, ca_cert, username='hobby')[source]

Bases: object

MQTT Connector for Niko Home Control 2.

This class manages MQTT connections to the Niko Home Control 2 broker, handling authentication, TLS encryption, and message routing to registered handlers.

broker

MQTT broker hostname or IP address.

Type:: str

jwt

JSON Web Token for authentication.

Type:: str

ca_cert

Path to CA certificate file for TLS.

Type:: str

username

MQTT username (default: “hobby”).

Type:: str

port

MQTT broker port (default: 8884).

Type:: int

client: Paho MQTT client instance.

last_msg

Last received MQTT message.

Type:: dict

handlers

List of registered message handlers.

Type:: list

__init__(broker, jwt, ca_cert, username='hobby')[source]

Initialize MQTT connector.

Parameters:

broker (str) – MQTT broker hostname or IP address.
jwt (str) – JSON Web Token for authentication.
ca_cert (str) – Path to CA certificate file for TLS verification.
username (str, optional) – MQTT username. Defaults to “hobby”.

Raises:

ValueError – If broker, jwt, or ca_cert is missing or empty.

connect()[source]

Connect to MQTT broker and start message loop.

Establishes connection to the broker and starts the network loop in a background thread.

Returns:

The connected MQTT client instance.

Return type:

mqtt.Client

Raises:

ConnectionError – If connection to the broker fails.
OSError – If network connection is unavailable.

get_devices(device_type=None, location_uuid=None, location_name=None)[source]

Get devices from Niko Home Control system.

Queries the broker for all devices, optionally filtered by type or location.

Parameters:

device_type (str, optional) – Filter by device type. Defaults to None.
location_uuid (str, optional) – Filter by location UUID. Defaults to None.
location_name (str, optional) – Filter by location name. Defaults to None.

Returns:

List of location dictionaries, each containing device information.

Return type:

list

get_locations()[source]

Get all locations from Niko Home Control system.

Queries the broker for all configured locations/rooms.

Returns:: List of location dictionaries containing location information.
Return type:: list

register_handler(handler)[source]

Register a message handler.

Adds a handler that will receive MQTT messages matching its input devices.

Parameters:: handler – Handler object with handle_message method and input_uuids attribute.
Raises:: TypeError – If handler does not have required attributes or methods.

Device Control

class pynhc2.Device(mqttconnector=None, device_uuid=None)[source]

Bases: object

Base class for Niko Home Control devices.

Provides basic device control functionality for any Niko Home Control device.

conn

MQTT connector instance.

Type:: MQTTConnector

device_uuid

Unique identifier for the device.

Type:: str

topic

MQTT topic for device commands.

Type:: str

method

Control method name.

Type:: str

current_status

Current device status.

Type:: str

__init__(mqttconnector=None, device_uuid=None)[source]

Initialize a Device instance.

Parameters:

mqttconnector (MQTTConnector, optional) – MQTT connector instance.
device_uuid (str, optional) – Unique device identifier.

Raises:

ValueError – If mqttconnector or device_uuid is not provided.

command(properties)[source]

Send a command to the device.

Sends control properties to the device via MQTT. Properties are lowerkey versions of the Niko camelcase properties.

Parameters:

properties (list) – List of property dictionaries to send to the device.

Raises:

ConnectionError – If MQTT connection is lost.
ValueError – If properties format is invalid.

class pynhc2.Lamp(mqttconnector=None, device_uuid=None)[source]

Bases: object

Lamp device controller for Niko Home Control.

Provides control methods for lamp devices including on/off switching and brightness control.

conn

MQTT connector instance.

Type:: MQTTConnector

device_uuid

Unique identifier for the lamp.

Type:: str

topic

MQTT topic for device commands.

Type:: str

method

Control method name.

Type:: str

status

Current lamp status (“On”, “Off”, or None).

Type:: str

brightness

Current brightness level (0-100).

Type:: int

__init__(mqttconnector=None, device_uuid=None)[source]

Initialize a Lamp instance.

Parameters:

mqttconnector (MQTTConnector, optional) – MQTT connector instance.
device_uuid (str, optional) – Unique lamp identifier.

Raises:

ValueError – If mqttconnector or device_uuid is not provided.

command(properties)[source]

Send a command to the lamp.

Sends control properties to the lamp via MQTT.

Parameters:

properties (list) – List of property dictionaries to send to the lamp. Each property dict should have CamelCase keys (e.g., {“Status”: “On”}).

Raises:

ConnectionError – If MQTT connection is lost.
ValueError – If properties format is invalid.

set_brightness(brightness='50')[source]

Set lamp brightness level.

Turns the lamp on (if off) and sets the brightness to the specified level.

Parameters:

brightness (str, optional) – Brightness level (0-100). Defaults to “50”.

Raises:

ValueError – If brightness is not between 0 and 100.
ConnectionError – If MQTT connection is lost.

Note

Currently always sends ‘On’ status with brightness. TODO: Send brightness only if lamp is already on.

switch()[source]

Toggle lamp between on and off states.

Switches the lamp to the opposite of its current state.

Raises:: ValueError – If lamp status has not been set yet.

switch_off()[source]

Turn the lamp off.

Sends an ‘Off’ command to the lamp and updates the status attribute.

Raises:: ConnectionError – If MQTT connection is lost.

switch_on()[source]

Turn the lamp on.

Sends an ‘On’ command to the lamp and updates the status attribute.

Raises:: ConnectionError – If MQTT connection is lost.

Message Handlers

class pynhc2.MessageHandler(mqttconnector, input_device, output_actions)[source]

Bases: object

Automation handler that triggers actions based on one device input.

Monitors an input devices and triggers one or more output actions when all input devices have sent messages within a specified time window. This enables NHC-devices to control non-NHC devices e.g. Shelly using pyShelly.

conn

MQTT connector instance.

Type:: MQTTConnector

input_device

Device object to monitor.

Type:: object

input_uuid

Device UUID extracted from input_device.

Type:: str

output_actions

List of callable actions to execute.

Type:: list

__init__(mqttconnector, input_device, output_actions)[source]

Initialize a MultiMessageHandler.

Parameters:

mqttconnector (MQTTConnector) – MQTT connector instance.
input_device (object) – Device object to monitor.
output_actions (list) – List of callable actions (methods or lambdas) to execute.

Raises:

ValueError – If input_device or output_actions is empty.
TypeError – If output_actions contains non-callable items.
AttributeError – If input device doesn’t have a device_uuid attribute.

handle_message()[source]

Process incoming MQTT messages for automation logic. Execution of all configured output actions.

The message is send to this object through the MQTT connector by checking the input_uuid.

class pynhc2.MultiMessageHandler(mqttconnector, input_devices, output_actions_on, output_actions_off, seconds_window=0.5)[source]

Bases: object

Automation handler that triggers actions based on multiple device inputs.

Monitors multiple input devices and triggers output actions when all input devices have sent the required number of messages within a specified time window. Duplicate entries in input_devices are supported and require the same device to send that many messages within the window (e.g., listing a device twice requires two presses in rapid succession). This enables complex automation scenarios like “turn on scene when two switches are pressed” or “trigger on double-press”.

The handler maintains a toggle state (‘off’ initially). Each time all input devices are triggered within the time window, the state toggles between ‘on’ and ‘off’, executing the corresponding set of output actions.

conn

MQTT connector instance.

Type:: MQTTConnector

input_devices

List of device objects to monitor.

Type:: list

input_uuids

List of device UUIDs extracted from input_devices.

Type:: list

seconds_window

Time window in seconds for input matching.

Type:: float

output_actions_on

List of callable actions to execute when state becomes ‘on’.

Type:: list

output_actions_off

List of callable actions to execute when state becomes ‘off’.

Type:: list

state

Current toggle state, either ‘on’ or ‘off’.

Type:: str

received

Buffer of received messages within the time window.

Type:: list

__init__(mqttconnector, input_devices, output_actions_on, output_actions_off, seconds_window=0.5)[source]

Initialize a MultiMessageHandler.

Parameters:

mqttconnector (MQTTConnector) – MQTT connector instance.
input_devices (list) – List of device objects (e.g., Lamp instances) to monitor. Duplicates are allowed — listing the same device N times requires it to send N messages within the time window before the handler triggers.
output_actions_on (list) – List of callable actions to execute when state becomes ‘on’.
output_actions_off (list) – List of callable actions to execute when state becomes ‘off’.
seconds_window (float, optional) – Time window in seconds for matching inputs. Defaults to 0.5.

Raises:

ValueError – If input_devices or either output_actions list is empty.
TypeError – If output_actions contain non-callable items.
AttributeError – If input devices don’t have device_uuid attribute.

handle_message(message)[source]

Process incoming MQTT message for automation logic.

Checks if all input devices have sent the required number of messages within the time window. Supports duplicate entries in input_devices, allowing the same device to be listed multiple times (e.g., to require two presses in rapid succession). If so, toggles the state between ‘on’ and ‘off’ and executes the corresponding set of output actions.

Parameters:: message (dict) – MQTT message dictionary containing: - device_uuid (str): UUID of the device that sent the message. - timestamp (float): Message timestamp in seconds. - Other message metadata.

File Reader

class pynhc2.NHC2FileReader(nhc2_file_path=None)[source]

Bases: object

Reader for Niko Home Control 2 configuration files.

Extracts and reads device and location information from .nhc2 configuration files exported from the Niko Home Control app.

nhc2_file_path

Path to the .nhc2 configuration file.

Type:: str

db_name

Path to the extracted SQLite database file.

Type:: str

__init__(nhc2_file_path=None)[source]

Initialize NHC2FileReader.

Parameters:

nhc2_file_path (str, optional) – Path to .nhc2 configuration file.

Raises:

ValueError – If nhc2_file_path is not provided.
FileNotFoundError – If the configuration file does not exist.

get_device_types()[source]

Get all unique device types from the configuration file.

Queries the SQLite database for all distinct device type codes.

Returns:

List of device type code strings (e.g., [‘Lamp’, ‘DimmableLamp’]).

Return type:

list

Raises:

sqlite3.DatabaseError – If the database is corrupted or invalid.
sqlite3.OperationalError – If required tables do not exist.

get_devices(device_type=None, location_uuid=None, location_name=None)[source]

Get devices from the configuration file.

Queries the SQLite database for devices, optionally filtered by device type or location.

Parameters:

device_type (str, optional) – Filter by device type code. Defaults to None.
location_uuid (str, optional) – Filter by location UUID. Defaults to None.
location_name (str, optional) – Filter by location name. Defaults to None.

Returns:

List of device dictionaries, each containing:

device_uuid (str): Unique identifier for the device.
device_name (str): Human-readable name of the device.
device_type (str): Device type code.
location_uuid (str): UUID of the location containing the device.
location_name (str): Name of the location containing the device.

Return type:

list

Raises:

sqlite3.DatabaseError – If the database is corrupted or invalid.
sqlite3.OperationalError – If required tables do not exist.

get_locations()[source]

Get all locations from the configuration file.

Queries the SQLite database for all configured locations/rooms.

Returns:

List of location dictionaries, each containing:

location_uuid (str): Unique identifier for the location.
location_name (str): Human-readable name of the location.

Return type:

list

Raises:

sqlite3.DatabaseError – If the database is corrupted or invalid.
sqlite3.OperationalError – If the Location table does not exist.