mirror of
https://github.com/weewx/weewx.git
synced 2026-04-17 16:16:56 -04:00
318 lines
12 KiB
Markdown
318 lines
12 KiB
Markdown
# [StdReport]
|
|
|
|
This section is for configuring the `StdReport` service, which controls what
|
|
reports are to be generated. While it can be highly customized for your
|
|
individual situation, this documentation describes the section as shipped in
|
|
the standard distribution.
|
|
|
|
Each report is represented by a subsection, marked with double brackets (e.g.,
|
|
`[[MyReport]]`). Any options for the report should be placed under it. The
|
|
standard report service will go through the subsections, running each report
|
|
in order.
|
|
|
|
WeeWX ships with the following subsections:
|
|
|
|
| subsection | Description |
|
|
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| [[SeasonsReport]] | A full-featured single-page skin. Statistics and plots are revealed by touch or button press. |
|
|
| [[SmartphoneReport]] | A skin formatted for smaller screens, with a look-and-feel reminiscent of first-generation Apple iPhone. |
|
|
| [[MobileReport]] | A static skin formatted for very small screens, with a look-and-feel reminiscent of WindowsCE or PalmOS. |
|
|
| [[StandardReport]] | The original skin that shipped for many years as the default report. It uses static HTML and images, and requires few resources to generate and display. |
|
|
| [[FTP]] | No presentation elements. Uses the reporting machinery to transfer files to a remote server using FTP. |
|
|
| [[RSYNC]] | No presentation elements. Uses the reporting machinery to transfer files to a remote server using rsync. |
|
|
|
|
Order matters. The reports that generate HTML and images, that is,
|
|
`SeasonsReport`, `SmartphoneReport`, `MobileReport`, and `StandardReport`,
|
|
are run _first_, then the reports that move them to a webserver, `FTP` and
|
|
`RSYNC`, are run. This insures that report generation is done before the
|
|
results are sent off.
|
|
|
|
Details for how to customize reports are in the section
|
|
[*Customizing reports*](../../custom/custom-reports.md), in the
|
|
*Customization Guide*.
|
|
|
|
#### SKIN_ROOT
|
|
|
|
The directory where the skins live.
|
|
|
|
If a relative path is specified, it is relative to
|
|
[`WEEWX_ROOT`](general.md#weewx_root).
|
|
|
|
#### HTML_ROOT
|
|
|
|
The target directory for the generated files. Generated files and images wil
|
|
l be put here.
|
|
|
|
If a relative path is specified, it is relative to
|
|
[`WEEWX_ROOT`](general.md#weewx_root).
|
|
|
|
#### log_success
|
|
|
|
If you set a value for `log_success` here, it will override the value set at
|
|
the [top-level](general.md#log_success) and will apply only to reporting.
|
|
In addition, `log_success` can be set for individual reports by putting them
|
|
under the appropriate subsection (*e.g.*, under `[[Seasons]]`).
|
|
|
|
#### log_failure
|
|
|
|
If you set a value for log_failure here, it will override the value set at
|
|
the [top-level](general.md#log_failure) and will apply only to reporting.
|
|
In addition, `log_failure` can be set for individual reports by putting them
|
|
under the appropriate subsection (*e.g.*, under `[[Seasons]]`).
|
|
|
|
#### data_binding
|
|
|
|
The data source to be used for the reports. It should match a binding given
|
|
in section [`[DataBindings]`](data-bindings.md). The binding can be
|
|
overridden in individual reports. Optional. Default is `wx_binding`.
|
|
|
|
#### report_timing
|
|
|
|
This parameter uses a cron-like syntax that determines when a report will be
|
|
run. The setting can be overridden in individual reports, so it is possible
|
|
to run each report with a different schedule. Refer to the separate document
|
|
[_Scheduling report generation_](../../custom/report-scheduling.md) for how
|
|
to control when reports are run. Optional. By default, a value is missing,
|
|
which causes each report to run on each archive interval.
|
|
|
|
## Standard WeeWX reports
|
|
|
|
These are the four reports that are included in the standard distribution of
|
|
WeeWX, and which actually generate HTML files and plots. They all use US
|
|
Customary units by default (but this can be changed by setting the option
|
|
`unit_system`).
|
|
|
|
#### [[SeasonsReport]]
|
|
|
|
#### [[SmartphoneReport]]
|
|
|
|
#### [[MobileReport]]
|
|
|
|
#### [[StandardReport]]
|
|
|
|
They all have the following options in common:
|
|
|
|
#### lang
|
|
|
|
Which language to use. The value can take one of three forms:
|
|
|
|
| Example | Meaning |
|
|
|--------------|---------------------------------------------------------------|
|
|
| `en` | English language |
|
|
| `en_GB` | English language, country Great Britain |
|
|
| `en_GB.utf8` | English language, country Great Britain, locale Great Britain |
|
|
|
|
The language part of the code is as defined in [ISO
|
|
639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
|
|
|
|
This option only works with skins that have been internationalized. All skins
|
|
that ship with WeeWX have been internationalized, but only a handful of
|
|
languages are included. To see which language a skin supports, look in the
|
|
subdirectory `lang` in the skin's directory. For example, if you see a file
|
|
`fr.conf`, then the skin can be localized in French.
|
|
|
|
See the section [_Changing
|
|
languages_](../../../custom/custom-reports/#changing-languages) for more
|
|
details.
|
|
|
|
#### unit_system
|
|
|
|
Which unit system to use with the skin. Choices are `US`, `METRIC`, or
|
|
`METRICWX`. See the reference section [*Units*](../units.md) for definitions of
|
|
these unit systems. Individual units can be overridden. See the section
|
|
[*Changing unit systems*](../../custom/custom-reports.md#changing-unit-systems)
|
|
in the *Customization Guide* for more details.
|
|
|
|
#### enable
|
|
|
|
Set to `true` to enable the processing of this skin. Set to `false` to
|
|
disable. If this option is missing, `true` is assumed.
|
|
|
|
#### skin
|
|
|
|
Where to find the skin. This should be a directory under `SKIN_ROOT`.
|
|
Inside the directory should be any templates used by the skin and a skin
|
|
configuration file, `skin.conf`.
|
|
|
|
#### HTML_ROOT
|
|
|
|
If you put a value for `HTML_ROOT` here, it will override the
|
|
[value](#html_root) directly under `[StdReport]`.
|
|
|
|
|
|
## [[FTP]]
|
|
|
|
While this "report" does not actually generate anything, it uses the report
|
|
machinery to upload files from directory `HTML_ROOT` to a remote webserver.
|
|
It does an incremental update, that is, it only FTPs any files that have
|
|
changed, saving the outgoing bandwidth of your Internet connection.
|
|
|
|
#### enable
|
|
|
|
Set to `true` (the default) to enable FTP. Set to `false` to disable.
|
|
|
|
#### user
|
|
|
|
Set to the username you use for your FTP connection to your web server.
|
|
Required. No default.
|
|
|
|
#### password
|
|
|
|
Set to the password you use for your FTP connection to your web server.
|
|
Required. No default.
|
|
|
|
#### server
|
|
|
|
Set to the name of your web server (*e.g.*, `www.acme.com`). Required.
|
|
No default
|
|
|
|
#### path
|
|
|
|
Set to the path where the weather data will be stored on your webserver
|
|
(*e.g.*, `/weather`). Required. No default.
|
|
|
|
!!! Note
|
|
Some FTP servers require a leading slash ('`/`'), some do not.
|
|
|
|
#### secure_ftp
|
|
|
|
Set to `true` to use FTP (FTPS) over TLS. This is an extension to the FTP
|
|
protocol that uses a Secure Socket Layer (SSL) protocol, not to be confused
|
|
with SFTP, which uses a Secure Socket Shell protocol. Not all FTP servers
|
|
support this. In particular, the Microsoft FTP server seems to do a poor
|
|
job of it. Optional. Default is `false`
|
|
|
|
#### secure_data
|
|
|
|
If a secure session is requested (option `secure_ftp=true`), should we attempt
|
|
a secure data connection as well? This option is useful due to a bug in the
|
|
Python FTP client library. See WeeWx GitHub
|
|
[Issue #284](https://github.com/weewx/weewx/issues/284). Optional. Default
|
|
is `true`.
|
|
|
|
#### reuse_ssl
|
|
|
|
Some FTP servers (notably PureFTP) reuse ssl connections with FTPS.
|
|
Unfortunately, the Python library has a bug that prematurely closes such
|
|
connections. See [https://bit.ly/2Lrywla](https://bit.ly/2Lrywla). Symptom is an
|
|
exception *OSError: [Errno 0]*, or a 425 error ("*425 Unable to build data
|
|
connection: Operation not permitted*"). This option activates a workaround for
|
|
Python versions greater than 3.6. It won't work for earlier versions. Optional.
|
|
Default is `false`.
|
|
|
|
#### port
|
|
|
|
Set to the port ID of your FTP server. Default is `21`.
|
|
|
|
#### passive
|
|
|
|
Set to `1` if you wish to use the more modern, FTP passive mode, `0` if you
|
|
wish to use active mode. Passive mode generally works better through firewalls,
|
|
but not all FTP servers do a good job of supporting it. See [Active FTP vs.
|
|
Passive FTP, a Definitive Explanation](https://slacksite.com/other/ftp.html)
|
|
for a good explanation of the difference. Default is `1` (passive mode).
|
|
|
|
#### max_tries
|
|
|
|
WeeWX will try up to this many times to FTP a file up to your server before
|
|
giving up. Default is `3`.
|
|
|
|
#### ftp_encoding
|
|
|
|
The vast majority of FTP servers send their responses back using UTF-8
|
|
encoding. However, there are a few oddballs that respond using Latin-1. This
|
|
option allows you to specify an alternative encoding.
|
|
|
|
#### ciphers
|
|
|
|
Some clients require a higher cipher level than the FTP server is capable of
|
|
delivering. The symptom is an error something like:
|
|
|
|
ssl.SSLError: [SSL: DH_KEY_TOO_SMALL] dh key too small (_ssl.c:997)`
|
|
|
|
This option allows you to specify a custom level. For example, in this case,
|
|
you might want to specify:
|
|
|
|
``` ini
|
|
ciphers='DEFAULT@SECLEVEL=1'
|
|
```
|
|
|
|
However, if possible, you are always better off upgrading the FTP server.
|
|
|
|
|
|
## [[RSYNC]]
|
|
|
|
While this "report" does not actually generate anything, it uses the report
|
|
machinery to upload files from directory `HTML_ROOT` to a remote webserver
|
|
using [rsync](https://rsync.samba.org/). Fast, efficient, and secure, it does
|
|
an incremental update, that is, it only synchronizes those parts of a file
|
|
that have changed, saving the outgoing bandwidth of your Internet connection.
|
|
|
|
If you wish to use rsync, you must configure passwordless ssh using
|
|
public/private key authentication from the user account that WeeWX runs, to
|
|
the user account on the remote machine where the files will be copied.
|
|
For details on how to do so, see the [wiki](https://github.com/weewx/weewx/wiki/rsync-setup).
|
|
|
|
#### enable
|
|
|
|
Set to `true` (the default) to enable rsync. Set to `false` to disable.
|
|
|
|
#### server
|
|
|
|
Set to the name of your server. This name should appear in your `.ssh/config`
|
|
file. Required. No default
|
|
|
|
#### user
|
|
|
|
Set to the ssh username you use for your rsync connection to your web server.
|
|
The local user that WeeWX runs as must have passwordless ssh
|
|
configured for _user@server_. Required. No default.
|
|
|
|
#### path
|
|
|
|
Set to the path where the weather data will be stored on your webserver
|
|
(_e.g._, `/var/www/html/weather`). Make sure `user` has write privileges in
|
|
this directory. Required. No default.
|
|
|
|
#### port
|
|
|
|
The port to use for the ssh connection. Default is to use the default port for
|
|
the `ssh` command (generally 22).
|
|
|
|
#### delete
|
|
|
|
Files that don't exist in the local report are removed from the remote
|
|
location.
|
|
|
|
!!! warning
|
|
USE WITH CAUTION! If you make a mistake in setting the path, this can
|
|
cause unexpected files to be deleted on the remote server.
|
|
|
|
Valid values are `1` to enable and `0` to disable. Required. Default is `0`.
|
|
|
|
#### rsync_options
|
|
|
|
Use this option to pass on any additional command line options to `rsync`. It
|
|
should be a comma separated list. For example
|
|
|
|
```ini
|
|
rsync_options = --exclude=*.ts, --ipv6
|
|
```
|
|
|
|
This would exclude any Typescript files from the transfer, and indicate that you
|
|
would prefer to use IPv6.
|
|
|
|
|
|
## [[Defaults]]
|
|
|
|
This section defines default values for all reports. You can set:
|
|
|
|
* The unit system to be used
|
|
* Overrides for individual units
|
|
* Which language to be used
|
|
* Number and time formats
|
|
* Labels to be used
|
|
* Calculation options for some derived values.
|
|
|
|
See the section [*Processing order*](../../custom/custom-reports.md#processing-order) in the *Customization Guide* for more details.
|