Usage examples

Simple switch

A simple single switch example. It prints the state of the switch on change.

Import modules

First import all the necessary modules:

from nirahmq import *
from nirahmq.components import Switch

Declare the switch callback

The switch command callback is called each time a payload is sent from Home Assistant to the switch. The expected payloads are Switch.payload_on for activating and Switch.payload_off for deactivating the switch.

def callback(switch: Switch, payload: str) -> None:
    match payload:
        case switch.payload_on:
            switch.set_state(True)
            print("TURNING ON")
        case switch.payload_off:
            switch.set_state(False)
            print("TURNING OFF")
        case _:
            print(f"Invalid payload `{payload}`!")

Note

Notice that the switch component is sending its new state back to Home Assistant. Is Switch.optimistic was set to True manually or by not defining Switch.state_topic, this would not be required.

Declare the discovery info

Declare a bare bones device with a single switch component.

discovery_info = DiscoveryInfo(
    device=DeviceInfo(identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'switch': Switch(
            command_topic="~/command",
            state_topic="~/state",
            command_callback=callback
        )
    }
)

Main program

The preferred way to use the Device and MQTTClient classes is inside a context manager.

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    input("Press enter to exit")

Full code sample

Full code sample

Switch example

from nirahmq import *
from nirahmq.components import Switch


def callback(switch: Switch, payload: str) -> None:
    match payload:
        case switch.payload_on:
            switch.set_state(True)
            print("TURNING ON")
        case switch.payload_off:
            switch.set_state(False)
            print("TURNING OFF")
        case _:
            print(f"Invalid payload `{payload}`!")


discovery_info = DiscoveryInfo(
    device=DeviceInfo(identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'switch': Switch(
            command_topic="~/command",
            state_topic="~/state",
            command_callback=callback
        )
    }
)

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    input("Press enter to exit")

Temperature light

A single light with color temperature support in Kelvin.

Import modules

First import all the necessary modules:

import json

from nirahmq import *
from nirahmq.components import Light
from nirahmq.enums import LightColorMode

Declare the light callback

The light command callback is called each time a payload is sent from Home Assistant to the light. The expected payloads are JSON encoded.

Important

Currently only the JSON schema is supported with the Light component.

def callback(light: Light, payload: str) -> None:
    try:
        cmd = json.loads(payload)
        if cmd['state'] == 'ON':
            if not callback.prev_state:
                print("Turning light ON")

            if brightness := cmd.get('brightness'):
                print(f"Setting brightness to {brightness / 2.55:.0f}%")

            if temp := cmd.get('color_temp'):
                print(f"Setting color temperature to {temp}K")

            callback.prev_state = True
        elif cmd['state'] == 'OFF':
            print("Turning light OFF")

            callback.prev_state = False
    except json.decoder.JSONDecodeError:
        pass


callback.prev_state = False  # Function static variable

Note

Here, the light is working in optimistic mode, as no Light.state_topic is defined.

Declare the discovery info

Declare a bare bones device with a single light component.

discovery_info = DiscoveryInfo(
    device=DeviceInfo(identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'light': Light(
            command_topic="~/command",
            supported_color_modes=[LightColorMode.COLOR_TEMP],
            color_temp_kelvin=True,
            command_callback=callback
        )
    }
)

Main program

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    input("Press enter to exit")

Full code sample

Full code sample

Light example

import json

from nirahmq import *
from nirahmq.components import Light
from nirahmq.enums import LightColorMode


def callback(light: Light, payload: str) -> None:
    try:
        cmd = json.loads(payload)
        if cmd['state'] == 'ON':
            if not callback.prev_state:
                print("Turning light ON")

            if brightness := cmd.get('brightness'):
                print(f"Setting brightness to {brightness / 2.55:.0f}%")

            if temp := cmd.get('color_temp'):
                print(f"Setting color temperature to {temp}K")

            callback.prev_state = True
        elif cmd['state'] == 'OFF':
            print("Turning light OFF")

            callback.prev_state = False
    except json.decoder.JSONDecodeError:
        pass


callback.prev_state = False  # Function static variable

discovery_info = DiscoveryInfo(
    device=DeviceInfo(identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'light': Light(
            command_topic="~/command",
            supported_color_modes=[LightColorMode.COLOR_TEMP],
            color_temp_kelvin=True,
            command_callback=callback
        )
    }
)

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    input("Press enter to exit")

Multi-sensor device

A device containing multiple sensor components.

Import modules

First import all the necessary modules:

import random

from nirahmq import *
from nirahmq.components import Sensor
from nirahmq.enums import SensorClass

Declare the discovery info

Declare a bare bones device with one temperature and one humidity sensor.

discovery_info = DiscoveryInfo(
    device=DeviceInfo(name="Multi device", identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'temp': Sensor(
            device_class=SensorClass.TEMPERATURE,
            suggested_display_precision=1,
            state_topic="~/state"
        ),
        'humid': Sensor(
            device_class=SensorClass.HUMIDITY,
            suggested_display_precision=1,
            state_topic="~/state"
        )
    }
)

Main program

Inside the context, the values for the temperature and humidity sensor is set to random values.

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    device['temp'].set_value(random.uniform(20, 30))
    device['humid'].set_value(random.uniform(40, 60))

    input("Press enter to exit")

Full code sample

Full code sample

Light example

import random

from nirahmq import *
from nirahmq.components import Sensor
from nirahmq.enums import SensorClass

discovery_info = DiscoveryInfo(
    device=DeviceInfo(name="Multi device", identifiers="nirahmq-device"),
    origin=OriginInfo(name="Python example"),
    components={
        'temp': Sensor(
            device_class=SensorClass.TEMPERATURE,
            suggested_display_precision=1,
            state_topic="~/state"
        ),
        'humid': Sensor(
            device_class=SensorClass.HUMIDITY,
            suggested_display_precision=1,
            state_topic="~/state"
        )
    }
)

with (MQTTClient("homeassistant.lan", username="<username>", password="<password>") as client,
      Device(client, discovery_info) as device):
    device['temp'].set_value(random.uniform(20, 30))
    device['humid'].set_value(random.uniform(40, 60))

    input("Press enter to exit")