Merge pull request iNavFlight#11343 from xznhj8129/msp_versioning

MSP spec versioning

Author: sensei-hacker

docs/Settings.md

@@ -8,8 +8,21 @@ For details on the structure of MSP, see [The wiki page](https://github.com/iNav
 For list of enums, see [Enum documentation page](https://github.com/iNavFlight/inav/wiki/Enums-reference)
 
 
+**When To Regenerate**
 
-**JSON file rev: 4**
+Run `docs/development/msp/gen_docs.sh` whenever MSP docs inputs change:
+- `msp_messages.json` message content/schema updates
+- source enum changes under `src/main` that affect `inav_enums.json`
+- `format.md` or this header template (`docs_v2_header.md`) changes
+
+By default the script removes temporary generated headers. Use `--keep_headers` only when you need them.
+
+**Versioning Rule**
+
+When the MSP JSON specification changes, bump `msp_messages.json` version:
+- breaking schema/compatibility change: increment `version.major`, reset `minor` and `patch`
+- backward-compatible schema extension: increment `version.minor`, reset `patch`
+- message/content/docs-only update inside current schema: increment `version.patch`
 
 **Warning: Verification needed, exercise caution until completely verified for accuracy and cleared, especially for integer signs. Source-based generation/validation is forthcoming. Refer to source for absolute certainty** 
 
@@ -27,36 +40,50 @@ For list of enums, see [Enum documentation page](https://github.com/iNavFlight/i
 # Format:
 ## JSON format example:
 ```
-    "MSP_API_VERSION": {
-        "code": 1,
-        "mspv": 1,
-        "request": null,
-        "reply": {
-            "payload": [
-                {
-                    "name": "mspProtocolVersion",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "MSP Protocol version (`MSP_PROTOCOL_VERSION`, typically 0)."
-                },
-                {
-                    "name": "apiVersionMajor",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "INAV API Major version (`API_VERSION_MAJOR`)."
-                },
-                {
-                    "name": "apiVersionMinor",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "INAV API Minor version (`API_VERSION_MINOR`)."
-                }
-            ],
-        },
-        "notes": "Used by configurators to check compatibility.",
-        "description": "Provides the MSP protocol version and the INAV API version."
+{
+    "version": {
+        "major": 2,
+        "minor": 0,
+        "patch": 0
     },
+    "messages": {
+        "MSP_API_VERSION": {
+            "code": 1,
+            "mspv": 1,
+            "request": null,
+            "reply": {
+                "payload": [
+                    {
+                        "name": "mspProtocolVersion",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "MSP Protocol version (`MSP_PROTOCOL_VERSION`, typically 0)."
+                    },
+                    {
+                        "name": "apiVersionMajor",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "INAV API Major version (`API_VERSION_MAJOR`)."
+                    },
+                    {
+                        "name": "apiVersionMinor",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "INAV API Minor version (`API_VERSION_MINOR`)."
+                    }
+                ]
+            },
+            "notes": "Used by configurators to check compatibility.",
+            "description": "Provides the MSP protocol version and the INAV API version."
+        },
+        "...": {}
+    }
+}
 ```
+## Top-level fields:
+**version**: JSON spec version (`major.minor.patch`)\
+**messages**: Dictionary keyed by MSP message name
+
 ## Message fields:
 **name**: MSP message name\
 **code**: Integer message code\
@@ -66,6 +93,7 @@ For list of enums, see [Enum documentation page](https://github.com/iNavFlight/i
 **variable_len**: Optional boolean, if true, message does not have a predefined fixed length and needs appropriate handling\
 **variants**: Optional special case, message has different cases of reply/request. Key/description is not a strict expression or code; just a readable condition\
 **not_implemented**: Optional special case, message is not implemented (never or deprecated)\
+**replaced_by**: Optional array of MSP message names that replace this command. Present when a command is deprecated and scheduled for removal. Empty array if no replacement is needed\
 **notes**: String with details of message
 
 ## Data dict fields:
@@ -2213,7 +2241,7 @@ For list of enums, see [Enum documentation page](https://github.com/iNavFlight/i
 | `armingFlags` | `uint16_t` | 2 | Bitmask | Bitmask: Flight controller arming flags (`armingFlags`). Note: Truncated to 16 bits |
 | `accCalibAxisFlags` | `uint8_t` | 1 | Bitmask | Bitmask: Accelerometer calibrated axes flags (`accGetCalibrationAxisFlags()`) |
 
-**Notes:** Superseded by `MSP2_INAV_STATUS` which provides the full 32-bit `armingFlags` and other enhancements.
+**Notes:** Superseded by `MSP2_INAV_STATUS` which provides the full 32-bit `armingFlags` and other enhancements. The `accCalibAxisFlags` field is not present in `MSP2_INAV_STATUS` but is available via `MSP_CALIBRATION_DATA`.
 
 ## <a id="msp_sensor_status"></a>`MSP_SENSOR_STATUS (151 / 0x97)`
 **Description:** Provides the hardware status for each individual sensor system.  

docs/development/msp/README.md

@@ -8,8 +8,21 @@ For details on the structure of MSP, see [The wiki page](https://github.com/iNav
 For list of enums, see [Enum documentation page](https://github.com/iNavFlight/inav/wiki/Enums-reference)
 
 
+**When To Regenerate**
 
-**JSON file rev: <file_rev>**
+Run `docs/development/msp/gen_docs.sh` whenever MSP docs inputs change:
+- `msp_messages.json` message content/schema updates
+- source enum changes under `src/main` that affect `inav_enums.json`
+- `format.md` or this header template (`docs_v2_header.md`) changes
+
+By default the script removes temporary generated headers. Use `--keep_headers` only when you need them.
+
+**Versioning Rule**
+
+When the MSP JSON specification changes, bump `msp_messages.json` version:
+- breaking schema/compatibility change: increment `version.major`, reset `minor` and `patch`
+- backward-compatible schema extension: increment `version.minor`, reset `patch`
+- message/content/docs-only update inside current schema: increment `version.patch`
 
 **Warning: Verification needed, exercise caution until completely verified for accuracy and cleared, especially for integer signs. Source-based generation/validation is forthcoming. Refer to source for absolute certainty** 
 

docs/development/msp/docs_v2_header.md

@@ -1,36 +1,50 @@
 # Format:
 ## JSON format example:
 ```
-    "MSP_API_VERSION": {
-        "code": 1,
-        "mspv": 1,
-        "request": null,
-        "reply": {
-            "payload": [
-                {
-                    "name": "mspProtocolVersion",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "MSP Protocol version (`MSP_PROTOCOL_VERSION`, typically 0)."
-                },
-                {
-                    "name": "apiVersionMajor",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "INAV API Major version (`API_VERSION_MAJOR`)."
-                },
-                {
-                    "name": "apiVersionMinor",
-                    "ctype": "uint8_t",
-                    "units": "",
-                    "desc": "INAV API Minor version (`API_VERSION_MINOR`)."
-                }
-            ],
-        },
-        "notes": "Used by configurators to check compatibility.",
-        "description": "Provides the MSP protocol version and the INAV API version."
+{
+    "version": {
+        "major": 2,
+        "minor": 0,
+        "patch": 0
     },
+    "messages": {
+        "MSP_API_VERSION": {
+            "code": 1,
+            "mspv": 1,
+            "request": null,
+            "reply": {
+                "payload": [
+                    {
+                        "name": "mspProtocolVersion",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "MSP Protocol version (`MSP_PROTOCOL_VERSION`, typically 0)."
+                    },
+                    {
+                        "name": "apiVersionMajor",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "INAV API Major version (`API_VERSION_MAJOR`)."
+                    },
+                    {
+                        "name": "apiVersionMinor",
+                        "ctype": "uint8_t",
+                        "units": "",
+                        "desc": "INAV API Minor version (`API_VERSION_MINOR`)."
+                    }
+                ]
+            },
+            "notes": "Used by configurators to check compatibility.",
+            "description": "Provides the MSP protocol version and the INAV API version."
+        },
+        "...": {}
+    }
+}
 ```
+## Top-level fields:
+**version**: JSON spec version (`major.minor.patch`)\
+**messages**: Dictionary keyed by MSP message name
+
 ## Message fields:
 **name**: MSP message name\
 **code**: Integer message code\

docs/development/msp/format.md

@@ -1,27 +1,34 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
 INAV_MAIN_PATH="../../../src/main"
+INAV_ROOT="../../.."
+BUILD_INFO_SCRIPT="./get_fc_build_info.sh"
+KEEP_HEADERS=0
+
+for arg in "$@"; do
+  if [[ "$arg" == "--keep_headers" ]]; then
+    KEEP_HEADERS=1
+  fi
+done
+
+eval "$(bash "$BUILD_INFO_SCRIPT" "$INAV_ROOT")"
 
 echo "###########"
 echo get_all_inav_enums_h.py
 python get_all_inav_enums_h.py --inav-root "$INAV_MAIN_PATH"
 
-echo "###########"
-echo "msp_messages.json checksum"
-actual="$(md5sum msp_messages.json | awk '{print $1}')"
-expected="$(awk '{print $1}' msp_messages.checksum)"
-echo "Hash:" $actual
-if [[ "$actual" != "$expected" ]]; then
-  n="$(cat rev)"
-  printf '%d' "$(n + 1)" > rev
-  echo "File changed, incrementing revision"
-  echo $actual > msp_messages.checksum
-fi
-
 echo "###########"
 echo gen_msp_md.py
 python gen_msp_md.py
 
 echo "###########"
 echo gen_enum_md.py
-python gen_enum_md.py
-rm all_enums.h
-read -n 1 -s -r -p "Press any key to continue"
+python gen_enum_md.py \
+  --fc-version-major "$FC_VERSION_MAJOR" \
+  --fc-version-minor "$FC_VERSION_MINOR" \
+  --fc-version-patch-level "$FC_VERSION_PATCH_LEVEL"
+if [[ "$KEEP_HEADERS" -eq 0 ]]; then
+  rm all_enums.h
+fi

docs/development/msp/gen_docs.sh

@@ -20,6 +20,7 @@
 from pathlib import Path
 from typing import List, Optional
 import json
+import argparse
 
 # ---------- Helpers ----------
 
@@ -249,7 +250,7 @@ def parse_files(paths: List[Path]) -> List[EnumDef]:
 
 # ---------- Markdown rendering ----------
 
-def render_markdown(enums: List[EnumDef]) -> str:
+def render_markdown(enums: List[EnumDef], build: dict) -> str:
     jsonfile = {}
     out = []
     out.append("# Enumerations\n")
@@ -277,19 +278,37 @@ def render_markdown(enums: List[EnumDef]) -> str:
         if '_source' in jsonfile[e.name]:
             jsonfile[e.name]['_source'] = jsonfile[e.name]['_source'].replace('../../../src', 'inav/src')
         out.append("")
-    # While we're at it, chuck this all into a JSON file
-    Path("inav_enums.json").write_text(json.dumps(jsonfile,indent=4), encoding="utf-8")
+    wrapped = {
+        "build": build,
+        "enums": jsonfile,
+    }
+    Path("inav_enums.json").write_text(json.dumps(wrapped, indent=4), encoding="utf-8")
     return "\n".join(out)
 
 # ---------- Main ----------
 
 def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate enum markdown/json from all_enums.h")
+    parser.add_argument("--fc-version-major", required=True, type=int)
+    parser.add_argument("--fc-version-minor", required=True, type=int)
+    parser.add_argument("--fc-version-patch-level", required=True, type=int)
+    args = parser.parse_args()
+
     path = Path("all_enums.h")
     if not path.exists():
         print(f"Error: {path} not found", file=sys.stderr)
         return 1
     enums = parse_files([path])
-    md = render_markdown(enums)
+    md = render_markdown(
+        enums,
+        {
+            "fc_version": {
+                "major": args.fc_version_major,
+                "minor": args.fc_version_minor,
+                "patch": args.fc_version_patch_level,
+            },
+        },
+    )
     Path("inav_enums_ref.md").write_text(md, encoding="utf-8")
     return 0
 

docs/development/msp/gen_enum_md.py

@@ -8,7 +8,7 @@
 - STRICT: If a code exists in one (MSPCodes vs JSON) but not the other, crash with details.
 - Index items link to headings via GitHub-style auto-anchors.
 - Tight layout; identical Request/Reply tables; skip complex=true with a stub.
-- Default input: msp_messages.json ; default output: MSP_Doc.md
+- Default input: msp_messages.json ; default output: README.md
 """
 
 import sys
@@ -414,24 +414,24 @@ def generate_markdown(defs: Dict[str, Any]) -> str:
     with open("format.md", "r", encoding="utf-8") as f:
         fmt = f.read()
 
-    with open("msp_messages.checksum", "r", encoding="utf-8") as f:
-        chksum = f.read().split(' ')[0]
-    with open("rev", "r", encoding="utf-8") as f:
-        rev = f.read()
-
-    header = header.replace('<format>',fmt)
-    header = header.replace('<file_rev>',rev)
-    header = header.replace('<file_hash>',chksum)
+    header = header.replace('<format>', fmt)
 
     index_md = build_index(json_by_code)
     return header + "\n" + index_md + "\n" + "".join(sections)
 
+
+def get_messages_definitions(payload: Dict[str, Any]) -> Dict[str, Any]:
+    if "messages" in payload:
+        return payload["messages"]
+    return payload
+
 def main():
     in_path = Path(sys.argv[1]) if len(sys.argv) >= 2 else Path("msp_messages.json")
     out_path = Path(sys.argv[2]) if len(sys.argv) >= 3 else Path("README.md")
 
     with in_path.open("r", encoding="utf-8") as f:
-        defs = json.load(f)
+        payload = json.load(f)
+    defs = get_messages_definitions(payload)
 
     md = generate_markdown(defs)
     out_path.write_text(md, encoding="utf-8")

docs/development/msp/gen_msp_md.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+INAV_ROOT="${1:-$(git rev-parse --show-toplevel)}"
+CMAKE_FILE="$INAV_ROOT/CMakeLists.txt"
+
+version_fields="$(sed -nE 's/^project\(INAV VERSION ([0-9]+)\.([0-9]+)\.([0-9]+)\).*/\1 \2 \3/p' "$CMAKE_FILE")"
+if [[ -z "$version_fields" ]]; then
+  echo "Failed to parse version from $CMAKE_FILE" >&2
+  exit 1
+fi
+read -r FC_VERSION_MAJOR FC_VERSION_MINOR FC_VERSION_PATCH_LEVEL <<< "$version_fields"
+
+printf 'FC_VERSION_MAJOR=%s\n' "$FC_VERSION_MAJOR"
+printf 'FC_VERSION_MINOR=%s\n' "$FC_VERSION_MINOR"
+printf 'FC_VERSION_PATCH_LEVEL=%s\n' "$FC_VERSION_PATCH_LEVEL"