MZTC: correct the driver against the camera protocol manual

Five points where the code disagreed with the BJ core serial protocol manual.
The manual is the one shipped with the camera and it is the source for the
class and subclass addresses the driver already used.

Auto shutter wire values

The camera defines 0x01 for temperature only, 0x02 for time only and 0x03 for
time and temperature. It answers 0x00 with a threshold error. The driver sent
the zero-based setting straight through. Every mode was off by one. The
default sent an out of range value. The setting keeps its zero-based ordering
for the settings.yaml lookup table. The driver adds
MZTC_SHUTTER_WIRE_OFFSET on the way out.

Shutter interval belongs to the camera

0x7C/0x05 is a read and write command taking two bytes of minutes. The camera
runs the schedule from it. The driver ignored the command and ran its own
timer, firing manual shutter commands that competed with the camera. The
interval is now pushed on connect. mztcCheckCalibration only counts elapsed
minutes for the status and OSD surfaces.

mztc_ffc_interval now accepts 1 to 60. Zero no longer means disabled, because
the camera owns the schedule. Selecting TEMP_ONLY is how time-driven
correction is turned off.

Initialization status reply address

The host asks on 0x7C/0x14. The manual specifies the reply as class 0x7D
subclass 0x06. The decoder matched on the request address. The reply was never
decoded.

Vignetting correction is an action

0x7C/0x0C with data 0x02, write only. The manual requires the lens to be
pointed at a uniform surface first. Running it automatically would superimpose
the current scene onto the correction. The boolean setting is
removed. mztc_vignetting and MSP2_SET_MZTC_VIGNETTING at 0x224B replace it.

Bad pixel removal is not a setting

0x78/0x1A drives an on-screen cursor through move, confirm and cancel steps.
A flight controller cannot walk that cursor onto each bad pixel. The boolean
setting is removed with nothing in its place.

Both removed booleans were never transmitted. They did nothing.

Contract changes

The MSP config payload drops from 24 to 22 bytes. msp_messages.json moves to
2.3.0 and gains MSP2_SET_MZTC_VIGNETTING. docs/Settings.md is regenerated.

The camera manual contradicts itself on the zoom labels. Its prose says 1x,
2x, 4x and 8x. Its value table for the same command says 1x, 2x, 3x and 4x.
The wire values 0 to 3 are identical either way. The enum is unchanged and the
ambiguity is documented.

Validated on three builds. SPEEDYBEEF405AIO with MZTC on sits at 77.9% flash.
MATEKF722SE with MZTC off sits at 95.1% flash. SITL builds too. All three
compile with no warnings in any MZTC file. 543 of 543 unit tests pass.

Author: wdunn001

docs/MassZero_Thermal_Camera.md

@@ -148,6 +148,8 @@ set mztc_mirror_mode = NONE
 
 Zoom accepts `1X`, `2X`, `4X` and `8X`. Mirror accepts `NONE`, `HORIZONTAL`, `VERTICAL` and `CENTRAL`. `mztc_zoom 2` applies a zoom level immediately by index.
 
+The camera manual contradicts itself on the zoom labels. Its prose says 1x, 2x, 4x and 8x. Its value table for the same command says 1x, 2x, 3x and 4x. The wire values 0 to 3 are the same either way. The setting works regardless of which set of labels is right.
+
 ### Shutter and flat field correction
 
 A manual shutter cycle on this camera performs a flat field correction. One command covers both:
@@ -163,7 +165,9 @@ set mztc_auto_shutter = TIME_AND_TEMP
 set mztc_ffc_interval = 5
 ```
 
-`mztc_auto_shutter` accepts `TEMP_ONLY`, `TIME_ONLY` and `TIME_AND_TEMP`. `mztc_ffc_interval` is in minutes. Setting it to 0 disables the time-driven correction. INAV issues its own timed correction unless `mztc_auto_shutter` is `TEMP_ONLY`. In that case the timing is left to the camera.
+`mztc_auto_shutter` accepts `TEMP_ONLY`, `TIME_ONLY` and `TIME_AND_TEMP`. `mztc_ffc_interval` is in minutes and accepts 1 to 60.
+
+The camera runs the shutter schedule itself. INAV pushes both values to it on connect and then leaves it alone. Select `TEMP_ONLY` to stop the camera correcting on a timer, since it then reacts to temperature drift only.
 
 ### Temperature alerts
 
@@ -177,11 +181,21 @@ Both thresholds accept -40 to 200 degrees Celsius. The low threshold must not ex
 
 Alerts only fire once the camera reports a temperature. The published MassZero protocol document defines no temperature-read command. No build in this tree reports one yet. The alert state stays clear.
 
-### Correction and display options
+### Vignetting correction
+
+Vignetting correction is a one-shot action. There is no setting for it:
+
+```
+mztc_vignetting
+```
+
+Point the lens at a uniform surface before running it. The camera superimposes whatever it is looking at onto the correction. A cluttered scene makes the image worse.
+
+Bad pixel removal is not exposed. The camera drives it through an on-screen cursor that has to be walked onto each bad pixel. A flight controller cannot do that usefully.
+
+### Display options
 
 ```
-set mztc_bad_pixel_removal = ON
-set mztc_vignetting_correction = ON
 set mztc_crosshair_enabled = OFF
 set mztc_temperature_unit = CELSIUS
 set mztc_update_rate = 9
@@ -202,6 +216,7 @@ set mztc_update_rate = 9
 | `mztc_denoise <spatial> <temporal>` | Set both denoising levels |
 | `mztc_alerts <enabled> <high> <low>` | Configure the temperature alerts |
 | `mztc_calibrate` | Trigger a manual shutter cycle for a flat field correction |
+| `mztc_vignetting` | Run one vignetting correction |
 | `mztc_save` | Save the current image settings to the camera's own flash |
 | `mztc_defaults` | Restore the camera to its factory defaults |
 | `mztc_reconnect` | Close the port and restart the connection sequence |
@@ -214,17 +229,18 @@ The camera is reachable over MSP V2 in INAV's own command range. Full payload la
 
 | Command | Code | Direction | Payload |
 | --- | --- | --- | --- |
-| `MSP2_MZTC_CONFIG` | 0x2240 | Out | 24 bytes |
+| `MSP2_MZTC_CONFIG` | 0x2240 | Out | 22 bytes |
 | `MSP2_MZTC_STATUS` | 0x2241 | Out | 19 bytes |
 | `MSP2_MZTC_FRAME_DATA` | 0x2242 | Out | 24 byte header plus thermal bytes |
-| `MSP2_SET_MZTC_CONFIG` | 0x2243 | In | 24 bytes |
+| `MSP2_SET_MZTC_CONFIG` | 0x2243 | In | 22 bytes |
 | `MSP2_SET_MZTC_MODE` | 0x2244 | In | 1 byte |
 | `MSP2_SET_MZTC_PALETTE` | 0x2245 | In | 1 byte |
 | `MSP2_SET_MZTC_ZOOM` | 0x2246 | In | 1 byte |
 | `MSP2_SET_MZTC_SHUTTER` | 0x2247 | In | 0 or 1 bytes |
 | `MSP2_SET_MZTC_ALERTS` | 0x2248 | In | 5 bytes |
 | `MSP2_SET_MZTC_IMAGE_PARAMS` | 0x2249 | In | 3 bytes |
 | `MSP2_SET_MZTC_CORRECTION` | 0x224A | In | 2 bytes |
+| `MSP2_SET_MZTC_VIGNETTING` | 0x224B | In | 0 or 1 bytes |
 
 Temperatures cross as signed 16 bit deci-degrees Celsius. 25.5 degrees is 255. Every field is read and written individually. The wire layout never depends on compiler padding.
 

docs/Settings.md

@@ -3551,16 +3551,6 @@ Auto shutter calibration mode
 
 ---
 
-### mztc_bad_pixel_removal
-
-Enable bad pixel removal
-
-| Default | Min | Max |
-| --- | --- | --- |
-| ON | OFF | ON |
-
----
-
 ### mztc_baudrate
 
 Baud rate index for MassZero Thermal Camera. Index 8 is 115200. MassZero cameras ship at that rate.
@@ -3623,11 +3613,11 @@ Enable MassZero Thermal Camera
 
 ### mztc_ffc_interval
 
-Flat Field Calibration interval in minutes (0=disabled)
+Automatic shutter interval in minutes. The camera runs the schedule itself. Set mztc_auto_shutter to TEMP_ONLY to stop it correcting on a timer.
 
 | Default | Min | Max |
 | --- | --- | --- |
-| 5 | 0 | 60 |
+| 5 | 1 | 60 |
 
 ---
 
@@ -3746,16 +3736,6 @@ Frame update rate in Hz
 
 ---
 
-### mztc_vignetting_correction
-
-Enable vignetting correction
-
-| Default | Min | Max |
-| --- | --- | --- |
-| ON | OFF | ON |
-
----
-
 ### mztc_zoom_level
 
 Digital zoom level

docs/development/msp/msp_messages.json

@@ -1,7 +1,7 @@
 {
     "version": {
         "major": 2,
-        "minor": 2,
+        "minor": 3,
         "patch": 0
     },
     "messages": {
@@ -11799,23 +11799,11 @@
                         "name": "ffc_interval",
                         "ctype": "uint8_t",
                         "units": "minutes",
-                        "desc": "Automatic flat field correction interval. 0-60, where 0 disables it."
-                    },
-                    {
-                        "name": "bad_pixel_removal",
-                        "ctype": "uint8_t",
-                        "units": "",
-                        "desc": "Bad pixel removal enabled. 0 or 1."
-                    },
-                    {
-                        "name": "vignetting_correction",
-                        "ctype": "uint8_t",
-                        "units": "",
-                        "desc": "Vignetting correction enabled. 0 or 1."
+                        "desc": "Automatic shutter interval in minutes. 1-60. The camera runs the schedule itself."
                     }
                 ]
             },
-            "notes": "Requires `USE_MZTC`. Fixed 24 byte reply. Each field is written with the `sbufWrite*` helpers. The layout never depends on compiler padding.",
+            "notes": "Requires `USE_MZTC`. Fixed 22 byte reply. Each field is written with the `sbufWrite*` helpers. The layout never depends on compiler padding.",
             "description": "Reads the MassZero thermal camera configuration."
         },
         "MSP2_MZTC_STATUS": {
@@ -12101,24 +12089,12 @@
                         "name": "ffc_interval",
                         "ctype": "uint8_t",
                         "units": "minutes",
-                        "desc": "Automatic flat field correction interval. 0-60, where 0 disables it."
-                    },
-                    {
-                        "name": "bad_pixel_removal",
-                        "ctype": "uint8_t",
-                        "units": "",
-                        "desc": "Bad pixel removal enabled. 0 or 1."
-                    },
-                    {
-                        "name": "vignetting_correction",
-                        "ctype": "uint8_t",
-                        "units": "",
-                        "desc": "Vignetting correction enabled. 0 or 1."
+                        "desc": "Automatic shutter interval in minutes. 1-60. The camera runs the schedule itself."
                     }
                 ]
             },
             "reply": null,
-            "notes": "Requires `USE_MZTC`. Expects 24 bytes. The whole request is validated against the `MZTC_*` limits before any field is applied. A rejected request leaves the running configuration untouched.",
+            "notes": "Requires `USE_MZTC`. Expects 22 bytes. The whole request is validated against the `MZTC_*` limits before any field is applied. A rejected request leaves the running configuration untouched.",
             "description": "Writes the MassZero thermal camera configuration."
         },
         "MSP2_SET_MZTC_MODE": {
@@ -12269,6 +12245,23 @@
             "reply": null,
             "notes": "Requires `USE_MZTC`. Expects 2 bytes. Returns an error if the camera is not connected.",
             "description": "Sets the MassZero thermal camera denoising parameters."
+        },
+        "MSP2_SET_MZTC_VIGNETTING": {
+            "code": 8779,
+            "mspv": 2,
+            "request": {
+                "payload": [
+                    {
+                        "name": "trigger",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "Ignored. The command itself is the trigger."
+                    }
+                ]
+            },
+            "reply": null,
+            "notes": "Requires `USE_MZTC`. Accepts 0 or 1 bytes. The camera manual requires the lens to be pointed at a uniform surface before this runs, so it is an action and never a stored setting.",
+            "description": "Runs one vignetting correction on the camera."
         }
     }
 }

src/main/config/mztc_camera.h

@@ -78,21 +78,28 @@ typedef enum {
     MZTC_MIRROR_CENTRAL = 3            // Both horizontal and vertical
 } mztcMirrorMode_e;
 
-// MassZero Thermal Camera auto shutter modes
+// MassZero Thermal Camera auto shutter modes.
+//
+// The camera expects 0x01 to 0x03 on the wire and rejects 0x00 as out of
+// range, so the driver adds MZTC_SHUTTER_WIRE_OFFSET when it sends the value.
+// These enum values stay zero-based because settings.yaml indexes its lookup
+// table from zero.
 typedef enum {
-    MZTC_SHUTTER_TEMP_ONLY = 0,        // Based on temperature difference only
-    MZTC_SHUTTER_TIME_ONLY = 1,        // Based on time interval only
-    MZTC_SHUTTER_TIME_AND_TEMP = 2     // Both time and temperature (default)
+    MZTC_SHUTTER_TEMP_ONLY = 0,        // Camera wire value 0x01
+    MZTC_SHUTTER_TIME_ONLY = 1,        // Camera wire value 0x02
+    MZTC_SHUTTER_TIME_AND_TEMP = 2     // Camera wire value 0x03, the default
 } mztcShutterMode_e;
 
+#define MZTC_SHUTTER_WIRE_OFFSET        1
+
 // MassZero Thermal Camera limits.
 //
 // These are the single source of truth for the valid ranges. settings.yaml
 // references them for the CLI bounds. The MSP handlers validate against them.
 // A value the CLI rejects cannot be smuggled in over MSP.
 #define MZTC_MIN_UPDATE_RATE            1       // Minimum 1 Hz
 #define MZTC_MAX_UPDATE_RATE            30      // Maximum 30 Hz
-#define MZTC_MIN_FFC_INTERVAL           0       // 0 disables periodic FFC
+#define MZTC_MIN_FFC_INTERVAL           1       // Minimum 1 minute
 #define MZTC_MAX_FFC_INTERVAL           60      // Maximum 60 minutes
 #define MZTC_MIN_PERCENT                0
 #define MZTC_MAX_PERCENT                100
@@ -127,9 +134,7 @@ typedef struct mztcConfig_s {
     uint8_t temperature_alerts;         // Enable temperature alerts
     float alert_high_temp;              // High temperature alert threshold
     float alert_low_temp;               // Low temperature alert threshold
-    uint8_t ffc_interval;               // Flat Field Calibration interval (minutes)
-    uint8_t bad_pixel_removal;          // Enable bad pixel removal
-    uint8_t vignetting_correction;      // Enable vignetting correction
+    uint8_t ffc_interval;               // Automatic shutter interval, in minutes
 } mztcConfig_t;
 
 // MassZero Thermal Camera status structure
@@ -219,6 +224,7 @@ bool mztcIsConnected(void);
 void mztcRequestReconnect(void);
 bool mztcSaveConfiguration(void);
 bool mztcRestoreDefaults(void);
+bool mztcTriggerVignettingCorrection(void);
 bool mztcConfigIsValid(const mztcConfig_t *cfg);
 
 // Serial framing helpers. Exposed so the unit test can exercise the wire

src/main/fc/cli.c

@@ -170,6 +170,7 @@ static void cliMztcCalibrate(char *cmdline);
 static void cliMztcReconnect(char *cmdline);
 static void cliMztcSave(char *cmdline);
 static void cliMztcDefaults(char *cmdline);
+static void cliMztcVignetting(char *cmdline);
 #endif
 
 #ifdef USE_CLI_BATCH
@@ -5242,6 +5243,19 @@ static void cliMztcDefaults(char *cmdline)
         cliPrintLine("Failed to restore camera defaults");
     }
 }
+
+// Point the lens at a uniform surface before running this. The camera
+// superimposes whatever it is looking at onto the correction otherwise.
+static void cliMztcVignetting(char *cmdline)
+{
+    UNUSED(cmdline);
+
+    if (mztcTriggerVignettingCorrection()) {
+        cliPrintLine("Vignetting correction triggered. Point the lens at a uniform surface first.");
+    } else {
+        cliPrintLine("Failed to trigger vignetting correction");
+    }
+}
 #endif // USE_MZTC
 
 static void cliHelp(char *cmdline);
@@ -5332,6 +5346,7 @@ const clicmd_t cmdTable[] = {
     CLI_COMMAND_DEF("mztc_mode", "set operating mode", "[mode]", cliMztcMode),
     CLI_COMMAND_DEF("mztc_palette", "set color palette", "[palette]", cliMztcPalette),
     CLI_COMMAND_DEF("mztc_save", "save the current settings to the camera flash", NULL, cliMztcSave),
+    CLI_COMMAND_DEF("mztc_vignetting", "run one vignetting correction", NULL, cliMztcVignetting),
     CLI_COMMAND_DEF("mztc_zoom", "set zoom level", "[level]", cliMztcZoom),
 #endif
     CLI_COMMAND_DEF("mmix", "custom motor mixer", NULL, cliMotorMix),

src/main/fc/fc_msp.c

@@ -2020,8 +2020,6 @@ static bool mspFcProcessOutCommand(uint16_t cmdMSP, sbuf_t *dst, mspPostProcessF
             sbufWriteU16(dst, (uint16_t)MZTC_TEMP_TO_DECIDEG(cfg->alert_high_temp));
             sbufWriteU16(dst, (uint16_t)MZTC_TEMP_TO_DECIDEG(cfg->alert_low_temp));
             sbufWriteU8(dst, cfg->ffc_interval);
-            sbufWriteU8(dst, cfg->bad_pixel_removal);
-            sbufWriteU8(dst, cfg->vignetting_correction);
         }
         break;
 
@@ -4082,8 +4080,6 @@ static mspResult_e mspFcProcessInCommand(uint16_t cmdMSP, sbuf_t *src)
             candidate.alert_high_temp = MZTC_DECIDEG_TO_TEMP((int16_t)sbufReadU16(src));
             candidate.alert_low_temp = MZTC_DECIDEG_TO_TEMP((int16_t)sbufReadU16(src));
             candidate.ffc_interval = sbufReadU8(src);
-            candidate.bad_pixel_removal = sbufReadU8(src);
-            candidate.vignetting_correction = sbufReadU8(src);
 
             // This rejects an update_rate of zero. The camera task would
             // otherwise use it as a divisor. It also rejects a baudrate that
@@ -4177,6 +4173,18 @@ static mspResult_e mspFcProcessInCommand(uint16_t cmdMSP, sbuf_t *src)
             return MSP_RESULT_ERROR;
         }
         break;
+
+    case MSP2_SET_MZTC_VIGNETTING:
+        // An action, not a setting. The lens has to be pointed at a uniform
+        // surface before this is worth running.
+        if (dataSize <= 1) {
+            if (!mztcTriggerVignettingCorrection()) {
+                return MSP_RESULT_ERROR;
+            }
+        } else {
+            return MSP_RESULT_ERROR;
+        }
+        break;
 #endif
 
     case MSP2_INAV_SET_CRUISE_HEADING:

src/main/fc/settings.yaml

@@ -260,7 +260,7 @@ constants:
 
   MZTC_MIN_UPDATE_RATE: 1
   MZTC_MAX_UPDATE_RATE: 30
-  MZTC_MIN_FFC_INTERVAL: 0
+  MZTC_MIN_FFC_INTERVAL: 1
   MZTC_MAX_FFC_INTERVAL: 60
   MZTC_MIN_PERCENT: 0
   MZTC_MAX_PERCENT: 100
@@ -4867,22 +4867,12 @@ groups:
         min: MZTC_MIN_ALERT_TEMP
         max: MZTC_MAX_ALERT_TEMP
       - name: mztc_ffc_interval
-        description: "Flat Field Calibration interval in minutes (0=disabled)"
+        description: "Automatic shutter interval in minutes. The camera runs the schedule itself. Set mztc_auto_shutter to TEMP_ONLY to stop it correcting on a timer."
         type: uint8_t
         default_value: 5
         field: ffc_interval
         min: MZTC_MIN_FFC_INTERVAL
         max: MZTC_MAX_FFC_INTERVAL
-      - name: mztc_bad_pixel_removal
-        description: "Enable bad pixel removal"
-        type: bool
-        default_value: ON
-        field: bad_pixel_removal
-      - name: mztc_vignetting_correction
-        description: "Enable vignetting correction"
-        type: bool
-        default_value: ON
-        field: vignetting_correction
   - name: PG_GEOZONE_CONFIG
     type: geozone_config_t
     headers: ["navigation/navigation.h"]