diff --git a/docs/man/man1/modcompile.1 b/docs/man/man1/modcompile.1
index 0bf8134f852..a5f3f8b7d4b 100644
--- a/docs/man/man1/modcompile.1
+++ b/docs/man/man1/modcompile.1
@@ -24,7 +24,7 @@
 .\"
 .TH modcompile "1"  "2023-07-13" "LinuxCNC Documentation" "The Enhanced Machine Controller"
 .SH NAME
-modcompile \- Utility for compiling Modbus drivers
+modcompile \- Utility for compiling Modbus drivers (SUPERSEDED)
 
 .SH SYNOPSIS
 
@@ -35,6 +35,11 @@ modcompile \- Utility for compiling Modbus drivers
 \fBmodcompile* [\fB-k\fR] [\fB-n\fR] [\fB-v\fR] module.mod ...
 
 .SH DESCRIPTION
+\fBmodcompile\fR and the mesa_modbus framework are superseded by the
+\fBhm2_modbus\fR driver and \fBmesambccc\fR-compiled MBCCB files. They remain
+available throughout the 2.9 series, but new configurations are encouraged to
+migrate.
+
 The \fBmodcompile\fR utility is used to compile modbus drivers that use the PktUART
 interface of Mesa cards.
 
diff --git a/docs/src/drivers/mesa_modbus.adoc b/docs/src/drivers/mesa_modbus.adoc
index d17b0b455a3..ce280c766fd 100644
--- a/docs/src/drivers/mesa_modbus.adoc
+++ b/docs/src/drivers/mesa_modbus.adoc
@@ -5,6 +5,8 @@
 
 = Mesa Modbus =
 
+NOTE: The Mesa Modbus framework (modcompile and mesa_modbus) is superseded by the link:../man/man9/hm2_modbus.9.html[hm2_modbus] driver and mesambccc-compiled MBCCB files. It remains available throughout the 2.9 series, but new configurations are encouraged to migrate.
+
 A framework to create custom, realtime, modbus drivers using the Mesa
 PktUART component.
 
diff --git a/docs/src/index.tmpl b/docs/src/index.tmpl
index ffa9ae415f5..73141c4a84e 100644
--- a/docs/src/index.tmpl
+++ b/docs/src/index.tmpl
@@ -200,7 +200,7 @@ function setup_page(){
 		<li><a href="drivers/hal_pi_gpio.html">Raspberry Pi GPIO Driver</a></li>
 		<li><a href="drivers/hostmot2.html">Mesa HostMot2 Driver</a></li>
 		<li><a href="drivers/mb2hal.html">Modbus to HAL Driver</a></li>
-		<li><a href="drivers/mesa_modbus.html">Modbus framework for Mesa cards</a></li>
+		<li><a href="drivers/mesa_modbus.html">Modbus framework for Mesa cards (superseded)</a></li>
 		<li><a href="drivers/mitsub-vfd.html">Mitsubishi VFD Driver</a></li>
 		<li><a href="drivers/motenc.html">Motenc Driver</a></li>
 		<li><a href="drivers/opto22.html">Opto22 Driver</a></li>
diff --git a/src/hal/drivers/mesa-hostmot2/modbus/README.adoc b/src/hal/drivers/mesa-hostmot2/modbus/README.adoc
index 7cfa602d44b..20ccfecf284 100644
--- a/src/hal/drivers/mesa-hostmot2/modbus/README.adoc
+++ b/src/hal/drivers/mesa-hostmot2/modbus/README.adoc
@@ -1,3 +1,8 @@
+NOTE: The mesa_modbus framework (this directory and modcompile) is
+superseded by the hm2_modbus driver and mesambccc-compiled .mbccb
+files. It remains available throughout the 2.9 series, but new
+configurations are encouraged to migrate.
+
 Do not edit mesa_modbus.c (Unless you are sure that you want to, of
 course).
 Create a new xxxxx.mod file that describes your particular modbus device
diff --git a/src/hal/drivers/mesa-hostmot2/modbus/modcompile.py b/src/hal/drivers/mesa-hostmot2/modbus/modcompile.py
index 2c1062c8698..9966756eb90 100644
--- a/src/hal/drivers/mesa-hostmot2/modbus/modcompile.py
+++ b/src/hal/drivers/mesa-hostmot2/modbus/modcompile.py
@@ -88,6 +88,11 @@ def main():
     if len(args) < 1:
         raise SystemExit("No modules found (*.mod files) to compile.");
 
+    print("NOTE: modcompile and the mesa_modbus framework are superseded by the"
+          " hm2_modbus driver and mesambccc-compiled .mbccb files. They remain"
+          " available throughout the 2.9 series, but new configurations are"
+          " encouraged to migrate.", file=sys.stderr)
+
     # Create a temporary directory and copy the C template into it
     tempdir = tempfile.mkdtemp(prefix="modcompile")
     BASE = os.path.abspath(os.path.join(os.path.dirname(sys.argv[0]), ".."))