Add jammed state support for MQTT lock (#25793)

Co-authored-by: Patrick ZAJDA <patrick@zajda.fr>

source/_integrations/lock.mqtt.markdown

@@ -20,7 +20,7 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i
 
 It's mandatory for locks to support `lock` and `unlock`. A lock may optionally support `open`, (e.g. to open the bolt in addition to the latch), in this case, `payload_open` is required in the configuration. If the lock is in optimistic mode, it will change states to `unlocked` when handling the `open` command.
 
-An MQTT lock can also report the intermediate states `unlocking` and `locking`.
+An MQTT lock can also report the intermediate states `unlocking`, `locking` or `jammed` if the motor reports a jammed state.
 <a id='new_format'></a>
 
 To enable MQTT locks in your installation, add the following to your `configuration.yaml` file:
@@ -194,27 +194,32 @@ retain:
   required: false
   type: boolean
   default: false
+state_jammed:
+  description: The payload sent to `state_topic` by the lock when it's jammed.
+  required: false
+  type: string
+  default: JAMMED
 state_locked:
-  description: The payload sent to by the lock when it's locked.
+  description: The payload sent to `state_topic` by the lock when it's locked.
   required: false
   type: string
   default: LOCKED
 state_locking:
-  description: The payload sent to by the lock when it's locking.
+  description: The payload sent to `state_topic` by the lock when it's locking.
   required: false
   type: string
   default: LOCKING
 state_topic:
-  description: The MQTT topic subscribed to receive state updates.
+  description: The MQTT topic subscribed to receive state updates. It accepts states configured with `state_jammed`, `state_locked`, `state_unlocked`, `state_locking` or `state_unlocking`.
   required: false
   type: string
 state_unlocked:
-  description: The payload sent to by the lock when it's unlocked.
+  description: The payload sent to `state_topic` by the lock when it's unlocked.
   required: false
   type: string
   default: UNLOCKED
 state_unlocking:
-  description: The payload sent to by the lock when it's unlocking.
+  description: The payload sent to `state_topic` by the lock when it's unlocking.
   required: false
   type: string
   default: UNLOCKING
@@ -223,7 +228,7 @@ unique_id:
    required: false
    type: string
 value_template:
-  description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the payload."
+  description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a state value from the payload.
   required: false
   type: string
 {% endconfiguration %}
@@ -249,12 +254,16 @@ The example below shows a full configuration for a MQTT lock.
 mqtt:
   lock:
     - name: Frontdoor
-      state_topic: "home-assistant/frontdoor/"
+      state_topic: "home-assistant/frontdoor/state"
       command_topic: "home-assistant/frontdoor/set"
       payload_lock: "LOCK"
       payload_unlock: "UNLOCK"
       state_locked: "LOCK"
       state_unlocked: "UNLOCK"
+      state_locking: "LOCKING"
+      state_unlocking: "UNLOCKING"
+      state_jammed: "MOTOR_JAMMED"
+      state_ok: "MOTOR_OK"
       optimistic: false
       qos: 1
       retain: true

source/_integrations/mqtt.markdown

@@ -426,6 +426,7 @@ Configuration variable names in the discovery payload may be abbreviated to cons
     'stat_cla':            'state_class',
     'stat_clsd':           'state_closed',
     'stat_closing':        'state_closing',
+    'stat_jam':            'state_jammed',
     'stat_off':            'state_off',
     'stat_on':             'state_on',
     'stat_open':           'state_open',