A new methodology for defining and displaying charts has been implemented starting with Version 1.0 of the Belchertown WeeWX skin. This capability provides significantly increased flexibility in decided what graphs to display and to customized them. To achieve this flexibility and still allow settings to be retained across version upgrades, a new file is being used to define the graphs displayed on the web pages output by the Belchertown skin.

This file, graphs.conf, is located in the skins/Belchertown directory and can be modified to define the graphs and charts displayed on the main web page as well as the Today, Week, Month and Year "Graphs" pages.

Although specifying and defining the graphs and charts displayed can seem complex at first, the good news is that even if graphs.conf does not exist, a default set of graphs will be displayed. Editing graphs.conf, though, will allow you to define the charts shown, their order, and their appearance. The following sections of this document will describe:

1. Belchertown Graphs Quick Start Guide
2. Capabilities of the new charting methodology built into Belchertown
3. The key files used for defining plots
4. The structure of the graphs.com file
5. The syntax used to define the plots displayed
6. Examples of graph definitions
7. Some Tips
8. How to ask for help if you encounter problems

The Belchertown skin charting system is extremely powerful and flexible. However it is set up so that upon installation of the skin, a set of standard graphs will automatically be generated. If you don't want any graphs generated (not sure why you'd want to do that 😕), just add highcharts_enabled = 0 in the [[Belchertown]] [[[Extras]]] stanza of weewx.conf.

To enable changing the specific observations graphed, their order or details such as type of plot or color of the lines on the charts shown, first make a copy of graphs.conf.example and name it graphs.conf. This can be done by typing sudo cp graphs.conf.example graphs.conf while in the skins/Belchertown directory.

The graphs.conf.example (and graphs.conf copy of it) have a number of comments at the beginning of the file describing the layout and structure of the file, as well as some of the options you can specify within it.

If you make a mistake changing items in the graphs.conf file, you may end up with no graphs being generated. In this case, if you can't locate the error causing the issue, you can always just delete the file and make a fresh copy of it from graphs.conf.example.

1. Define the timeframe for the graph so it will begin either a specific number of seconds prior to current time, or to start at the beginning of the current day, week, month or year.
2. Choose the order of the graphs displayed.
3. Define the name of the graph.
4. Choose the observation to be plotted (any observation stored in the weewx archive database).
5. Plot multiple observations on a single graph.
6. Specify the type of plot that is graphed (line, spline, area, areaspline, scatter, column, etc.).
7. Specify the color of the plotted observation.
8. Specify which y-axis (left or right) is associated with the plotted observation.
9. Display a special radial wind rose plot that shows the percentage of time wind was blowing from each of sixteen directions over the plot's duration.
10. Other specifications such as determining how much of a gap in data will show as a gap in the plotted line, determining which line is on top of others when multiple observations are plotted on a single graph and y-axis minimum and maximum values.

There are 2 new files related to the new graphing capabilities of the Belchertown skin that users need to be aware of. They are graphs.conf.example and graphs.conf. Both are located in the Belchertown skins directory. This is typically /etc/weewx/skins/Belchertown in Linux systems where WeeWX was installed using a package via DEB or RPM. For implementations of WeeWX that used setup.py, the files are located in /home/weewx/skins/Belchertown.

Upon installation, graphs.conf.example is placed in the skins/Belchertown directory. graphs.conf does not exist until the user creates it in order to specify changes to the default graphs which are displayed. It is easiest to make a copy of graphs.conf.example and name it graphs.conf (e.g. by typing sudo cp graphs.conf.example graphs.conf) while in the skins/Belchertown directory. Note: If the graphs.conf file is not present in the skins/Belchertown directory, the default graphs defined in graphs.conf.example are displayed on the Belchertown web pages.

The file structure of both graphs.conf.example and graphs.conf are the same and straight-forward. Comment lines are preceded by the # symbol.

At the beginning of the file are detailed comments outlining the chart types and options, a description of the rainTotal observation, some tips and tricks, and a description of the Settings options available.

Next come the observations and their settings for each of the graphs to be plotted on the four "Graphs" pages: "Today" (including graphs plotted on the main web page); "Week"; "Month"; and "Year". The observations and settings for each page are located under their corresponding section stanza ([day], [week], [month] and [year]).

That's it - pretty clear-cut! Just note that the syntax of the settings must be carefully followed. That syntax is described in the next section of this document.

• First are some global default settings including the aggregate_type. Aggregate_type determines if the observation data is averaged (avg), listed as the maximum value (max), minimum value (min) or summed (sum) over the aggregate_interval. Next are the default plot line colors - 10 of them. Note, the colors are chosen so that they show well whether the skin is in light mode or dark mode. So if you choose to set a particular color for a plot line on a graph (instead of letting Highcharts choose it for you), you should consider using one of the 10 defaults listed.

• Next are each of the four Chart group stanzas listed below [day], [week], [month] and [year]. These must be present and cannot be renamed. Under each of the four Chart group stanzas is a series of lower level stanzas defining the graphs to be plotted and their settings. The syntax of the file is described below:

• Chart group: as noted above, these stanzas [day], [week], [month], [year] must be present. They are actually the names of the json files generated to plot the graphs.

• Chart group level options : if a chart within the group does not specify an option, it’ll inherit this option. As described above, the default options generally will include the time_length covered by the graph and the gapsize which determines how long a period of missing observation data results in a gap in the plotted line.

• Chart ID Name (contained within a double brace stanza[[xxx]]): this is used by highcharts and can be anything we want. I recommend choosing a name that signifies the graph to plotted. In the infographic below, the names "temmplt" and "humplt" are used for denote "temperature plot" and "humidity plot". But any names could have been used.

• Chart-level options: Under the Chart ID Name are the chart-level options that define things such as the graph's title, yAxis parameters, etc.

• Observations to be plotted (contained within a triple brace stanza[[[xxx]]]): these are the observations to graph in the chart. The names are case-sensitive and must match the name of the observation in the archive schema. For example outTemp or inTemp or barometer.

• Observation specific options: Under the Observations to be plotted are specific overrides, such as color, zIndex (which determines which plotted line appears plotted on top of other lines on a multi-line graph) and name of the observation in the legend. If name is omitted, the default weewx name will be applied. For example instead of default “Outside Temperature”, you can specify just “Temperature” with the name option.

The syntax of the stanzas within graphs.conf file must be carefully followed. If the graphs fail to load, check the syntax for errors and revert any errors. If worse comes to worst, delete graphs.conf, ensure that the graphs display with only graphs.conf.example. If so, create a fresh version of graphs.conf by copying graphs.conf.example and try again.

[[windplt]]
    # The combined Wind Chart works best in this configuration
    title = Wind Speed and Direction
    yaxis_min = 0
    [[[windDir]]]
        zIndex = 2
        yAxis = 1
        yaxis_max = 360
        lineWidth = 0
        [[[[marker]]]]
            enabled = true
        [[[[states]]]]
            [[[[[hover]]]]]
                    lineWidthPlus = 0
    [[[windGust]]]
        zIndex = 1
    [[[windSpeed]]]
        type = area

This plot definition has three observations on one graph. the Wind Speed (windSpeed) is plotted below the others (no zIndex specified). Wind Gust (windGust) is plotted on top of Wind Speed (zIndex=1) and Wind Direction is plotted on top of both (zIndex=2).

Additionally Wind direction is associated with the right vertical axis (yAxis=1). That axis has a set maximum of 360 degrees (yaxis_max = 360) which translate to N. So wind direction goes from North through all directions and returning to North. The other Wind direction settings are needed because it is a scatter plot without connecting lines.

Wind Gust and Wind Speed are associated with the left vertical axis (no yAxis is specified). Wind speed is rendered as an area plot. Here's an example of how the plot specified by the settings above looks:

[[roseplt]]
    title = Wind Rose
    [[[windRose]]]

A Wind Rose is a special graph that displays wind speed and direction over the period of time chosen. As you see above it only needs a title and the observation type [[[windRose]]]. A Wind Rose is displayed as a polar chart with wedges designating the wind direction around the compass. The length and color of the wedges represent the percentage of time each range of the wind speeds was blowing from a specific direction. Hovering the mouse over the Wind Rose will display the data. This is an example Wind Rose with the mouse being hovered over the NNE direction to show the details of wind from that direction.

• Caution! The more charts you have, the slower things can become. This is especially true for graphs defined beneath the [year] Chart Group (graphs which are displayed on the Graphs YEAR page). Charts are interactive and have to be generated from the database on every archive interval. This could result in large file sizes that are generated, and that your website visitors have to download. You're welcome to customize as many charts as you want, but be warned things could slow down if you do too much! The defaults in this skin have proven to be a good baseline for the number of charts and options without overwhelming your system.

• A line plot (like windSpeed) and a scatter plot (like windDir) cannot exist on the same chart and have working tooltips (the bubble that pops up). But according to this post, you can "trick" highcharts into doing almost the same thing. https://stackoverflow.com/a/43992380/1177153. However the graph which has windSpeed and windDir inside graphs.conf.example utilize line charts. The line chart for windDir has the line width removed, so it appears as a scatter chart. I have been referring to this trick as a line-as-scatter.

• When you specify a color for an observation, try choosing a color from this list first. They tend to look good both in light mode and in dark mode. They are the default colors if you allow the skin to choose the colors. Note: Color names are mine and not official.

  • #268bd2 - blue
  • #90ed7d - light green
  • #f7a35c - tan-brown
  • #d33682 - magenta
  • #8085e9 - light purple
  • #e4d354 - yellow-green
  • #f15c80 - pink
  • #8085e8 - purple-blue
  • #8d4653 - brick
  • #91e8e1 - aqua

• Special rainTotal Observation Type: The built in "rain" observation actually counts "bucket tips". The chart generated for this observation will show when the bucket tipped and that's all. Using the special built in "rainTotal" observation - unique to Belchertown - will increment those bucket tips across the graph's time period, showing you the total rain for that time period.

• It is possible to specify different plots (and/or plot definitions) on the Belchertown front page than those on the Today Graphs page. For instance the front page can show plots since midnight of the current day, while the Today Graphs page can show those same (or different) plots with data from the past 24 hours. To do this, first add highcharts_frontpage_graphgroup = frontpage to the [[Belchertown]] [[[Extras]]] stanza in the weewx.conf file. You then add a new Chart Group section in graphs.conf called [frontpage]. Under this section add the graphs you want plotted on the frontpage with their associated options.

• Similarly to the above, a plot can be added to any Belchertown page that supports .inc files (e.g. Records page, About page and the home page index_hooks)! For example let's work on the About page. To do this, add a new Chart Group section in graphs.conf called [about] and add one or more plot definitions there. Then open your about.inc file and at the top enter this: <script type='text/javascript'>showChart("about");</script>. Then within the content of your About page, you would place a line like this where you want the chart to appear: <div id="**YOUR-CHART-ID**"></div>. Replace YOUR-CHART-ID with the Chart ID name (or names) that you gave the chart under the [about] section in graphs.conf. Repeat this <div> for each custom chart you wish to display, changing the id= with your chart ID. An example can be seen at https://belchertownweather.com/about/

The best place to find help if you encounter problems is the Google weewx-users group (https://groups.google.com/forum/#!forum/weewx-user). This is the official WeeWX place to post questions and request help. The developer of the Belchertown skin is active there as are other WeeWX developers and many knowledgeable users. All are helpful to those who encounter issues with WeeWX implementations. If your issue is caused by a bug you find in the Belchertown skin, or you have a feature request, you can open an Issue on the poblabs/weewx-belchertown GitHub repository (https://github.com/poblabs/weewx-belchertown/issues). If you are testing release candidates of the Belchertown skin, this is probably the best place to note any problems or bugs you encounter.