{"id":"cbaa02a7-4188-4c44-a4e8-e54e108420f6","slug":"linux-embedded-dev","kind":"skill","name":"linux-embedded-dev","summary":"A Codex skill for Linux embedded learning, bringup, debugging, source reading, and performance work. This skill is designed as a broad Linux embedded development companion rather than a narrow single-","owner":"heyu-233","repoUrl":"https://github.com/heyu-233/linux-embedded-dev","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-04-11T08:33:52.000Z","addedAt":"2026-10-21T22:54:04.083Z","logoUrl":"https://avatars.githubusercontent.com/u/180063967?u=7a752c96e7e70e923016727cd02bcffcc2fef333&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","productivity"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T22:33:18.525Z","sample":false,"url":"https://conduits.dev/tools/linux-embedded-dev","language":"Python","transports":["stdio"],"install":{"pypi":"debugctl"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# linux-embedded-dev\n\n> A Codex skill for Linux embedded bring-up, driver reading, board debugging, full-link diagnostics, and practical learning.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Codex Skill](https://img.shields.io/badge/Codex-Skill-111827.svg)](SKILL.md)\n[![Focus](https://img.shields.io/badge/Focus-Linux%20Embedded-0f766e.svg)](#what-it-helps-with)\n[![Camera Companion](https://img.shields.io/badge/Module-V4L2%20%2F%20Camera-7c3aed.svg)](references/camera-companion-index.md)\n\n`linux-embedded-dev` turns Codex into a structured Linux embedded development partner. It helps you move from scattered logs, device-tree fragments, shell commands, and driver code into a clear debugging path:\n\n```text\nidentify the layer -> ask for bounded evidence -> explain the system role -> take the next smallest step -> record what was learned\n```\n\nIt is built for real embedded work: vendor BSPs, old toolchains, DTS bring-up, `/dev` node mysteries, cross-compilation, rootfs integration, V4L2 camera paths, board-side scripts, and host-side full-link debug pipelines.\n\n## Why This Exists\n\nEmbedded Linux debugging is rarely one clean problem. A camera issue may actually be a device-tree endpoint issue. A userspace failure may be a probe-path issue. A \"works on the host\" binary may fail because of `glibc` or library ABI mismatch.\n\nThis skill gives Codex a reusable operating style for that world:\n\n- route the issue to the right layer first\n- teach the mental model without dumping a lecture\n- ask for small command outputs instead of giant logs\n- map DTS, driver, board, and userspace artifacts together\n- keep hard-won project knowledge in reusable notes\n\n## What It Helps With\n\n- Board bring-up and boot-chain debugging\n- Device tree, DTS, clocks, GPIO, regulators, reset, and pinctrl\n- Kernel driver and platform-code reading\n- Character device and platform driver learning paths\n- I2C, SPI, UART, MMC/SD bus debugging\n- Cross-compilation and target ABI compatibility\n- Root filesystem and userspace integration\n- Service startup, `/dev` nodes, logs, and process supervision\n- Performance and observability with bounded evidence\n- V4L2, media graph, sensor bring-up, and capture-path optimization\n- Host-to-VM-to-board full-link debug pipelines\n\n## Quickstart\n\nClone this repository into your Codex skills directory.\n\n```powershell\ngit clone https://github.com/heyu-233/linux-embedded-dev `\n  C:\\Users\\<your-user>\\.codex\\skills\\linux-embedded-dev\n```\n\nUnix-like systems:\n\n```bash\ngit clone https://github.com/heyu-233/linux-embedded-dev \\\n  ~/.codex/skills/linux-embedded-dev\n```\n\nThen invoke it explicitly:\n\n```text\nUse $linux-embedded-dev to debug why my DTS node probes but no /dev node appears.\n```\n\n## debugctl Prototype\n\nThe repository now includes a runnable Python prototype for `debugctl`.\n\nRun it from the repository root:\n\n```powershell\n$env:PYTHONPATH = \"$PWD\\src\"\npython -m debugctl status --target examples\\target.imx6ull.yaml\npython -m debugctl collect --target examples\\target.imx6ull.yaml --out .runtime\\latest\npython -m debugctl deploy --target examples\\target.imx6ull.yaml --artifact .\\build\\hello\npython -m debugctl run --target examples\\target.imx6ull.yaml --cmd \"./hello\"\npython -m debugctl diagnose --bundle .runtime\\latest\n```\n\nCurrent scope:\n\n- parses and validates target YAML\n- routes the Linux-board and MCU subcommands\n- probes `linux-board` targets over SSH in `status`\n- collects bounded remote evidence over SSH in `collect`\n- uploads artifacts with SCP and verifies remote SHA-256 in `deploy`\n- runs remote commands inside `runtime.workdir` in `run`\n- classifies evidence bundles into connectivity, missing-command, partial, or complete states in `diagnose`\n- checks MCU tool availability and exposes `flash`, `reset`, and `serial`\n\nNot implemented yet:\n\n- serial capture\n- richer MCU serial capture loop\n- richer board-side diagnosis rules\n- power control and multi-resource orchestration\n\n## The Default Working Loop\n\nThe skill is designed to keep each turn executable and small:\n\n```text\nMode: teaching or efficiency\nCurrent goal: what this turn is trying to confirm\nPrinciple in brief: where this step sits in the system\nDo this now: one command, one file, or one minimal edit\nSend back: the exact output needed for the next branch\n```\n\nThat loop is especially useful when working with a physical board, because every extra manual step costs time and every huge log dump creates noise.\n\n## Module Map\n\nStart with `references/module-index.md` when the right layer is unclear.\n\n| If the symptom looks like... | Start here |\n|---|---|\n| board does not boot, hangs early, bad bootargs | `references/boot-chain-and-startup.md` |\n| hardware exists but Linux does not bind it correctly | `references/device-tree-and-driver-workflow.md` |\n| I2C, SPI, UART, or MMC communication is unstable | `references/common-bus-debugging.md` |\n| probe succeeds but userspace still fails | `references/build-rootfs-userspace.md` |\n| learning platform drivers or char devices | `references/char-device-and-platform-driver-path.md` |\n| CPU, latency, frame rate, throughput, or stability | `references/perf-and-observability.md` |\n| camera, V4L2, media graph, sensor bring-up | `references/camera-companion-index.md` |\n| host terminal controls VM, board, backend, logs | `references/full-link-debug-pipeline.md` |\n\n## Development Notes\n\nThe current development direction is documented in:\n\n- `references/oss-reference-map.md`\n- `references/agent-architecture-notes.md`\n- `references/debugctl-cli-prototype.md`\n- `examples/oss-inspired-flows.md`\n- `examples/target.imx6ull.yaml`\n- `examples/target.stm32f103.yaml`\n\n## Repository Structure\n\n```text\nlinux-embedded-dev/\n|-- SKILL.md\n|-- README.md\n|-- LICENSE\n|-- agents/\n|   `-- openai.yaml\n|-- examples/\n|   |-- oss-inspired-flows.md\n|   |-- target.imx6ull.yaml\n|   `-- target.stm32f103.yaml\n`-- references/\n    |-- module-index.md\n    |-- linux-embedded-learning-roadmap.md\n    |-- linux-embedded-debug-workflow.md\n    |-- oss-reference-map.md\n    |-- agent-architecture-notes.md\n    |-- debugctl-cli-prototype.md\n    |-- boot-chain-and-startup.md\n    |-- device-tree-and-driver-workflow.md\n    |-- common-bus-debugging.md\n    |-- char-device-and-platform-driver-path.md\n    |-- build-rootfs-userspace.md\n    |-- perf-and-observability.md\n    |-- full-link-debug-pipeline.md\n    |-- project-learning-note.md\n    |-- camera-companion-index.md\n    `-- ...\n```\n\n## Example Prompts\n\n```text\nUse $linux-embedded-dev to help me understand this i.MX6ULL boot log.\n```\n\n```text\nUse $linux-embedded-dev to build a code map for this platform driver.\n```\n\n```text\nUse $linux-embedded-dev to debug an I2C sensor that sometimes probes and sometimes fails.\n```\n\n```text\nUse $linux-embedded-dev to design a host-side full-link debug pipeline for my board.\n```\n\n```text\nUse $linux-embedded-dev to analyze an OV5640 + V4L2 capture path and reduce CPU usage.\n```\n\n## Camera Companion\n\nCamera work is included as a companion module rather than a separate skill. The goal is to keep Linux bring-up context and media-specific debugging in the same reasoning path.\n\nUseful camera references:\n\n- `references/camera-companion-index.md`\n- `references/imx6ull-camera-pipeline.md`\n- `references/ov5640-bringup-checklist.md`\n- `references/v4l2-buffer-lifecycle.md`\n- `references/perf-tuning-checklist.md`\n- `references/profiling-playbook.md`\n\n## Full-Link Debug Pipeline\n\nThe skill includes a sanitized pattern for projects where one host terminal controls the whole chain:\n\n```text\nHost PC -> build VM -> embedded board -> backend/frontend/proxy/database -> logs\n```\n\nSee `references/full-link-debug-pipeline.md` for a reusable template covering SSH aliases, multi-NIC routing issues, target ABI checks, base64 SSH deployment, board restart patterns, status commands, and log maps.\n\n## Design Principles\n\n- **Layer first**: boot, DTS, driver, bus, userspace, performance, or camera.\n- **Evidence before advice**: logs, commands, file paths, callbacks, and exact symptoms.\n- **Small steps**: one meaningful command or edit at a time by default.\n- **Teach while debugging**: short explanations that build the user's mental model.\n- **Reusable notes**: keep milestone, hard-problem, and optimization findings durable.\n- **Privacy-aware case studies**: publish patterns, not raw personal lab details.\n\n## Inspiration\n\nThis skill borrows the strongest structural habits from mature engineering READMEs and embedded review workflows: a crisp promise at the top, quick installation, concrete use cases, focused references, and evidence-first checklists.\n\nIt is intentionally focused on Linux embedded systems rather than MCU-only firmware. The center of gravity is boot flow, device tree, drivers, userspace integration, observability, and practical board work.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE).\n"}