Skip to main content
Firmware Stable

Composite Manual Generation Skill

Purpose​

Generate a self-contained, linear product manual (Markdown source + PDF output) for a specific hardware/firmware combination. The manual combines HW specs, FW configuration, SW connectivity, and troubleshooting into one document suitable for print or offline distribution.

When to Use​

  • User asks to create a product manual or PDF for a controller + firmware combination
  • User asks to document a new HW/FW pairing in composite format
  • User wants to update an existing composite manual

Prerequisites​

Gather source material from:

  1. Hardware docs -- docs/hw/ for pinout, connectors, mechanical specs, environmental ratings
  2. Firmware docs -- docs/fw/apps/esc/<app_name>/ for parameters, features, states, CAN messages
  3. Software docs -- docs/sw/ for YOS shell, connection instructions, firmware update procedures
  4. Product images -- from the astroweb workspace (astroweb/public/media/) or docs static assets
  5. Datasheets / drawings -- typically PDFs in the hw docs or provided by the user

Output Structure​

Create a folder named <HW>_<FW>_Manual/ under docs/composite/:

docs/composite/
  build_pdf.mjs     -- Shared build script (invoke with manual folder name)
  style.css         -- Shared PDF stylesheet
  package.json      -- Shared deps: puppeteer, marked, mermaid
  silixcon-logo.png -- Brand logo (auto-copied into manual img/ at build time)
  build/            -- PDF output (git-ignored)

docs/composite/<HW>_<FW>_Manual/
  index.md          -- Complete manual in Markdown
  manual.json       -- Cover config: title, subtitle, coverImage, version, footerLabel
  img/              -- Product-specific images (no shared assets needed here)

Manual Document Structure (index.md)​

Follow this chapter order:

# <HW> Motor Controller -- <FW> Application Manual

## Quick Start with Quick-Setup Pad

(If applicable -- accessory-based setup without software)

## Table of Contents

## 1. Introduction & Scope

## 2. Safety Information

## 3. Product Overview

## 4. Electrical Specifications

## 5. Mechanical Specifications

## 6. Connector & Pinout Reference

## 7. Software Connection & Tools

## 8. Firmware Overview -- <FW>

## 9. Motor Identification & Commissioning

## 10. Signal Conditioning (Throttle Input)

## 11. Current / Voltage / Speed Limits

## 12. Thermal Management

## 13. CAN Bus Communication

## 14. Function Presets (Quick Setup)

## 15. Firmware Update Procedure

## 16. Troubleshooting & LED Codes

## 17. Ordering & Support

Adjust chapters based on what's relevant for the specific HW/FW combination.

Content Guidelines​

  • ASCII only in the Markdown source (build tools may corrupt UTF-8 multi-byte characters)
  • Use -- for em dashes, x for multiplication signs, straight quotes only
  • Use mermaid fenced code blocks for flow/signal diagrams (rendered at PDF build time)
  • Keep all images in img/ with descriptive names (no spaces)
  • Do NOT include default parameter values unless explicitly requested
  • Focus on differentiation and practical guidance over raw spec repetition
  • Pin names should use firmware function names (not GPIO abstractions like GPIN1)
  • Reference the parameter tree paths as they appear in YOS shell (e.g. /io/pwm_input/)

PDF Build Process​

The build script (build_pdf.mjs) does:

  1. Read index.md and style.css
  2. Convert Markdown to HTML via marked (with custom renderer for mermaid blocks)
  3. Inline the mermaid.js library from node_modules/
  4. Prepend a branded cover page (logo, product image, company info, date)
  5. Write a temp HTML file and open it in headless Chromium via Puppeteer
  6. Wait for mermaid diagrams to render (SVG injection)
  7. Generate A4 PDF with headers/footers

Branded Elements (from siliXcon style)​

  • Primary color: #F26525 (orange)
  • Accent: #FF8C42
  • Font: Inter
  • Logo: img/silixcon-logo.png
  • Cover: white background, orange bottom border, centered layout

Adapting for a New HW/FW Combination​

  1. Create a new folder docs/composite/<NewHW>_<NewFW>_Manual/
  2. Create manual.json with cover config: 
    {
      "title": "Controller Name",
      "subtitle": "FW_NAME Application -- Product Manual",
      "coverImage": "product-photo.png",
      "footerLabel": "Controller FW_NAME Manual",
      "version": "1.0"
    }
  3. Create img/ folder and add product-specific images
  4. Write index.md content:
    • Pull HW specs from docs/hw/<controller>/
    • Pull FW features from docs/fw/apps/esc/<app>/
    • Pull SW instructions from docs/sw/
  5. Build: node build_pdf.mjs <NewHW>_<NewFW>_Manual
  6. Verify the PDF in build/ renders correctly (cover, page breaks, diagrams, images)

Style Rules for Tables​

  • Use orange header background (thead { background: #F26525 })
  • Alternating row shading
  • Avoid tables wider than page -- use abbreviations or split into multiple tables
  • Pin tables: columns = Pin#, Wire Color, Function, Notes

Checklist Before Finishing​

  • All images are in img/ and render in the PDF
  • Mermaid diagrams render (check "Mermaid diagrams rendered: N" in build output)
  • Cover page shows correct product name and image
  • Page breaks occur at each ## chapter heading
  • No broken image links (check for blank spaces in PDF)
  • Parameter paths match actual firmware tree
  • No UTF-8 corruption (em dashes, special chars)
  • PDF file size is reasonable (< 15 MB)
  • Generated PDF is NOT committed to git