Home

Getting started

Prerequisites

A basic understanding of WeeWX and MQTT is required.

A MQTT broker publishing the desired data to one or more topics.

MQTT

First up is to ensure that you can subscribe to the MQTT topics independent of WeeWX and obtain a basic understanding of the data being published.

1. Determine the information is required to subscribe to the MQTT topic(s). Some of the questions to answer are:

   • What is the broker/server name?
   • What is the port to connect to?
   • Is a username/password required?
   • What topics is the data being published to?
   • etc.

2. Test that you can subscribe to the MQTT topic(s). A couple of options are:

   1. mosquitto_sub

      The advantage of using mosquitto_sub, it is a widely used utility and therefore a lot of information can be found on the web.

   2. mqtt_test.py

      The advantabe of using mqtt_test.py is that it can be used to also test the MQTTSubscribe section of the WeeWX configuration.

3. Determine the MQTT message 'type'.

   Currently three message 'types' are supported.

   1. 'individual' - Each field is its own topic and the MQTT message is the value. For example,

      The value 1 is published to a topic of topic/id and the value 26.7 is published to a topic of topic/temp1.

   2. 'json' - The MQTT message is json. The json field/values in the message map to field/values in WeeWx. An example message is,

      {
       "id": 1,
       "temp1": “26.7“
      }
      

   3. 'keyword' - The MQTT message is delimited data of keywords and values. The json field/values in the message map to field/values in WeeWx. An example message is,

      id=1,temp1=26.7
      

WeeWX

Next up is to determine the necessary information to configure MQTTSubscribe

1. Determine if MQTTSubscribe should be run as a driver or service.

   If you have an existing WeeWX installation running and you want to add/augment with it data from MQTT, run MQTTSubscribe as a service. If this will be a new WeeWX installation where the data is being received via MQTT, run MQTTSubscribe as a driver.

2. Determine incoming 'unit system'.

   WeeWX has 3 unit systems. MQTTSubscribe must be configured to use one. The default is US

   • US - U.S. Customary
   • METRICWX - Metric, with rain related measurements in mm and speeds in m/s
   • METRIC - Metric, with rain related measurements in cm and speeds in km/hr

3. Determine what data transformation/conversion needs to be done on the incoming data.

   MQTTTSubscribe supports many types of transformations/conversions of the incoming data.

   • Ignore incoming data.
   • Renaming the incoming name of the field/observation.
   • By default incoming data is converted to type float. MQTTSubscribe supports conversion to int and str types.
   • If all of the incoming data does not belong to the same WeeWX unit system, each field can specify its units.
   • WeeWX expects some data (for example, rain) to be an increment from previous 'readings. If the MQTT data is a running total, MQTTSubscribe can 'convert' into an increment before passing it to WeeWx.
   • And any other required transformations/conversions...

Installation

Follow the instructions to install MQTTSubscribe.

Configuration

Using the information that has been gathered, configure MQTTSubscribe.

Test/Confirm that MQTTSubscribe is running as expected

The easiest is to verify the expected values are displayed in one of WeeWX skins. If it is displaying incorrect data, there are multiple places where an error might have occurred. Some of the most common are:

1. Data is not received from MQTT.
2. Incorrect transformation.
3. Incorrect skin configuration.

The following are some things that can be done to help narrow down where the problem is:

• Run WeeWX directly from the command line. This allows one to see the values in the WeeWX loop packets and archive records. If the values are correct, the problem is probably something in the WeeWX pipeline that runs after MQTTSubscribe. If they are incorrect or missing, the problem is probably related to MQTTSubscribe.
• Query the WeeWX database. If the value is correct in the database, the problem is probably skin related.
• If all else fails, set debug = 1, restart WeeWX, capture the log from startup and ask for help.

Debugging

See, debugging.