mirror/weewx
1
0
Fork 0
mirror of https://github.com/weewx/weewx.git synced 2026-04-19 00:56:54 -04:00
Code Issues Packages Projects Releases Wiki Activity

Working on documentation of wee_extension

Browse Source
This commit is contained in:
Tom Keffer
2015-04-30 13:40:52 -07:00
parent d500a0c3aa
commit 79105e4e39
3 changed files with 243 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
TODO.txt
View File

@@ -1,6 +1,10 @@
TODO: items for the next release; complete list is at github
-------------------------------------------------------------------------------
Uninstalling a non-existent extension gives a useless error.
The option BIN_ROOT is getting accidentally injected into the config file.
Running wee_config without a command, for example,
wee_config --driver=something
should either return an error, or indicate that it did nothing.

123
docs/customizing.htm
View File

@@ -4224,8 +4224,127 @@ mv weewx.sdb_new weewx.sdb</pre>
high-level description. If you're game, give it a try — I'm happy to
help you out!</p>
<h1 id="extensions">Extensions</h1>
<p>Now that you have made some customizations, you might want to share
<h1 id="extensions">Extensions</h1>
<p>
A key feature of <span class="code">weewx</span> is its ability to be
extended by installing 3rd party <em>extensions</em>, using a simple
tool. Take a look at the <a
href="https://github.com/weewx/weewx/wiki"><span class="code">weewx</span>
wiki</a> for a sampling of some of the extensions that are available.
</p>
<h2>
The utility <span class="code">wee_extension</span>
</h2>
<p>
The utility <span class="code">wee_extension</span> is used to add an
extension. It's worth running with the <span class="code">--help</span>
option to see how it is used:
</p>
<pre class="tty">
<b>cd /home/weewx
./bin/wee_extension --help</b></pre>
<p>This results in:</p>
<pre class="tty">
Usage: wee_extension --help
wee_extension --list
[CONFIG_FILE|--config=CONFIG_FILE]
wee_extension --install=(filename|directory)
[CONFIG_FILE|--config=CONFIG_FILE]
[--tmpdir==DIR] [--dry-run] [--verbosity=N]
wee_extension --uninstall=EXTENSION
[CONFIG_FILE|--config=CONFIG_FILE]
[--verbosity=N]
Install, list, and uninstall extensions to weewx.
Commands:
--list: Show installed extensions.
--install: Install the specified extension.
--uninstall: Uninstall the specified extension.
Options:
-h, --help show this help message and exit
--list Show installed extensions.
--install=FILENAME|DIRECTORY
Install the extension contained in FILENAME or
DIRECTORY. FILENAME must be an archive that contains a
packaged extension such as pmon.tar.gz. DIRECTORY
must be a packaged extension.
--uninstall=EXTENSION
Uninstall the extension with name EXTENSION.
--config=CONFIG_FILE Use configuration file CONFIG_FILE.
--tmpdir=DIR Use temporary directory DIR.
--bin-root=BIN_ROOT Look in BIN_ROOT for weewx executables.
--dry-run Print what would happen but do not do it.
--verbosity=N How much status to display, 0-3</pre>
<h3>Installing an extension</h3>
<p>
Let's try installing a simple extension, <a
href="https://github.com/weewx/weewx/wiki/cmon"><em>cmon</em></a>,
used to monitor your computer.
</p>
<p>
First download it. You can either do this from the link given in the
wiki, or by using <span class="code">wget</span> (which you may have
to install):
</p>
<pre class="tty">
<b>wget -P /var/tmp http://lancet.mit.edu/mwall/projects/weather/releases/weewx-cmon-0.7.tgz</b></pre>
<p>
This will put the tarfile <span class="code">weewx-cmon-0.7.tgz</span>
in the directory <span class="code">/var/tmp</span>.
</p>
<p>Now install the extension:</p>
<pre class="tty">
<b>cd /home/weewx</b>
<b>./bin/wee_extension --install=/var/tmp/weewx-cmon-0.7.tgz</b>
Request to install '/var/tmp/weewx-cmon-0.7.tgz'
Extracting from tarball /var/tmp/weewx-cmon-0.7.tgz
Added new service user.cmon.ComputerMonitor to process_services
Saving installer file to /home/weewx/bin/weecfg/user/installer/cmon
Saved configuration dictionary. Backup copy at /home/weewx/weewx.conf.20150430130322
Finished installing extension '/var/tmp/weewx-cmon-0.7.tgz'</pre>
<p>The installer has done a number of things for you:</p>
<ol>
<li>It put a new skin, <span class="code">cmon</span>, in the <span
class="code">skins</span> subdirectory;
</li>
<li>It put a new service, <span class="code">user.cmon.ComputerMonitor</span>,
in the list of services to be run by <span class="code">weewx</span>;</li>
<li>It defined a new database, <span class="code">cmon_sqlite</span>,
and a binding, <span class="code">cmon_binding</span>, to that database;
</li>
<li>It added a top-level "stanza" <span class="code">[ComputerMonitor]</span>
to your configuration file <span
class="code">weewx.conf</span>, that specifies the data binding <span
class="code">cmon</span> is to use.
</li>
<li>And, finally, it saved the details of how the extension was installed so you can
remove it later, should you choose to do so;</li>
</ol>
<h3>Listing installed extensions</h3>
<p>The utility <span class="code">wee_extension</span> can tell you which extensions
you have installed:</p>
<pre class="tty"><b>./bin/wee_extension --list</b>
cmon</pre>
<p>You can see it lists the extension we just installed, <span class="code">cmon</span>.</p>
<h3>Removing extensions</h3>
<p>Finally, you can remove an extension using the same tool:</p>
<pre class="tty"><b>./bin/wee_extension --uninstall=cmon</b>
<b>./bin/wee_extension --list</b>
No extensions installed</pre>
<h2>Creating extensions</h2>
<p>Now that you have made some customizations, you might want to share
those changes with other <span class='code'>weewx</span> users. Put
your customizations into an extension to make installation, removal,
and distribution easier.</p>

171
docs/usersguide.htm
View File

@@ -1066,22 +1066,27 @@ Version: 3.1.0
<a href='setup.htm'><span class="code">setup.py</span> instructions</a>.
</p>
<h1 id="wee_config_utility">The utility <span class="code">wee_config</span></h1>
<p>
When you install <span class="code">weewx</span> for the first time,
the installation process will prompt you for the most essential
options, such as the type of hardware you are using, latitude,
longitude, or altitude. But, what if you want to change these later? You
could go into the definitive configuration file, <span class="code">weewx.conf</span>,
which is described in detail in the <a href="#configuring">next
section</a>, but it's a big file with lots of nuances. Alternatively, if
you're just changing something simple, you may be able to
use the utility <span class="code">wee_config</span>.
</p>
<p>Before starting, it's worth running the utility with the <span class="code">--help</span> option to see how
it is used:</p>
<pre class="tty">wee_config --help</pre>
<p>This results in:</p>
<h1 id="wee_config_utility">The utility <span class="'code">wee_config</span></h1>
<p>
When you install <span class="code">weewx</span> for the first time,
the installation process will prompt you for the most essential
options, such as the type of hardware you are using, latitude,
longitude, or altitude. But, what if you want to change these later?
In particular, what if you want to change device drivers? You could
edit the definitive configuration file, <span class="code">weewx.conf</span>,
by hand &mdash; described in detail in the <a href="#configuring">next section</a>
&mdash; but it's a big file with lots of nuances. Alternatively, if
you're just changing something simple, you may be able to use the
utility <span class="code">wee_config</span>.
</p>
<p>
Before starting, it's worth running it with the <span
class="code">--help</span> option to see how it is used:
</p>
<pre class="tty">wee_config --help</pre>
<p>This results in:</p>
<pre class="tty">
Usage: wee_config --help
wee_config --version
@@ -1150,22 +1155,37 @@ Options:
--no-backup Do not save a backup of any existing files.
--debug Show diagnostic information while running.</pre>
<p>The utility is pretty good about "guessing" where your configuration
file <span class="code">weewx.conf</span> is, but if you've done an
unusual install, you may have to tell it explicitly. You can either put
the location directly in the command line like this:</p>
<pre class="tty">wee_config /home/weewx/weewx.conf </pre>
<p>or use option <span class="code">--config</span>:</p>
<pre class="tty">wee_config --config=/home/weewx/weewx.conf</pre>
<h2>Changing device drivers</h2>
<p>The most common use for <span class="code">wee_config</span> is to
change device drivers. Say that you originally installed <span class="code">weewx</span>
with the Simulator. Now you've bought a Davis Vantage and you want to switch
to that. Here's how you do it. First, if you don't know the name of the
driver, you can list what is available:</p>
<pre class="tty">wee_config --list-drivers</pre>
<p>This will result in something like this:</p>
<pre class="tty">
<p>
The utility is pretty good about "guessing" where your configuration
file <span class="code">weewx.conf</span> is, but if you've done an
unusual install, you may have to tell it explicitly. You can do this by
either putting the location directly in the command line:
</p>
<pre class="tty">wee_config /home/weewx/weewx.conf </pre>
<p>
or by using option <span class="code">--config</span>:
</p>
<pre class="tty">wee_config --config=/home/weewx/weewx.conf</pre>
<h2>Changing device drivers</h2>
<p>
The most common use for <span class="code">wee_config</span> is to
change device drivers. Say that you originally installed
<span class="code">weewx</span> with the Simulator. Now you've bought a
Davis Vantage and you want to switch to that. Here's how you do it.
First, if you don't know the name of the driver, you can list all the
drivers available in your weewx install:
</p>
<pre class="tty">wee_config --list-drivers</pre>
<p>This will result in something like this:</p>
<pre class="tty">
weewx.drivers.acurite AcuRite 0.16
weewx.drivers.cc3000 CC3000 0.8
weewx.drivers.fousb FineOffsetUSB 1.7
@@ -1180,30 +1200,75 @@ weewx.drivers.ws1 WS1 0.19
weewx.drivers.ws23xx WS23xx 0.22
weewx.drivers.ws28xx WS28xx 0.34</pre>
<p>
From this, we can see that the name of the driver is <span
class="code">weewx.drivers.vantage</span>. Now run <span
class="code">wee_config</span>, with the <span class="code">--modify</span>
command, specifying that driver:
</p>
<pre class="tty">wee_config --modify --driver=weewx.drivers.vantage</pre>
<p>
From this list, we can see that the name of the driver is <span
class="code">weewx.drivers.vantage</span>. Now run <span
class="code">wee_config</span>, with the <span class="code">--modify</span>
command, specifying that driver:
</p>
<pre class="tty">wee_config --modify --driver=weewx.drivers.vantage</pre>
<p>
The utility will go through your previously selected options, such as
station description, latitude, longitude, altitude, <i>etc.</i>. Your
previously selected values, <em>including</em> the device driver,
will all be the defaults. So, all you have to do is keep hitting
enter.
</p>
<p>
If this is too much trouble, you can specify the <span class="code">--no-prompt</span>
option:
</p>
<p>
The utility will go through your previously selected options, such as
station description, latitude, longitude, altitude, <i>etc.</i>. Your
previously selected values, <em>including</em> the specified device driver,
will all be the defaults. So, all you have to do is keep hitting
enter. This is what it looked like when I switched from the simulator
to the Vantage driver:
</p>
<pre class="tty">
<b>$ cd /home/weewx</b>
<b>$ ./bin/wee_config --modify --driver=weewx.drivers.vantage </b>
Using configuration file /home/weewx/weewx.conf
Enter a brief description of the station, such as its location. For example:
Santa's Workshop, North Pole
description [Hood River, Oregon]:
Specify altitude, with units 'foot' or 'meter'. For example:
35, foot
12, meter
altitude [700, foot]:
Specify latitude in decimal degrees, negative for south.
latitude [45]:
Specify longitude in decimal degrees, negative for west.
longitude [-125]:
Indicate the preferred units for display: 'metric' or 'us'
units [metricwx]:
Installed drivers include:
0) AcuRite (weewx.drivers.acurite)
1) CC3000 (weewx.drivers.cc3000)
2) FineOffsetUSB (weewx.drivers.fousb)
3) Simulator (weewx.drivers.simulator)
4) TE923 (weewx.drivers.te923)
5) Ultimeter (weewx.drivers.ultimeter)
6) Vantage (weewx.drivers.vantage)
7) WMR100 (weewx.drivers.wmr100)
8) WMR200 (weewx.drivers.wmr200)
9) WMR9x8 (weewx.drivers.wmr9x8)
10) WS1 (weewx.drivers.ws1)
11) WS23xx (weewx.drivers.ws23xx)
12) WS28xx (weewx.drivers.ws28xx)
choose a driver [6]:
Specify the hardware interface, either 'serial' or 'ethernet'.
If the station is connected by serial, USB, or serial-to-USB
adapter, specify serial. Specify ethernet for stations with
WeatherLinkIP interface.
type [serial]:
Specify a port for stations with a serial interface, for
example /dev/ttyUSB0 or /dev/ttyS0.
port [/dev/ttyUSB0]:
Saved backup to /home/weewx/weewx.conf.20150430084525
Saved configuration to /home/weewx/weewx.conf
</pre>
<pre class="tty">wee_config --modify --driver=weewx.drivers.vantage --no-prompt</pre>
<p>
If this is too much trouble, you can specify the <span class="code">--no-prompt</span>
option:
</p>
<p>This will accept all the defaults, including your new device
driver, without asking for any input.</p>
<pre class="tty">wee_config --modify --driver=weewx.drivers.vantage --no-prompt</pre>
<p>This will accept all the defaults, including your new device
driver, without asking for any input.</p>
<h1 id="configuring">Configuring <span class="code">weewx</span></h1>