Skip to content
Rich Bell edited this page Jan 24, 2024 · 19 revisions

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.
Getting Started

    Prerequisites
    Required MQTT information
    Required WeeWX information
    Installing MQTTSubscribe
    Configuring MQTTSubscribe
    Running MQTTSubscribe with WeeWX
    Debugging

Common Options

    Main section
    The [[topics]] section
    The [[[message]]] section
    The [[[topic-name]]] section
    The [[[[field-name]]]] section

Additional Options

    Main section
    The [[tls]] section
    The [[topics]] section
    The [[[topic-name]]] section
    The [[[[field-name]]]] section

Date/Time Processing Options

Experimental Options

Configurator Mode

    Environment setup
    Invocation
    Options

Simulator Mode

    Environment setup
    Invocation
    driver simulation options
    service simulation options

Parser Mode

    Environment setup
    Invocation
    Options

Example individual Configuration

Example json Configuration

    Simple json message
    'Nested' json message
    json message with array

Example keyword Configuration

Example Configuration with multiple types

Example unit and unit group customization

FAQ

Debugging
Understanding The log

    Initialization
    MQTT Initialization
    MQTTSubscribeDriver secondary thread processing
    MQTTSubscribeDriver primary thread processing
    MQTTSubscribeService secondary thread processing
    MQTTSubscribeService primary thread processing

Supporting Additional message types
Development Environment
Deprecated Documentation

     Configuring pre 1.6.0
     Options Removed In 2.0.0
     Using test_mqtt.py To Check MQTT
     Running As A driver In Standalone Mode
     Running As A service In Standalone Mode

Clone this wiki locally