ili9341: add optional madctl kwarg, remove hardcoded writes

Author: ritesh006

README.rst

@@ -64,6 +64,36 @@ Usage Example
     while True:
         pass
 
+Custom MADCTL Example
+---------------------
+
+The driver accepts an optional ``madctl`` keyword argument. If provided, the driver writes
+this value directly to the MADCTL register (0x36) during initialization. If omitted, the
+driver leaves MADCTL unchanged.
+
+This allows advanced users to apply hardware-level rotations or control BGR/RGB order
+without relying on displayio’s software rotation. Using MADCTL can improve performance
+when displaying large bitmaps (e.g. with ``OnDiskBitmap``).
+
+
+.. code-block:: python
+
+    import board
+    import displayio
+    import fourwire
+    import adafruit_ili9341
+
+    spi = board.SPI()
+    tft_cs = board.D9
+    tft_dc = board.D10
+
+    displayio.release_displays()
+    display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs)
+
+    # Pass a custom MADCTL value (example: 0b01011000)
+    # Note: if you don't pass madctl, the driver does not modify the register.
+    display = adafruit_ili9341.ILI9341(display_bus, width=320, height=240, madctl=0b01011000)
+
 Documentation
 =============
 

adafruit_ili9341.py

@@ -92,15 +92,39 @@ class ILI9341(BusDisplay):
     ILI9341 display driver
 
     :param FourWire bus: bus that the display is connected to
+    :param bool bgr: Use BGR color order instead of RGB
+    :param bool invert: Invert the display
+    :keyword int madctl: (optional) Raw value to write to the MADCTL register (0x36). If provided, the driver emits a MADCTL write during init; if omitted, the driver leaves MADCTL unchanged.
+
     """
 
-    def __init__(self, bus: FourWire, *, bgr: bool = False, invert: bool = False, **kwargs: Any):
-        init_sequence = _INIT_SEQUENCE
-        if bgr:
-            init_sequence += b"\x36\x01\x30"  # _MADCTL Default rotation plus BGR encoding
-        else:
-            init_sequence += b"\x36\x01\x38"  # _MADCTL Default rotation plus RGB encoding
+    def __init__(
+        self,
+        bus: FourWire,
+        *,
+        bgr: bool = False,
+        invert: bool = False,
+        **kwargs: Any,
+    ):
+        
+        # Accept optional raw MADCTL via kwargs (requested by maintainers)
+        madctl = kwargs.pop("madctl", None)
+
+        # Start with base init sequence
+        init_sequence = bytearray(_INIT_SEQUENCE)
+
+        # Only touch MADCTL if caller explicitly provided it via kwargs
+        if madctl is not None:
+            try:
+                idx = init_sequence.index(0x36)  # MADCTL command
+                init_sequence[idx + 1] = 0x01    # data length
+                init_sequence[idx + 2] = madctl & 0xFF
+            except ValueError:
+                # Not present — append a single-byte MADCTL write
+                init_sequence += bytes((0x36, 0x01, madctl & 0xFF))
+
+        # Inversion
         if invert:
-            init_sequence += b"\x21\x00"  # _INVON
+            init_sequence += b"\x21\x00"
 
         super().__init__(bus, init_sequence, **kwargs)

madctl_kwargs.patch

@@ -0,0 +1,66 @@
+diff --git a/adafruit_ili9341.py b/adafruit_ili9341.py
+--- a/adafruit_ili9341.py
++++ b/adafruit_ili9341.py
+@@ -131,11 +131,12 @@ class ILI9341(BusDisplay):
+     :param FourWire bus: bus that the display is connected to
+     :param bool bgr: Use BGR color order instead of RGB
+     :param bool invert: Invert the display
+-    :param int madctl: Optional custom MADCTL value to override rotation/scan order bits
++    :keyword int madctl: (optional) Raw value to write to the MADCTL register (0x36).
++        If provided, the driver emits a MADCTL write during init. If omitted,
++        the driver will not alter MADCTL.
+     """
+ 
+     def __init__(
+         self,
+         bus: FourWire,
+         *,
+         bgr: bool = False,
+         invert: bool = False,
+-        madctl: int | None = None,
+         **kwargs: Any,
+     ):
+-        # Start with base init sequence
++        # Accept optional raw MADCTL via kwargs (requested by maintainers)
++        madctl = kwargs.pop("madctl", None)
++        # Start with base init sequence
+         init_sequence = bytearray(_INIT_SEQUENCE)
+ 
+-        # --- Replace existing MADCTL instead of appending ---
+-        # Find MADCTL (0x36) in init sequence
+-        try:
+-            idx = init_sequence.index(0x36)
+-            # Overwrite the length (always 1) + value
+-            if madctl is not None:
+-                init_sequence[idx + 1] = 0x01
+-                init_sequence[idx + 2] = madctl
+-            elif bgr:
+-                init_sequence[idx + 1] = 0x01
+-                init_sequence[idx + 2] = 0x30  # BGR encoding
+-            else:
+-                init_sequence[idx + 1] = 0x01
+-                init_sequence[idx + 2] = 0x38  # RGB encoding
+-        except ValueError:
+-            # If no MADCTL present, append it
+-            if madctl is not None:
+-                init_sequence += bytes([0x36, 0x01, madctl])
+-            elif bgr:
+-                init_sequence += b"\x36\x01\x30"
+-            else:
+-                init_sequence += b"\x36\x01\x38"
++        # Only touch MADCTL if caller explicitly provided it via kwargs
++        if madctl is not None:
++            # If MADCTL (0x36) already exists, overwrite its single data byte
++            try:
++                idx = init_sequence.index(0x36)
++                init_sequence[idx + 1] = 0x01  # data length
++                init_sequence[idx + 2] = madctl & 0xFF
++            except ValueError:
++                # Not present — append a single-byte MADCTL write
++                init_sequence += bytes((0x36, 0x01, madctl & 0xFF))
+ 
+         # Inversion
+         if invert:
+             init_sequence += b"\x21\x00"
+ 
+         super().__init__(bus, init_sequence, **kwargs)

pyproject.toml

@@ -46,3 +46,16 @@ py-modules = ["adafruit_ili9341"]
 [tool.setuptools.dynamic]
 dependencies = {file = ["requirements.txt"]}
 optional-dependencies = {optional = {file = ["optional_requirements.txt"]}}
+
+[tool.ruff]
+# Enable default linting rules
+select = ["E", "F"]
+
+# Ignore specific rules if needed
+ignore = []
+
+# Allow fixing issues automatically with `ruff check --fix`
+fix = true
+
+# Formatting (instead of Black)
+line-length = 88

test_madctl.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2025 Ritesh
+#
+# SPDX-License-Identifier: MIT
+
+import pytest
+
+from adafruit_ili9341 import ILI9341
+
+
+class DummyBus:
+    """A fake bus to avoid hardware dependency."""
+
+    def __init__(self):
+        self.commands = []
+
+    def send(self, *args, **kwargs):
+        self.commands.append((args, kwargs))
+
+
+def extract_madctl_bytes(init_seq: bytes) -> bytes | None:
+    """
+    Helper to find MADCTL command (0x36) in the init sequence.
+    Returns 2 bytes: [0x36, value] or None if not present.
+    """
+    for i in range(len(init_seq) - 2):
+        if init_seq[i] == 0x36:
+            return init_seq[i : i + 3]
+    return None
+
+
+def test_default_rgb_encoding():
+    bus = DummyBus()
+    disp = ILI9341(bus)
+    madctl = extract_madctl_bytes(disp.init_sequence)
+    assert madctl == b"\x36\x01\x38"  # Default RGB
+
+
+def test_bgr_encoding():
+    bus = DummyBus()
+    disp = ILI9341(bus, bgr=True)
+    madctl = extract_madctl_bytes(disp.init_sequence)
+    assert madctl == b"\x36\x01\x30"  # BGR mode
+
+
+def test_custom_madctl():
+    bus = DummyBus()
+    disp = ILI9341(bus, madctl=0b01011000)
+    madctl = extract_madctl_bytes(disp.init_sequence)
+    assert madctl == bytes([0x36, 0x01, 0b01011000])  # Custom override