feature: add support for parsing boards, defconfigs and archs

docs/source/api_examples.md

@@ -100,3 +100,36 @@ for path in copied_paths:
 # Clean up when done
 cleanup_tmp_copies(copied_paths)
 ```
+
+## List available boards and defconfigs with Board Explorer
+
+The NuttxBoardExplorer allows the user to retrieve a list of boards, which
+can be filtered by arch, soc or individual board. Each returned board has
+a list of all defconfigs, which can be iterated and its content can be retrieved.
+
+This example demonstrates how to discover boards and defconfigs available
+in an existing NuttX repository using the lightweight helpers in
+`ntxbuild.nuttx`.
+
+```python
+from pathlib import Path
+from ntxbuild.nuttx import NuttxBoardExplorer
+
+# Path to the nuttx repository inside your nuttxspace
+nuttx_repo = Path.cwd() / "nuttx"
+
+# Create a filter and list all boards for a specific architecture
+nbf = NuttxBoardExplorer(nuttx_repo)
+boards = nbf.set_arch("arm").boards
+
+for board in boards:
+    print(f"Board: {board.name} (arch={board.arch} soc={board.soc})")
+    for cfg in board.defconfigs:
+        print(f"  - defconfig: {d.name}")
+        # optionally read the defconfig content
+        # print(d.content)
+
+# You can also find boards by soc or by exact board name
+boards_by_soc = nbf.set_soc("stm32").boards
+boards_by_name = nbf.set_board("nuttx-stm32").boards
+```

docs/source/features.md

@@ -39,6 +39,19 @@ See usage examples on {doc}`api_examples`.
 - Configurable target directory
 - Automatic cleanup
 
+## Board Explorer
+
+The Board Explorer feature provides a simple way to discover and inspect
+the boards and available defconfigs inside a NuttX repository. It is available
+both through the CLI (commands that list boards) and the Python API
+(see `ntxbuild.nuttx` helpers).
+
+- Quickly find which boards support a particular architecture or SoC.
+- Programmatically build a list of candidate boards for automated testing or
+	CI matrix generation.
+- Provide a lightweight UI (or CLI output) that helps users choose a board
+	and defconfig before running `start` or `build` commands.
+
 ## Curses Support
 Menuconfig works just as usual through this tool.
 

docs/source/ntxbuild.rst

@@ -73,6 +73,17 @@ Utilities Module
    :show-inheritance:
    :undoc-members:
 
+NuttX Module
+---------------------
+
+Utilities for discovering and representing NuttX boards and defconfigs. This
+module provides small data classes to represent boards under `<nuttxspace>/nuttx/boards`.
+
+.. automodule:: ntxbuild.nuttx
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 Module contents
 ---------------
 

docs/source/quick_start.md

@@ -79,6 +79,68 @@ builder.build(parallel=10)
 builder.distclean()
 ```
 
+## View Available Boards and Configs
+It is possible to quickly see a table of available boards for a SoC or defconfigs for a board.
+
+For the board list, provide the SoC name as in `boards/<arch>/<soc>`.
+```bash
+$ ntxbuild list boards qemu
+╒═════════════╕
+│ Boards      │
+╞═════════════╡
+│ qemu-armv7a │
+├─────────────┤
+│ qemu-armv7r │
+├─────────────┤
+│ qemu-armv8a │
+├─────────────┤
+│ qemu-i486   │
+╘═════════════╛
+Total boards: 4
+
+$ ntxbuild list boards esp32c6
+╒═════════════════╕
+│ Boards          │
+╞═════════════════╡
+│ esp32c6-devkitc │
+├─────────────────┤
+│ esp32c6-devkitm │
+├─────────────────┤
+│ esp32c6-xiao    │
+╘═════════════════╛
+Total boards: 3
+```
+
+To view defconfigs, use the board name under `boards/<arch>/<soc>/<board>`.
+
+```
+$ ntxbuild list defconfigs esp32c6-devkitc
+╒══════════════════════╤════════════════════╕
+│ Defconfigs           │ Defconfigs         │
+╞══════════════════════╪════════════════════╡
+│ adc                  │ bmp180             │
+├──────────────────────┼────────────────────┤
+│ buttons              │ capture            │
+├──────────────────────┼────────────────────┤
+│ crypto               │ efuse              │
+├──────────────────────┼────────────────────┤
+│ gpio                 │ i2c                │
+|──────────────────────┼────────────────────┤
+[...]
+|──────────────────────┼────────────────────┤
+│ twai                 │ ulp                │
+├──────────────────────┼────────────────────┤
+│ usbconsole           │ watchdog           │
+├──────────────────────┼────────────────────┤
+│ wifi                 │                    │
+╘══════════════════════╧════════════════════╛
+╒═════════╤═════════════════╤════════╤═════════╤════════════════════════════════╕
+│   Total │ Board           │ Arch   │ Soc     │ Path (nuttx/boards/)           │
+╞═════════╪═════════════════╪════════╪═════════╪════════════════════════════════╡
+│      37 │ esp32c6-devkitc │ risc-v │ esp32c6 │ risc-v/esp32c6/esp32c6-devkitc │
+╘═════════╧═════════════════╧════════╧═════════╧════════════════════════════════╛
+```
+
 ## Downloading Toolchains
 To visualize currently available toolchains, execute the `toolchain list` command:
 

ntxbuild/cli.py

@@ -12,6 +12,7 @@
 from .build import BuildTool, nuttx_builder
 from .config import ConfigManager
 from .env_data import clear_ntx_env, create_base_env_file, load_ntx_env
+from .nuttx import NuttxBoardExplorer
 from .setup import download_nuttx_apps_repo, download_nuttx_repo
 from .toolchains import ManagePath, ToolchainInstaller
 from .utils import NUTTX_APPS_DEFAULT_DIR_NAME, NUTTX_DEFAULT_DIR_NAME, find_nuttx_root
@@ -512,5 +513,77 @@ def menuconfig(menuconfig):
         sys.exit(1)
 
 
+@main.group()
+def list():  # noqa: F811
+    """List available boards and defconfigs.
+
+    Provides commands to list boards and defconfigs in the NuttX repository.
+    """
+    pass
+
+
+@list.command()
+@click.argument("soc")
+@click.option("--nuttx-dir", help="NuttX directory", default=NUTTX_DEFAULT_DIR_NAME)
+@click.option("--apps-dir", help="Apps directory", default=NUTTX_APPS_DEFAULT_DIR_NAME)
+def boards(soc, nuttx_dir, apps_dir):
+    """List available boards for a specific SoC/chip.
+
+    Example usage:
+        ntxbuild list boards <soc>
+    """
+    current_dir = Path.cwd()
+    logger.debug(f"Search for nuttx directory in: {current_dir}")
+
+    # This validates the directory structure. We don't use prepare_env
+    # because we don't need to load the environment just to check
+    # available boards.
+    nuttxspace = find_nuttx_root(current_dir, nuttx_dir, apps_dir)
+
+    try:
+        nuttx_path = nuttxspace / nuttx_dir
+        explorer = NuttxBoardExplorer(nuttx_path)
+        boards_list = explorer.set_soc(soc).boards
+        if not boards_list:
+            click.echo(f"No boards found for SoC: {soc}")
+            sys.exit(0)
+        explorer.print_board_summary()
+        sys.exit(0)
+    except Exception as e:
+        click.echo(f"❌ {e}")
+        sys.exit(1)
+
+
+@list.command()
+@click.argument("board")
+@click.option("--nuttx-dir", help="NuttX directory", default=NUTTX_DEFAULT_DIR_NAME)
+@click.option("--apps-dir", help="Apps directory", default=NUTTX_APPS_DEFAULT_DIR_NAME)
+def defconfigs(board, nuttx_dir, apps_dir):
+    """List available defconfigs for a specific board.
+
+    Example usage:
+        ntxbuild list defconfigs <board>
+    """
+    current_dir = Path.cwd()
+    logger.debug(f"Search for nuttx directory in: {current_dir}")
+
+    # This validates the directory structure. We don't use prepare_env
+    # because we don't need to load the environment just to check
+    # available defconfigs.
+    nuttxspace = find_nuttx_root(current_dir, nuttx_dir, apps_dir)
+    try:
+        nuttx_path = nuttxspace / nuttx_dir
+        explorer = NuttxBoardExplorer(nuttx_path)
+        boards_list = explorer.set_board(board).boards
+        if not boards_list:
+            click.echo(f"Board not found: {board}")
+            sys.exit(0)
+        boards_list[0].print_defconfig_summary()
+        sys.exit(0)
+    except Exception as e:
+        click.echo(f"❌ {e}")
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     main()