# pymchppackinstall

**Repository Path**: bellstudio/pymchppackinstall

## Basic Information

- **Project Name**: pymchppackinstall
- **Description**: CLI tool to search and download Microchip CMSIS packs. Supports searching by name or keyword, viewing version
history, and downloading. Two data sources available with local caching (24h expiry).
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pymchppackinstall

A standalone CLI tool to search, download, install, and manage Microchip CMSIS packs from https://packs.download.microchip.com/. A pure Python replacement for MPLAB X `packmanagercli.bat` with no Java dependency.

## Installation

Requires Python 3.10+.

```bash
git clone <repository-url>
cd pymchppackinstall
pip install .
```

For development (editable install):

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/macOS
pip install -e ".[dev]"
```

## Usage

### Search for packs

Search by pack name, device part number, family, or keyword. All terms are AND-matched (case-insensitive).

```bash
pymchppackinstall search "PIC32MZ"
pymchppackinstall search "ATmega328P"
pymchppackinstall search "SAMD21"
pymchppackinstall search "pic32cm-pl"
```

Example output:

```
Found 2 pack(s) matching 'PIC32CM-PL':

  [1] Microchip PIC32CM-PL Series CMSIS Driver Support
      ID: CMSIS-Driver_PIC32CM-PL | Category: Software Packs
      Versions: v1.2.0 (2026-04-30) [latest]
               v1.1.1 (2026-04-02)
               v1.1.0 (2026-04-01)
               v1.0.1 (2026-01-21)
               v1.0.0 (2026-01-20)

  [2] Microchip PIC32CM-PL Series Device Support
      ID: PIC32CM-PL_DFP | Category: Device Family Package Microchip
      Devices: 11
      Versions: v1.3.414 (2026-05-06) [latest]
               v1.2.329 (2026-02-17)
               v1.1.324 (2026-01-15)
               v1.0.313 (2025-12-03)
```

### Show detailed pack info

View full release history with descriptions. Shows all matching packs:

```bash
pymchppackinstall info "PIC32CM-PL_DFP"
pymchppackinstall info "PIC32CM"
```

### Download a pack

Download the latest version:

```bash
pymchppackinstall download "PIC32CM-PL_DFP"
```

Download a specific version:

```bash
pymchppackinstall download "PIC32CM-PL_DFP" --version 1.0.313
```

Download to a specific directory:

```bash
pymchppackinstall download "ATtiny_DFP" --version 3.4.278 -o ./packs
```

### List all available packs

```bash
pymchppackinstall list
```

### Install a pack

Install the latest version from the remote repository:

```bash
pymchppackinstall install PIC32CM-JH_DFP
```

Install a specific version:

```bash
pymchppackinstall install PIC32CM-JH_DFP --version 1.4.224
```

Install from a local `.atpack` file (downloaded previously or obtained offline):

```bash
pymchppackinstall install --from-disk Microchip.PIC32CM-JH_DFP.1.5.236.atpack
```

Install to a custom location:

```bash
pymchppackinstall install SAMD21_DFP --location D:\my_packs
```

Force reinstall (overwrite existing):

```bash
pymchppackinstall install PIC32CM-JH_DFP --force
```

Packs are installed to `~/.mchp_packs/<Vendor>/<PackID>/<Version>/` by default (same structure MPLAB X uses).

### Uninstall a pack

Uninstall a specific version:

```bash
pymchppackinstall uninstall PIC32CM-JH_DFP --version 1.3.221
```

If only one version is installed, `--version` can be omitted:

```bash
pymchppackinstall uninstall ATmega_DFP
```

Uninstall a non-Microchip vendor pack:

```bash
pymchppackinstall uninstall CMSIS --version 5.4.0 --vendor ARM
```

### Check installed packs

List all locally installed packs:

```bash
pymchppackinstall installed
```

Example output:

```
Installed packs (64):

  Pack ID                                  Vendor       Versions
  ---------------------------------------- ------------ ------------------------------
  CMSIS                                    ARM          6.3.0, 6.2.0, 6.1.0, 5.9.0, 5.4.0
  ATmega_DFP                               Microchip    3.5.296
  PIC32CM-JH_DFP                           Microchip    1.5.236, 1.4.224, 1.3.221
  SAMD21_DFP                               Microchip    3.6.144
  ...

Total: 64 pack(s)
```

Filter installed packs by device name (cross-references with repository index):

```bash
pymchppackinstall installed --device-name PIC32CM5164JH
pymchppackinstall installed -d ATSAME51
```

Example output:

```
Filtering installed packs for device: PIC32CM5164JH
Fetching pack index (XML)...

Installed packs (1):

  Pack ID                                  Vendor       Versions
  ---------------------------------------- ------------ ------------------------------
  PIC32CM-JH_DFP                           Microchip    1.5.236, 1.4.224, 1.3.221

Total: 1 pack(s)
```

### Check .atpack files against installed packs

Verify whether `.atpack` files in a directory are already installed. The version is determined by reading the `.pdsc` metadata inside each archive (authoritative), with filename parsing as a fallback.

```bash
# Check current directory
pymchppackinstall check

# Check a specific folder
pymchppackinstall check C:\path\to\downloaded_packs

# Check against a custom install location
pymchppackinstall check C:\path\to\packs --location D:\my_packs
```

Example output:

```
Checking 5 pack(s) in: C:\packs

======================================================================
  Status       Pack ID                          Expected     Installed
  ------------ -------------------------------- ------------ --------------------
  [OK]         PIC32CM-JH_DFP                   1.5.236      1.5.236, 1.4.224
  [OK]         SAMD21_DFP                       3.6.144      3.6.144
  [MISMATCH]   ATmega_DFP                       3.4.100      3.5.296
  [MISSING]    PIC32MX_DFP                      1.7.400      (none)
  [SKIP]       renamed_file.atpack              (unable to parse)
======================================================================

Summary: 5 pack(s) checked
  OK:        2
  MISMATCH:  1 (different version installed)
  MISSING:   1 (not installed)
```

### Update installed packs

Update all installed packs to their latest available version:

```bash
pymchppackinstall update
```

Use `--verbose` for detailed progress:

```bash
pymchppackinstall --verbose update
```

### Data source selection

The tool supports two data sources for the pack index:

- **`xml`** (default) — Fetches `index.idx.gz`, a compact gzipped XML file (~1MB). Faster and more structured.
- **`html`** — Scrapes the HTML web page directly (~3MB). Produces slightly richer display names.

Use `--source` or `-s` to switch:

```bash
pymchppackinstall --source xml search "PIC32MZ"
pymchppackinstall -s html search "PIC32MZ"
```

#### Performance comparison

| Metric | XML | HTML |
|--------|-----|------|
| Network + parse (first run) | ~1.3s | ~0.7s |
| Raw cache (parse only) | ~0.58s | ~0.22s |
| JSON cache (pre-parsed) | ~0.02s | ~0.004s |
| Cache file size (raw) | 1.1 MB | 3.2 MB |
| Cache file size (JSON) | 542 KB | 660 KB |
| Data richness | Full (67K devices, toolchains, datasheets) | Pack summaries only |
| Stability | Structured XML with schema | HTML scraping, may break on redesign |

The tool uses a 3-tier cache strategy:
1. **JSON cache** (fastest) — pre-parsed pack data loaded directly, 28-56x faster than re-parsing
2. **Raw cache** — avoids network, re-parses from local gz/html file
3. **Network** — full fetch + parse, only on first run or with `--no-cache`

HTML is faster to parse because the HTML parser skips most page content, while the XML parser must decompress and parse the full 37MB uncompressed index with 500K+ lines. XML is the default because it's a smaller download, more robust, and provides richer metadata for potential future features.

### Caching

The pack index is cached locally to avoid repeated downloads. The cache expires after **24 hours** and is stored at:

- Windows: `C:\Users\<user>\.cache\pymchppackinstall\`
- Linux/macOS: `~/.cache/pymchppackinstall/`

Cached files:
- `index.idx.gz` / `index.html` — raw server response
- `packs_xml.json` / `packs_html.json` — pre-parsed pack data (used on subsequent runs for near-instant startup)

To force a fresh fetch from the server:

```bash
pymchppackinstall --no-cache search "PIC32MZ"
```

## Running without installation

If you prefer not to install, you can run directly as a Python module:

```bash
pip install requests
set PYTHONPATH=src
python -m mchp_pack_downloader search "PIC32MZ"
```

## How it works

The tool fetches the pack index from https://packs.download.microchip.com/ and parses it to extract pack metadata (names, versions, download URLs, device lists). It provides search, download, install, uninstall, and update capabilities via the command line. No API key or authentication is required.

`.atpack` files are standard ZIP archives. Installation extracts them into a directory structure compatible with MPLAB X:

```
~/.mchp_packs/
  Microchip/
    PIC32CM-JH_DFP/
      1.5.236/
      1.4.224/
    SAMD21_DFP/
      3.6.144/
  ARM/
    CMSIS/
      6.3.0/
```

Two index formats are supported:

| Source | URL | Format | Size |
|--------|-----|--------|------|
| `xml`  | `index.idx.gz` | Gzipped XML with full pack/device/release metadata | ~1MB |
| `html` | `/` (index page) | HTML page scraped for pack cards | ~3MB |

## Dependencies

- [requests](https://pypi.org/project/requests/) - HTTP client for fetching the index and downloading packs
- Python standard library `html.parser` - for HTML index parsing
- Python standard library `xml.etree.ElementTree` - for XML index parsing
- Python standard library `zipfile` - for extracting .atpack archives during install