mirror of
https://github.com/weewx/weewx.git
synced 2026-04-18 08:36:54 -04:00
136 lines
5.3 KiB
Markdown
136 lines
5.3 KiB
Markdown
# Customizing units and unit groups
|
|
|
|
!!! Warning
|
|
This is an area that is changing rapidly in WeeWX. Presently, new units
|
|
and unit groups are added by manipulating the internal dictionaries in
|
|
WeeWX (as described below). In the future, they may be specified in
|
|
`weewx.conf`.
|
|
|
|
## Assigning a unit group
|
|
|
|
In the section [Customizing the database](database.md), we created a new
|
|
observation type, `electricity`, and added it to the database schema. Now we
|
|
would like to recognize that it is a member of the unit group
|
|
`group_energy` (which already exists), so it can enjoy the labels
|
|
and formats already provided for this group. This is done by extending
|
|
the dictionary `weewx.units.obs_group_dict`.
|
|
|
|
Add the following to our new services file `user/electricity.py`,
|
|
just after the last import statement:
|
|
|
|
``` python
|
|
import weewx
|
|
from weewx.engine import StdService
|
|
|
|
import weewx.units
|
|
weewx.units.obs_group_dict['electricity'] = 'group_energy'
|
|
|
|
class AddElectricity(StdService):
|
|
|
|
# [...]
|
|
```
|
|
|
|
When our new service gets loaded by the WeeWX engine, these few lines
|
|
will get run. They tell WeeWX that our new observation type,
|
|
`electricity`, is part of the unit group `group_energy`.
|
|
Once the observation has been associated with a unit group, the unit
|
|
labels and other tag syntax will work for that observation. So, now a
|
|
tag like:
|
|
|
|
```
|
|
$month.electricity.sum
|
|
```
|
|
|
|
will return the total amount of electricity consumed for the month, in
|
|
Watt-hours.
|
|
|
|
## Creating a new unit group
|
|
|
|
That was an easy one, because there was already an existing group,
|
|
`group_energy`, that covered our new observation type. But, what
|
|
if we are measuring something entirely new, like force with time? There
|
|
is nothing in the existing system of units that covers things like
|
|
newtons or pounds. We will have to define these new units, as well as
|
|
the unit group they can belong to.
|
|
|
|
We assume we have a new observation type, `rocketForce`, which we
|
|
are measuring over time, for a service named `Rocket`, located in
|
|
` user/rocket.py`. We will create a new unit group,
|
|
`group_force`, and new units, `newton` and `pound`.
|
|
Our new observation, `rocketForce`, will belong to
|
|
`group_force`, and will be measured in units of `newton`
|
|
or `pound`.
|
|
|
|
To make this work, we need to add the following to
|
|
`user/rocket.py`.
|
|
|
|
1. As before, we start by specifying what group our new observation
|
|
type belongs to:
|
|
|
|
``` python
|
|
import weewx.units
|
|
weewx.units.obs_group_dict['rocketForce'] = 'group_force'
|
|
```
|
|
|
|
2. Next, we specify what unit is used to measure force in the three
|
|
standard unit systems used by weewx.
|
|
|
|
``` python
|
|
weewx.units.USUnits['group_force'] = 'pound'
|
|
weewx.units.MetricUnits['group_force'] = 'newton'
|
|
weewx.units.MetricWXUnits['group_force'] = 'newton'
|
|
```
|
|
|
|
3. Then we specify what formats and labels to use for `newton`
|
|
and `pound`:
|
|
|
|
``` python
|
|
weewx.units.default_unit_format_dict['newton'] = '%.1f'
|
|
weewx.units.default_unit_format_dict['pound'] = '%.1f'
|
|
|
|
weewx.units.default_unit_label_dict['newton'] = ' newton'
|
|
weewx.units.default_unit_label_dict['pound'] = ' pound'
|
|
```
|
|
|
|
4. Finally, we specify how to convert between them:
|
|
|
|
``` python
|
|
weewx.units.conversionDict['newton'] = {'pound': lambda x : x * 0.224809}
|
|
weewx.units.conversionDict['pound'] = {'newton': lambda x : x * 4.44822}
|
|
```
|
|
|
|
Now, when the service `Rocket` gets loaded, these lines of code
|
|
will get executed, adding the necessary unit extensions to WeeWX.
|
|
|
|
## Using the new units
|
|
|
|
Now you've added a new type of units. How do you use it?
|
|
|
|
Pretty much like any other units. For example, to do a plot of the
|
|
month's electric consumption, totaled by day, add this section to the
|
|
`[[month_images]]` section of `skin.conf`:
|
|
|
|
``` ini
|
|
[[[monthelectric]]]
|
|
[[[[electricity]]]]
|
|
aggregate_type = sum
|
|
aggregate_interval = 1d
|
|
label = Electric consumption (daily total)
|
|
```
|
|
|
|
This will cause the generation of an image `monthelectric.png`,
|
|
showing a plot of each day's consumption for the past month.
|
|
|
|
If you wish to use the new type in the templates, it will be available
|
|
using the same syntax as any other type. Here are some other tags that
|
|
might be useful:
|
|
|
|
| Tag| Meaning |
|
|
|----|------------------------------------------------------------------------------------------------------------------------|
|
|
| `$day.electricity.sum`| Total consumption since midnight |
|
|
| `$year.electricity.sum`| Total consumption since the first of the year |
|
|
| `$year.electricity.max`| The most consumed during any archive period |
|
|
| `$year.electricity.maxsum`| The most consumed during a day |
|
|
| `$year.electricity.maxsumtime`| The day it happened. |
|
|
| `$year.electricity.sum_ge((5000.0, 'kWh', 'group_energy'))`| The number of days of the year where<br/>more than 5.0 kWh of energy was consumed.<br/>The argument is a `ValueTuple`. |
|