Polled sources

Sensors this driver goes and asks

Some hardware cannot be pointed anywhere. There is no field for a server address, because it was never meant to send anything: it sits on your network and answers whoever asks. A PurpleAir is like this, and so is a Davis AirLink, and so is most of what is sold as having a local API.

An Ecowitt gateway is here for the other reason. It can be pointed at a server, and this driver reads it that way too; it also answers a protocol of its own, and reading it that way means nothing has to be set on the console at all. See Ecowitt gateway API.

An Ambient console is here for a third reason. It can be pointed at a server, but the awnet app has room for one and older models have room for none, so a console whose slot is already taken cannot be pointed here at all. Its readings are on ambientweather.net either way, and the driver reads them back from there. That is also the only way to read a station that is not on your network: a second home, a relative's garden. See Ambient Weather (ambientweather.net).

So the driver asks. Every so often it fetches the sensor's own answer, reads it the same way it reads an upload, and records it. From there nothing is different: the same field map, the same channels, the same rule about which station owns which column.

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

Add a station there, pick the sensor from the list under This machine reads it, type its address, and press the button. It is asked once before anything is saved, so a wrong address is a message on the screen rather than something to undo. See Web interface.

The whole of it

[UltimatePush]
    [[polling]]
        [[[air]]]
            address = 1.2.3.4
            protocol = purpleair
            interval = 60
            role = extra
            channel = 3

That is a finished station. There is no second block naming it under [[stations]], and there is nothing waiting to be let in.

This is the one kind of station that needs nothing recognised. Everything else that arrives here had to be identified first, because an upload turns up on a port and something has to say which console sent it. Nothing has to say that here: the driver asked an address it was given, and whatever answered is what it asked. That is why the block is short.

air is the station's name, and you choose it. It is what the log and the web interface call this sensor.

What each line is

address is where the sensor is on your network. The protocol knows what to ask it for, so the address is enough. Give the sensor a fixed address in your router, under whatever the router calls a reserved lease: one that changes is one that stops being found.

protocol says how to read the answer. Naming it here also switches it on; there is nothing to add to protocols in the section above.

interval is seconds between one answer and the next question. Sixty is sensible. Five is the shortest allowed, and asking faster than a sensor measures buys nothing.

role and channel are the same as for any other station, and mean the same thing. See Several stations.

url can replace address for a sensor that answers somewhere unusual. Then protocol is still needed, to say how to read what comes back.

timeout is how long to wait for an answer, in seconds. Ten by default, which is long for anything on your own network.

Which sensors

Protocol	Hardware	Page
purpleair	PurpleAir PA-II, PA-II-SD and PA-I	PurpleAir
airlink	Davis AirLink	Davis AirLink
ecowitt_gateway	Ecowitt GW1000, GW1100, GW1200, GW2000, GW3000, WH2650, WN1900	Ecowitt gateway API
ambient_cloud	any Ambient console on an ambientweather.net account	Ambient Weather (ambientweather.net)
homeassistant	anything Home Assistant can read	Home Assistant

The last one is not a make of hardware. Home Assistant has an integration for very nearly every sensor sold, so if it can read your thermometer, this can record it: an Aqara in the bedroom, a soil probe on Zigbee, the sensor inside a Shelly or a Tado. It needs two things no other source here does, an address and a token, and it has a page of its own.

Adding another is a catalog and a protocol class, both small, and the asking is already written. See New sensors.

Trying it without the hardware

A sensor that has to be asked is the one kind of station nobody can try before they own it. A console that uploads can be imitated with curl and hardware on a cable has the WeeWX simulator; there is nothing to ask when there is nothing there.

So there is one of each to ask:

python -m user.ultimatepush --fake-purpleair

python -m user.ultimatepush --fake-airlink

python -m user.ultimatepush --fake-gw1000

python -m user.ultimatepush --fake-homeassistant

python -m user.ultimatepush --fake-ambient-cloud

The first two answer on ports 8081 and 8082, the gateway on 45000 and the Home Assistant on 8123, which are the ports the real ones use. The Ambient one answers on 8124, which is nobody's real port: that service is on the internet rather than on your network, so a source is pointed at the fake with a url line instead of an address. All five send readings that move. Point a source at 127.0.0.1:8081 and the whole of this page can be walked through before the real sensor arrives.

The last one insists on a token, the way the real one does, and prints the block to copy when it starts. It has two devices, one outdoors and one indoors, and three sensors that are not reporting a number: one unavailable, one unknown, and one whose reading is an hour old. None of those three should reach the database, and watching that happen is the point of them.

Where the readings go

An air quality sensor sends particle counts nothing else sends, and a temperature that fights with your weather station for outTemp.

The particle counts have nowhere to collide, so they arrive as themselves: pm1_0, pm2_5, pm10_0, and more besides. A PurpleAir has two laser counters and sends both, and an AirLink sends averages over an hour, three hours and a day beside the current reading. WeeWX has columns for the first three; the rest need adding, and Database columns says how.

The temperature and humidity are the reason for role = extra. On a PurpleAir the thermometer is inside the housing beside electronics that are warm and reads several degrees above the air outside. As an extra station it goes to extraTemp3 rather than outTemp, where nothing mistakes it for the air temperature.

None of that applies to a gateway. It is the weather station, so it is the main one and its temperature is the outdoor temperature; leave role out. The example blocks on this page are an air quality sensor's, and the gateway's own page has its own.

When it stops recording

Nothing answers. The log says so once, when it starts failing, and then stays quiet rather than writing a line a minute for a sensor that is away for the winter. It keeps trying, waiting longer between tries up to five minutes, and says so again when the sensor comes back. Look at where the log starts rather than where it ends.

Something answers and it is refused. Whatever is at that address is not what the protocol line says. Usually the address moved and now belongs to something else.

It answers and records nothing. Its readings are all ones another station already fills. That is the ordinary rule about columns and not something particular to polling; see Several stations.

What it costs

One thread per source, asleep between questions. A sensor that has been unplugged holds up only itself.

Nothing is opened on your network. The driver makes the connection, so a polled source needs no port, no path and no secret, and nothing about it is reachable from outside this machine.