Overview

This module integrates with Home Assistant using MQTT to provide telemetry, commands, and device control. It allows seamless communication between the MicroPython device and Home Assistant, enabling real-time updates and control of connected devices such as LED strips, relays, and sensors.

Features

• MQTT Integration:
  • Publishes telemetry data to Home Assistant.
  • Subscribes to commands from Home Assistant.
• Device Discovery:
  • Automatically registers devices with Home Assistant using MQTT discovery.
• Real-Time Updates:
  • Sends telemetry updates for connected devices.
  • Supports state changes and telemetry updates for LED strips, relays, and other sensors.
• Web-Based Configuration:
  • Configure MQTT settings (server, username, password) via a web interface.
• Support for Multiple Devices:
  • Handles telemetry and commands for various devices, including LED strips, relays, and sensors.

UI Hardware / Pinout Configuration

• Microcontroller:
  • Requires a Wi-Fi-enabled microcontroller (e.g., ESP32 or ESP8266).
  • Uses the MQTT protocol for communication with Home Assistant.
• MQTT Server:
  • Configurable via the web interface (web_ha.html).
  • Default server: mqtt.wolfen.za.net.

Telemetry Provided

The module provides telemetry data for various devices. Examples include:

• General Telemetry:
  • temperature: Current temperature in degrees Celsius.
  • humidity: Current humidity percentage.
  • rssi: Wi-Fi signal strength in dBm.
  • freeram: Free RAM in bytes.
  • freedisk: Free disk space in bytes.
  • wifiuptime: Wi-Fi uptime in seconds.
• LED Strip Telemetry:
  • ledprimary: Primary color in RGB format.
  • ledsecondary: Secondary color in RGB format.
  • ledbrightness: Brightness level (1-255).
  • ledaction: Current animation effect (e.g., fade, cycle).
  • ledstate: Current state (ON or OFF).
• Relay Telemetry:
  • relay: Current state of relays (ON or OFF).

Telemetry Consumed

• None. This module does not consume telemetry from external sources.

Commands Provided

The module supports the following commands:

• LED Strip Commands:
  • Set primary and secondary colors.
  • Adjust brightness.
  • Change animation effects (e.g., fade, cycle, bounce).
  • Example command for setting primary color:

    {
      "command": "setColor",
      "value": "255,0,0"
    }
    

• Relay Commands:
  • Turn relays on or off.
  • Example command for turning a relay on:

    {
      "command": "relay/on/1"
    }
    

• System Commands:
  • Reboot the device.
  • Example command:

    {
      "command": "/system/reboot"
    }
    

Commands Consumed

The module subscribes to MQTT topics for commands. Examples include:

• /ledprimary/command: Commands for the primary LED strip.
• /ledsecondary/command: Commands for the secondary LED strip.
• /relay/command: Commands for relays.
• /system/reboot: Command to reboot the device.

Web Interface

The module includes a web-based configuration page (web_ha.html) for setting up MQTT integration. Features include:

• Enable or disable Home Assistant integration.
• Configure MQTT server, username, and password.
• Set topics for publishing and subscribing to telemetry and commands.
• Save settings, which are persisted across device restarts.

MQTT Discovery

• Devices are automatically registered with Home Assistant using MQTT discovery.
• Configuration topics are dynamically generated based on the device ID and telemetry attributes.
• Example configuration for an LED strip (ledprimary.json or ledsecondary.json):

  {
    "brightness": true,
    "brightness_scale": 255,
    "color_mode": true,
    "command_topic": "~/command",
    "effect": true,
    "effect_list": ["none", "switch", "fade", "cycle", "bounce", "rainbow"],
    "json_attributes_topic": "~/jsonstate",
    "schema": "json",
    "supported_color_modes": ["rgb"],
    "stat_t": "~/state"
  }
  

Unit of Measurement (UOM)

The uom.json file defines units of measurement for telemetry attributes. Examples:

• temperature: *C
• humidity: %
• rssi: dBm
• freeram: bytes

Device Classes

The devclass.json file maps telemetry attributes to Home Assistant device classes. Examples:

• temperature: temperature
• humidity: humidity
• relay: switch

Additional Information

• Persistence:
  • User preferences (e.g., MQTT settings) are saved and restored on restart.
• LED Strip Configuration:
  • The ledprimary.json and ledsecondary.json files define the configuration for LED strips, including supported effects and color modes.
• Error Handling:
  • The module automatically reconnects to the MQTT broker if the connection is lost.
  • Logs errors and connection attempts via SerialLog.

This module provides a robust and flexible integration with Home Assistant, making it ideal for IoT projects that require real-time telemetry and control.