blog.matterxiaomi.com

Ecovacs in Home Assistant Part8 - Create a complete Home Assistant integration for the Ecovacs X5 Pro(skills)

2026-05-12T19:59:00Z

Control Ecovacs Deebot robot vacuums via the Ecovacs Open Platform AK and a gateway (/robot/skill/*).

I'll analyze these https://github.com/mslycn/vacumm-ecovacs-deebot/blob/main/references/api.md#cloudctl-clean to understand the Ecovacs API.I've created a complete Home Assistant integration for the Ecovacs Deetbot X5 Pro.

Repository Structure
Control commands

Repository Structure

custom_components/ecovacs_x5pro/
├── __init__.py (setup integration)
├── manifest.json (metadata)
├── const.py (constants)
├── config_flow.py (configuration UI)
├── api.py (API client)
└── vacuum.py (vacuum entity)

api.py GetWorkState

config_flow.py

api.py

the actual API returns:

JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dust'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'wash', 'chargeSt': 'charging', 'stationSt': 'i'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'washpause', 'chargeSt': 'charging', 'stationSt': 'i'}}}}

Your API response has one extra level of nesting that wasn't accounted for.So you need to go one level deeper:

ctl = (
    data.get("data", {})      # First data level
        .get("data", {})      # ← SECOND data level (was missing!)
        .get("ctl", {})       # Then ctl
        .get("data", {})      # Then final data
)

vacuum.py

当前 vacuum.py 推荐结构（tree）

vacuum.py
│
├── imports
│
├── logger
│
├── SCAN_INTERVAL
│
├── 状态映射
│   └── STATION_MAP
│
├── class EcovacsX5Vacuum(StateVacuumEntity)
│   │
│   ├── __init__
│   │
│   ├── device_info
│   │
│   ├── should_poll
│   │
│   ├── async_update
│   │
│   ├── state
│   │
│   ├── extra_state_attributes
│   │
│   ├── async_start
│   │
│   ├── async_pause
│   │
│   ├── async_return_to_base
│   │
│   └── _send
│
└── async_setup_entry

more detail

vacuum.py
│
├── from homeassistant.components.vacuum import ...
├── from datetime import timedelta
├── import aiohttp
├── import logging
│
├── _LOGGER
│
├── SCAN_INTERVAL
│
├── STATION_MAP
│   ├── i → idle
│   ├── w → washing
│   ├── d → drying
│   ├── e → emptying
│   ├── g → going_charging
│   ├── c → charging
│   └── p → paused
│
├── class EcovacsX5Vacuum
│   │
│   ├── __init__(api)
│   │   ├── 保存 api
│   │   ├── 设置 entity 名称
│   │   ├── 设置 unique_id
│   │   ├── 初始化 state
│   │   └── 设置支持功能
│   │
│   ├── device_info
│   │   └── 注册设备到 HA
│   │
│   ├── should_poll
│   │   └── 告诉 HA 需要轮询
│   │
│   ├── async_update
│   │   ├── 调 API
│   │   ├── 获取状态
│   │   ├── 更新 self._state
│   │   └── 更新 self._station
│   │
│   ├── state
│   │   └── 返回 vacuum 状态
│   │
│   ├── extra_state_attributes
│   │   └── 返回 station_state
│   │
│   ├── async_start
│   │   └── Clean s
│   │
│   ├── async_pause
│   │   └── Clean p
│   │
│   ├── async_return_to_base
│   │   └── Charge go
│   │
│   └── _send
│       ├── POST 控制命令
│       ├── 刷新状态
│       └── 更新 UI
│
└── async_setup_entry
    ├── 创建 API
    └── 注册实体

vacuum.py

必须提供 device_info（否则没有设备卡片）

@property
def device_info(self):
    return {
        "identifiers": {("ecovacs_x5pro", self.api.name)},
        "name": "Ecovacs X5 Pro",
        "manufacturer": "Ecovacs",
        "model": "X5 Pro",
    }

实体必须有 unique_id（否则不会注册）

self._attr_unique_id = f"ecovacs_x5pro_{api.name}"

async_add_entities 必须执行，实体创建

async_add_entities([EcovacsX5Vacuum(api)], update_before_add=True)

vacuum.py - async_setup_entry(hass, entry, async_add_entities)

# ---------------- setup ----------------

async def async_setup_entry(hass, entry, async_add_entities):
    """Set up vacuum entity from config entry."""


    async_add_entities(
        [EcovacsX5Vacuum(api)],
        update_before_add=True
    )

__init__.py - async_setup_entry 必须正确加载平台

await hass.config_entries.async_forward_entry_setups(
    entry,
    ["vacuum", "sensor"]   # 👈 你有哪些就写哪些
)

vacuum.py

class EcovacsX5Vacuum(StateVacuumEntity):
    """Ecovacs X5 Pro vacuum entity."""

    def __init__(self, api):

        self._station = "idle"

    @property
    def device_info(self):
        """Return device information."""
        return {
            "identifiers": {("ecovacs_x5pro", self.api.name)},
            "name": "Ecovacs X5 Pro",
            "manufacturer": "Ecovacs",
            "model": "X5 Pro",
        }
    ....

    async def async_update(self):
        """Update the vacuum state."""
    ...
            # Update  State
            if clean_code == "wash":
                self._state = "washing"
    ...


# ---------------- setup ----------------

async def async_setup_entry(hass, entry, async_add_entities):
    """Set up vacuum entity from config entry."""

    from .api import EcovacsAPI

    api = EcovacsAPI(
        entry.data["ak"],
        entry.data["nickname"]
    )

   #  4.3 实体创建
    async_add_entities(
        [EcovacsX5Vacuum(api)],
        update_before_add=True
    )

   @property
   def icon(self):
       return "mdi:robot-vacuum"    # 加 icon，让 UI 更像官方

Control commands

vacuum.py

run ok

 async def async_start(self):
        """Start the vacuum."""
        await self._send("Clean", {"act": "s"})

    async def async_pause(self):
        """Pause the vacuum."""
        await self._send("Clean", {"act": "p"})

    async def async_return_to_base(self):
        """Return the vacuum to base."""
        await self._send("Charge", {"act": "go"})

    async def _send(self, cmd, data):
        payload = {
            "ak": self.api.ak,
            "nickName": self.api.name,
            "ctl": {
                "cmd": cmd,
                "data": data
            }
        }

Ecovacs in Home Assistant Part7 - Robot Vacuum Control skills

2026-05-11T15:45:15Z

For state queries, you can use the script status, or call GetWorkState via POST /robot/skill/ctl.

Now we Call the Ecovacs Deebot gateway api via HTTP

Device list
Get area list
GetWorkState
- stationState when deebot docked

Device list

curl -sS "https://open.ecovacs.com/robot/skill/deviceList?ak=your Access Key"

curl -sS "https://open.ecovacs.cn/robot/skill/deviceList?ak=FOcadaKSxfWGsZ65bsDeGlXjc4bASLko" | python -m json.tool
{
    "msg": "OK",
    "code": 0,
    "data": [
        {
            "name": "E0**",
            "nick": "DEEBOTX5PRO"
        },
        {
            "name": "E0**",
            "nick": null
        }
    ]
}

curl -sS -X POST "https://open.ecovacs.cn/robot/skill/ctl" -H 'Content-Type: application/json' \

-d “{\"ak\":\"FOcadaKSxfWGsZ65bsDeGlXjc4bASLko\",\"nickName\":\"DEEBOTX5PRO\",\"ctl\":{\"cmd\":\"GetAreaList\",\"data\":{}}}" | python -m json.tool

Get area list

curl -sS -X POST "${BASE_URL}/robot/skill/ctl" -H 'Content-Type: application/json' \

-d "{\"ak\":\"${AK}\",\"nickName\":\"device nick or name fragment\",\"ctl\":{\"cmd\":\"GetAreaList\",\"data\":{}}}"

curl -sS -X POST "https://open.ecovacs.cn/robot/skill/ctl" \
  -H "Content-Type: application/json" \
  -d '{
    "ak": "FOcadaKSxfWGsZ65bsDeGlXjc4bASLko",
    "nickName": "DEEBOTX5PRO",
    "ctl": {
      "cmd": "GetAreaList",
      "data": {}
    }
  }' | python -m json.tool

output

 curl -sS -X POST "https://open.ecovacs.cn/robot/skill/ctl" \
  -H "Content-Type: application/json" \
  -d '{
    "ak": "FOcadaKSxfWGsZ65bsDeGlXjc4bASLko",
    "nickName": "DEEBOTX5PRO",
    "ctl": {
      "cmd": "GetAreaList",
      "data": {}
    }
  }' | python -m json.tool
{
    "msg": "OK",
    "code": 0,
    "data": {
        "code": 0,
        "msg": "success",
        "data": {
            "ctl": {
                "data": {
                    "ret": "ok",
                    "list": [
                        {
                            "subType": "6",
                            "mssid": "2",
                            "name": "\u5ba2\u5385\u536b\u751f\u95f4"
                        },
                        {
                            "subType": "6",
                            "mssid": "3",
                            "name": "\u4e3b\u5367\u536b\u751f\u95f4"
                        },
                        {
                            "subType": "13",
                            "mssid": "4",
                            "name": "\u9633\u53f0"
                        },
                        {
                            "subType": "5",
                            "mssid": "5",
                            "name": "\u53a8\u623f"
                        },
                        {
                            "subType": "0",
                            "mssid": "6",
                            "name": "\u5ba2\u4eba\u623f"
                        },
                        {
                            "subType": "10",
                            "mssid": "7",
                            "name": "\u513f\u7ae5\u623f"
                        },
                        {
                            "subType": "3",
                            "mssid": "8",
                            "name": "\u5367\u5ba4"
                        },
                        {
                            "subType": "1",
                            "mssid": "9",
                            "name": "\u5ba2\u5385"
                        },
                        {
                            "subType": "4",
                            "mssid": "10",
                            "name": "\u4e66\u623f"
                        }
                    ]
                }
            }
        }
    }
}

subtype: 0 unspecified, 1 living room, 2 dining room, 3 bedroom, 4 study, 5 kitchen, 6 bathroom

see: https://github.com/mslycn/vacumm-ecovacs-deebot/blob/main/references/api.md#getarealist-response-list-appendix-e

GetWorkState

curl -X POST "https://open.ecovacs.cn/robot/skill/ctl" \

-H "Content-Type: application/json" \

-d '{

"ak": "你的AK",

"nickName": "你的设备",

"ctl": {

"cmd": "GetWorkState"

}

curl -X POST "https://open.ecovacs.cn/robot/skill/ctl" \
-H "Content-Type: application/json" \
-d '{
  "ak": "FOcadaKSxfWGsZ65bsDeGlXjc4bASLko",
  "nickName": "DEEBOTX5PRO",
  "ctl": {
    "cmd": "GetWorkState"
  }
}' | python -m json.tool

output

{
    "msg": "OK",
    "code": 0,
    "data": {
        "code": 0,
        "msg": "success",
        "data": {
            "ctl": {
                "data": {
                    "ret": "ok",
                    "cleanSt": "h",
                    "chargeSt": "charging",
                    "stationSt": "i"
                }
            }
        }
    }
}

stationState when deebot docked

idle

"ret": "ok",

"cleanSt": "h",

"chargeSt": "charging",

"stationSt": "i"

dust

"data": {

"ret": "ok",

"cleanSt": "h",

"chargeSt": "charging",

"stationSt": "dust"

dust via ecovacs home app

JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'i'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dustpause'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dust'}}}}}

deebot auto return to dust

Ecovacs data from vacuum.py: {'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dust'}
Ecovacs data from vacuum.py: {'cleanSt': 's', 'chargeSt': 'i', 'stationSt': 'i'}
Ecovacs data from vacuum.py: {'cleanSt': 'h', 'chargeSt': 'g', 'stationSt': 'i'}
Ecovacs data from vacuum.py: {'cleanSt': 'p', 'chargeSt': 'charging', 'stationSt': 'i'}
Ecovacs data from vacuum.py: {'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dustpause'}

wash

"cleanSt": "wash",

"chargeSt": "charging",

"stationSt": "i"

JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'dust'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'wash', 'chargeSt': 'charging', 'stationSt': 'i'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'washpause', 'chargeSt': 'charging', 'stationSt': 'i'}}}}

dry

"data": {

"ret": "ok",

"cleanSt": "h",

"chargeSt": "charging",

"stationSt": "dry"

Cleaning only vacumm

{

"msg": "OK",

"code": 0,

"data": {

"code": 0,

"msg": "success",

"data": {

"ctl": {

"data": {

"ret": "ok",

"cleanSt": "s",

"chargeSt": "i",

"stationSt": "i"

}

error code

JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'fail', 'errno': 4200, 'msg': '{"ret":"fail","errno":4200,"error":"endpoint offline","debug":"jmq.clusterNode.FetchClientInfo rsp!=null; clientinfo is in redis, but last endpoint ping and sync to redis time is 1778503965012, "}'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'fail', 'errno': 4200, 'msg': '{"ret":"fail","errno":4200,"error":"endpoint offline","debug":"jmq.clusterNode.FetchClientInfo rsp!=null; clientinfo is in redis, but last endpoint ping and sync to redis time is 1778503965013, "}'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'fail', 'errno': 4200, 'msg': '{"ret":"fail","errno":4200,"error":"endpoint offline","debug":"jmq.clusterNode.FetchClientInfo rsp!=null; clientinfo is in redis, but last endpoint ping and sync to redis time is 1778503965014, "}'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'fail', 'errno': 4200, 'msg': '{"ret":"fail","errno":4200,"error":"endpoint offline","debug":"jmq.clusterNode.FetchClientInfo rsp!=null; clientinfo is in redis, but last endpoint ping and sync to redis time is 1778503965018, "}'}}}}}
JSON response from api.py: {'msg': 'OK', 'code': 0, 'data': {'code': 0, 'msg': 'success', 'data': {'ctl': {'data': {'ret': 'ok', 'cleanSt': 'h', 'chargeSt': 'charging', 'stationSt': 'i'}}}}}

detail：

CloudCtl: Clean https://github.com/mslycn/vacumm-ecovacs-deebot/blob/main/references/api.md#cloudctl-clean

How to upgrade Raspberry Pi OS

2026-04-29T20:47:03Z

This article is intended to look at the commands needed for the Raspberry Pi Upgradation to Latest Version.

I have a RPi 5 running Raspberry Pi OS Lite (Bookworm), and I upgrade it to the newest Raspberry OS (Debian 13 Trixie).

Upgrade Raspberry Pi OS from Bookworm to Trixie.

Check Raspberry OS Version (Current)
Make Sure the System Is Up to Date
Edit sources.list for Debian Trixie
Update the Raspberry Pi OS
Verification - Display your Debian version

Check Raspberry OS Version (Current)

cat /etc/os-release

output

cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

Make Sure the System Is Up to Date

Before upgrading, update and upgrade all existing packages,Ensure your current system is fully updated.Perform a full upgrade of your existing OS installation.

sudo apt update
sudo apt full-upgrade
sudo reboot

Edit sources.list for Debian Trixie

Change all references from bookworm to trixie.

In this file, you only need to change bookworm to trixie.

sudo nano /etc/apt/sources.list

change

deb http://raspbian.raspberrypi.org/raspbian/ bookworm main contrib non-free rpi non-free-firmware

deb http://deb.debian.org/debian trixie main contrib non-free non-free-firmware
deb http://deb.debian.org/debian-security/ trixie-security main contrib non-free non-free-firmware
deb http://deb.debian.org/debian trixie-updates main contrib non-free non-free-firmware

sudo nano /etc/apt/sources.list.d/raspi.list

change

deb http://archive.raspberrypi.com/debian/ bookworm main

deb http://archive.raspberrypi.com/debian/ trixie main

Update the Raspberry Pi OS

Upgrade to Debian 13 (Trixie)

# Ensure that your system has the latest repository information.Refresh package index
sudo apt update -y
# This will update the Raspberry Pi to the version that is available for the device.
sudo apt full-upgrade -y
# Restart your Device
sudo reboot

output

Get:1 http://deb.debian.org/debian trixie InRelease [140 kB]
Get:2 http://deb.debian.org/debian-security trixie-security InRelease [43.4 kB]
...
Get:858 http://deb.debian.org/debian trixie/main arm64 zstd arm64 1.5.7+dfsg-1 [635 kB]                                                
Fetched 788 MB in 1min 17s (10.2 MB/s)                                                                                                 
Reading changelogs... Done

...

update-initramfs: Generating /boot/initrd.img-6.12.75+rpt-rpi-v8
'/boot/initrd.img-6.12.75+rpt-rpi-v8' -> '/boot/firmware/initramfs8'
update-initramfs: Generating /boot/initrd.img-6.12.75+rpt-rpi-2712
'/boot/initrd.img-6.12.75+rpt-rpi-2712' -> '/boot/firmware/initramfs_2712'
Processing triggers for libgdk-pixbuf-2.0-0:arm64 (2.42.12+dfsg-4+deb13u1) ...

After the upgrade completes, reboot your system.

Verification - Display your Debian version

 cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
NAME="Debian GNU/Linux"
VERSION_ID="13"
VERSION="13 (trixie)"
VERSION_CODENAME=trixie
DEBIAN_VERSION_FULL=13.4
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

Useful links

Upgrades from Debian 12 (bookworm)

https://www.debian.org/releases/trixie/release-notes/upgrading.en.html#upgrading-full

how to run locally llama.cpp for home assistant on rpi5

2026-05-09T17:05:26Z

Large Language Models for Home Assistant.

To run llama.cpp locally for Home Assistant, you must host a llama.cpp server that provides an API， that Home Assistant can communicate with via an API.

Home Assistant does not have a "llama.cpp" brand integration by default.

connect Home Assistant to it using a compatible integration. such as https://github.com/skye-harris/hass_local_openai_llm.

Run llama-server
Connect to Home Assistant
- Integration
- Voice assistant

Device: Raspberry Pi 5 (8GB)

OS: Debian 12

Runtime: Docker

Inference Engine: llama-server

Model: Gemma 4 E2B (GGUF, quantized)

Home assistant Integration: Local OpenAI LLM

In the ghcr.io/ggml-org/llama.cpp repository, the images are split by purpose:

Tag	Primary Contents	Best Use Case
`:light`	`llama-cli`, `llama-completion`	Testing/CLI: Best for running models in the terminal or one-off completions without overhead.
`:server`	`llama-server`	Production/API: Ideal for your Home Assistant setup. It provides the OpenAI-compatible endpoint.
`:full`	CLI, Server, and Python conversion/quantization tools.	Development: Use this if you need to convert `.safetensors` to `.gguf` or quantize a model yourself.

:light: Contains only llama-cli and llama-completion.It does not contain the API server.

:server: Contains only llama-server.It contain the API server not contain llama-cli.A lightweight, OpenAI API compatible, HTTP server for serving LLMs.

:full: Contains everything.

You should use the :server tag (or better yet, the :server-arm64 tag since you are on a Raspberry Pi 5).

Run llama-server

The llama-server executable acts as an OpenAI-compatible API that Home Assistant can use.

docker run -it --rm \
  --name llama \
  -v /datadocker/llama-cpp/models:/models \
  -p 8091:8080 \
  ghcr.io/ggml-org/llama.cpp:server \
  -m /models/google_gemma-4-E2B-it-Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --threads 4 \
  --jinja

Parameter Description

--entrypoint /app/llama-cli: processes your input (or waits for one), and then exits. It does not listen for network requests on a port.

--entrypoint /app/llama-server: You were using llama-cli, which is for one-off prompts in the terminal. The llama-server is required to handle API calls like curl.

--host 0.0.0.0: Inside a Docker container, the server must listen on 0.0.0.0 to accept connections from your Raspberry Pi's IP or localhost.

--port 8080: This tells the software inside the container to listen on port 8080 (which you mapped to 8091 on your host).

--jinja: support for OpenAI-style function calling.Tool calling must be enabled in inference engine.Detail

output

...
srv          init: init: chat template, thinking = 1
main: model loaded
main: server is listening on http://0.0.0.0:8080
main: starting the main loop...
srv  update_slots: all slots are idle

Now llama.cpp = local LLM → HTTP API server

Test

Once the server logs show "HTTP server listening", run your curl command. Make sure to include a JSON body, otherwise the server might reject the request:

curl http://localhost:8091/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello Gemma!"}]
  }'

Connect to Home Assistant

Integration - Add Integration

Custom Integration - Local OpenAI LLM Integration

https://github.com/skye-harris/hass_local_openai_llm

Wyoming-LLM (The Bridge): A Home Assistant Integration that sits between HA and llama.cpp.

Custom Integration - Configure Integration

Added server URL to the initial server configuration

http://192.168.2.125:8091

Voice assistant - Create conversation agent

Add assistant

How to Run AI Models Locally with llama.cpp on rpi5

2026-04-23T17:42:13Z

Most people access generative AI tools like ChatGPT or Gemini through a web interface or API — but what if you could run them locally?

In this article, you’ll learn how to set up your own local generative AI using existing models such as llama.cpp.

The final result will look like the GIF shown below (note, it’s hosted localhost)

Prerequisites

Prerequisites

Hardware: Raspberry Pi 5 (8GB RAM highly recommended).

OS: Raspberry Pi OS (64-bit) or Ubuntu (64-bit).

Storage: At least 5GB free space (preferably on an SSD/NVMe for speed).

Device: Raspberry Pi 5 (8GB)

OS: Debian 12

Runtime: Docker

Engine: llama.cpp

Model: Gemma 4 E2B (GGUF, quantized)

Install Docker (Debian 12)

Here are the commands I used to Got Gemma 4 E2B running on a Raspberry Pi 5 8GB:

step 1. Pull llama.cpp (light)

First of all, we need an LLM Serving Engine, such as llama.cpp.

# This is the correct lightweight image for Pi (ARM)
docker pull ghcr.io/ggml-org/llama.cpp:light

step 2. Pick a model - Download Gemma (GGUF, quantized)

# llama.cpp only works with GGUF

# Create model directory
mkdir -p /datadocker/llama-cpp
cd /datadocker/llama-cpp/models


https://huggingface.co/unsloth/gemma-4-E2B-it-GGUF/tree/main

https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF/tree/main

google_gemma-4-E2B-it-Q4_0.gguf
https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF/resolve/main/google_gemma-4-E2B-it-Q4_0.gguf?download=true

Note

There is no official “Gemma 4 E2B GGUF direct URL” from Google.

GGUF files are community-converted and hosted on Hugging Face.

step 3. Docker run and load model

Run llama.cpp server (Docker)

docker run -v /path/to/models:/models --entrypoint /app/llama-cli ghcr.io/ggml-org/llama.cpp:light -m /models/7B/ggml-model-q4_0.gguf

run ok

docker run -it --rm \
  -v /datadocker/llama-cpp/models:/models \
  --entrypoint /app/llama-cli \
  -p 8091:8080 \
  ghcr.io/ggml-org/llama.cpp:light \
  -m /models/gemma-4-e2b-it-Q4_K_M.gguf \

Note

1.pick the model you downloaded earlier.

output

load_backend: loaded CPU backend from /app/libggml-cpu-armv8.2_2.so

Loading model...

▄▄ ▄▄
██ ██
██ ██  ▀▀█▄ ███▄███▄  ▀▀█▄    ▄████ ████▄ ████▄
██ ██ ▄█▀██ ██ ██ ██ ▄█▀██    ██    ██ ██ ██ ██
██ ██ ▀█▄██ ██ ██ ██ ▀█▄██ ██ ▀████ ████▀ ████▀
                                    ██    ██
                                    ▀▀    ▀▀

build      : b8833-45cac7ca7
model      : google_gemma-4-E2B-it-Q4_0.gguf
modalities : text

available commands:
  /exit or Ctrl+C     stop or exit
  /regen              regenerate the last response
  /clear              clear the chat history
  /read <file>        add a text file
  /glob <pattern>     add text files using globbing pattern


>

step 4. test

> how

[Start thinking]
Thinking Process:

1.  **Analyze the Request:** The user provided a single word: "how". This is an extremely open-ended prompt. It implies a question, a request for a process, or a search for a method.
2.  **Determine the Context:** Since there is no context, I must provide a response that addresses the ambiguity while offering ways to get a useful answer.
3.  **Identify the Goal:** The goal is to prompt the user to specify what they want to know "how" to do.
4.  **Brainstorm Potential Interpretations of "how":**
    *   *How does X work?* (Mechanism, process)
    *   *How do I do Y?* (Instructions, tutorial)
    *   *How to achieve Z?* (Strategy, steps)
    *   *How are we connected?* (Relationship, system)
5.  **Formulate the Response Strategy:**
    *   Acknowledge the brevity.
    *   State that more information is needed.
    *   Provide examples of the types of questions I can answer.
    *   Invite the user to ask the specific question.
6.  **Draft the Response (Self-Correction/Refinement):** Start with a friendly, open invitation. Ensure the tone is helpful and encouraging. (The resulting response should be a clear call to action.)
[End thinking]

Please tell me what you would like to know **how** to do! 😊

I can help you with instructions, explanations, processes, recipes, coding, concepts, and much more.

**For example, you could ask:**

* "How do I bake a cake?"
* "How does photosynthesis work?"
* "How do I change the font in Microsoft Word?"
* "How do I start learning Spanish?"

**Just tell me your question!**

[ Prompt: 8.6 t/s | Generation: 5.6 t/s ]

>

access generative AI tools like llamacp through a web interface or API

Useful links

llama.cpp on GitHub with Docker image

https://github.com/ggml-org/llama.cpp/blob/master/docs/docker.md

Models download via url

https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF/tree/main

https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF/blob/main/google_gemma-4-E2B-it-Q4_0.gguf

https://huggingface.co/ggml-org/gemma-4-E2B-it-GGUF

How to Run AI Models Locally with Ollama

2026-04-21T20:42:51Z

In this article, you’ll learn how to set up your own local generative AI using existing models such as Gemma 4 and Meta’s LLaMA 3.

The official [Ollama Docker image](https://hub.docker.com/r/ollama/ollama) ollama/ollama is available on Docker Hub.

To run the Gemma 4 model locally using Ollama:

First of all, we need an LLM Serving Engine, such as Ollama: A framework for running large language models locally.

Pull the LLM models via Ollama

Load the LLM models via Ollama

Test the LLM models via Ollama CLI

Install Ollama with Docker
Pull and Run a Model via ollama
Test the LLM models via Ollama CLI
Configuration Checklist

Install Ollama with Docker

There are several ways to install it on your machine,we will Running ollama via Docker.

Download

docker pull ollama/ollama:0.21.0

Version control:

Google officially released the Gemma 4 family on April 2, 2026, and ollama latest version has stabilized support for its unique architectures.

## Run the Container

You need to decide if you want to use CPU-only or GPU acceleration and specified a specific version.

CPU Only

~~~

docker run -d \

  -v ollama:/root/.ollama \

  -p 11434:11434 \

  --name ollama \

  ollama/ollama:0.21.0

~~~

The container starts an API server, but it doesn't come with any LLMs pre-installed.

Pull and Run a Model via ollama

You need to "exec" into the container to pull a model (like Llama 4 ).

# into the container
docker exec -it ollama sh

# Download a model without running it
ollama pull [model-name]

# Run a Model
# A single command (ollama run gemma4:e4b) handles downloading, memory management, and API serving.
ollama run gemma4:e4b

Ollama will automatically download the model.llm server loading model.

Once the model is loaded, you can see generating output:

output

# ollama run gemma4:e2b
>>>

docker logs -f ollama

output

time=2026-04-18T09:18:54.786Z level=INFO source=server.go:1398 msg="waiting for server to become available" status="llm server loading model"
...
time=2026-04-18T09:20:29.899Z level=INFO source=server.go:1402 msg="llama runner started in 97.04 seconds"
[GIN] 2026/04/18 - 09:20:32 | 200 |         1m42s |       127.0.0.1 | POST     "/api/generate"
[GIN] 2026/04/18 - 09:22:32 | 200 | 39.184533484s |       127.0.0.1 | POST     "/api/chat"

Test the LLM models via Ollama CLI

start a chat -Test the LLM models

Verify - cli(Test in CLI)

# ollama run gemma4:e2b
>>> how
Thinking...
Thinking Process:

1.  **Analyze the Input:** The input is "how".
...

Verify - api test

curl http://localhost:11434/api/chat -d '{
  "model": "gemma3",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'

output

root@debian:~# curl http://localhost:11434/api/chat -d '{
  "model": "gemma4:e2b",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'
{"model":"gemma4:e2b","created_at":"2026-04-18T09:24:45.242321396Z","message":{"role":"assistant","content":"The reason the sky appears blue is due to a phenomenon called **Rayleigh Scattering**. It is a result of how sunlight interacts with the small molecules of the Earth's atmosphere.\n\nHere is a detailed breakdown of the process:\n\n---\n\n### 1. The Ingredients: Sunlight and Atmosphere\n\n**A. Sunlight is White Light:**\nSunlight, which appears white to us, is actu
...

Verify - Web UI(Browser test)

open-webui

https://github.com/open-webui/open-webui

# ollama list
NAME             ID              SIZE      MODIFIED          
gemma4:e2b       7fbdbf8f5e45    7.2 GB    15 minutes ago       
gemma4:e4b       c6eb396dbd59    9.6 GB    About an hour ago    
gemma3:4b        a2af6cc3eb7f    3.3 GB    2 hours ago          
llama3:latest    365c0bd3c000    4.7 GB    3 hours ago

Quick Diagnostic Steps

docker logs -f ollama

Configuration Checklist

OS: 64-bit Debian12 OS

RAM:16G

CPU:Intel Cpu 10400

Larger Models:Gemma 4 E2B (4-bit)

Useful links

Recommended Models of ollama

https://ollama.com/library

gemma4 Model information

https://ollama.com/library/gemma4:e4b

Gemma 4 Inference Memory Requirements

https://ai.google.dev/gemma/docs/core#gemma-4-inference-memory-requirements

Parameters	BF16 (16-bit)	SFP8 (8-bit)	Q4_0 (4-bit)
Gemma 4 E2B	9.6 GB	4.6 GB	3.2 GB
Gemma 4 E4B	15 GB	7.5 GB	5 GB
Gemma 4 31B	58.3 GB	30.4 GB	17.4 GB
Gemma 4 26B A4B	48 GB	25 GB	15.6 GB

model requires more system memory (9.8 GiB) than is available (4.7 GiB)

blog

https://medium.com/tech-ai-chat/running-llm-on-a-local-mac-machine-0dae23d8320b

Ollama vs LiteLLM vs llmama.cpp vs vvllm vs lm studio

2026-04-19T18:27:39Z

How to run a local LLM server step by step

Ollama vs LiteLLM vs llmama.cpp vs vvllm vs lm studio

These tools represent different layers of the AI stack. While they overlap, they generally serve distinct purposes:

Serving (Llama.cpp, vLLM),

Managing (Ollama, LM Studio),

Routing (LiteLLM).

Managing (Ollama, LM Studio)
Serving (Llama.cpp, vLLM)
Routing (LiteLLM)

Managing (Ollama, LM Studio)

Ollama

A local LLM inference/runtime platform.It handles model downloads, storage, and execution with a simple CLI/API. Think of it as a “local LLM server”.

Run AI Models locally integrate via API

LM Studio

A desktop application.

Run AI Models locally with a Chat UI

Serving (Llama.cpp, vLLM)

llama.cpp - run ai model on edge devices.

Run a model on a Raspberry Pi.

vLLM

Build a high-traffic AI startup or production API.

Routing (LiteLLM)

LiteLLM

LiteLLM is not an inference engine; it is a Proxy/Router.A proxy/gateway layer that provides a unified, OpenAI-compatible API for calling many LLM providers (cloud and local).

Matter Bridge in Home Assistant Part2 - Install MatterBridge Connect to Home assistant

2026-02-16T23:14:37Z

Matter Bridge in Home Assistant Part2 - Install MatterBridge Connect to Home assistant

Quick start
Install and configure
How to Use

Quick start

I set up the matterbridge as follows:

Install the Matterbridge docker

Create long-lived access tokens to allow home-assistant-matter-hub docker to interact with your Home Assistant instance.

Communication configure between Matterhub and Home Assistant,Matterbridge to connect to home assistant with url and token

expose homeassistant device as a matter bridge

open http://192.168.2.125:8482/ via chrome browser

Create a new bridge,

Add device "pattern: switch.air_con" in new bridge

start it to generate a pairing QR code

Connect accessory to Apple Home

Install and configure

docker-compose.yml

You need to create an access token in home assistant instance and export it like this:

services:
  matter-hub:
    image: ghcr.io/t0bst4r/home-assistant-matter-hub:3.0.1
    restart: unless-stopped
    network_mode: host
    environment: # more options can be found in the configuration section
      - HAMH_HOME_ASSISTANT_URL=http://192.168.2.125:8123/
      - HAMH_HOME_ASSISTANT_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzcwZDExYjM4MjE0YzFmYThmZTk3NDZjMDQyODU2NSIsImlhdCI6MTc3MTA4MTk1NSwiZXhwIjoyMDg2NDQxOTU1fQ.vhZD-KhJe4XIXd6_XvBE92y4T5W1aICSfBCbTTCvFL4
      - HAMH_LOG_LEVEL=info
      - HAMH_HTTP_PORT=8482
    volumes:
      - /datadocker/home-assistant-matter-hub:/data

Now you can visit it via web ui

http://192.168.2.125:8482/

How to Use

expose homeassistant device as a matter bridge

open http://192.168.2.125:8482/

Create a new bridge for device,home-assistant-matter-hub docker get it from home assistant via api.

type:pattern

value:light.yeelink_cn_ceiling21_s_2_light

{
  "name": "matterbridgeceilling21v2",
  "port": 5543,
  "filter": {
    "include": [
      {
        "type": "pattern",
        "value": "light.yeelink_cn_476690814_ceiling21_s_2_light"
      }
    ],
    "exclude": []
  },
  "featureFlags": {
    "coverDoNotInvertPercentage": false,
    "includeHiddenEntities": false
  }
}

Ecovacs in Home Assistant Part6 - Ecovacs Robot MCP Server

2026-05-12T18:59:34Z

Official Ecovacs Deebot MCP Server

MCP protocol

https://github.com/ecovacs-ai/ecovacs-mcp/blob/main/ecovacs_mcp/robot_mcp_stdio.py

Created:2025.04.24

Official Doc：

https://open.ecovacs.com/#/serviceOverview

way 1.custom integration
way 2. mcp client integraton in ha

way 1.custom integration

https://github.com/hoangminh1109/ecovacs_cn

way 2. mcp client integraton in ha

mcp client integration

https://www.home-assistant.io/integrations/mcp

mcp client integraton configure

The remote MCP server URL for the SSE endpoint, for example http://example/mcp

Ecovacs SSE Server URL:

https://mcp-open.ecovacs.cn/sse?ak=your ak

useful links

https://open.ecovacs.com/#/serviceOverview

ModelScope vs Hugging Face vs k2-fsa.github.io vs Kaldi vs Sherpa

2026-04-30T17:02:08Z

Hugging Face, ModelScope, and k2-fsa.github.io (specifically the k2-fsa/sherpa-onnx project) represent different approaches to the machine learning ecosystem。

Hugging Face and ModelScope host everything. k2-fsa and Sherpa only do Speech.

k2-fsa and Sherpa are highly specialized tools focused on speech recognition (ASR) and synthesis (TTS)

Sherpa (often referred to as sherpa-onnx or sherpa-ncnn) is a lightweight speech-to-text (ASR) and text-to-speech (TTS) engine. Best for: Deploying speech models on edge devices (Android, iOS, WebAssembly, ARM boards) or high-performance servers, prioritizing low latency and CPU efficiency.

Hugging Face（Global AI model platform）
ModelScope(The Alibaba/Chinese AI Industrial model platform)
specialized tools focused on speech recognition (ASR) and synthesis (TTS)
- k2-fsa (Next-Gen Kaldi)
- Sherpa(The Real-Time Speech Deployment Tool)

These four entities represent two different categories: Model Ecosystems (Hugging Face & ModelScope) and Speech Recognition Frameworks (Kaldi & k2-fsa).

Hugging Face（Global AI model platform）

The Global Industry Standard。It supports NLP, computer vision, audio, and multimodal models via transformers and diffusers libraries.

download models

https://huggingface.co/models

https://huggingface.co/FunAudioLLM/SenseVoiceSmall

https://huggingface.co/funasr/paraformer-zh/blame/7904416f6cb6290ee7dc0b2ddb2993a9fe4f421a/README.md

ModelScope(The Alibaba/Chinese AI Industrial model platform)

ModelScope is an AI model hub led by Alibaba DAMO Academy. It provides pre-trained models, pipelines, and deployment tools, especially strong in Chinese language and speech technologies.ModelScope is often described as the "Chinese Hugging Face."

https://modelscope.cn/search?search=sherpa%20onnx

Inference Framework

1.funasr

2.funasr-onnx

see:https://github.com/modelscope/FunASR?tab=readme-ov-file#sensevoice

Alibaba Speech-to-Text models tree

Alibaba Speech-to-Text models tree
├── FunASR（ASR 推理框架）
│
│   ├── FunASR 1.3
│   │   ├── Paraformer series
│   │   │   ├── paraformer-zh
│   │   │   ├── paraformer-large
│   │   │   ├── paraformer-streaming
│   │   │   └── paraformer-hotword
│   │
│   ├── FunASR 1.5
│   │   ├── Paraformer（升级版）
│   │   ├── FunASR-Nano series
│   │   │   ├── Nano Small
│   │   │   ├── Nano Streaming
│   │   │   └── Nano Int8（边缘部署）
│   │   │
│   │   ├── SenseVoice series
│   │   │   ├── SenseVoice Small
│   │   │   ├── SenseVoice Large
│   │   │   └── SenseVoice multilingual
│   │
│   └── Inference Framework
│       ├── PyTorch
│       ├── funasr-onnx
│       ├── Sherpa-ONNX
│       └── TensorRT
│
└── FunAudioLLM（语音大模型）

https://github.com/FunAudioLLM/SenseVoice

https://github.com/modelscope/FunASR

specialized tools focused on speech recognition (ASR) and synthesis (TTS)

Kaldi: Speech Toolkit

The "grandfather" of modern speech recognition. It is a C++ based toolkit developed primarily by Dan Povey.

demo

KaldiRecognizer

https://github.com/rhasspy/wyoming-faster-whisper/blob/main/wyoming_faster_whisper/__main__.py

k2-fsa (Next-Gen Kaldi)

Speech Toolkit.The Modern Successor

What it is: Often called "Next-gen Kaldi." It is a complete rewrite of Kaldi’s core concepts to make them natively compatible with PyTorch.

Key Repositories:

Icefall: Where the actual training recipes for speech models (like Zipformer) live.

k2: The core library for differentiable FSTs.the old version of the tool you used before k2-fsa existed.

download sherpa-onnx

https://github.com/k2-fsa/sherpa-onnx/releases

download sherpa-onnx asr models

https://k2-fsa.github.io/sherpa/onnx/pretrained_models/index.html

https://github.com/k2-fsa/sherpa-onnx/releases/tag/asr-models

download Silero VAD ONNX model

# https://k2-fsa.github.io/sherpa/onnx/sense-voice/pretrained.html#sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17
wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/silero_vad.onnx

download url:https://k2-fsa.github.io/sherpa/onnx/vad/silero-vad.html#download-models-files

Sherpa(The Real-Time Speech Deployment Tool)

The deployment engine (CPU/GPU, Android, iOS, WebAssembly).It uses models trained in the k2-fsa ecosystem.

How they all fit together

1.k2-fsa is the tool you use to build a high-performance speech model.

silero-vad model download

https://k2-fsa.github.io/sherpa/onnx/vad/silero-vad.html#download-models-files

Once you've trained that model using k2-fsa, you might upload it to Hugging Face or ModelScope so others can download it easily.

Hugging Face hosts models from both ModelScope and k2-fsa/Sherpa, serving as a distribution point for them.

Layer Relationship

Model Hosting & Distribution
   ├── ModelScope
   └── Hugging Face

Inference / Runtime Framework
   └── k2-fsa / sherpa

blog.matterxiaomi.com

Ecovacs in Home Assistant Part8 - Create a complete Home Assistant integration for the Ecovacs X5 Pro(skills)

Table of Contents

Repository Structure

Control commands

Ecovacs in Home Assistant Part7 - Robot Vacuum Control skills

Table of Contents

Device list

Get area list

GetWorkState

stationState when deebot docked

How to upgrade Raspberry Pi OS

Table of Contents

Check Raspberry OS Version (Current)

Make Sure the System Is Up to Date

Edit sources.list for Debian Trixie

Update the Raspberry Pi OS

Verification - Display your Debian version

how to run locally llama.cpp for home assistant on rpi5

Table of Contents

Run llama-server

Connect to Home Assistant

Integration - Add Integration

Voice assistant - Create conversation agent

How to Run AI Models Locally with llama.cpp on rpi5

Table of Contents

Prerequisites

step 1. Pull llama.cpp (light)

step 2. Pick a model - Download Gemma (GGUF, quantized)

step 3. Docker run and load model

step 4. test

How to Run AI Models Locally with Ollama

Table of Contents

Install Ollama with Docker

Pull and Run a Model via ollama

Test the LLM models via Ollama CLI

Configuration Checklist

Ollama vs LiteLLM vs llmama.cpp vs vvllm vs lm studio

Table of Contents

Managing (Ollama, LM Studio)

Serving (Llama.cpp, vLLM)

Routing (LiteLLM)

Matter Bridge in Home Assistant Part2 - Install MatterBridge Connect to Home assistant

Table of Contents

Quick start

Install and configure

How to Use

Ecovacs in Home Assistant Part6 - Ecovacs Robot MCP Server

Table of Contents

way 1.custom integration

way 2. mcp client integraton in ha

ModelScope vs Hugging Face vs k2-fsa.github.io vs Kaldi vs Sherpa

Table of Contents

Hugging Face（Global AI model platform）

ModelScope(The Alibaba/Chinese AI Industrial model platform)

specialized tools focused on speech recognition (ASR) and synthesis (TTS)

k2-fsa (Next-Gen Kaldi)

download Silero VAD ONNX model

Sherpa(The Real-Time Speech Deployment Tool)