diff --git a/src/assets/images/user-guide/integrations/kafka-integration-architecture.svg b/src/assets/images/user-guide/integrations/kafka-integration-architecture.svg
new file mode 100644
index 0000000000..d3770e51d9
--- /dev/null
+++ b/src/assets/images/user-guide/integrations/kafka-integration-architecture.svg
@@ -0,0 +1,154 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1430" height="412" viewBox="0 0 962 277.3">
+  <defs>
+    <pattern id="dots" x="0" y="0" width="14" height="14" patternUnits="userSpaceOnUse">
+      <circle cx="7" cy="7" r="1" fill="#dde0e4"/>
+    </pattern>
+    <clipPath id="clip0">
+      <path fill="#fff" d="M0 0h962v277.3H0z"/>
+    </clipPath>
+  </defs>
+  <g clip-path="url(#clip0)">
+    <path fill="#fff" d="M0 0h962v277.3H0z"/>
+    <rect width="962" height="277.3" fill="url(#dots)"/>
+    <g transform="translate(0,33)">
+
+      <!-- ThingsBoard Deployment outer box (covers B3, B4, B5) -->
+      <rect x="390" y="-11" width="562" height="192" rx="12" fill="none" stroke="#00695c" stroke-width="0.75" stroke-dasharray="6,4"/>
+      <rect x="410" y="-18" width="178" height="14" fill="#fff"/>
+      <text x="501" y="-11" text-anchor="middle" font-family="system-ui,sans-serif" font-size="14" fill="#00695c" font-weight="600" dominant-baseline="central" textLength="174" lengthAdjust="spacing">ThingsBoard Deployment</text>
+
+      <!-- ============ BLOCK 1: Existing Device ============ -->
+      <rect x="6" y="59" width="150" height="52" rx="10" fill="#fff" stroke="#6a1b9a" stroke-width="1.5"/>
+      <g transform="translate(13.3,64.3) scale(0.69)" fill="#6a1b9a">
+        <rect x="14" y="14" width="32" height="32" rx="2" fill="#6a1b9a"/>
+        <rect x="19" y="19" width="22" height="22" rx="1" fill="#fff"/>
+        <rect x="20" y="8" width="4" height="7" rx="1"/>
+        <rect x="28" y="8" width="4" height="7" rx="1"/>
+        <rect x="36" y="8" width="4" height="7" rx="1"/>
+        <rect x="20" y="45" width="4" height="7" rx="1"/>
+        <rect x="28" y="45" width="4" height="7" rx="1"/>
+        <rect x="36" y="45" width="4" height="7" rx="1"/>
+        <rect x="8" y="20" width="7" height="4" rx="1"/>
+        <rect x="8" y="28" width="7" height="4" rx="1"/>
+        <rect x="8" y="36" width="7" height="4" rx="1"/>
+        <rect x="45" y="20" width="7" height="4" rx="1"/>
+        <rect x="45" y="28" width="7" height="4" rx="1"/>
+        <rect x="45" y="36" width="7" height="4" rx="1"/>
+      </g>
+      <text x="99" y="85" text-anchor="middle" font-family="system-ui,sans-serif" font-size="10" fill="#17181c" font-weight="600" dominant-baseline="middle">Existing Device</text>
+
+      <!-- GAP 1 UPLINK -->
+      <line x1="156" y1="78" x2="218" y2="78" stroke="#1565c0" stroke-width="1.5"/>
+      <polygon points="218,74 226,78 218,82" fill="#1565c0"/>
+      <text x="191" y="42" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Produce</text>
+      <text x="191" y="51" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">messages /</text>
+      <text x="191" y="60" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Publish</text>
+      <text x="191" y="69" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">messages</text>
+      <!-- GAP 1 DOWNLINK -->
+      <line x1="226" y1="92" x2="164" y2="92" stroke="#f53d7d" stroke-width="1.5" stroke-dasharray="4,3"/>
+      <polygon points="164,88 156,92 164,96" fill="#f53d7d"/>
+      <text x="191" y="101" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Receive</text>
+      <text x="191" y="110" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">commands</text>
+
+      <!-- ============ BLOCK 2: Kafka brokers ============ -->
+      <rect x="226" y="5" width="110" height="160" rx="10" fill="#fff" stroke="#00695c" stroke-width="1.5"/>
+      <text x="293.07" y="85" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="middle">kafka</text>
+      <g transform="translate(251.29,69.46) scale(0.074738)" fill="#231f20">
+        <path d="M201.816 230.216c-16.186 0-30.697 7.171-40.634 18.461l-25.463-18.026c2.703-7.442 4.255-15.433 4.255-23.797 0-8.219-1.498-16.076-4.112-23.408l25.406-17.835c9.936 11.233 24.409 18.365 40.548 18.365 29.875 0 54.184-24.305 54.184-54.184 0-29.879-24.309-54.184-54.184-54.184-29.875 0-54.184 24.305-54.184 54.184 0 5.348.808 10.505 2.258 15.389l-25.423 17.844c-10.62-13.175-25.911-22.374-43.333-25.182v-30.64c24.544-5.155 43.037-26.962 43.037-53.019C124.171 24.305 99.862 0 69.987 0 40.112 0 15.803 24.305 15.803 54.184c0 25.708 18.014 47.246 42.067 52.769v31.038C25.044 143.753 0 172.401 0 206.854c0 34.621 25.292 63.374 58.355 68.94v32.774c-24.299 5.341-42.552 27.011-42.552 52.894 0 29.879 24.309 54.184 54.184 54.184 29.875 0 54.184-24.305 54.184-54.184 0-25.883-18.253-47.553-42.552-52.894v-32.775a69.965 69.965 0 0 0 42.6-24.776l25.633 18.143c-1.423 4.84-2.22 9.946-2.22 15.24 0 29.879 24.309 54.184 54.184 54.184 29.875 0 54.184-24.305 54.184-54.184 0-29.879-24.309-54.184-54.184-54.184zm0-126.695c14.487 0 26.27 11.788 26.27 26.271s-11.783 26.27-26.27 26.27-26.27-11.787-26.27-26.27c0-14.483 11.783-26.271 26.27-26.271zm-158.1-49.337c0-14.483 11.784-26.27 26.271-26.27s26.27 11.787 26.27 26.27c0 14.483-11.783 26.27-26.27 26.27s-26.271-11.787-26.271-26.27zm52.541 307.278c0 14.483-11.783 26.27-26.27 26.27s-26.271-11.787-26.271-26.27c0-14.483 11.784-26.27 26.271-26.27s26.27 11.787 26.27 26.27zm-26.272-117.97c-20.205 0-36.642-16.434-36.642-36.638 0-20.205 16.437-36.642 36.642-36.642 20.204 0 36.641 16.437 36.641 36.642 0 20.204-16.437 36.638-36.641 36.638zm131.831 67.179c-14.487 0-26.27-11.788-26.27-26.271s11.783-26.27 26.27-26.27 26.27 11.787 26.27 26.27c0 14.483-11.783 26.271-26.27 26.271z"/>
+      </g>
+
+      <!-- GAP 2 UPLINK -->
+      <line x1="336" y1="70" x2="398" y2="70" stroke="#1565c0" stroke-width="1.5"/>
+      <polygon points="398,66 406,70 398,74" fill="#1565c0"/>
+      <text x="371" y="44" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Consume</text>
+      <text x="371" y="53" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">messages /</text>
+      <text x="371" y="62" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Poll messages</text>
+
+      <!-- ============ BLOCK 3: Kafka Integration ============ -->
+      <rect x="406" y="5" width="130" height="130" rx="10" fill="#fff" stroke="#00695c" stroke-width="1.5"/>
+      <text x="471" y="18" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="hanging">Kafka</text>
+      <text x="471" y="34" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="hanging">Integration</text>
+      <g transform="matrix(-0.169870,0,0,-0.166552,516.5201,126.5578)" fill="#00695c">
+        <path d="m 465.3,145.05 h -43.5 c -17.7,0 -21.8,-14.7 -12.6,-25.3 15.2,-17.2 7.1,-43 -20.2,-44.5 -27.3,1 -35.4,27.3 -20.2,44 9.1,10.1 5.1,25.3 -12.6,25.3 h -42.5 c -12.6,0 -23.3,10.1 -23.3,23.3 v 55.1 h -1 -78.4 v -21.8 c 0,-2 -2.5,-3 -4.6,-1.5 l -51.1,42 c -1.5,1.5 -1.5,4 0,5.6 l 51.1,42 c 2,1.5 4.6,0 4.6,-2 v -21.8 h 78.2 1 v 55.6 c 0,12.6 10.1,23.3 23.3,23.3 H 356 c 17.7,0 21.8,14.7 12.6,24.8 -15.2,17.2 -7.1,43 20.2,44 27.3,-1 35.4,-27.3 20.2,-44 -9.1,-10.1 -5.1,-24.8 12.6,-24.8 h 43 c 13.2,0 23.8,-10.6 23.8,-23.8 v -43.6 c -0.5,-17.2 -15.2,-21.2 -25.3,-12.1 -17.2,15.2 -43.5,7.1 -44.5,-20.2 1,-27.3 27.3,-35.4 44.5,-20.2 10.1,9.1 24.8,5.1 25.3,-12.1 v -44 c 0.1,-12.7 -10,-23.3 -23.1,-23.3 z"/>
+        <path d="m 244.7,145.45 h -43.5 c -17.7,0 -21.8,-15.2 -12.6,-25.3 15.2,-17.2 7.1,-43.5 -20.2,-44.5 -27.3,1 -35.4,26.8 -20.2,44 9.1,10.1 5.1,25.3 -12.6,25.3 H 93.1 c -13.2,0 -23.3,10.6 -23.3,23.3 v 43.5 c 0,17.7 -15.2,21.8 -25.3,12.6 -17.2,-15.2 -43.5,-7.1 -44.5,20.2 1,27.3 27.3,35.4 44,20.2 10.1,-9.1 25.3,-5.1 25.3,12.6 v 43 c 0,13.2 10.6,23.3 23.3,23.3 h 42.5 c 17.7,0 21.8,14.7 12.6,24.8 -15.2,16.7 -7.1,43 20.2,44 27.3,-1 35.4,-26.8 20.2,-44 -9.1,-10.1 -5.1,-24.8 12.6,-24.8 h 43 c 13.2,0 23.8,-10.6 23.8,-23.8 v -32.7 h -34.4 c -0.5,13.7 -11.7,24.8 -25.3,24.8 -6.1,0 -11.6,-2 -16.2,-5.6 l -51.1,-42 c -6.1,-5.1 -9.6,-12.1 -9.6,-20.2 0,-8.1 3.5,-15.2 9.6,-20.2 l 51.6,-42 c 4.6,-3.5 10.1,-5.6 16.2,-5.6 13.7,0 24.8,11.1 25.3,24.8 H 268 v -32.4 c 0,-13.2 -10.6,-23.3 -23.3,-23.3 z"/>
+      </g>
+
+      <!-- GAP 3 UPLINK -->
+      <line x1="536" y1="70" x2="598" y2="70" stroke="#1565c0" stroke-width="1.5"/>
+      <polygon points="598,66 606,70 598,74" fill="#1565c0"/>
+      <text x="571" y="62" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">uplink payload</text>
+
+      <!-- ============ BLOCK 4: Data Converters ============ -->
+      <rect x="606" y="5" width="130" height="130" rx="10" fill="#fff" stroke="#00695c" stroke-width="1.5"/>
+      <text x="671" y="18" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="hanging">Data Converter</text>
+      <g transform="matrix(0.217828,0,0,0.213574,616.2844,38.1842)" fill="#00695c">
+        <path d="m 373.23,68.177 -61.8,-41.6 c -3.4,-2.3 -7.9,0.1 -7.9,4.2 v 22.5 h -153.6 c -10.6,0 -19.1,8.6 -19.1,19.1 v 106.5 c 0,2.3 2.6,3.7 4.5,2.4 l 30,-20.2 c 2.3,-1.5 3.7,-4.1 3.7,-6.9 v -62.7 h 134.4 v 22.5 c 0,4.1 4.5,6.5 7.9,4.2 l 61.8,-41.6 c 3.1,-2 3.1,-6.4 0.1,-8.4 z"/>
+        <path d="m 354.13,117.98 -30,20.2 c -2.3,1.5 -3.7,4.1 -3.7,6.9 v 62.6 h -134.5 v -22.5 c 0,-4.1 -4.5,-6.5 -7.9,-4.2 l -61.8,41.6 c -3,2 -3,6.4 0,8.4 l 61.8,41.6 c 3.4,2.3 7.9,-0.1 7.9,-4.2 v -22.5 h 153.5 c 10.6,0.1 19.2,-8.5 19.2,-19.1 v -106.4 c 0,-2.3 -2.6,-3.7 -4.5,-2.4 z"/>
+      </g>
+      <rect x="647" y="111" width="48" height="15" rx="7.5" fill="#e6f4f1"/>
+      <text x="671" y="118" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#00695c" font-weight="700" dominant-baseline="central">Uplink</text>
+
+      <!-- GAP 4 UPLINK -->
+      <line x1="736" y1="70" x2="798" y2="70" stroke="#1565c0" stroke-width="1.5"/>
+      <polygon points="798,66 806,70 798,74" fill="#1565c0"/>
+      <text x="771" y="53" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">telemetry /</text>
+      <text x="771" y="62" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">attributes</text>
+
+      <!-- ============ BLOCK 5: ThingsBoard Core Service ============ -->
+      <rect x="806" y="5" width="130" height="160" rx="10" fill="#fff" stroke="#00695c" stroke-width="1.5"/>
+      <text x="871" y="18" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="hanging">ThingsBoard</text>
+      <text x="871" y="32" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#17181c" font-weight="600" dominant-baseline="hanging">Core Service</text>
+      <g transform="translate(117,5)">
+        <!-- Storage -->
+        <rect x="701" y="58" width="106" height="26" rx="5" fill="#f0f1f3" stroke="#c1c3c8" stroke-width=".8"/>
+        <g fill="#00695c" transform="translate(45,1.5)">
+          <ellipse cx="669" cy="65" rx="7" ry="2.5" fill="#00695c"/>
+          <rect x="662" y="65" width="14" height="9" fill="#00695c"/>
+          <ellipse cx="669" cy="74" rx="7" ry="2.5" fill="#00695c"/>
+          <ellipse cx="669" cy="65" rx="7" ry="2.5" fill="#e6f4f1" opacity=".5"/>
+        </g>
+        <text x="744" y="71" text-anchor="start" font-family="system-ui,sans-serif" font-size="8.5" fill="#37474f" font-weight="600" dominant-baseline="central">Storage</text>
+        <!-- Dashboards -->
+        <rect x="701" y="90" width="106" height="26" rx="5" fill="#f0f1f3" stroke="#c1c3c8" stroke-width=".8"/>
+        <g fill="#00695c" transform="translate(47.5,2.5)">
+          <rect x="661" y="99" width="2.5" height="7" rx=".5"/>
+          <rect x="665" y="95" width="2.5" height="11" rx=".5"/>
+          <rect x="669" y="97" width="2.5" height="9" rx=".5"/>
+          <path d="M674,104 a6,6 0 0,1 12,0" fill="none" stroke="#00695c" stroke-width="1.3"/>
+          <line x1="680" y1="104" x2="677" y2="99" stroke="#00695c" stroke-width="1" stroke-linecap="round"/>
+          <circle cx="680" cy="104" r="1" fill="#00695c"/>
+        </g>
+        <text x="744" y="103" text-anchor="start" font-family="system-ui,sans-serif" font-size="8.5" fill="#37474f" font-weight="600" dominant-baseline="central">Dashboards</text>
+        <!-- Rule Engine -->
+        <rect x="701" y="122" width="106" height="26" rx="5" fill="#f0f1f3" stroke="#c1c3c8" stroke-width=".8"/>
+        <g fill="#00695c" transform="translate(49,0)">
+          <circle cx="665" cy="135" r="4" fill="none" stroke="#00695c" stroke-width="1.3"/>
+          <circle cx="665" cy="135" r="1.5" fill="#00695c"/>
+          <rect x="664" y="129.5" width="2" height="2" rx=".4"/>
+          <rect x="664" y="138.5" width="2" height="2" rx=".4"/>
+          <rect x="659" y="134" width="2" height="2" rx=".4"/>
+          <rect x="669" y="134" width="2" height="2" rx=".4"/>
+          <circle cx="672" cy="129" r="2.5" fill="none" stroke="#00695c" stroke-width="1"/>
+          <circle cx="672" cy="129" r="1" fill="#00695c"/>
+          <line x1="678" y1="128" x2="678" y2="142" stroke="#00695c" stroke-width="1.2"/>
+          <polygon points="683,128 681,134 683.5,134 681,141 687,133 684.5,133 687,128" fill="#00695c"/>
+        </g>
+        <text x="744" y="135" text-anchor="start" font-family="system-ui,sans-serif" font-size="8.5" fill="#37474f" font-weight="600" dominant-baseline="central">Rule Engine</text>
+      </g>
+
+      <!-- DOWNLINK RETURN: TB Core Service -> kafka (bottom path) -->
+      <line x1="806" y1="147" x2="344" y2="147" stroke="#f53d7d" stroke-width="1.5" stroke-dasharray="4,3"/>
+      <polygon points="344,143 336,147 344,151" fill="#f53d7d"/>
+      <text x="571" y="158" text-anchor="middle" font-family="system-ui,sans-serif" font-size="8" fill="#888d99">Produce commands / Publish commands</text>
+
+      <!-- LEGEND -->
+      <line x1="26" y1="200" x2="64" y2="200" stroke="#1565c0" stroke-width="1.5"/>
+      <polygon points="56,196 64,200 56,204" fill="#1565c0"/>
+      <text x="78" y="204" font-family="system-ui,sans-serif" font-size="11" fill="#555962">Uplink — data from Kafka to ThingsBoard</text>
+      <line x1="26" y1="222" x2="64" y2="222" stroke="#f53d7d" stroke-width="1.5" stroke-dasharray="4,3"/>
+      <polygon points="34,218 26,222 34,226" fill="#f53d7d"/>
+      <text x="78" y="226" font-family="system-ui,sans-serif" font-size="11" fill="#555962">Downlink — Rule Node publishes back to Kafka</text>
+
+    </g>
+  </g>
+</svg>
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_1.png b/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_1.png
deleted file mode 100644
index 51e8f1babf..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_1.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_work_with_cluster_1.png b/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_work_with_cluster_1.png
deleted file mode 100644
index 067e82d3db..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_work_with_cluster_1.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_0.png b/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_0.png
deleted file mode 100644
index 98b3a11238..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_0.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_1.png b/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_1.png
deleted file mode 100644
index 2ea0f49d73..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_1.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_2.png b/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_2.png
deleted file mode 100644
index b98bce1a4f..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_2.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_0.png b/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_0.png
deleted file mode 100644
index d8c4070557..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_0.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_1.png b/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_1.png
deleted file mode 100644
index d2292cd39e..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_1.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png
index 5db765e5ba..a88e462299 100644
Binary files a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png and b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png
index 3be1928ffe..02cf5d9231 100644
Binary files a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png and b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png
index db6a0db7f3..c1aaf98e99 100644
Binary files a/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png and b/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-1.png
new file mode 100644
index 0000000000..16be267d89
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-2.png
new file mode 100644
index 0000000000..6e329f1547
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-3.png b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-3.png
new file mode 100644
index 0000000000..41cc83d3ac
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-3.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-create-downlink-topic-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-create-downlink-topic-1.png
new file mode 100644
index 0000000000..58d9d2e4ab
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-create-downlink-topic-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-1.png
new file mode 100644
index 0000000000..13b4287341
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-2.png
new file mode 100644
index 0000000000..706c82a8c2
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-3.png b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-3.png
new file mode 100644
index 0000000000..e73163e0f1
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-3.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-1.png
new file mode 100644
index 0000000000..43122ef14e
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-2.png
new file mode 100644
index 0000000000..5d6dcaf781
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-start-downlink-consumer-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-start-downlink-consumer-1.png
new file mode 100644
index 0000000000..2041711224
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-start-downlink-consumer-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-trigger-downlink-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-trigger-downlink-1.png
new file mode 100644
index 0000000000..f638cd79f1
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-trigger-downlink-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-1.png
new file mode 100644
index 0000000000..40bb7d3f08
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-2.png
new file mode 100644
index 0000000000..74336da7fc
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-3.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-3.png
new file mode 100644
index 0000000000..e3e0de1751
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-3.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-device-provisioning-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-device-provisioning-1.png
new file mode 100644
index 0000000000..e8ce4fdd7a
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-device-provisioning-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-1.png
new file mode 100644
index 0000000000..0bc939e8e1
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-2.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-2.png
new file mode 100644
index 0000000000..37d65484a5
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-2.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka-verify-kafka-delivery-1.png b/src/assets/images/user-guide/integrations/kafka/kafka-verify-kafka-delivery-1.png
new file mode 100644
index 0000000000..a1862425fa
Binary files /dev/null and b/src/assets/images/user-guide/integrations/kafka/kafka-verify-kafka-delivery-1.png differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka_integration_test_send_msg_result.png b/src/assets/images/user-guide/integrations/kafka/kafka_integration_test_send_msg_result.png
deleted file mode 100644
index 2d29ba211b..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/kafka_integration_test_send_msg_result.png and /dev/null differ
diff --git a/src/assets/images/user-guide/integrations/kafka/kafka_uplink_test_decoder.png b/src/assets/images/user-guide/integrations/kafka/kafka_uplink_test_decoder.png
deleted file mode 100644
index 9fb43f101c..0000000000
Binary files a/src/assets/images/user-guide/integrations/kafka/kafka_uplink_test_decoder.png and /dev/null differ
diff --git a/src/content/_includes/docs/user-guide/integrations/kafka.mdx b/src/content/_includes/docs/user-guide/integrations/kafka.mdx
index 08634a84e7..4387f30974 100644
--- a/src/content/_includes/docs/user-guide/integrations/kafka.mdx
+++ b/src/content/_includes/docs/user-guide/integrations/kafka.mdx
@@ -7,356 +7,691 @@ import { Products } from '~/models/site.models';
 import Tabs from '@components/Tabs.astro';
 import TabItem from '@components/TabItem.astro';
 
-<Banner variant="peFeature" product={props.product} path="user-guide/integrations/kafka" />
+<Banner variant="peFeature" product={props.product} path="installation/" />
+The <a href="https://kafka.apache.org/" target="_blank" rel="noopener noreferrer nofollow"><strong>Apache Kafka</strong></a> integration connects ThingsBoard to Apache Kafka message brokers. Use it to consume records that producers — devices, IoT platforms, connectivity providers, or your own applications — publish to Kafka topics, and bring them into ThingsBoard as telemetry and attributes for monitoring and rule-based automation — including publishing commands back to Kafka.
 
-Kafka Integration connects ThingsBoard to <a href="https://kafka.apache.org/" target="_blank">Apache Kafka</a> message brokers. It subscribes to one or more Kafka topics, consumes incoming messages, and transforms them into ThingsBoard telemetry and attributes via an uplink converter.
+## Architecture
 
-<DocImage src="/src/assets/images/user-guide/integrations/kafka/Kafka_main.png" alt="Kafka Integration architecture diagram — devices and IoT platforms publish messages to Kafka brokers; the Kafka Integration consumes topics, passes payloads through an uplink converter, and pushes telemetry and attributes to ThingsBoard; a separate Kafka Rule Node handles downlink" />
+<ImageGallery images={[
+  {
+    src: '/src/assets/images/user-guide/integrations/kafka-integration-architecture.svg',
+    alt: 'Kafka integration architecture diagram showing uplink data flowing from a producer through Kafka brokers to the ThingsBoard Kafka Integration, the uplink converter, and Core Service, and downlink flowing back from the Rule Engine to Kafka via the Kafka Rule Node',
+    caption: 'Kafka integration architecture — uplink and downlink data flow between Kafka and ThingsBoard.',
+  },
+]} />
+
+A producer publishes a record to a Kafka topic. The Kafka Integration, acting as a Kafka consumer, subscribes to the topic and polls the broker for new records. The uplink converter decodes the record value into telemetry and attributes, and the ThingsBoard Core Service stores the data, creating the device automatically on first contact. For downlink, the Rule Engine hands a message to a Kafka Rule Node, which publishes it to a separate Kafka topic; external consumers then read it. The Kafka Integration has no dedicated downlink converter.
 
 ## Prerequisites
 
-A running Kafka broker is required before creating the integration.
+Before creating the integration, ensure:
 
-Use a local installation or a cloud-managed cluster such as <a href="https://www.confluent.io/" target="_blank">Confluent Cloud</a>.
+- You have access to {props.product !== Products.PAAS && props.product !== Products.PAAS_EU && <><DocLink product={Products.PE} path="installation/" target="_blank">ThingsBoard PE</DocLink> or </>}<a href="/installations/?product=thingsboard-cloud" target="_blank" rel="noopener noreferrer"><strong>ThingsBoard Cloud</strong></a> with integration functionality enabled for your tenant.
+- You have permissions to create integrations and data converters.
+- You have a running <a href="https://kafka.apache.org/" target="_blank" rel="noopener noreferrer nofollow"><strong>Apache Kafka</strong></a> broker — either a local installation or a cloud-managed cluster such as <a href="https://www.confluent.io/" target="_blank" rel="noopener noreferrer nofollow"><strong>Confluent Cloud</strong></a>. If you do not have a cluster yet, follow the **[Kafka Setup](#kafka-setup)** step below.
 
-## ThingsBoard integration setup
+<Aside type="note" title="Setup used in this guide">
+  This guide assumes a **self-hosted ThingsBoard PE deployed locally** and an **Apache Kafka broker installed on the same machine**. Because both run on the same host, the integration reaches the broker at `localhost:9092`. If ThingsBoard and Kafka run on different hosts — or you use ThingsBoard Cloud — replace `localhost` with the broker's reachable address and set the broker's `advertised.listeners` accordingly (see the note under [Required Connection Details](#required-connection-details)).
+</Aside>
 
-### Create an uplink converter
+## Kafka Setup
 
-The uplink converter decodes the Kafka message body and maps it to the ThingsBoard data model. Kafka uses a <DocLink product={props.product} path="user-guide/integrations/uplink-data-converter">generic uplink converter</DocLink>.
+The Kafka Integration connects ThingsBoard to an existing Apache Kafka broker as a consumer. The steps below stand up a minimal **single-node broker in KRaft mode (no ZooKeeper)**, which is enough to test the integration. If you use a managed cluster (Confluent Cloud, Amazon MSK, Aiven, Redpanda Cloud, and others), skip to [Required Connection Details](#required-connection-details) and obtain the values from your provider instead.
 
-The decoder function receives:
-- `payload` — raw bytes of the Kafka message value
-- `metadata` — `integrationName` and any key-value pairs configured in the integration's Metadata settings
+### Run a Single-Node Broker (KRaft)
 
-It must return `deviceName`, `deviceType`, `telemetry`, and `attributes`. Both `telemetry` and `attributes` are flat key-value maps — nested objects are not supported.
+KRaft is Kafka's built-in consensus protocol; since Kafka 4.0 it fully replaces ZooKeeper, so one process acts as both controller and broker. Kafka 4.x requires **Java 17+**, and formatting storage is a **required, explicit step** before the first start. The commands below were verified on Ubuntu with Kafka 4.3.1 — adjust the version and paths for your environment.
 
-<Aside type="tip">
-  Use <DocLink product={props.product} path="user-guide/tbel">TBEL</DocLink> for converter scripts — it executes significantly faster than plain JavaScript inside ThingsBoard.
+**1. Install Java and download Kafka:**
+
+```bash
+sudo apt update
+sudo apt install -y openjdk-17-jre-headless curl
+java -version
+ 
+cd /tmp
+curl -fLO https://downloads.apache.org/kafka/4.3.1/kafka_2.13-4.3.1.tgz
+sudo tar -xzf kafka_2.13-4.3.1.tgz -C /opt
+sudo ln -s /opt/kafka_2.13-4.3.1 /opt/kafka
+sudo chown -R "$USER":"$USER" /opt/kafka_2.13-4.3.1
+cd /opt/kafka
+```
+
+**2. Initialize KRaft storage** (run once per broker):
+
+```bash
+KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
+bin/kafka-storage.sh format \
+  --standalone \
+  --cluster-id "$KAFKA_CLUSTER_ID" \
+  --config config/server.properties
+```
+
+**3. Start the broker:**
+
+```bash
+bin/kafka-server-start.sh config/server.properties
+```
+
+<Aside type="note" title="No ZooKeeper in Kafka 4.x">
+  KRaft mode has no ZooKeeper. Admin and console commands use `--bootstrap-server` — the `--zookeeper` flag was already removed from these tools back in Kafka 3.0 (well before ZooKeeper itself was removed from the broker in 4.0). If a guide references `config/kraft/server.properties`, note that in Kafka 4.x the KRaft configuration was consolidated into `config/server.properties`.
 </Aside>
 
-In this example, device **43T1YH-REE** sends a JSON payload where telemetry readings are packed as a 4-byte hex string in the `data` field:
+### Create a Topic
 
-```json
-{
-  "EUI": "43T1YH-REE",
-  "ts": 1638876127000,
-  "data": "3d1f0059",
-  "port": 10,
-  "freq": 24300,
-  "rssi": -130,
-  "serial": "230165HRT"
-}
+Create the uplink topic the integration will subscribe to (or enable **Auto create topics** in the integration to have ThingsBoard create it on subscribe). Run the command from the Kafka install directory (e.g. `/opt/kafka`):
+
+```bash
+bin/kafka-topics.sh --create \
+  --topic my-topic \
+  --bootstrap-server localhost:9092 \
+  --partitions 1 \
+  --replication-factor 1
+```
+
+Verify it exists (optional):
+
+```bash
+bin/kafka-topics.sh --bootstrap-server localhost:9092 --list
 ```
 
-`EUI` is used as the device name. Each 2-character hex segment of `data` encodes one sensor reading:
-- `3d` &#8702; Temperature
-- `1f` &#8702; Humidity
-- `00` &#8702; Fan speed
-- `59` &#8702; Pressure
+### Required Connection Details
+
+Collect these values for the integration's **Connection** step. For the single-node broker above, they are:
+
+| Field | Value for this setup | Description |
+|-------|----------------------|-------------|
+| **Group ID** | you define, e.g. `thingsboard-kafka-group` | Kafka consumer group name |
+| **Client ID** | you define, e.g. `thingsboard-kafka-client-01` | consumer client identifier |
+| **Bootstrap servers** | `localhost:9092` (or the broker host IP) | broker `host:port` address |
+| **Poll interval** | `5000` | poll frequency in milliseconds |
+| **Topics** | `my-topic` | comma-separated topic(s) to subscribe to |
+
+<Aside type="caution" title="The broker must be reachable from ThingsBoard">
+  `localhost:9092` works **only when ThingsBoard runs on the same host** as the broker. If ThingsBoard is on another host — or on **ThingsBoard Cloud** — set **Bootstrap servers** to the broker's reachable IP/hostname **and** set the broker's `advertised.listeners` to that same address; otherwise the consumer connects to the broker but then fails to fetch records. Alternatively, run the integration in **Execute remotely** mode next to the broker.
+</Aside>
+
+### Authentication (Secured Brokers)
+
+If the broker requires authentication — most managed and cloud brokers do — you also need credentials, typically a **username/password** or an **API key/secret**, together with the security protocol (e.g. `SASL_SSL`). These are entered under **Advanced settings &#8702; Other properties** as SASL/SSL parameters (see the **Other Properties** row under [Connection Settings](#connection-settings)). For an open or local broker without authentication, no credentials are needed — leave these empty.
+
+## Create Kafka Uplink Data Converter
+
+The uplink converter receives each consumed Kafka record, decodes the record value, and returns a structured object that ThingsBoard uses to create or update a device and store its telemetry and attributes.
+For the full decoder function reference — all input parameters and output fields — see <DocLink product={props.product} path="user-guide/integrations/uplink-data-converter" target="_blank">Uplink Data Converter</DocLink>.
+
+Kafka uses a **generic** uplink converter. These converters decode a JSON message received from a Kafka topic and transform it into the ThingsBoard integration data format.
+
+<Steps>
+  <ol start="1">
+    <li>Go to <strong>Integrations center &#8702; Data converters</strong>.</li>
+    <li>Click <strong>+ Add data converter &#8702; Create new converter</strong>.</li>
+  </ol>
+</Steps>
+
+In the **Add data converter** dialog:
+
+<Steps>
+  <ol start="3">
+    <li><strong>Converter type</strong> — leave <strong>Uplink</strong> (selected by default).</li>
+    <li><strong>Integration type</strong> — in the search field, enter <code>Kafka</code> and select <strong>Kafka</strong> from the list.</li>
+    <li><strong>Name</strong> — enter a converter name, for example <code>Kafka Uplink Converter</code>.</li>
+    <li><strong>Main decoding configuration</strong> — a code editor with the function signature <code>function decoder(payload, metadata) &#123;</code>. Paste the decoder function shown below. By default the editor opens in TBEL; use the <strong>TBEL / JS</strong> toggle (upper right) to switch languages.</li>
+    <li>Click <strong>Add</strong>.</li>
+  </ol>
+</Steps>
+
+<Aside type="tip">
+  Use <DocLink product={props.product} path="user-guide/tbel">TBEL</DocLink> for converter scripts — it executes significantly faster than plain JavaScript inside ThingsBoard.
+</Aside>
 
 <Tabs>
-<TabItem label="TBEL (Recommended)">
+  <TabItem label="TBEL (Recommended)">
+    ```js maxLines=15 collapsible
+    /** Decoder **/
+
+    // Decode the Kafka message payload into a JSON object.
+    var payloadJson = decodeToJson(payload);
+
+    // Use the EUI value as the ThingsBoard device name.
+    var deviceName = payloadJson.EUI;
 
-```js maxLines=35 collapsible
-/** Decoder **/
+    // Assign the same device type to all devices created by this integration.
+    var deviceType = 'Monitoring sensor';
 
-var payloadJson = decodeToJson(payload);
-var deviceName = payloadJson.EUI;
-var deviceType = 'Monitoring-sensor';
+    // Build the object expected by the ThingsBoard integration.
+    var result = {
+      deviceName: deviceName,
+      deviceType: deviceType,
 
-var result = {
-    deviceName: deviceName,
-    deviceType: deviceType,
-    attributes: {},
-    telemetry: {
+      // No device attributes are extracted from the incoming message.
+      attributes: {},
+
+      // Create a timestamped telemetry entry.
+      telemetry: {
+        // Use the timestamp provided in the Kafka message.
         ts: payloadJson.ts,
+
         values: {
-            Temperature: hexToInt(payloadJson.data.substring(0, 2)),
-            Humidity: hexToInt(payloadJson.data.substring(2, 4)),
-            Fan: hexToInt(payloadJson.data.substring(4, 6)),
-            Port: payloadJson.port,
-            Freq: payloadJson.freq,
-            Pressure: hexToInt(payloadJson.data.substring(6, 8)),
-            rssi: payloadJson.rssi,
-            serial: payloadJson.serial
+          // Read the first byte from the hexadecimal data field.
+          Temperature: hexToInt(payloadJson.data.substring(0, 2)),
+
+          // Read the second byte from the hexadecimal data field.
+          Humidity: hexToInt(payloadJson.data.substring(2, 4)),
+
+          // Read the third byte from the hexadecimal data field.
+          Fan: hexToInt(payloadJson.data.substring(4, 6)),
+
+          // Copy message metadata directly to telemetry.
+          Port: payloadJson.port,
+          Freq: payloadJson.freq,
+
+          // Read the fourth byte from the hexadecimal data field.
+          Pressure: hexToInt(payloadJson.data.substring(6, 8)),
+
+          // Copy signal strength and serial number to telemetry.
+          rssi: payloadJson.rssi,
+          serial: payloadJson.serial
         }
+      }
+    };
+
+    // Converts a hexadecimal string into an integer.
+    function hexToInt(hex) {
+      return parseInt(hex, 16);
     }
-};
 
-function hexToInt(hex) {
-    return parseInt(hex, 16);
-}
+    /** Helper function 'decodeToJson' is already built-in **/
 
-/** Helper function 'decodeToJson' is already built-in **/
+    return result;
+    ```
+    </TabItem>
+    <TabItem label="JavaScript">
+    ```js maxLines=15 collapsible
+    /** Decoder **/
 
-return result;
-```
+    // Decode the Kafka message payload into a JSON object.
+    var payloadJson = decodeToJson(payload);
+
+    // Use the EUI value as the ThingsBoard device name.
+    var deviceName = payloadJson.EUI;
 
-</TabItem>
-<TabItem label="JavaScript">
+    // Assign the same device type to all devices created by this integration.
+    var deviceType = 'Monitoring sensor';
 
-```js maxLines=50 collapsible
-/** Decoder **/
+    // Build the object expected by the ThingsBoard integration.
+    var result = {
+      deviceName: deviceName,
+      deviceType: deviceType,
 
-var payloadJson = decodeToJson(payload);
-var deviceName = payloadJson.EUI;
-var deviceType = 'Monitoring-sensor';
+      // No device attributes are extracted from the incoming message.
+      attributes: {},
 
-var result = {
-    deviceName: deviceName,
-    deviceType: deviceType,
-    attributes: {},
-    telemetry: {
+      // Create a timestamped telemetry entry.
+      telemetry: {
+        // Use the timestamp provided in the Kafka message.
         ts: payloadJson.ts,
+        
         values: {
-            Temperature: hexToInt(payloadJson.data.substring(0, 2)),
-            Humidity: hexToInt(payloadJson.data.substring(2, 4)),
-            Fan: hexToInt(payloadJson.data.substring(4, 6)),
-            Port: payloadJson.port,
-            Freq: payloadJson.freq,
-            Pressure: hexToInt(payloadJson.data.substring(6, 8)),
-            rssi: payloadJson.rssi,
-            serial: payloadJson.serial
+          // Read the first byte from the hexadecimal data field.
+          Temperature: hexToInt(payloadJson.data.substring(0, 2)),
+
+          // Read the second byte from the hexadecimal data field.
+          Humidity: hexToInt(payloadJson.data.substring(2, 4)),
+
+          // Read the third byte from the hexadecimal data field.
+          Fan: hexToInt(payloadJson.data.substring(4, 6)),
+
+          // Copy message metadata directly to telemetry.
+          Port: payloadJson.port,
+          Freq: payloadJson.freq,
+
+          // Read the fourth byte from the hexadecimal data field.
+          Pressure: hexToInt(payloadJson.data.substring(6, 8)),
+
+          // Copy signal strength and serial number to telemetry.
+          rssi: payloadJson.rssi,
+          serial: payloadJson.serial
         }
+      }
+    };
+
+    /** Helper functions **/
+
+    // Converts the incoming byte array into a UTF-8-compatible string.
+    function decodeToString(payload) {
+      return String.fromCharCode.apply(String, payload);
     }
-};
 
-/** Helper functions **/
+    // Converts the incoming byte array into a string and parses it as a JSON object.
+    function decodeToJson(payload) {
+      var str = decodeToString(payload);
+      return JSON.parse(str);
+    }
 
-function decodeToString(payload) {
-    return String.fromCharCode.apply(String, payload);
-}
+    // Converts a hexadecimal string into an integer. Matches the TBEL tab —
+    // both read a single byte (2 hex characters) at a time, so no byte-order
+    // reversal is needed. If you extend this to multi-byte fields, decide on
+    // endianness explicitly and keep both tabs consistent.
+    function hexToInt(hex) {
+      return parseInt(hex, 16);
+    }
 
-function decodeToJson(payload) {
-    var str = decodeToString(payload);
-    return JSON.parse(str);
-}
+    return result;
+    ```
+  </TabItem>
+</Tabs>
+
+<h4>What the Converter Receives</h4>
+
+ThingsBoard passes two variables to the decoder function:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `payload` | byte array | The raw bytes of the Kafka **record value**. |
+| `metadata` | object | Key-value map containing `integrationName`, any pairs configured in the integration's **Metadata** settings, and likely Kafka-specific fields such as `topic`, `partition`, and `offset` (the same fields the outbound Kafka Rule Node adds to its own metadata — see [Configure Downlink](#configure-downlink)). Open the uplink converter's **Events** tab and inspect a real **Metadata** panel to confirm exactly which fields your setup receives. |
+
+<Aside type="note" title="JSON payloads">
+  If the record value is a JSON document, use the built-in `decodeToJson(payload)` helper to parse it into an object before mapping fields.
+</Aside>
+
+<h4>Example: JSON Payload Decoded</h4>
+
+Apache Kafka does not impose an application-level schema on a record’s value. The value is stored as bytes and may contain JSON, Avro, Protobuf, plain text, or any other format selected by the producer.
+
+This example models a typical IoT data flow in which a LoRaWAN Network Server, or an intermediate service, publishes device uplink events to Kafka. Therefore, the sample message contains LoRaWAN-related fields such as a device EUI, frame port, frequency, and RSSI rather than Kafka-specific fields.
+
+Note that the field names and message structure used in this example are not defined by Kafka or standardized across all LoRaWAN Network Servers. Each producer may use a different schema, naming convention, nesting structure, or serialization format. Update the uplink converter and decoder to match the exact message format produced by your system.
+
+In this example, the device `43T1YH-REE` publishes a JSON record to Kafka. The sensor readings are encoded as a 4-byte hexadecimal string in the `data` field, and the incoming message is expected to contain the following fields:
 
-function hexToInt(value) {
-    return parseInt('0x' + value.match(/../g).reverse().join(''));
+```json
+{
+  "EUI": "43T1YH-REE",
+  "ts": 1638876127000,
+  "data": "3d1f0059",
+  "port": 10,
+  "freq": 24300,
+  "rssi": -130,
+  "serial": "230165HRT"
 }
+```
+
+The `data` field must contain at least eight hexadecimal characters. Each pair of characters represents one telemetry value:
+
+| Character positions | Telemetry key | Raw hex | Decoded value |
+| ------------------- | ------------- | ------- | ------------- |
+| `0–1`               | `Temperature` | `3d`    | `61`          |
+| `2–3`               | `Humidity`    | `1f`    | `31`          |
+| `4–5`               | `Fan`         | `00`    | `0`           |
+| `6–7`               | `Pressure`    | `59`    | `89`          |
+
+The converter returns:
 
-return result;
+```json
+{
+  "deviceName": "43T1YH-REE",
+  "deviceType": "Monitoring sensor",
+  "attributes": {},
+  "telemetry": {
+    "ts": 1638876127000,
+    "values": {
+      "Temperature": 61,
+      "Humidity": 31,
+      "Fan": 0,
+      "Port": 10,
+      "Freq": 24300,
+      "Pressure": 89,
+      "rssi": -130,
+      "serial": "230165HRT"
+    }
+  }
+}
 ```
 
-</TabItem>
-</Tabs>
+In short:
 
-### Create the Kafka integration
+* `deviceName`: the value of the `EUI` field;
+* `deviceType`: the static `Monitoring sensor` device type;
+* `attributes`: an empty object because the message does not contain attribute data;
+* `telemetry`: timestamped telemetry values extracted from the message.
 
-<Steps>
-1. Go to **Integrations center → Integrations** and click **+ Add integration**.
-2. **Basic settings:**
-    - Set **Integration type** to **Kafka** and enter a name (e.g. "Kafka integration").
-    - **Enable integration** and **Allow create devices or assets** are on by default.
-    - Click **Next**.
-</Steps>
+<Aside type="note">
+  The hexadecimal values are converted to unsigned integers without applying scaling or unit conversion.
+</Aside>
 
-<ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png', alt: 'Add integration wizard — Basic settings step: Integration type Kafka, name "Kafka integration", Enable integration and Allow create devices or assets toggles on, Next button', caption: 'Basic settings: set Integration type to Kafka, enter a name, verify both toggles are on, click Next' },
-]} />
+## Create Kafka Integration
 
 <Steps>
-  <ol start="3">
+  <ol start="1">
+    <li>Go to <strong>Integrations center &#8702; Integrations</strong> and click <strong>+ Add integration</strong>.</li>
+    <li>
+      <span><strong>Basic settings:</strong></span>
+      <ul>
+        <li>Set <strong>Integration type</strong> to <strong>Kafka</strong>.</li>
+        <li>Enter a <strong>Name</strong> for the integration, or keep the default <code>Kafka integration</code>.</li>
+        <li>Leave <strong>Enable integration</strong> and <strong>Allow create devices or assets</strong> on so a device is created automatically on first message.</li>
+        <li>Click <strong>Next</strong>.</li>
+      </ul>
+    </li>
     <li>
       <span><strong>Uplink data converter:</strong></span>
       <ul>
-        <li>Click <strong>Create new</strong>, enter a name, and paste the decoder script from the section above. Alternatively, click <strong>Select existing</strong> to reuse a previously created converter.</li>
+        <li>Click <strong>Select existing</strong> and choose the <a href="#create-kafka-uplink-data-converter"><strong>Kafka Uplink Converter</strong></a> created above, or click <strong>Create new</strong> to define the decoder inline.</li>
         <li>Click <strong>Next</strong>.</li>
       </ul>
     </li>
-  </ol>
-</Steps>
-
-<ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png', alt: 'Add integration wizard — Uplink data converter step: converter name entered, decoder script visible in TBEL mode, Test decoder function button at the bottom', caption: 'Enter a converter name, paste the decoder script, then click Test decoder function to verify the output before proceeding' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/kafka_uplink_test_decoder.png', alt: 'Test decoder function dialog — sample JSON payload entered in the Payload field on the left, decoded output on the right showing deviceName, deviceType, telemetry with Temperature, Humidity, Fan, Pressure, and other fields', caption: 'Test decoder function: paste the sample payload on the left and click Test — the decoded result appears on the right' },
-]} />
-
-<Steps>
-  <ol start="4">
     <li>
       <span><strong>Connection:</strong></span>
       <ul>
-        <li>Fill in <strong>Group ID</strong>, <strong>Client ID</strong>, <strong>Bootstrap servers</strong>, <strong>Poll interval</strong>, and <strong>Topics</strong>.</li>
+        <li>Fill in <strong>Group ID</strong>, <strong>Client ID</strong>, <strong>Bootstrap servers</strong>, <strong>Poll interval</strong>, and <strong>Topics</strong> — see <a href="#required-connection-details"><strong>Required Connection Details</strong></a> for the values to use.</li>
         <li>Toggle <strong>Auto create topics</strong> if the topic does not exist yet.</li>
-        <li>For Confluent Cloud or other secured brokers, expand <strong>Advanced settings</strong> and add SASL/SSL properties under <strong>Other properties</strong>.</li>
+        <li>For a secured broker, expand <strong>Advanced settings</strong> and add SASL/SSL properties under <strong>Other properties</strong>.</li>
       </ul>
-      <span>Read more about each parameter in <a href="#connection-settings">connection settings</a>.</span>
+      <span>Read more about each parameter in <a href="#connection-settings"><strong>connection settings</strong></a>.</span>
     </li>
     <li>Click <strong>Add</strong>.</li>
   </ol>
 </Steps>
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png', alt: 'Add integration wizard — Connection step: Group ID, Client ID, Bootstrap servers (YOUR_KAFKA_DOMAIN:9092), Poll interval 5000, Topics (my-topic), Auto create topics toggle off, Execute remotely collapsed, Add button', caption: 'Connection: fill in Group ID, Client ID, Bootstrap servers, Poll interval, and Topics, then click Add' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-1.png', alt: 'Add integration wizard — Basic settings step: Integration type Kafka, name Kafka integration, Enable integration and Allow create devices or assets toggled on', caption: 'Set Integration type to Kafka, enter a name, and click Next' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-2.png', alt: 'Add integration wizard — Uplink data converter step: Select existing active with Kafka Uplink Converter selected', caption: 'Click Select existing, choose Kafka Uplink Converter, and click Next' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-add-integration-3.png', alt: 'Add integration wizard — Connection step: Group ID, Client ID, Bootstrap servers, Poll interval, and Topics fields filled in', caption: 'Fill in Group ID, Client ID, Bootstrap servers, Poll interval, and Topics, then click Add' },
 ]} />
 
 <Aside type="note">
 Enable **Debug mode** during initial setup to inspect all incoming messages and converter execution logs on the integration's **Events** tab. Disable it in production — debug events are stored in the database and can quickly consume disk space.
 </Aside>
 
-#### Connection settings
+### Connection Settings
 
-<h4>Group ID</h4>
+| Parameter | Description |
+|-----------|-------------|
+| **Group ID** | A string you define; identifies the consumer group this integration belongs to (e.g. `thingsboard-kafka-group`). All instances sharing the same Group ID split the partition load, so each record is delivered to only one instance. |
+| **Client ID** | A string you define; labels this consumer client for monitoring and logging (e.g. `thingsboard-kafka-client-01`). Must be unique per running consumer if you need to distinguish instances in Kafka metrics. |
+| **Bootstrap Servers** | Comma-separated list of Kafka broker addresses in `host:port` format, e.g. `localhost:9092`. Used to establish the initial connection to the cluster. |
+| **Poll Interval** | How often the integration polls Kafka for new records, in milliseconds. Default: `5000`. |
+| **Topics** | Comma-separated list of Kafka topics to subscribe to, e.g. `my-topic`. |
+| **Auto Create Topics** | When enabled, ThingsBoard automatically creates any subscribed topics that do not already exist on the broker. |
+| **Other Properties** | Additional Kafka consumer properties as key-value pairs. Use this for security configuration such as SASL/SSL when connecting to a secured broker. The exact keys and values depend on your broker/provider — consult its documentation. |
+| **Execute Remotely** | When enabled, ThingsBoard generates an **Integration key** and **Integration secret**, letting the integration run as a separate process outside the ThingsBoard cluster — useful when it must reside in a DMZ or on an on-premises gateway. |
 
-A string you define — it identifies the consumer group this integration belongs to. You can use any value (e.g. `tb-kafka-group`). All integration instances sharing the same Group ID form a consumer group and split the partition load, so each message is delivered to only one instance.
+## Test the Integration
 
-<h4>Client ID</h4>
+Publish a test record to the topic the integration subscribes to, then optionally confirm it landed on the topic. Run the commands from the Kafka install directory (e.g. `/opt/kafka`).
 
-A string you define — it labels this consumer client for monitoring and logging purposes (e.g. `tb-kafka-client`). Must be unique per running consumer if you need to distinguish instances in Kafka metrics.
+<Aside type="note">
+  Enable **Debug mode** on the integration during setup to inspect all incoming records and converter output. Disable it in production — debug events are stored in the database and can quickly consume disk space.
+</Aside>
 
-<h4>Bootstrap servers</h4>
+### Produce a Test Record
 
-Comma-separated list of Kafka broker addresses in `host:port` format, e.g. `localhost:9092`. Used to establish the initial connection to the cluster.
+Use `kafka-console-producer.sh` to publish a test message. Replace `localhost:9092` with your broker address and `my-topic` with your configured topic if they differ:
 
-<h4>Poll interval (ms)</h4>
+```bash
+echo '{"EUI":"43T1YH-REE","ts":1638876127000,"data":"3d1f0059","port":10,"freq":24300,"rssi":-130,"serial":"230165HRT"}' | \
+  bin/kafka-console-producer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic my-topic > /dev/null
+```
 
-How often the integration polls Kafka for new messages. Default: `5000` ms.
+<ImageGallery images={[
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-1.png', alt: 'Terminal running kafka-console-producer.sh, piping a JSON test record to the my-topic topic on localhost:9092', caption: 'Publish the test record with kafka-console-producer.sh' },
+]} />
 
-<h4>Topics</h4>
+<h4>Verify the Record on the Topic (Optional)</h4>
 
-Comma-separated list of Kafka topics to subscribe to, e.g. `my-topic`.
+```bash
+bin/kafka-console-consumer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic my-topic \
+  --from-beginning
+```
 
-<h4>Auto create topics</h4>
+You should see the record echoed back:
 
-When enabled, ThingsBoard automatically creates any subscribed topics that do not already exist on the broker.
+```json
+{"EUI":"43T1YH-REE","ts":1638876127000,"data":"3d1f0059","port":10,"freq":24300,"rssi":-130,"serial":"230165HRT"}
+```
+
+<ImageGallery images={[
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-produce-test-record-2.png', alt: 'Terminal running kafka-console-consumer.sh with --from-beginning, echoing back the published JSON test record', caption: 'kafka-console-consumer.sh echoes back the published record' },
+]} />
 
-<h4 id="other-properties">Other properties</h4>
+<Aside type="note" title="Kafka 4.x console tools">
+  Use `--bootstrap-server` with the console producer and consumer — the older `--broker-list` and `--zookeeper` flags no longer exist in current Kafka tools (`--zookeeper` was removed from these commands back in Kafka 3.0, separate from ZooKeeper's later removal from the broker itself in 4.0). If the consumer prints `UNKNOWN_TOPIC_OR_PARTITION`, the topic name is wrong or the topic does not exist yet: create it (see [Create a Topic](#create-a-topic)) or enable **Auto create topics** in the integration.
+</Aside>
 
-Additional Kafka consumer properties as key-value pairs. Use this for security configuration such as SASL/SSL when connecting to Confluent Cloud or other secured brokers.
+### Verify Integration Events
 
-For **Confluent Cloud**, add the following four entries:
+Go to **Integrations center &#8702; Integrations**, open **Kafka integration**, and click the **Events** tab. With **Debug mode** on, each consumed record appears as an event with **Type**: **Uplink** and **Status**: **OK**. Click the **&#8942;** icon in the **Message** column to inspect the raw record the integration received from Kafka.
 
-| Key | Value |
-|-----|-------|
-| `ssl.endpoint.identification.algorithm` | `https` |
-| `sasl.mechanism` | `PLAIN` |
-| `sasl.jaas.config` | `org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";` |
-| `security.protocol` | `SASL_SSL` |
+<ImageGallery images={[
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-1.png', alt: 'Kafka integration Events tab — Debug event type showing one Uplink event with status OK', caption: 'Integration → Events — confirm the Uplink event with Status OK' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-integration-events-2.png', alt: 'Message dialog showing the raw Kafka record — EUI, ts, data, port, freq, rssi, and serial', caption: 'Click the Message column to inspect the raw record' },
+]} />
 
-Replace `CLUSTER_API_KEY` and `CLUSTER_API_SECRET` with the API key and secret from your Confluent Cloud cluster's **Data integration → API keys** section.
+### Verify Converter Events
 
-<h4>Execute remotely</h4>
+Go to **Integrations center &#8702; Data converters**, open **Kafka Uplink Converter**, and click the **Events** tab. Click **In** to see the raw Kafka record the decoder received (`EUI`, `ts`, `data`, `port`, `freq`, `rssi`, `serial`), and **Out** to see the decoded `deviceName`, `deviceType`, `attributes`, and `telemetry` it produced.
 
-When enabled, ThingsBoard generates an **Integration key** and **Integration secret**. These credentials allow the integration to run as a separate process outside the ThingsBoard cluster — useful for deployments where the integration must reside in a DMZ or on-premises gateway.
+<ImageGallery images={[
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-1.png', alt: 'Kafka Uplink Converter Events tab — Debug event type showing one Uplink event with In, Out, and Metadata columns', caption: 'Data converter → Events — one row per consumed record' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-2.png', alt: 'In dialog showing the raw Kafka record passed into the decoder — EUI, ts, data, port, freq, rssi, and serial', caption: 'Click In to see the raw record the decoder received' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-converter-events-3.png', alt: 'Out dialog showing the decoded payload — deviceName, deviceType Monitoring sensor, empty attributes, and telemetry values for Temperature, Humidity, Fan, Port, Freq, Pressure, rssi, and serial', caption: 'Click Out to see the decoded deviceName, deviceType, and telemetry values' },
+]} />
 
-## Confluent Cloud setup
+### Verify Device Provisioning
 
-<Steps>
-1. **Get the Bootstrap server address.**
-   Open your Confluent Cloud environment, click the cluster to enter it, then open **Cluster settings → General**. Copy the **Bootstrap server** value (`YOUR_DOMAIN.confluent.cloud:9092`) — paste it into the **Bootstrap servers** field in ThingsBoard.
-</Steps>
+Go to **Entities &#8702; Devices** — device `43T1YH-REE` (Device profile: `Monitoring sensor`) is auto-created on the first record. Open it and check the **Latest telemetry** tab — you should see all 8 decoded keys: `Temperature`, `Humidity`, `Fan`, `Port`, `Freq`, `Pressure`, `rssi`, and `serial`.
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_work_with_cluster_0.png', alt: 'Confluent Cloud — environment page listing cluster "cluster_TB" (Running, Azure, westeurope)', caption: 'Open your Confluent Cloud environment and click the cluster' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_work_with_cluster_1.png', alt: 'Side-by-side: Confluent Cloud Cluster settings showing Bootstrap server highlighted, and ThingsBoard integration Connection step with Bootstrap servers field filled from the same value', caption: 'Copy the Bootstrap server from Cluster settings and paste it into the Bootstrap servers field in ThingsBoard' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-device-provisioning-1.png', alt: 'ThingsBoard device 43T1YH-REE Latest telemetry tab showing 8 decoded keys — Fan, Freq, Humidity, Port, Pressure, rssi, serial, and Temperature', caption: 'Device → Latest telemetry — all 8 decoded keys reported' },
 ]} />
 
-<Steps>
-  <ol start="2">
-    <li>
-      <strong>Create an API key.</strong>
-      Go to <strong>Data integration → API keys</strong> and click <strong>Create key</strong>. Select <strong>Global access</strong> (development) or <strong>Granular access</strong> (production), complete the wizard, then copy the generated <strong>key</strong> and <strong>secret</strong>. Use them in <code>sasl.jaas.config</code>:
-      <Code code={'org.apache.kafka.common.security.plain.PlainLoginModule required username="YOUR_KEY" password="YOUR_SECRET";'} lang="text" wrap />
-    </li>
-  </ol>
-</Steps>
+## Configure Downlink
+
+The Kafka Integration has **no dedicated downlink converter**. To publish messages from ThingsBoard back to Kafka, use the <DocLink product={props.product} path="reference/rule-engine/nodes/external/kafka" target="_blank">Kafka Rule Node</DocLink> in the Rule Engine. The node takes the message payload, publishes it as the Kafka record value, and on broker acknowledgment adds `offset`, `partition`, and `topic` to the message metadata.
+
+The steps below test downlink entirely on the local setup — self-hosted ThingsBoard PE and the Kafka broker on the same machine. The idea: add a Kafka rule node that publishes to a **separate** downlink topic, then trigger it by updating a **shared attribute** on device `43T1YH-REE` and confirm the value with a console consumer.
+
+<Aside type="caution" title="Avoid message loops">
+  Do not subscribe the integration and the Kafka Rule Node to the **same topic** — each consumed record would trigger another publish to the same topic, causing runaway processing. Use a **separate downlink topic**.
+</Aside>
+
+### Prepare the Downlink Topic
+
+<h5>1. Create a Separate Downlink Topic</h5>
+
+Run from the Kafka install directory (e.g. `/opt/kafka`):
+
+```bash
+bin/kafka-topics.sh --create \
+  --topic my-topic-downlink \
+  --bootstrap-server localhost:9092 \
+  --partitions 1 \
+  --replication-factor 1
+```
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_API_keys_1.png', alt: 'Confluent Cloud — Data integration → API keys page with no keys yet and Create key button highlighted', caption: 'Navigate to Data integration → API keys and click Create key' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_API_keys_2.png', alt: 'Confluent Cloud — Create key wizard step 1: select scope — Global access (recommended for development) or Granular access (recommended for production)', caption: 'Select Global access for development or Granular access for production, then click Next' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-create-downlink-topic-1.png', alt: 'Terminal running kafka-topics.sh --create for topic my-topic-downlink, confirming Created topic my-topic-downlink', caption: 'kafka-topics.sh --create confirms the my-topic-downlink topic was created' },
 ]} />
 
-<Steps>
-  <ol start="3">
-    <li>
-      <strong>Create a topic.</strong>
-      Go to <strong>Topics</strong> and click <strong>Create topic</strong>. Enter a topic name (e.g. <code>my-topic</code>) and click <strong>Create with defaults</strong>. Use this name in the ThingsBoard integration <strong>Topics</strong> field.
-    </li>
-  </ol>
-</Steps>
+<h5>2. Start a Consumer on the Downlink Topic</h5>
+
+In a **second terminal**, leave a consumer running so you can watch messages arrive:
+
+```bash
+bin/kafka-console-consumer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic my-topic-downlink \
+  --from-beginning
+```
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_confluent_create_topic_0.png', alt: 'Confluent Cloud — Topics page with no topics yet and Create topic button highlighted', caption: 'Navigate to Topics and click Create topic' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_confluent_create_topic_1.png', alt: 'Confluent Cloud — New topic form: topic name "my-topic", 6 partitions, Create with defaults button highlighted; Topic Summary panel on the right shows default settings', caption: 'Enter the topic name (e.g. my-topic) and click Create with defaults' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-start-downlink-consumer-1.png', alt: 'Terminal running kafka-console-consumer.sh with --from-beginning on topic my-topic-downlink, waiting for messages', caption: 'Leave this consumer running to watch for messages on my-topic-downlink' },
 ]} />
 
+### Configure the Root Rule Chain
+
+<h5>Add and Configure the <DocLink product={props.product} path="reference/rule-engine/nodes/external/kafka" target="_blank">Kafka Rule Node</DocLink>:</h5>
+
 <Steps>
-  <ol start="4">
+  <ol>
+    <li>Go to <strong>Rule chains</strong> and open the <strong>Root Rule Chain</strong> (the chain that processes your device's messages).</li>
     <li>
-      <strong>Add SASL/SSL properties in ThingsBoard.</strong>
-      In the integration <strong>Connection</strong> step, expand <strong>Other properties</strong> and add the four entries from the <a href="#other-properties">table above</a>, replacing <code>CLUSTER_API_KEY</code> and <code>CLUSTER_API_SECRET</code> with the values from step 2.
+      In the node palette on the left, search for <strong>kafka</strong> — it appears under the <strong>External</strong> category — and drag it onto the canvas. In the node dialog, set:
+      <table>
+        <thead>
+          <tr><th>Field</th><th>Value for this setup</th></tr>
+        </thead>
+        <tbody>
+          <tr><td><strong>Name</strong></td><td><code>Kafka Downlink</code></td></tr>
+          <tr><td><strong>Topic pattern</strong></td><td><code>my-topic-downlink</code></td></tr>
+          <tr><td><strong>Key pattern</strong></td><td><em>(leave empty)</em></td></tr>
+          <tr><td><strong>Bootstrap servers</strong></td><td><code>localhost:9092</code></td></tr>
+          <tr><td><strong>Automatically retry times if fails</strong></td><td><code>0</code> (or default)</td></tr>
+          <tr><td><strong>Produces batch size in bytes</strong></td><td><code>16384</code> (default)</td></tr>
+          <tr><td><strong>Time to buffer locally (ms)</strong></td><td>default</td></tr>
+          <tr><td><strong>Client buffer max size in bytes</strong></td><td>default</td></tr>
+          <tr><td><strong>Number of acknowledgments</strong></td><td>default</td></tr>
+          <tr><td><strong>Other properties</strong></td><td><em>(leave empty — local <code>PLAINTEXT</code> broker needs no auth)</em></td></tr>
+        </tbody>
+      </table>
     </li>
+    <li>Click <strong>Add</strong>. The <strong>Topic pattern</strong> supports templates (e.g. <code>$&#123;deviceType&#125;-downlink</code>), but a static name is fine for testing.</li>
   </ol>
 </Steps>
 
+<h5>Wire the Node into the Rule Chain:</h5>
+
+The Kafka node publishes whatever message reaches it, so connect it to a message flow. For a quick end-to-end test, reuse the uplink you already have working:
+
+<Steps>
+  1. On the canvas, drag a connection from the **Message Type Switch** node to the new **Kafka** node.
+  2. In the relation dialog, select the **Attributes Updated** label and confirm.
+  3. Click **Apply changes** (top-right) to save the rule chain.
+</Steps>
+
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_integration_properties_1.png', alt: 'ThingsBoard Kafka integration Connection step — Other properties section expanded showing all four SASL/SSL key-value pairs: ssl.endpoint.identification.algorithm https, sasl.mechanism PLAIN, sasl.jaas.config with credentials, security.protocol SASL_SSL', caption: 'Expand Other properties in the Connection step and add all four SASL/SSL entries, replacing the placeholder credentials with your Confluent Cloud API key and secret' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-1.png', alt: 'Root Rule Chain node palette searched for kafka, showing the kafka node under External with its description tooltip mentioning offset, partition, and topic response fields', caption: 'Search for kafka in the node palette — it appears under External' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-2.png', alt: 'Add rule node: kafka dialog with Name Kafka Downlink, Topic pattern my-topic-downlink, Bootstrap servers localhost:9092, and default values for the remaining fields', caption: 'Add rule node: kafka — Name, Topic pattern, and Bootstrap servers filled in' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-configure-rule-chain-3.png', alt: 'Root Rule Chain canvas showing the Message Type Switch node connected to the kafka Kafka Downlink node via the Attributes Updated relation, with Apply changes highlighted', caption: 'Message Type Switch connected to Kafka Downlink via Attributes Updated' },
 ]} />
 
-## Send uplink message
+Now, whenever a shared attribute is updated on a device, its value is published to `my-topic-downlink`.
 
-<Tabs>
-<TabItem label="Standard Kafka">
+<Aside type="note" title="Restrict to shared scope (optional)">
+  `ATTRIBUTES_UPDATED` fires for both **shared** and **server** scope. If you want only shared-attribute changes, add a **script filter** node before the Kafka node that passes messages whose metadata `scope` equals `SHARED_SCOPE`. For a simple test you can skip this and just update shared attributes.
+</Aside>
 
-Use `kafka-console-producer.sh` to publish a test message. Replace `URL_OF_YOUR_BOOTSTRAP_SERVER` with your broker address and `my-topic` with your configured topic:
+### Trigger a Downlink
 
-```bash
-echo "{\"EUI\":\"43T1YH-REE\",\"ts\":1638876127000,\"data\":\"3d1f0059\",\"port\":10,\"freq\":24300,\"rssi\":-130,\"serial\":\"230165HRT\"}" | \
-  /usr/local/kafka/bin/kafka-console-producer.sh \
-  --broker-list URL_OF_YOUR_BOOTSTRAP_SERVER:9092 \
-  --topic my-topic > /dev/null
-```
+Update a shared attribute on device `43T1YH-REE`:
 
-</TabItem>
-<TabItem label="Confluent Cloud">
-
-In the Confluent Cloud web UI, open your topic and use the **Produce a new message** button on the **Messages** tab:
+<Steps>
+  1. Go to **Entities &#8702; Devices** and open **43T1YH-REE**.
+  2. Open the **Attributes** tab and set the scope selector to **Shared attributes**.
+  3. Click **+**, enter key `powerState`, value `on` (type String), and click **Add**.
+</Steps>
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_confluent_send_payload_to_tb_0.png', alt: 'Confluent Cloud — topic Messages tab with Produce a new message button visible', caption: 'Open the topic Messages tab and click Produce a new message' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_confluent_send_payload_to_tb_1.png', alt: 'Confluent Cloud — produce message form expanded on the topic Messages tab: JSON payload entered in the Value field, Produce button highlighted', caption: 'Paste the JSON payload into the Value field and click Produce' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/create_integration/kafka_confluent_send_payload_to_tb_2.png', alt: 'Confluent Cloud — message successfully produced confirmation', caption: 'Message produced — ThingsBoard will consume it within the next poll interval' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-trigger-downlink-1.png', alt: 'Add attribute dialog on device 43T1YH-REE — Entity attributes scope set to Shared attributes, Key powerState, type String, value on', caption: 'Add attribute — scope Shared attributes, key powerState, value on' },
 ]} />
 
-</TabItem>
-</Tabs>
+The attribute update flows through the rule chain, and the Kafka node publishes it to the downlink topic.
+
+### Verify Kafka Delivery
 
-Device **43T1YH-REE** is auto-created on the first uplink. Go to **Entities &#8702; Devices**, open the device, and check the **Latest telemetry** tab to confirm all decoded fields arrived correctly.
+Switch to the consumer terminal from **Start a Consumer on the Downlink Topic** — the record should appear on `my-topic-downlink`:
+
+```json
+{"powerState":"on"}
+```
 
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/kafka_integration_test_send_msg_result.png', alt: 'ThingsBoard Devices page — device 43T1YH-REE selected with Latest telemetry tab showing decoded values: Temperature, Humidity, Fan, Pressure, Port, Freq, rssi, and serial', caption: 'ThingsBoard auto-creates device 43T1YH-REE on the first message — open the device to confirm all decoded telemetry keys are present on the Latest telemetry tab' },
+  { src: '/src/assets/images/user-guide/integrations/kafka/kafka-verify-kafka-delivery-1.png', alt: 'Terminal running kafka-console-consumer.sh on my-topic-downlink, echoing back the published record powerState on', caption: 'kafka-console-consumer.sh echoes back the published record on my-topic-downlink' },
 ]} />
 
-## Downlink
+### Verify Rule Node Events
 
-The Kafka Integration does not have a dedicated downlink converter. To publish messages from ThingsBoard back to a Kafka topic, use the <DocLink product={props.product} path="reference/rule-engine/nodes/external/kafka">Kafka Rule Node</DocLink> in the rule engine.
+Open the Root Rule Chain, click the **Kafka Downlink** node, and open its **Events** tab. Each trigger produces two events — an **IN** event (**Relation Type**: Attributes Updated) for the message entering the node, and an **OUT** event (**Relation Type**: Success) for the published record. Click **Data** on the **OUT** event to see the published payload (e.g. `{"powerState":"on"}`), and **Metadata** to see the publish result — `offset`, `partition`, `topic`, the attribute `scope` (`SHARED_SCOPE`), and the user who made the change.
 
-<Aside type="caution">
-Do not subscribe the integration and the Kafka Rule Node to the **same topic** — this creates a message loop where each consumed message triggers another publish to the same topic, causing runaway processing.
+<Aside type="note" title="Enable Debug mode on the node">
+  The **Events** tab only logs entries while **Debug mode** is on for this specific node.
 </Aside>
 
-Configure the Kafka Rule Node with the same bootstrap servers and security properties as the integration, but point it to a **separate downlink topic**.
-
 <ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_0.png', alt: 'ThingsBoard rule chain editor — Kafka external rule node added at the end of the Monitoring-sensor rule chain, connected via Success relation after the TB Response node', caption: 'Add the Kafka rule node to the device rule chain and connect it after the node that produces the outgoing message' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_1.png', alt: 'ThingsBoard Kafka Downlink rule node configuration — Details tab showing topic pattern, bootstrap servers, key and value serializers, and Other properties section with all four SASL/SSL entries filled in', caption: 'Configure the node: set the downlink topic, bootstrap servers, serializers, and SASL/SSL Other properties for Confluent Cloud' },
+  {
+    src: '/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-1.png',
+    alt: 'Kafka Downlink rule node Events tab showing an IN event with Relation Type Attributes Updated and an OUT event with Relation Type Success',
+    caption: 'The Kafka Downlink node Events tab — one IN and one OUT event per trigger',
+  },
+  {
+    src: '/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-2.png',
+    alt: 'Data dialog showing the published payload — powerState on',
+    caption: 'Click Data on the OUT event to see the published payload',
+  },
+  {
+    src: '/src/assets/images/user-guide/integrations/kafka/kafka-downlink-node-events-3.png',
+    alt: 'Metadata dialog showing offset, partition, scope SHARED_SCOPE, topic my-topic-downlink, and the user who made the change',
+    caption: 'Click Metadata to see the publish result — offset, partition, topic, and scope',
+  },
 ]} />
 
-Enable **Debug mode** on the node. To verify messages are being published, open the node's **Events** tab — each processed message appears as a Debug entry. Expand an entry to inspect the payload. The Confluent Cloud topic Metrics will show a Production throughput spike when messages arrive.
+## Troubleshooting
 
-<ImageGallery images={[
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_node_2.png', alt: 'ThingsBoard Kafka Downlink rule node — Events tab with Debug filter active showing POST_TELEMETRY Success entries; Data popup open displaying the published JSON payload with deviceName, temperature, humidity, and other fields', caption: 'Kafka Downlink node Events tab — expand a Debug entry to view the published message payload' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_0.png', alt: 'ThingsBoard Kafka Downlink rule node — Events tab showing multiple POST_TELEMETRY Debug events; Data popup open with the full JSON payload including device name and telemetry values', caption: 'Multiple Debug events confirm the node is publishing messages — open any entry to inspect the exact payload sent to Confluent Cloud' },
-  { src: '/src/assets/images/user-guide/integrations/kafka/confluent/downlink/kafka_confluent_downlink_result_1.png', alt: 'Confluent Cloud — RESPONSE topic Metrics page, Production tab showing a throughput spike in the bytes-produced-per-second chart at the time ThingsBoard published the downlink messages', caption: 'Confluent Cloud RESPONSE topic Metrics — a spike in the Production throughput chart confirms the downlink messages arrived on the separate topic' },
-]} />
+This section covers the most common problems encountered when setting up and running the Kafka integration. Each entry describes the symptom, the most likely cause, and the steps to resolve it.
+
+<h4>No Records Consumed</h4>
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No records consumed in ThingsBoard | Wrong **Bootstrap servers** | Open the integration and confirm the broker `host:port` values match your cluster. |
+| No records consumed | Wrong **Topics** | Confirm the producer publishes to the same topic name configured in the integration. |
+| No records consumed | Topic does not exist | Enable **Auto create topics**, or create the topic on the broker manually. |
+| No records consumed | SASL/SSL misconfigured | For a secured broker, verify the **Other properties** entries (security protocol, SASL mechanism, credentials) match what your broker/provider requires. |
+| No records consumed | Integration is disabled | Open the integration and confirm **Enable integration** is on. |
+
+<h4>Record Consumed but Device Not Created</h4>
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Record consumed, no device in ThingsBoard | **Allow create devices or assets** is disabled | Open the integration, click the pencil icon, and enable **Allow create devices or assets** in the Basic settings step. |
+| Record consumed, no device in ThingsBoard | Converter returns an empty device name | Open the uplink converter **Events** tab and inspect the **Out** panel — confirm `deviceName` is present and non-empty. |
+| Record consumed, converter shows error | TBEL or JavaScript exception in the decoder | Open the uplink converter **Events** tab, filter by **Error**, and inspect the stack trace. Common causes: wrong byte offset, malformed JSON, or undefined field. |
+
+<h4>Downlink Not Published</h4>
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Kafka Rule Node Events tab is empty | Rule chain path never reaches the node | Confirm the node is connected after the node that produces the outgoing message via the correct relation. |
+| Runaway processing / message loop | Integration and Rule Node use the same topic | Point the Kafka Rule Node to a **separate downlink topic**. |
+| Node runs but nothing on the broker | Wrong bootstrap servers or serializers | Open the node's **Events → Out** panel and verify the topic, bootstrap servers, and serializers. |
+| Authentication errors to a secured broker | Missing/invalid SASL/SSL properties | Add the required SASL/SSL entries to the node's **Other properties** and verify the credentials against your broker/provider's documentation. |
+
+<h4>How to Read Debug Events</h4>
+
+<Steps>
+  1. Go to **Integrations center &#8702; Integrations**, open **Kafka integration**, and click the **Events** tab.
+  2. Click an event row to inspect:
+</Steps>
+
+- **In** — the raw record value received from Kafka before processing.
+- **Out** — what the converter returned: device name, attributes, and telemetry values passed to ThingsBoard.
+- **Error** — error text and stack trace, if processing failed.
+Enable **Debug mode** on the integration to capture all raw input/output events. Starting from ThingsBoard 3.9, full debug events are stored only during the first hour — afterwards, only error events are retained. Disable debug mode once the issue is identified.
+
+<Aside type="note" title="Debug mode causes high disk usage">
+  Disable debug mode in production. When active, every processed record is written to the database. Switch back to **Failures** mode once setup is confirmed.
+</Aside>
 
-## See also
+## See Also
 
-- <DocLink product={props.product} path="user-guide/integrations">Integration Overview</DocLink>
-- <DocLink product={props.product} path="user-guide/integrations/uplink-data-converter">Uplink Converters</DocLink>
-- <DocLink product={props.product} path="user-guide/rule-engine">Rule Engine</DocLink>
-- <DocLink product={props.product} path="reference/rule-engine/nodes/external/kafka">Kafka Rule Node</DocLink>
-- <DocLink product={props.product} path="user-guide/tbel">ThingsBoard Expression Language (TBEL)</DocLink>
+- <DocLink product={props.product} path="user-guide/integrations" target="_blank">Integrations Overview</DocLink> — how ThingsBoard connects to external platforms and how uplink/downlink flow works
+- <DocLink product={props.product} path="user-guide/integrations/uplink-data-converter" target="_blank">Uplink Data Converter</DocLink> — full decoder function reference: input parameters, output fields, and scripting patterns
+- <DocLink product={props.product} path="reference/rule-engine/nodes/external/kafka" target="_blank">Kafka Rule Node</DocLink> — publish messages from the Rule Engine back to a Kafka topic (downlink)
+- <DocLink product={props.product} path="user-guide/integrations/remote" target="_blank">Remote Integration</DocLink> — run the integration outside the ThingsBoard server to reach a broker on a private network
+- <DocLink product={props.product} path="user-guide/tbel" target="_blank">TBEL scripting reference</DocLink> — built-in functions and operators for writing converter scripts
+- <DocLink product={props.product} path="user-guide/rule-engine" target="_blank">Rule Engine</DocLink> — how the rule chain routes messages to the Kafka Rule Node
diff --git a/src/content/docs/docs/paas/eu/user-guide/integrations/kafka.mdx b/src/content/docs/docs/paas/eu/user-guide/integrations/kafka.mdx
index a118403b54..01659beea7 100644
--- a/src/content/docs/docs/paas/eu/user-guide/integrations/kafka.mdx
+++ b/src/content/docs/docs/paas/eu/user-guide/integrations/kafka.mdx
@@ -1,6 +1,6 @@
 ---
 title: Kafka Integration
-description: Connect ThingsBoard Cloud to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter.
+description: Connect ThingsBoard Cloud to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter, and publish commands back to Kafka using the Kafka Rule Node.
 ---
 import PageComponent from '@includes/docs/user-guide/integrations/kafka.mdx'
 import { Products } from '~/models/site.models'
diff --git a/src/content/docs/docs/paas/user-guide/integrations/kafka.mdx b/src/content/docs/docs/paas/user-guide/integrations/kafka.mdx
index b7404d071d..fedcb92d4b 100644
--- a/src/content/docs/docs/paas/user-guide/integrations/kafka.mdx
+++ b/src/content/docs/docs/paas/user-guide/integrations/kafka.mdx
@@ -1,6 +1,6 @@
 ---
 title: Kafka Integration
-description: Connect ThingsBoard Cloud to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter.
+description: Connect ThingsBoard Cloud to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter, and publish commands back to Kafka using the Kafka Rule Node.
 ---
 import PageComponent from '@includes/docs/user-guide/integrations/kafka.mdx'
 import { Products } from '~/models/site.models'
diff --git a/src/content/docs/docs/pe/user-guide/integrations/kafka.mdx b/src/content/docs/docs/pe/user-guide/integrations/kafka.mdx
index a57695048e..854679f72e 100644
--- a/src/content/docs/docs/pe/user-guide/integrations/kafka.mdx
+++ b/src/content/docs/docs/pe/user-guide/integrations/kafka.mdx
@@ -1,6 +1,6 @@
 ---
 title: Kafka Integration
-description: Connect ThingsBoard to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter.
+description: Connect ThingsBoard to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter, and publish commands back to Kafka using the Kafka Rule Node.
 ---
 import PageComponent from '@includes/docs/user-guide/integrations/kafka.mdx'
 import { Products } from '~/models/site.models'
diff --git a/src/content/docs/docs/user-guide/integrations/kafka.mdx b/src/content/docs/docs/user-guide/integrations/kafka.mdx
index e2a2d6ca50..fe22e0299b 100644
--- a/src/content/docs/docs/user-guide/integrations/kafka.mdx
+++ b/src/content/docs/docs/user-guide/integrations/kafka.mdx
@@ -1,6 +1,6 @@
 ---
 title: Kafka Integration
-description: Connect ThingsBoard to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter.
+description: Connect ThingsBoard to Apache Kafka message brokers to consume device telemetry from topics via an uplink converter, and publish commands back to Kafka using the Kafka Rule Node.
 ---
 import PageComponent from '@includes/docs/user-guide/integrations/kafka.mdx'
 import { Products } from '~/models/site.models'