1. Project Overview

Docker, HA, EMQX, MQTT
HACS, HA MCP Server, Xiaozhi MCP install
Link Xiaozhi to HA, expose entities
Flowcharts, key code, MQTTX tests

Voice temperature reading, switch/LED control, MQTT console prints


2. Environment Setup

2.1 Docker

1. Download & install Docker Desktop.
2. Mirror acceleration →Docker Engine settings → add the mirror list provided in the original doc, then Apply.
Go to Settings - Docker Engine and add the following code

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "debug": true,
  "experimental": false,
  "insecure-registries": [
    "registry.docker-cn.com",
    "docker.mirrors.ustc.edu.cn"
  ],
  "registry-mirrors": [
    "https://docker.registry.cyou",
    "https://docker-cf.registry.cyou",
    "https://dockercf.jsdelivr.fyi",
    "https://docker.jsdelivr.fyi",
    "https://dockertest.jsdelivr.fyi",
    "https://mirror.aliyuncs.com",
    "https://dockerproxy.com",
    "https://mirror.baidubce.com",
    "https://docker.m.daocloud.io",
    "https://docker.nju.edu.cn",
    "https://docker.mirrors.sjtug.sjtu.edu.cn",
    "https://docker.mirrors.ustc.edu.cn",
    "https://mirror.iscas.ac.cn",
    "https://docker.rainbond.cc",
    "https://do.nark.eu.org",
    "https://dc.j8.work",
    "https://dockerproxy.com",
    "https://gst6rzl9.mirror.aliyuncs.com",
    "https://registry.docker-cn.com",
    "http://hub-mirror.c.163.com",
    "http://mirrors.ustc.edu.cn/",
    "https://mirrors.tuna.tsinghua.edu.cn/",
    "http://mirrors.sohu.com/"
  ]
}

 Just select Apply.

HA deployment
docker pull homeassistant/home-assistant: latest

EMQX deployment

After adding the software image source, execute the command

docker pull emqx/emqx: latest
to pull the latest version of the emqx image.
Execute the command

docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 emqx/emqx:latest

Create and run the emqx container.

If you receive an error message indicating that the port is already in use, delete the emqx container you created, go to the Images tab, click the Start button corresponding to the emqx/emqx image, and manually configure the container name, host port, and other parameters. Enter 0 for the port, and the system will randomly assign an available port.
Configure EMQX
(1) Go to the Containers page, click the emqx port link, and enter the emqx browser page. The initial login username is admin and the password is public.
(2) Open Access Control - Client Authentication - Create - Password-Based - Built-in Database - (Default Configuration) - Create.

(3) User Management - Create New User - Customise the username and password.

MQTT Configuration
(1) In the command line terminal, enter ipconfig to obtain the local computer's IPv4 address, such as 192.168.31.160
(2) Configure Home Assistant: click Settings - Devices & Services - Add Integration - Search for MQTT - Enter proxy information. 
Enter the computer's IP address in the Proxy field, port 1883, and the username and password created in EMQX.
(3) Navigate to the HA directory, open the configuration.yaml configuration file, and add temperature sensors and switch devices.
mqtt:
  sensor:
    - name: "Temperature"
      state_topic: "ha/adc/temp"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temperature }}"
  switch:
    - name: "Switch"
      unique_id: "led_switch"
      command_topic: "ha/switch/cmd"
      state_topic: "ha/switch/state"
      payload_on: "ON"
      payload_off: "OFF"

      retain: true

Save changes and reload the configuration to apply changes.

(4) Go to the HA overview page, edit the dashboard, and add temperature sensor and switch cards.
Xiaozhi MCP
Includes installation and parameter configuration of HACS, HA MCP, and Xiaozhi MCP.
HACS Installation
Install using the command line;
Enter the HA container terminal,

Execute the following command:
wget -O - https://get.hacs.vip | bash -
Obtain the HACS compressed file and install it automatically.

Once the installation is complete, go to Settings, search for and add HACS integration.
See: hacs-china: HACS Express Edition
HA MCP Installation
Before installing XiaoZhi MCP, you need to install the official HA MCP Server integration.
Features

GitHub： Xiaozhi AI chatbot to Home Assistant via MCP.


5. Establish Connection
To let Xiaozhi control devices, expose HA entities:
HA → Settings → Voice Assistants → Add Assistant (Chinese).
Enable Expose new entities.

Expose tab → add target entities (temperature sensor, switch, etc.).

6. Engineering Test
Use a MicroPython board as an HA end-device (temperature sensor + LED switch).
6.1 Flowchart

6.2 Code (MicroPython)
Save as main.py in Thonny IDE:

#!/usr/bin/env python3import jsonimport networkimport timeimport randomfrom machine import Pin, ADCfrom umqtt.simple import MQTTClient
# ========== Configuration ==========
WIFI_SSID = "xxx"           # wifi name
WIFI_PASS = "xxx"           # wifi password
ADC_PIN = 16                # ADC pin
LED_PIN = 3                 # LED pin
MQTT_SERVER = "192.168.31.160" # ip address
MQTT_PORT = 32768           # MQTT Broker port
MQTT_USER = "xxx"           # MQTT Broker user
MQTT_PASS = "xxx"           # MQTT Broker password
MQTT_CLIENT_ID = f"ha-client-{random.getrandbits(8)}"
# MQTT topic
PUB_TOPIC = "ha/adc/temp"       # publish topic
SUB_TOPIC = "ha/switch/cmd"     # subscribe LED
STATE_TOPIC = "ha/switch/state" # publish LED state# ============================

led = Pin(LED_PIN, Pin.OUT, value=0)  # initialize LED
def wifi_connect():
    sta = network.WLAN(network.STA_IF)
    sta.active(True)
    if not sta.isconnected():
        print("Connecting to WiFi...")
        sta.connect(WIFI_SSID, WIFI_PASS)
        for _ in range(20):
            if sta.isconnected():
                break
            time.sleep(1)
    print("WiFi Connected:", sta.ifconfig())
def read_temperature():
    adc = ADC(Pin(ADC_PIN))
    adc.atten(ADC.ATTN_11DB)
    raw = adc.read()
    volt = raw / 4095 * 3.3
    temp = (volt - 0.5) * 100 - 88 # ADC temperature
    return round(temp, 1)
def mqtt_callback(topic, msg):
    topic = topic.decode()
    msg = msg.decode()
    print(f"MQTT Received: {topic} -> {msg}")
  
    if topic == SUB_TOPIC:
        if msg == "ON":
            led.on()
            client.publish(STATE_TOPIC, "ON")
        elif msg == "OFF":
            led.off()
            client.publish(STATE_TOPIC, "OFF")
def mqtt_connect():
    client = MQTTClient(
        MQTT_CLIENT_ID,
        MQTT_SERVER,
        MQTT_PORT,
        MQTT_USER,
        MQTT_PASS,
        keepalive=60
    )
    client.set_callback(mqtt_callback)
    client.connect()
    client.subscribe(SUB_TOPIC)
    print(f"MQTT Connected to {MQTT_SERVER}, subscribed to {SUB_TOPIC}")
    return client
def main():
    wifi_connect()
    global client
    client = mqtt_connect()
  
    try:
        while True:
            client.check_msg()          # check MQTT 
            temp = read_temperature()   # read temperature
            client.publish(PUB_TOPIC, json.dumps({"temperature": temp}))
            time.sleep(1)               # delay
    finally:
        client.disconnect()
        print("MQTT Disconnected")
if __name__ == "__main__":
    main()

Upload firmware & run.

6.3 MQTTX Test
1. Install MQTTX.
2 . Add connection → enter broker IP, port, credentials.
3 . Subscribe to topics:
Publish to ha/switch/cmd with ON / OFF to test LED. 7. Demo
7.1 Voice Temperature Reading
Dialogue:

(ADC formula adjusted for test purposes.)

7.2 Voice Switch Control