Add configuration option to retain MQTT messages (#232)

* Add configuration option to retain MQTT messages

* Docs

README.md

@@ -118,7 +118,7 @@ Options:
                                   ECOWITT2MQTT_DIAGNOSTICS]
   --disable-calculated-data       Disable the output of calculated sensors.
                                   [env var:
-                                  ECOWITT2MQTT_DISABLE_CALCULATE_DATA]
+                                  ECOWITT2MQTT_DISABLE_CALCULATED_DATA]
   -e, --endpoint TEXT             The relative endpoint/path to serve
                                   ecowitt2mqtt on.  [env var:
                                   ECOWITT2MQTT_ENDPOINT, ENDPOINT; default:
@@ -147,6 +147,8 @@ Options:
   --mqtt-port INTEGER             The listenting port of the MQTT broker.
                                   [env var: ECOWITT2MQTT_MQTT_PORT, MQTT_PORT;
                                   default: 1883]
+  --mqtt-retain                   Instruct the MQTT broker to retain messages.
+                                  [env var: ECOWITT2MQTT_MQTT_RETAIN]
   --mqtt-tls                      Enable MQTT over TLS.  [env var:
                                   ECOWITT2MQTT_MQTT_TLS]
   -t, --mqtt-topic TEXT           The MQTT topic to publish device data to.
@@ -173,26 +175,27 @@ Options:
 
 ## Environment Variables
 
-* `ECOWITT2MQTT_BATTERY_OVERRIDE`: a semicolon-delimited list of key=value battery overrides
-* `ECOWITT2MQTT_CONFIG`: a path to a YAML or JSON config file
+* `ECOWITT2MQTT_BATTERY_OVERRIDE`: a semicolon-delimited list of key=value battery overrides (default: `numeric`)
+* `ECOWITT2MQTT_CONFIG`: a path to a YAML or JSON config file (default: `None`)
 * `ECOWITT2MQTT_DEFAULT_BATTERY_STRATEGY`: the default battery config strategy to use (default: `boolean`)
-* `ECOWITT2MQTT_DIAGNOSTICS`: whether to output diagnostics
-* `ECOWITT2MQTT_DISABLE_CALCULATE_DATA`: whether to disable the output of calculated sensors
+* `ECOWITT2MQTT_DIAGNOSTICS`: whether to output diagnostics (default: `false`)
+* `ECOWITT2MQTT_DISABLE_CALCULATE_DATA`: whether to disable the output of calculated sensors (default: `false`)
 * `ECOWITT2MQTT_ENDPOINT`: the relative endpoint/path to serve ecowitt2mqtt on (default: `/data/report`)
 * `ECOWITT2MQTT_HASS_DISCOVERY`: publish data in the Home Assistant MQTT Discovery format Idefault: `false`)
 * `ECOWITT2MQTT_HASS_DISCOVERY_PREFIX`: the Home Assistant discovery prefix to use (default: `homeassistant`)
-* `ECOWITT2MQTT_HASS_ENTITY_ID_PREFIX`: the prefix to use for Home Assistant entity IDs
+* `ECOWITT2MQTT_HASS_ENTITY_ID_PREFIX`: the prefix to use for Home Assistant entity IDs (default: `""`)
 * `ECOWITT2MQTT_INPUT_UNIT_SYSTEM`: the input unit system used by the device (default: `imperial`)
 * `ECOWITT2MQTT_MQTT_BROKER`: the hostname or IP address of an MQTT broker
 * `ECOWITT2MQTT_MQTT_PASSWORD`: a valid password for the MQTT broker
 * `ECOWITT2MQTT_MQTT_PORT`: the listenting port of the MQTT broker (default: `1883`)
-* `ECOWITT2MQTT_MQTT_TLS`: publish data via MQTT over TLS
+* `ECOWITT2MQTT_MQTT_RETAIN`: whether to instruct the MQTT broker to retain messages (default: `false`)
+* `ECOWITT2MQTT_MQTT_TLS`: publish data via MQTT over TLS (default: `false`)
 * `ECOWITT2MQTT_MQTT_TOPIC`: the MQTT topic to publish device data to
 * `ECOWITT2MQTT_MQTT_USERNAME`: a valid username for the MQTT broker
 * `ECOWITT2MQTT_OUTPUT_UNIT_SYSTEM`: the unit system to use in output (default: `imperial`)
 * `ECOWITT2MQTT_PORT`: the port to serve ecowitt2mqtt on (default: `8080`)
-* `ECOWITT2MQTT_RAW_DATA`: return raw data (don't attempt to translate any values)
-* `ECOWITT2MQTT_VERBOSE`: increase verbosity of logged output
+* `ECOWITT2MQTT_RAW_DATA`: return raw data (don't attempt to translate any values) (default: `false`)
+* `ECOWITT2MQTT_VERBOSE`: increase verbosity of logged output (default: `false`)
 
 ## Configuration File
 
@@ -213,6 +216,7 @@ input_unit_system: imperial
 mqtt_broker: 127.0.0.1
 mqtt_password: password
 mqtt_port: 1883
+mqtt_retain: false
 mqtt_tls: false
 mqtt_topic: Test
 mqtt_username: user
@@ -241,6 +245,7 @@ verbose: false
   "mqtt_broker": "127.0.0.1",
   "mqtt_password": "password",
   "mqtt_port": 1883,
+  "mqtt_retain": 1883,
   "mqtt_tls": false,
   "mqtt_topic": "Test",
   "mqtt_username": "user",

ecowitt2mqtt/cli.py

@@ -21,6 +21,7 @@
     ENV_MQTT_BROKER,
     ENV_MQTT_PASSWORD,
     ENV_MQTT_PORT,
+    ENV_MQTT_RETAIN,
     ENV_MQTT_TLS,
     ENV_MQTT_TOPIC,
     ENV_MQTT_USERNAME,
@@ -154,6 +155,12 @@ def main(  # pylint: disable=too-many-arguments,too-many-locals
         envvar=[ENV_MQTT_PORT, LEGACY_ENV_MQTT_PORT],
         help="The listenting port of the MQTT broker.",
     ),
+    mqtt_retain: bool = typer.Option(
+        False,
+        "--mqtt-retain",
+        envvar=[ENV_MQTT_RETAIN],
+        help="Instruct the MQTT broker to retain messages.",
+    ),
     mqtt_tls: bool = typer.Option(
         False,
         "--mqtt-tls",

ecowitt2mqtt/config.py

@@ -20,6 +20,7 @@
     CONF_MQTT_BROKER,
     CONF_MQTT_PASSWORD,
     CONF_MQTT_PORT,
+    CONF_MQTT_RETAIN,
     CONF_MQTT_TLS,
     CONF_MQTT_TOPIC,
     CONF_MQTT_USERNAME,
@@ -230,6 +231,11 @@ def mqtt_port(self) -> int:
         """Return the MQTT broker port."""
         return cast(int, self._config.get(CONF_MQTT_PORT))
 
+    @property
+    def mqtt_retain(self) -> bool:
+        """Return whether MQTT messages should be retained."""
+        return cast(bool, self._config.get(CONF_MQTT_RETAIN, False))
+
     @property
     def mqtt_tls(self) -> bool:
         """Return whether MQTT over TLS is configured."""

ecowitt2mqtt/const.py

@@ -23,6 +23,7 @@
 CONF_MQTT_BROKER: Final = "mqtt_broker"
 CONF_MQTT_PASSWORD: Final = "mqtt_password"
 CONF_MQTT_PORT: Final = "mqtt_port"
+CONF_MQTT_RETAIN: Final = "mqtt_retain"
 CONF_MQTT_TLS: Final = "mqtt_tls"
 CONF_MQTT_TOPIC: Final = "mqtt_topic"
 CONF_MQTT_USERNAME: Final = "mqtt_username"
@@ -129,6 +130,7 @@
 ENV_MQTT_BROKER: Final = "ECOWITT2MQTT_MQTT_BROKER"
 ENV_MQTT_PASSWORD: Final = "ECOWITT2MQTT_MQTT_PASSWORD"
 ENV_MQTT_PORT: Final = "ECOWITT2MQTT_MQTT_PORT"
+ENV_MQTT_RETAIN: Final = "ECOWITT2MQTT_MQTT_RETAIN"
 ENV_MQTT_TLS: Final = "ECOWITT2MQTT_MQTT_TLS"
 ENV_MQTT_TOPIC: Final = "ECOWITT2MQTT_MQTT_TOPIC"
 ENV_MQTT_USERNAME: Final = "ECOWITT2MQTT_MQTT_USERNAME"

ecowitt2mqtt/helpers/publisher/hass.py

@@ -438,6 +438,7 @@ def _generate_discovery_payload(
                 },
                 "name": name,
                 "qos": 1,
+                "retain": self.ecowitt.config.mqtt_retain,
                 "state_topic": f"{base_topic}/state",
                 "unique_id": f"{device.unique_id}_{payload_key}",
             },
@@ -492,7 +493,9 @@ async def async_publish(self, data: dict[str, DataValueType]) -> None:
                         tasks.append(
                             asyncio.create_task(
                                 self.client.publish(
-                                    topic, generate_mqtt_payload(payload)
+                                    topic,
+                                    payload=generate_mqtt_payload(payload),
+                                    retain=self.ecowitt.config.mqtt_retain,
                                 )
                             )
                         )

ecowitt2mqtt/helpers/publisher/topic.py

@@ -25,7 +25,9 @@ async def async_publish(self, data: dict[str, DataValueType]) -> None:
         try:
             async with self.client:
                 await self.client.publish(
-                    self.ecowitt.config.mqtt_topic, generate_mqtt_payload(data)
+                    self.ecowitt.config.mqtt_topic,
+                    payload=generate_mqtt_payload(data),
+                    retain=self.ecowitt.config.mqtt_retain,
                 )
         except MqttError as err:
             raise PublishError(