-
Notifications
You must be signed in to change notification settings - Fork 297
Weewx Driver Development Tips
When building a new driver start with the section Porting to new hardware in the Customizing Guide. You can familiarize yourself with the architecture and basic requirements there. You can use the fileparse driver as a starting point.
Custom drivers/extensions should not be installed in the weewx/drivers
directory. Instead they ideally should be installed as extensions that are
installed using weectl extension
. To accomplish this setup your source files
in the following fashion.
-
bin/user/mydriver.py
- This is the driver file itself -
install.py
- This is the extension installer, see the next section for details. -
README.md
- Not mandatory but super helpful for your users. You should document your module, options and config here. -
LICENSE
- Not mandatory but recommended. The open source license of your choice goes here.
The install.py
file implements a loader and a class that inherits from
ExtensionInstaller
. A basic skeleton for your file might look like the one
below.
from weecfg.extension import ExtensionInstaller
def loader():
return YOURDRIVERInstaller()
class YOURDRIVERInstaller(ExtensionInstaller):
def __init__(self):
super(YOURDRIVERInstaller, self).__init__(
version=".1",
name='YOURDRIVER',
description='YOUR DRIVER installer',
author="YOUR NAME",
author_email="YOUR@EMAIL.ADDY",
files=[('bin/user', ['bin/user/YOURDRIVER.py'])],
config={
'YOURDRIVER': {
'driver' : 'bin.user.YOURDRIVER,
'config_param_1': 'YOUR_VALUE_1',
'config_param_2': 'YOUR_VALUE_2',
'config_param_3': 'YOUR_VALUE_3'
},
}
)
As you can see above the class sets some basic metadata about your driver. Pay special attention to the files and config values.
- The files tuple identifies what files are needed in what directory. More than one file is supported in the file list but usually you'll have a single file.
- The config dictionary sets up your configuration parameters. At a minimum
you'll want the stanza to be named with your driver's name and the driver
parameter should be set to
bin.user.YOURDRIVER
withYOURDRIVER
being your driver's name. This will be used byweectl
.
To install your driver you can either download a zip (most easily done using the
github download as zip button), tgz or a directory containing your driver files.
I.e. a clone of your repo if you're using github. To install your driver use
the weectl
command like so.
weectl extension install YOURDRIVER.zip
If all goes well your driver will be installed and your config stanza be added
to the weewx.conf
. Note that the stanza for your driver will appear at the
bottom of the weewx.conf
file!
At this point you should set any custom configuration values and then run weectl
to start using your driver. After editing you'll want to run the command below.
weectl station reconfigure --driver=YOURDRIVER --no-prompt
The --no-prompt
flag tells weectl
not to ask you about all the key setup
settings like latitude/longitude etc... After this you should be able to
inspect your weewx.conf
, see that the station_type
has been set to your driver
and the driver configuration stanza will be right below the [Station]
stanza
for handy tweaking and debugging.
The documentation contains more information about weectl extension
.
-
Setting default values at installation time, rather than editing the
weewx.conf
file, is left as an exercise for the reader. It seems like it should be possible via theinstall.py
file. If anyone finds an implementation like this I recommend they document how it works in this wiki page. -
When installing the extension the driver's stanza is unceremoniously dumped to the end of the
weewx.conf
file. Theweectl
utility knows how to re-order them correctly but that doesn't seem to yet be part of theweectl
code. This can be confusing if you're assuming there's a way to resetstation_type
and place the driver stanza in the "normal" location prior to runningweectl
. -
It's possible to preserve comments and create a cleaner doc string version of your config stanza. To do so you need to put the raw stanza in a doc string and then leverage the ConfigObject library to parse it and hand it to your driver's extension class. An example for this would be lovely in this page but I've yet to accomplish it so it remains a todo at the time of this writing.