Protocol Homeassistant

Home Assistant

Setting up Home Assistant by hand, in weewx.conf.

Generated by tools/build_protocols.py. What each protocol needs is written in that tool; what it is called and what goes into the console comes from the code. Do not edit by hand.

There is a web interface for all of this. It is on by default, and the driver prints its address when WeeWX starts:

INFO user.ultimatepush.driver: The web interface is at
http://1.2.3.4:8080/?token=abcdefg12345

Everything on this page can be done there instead, and one thing is much easier: deciding which reading goes into which database column. See Web interface.

What it is

Any sensor Home Assistant can read and this driver cannot: Aqara and SwitchBot room sensors, Zigbee and Z-Wave soil probes, Shelly and Tado built-in sensors, anything on Matter or Bluetooth, and every weather station with an integration of its own

In protocols = auto	no, and it does not need to be: naming it under [[polling]] is what switches it on
Named by	the name you give the block
Recording from	its first answer

The smallest configuration that works

[Station]
    station_type = UltimatePush

[UltimatePush]
    driver = user.ultimatepush.driver
    port = 8000

    [[polling]]
        [[[garden]]]
            address = 1.2.3.4:8123
            protocol = homeassistant
            token = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.a-very-long-token
            entities = sensor.garden_temperature, sensor.garden_humidity
            interval = 60
            role = extra
            channel = 3

There is nothing to identify and nothing to wait for: the driver knows what answered because it knows what it asked. What it does have to be told is which sensors to read and what to authenticate itself with, which is the two lines above that no other polled source has. role = extra puts the readings in columns of their own, which is what you want for anything that is not your main weather station.

What else it takes

Home Assistant has nowhere to type a server address into, and it is not asked to send anything. This driver asks it, so what is needed is its address and a token.

The token is a long-lived access token, made in Home Assistant under your own profile, at the bottom of the Security tab. It grants everything your user account can do, so treat it the way you would your password.

One block is one Home Assistant device. Several devices means several blocks against the same address, each with its own role and channel.

Options of its own

These belong to this protocol alone and go in the [[polling]] block that sets the source up. Everything else that applies is in [Configuration](Configuration.md#driver- options).

stale

How old a reading may be, in seconds, before it stops counting as a reading. Twice the interval by default. A sensor whose battery has gone keeps returning its last value for ever, and without this that value would be recorded as though it were fresh. Raise it for a sensor that reports only when its reading changes.

Worth knowing

Home Assistant is not hardware. It is the other program on your network that already talks to the thermometer in the bedroom, the soil probe in the raised bed and the sensor inside the boiler, and it will tell this driver what any of them is reading. So the answer to "can WeeWX read my Aqara" is now: if Home Assistant can, this can.

Make a token first. In Home Assistant, click your name at the bottom of the sidebar, open the Security tab, scroll to Long-lived access tokens and create one. It is shown once. Copy it into the token line before you close the dialog, because there is no way to see it again and the only fix is to make another.

That token can do everything your user account can do, including turning things off. Keep it the way you would keep the password. It goes in weewx.conf, which is readable by whoever can read that file, or in the settings file the web interface writes, which is the same. This driver never prints it: not in a log line, not on the page that shows what arrived, not in an error message. If you would rather it could do less, make the token under a Home Assistant user of its own with only the areas you want it to see.

One block is one device, not one Home Assistant. Home Assistant groups its sensors into devices, and that grouping is exactly what this driver needs: the thermometer on the balcony is one station and the one in the living room is another, so one of them fills the outdoor temperature and the other lands in a column of its own. Set up a second block against the same address for the second device. There is no cost to it.

Say which sensors, and in what order. entities names them, and the order is not decoration. The first temperature in the list is the temperature; a second one on the same device arrives under a name of its own and waits in the web interface for you to say which column it should have. So put the one you mean first.

The web interface does the whole of this for you: type the address, paste the token, press Find the sensors, and it lists what is there grouped by device with the first one ticked.

Readings that are not readings are left out. Home Assistant says unavailable when it cannot reach a sensor and unknown before it has heard from one, and neither of those is zero. A sensor whose battery has gone is worse, because Home Assistant keeps returning the last number it had, for ever: left alone that would write one afternoon's temperature into your database sixty times an hour. So a reading older than stale seconds is not recorded. That is twice the interval unless you say otherwise, which is right for a sensor that reports on a schedule and too short for one that reports only when the reading changes. A soil probe that sends every fifteen minutes wants stale = 2000 or so.

The units are Home Assistant's and the columns are WeeWX's. Whatever it sends, whether Fahrenheit or Kelvin, miles an hour or knots, inches of mercury or hectopascals, is converted before it is recorded. Nothing has to match.

No Home Assistant to hand? python -m user.ultimatepush --fake-homeassistant answers like one, with two devices and three sensors that are not reporting a number.

When nothing arrives

Nothing is recorded and the log says the token was refused: the token is wrong, or it was revoked, or it belongs to a user that has been deleted. Make a new one. It is said once and then the driver stays quiet, so look at the start of the log rather than the end.

One sensor is missing and the rest are fine. Either Home Assistant is saying unavailable or unknown for it, or its last reading is older than stale allows. Open the sensor in Home Assistant: it says at the top when it was last updated. If that is minutes ago and the sensor is working normally, raise stale.

A sensor was recording and stopped, and Home Assistant still shows it. Its entity was renamed. Home Assistant does that when you rename the device it belongs to, and the old name then belongs to nothing; the log says which one it could not read.

Two sensors of the same kind and only one is recorded. That is deliberate. The first of each kind fills the column, and the second arrives under a name of its own; the web interface lists it and gives it a column when you say where it goes.

The device has no name and the station is called nothing. Rendering the list of devices needs an administrator's token, and reading the sensors does not. Nothing else is affected, and a token made under an administrator account fixes it.

The temperature is right and the rain is nonsense. Nearly every rain sensor reports the total so far, and WeeWX has to be told to difference it. That is [StdWXCalculate] and the driver says so at startup if it is not set.

More than one station

This is one station among however many others. Which of them fills outTemp, and where the rest of their readings go, is in Several stations.