Add a getting-started guide for the NXP FRDM i.MX 93, and fix its console device

[jetm]

What this fixes

The FRDM i.MX 93 had no getting-started page. Every other board with hardware on a desk has one - the Pi, Jetson, qemu - and this board's hardware page instead sent readers to the generic target selector, which asks them to pick a target and hands back three commands. Someone holding the board could not get from it to a running system without filling in the gaps themselves.

It also documented the wrong serial device. The entry said /dev/ttyUSB0; this board carries its console on the onboard USB-C port and enumerates as two CDC-ACM devices, so anyone following it opened a device that does not exist and got a dead terminal with nothing explaining why.

Changes

• New getting-started/frdm-imx93, following the Raspberry Pi page: prerequisites, serial console, initialize, install, build, provision, run, SSH. Plus a container section, since a board that keeps running a workload across a power cycle is what people are evaluating.
• Serial entry corrected to ttyACM0, leading with the stable by-id path - the ttyACM number moves as soon as another USB serial device is attached.
• Hardware page now links to the guide instead of repeating a shortened version of it, matching how the other boards are laid out.
• Target metadata points at the new guide rather than the selector, and the generated snapshot is refreshed to match.

Three details in the container section are called out because each fails silently rather than loudly, and all three cost hardware time to find: the unit must sit under overlay/usr/lib/systemd/system where enable_services looks for it; types needs both sysext and confext, because the unit ships in one and its enablement symlink is written into the other; and Restart=always rather than on-failure, since --rm plus Type=simple leaves a cleanly-exited container's unit inactive with nothing to restart it.

Verified

make build passes and both pages render. The serial device, the boot output and the container behaviour were all taken from a board rather than written from the datasheet.

The guide deliberately does not link the container dev mode guide: that page is still draft on its own branch, and onBrokenLinks is throw, so linking it fails the build from main.

[nicksinas]

Does this leverage the existing way we handle Getting Started? Its done dynamically, but custom per target. We only have a few targets we pin in the left side nav.

[jetm]

@nicksinas Yes — same pattern as the Pi/Jetson/qemu pages. Those are the small pinned set that sit next to the dynamic per-target generator rather than replacing it; this joins that set rather than bypassing it. Nothing about the dynamic selector changes.

Separate from the draft status: can you boot whatever's currently on your FRDM i.MX 93 (doesn't need to be our BSP) and paste back:

cat /sys/devices/soc0/soc_id
cat /sys/devices/soc0/revision
dmesg | grep -i imx93

This PR is waiting on meta-avocado#259, which only boots on Rev1.2 silicon — the 6.6.36 BSP your board might currently have doesn't get far enough to boot on that revision. If your board comes back as something earlier than 1.2, that changes what "waiting on #259" actually means for you, so I'd rather know now than after it un-drafts.

[nicksinas]

@jetm I would not add this target to the side nav. I think we reserve that for imx95-frdm as its more popular than the 93. I would keep this update in the dynamic section/UI only.

[jetm]

@nicksinas Done - dropped it from the pinned Getting Started list, kept imx95-frdm's future slot open. The page itself stays (still linked from the hardware page and from targets.json's gettingStartedUrl), just not in the hand-picked sidebar set anymore. npm run build passes. Let me know if that's not what you meant.

Un-drafting this now. Not gating it on the board-revision question from my last comment - I've asked for that a few times over the past two weeks with no reply, and nothing in this PR depends on the answer either way.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a dedicated “Getting Started” guide for the NXP FRDM i.MX 93 and updates the target metadata to reflect the board’s onboard USB-C serial console.

Changes:

• Update FRDM i.MX 93 target serial settings to onboard USB-C CDC-ACM and add a detailed serial-console description.
• Point FRDM i.MX 93 target metadata and board page to a new FRDM-specific getting-started guide.
• Add a new FRDM i.MX 93 getting-started guide covering init/build/provision/run and persistent container deployment.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/src/data/hardware/targets.json	Updates FRDM i.MX 93 serial console metadata and links to the new getting-started guide.
src/src/data/hardware/generated-targets.json	Mirrors the FRDM i.MX 93 metadata changes in the generated hardware index.
src/docs-hardware/nxp/frdm-imx-93/index.mdx	Replaces generic getting-started steps with a pointer to the FRDM-specific guide and updated quickstart commands.
src/docs-guides/getting-started/frdm-imx93.mdx	New end-to-end getting-started guide for the FRDM i.MX 93 including serial console and container persistence.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Suppressed comments (4)

src/src/data/hardware/targets.json:562

• This description is very long and includes multi-step guidance that’s likely duplicated in the new getting-started guide. If this field is rendered in a compact UI (cards/tables/tooltips), it may become hard to read and maintain. Consider shortening this to a brief summary and linking users to gettingStartedUrl for the full instructions.

      "description": "The board carries its debug console on the onboard USB-C port, so no separate TTL adapter is needed. It enumerates as two CDC-ACM devices and the Linux console is the first one. Prefer the by-id path over the ttyACM number, which moves when other USB serial devices are attached: `tio -b 115200 /dev/serial/by-id/usb-1a86_USB_Dual_Serial_*-if00`. Run `ls /dev/serial/by-id/` to see the serial number for your board."

src/docs-guides/getting-started/frdm-imx93.mdx:20

• The guide lists macOS as a supported host OS, but the serial console instructions shown are Linux-specific (/dev/serial/by-id). Add an explicit Linux-only note and provide macOS-equivalent device discovery/paths (e.g., /dev/cu.*) or clarify that the detailed serial steps below assume Linux.

- A USB-C cable (the board's debug console and power)
- macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)

src/docs-guides/getting-started/frdm-imx93.mdx:30

• The guide lists macOS as a supported host OS, but the serial console instructions shown are Linux-specific (/dev/serial/by-id). Add an explicit Linux-only note and provide macOS-equivalent device discovery/paths (e.g., /dev/cu.*) or clarify that the detailed serial steps below assume Linux.
  src/docs-guides/getting-started/frdm-imx93.mdx:98
• The example login banner hard-codes Avocado OS 0.0.0, which is likely to become stale quickly and may confuse users if their output differs. Consider using a placeholder (e.g., <version>) or omitting the version number from the snippet.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (7)

src/src/data/hardware/targets.json:562

• The serial command still points at /dev/ttyUSB0, which contradicts the new description (CDC-ACM + prefer /dev/serial/by-id/...-if00) and will keep showing the wrong device path in consumers of targets.json (e.g., the TargetSelector). Update the command to match the documented device path pattern.

      "onboard": true,
      "baud": 115200,
      "command": "tio -b 115200 /dev/ttyUSB0",
      "description": "The board carries its debug console on the onboard USB-C port, so no separate TTL adapter is needed. It enumerates as two CDC-ACM devices and the Linux console is the first one. Prefer the by-id path over the ttyACM number, which moves when other USB serial devices are attached: `tio -b 115200 /dev/serial/by-id/usb-1a86_USB_Dual_Serial_*-if00`. Run `ls /dev/serial/by-id/` to see the serial number for your board."

src/src/data/hardware/generated-targets.json:315

• Same as targets.json: the generated snapshot still uses /dev/ttyUSB0 for this board's serial command, which conflicts with the updated CDC-ACM/by-id guidance. Regenerate or update this entry so the displayed command matches the guide.

      "onboard": true,
      "baud": 115200,
      "command": "tio -b 115200 /dev/ttyUSB0",
      "description": "The board carries its debug console on the onboard USB-C port, so no separate TTL adapter is needed. It enumerates as two CDC-ACM devices and the Linux console is the first one. Prefer the by-id path over the ttyACM number, which moves when other USB serial devices are attached: `tio -b 115200 /dev/serial/by-id/usb-1a86_USB_Dual_Serial_*-if00`. Run `ls /dev/serial/by-id/` to see the serial number for your board."

src/docs-guides/getting-started/frdm-imx93.mdx:29

• SerialConsoleOptional describes a UART-to-USB adapter being optional, but this board's console is over the onboard USB-C port (no TTL adapter). Replacing the shared callout with a board-specific note avoids contradictory guidance in the Serial console section.

## Serial console

<SerialConsoleOptional />

The board carries its debug console on the onboard USB-C port, so no separate TTL adapter is needed. It enumerates as **two** CDC-ACM devices and the Linux console is the first of them.

src/docs-guides/getting-started/frdm-imx93.mdx:144

• After adding the var_files requirement for docker_images, this section should no longer say there are only three quiet failure points, and it should explicitly call out var_files as one of them (otherwise readers may still end up with a non-working pre-seeded cache).

Three details decide whether this works, and each one fails quietly rather than loudly:

- **The unit belongs at `overlay/usr/lib/systemd/system/my-app.service`.** That is where `enable_services` looks for it in order to write the enablement symlink.
- **`types` needs both `sysext` and `confext`.** The unit ships in the sysext under `/usr/lib`; the enablement symlink is written under `/etc`, which is confext territory. With only one of the two, the unit is present on the device but never starts.
- **`docker_images` is honored on a runtime build.** It pulls the image into the `/var` partition at build time, so a freshly provisioned board runs it without ever contacting a registry.

src/src/data/hardware/targets.json:560

• Setting serial.onboard: true will make the TargetSelector render an "Optional: serial console" note that currently says "Connect the Micro USB cable" (see src/src/components/TargetSelector/index.js:297-302). This board uses USB-C for console, so the UI copy becomes incorrect when this flag is enabled. Consider updating the TargetSelector text to be cable/port-agnostic (or driven by a new field like serial.cable), otherwise readers will be told to use the wrong connector.

      "onboard": true,
      "baud": 115200,

src/docs-guides/getting-started/frdm-imx93.mdx:9

• After replacing the serial-console callout, the SerialConsoleOptional import becomes unused and should be removed to keep the MDX clean and avoid lint/build warnings (depending on configuration).

This issue also appears on line 25 of the same file.

import HostPrerequisites from '@site/src/components/shared/HostPrerequisites'
import SerialConsoleOptional from '@site/src/components/shared/SerialConsoleOptional'

src/docs-guides/getting-started/frdm-imx93.mdx:131

• This example declares docker_images but omits the required var_files exclusion for Docker storage (var/lib/docker/**). Existing docs and the config schema indicate docker_images requires var_files so the Docker data ends up on the writable /var partition rather than being baked into the read-only extension image.

This issue also appears on line 140 of the same file.

    docker_images:
      - image: docker.io/<org>/<image>
        tag: <tag>