embedded-systems
Use this skill when writing or reviewing Python code for Raspberry Pi 5 edge devices -- UART hardware drivers, camera streaming via picamera2, GPIO control, systemd services, or resource monitoring. Don't use it for MAVLink protocol parsing (use mavlink-integration), web portal server code, or Helm work.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 8
- Forks
- 5
01 前言 Front Matter
- docs
- { "status": "reviewed", "updated": 1785974400000, "source_sha": "36398d0f597c" }
- name
- embedded-systems
- owner
- swarmery-core
- version
- 1.0.0
- description
- Use this skill when writing or reviewing Python code for Raspberry Pi 5 edge devices -- UART hardware drivers, camera streaming via picamera2, GPIO control, systemd services, or resource monitoring. Don't use it for MAVLink protocol parsing (use mavlink-integration), web portal server code, or Helm work.
- allowed-tools
- Read, Edit, Bash, Grep, Glob
03 SKILL.md 正文
Purpose
Produce and review Python code for Raspberry Pi 5 edge devices running the edge service. Covers UART serial communication, picamera2 camera streaming, GPIO control, resource monitoring, and systemd service configuration. All generated code passes mypy, handles MOCK_MODE for CI, and releases hardware resources on exit. For MAVLink protocol parsing (message IDs, dialects, command sequences), compose with mavlink-integration.
Success criteria: generated code imports without hardware attached (MOCK_MODE=true), passes mypy with zero errors, and releases every acquired resource in a finally block.
When to use
- Writing or reviewing Python code that interfaces with RPi5 hardware (UART, GPIO, camera)
- Configuring systemd services for the edge service on edge devices
- Debugging hardware communication issues (serial port, camera initialization)
- Implementing resource monitoring (CPU temperature, memory, throttling) on edge devices
When NOT to use
- Web portal server-side TypeScript code (use
api-integrationorcode-standards) - Infrastructure or Helm chart work (use the project's deployment workflow)
- MAVLink message parsing, dialect selection, or command sequencing (use
mavlink-integration) - Docker image building for the edge service (use
docker-build) - Python dependency auditing (use
deps-check) - Any Python code in the edge service that is purely MAVLink protocol without hardware driver concerns (use
mavlink-integration)
Required environment
- Runtime:
.claude/skills/embedded-systems/SKILL.md - Tools/libraries: Python 3.11+,
serial_asyncio,picamera2,psutil,asyncio - Hardware: Raspberry Pi 5 (or
MOCK_MODE=truefor CI/dev without hardware) - Code standards:
mypyfor type checking,black(line length 100),isort,flake8(max complexity 10)
Inputs
component: "uart" | "camera" | "gpio" | "systemd" | "monitoring"-- which hardware subsystem to work withmock_mode: boolean-- if true, generate code that works without physical hardware (for CI testing)
Outputs
- Format: Python code with type hints, specific exception handling, and
MOCK_MODEsupport. All code passesmypywithout errors. - Length budget: max 120 lines per class; max 40 lines per standalone function; systemd unit files under 25 lines.
Procedure
-
Check mock mode -- Determine if the code should support running without hardware. If
MOCK_MODEis set in the environment, all hardware interfaces return simulated data.import os MOCK_MODE = os.environ.get("MOCK_MODE", "false").lower() == "true"Checkpoint:
MOCK_MODEcheck is present at module level. The check reads from the environment at runtime, never hardcoded to a literal"false". -
Import required modules -- Always include explicit imports. Never assume modules are available in scope. If using
serial.EIGHTBITSorserial.SerialException, you mustimport serialseparately --serial_asynciodoes not bringserialconstants into scope.import asyncio import logging import serial # required for serial.EIGHTBITS, serial.SerialException import serial_asyncio from typing import Optional logger = logging.getLogger(__name__)Checkpoint:
loggerand all type imports are explicitly defined.import serialis present if anyserial.*constant or exception is referenced. -
Implement with specific exceptions -- Use specific exception types, not bare
except Exception. Hardware code handles known failure modes:- UART:
serial.SerialException,OSError,asyncio.TimeoutError - Camera:
RuntimeError(picamera2 init failure),OSError(device not found) - GPIO:
PermissionError,FileNotFoundError(sysfs access)
Checkpoint: Every
exceptblock catches a specific exception type. - UART:
-
Add cleanup in
finallyblocks -- Hardware resources (serial ports, camera) are released on exit.Checkpoint: Every
connect/initializehas a correspondingclose/cleanupin afinallyblock. -
Add exit conditions to loops -- Streaming loops accept a stop signal.
Checkpoint: Every
whileloop checks astop_event: asyncio.Eventor equivalent. -
Show diff before applying Edit -- Before applying any Edit to an existing file, show the operator a before/after diff of the code change and confirm the target hardware component.
Checkpoint: Diff shown; operator has context on which hardware subsystem is affected.
-
Test with MOCK_MODE -- Verify the code runs in CI without hardware by setting
MOCK_MODE=true.Checkpoint:
mypypasses, and the module can be imported without hardware attached.
Self-check
<self-check>
- [ ] All Python code has type hints on parameters and return types
- [ ]
loggeris explicitly created vialogging.getLogger(__name__), not used as an undefined name - [ ]
serialmodule is imported before referencingserial.EIGHTBITS,serial.SerialException, etc. --serial_asynciodoes NOT bring these into scope - [ ] Every
exceptblock catches a specific exception, not bareException - [ ] Every streaming loop has an exit condition (e.g.,
stop_event.is_set()) - [ ] Hardware resources are released in
finallyblocks - [ ]
MOCK_MODEsupport is present for CI compatibility -- the check readsos.environ, never hardcoded - [ ] No hardcoded paths like
/home/pi/-- use environment variables or systemd specifiers - [ ]
mypywould pass on the generated code - [ ] Systemd service templates use
MOCK_MODE=${MOCK_MODE:-false}, not a hardcoded literal - [ ] Before/after diff was shown for every Edit applied to existing files </self-check>
Common mistakes
- DO NOT use bare
except Exception-- always catch specific exceptions (serial.SerialException,OSError,RuntimeError) - DO NOT reference
loggerwithout defining it -- always addlogger = logging.getLogger(__name__)at module level - DO NOT reference
serial.EIGHTBITSwithoutimport serial-- theserial_asyncioimport does not bringserialconstants into scope - DO NOT write infinite loops without exit conditions -- always use
while not stop_event.is_set()or a cancellation token - DO NOT hardcode
/home/pi/in systemd service files -- use%h(home directory specifier) or environment variables; the deploy user may beubuntu(as on the staging environment) - DO NOT use
raspi-configmenu instructions for camera enable -- on Raspberry Pi OS Bookworm (2024+), usedtoverlay=camera_auto_detectin/boot/firmware/config.txt - DO NOT call
self.camera.capture_file()without checkingself.camera is not Nonefirst - DO NOT open UART without a corresponding
finallyblock to release the port - DO NOT hardcode
MOCK_MODE=falsein systemd service templates -- useMOCK_MODE=${MOCK_MODE:-false}so environment-specific overrides work via drop-in files
Escalation
- Stop and ask when: The target RPi model is not RPi5 (GPIO pinout and UART assignments differ)
- Stop and ask when: Multiple services need the same UART port (serial port contention)
- Stop and ask when: Camera resolution exceeds 1920x1080 at 30fps (may exceed RPi5 ISP throughput)
- Stop and ask when: The code must interact with MAVLink messages (hand off to
mavlink-integration)
What to surface
- Whether
MOCK_MODEis being used (affects test validity) - Hardware-specific side effects: UART monopolizes the serial port, camera locks the CSI interface
- The systemd service user and working directory (must match the target device)
- Any
asyncio.to_thread()calls wrapping blocking I/O (pymavlink, picamera2 capture)
Examples
<example name="uart-reader"> Scenario: Implement a UART reader for serial communication on the edge service
import asyncio
import logging
import os
import serial
import serial_asyncio
from typing import Optional
logger = logging.getLogger(__name__)
MOCK_MODE = os.environ.get("MOCK_MODE", "false").lower() == "true"
class UARTReader:
"""Async UART reader for serial communication with flight controller."""
def __init__(self, port: str = "/dev/ttyAMA0", baudrate: int = 57600) -> None:
self.port = port
self.baudrate = baudrate
self.reader: Optional[asyncio.StreamReader] = None
self.writer: Optional[asyncio.StreamWriter] = None
async def connect(self) -> bool:
"""Establish UART connection. Returns True on success."""
if MOCK_MODE:
logger.info("MOCK_MODE: Simulating UART connection on %s", self.port)
return True
try:
self.reader, self.writer = await serial_asyncio.open_serial_connection(
url=self.port,
baudrate=self.baudrate,
bytesize=serial.EIGHTBITS,
parity=serial.PARITY_NONE,
stopbits=serial.STOPBITS_ONE,
)
logger.info("Connected to UART: %s", self.port)
return True
except serial.SerialException as err:
logger.error("UART serial error on %s: %s", self.port, err)
return False
except OSError as err:
logger.error("UART OS error on %s: %s", self.port, err)
return False
async def read_bytes(self, size: int, timeout: float = 1.0) -> Optional[bytes]:
"""Read bytes from UART with timeout."""
if MOCK_MODE:
return b"\x00" * size
if self.reader is None:
return None
try:
data = await asyncio.wait_for(self.reader.read(size), timeout=timeout)
return data
except asyncio.TimeoutError:
logger.debug("UART read timeout after %.1fs", timeout)
return None
except serial.SerialException as err:
logger.error("UART read serial error: %s", err)
return None
except OSError as err:
logger.error("UART read OS error: %s", err)
return None
async def close(self) -> None:
"""Release UART resources."""
if self.writer is not None:
try:
self.writer.close()
await self.writer.wait_closed()
except OSError as err:
logger.warning("Error closing UART writer: %s", err)
finally:
self.writer = None
self.reader = None
logger.info("UART connection closed on %s", self.port)
</example>
<example name="camera-streamer"> Scenario: Camera streaming with exit condition and cleanup
import asyncio
import logging
import os
from io import BytesIO
from typing import Awaitable, Callable, Optional
logger = logging.getLogger(__name__)
MOCK_MODE = os.environ.get("MOCK_MODE", "false").lower() == "true"
class CameraStreamer:
"""Async camera streamer using picamera2."""
def __init__(self, width: int = 640, height: int = 480, fps: int = 30) -> None:
self.width = width
self.height = height
self.fps = fps
self._camera: Optional[object] = None # Picamera2 instance
async def initialize(self) -> bool:
"""Initialize camera. Returns True on success."""
if MOCK_MODE:
logger.info("MOCK_MODE: Simulating camera initialization")
return True
try:
from picamera2 import Picamera2
self._camera = Picamera2()
config = self._camera.create_still_configuration(
main={"size": (self.width, self.height)}
)
self._camera.configure(config)
self._camera.start()
logger.info("Camera initialized: %dx%d @ %dfps", self.width, self.height, self.fps)
return True
except RuntimeError as err:
logger.error("Camera init runtime error: %s", err)
return False
except OSError as err:
logger.error("Camera device not found: %s", err)
return False
async def capture_jpeg(self) -> Optional[bytes]:
"""Capture a single JPEG frame."""
if MOCK_MODE:
return b"\xff\xd8\xff\xe0" + b"\x00" * 100 + b"\xff\xd9"
if self._camera is None:
logger.warning("Camera not initialized, cannot capture")
return None
try:
buffer = BytesIO()
await asyncio.to_thread(self._camera.capture_file, buffer, format="jpeg")
return buffer.getvalue()
except RuntimeError as err:
logger.error("Camera capture error: %s", err)
return None
async def stream_loop(
self,
callback: Callable[[bytes], Awaitable[None]],
stop_event: asyncio.Event,
) -> None:
"""Stream JPEG frames until stop_event is set."""
logger.info("Starting camera stream loop")
try:
while not stop_event.is_set():
jpeg_data = await self.capture_jpeg()
if jpeg_data:
await callback(jpeg_data)
await asyncio.sleep(1.0 / self.fps)
finally:
logger.info("Camera stream loop stopped")
async def cleanup(self) -> None:
"""Release camera resources."""
if self._camera is not None:
try:
self._camera.stop()
self._camera.close()
except RuntimeError as err:
logger.warning("Error closing camera: %s", err)
finally:
self._camera = None
logger.info("Camera resources released")
</example>
<example name="systemd-service"> Scenario: Systemd service template (parameterized, 12-factor compliant)
# /etc/systemd/system/<device>@.service
[Unit]
Description=Edge Control Box Service
After=network.target
[Service]
Type=simple
User=%i
WorkingDirectory=%h/<device>
ExecStart=%h/<device>/venv/bin/python src/send_data.py
Restart=always
RestartSec=10
Environment="PYTHONUNBUFFERED=1"
Environment="LOG_LEVEL=INFO"
Environment="MOCK_MODE=${MOCK_MODE:-false}"
[Install]
WantedBy=multi-user.target
Usage: sudo systemctl enable <device>@ubuntu (where ubuntu is the deploy user).
To override MOCK_MODE for a specific device, create a drop-in:
sudo systemctl edit <device>@ubuntu
# Add: [Service]
# Add: Environment="MOCK_MODE=true"
</example>
Failure modes
| Mode | Symptom | Detection | Fix |
|---|---|---|---|
| UART permission denied | PermissionError on /dev/ttyAMA0 |
Exception caught in connect() |
Add user to dialout group (sudo usermod -a -G dialout $USER), then log out and back in |
| Camera not detected | RuntimeError during Picamera2() init |
Exception caught in initialize() |
Verify dtoverlay=camera_auto_detect in /boot/firmware/config.txt and reboot; check CSI cable connection |
| CPU thermal throttling | Performance degradation, CPU temp > 80C | get_cpu_temperature() returns > 80.0 |
Add heatsink, reduce camera resolution, or reduce telemetry polling rate |
| Serial port contention | serial.SerialException with "device busy" |
Another process holds /dev/ttyAMA0 |
Check for other UART consumers (lsof /dev/ttyAMA0), stop conflicting service |
Related skills
mavlink-integration-- compose for MAVLink protocol handling; embedded-systems provides the UART transport layer, mavlink-integration provides message parsing and command sequencesdocker-build-- defer for creating the edge service Docker image (ARM64)code-standards-- code-standards defines Python style rules (black, isort, flake8, mypy) that apply to all edge service codeapi-integration-- the edge service WebSocket server (port 8081) that the web portal connects to is documented in api-integration
How to use
What it does
This skill writes and reviews Python that talks to real hardware on a single-board edge computer — serial ports, camera capture, GPIO lines, resource monitoring, and the service unit that keeps it running. It bakes in the habits that hardware code fails without: explicit imports, specific exception types, cleanup in finally, loops that can be stopped, and a mock path so the module still imports on a CI box with no hardware attached.
When to use it
- You are writing or reviewing Python that opens a serial port, drives GPIO pins, or captures frames from a CSI camera.
- You need a service unit file for the edge service, parameterized by user and home directory rather than hardcoded paths.
- A hardware call is failing — the port is busy, the camera never initializes, the process holds a device after exit.
- You are adding CPU temperature, memory, or throttling checks to a device agent.
When not to use it
- Parsing MAVLink messages, choosing dialects, or sequencing commands — use
mavlink-integration; this skill only supplies the transport underneath it. - Server-side TypeScript for a web portal — use
api-integrationorcode-standards. - Building the container image for the edge service — use
docker-build. - Auditing Python dependencies — use
deps-check.
How to invoke
Skill(skill: "uav-pack:embedded-systems")
Invoke it before you write the code, not after. Tell it which subsystem you are on — uart, camera, gpio, systemd, or monitoring — and whether the result must run without hardware.
Inputs
component— which subsystem:uart,camera,gpio,systemd, ormonitoring— required.mock_mode— whether the generated code must run with no hardware attached, for CI — optional, defaults to supporting it.
What you get back
Typed Python with a module-level logger, a runtime MOCK_MODE check, specific except clauses, and every acquired resource released in a finally block. Classes stay under 120 lines, standalone functions under 40, service unit files under 25. Before any edit to an existing file you get a before/after diff and a note on which hardware subsystem it touches.
Worked example
Skill(skill: "uav-pack:embedded-systems")
"Add a camera streamer to the edge service that pushes JPEG frames to a callback."
You get an async class with initialize, capture_jpeg, a stream_loop that runs while not stop_event.is_set(), and a cleanup that stops and closes the device. Blocking capture is wrapped in asyncio.to_thread. With MOCK_MODE=true the module imports and returns a stub JPEG, so the test suite passes on a machine with no camera.
Related
mavlink-integration— compose with it when the bytes on the wire are MAVLink frames rather than raw serial.code-standards— the underlying style rules (formatting, import order, lint, type checking) for all Python here.api-integration— for the socket server the portal connects to, rather than the device-side driver.
04 同仓库更多 Skills
short-desc
Too short.
no-frontmatter
暂无简介
global-skill
Fixture global skill (minimal user-scope shape, format doc §2.3).
documented-skill
Fixture skill whose usage guide deliberately omits the Worked example subsection.
z
NOT auto-discovered — only skills/ is scanned for plugins (§2.2).
y
Plugin skill y from toolpack — stored as "toolpack:y".