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, 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:

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:

   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.

   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:

   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:

   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:

[[[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 more than 5.0 kWh of energy was consumed. The argument is a ValueTuple.