i2c embedded rust ecosystem flow chart

src/i2c/i2c-and-rust.md

@@ -47,6 +47,9 @@ It provides wrapper types like AtomicDevice, CriticalSectionDevice, and RefCellD
 
 You can use I2C in two ways:
 
+<img style="display: block; margin: auto;" alt="I2C Single Controller Multiple Devices" src="./images/i2c-embedded-hal-rust-ecosystem.svg"/>
+
+
 - Without sharing: If your application only talks to one I2C device, you can pass the I2C bus instance provided by the HAL (which implements the I2c trait) directly to the driver.
 
 - With sharing: If your application needs to communicate with multiple I2C devices on the same bus, you can wrap the I2C bus instance (provided by the HAL) using one of the sharing types from the embedded-hal-bus crate, such as AtomicDevice or CriticalSectionDevice. This allows safe, coordinated access across multiple drivers.

src/i2c/images/i2c-embedded-hal-rust-ecosystem.svg

@@ -0,0 +1,65 @@
+<svg width="800" height="880" xmlns="http://www.w3.org/2000/svg">
+<!--
+  Source: https://github.com/ImplFerris/ImplFerris
+  Copyright (c) 2025 implrust.com
+  Licensed under CC BY-SA 4.0
+-->
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="6" refX="4" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#ba7d18"/>
+    </marker>
+    <style>
+      .box { rx:14; ry:14; stroke:#444; stroke-width:1.8; fill-opacity:1 }
+      .label { font-family:sans-serif; font-size:16px; fill:#222 }
+      .sub   { font-family:sans-serif; font-size:14px; fill:#222 }
+      .arrow-label { font-family:sans-serif; font-size:13px; fill:#ba7d18;font-weight:bold }
+    </style>
+  </defs>
+
+  <!-- Microcontroller -->
+  <rect x="250" y="20" width="300" height="160" fill="#ECEFF1" class="box"/>
+  <text x="400" y="70" text-anchor="middle" class="label">Microcontroller</text>
+  <rect x="300" y="105" width="200" height="50" fill="#AEDFF7" class="box"/>
+  <text x="400" y="135" text-anchor="middle" class="label">I2C Peripheral</text>
+
+  <!-- Arrow to HAL -->
+  <line x1="400" y1="180" x2="400" y2="235" stroke="#ba7d18" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <text x="410" y="210" class="arrow-label">Exposes hardware</text>
+
+  <!-- HAL -->
+  <rect x="250" y="240" width="300" height="120" fill="#C8E6C9" class="box"/>
+  <text x="400" y="280" text-anchor="middle" class="label">HAL</text>
+  <text x="400" y="305" text-anchor="middle" class="sub">implements I2c trait</text>
+  <text x="400" y="330" text-anchor="middle" class="sub">(hardware-specific)</text>
+
+  <!-- Fork arrows -->
+  <line x1="400" y1="360" x2="200" y2="415" stroke="#ba7d18" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <line x1="400" y1="360" x2="600" y2="415" stroke="#ba7d18" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <!-- Arrow labels -->
+  <text x="110" y="390" class="arrow-label">used directly</text>
+  <text x="610" y="390" class="arrow-label">wrapped for sharing</text>
+
+  <!-- Direct driver path -->
+  <rect x="70" y="420" width="260" height="120" fill="#FFCDD2" class="box"/>
+  <text x="200" y="465" text-anchor="middle" class="label">Driver</text>
+  <text x="200" y="490" text-anchor="middle" class="sub">uses I2c trait directly</text>
+  <text x="200" y="515" text-anchor="middle" class="sub">(simple / single device)</text>
+
+  <!-- embedded-hal-bus box -->
+  <rect x="470" y="420" width="260" height="120" fill="#FFE082" class="box"/>
+  <text x="600" y="460" text-anchor="middle" class="label">embedded-hal-bus</text>
+  <text x="600" y="490" text-anchor="middle" class="sub">provides shared bus implementations</text>
+  <text x="600" y="510" text-anchor="middle" class="sub">(e.g. AtomicDevice, RefCellDevice)</text>
+
+  <!-- Arrow from wrappers to shared driver -->
+  <line x1="600" y1="540" x2="600" y2="595" stroke="#ba7d18" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <text x="610" y="570" class="arrow-label">used via wrapper</text>
+
+  <!-- Shared driver path -->
+  <rect x="470" y="600" width="260" height="120" fill="#FFCDD2" class="box"/>
+  <text x="600" y="640" text-anchor="middle" class="label">Driver</text>
+  <text x="600" y="665" text-anchor="middle" class="sub">uses I2c trait via wrapper</text>
+  <text x="600" y="690" text-anchor="middle" class="sub">(sharing multiple devices)</text>
+</svg>
+