packwise-skills 1.0.0 → 1.2.0

package/sub-skills/embedded/esp32.md

@@ -1,184 +1,184 @@
-# ESP32 Embedded Build Sub-Skill
-
-Build firmware for ESP32 series using ESP-IDF or Arduino framework.
-
-**Current versions**: ESP-IDF v5.3+ / Arduino-ESP32 3.x (2025-2026)
-
-## When to Use
-
-- WiFi/Bluetooth IoT devices
-- Smart home sensors and controllers
-- Wearable devices
-- Industrial IoT gateways
-- Audio streaming devices (ESP32-S3)
-- Low-power battery devices (ESP32-C6, ESP32-H2)
-
-## ESP32 Family Overview
-
-| Chip | Core | WiFi | BT | Flash | Best For |
-|------|------|------|-----|-------|----------|
-| ESP32 | Xtensa dual-core 240MHz | WiFi 4 | BT 4.2 + BLE | 4-16MB | General IoT, most mature |
-| ESP32-S2 | Xtensa single-core 240MHz | WiFi 4 | No BT | 4-16MB | Low-cost WiFi, USB OTG |
-| ESP32-S3 | Xtensa dual-core 240MHz | WiFi 4 | BLE 5.0 | 8-16MB | AI acceleration, USB, camera |
-| ESP32-C3 | RISC-V single-core 160MHz | WiFi 4 | BLE 5.0 | 4MB | Low-cost, pin-compatible with ESP8266 |
-| ESP32-C6 | RISC-V single-core 160MHz | WiFi 6 | BLE 5.0 + 802.15.4 | 4MB | Thread/Zigbee/Matter, WiFi 6 |
-| ESP32-H2 | RISC-V single-core 96MHz | No WiFi | BLE 5.0 + 802.15.4 | 4MB | Thread/Zigbee/Matter, ultra-low power |
-
-## ESP-IDF Build (Recommended for Production)
-
-### Prerequisites
-
-```bash
-# Install ESP-IDF
-# Linux/macOS:
-mkdir -p ~/esp && cd ~/esp
-git clone --recursive https://github.com/espressif/esp-idf.git
-cd esp-idf && ./install.sh esp32  # or esp32s3, esp32c3, esp32c6, etc.
-source export.sh
-
-# Windows:
-# Download ESP-IDF Tools Installer from docs.espressif.com
-
-# Verify
-idf.py --version
-```
-
-### Build
-
-```bash
-# Set target chip
-idf.py set-target esp32       # or esp32s3, esp32c3, esp32c6, etc.
-
-# Configure (menuconfig)
-idf.py menuconfig
-
-# Build
-idf.py build
-# Output: build/myproject.bin, build/myproject.elf
-
-# Flash (USB connected)
-idf.py -p /dev/ttyUSB0 flash    # Linux
-idf.py -p COM3 flash             # Windows
-
-# Monitor serial output
-idf.py -p /dev/ttyUSB0 monitor
-
-# Flash + monitor in one step
-idf.py -p /dev/ttyUSB0 flash monitor
-```
-
-### Project Structure
-
-```
-myproject/
-├── CMakeLists.txt              ← Top-level CMake
-├── main/
-│   ├── CMakeLists.txt          ← Main component CMake
-│   ├── main.c                  ← Entry point (app_main)
-│   └── wifi.c                  ← WiFi management
-├── components/                 ← Custom components
-│   └── mylib/
-│       ├── CMakeLists.txt
-│       ├── mylib.c
-│       └── include/mylib.h
-├── sdkconfig                   ← Build configuration
-├── partitions.csv              ← Flash partition table
-└── managed_components/         ← ESP-IDF component registry deps
-```
-
-### Flash Partition Table
-
-```csv
-# partitions.csv — custom partition layout
-# Name,    Type, SubType, Offset,  Size,    Flags
-nvs,       data, nvs,     0x9000,  0x6000,
-phy_init,  data, phy,     0xf000,  0x1000,
-factory,   app,  factory, 0x10000, 0x1F0000,
-storage,   data, spiffs,  0x200000,0x200000,
-```
-
-## Arduino-ESP32 Build (Simpler, Faster Prototyping)
-
-### PlatformIO Configuration
-
-```ini
-; platformio.ini
-[env:esp32dev]
-platform = espressif32
-board = esp32dev
-framework = arduino       ; or: espidf
-monitor_speed = 115200
-upload_speed = 921600
-board_build.partitions = huge_app.csv
-build_flags =
-    -DARDUINO_USB_CDC_ON_BOOT=1
-lib_deps =
-    bblanchon/ArduinoJson@^7.0.0
-    knolleary/PubSubClient@^2.8
-```
-
-```bash
-pio run                    # Build
-pio run -t upload          # Flash
-pio device monitor         # Serial monitor
-```
-
-### Arduino Code Example
-
-```cpp
-#include <WiFi.h>
-#include <PubSubClient.h>
-
-const char* ssid = "MyWiFi";
-const char* password = "MyPassword";
-const char* mqtt_server = "192.168.1.100";
-
-WiFiClient espClient;
-PubSubClient client(espClient);
-
-void setup() {
-    Serial.begin(115200);
-    WiFi.begin(ssid, password);
-    while (WiFi.status() != WL_CONNECTED) { delay(500); }
-    client.setServer(mqtt_server, 1883);
-}
-
-void loop() {
-    if (!client.connected()) {
-        client.connect("esp32-client");
-    }
-    client.publish("sensor/temperature", "23.5");
-    delay(5000);
-}
-```
-
-## Over-the-Air (OTA) Updates
-
-```cpp
-// Arduino OTA
-#include <ArduinoOTA.h>
-
-void setup() {
-    ArduinoOTA.setHostname("my-esp32");
-    ArduinoOTA.setPassword("admin");
-    ArduinoOTA.begin();
-}
-
-void loop() {
-    ArduinoOTA.handle();
-}
-```
-
-## Common Pitfalls
-
-| Issue | Fix |
-|-------|-----|
-| WiFi disconnects frequently | Use WiFi event handlers; implement reconnection logic |
-| Flash size mismatch | Set correct flash size in menuconfig; check actual chip |
-| PSRAM not detected | Enable PSRAM in menuconfig; check board has PSRAM chip |
-| BLE connection fails | Check BLE MTU size; ensure correct service/characteristic UUIDs |
-| Deep sleep current too high | Disable WiFi/BT before sleep; use RTC GPIO for wake |
-| Partition table error | Verify partition sizes fit flash; use `idf.py partition-table` to check |
-| Build: "sdkconfig mismatch" | Run `idf.py fullclean` then `idf.py build` |
-| Upload fails on Windows | Install CP2102/CH340 USB driver; check COM port |
-| Stack overflow crash | Increase task stack size (default 4KB may be too small) |
+# ESP32 Embedded Build Sub-Skill
+
+Build firmware for ESP32 series using ESP-IDF or Arduino framework.
+
+**Current versions**: ESP-IDF v5.3+ / Arduino-ESP32 3.x (2025-2026)
+
+## When to Use
+
+- WiFi/Bluetooth IoT devices
+- Smart home sensors and controllers
+- Wearable devices
+- Industrial IoT gateways
+- Audio streaming devices (ESP32-S3)
+- Low-power battery devices (ESP32-C6, ESP32-H2)
+
+## ESP32 Family Overview
+
+| Chip | Core | WiFi | BT | Flash | Best For |
+|------|------|------|-----|-------|----------|
+| ESP32 | Xtensa dual-core 240MHz | WiFi 4 | BT 4.2 + BLE | 4-16MB | General IoT, most mature |
+| ESP32-S2 | Xtensa single-core 240MHz | WiFi 4 | No BT | 4-16MB | Low-cost WiFi, USB OTG |
+| ESP32-S3 | Xtensa dual-core 240MHz | WiFi 4 | BLE 5.0 | 8-16MB | AI acceleration, USB, camera |
+| ESP32-C3 | RISC-V single-core 160MHz | WiFi 4 | BLE 5.0 | 4MB | Low-cost, pin-compatible with ESP8266 |
+| ESP32-C6 | RISC-V single-core 160MHz | WiFi 6 | BLE 5.0 + 802.15.4 | 4MB | Thread/Zigbee/Matter, WiFi 6 |
+| ESP32-H2 | RISC-V single-core 96MHz | No WiFi | BLE 5.0 + 802.15.4 | 4MB | Thread/Zigbee/Matter, ultra-low power |
+
+## ESP-IDF Build (Recommended for Production)
+
+### Prerequisites
+
+```bash
+# Install ESP-IDF
+# Linux/macOS:
+mkdir -p ~/esp && cd ~/esp
+git clone --recursive https://github.com/espressif/esp-idf.git
+cd esp-idf && ./install.sh esp32  # or esp32s3, esp32c3, esp32c6, etc.
+source export.sh
+
+# Windows:
+# Download ESP-IDF Tools Installer from docs.espressif.com
+
+# Verify
+idf.py --version
+```
+
+### Build
+
+```bash
+# Set target chip
+idf.py set-target esp32       # or esp32s3, esp32c3, esp32c6, etc.
+
+# Configure (menuconfig)
+idf.py menuconfig
+
+# Build
+idf.py build
+# Output: build/myproject.bin, build/myproject.elf
+
+# Flash (USB connected)
+idf.py -p /dev/ttyUSB0 flash    # Linux
+idf.py -p COM3 flash             # Windows
+
+# Monitor serial output
+idf.py -p /dev/ttyUSB0 monitor
+
+# Flash + monitor in one step
+idf.py -p /dev/ttyUSB0 flash monitor
+```
+
+### Project Structure
+
+```
+myproject/
+├── CMakeLists.txt              ← Top-level CMake
+├── main/
+│   ├── CMakeLists.txt          ← Main component CMake
+│   ├── main.c                  ← Entry point (app_main)
+│   └── wifi.c                  ← WiFi management
+├── components/                 ← Custom components
+│   └── mylib/
+│       ├── CMakeLists.txt
+│       ├── mylib.c
+│       └── include/mylib.h
+├── sdkconfig                   ← Build configuration
+├── partitions.csv              ← Flash partition table
+└── managed_components/         ← ESP-IDF component registry deps
+```
+
+### Flash Partition Table
+
+```csv
+# partitions.csv — custom partition layout
+# Name,    Type, SubType, Offset,  Size,    Flags
+nvs,       data, nvs,     0x9000,  0x6000,
+phy_init,  data, phy,     0xf000,  0x1000,
+factory,   app,  factory, 0x10000, 0x1F0000,
+storage,   data, spiffs,  0x200000,0x200000,
+```
+
+## Arduino-ESP32 Build (Simpler, Faster Prototyping)
+
+### PlatformIO Configuration
+
+```ini
+; platformio.ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino       ; or: espidf
+monitor_speed = 115200
+upload_speed = 921600
+board_build.partitions = huge_app.csv
+build_flags =
+    -DARDUINO_USB_CDC_ON_BOOT=1
+lib_deps =
+    bblanchon/ArduinoJson@^7.0.0
+    knolleary/PubSubClient@^2.8
+```
+
+```bash
+pio run                    # Build
+pio run -t upload          # Flash
+pio device monitor         # Serial monitor
+```
+
+### Arduino Code Example
+
+```cpp
+#include <WiFi.h>
+#include <PubSubClient.h>
+
+const char* ssid = "MyWiFi";
+const char* password = "MyPassword";
+const char* mqtt_server = "192.168.1.100";
+
+WiFiClient espClient;
+PubSubClient client(espClient);
+
+void setup() {
+    Serial.begin(115200);
+    WiFi.begin(ssid, password);
+    while (WiFi.status() != WL_CONNECTED) { delay(500); }
+    client.setServer(mqtt_server, 1883);
+}
+
+void loop() {
+    if (!client.connected()) {
+        client.connect("esp32-client");
+    }
+    client.publish("sensor/temperature", "23.5");
+    delay(5000);
+}
+```
+
+## Over-the-Air (OTA) Updates
+
+```cpp
+// Arduino OTA
+#include <ArduinoOTA.h>
+
+void setup() {
+    ArduinoOTA.setHostname("my-esp32");
+    ArduinoOTA.setPassword("admin");
+    ArduinoOTA.begin();
+}
+
+void loop() {
+    ArduinoOTA.handle();
+}
+```
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| WiFi disconnects frequently | Use WiFi event handlers; implement reconnection logic |
+| Flash size mismatch | Set correct flash size in menuconfig; check actual chip |
+| PSRAM not detected | Enable PSRAM in menuconfig; check board has PSRAM chip |
+| BLE connection fails | Check BLE MTU size; ensure correct service/characteristic UUIDs |
+| Deep sleep current too high | Disable WiFi/BT before sleep; use RTC GPIO for wake |
+| Partition table error | Verify partition sizes fit flash; use `idf.py partition-table` to check |
+| Build: "sdkconfig mismatch" | Run `idf.py fullclean` then `idf.py build` |
+| Upload fails on Windows | Install CP2102/CH340 USB driver; check COM port |
+| Stack overflow crash | Increase task stack size (default 4KB may be too small) |

package/sub-skills/embedded/ros.md

@@ -1,150 +1,150 @@
-# ROS/ROS2 Robotics Build Sub-Skill
-
-Build and package robotic applications using ROS (Robot Operating System).
-
-**Current versions**: ROS 2 Jazzy Jalisco (LTS, 2024-2029) / ROS 1 Noetic (EOL 2025) (2025-2026)
-
-## When to Use
-
-- Robot navigation and SLAM
-- Manipulator/arm control
-- Multi-robot coordination
-- Sensor fusion (LiDAR, camera, IMU)
-- Autonomous vehicles (research)
-- Industrial automation
-
-## ROS 1 vs ROS 2
-
-| Feature | ROS 1 Noetic | ROS 2 Jazzy |
-|---------|-------------|-------------|
-| Status | EOL May 2025 | Active LTS (2024-2029) |
-| Middleware | Custom TCP/UDP | DDS (Data Distribution Service) |
-| Real-time | No | Yes (with RT kernel) |
-| Security | None built-in | SROS2 (DDS-Security) |
-| Multi-robot | Difficult | First-class support |
-| Language | C++ / Python 2.7+3 | C++ / Python 3.10+ |
-| OS | Ubuntu 20.04 | Ubuntu 24.04 |
-| **Recommendation** | Legacy only | **Use ROS 2 for all new projects** |
-
-## ROS 2 Build
-
-### Prerequisites
-
-```bash
-# Ubuntu 24.04 (recommended)
-sudo apt update && sudo apt install software-properties-common
-sudo add-apt-repository universe
-sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
-  -o /usr/share/keyrings/ros-archive-keyring.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \
-  http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | \
-  sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
-sudo apt update
-sudo apt install ros-jazzy-desktop
-source /opt/ros/jazzy/setup.bash
-```
-
-### Build with colcon
-
-```bash
-# Create workspace
-mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
-ros2 pkg create --build-type ament_cmake my_robot
-
-# Build
-cd ~/ros2_ws
-colcon build --packages-select my_robot
-# Output: install/my_robot/
-
-# Source the workspace
-source install/setup.bash
-
-# Build with symlink (faster iteration)
-colcon build --symlink-install
-
-# Test
-colcon test --packages-select my_robot
-```
-
-### Package Structure
-
-```
-my_robot/
-├── CMakeLists.txt          ← Build configuration
-├── package.xml             ← Package metadata
-├── include/my_robot/       ← Header files
-├── src/                    ← C++ source files
-│   └── my_node.cpp
-├── launch/                 ← Launch files
-│   └── bringup.launch.py
-├── config/                 ← Parameter files
-│   └── params.yaml
-├── urdf/                   ← Robot description
-│   └── my_robot.urdf
-├── meshes/                 ← 3D models
-├── worlds/                 ← Gazebo worlds
-└── msg/                    ← Custom message types
-    └── MyMessage.msg
-```
-
-### Launch File (Python)
-
-```python
-# launch/bringup.launch.py
-from launch import LaunchDescription
-from launch_ros.actions import Node
-
-def generate_launch_description():
-    return LaunchDescription([
-        Node(
-            package='my_robot',
-            executable='my_node',
-            name='my_node',
-            parameters=[{'param1': 'value1'}],
-            output='screen'
-        ),
-    ])
-```
-
-```bash
-ros2 launch my_robot bringup.launch.py
-```
-
-## Docker Build
-
-```dockerfile
-FROM ros:jazzy-ros-base
-WORKDIR /ros2_ws
-RUN apt-get update && apt-get install -y \
-    ros-jazzy-navigation2 \
-    ros-jazzy-slam-toolbox \
-    && rm -rf /var/lib/apt/lists/*
-COPY . src/my_robot/
-RUN . /opt/ros/jazzy/setup.sh && colcon build --packages-select my_robot
-RUN echo "source /ros2_ws/install/setup.bash" >> ~/.bashrc
-CMD ["ros2", "launch", "my_robot", "bringup.launch.py"]
-```
-
-## Simulation (Gazebo)
-
-```bash
-# Install Gazebo (Harmonic, recommended for ROS 2 Jazzy)
-sudo apt install ros-jazzy-gz-sim
-
-# Launch Gazebo with robot
-ros2 launch my_robot gazebo.launch.py
-```
-
-## Common Pitfalls
-
-| Issue | Fix |
-|-------|-----|
-| `ros2: command not found` | Source ROS: `source /opt/ros/jazzy/setup.bash` |
-| Package not found after build | Source workspace: `source install/setup.bash` |
-| DDS discovery issues | Set `ROS_DOMAIN_ID` for network isolation; check firewall |
-| Gazebo crash | Check GPU driver; use `LIBGL_ALWAYS_SOFTWARE=1` for headless |
-| URDF parsing error | Validate with `check_urdf`; check XML syntax |
-| Real-time not working | Use RT kernel (`PREEMPT_RT`); set thread priority with `SCHED_FIFO` |
-| Jetson build slow | Cross-compile on x86; use Docker multi-stage build |
-| Navigation stack fails | Check map server; verify TF tree with `ros2 run tf2_tools view_frames` |
-| Node communication fails | Same `ROS_DOMAIN_ID` on all nodes; check QoS settings |
+# ROS/ROS2 Robotics Build Sub-Skill
+
+Build and package robotic applications using ROS (Robot Operating System).
+
+**Current versions**: ROS 2 Jazzy Jalisco (LTS, 2024-2029) / ROS 1 Noetic (EOL 2025) (2025-2026)
+
+## When to Use
+
+- Robot navigation and SLAM
+- Manipulator/arm control
+- Multi-robot coordination
+- Sensor fusion (LiDAR, camera, IMU)
+- Autonomous vehicles (research)
+- Industrial automation
+
+## ROS 1 vs ROS 2
+
+| Feature | ROS 1 Noetic | ROS 2 Jazzy |
+|---------|-------------|-------------|
+| Status | EOL May 2025 | Active LTS (2024-2029) |
+| Middleware | Custom TCP/UDP | DDS (Data Distribution Service) |
+| Real-time | No | Yes (with RT kernel) |
+| Security | None built-in | SROS2 (DDS-Security) |
+| Multi-robot | Difficult | First-class support |
+| Language | C++ / Python 2.7+3 | C++ / Python 3.10+ |
+| OS | Ubuntu 20.04 | Ubuntu 24.04 |
+| **Recommendation** | Legacy only | **Use ROS 2 for all new projects** |
+
+## ROS 2 Build
+
+### Prerequisites
+
+```bash
+# Ubuntu 24.04 (recommended)
+sudo apt update && sudo apt install software-properties-common
+sudo add-apt-repository universe
+sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
+  -o /usr/share/keyrings/ros-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \
+  http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | \
+  sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
+sudo apt update
+sudo apt install ros-jazzy-desktop
+source /opt/ros/jazzy/setup.bash
+```
+
+### Build with colcon
+
+```bash
+# Create workspace
+mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
+ros2 pkg create --build-type ament_cmake my_robot
+
+# Build
+cd ~/ros2_ws
+colcon build --packages-select my_robot
+# Output: install/my_robot/
+
+# Source the workspace
+source install/setup.bash
+
+# Build with symlink (faster iteration)
+colcon build --symlink-install
+
+# Test
+colcon test --packages-select my_robot
+```
+
+### Package Structure
+
+```
+my_robot/
+├── CMakeLists.txt          ← Build configuration
+├── package.xml             ← Package metadata
+├── include/my_robot/       ← Header files
+├── src/                    ← C++ source files
+│   └── my_node.cpp
+├── launch/                 ← Launch files
+│   └── bringup.launch.py
+├── config/                 ← Parameter files
+│   └── params.yaml
+├── urdf/                   ← Robot description
+│   └── my_robot.urdf
+├── meshes/                 ← 3D models
+├── worlds/                 ← Gazebo worlds
+└── msg/                    ← Custom message types
+    └── MyMessage.msg
+```
+
+### Launch File (Python)
+
+```python
+# launch/bringup.launch.py
+from launch import LaunchDescription
+from launch_ros.actions import Node
+
+def generate_launch_description():
+    return LaunchDescription([
+        Node(
+            package='my_robot',
+            executable='my_node',
+            name='my_node',
+            parameters=[{'param1': 'value1'}],
+            output='screen'
+        ),
+    ])
+```
+
+```bash
+ros2 launch my_robot bringup.launch.py
+```
+
+## Docker Build
+
+```dockerfile
+FROM ros:jazzy-ros-base
+WORKDIR /ros2_ws
+RUN apt-get update && apt-get install -y \
+    ros-jazzy-navigation2 \
+    ros-jazzy-slam-toolbox \
+    && rm -rf /var/lib/apt/lists/*
+COPY . src/my_robot/
+RUN . /opt/ros/jazzy/setup.sh && colcon build --packages-select my_robot
+RUN echo "source /ros2_ws/install/setup.bash" >> ~/.bashrc
+CMD ["ros2", "launch", "my_robot", "bringup.launch.py"]
+```
+
+## Simulation (Gazebo)
+
+```bash
+# Install Gazebo (Harmonic, recommended for ROS 2 Jazzy)
+sudo apt install ros-jazzy-gz-sim
+
+# Launch Gazebo with robot
+ros2 launch my_robot gazebo.launch.py
+```
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| `ros2: command not found` | Source ROS: `source /opt/ros/jazzy/setup.bash` |
+| Package not found after build | Source workspace: `source install/setup.bash` |
+| DDS discovery issues | Set `ROS_DOMAIN_ID` for network isolation; check firewall |
+| Gazebo crash | Check GPU driver; use `LIBGL_ALWAYS_SOFTWARE=1` for headless |
+| URDF parsing error | Validate with `check_urdf`; check XML syntax |
+| Real-time not working | Use RT kernel (`PREEMPT_RT`); set thread priority with `SCHED_FIFO` |
+| Jetson build slow | Cross-compile on x86; use Docker multi-stage build |
+| Navigation stack fails | Check map server; verify TF tree with `ros2 run tf2_tools view_frames` |
+| Node communication fails | Same `ROS_DOMAIN_ID` on all nodes; check QoS settings |