Metadata-Version: 2.4
Name: pymcp2222
Version: 1.0.1.7
Summary: Microchip MCP2222 USB-to-I2C/SPI/UART/IO bridge - CLI and Python library
Author-email: Microchip Technology <support@microchip.com>
License: MIT
Project-URL: Homepage, https://www.microchip.com
Keywords: Microchip
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pyusb
Requires-Dist: appdirs
Requires-Dist: libusb_package
Requires-Dist: rich
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pylint>=2.15; extra == "dev"
Provides-Extra: test
Requires-Dist: mock; extra == "test"
Requires-Dist: pytest; extra == "test"
Provides-Extra: doc
Requires-Dist: mock; extra == "doc"
Requires-Dist: sphinx; extra == "doc"
Dynamic: license-file

# pymcp2222 - Microchip MCP2222 USB-to-I2C/SPI/UART/IO Bridge - CLI and Python library

[![PyPI - Format](https://img.shields.io/pypi/format/pymcp2222)](https://pypi.org/project/pymcp2222/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pymcp2222)](https://pypi.org/project/pymcp2222/)
![PyPI - License](https://img.shields.io/pypi/l/pymcp2222)

---

## Overview

**pymcp2222** is a command-line tool and Python library to provision, configure, and control Microchip's MCP2222 USB-to-UART/I2C/SPI/IO bridge devices, with unified CLI and API.

---

## Installation

```bash
pip install pymcp2222
```

---

## Command-Line Usage

See all options and help with:

```bash
pymcp2222 --help
pymcp2222 <command> --help
```

### Device Listing

```bash
pymcp2222 list                                 # List devices (default VID/PID)
pymcp2222 --vid 0x1234 --pid 0x5678 list       # List devices with custom VID/PID
pymcp2222 --vid 0x04D8 --pid 0x0B15 --serial SERIALNO list
```

---

### GPIO Examples

```bash
pymcp2222 gpio read --pin 0
pymcp2222 gpio write --pin 2 --value 1
```

---

### IO Pin Control and Configuration Examples

```bash
# Set one pin
pymcp2222 io setconfig --pin 3 --config designation=GPIO3,direction=output,open_drain=1,idle_state=1,pull_up=1

# Set an alternate alert config
pymcp2222 io setconfig --pin 2 --config designation=ALRT1,direction=input,pull_up=1,edge=rising

# Get pin config
pymcp2222 io getconfig --pin 2
```

---

### I2C Protocol Examples

```bash
# Configure I2C bus
pymcp2222 i2c configure --speed 400kHz --timeout 100ms

# I2C write
pymcp2222 i2c write --address 0x55 --data 0xA0,0xB1
pymcp2222 i2c write --address 0x55 --input-file C:\\Users\\JohnDoe\\mydata.csv

# I2C read
pymcp2222 i2c read --address 0x55 --length 2
pymcp2222 i2c read --address 0x55 --length 10 --output-file C:\\Users\\JohnDoe\\result.csv

# I2C write-read (repeated start)
pymcp2222 i2c write_read --address 0x12 --write-data 0xEF,0xAB --read-length 2 --output-file C:\\Users\\JohnDoe\\readback.csv

# I2C line diagnostics and recovery
pymcp2222 i2c get_scl_sda
pymcp2222 i2c bus_recovery
```

---

### SPI Protocol Examples

```bash
# Configure SPI
pymcp2222 spi configure --cs CS1 --speed 3MHz --mode 0 --polarity active_low --delay 100

# SPI write
pymcp2222 spi write --data 0xAA,0xBB
pymcp2222 spi write --input-file C:\\Users\\JohnDoe\\mydata.csv

# SPI read
pymcp2222 spi read --length 4
pymcp2222 spi read --length 16 --output-file C:\\Users\\JohnDoe\\readbytes.csv

# SPI exchange (full duplex)
pymcp2222 spi exchange --data 0x01,0x02,0x03
pymcp2222 spi exchange --input-file C:\\Users\\JohnDoe\\in.csv --output-file C:\\Users\\JohnDoe\\out.csv
```

---

### CONFIG Command (Full Device Configuration) Examples

```bash
# Get config
pymcp2222 config get usb
pymcp2222 config get manufacturer
pymcp2222 config get product_name
pymcp2222 config get serial_number
pymcp2222 config get io --source EEPROM
pymcp2222 config get i2c --source SRAM
pymcp2222 config get spi --source SRAM
pymcp2222 config get protection_level
pymcp2222 config get rev_id

# Set manufacturer/product/serial
pymcp2222 config set manufacturer --name "Microchip Inc."
pymcp2222 config set product_name --name "My Product"
pymcp2222 config set serial_number --new-serial "SN0010002"

# Set USB (with optional custom VID/PID, power descriptors)
pymcp2222 config set usb --newvid 0x1234 --newpid 0x5678 --max-current 250mA
pymcp2222 config set usb --newvid 0x04D8 --newpid 0x0B15 --max-current 250mA --self-powered --remote-wakeup --serial-enabled
pymcp2222 --vid 0x1234 --pid 0x5678 config set usb --newvid 0x04D8 --newpid 0x0B15 --max-current 250mA

# Set all IO pins at once
pymcp2222 config set io \
    --pin0 designation=GPIO0,direction=output,open_drain=1,idle_state=1,pull_up=1 \
    --pin1 designation=GPIO1,direction=input,pull_up=1 \
    --pin2 designation=ALRT1,direction=input,pull_up=1,edge=rising \
    --pin3 designation=CLKO,direction=output,clkdiv=4MHZ \
    --pin4 designation=ALRT2,direction=input,pull_up=0,edge=falling \
    --pin5 designation=ALRT3,direction=input,edge=rising,pull_up=0

# Set I2C/SPI config
pymcp2222 config set i2c --speed 400kHz --timeout 100ms
pymcp2222 config set spi --speed 3MHz --mode 0 --cs CS1 --polarity active_low --delay 2500

# Password protection/config locking
pymcp2222 config enable_password --password abcd1234
pymcp2222 config disable_password --password abcd1234
pymcp2222 config lock_config --password abcd1234
pymcp2222 config unlock_config --password abcd1234
pymcp2222 config change_password --old abcd1234 --new 4321dcba
pymcp2222 config permanent_lock --serial-number SN0010002

# Copy EEPROM to SRAM, restore factory defaults, soft reset
pymcp2222 config eeprom_as_current
pymcp2222 config reset_to_factory
pymcp2222 config soft_reset
```

---

## Python API Usage

Here are examples for all main API types/classes.  
All exceptions raised are documented in the respective method docstrings.

---

### Device Enumeration (list_mcp2222_devices.py)
```python
from pymcp2222.list_mcp2222_devices import list_devices
devices = list_devices()
for d in devices:
    print(f"Device: vid={d.vid:04x} pid={d.pid:04x} serial={d.serial} product={d.product}")
```

---

### Device Connection and Basic Usage (mcp2222device.py)
```python
from pymcp2222.mcp2222device import MCP2222Device
dev = MCP2222Device()  # Default VID/PID. Or: MCP2222Device(vid=0x1234, pid=0x5678, serial="...")
dev.open()
print("Connected:", dev.get_connected_device_info())
dev.close()
```

---

### Configure IO pin and get configuration (io.py)
**Configure IO pin**
```python
from pymcp2222.io import IOPinConfig, IODirection, IO0Designation

dev = MCP2222Device()
config = IOPinConfig(
    designation=IO0Designation.GPIO0,
    direction=IODirection.OUTPUT,
    open_drain=True,
    idle_state=True,
    pull_up=True
)
dev.io.set_config(0, config)
result = dev.io.get_config(0)
print(result)
```

**Read/Write a GPIO**
```python
from pymcp2222.mcp2222device import MCP2222Device
from pymcp2222.io import GpioVal

dev = MCP2222Device()
dev.open()
state = dev.io.gpio_read(0)
print("GPIO0 state:", state)
dev.io.gpio_write(0, GpioVal.HIGH)
dev.close()
```

---

### Device-wide IO Configuration (mcp2222device.py)

**Set all IO pins (EEPROM, takes effect after power-cycle or soft-reset):**
```python
from pymcp2222.mcp2222device import MCP2222Device, IOSettings
from pymcp2222.io import IOPinConfig, IODirection, IO0Designation, IO1Designation, IO2Designation, IO3Designation, IO4Designation, IO5Designation

dev = MCP2222Device()
setting = IOSettings([
    IOPinConfig(IO0Designation.GPIO0, IODirection.OUTPUT, open_drain=True, idle_state=True, pull_up=True),
    IOPinConfig(IO1Designation.GPIO1, IODirection.INPUT, pull_up=True),
    IOPinConfig(IO2Designation.ALRT1, IODirection.INPUT, pull_up=True),
    IOPinConfig(IO3Designation.CLKO, IODirection.OUTPUT, open_drain=True, idle_state=False),
    IOPinConfig(IO4Designation.ALRT2, IODirection.INPUT, pull_up=False),
    IOPinConfig(IO5Designation.ALRT3, IODirection.INPUT, pull_up=False)
])
dev.set_io_power_on_config(setting)
```

**Get all IO pin configs (SRAM or EEPROM):**
```python
from pymcp2222.mcp2222device import ConfigSource
io_config = dev.get_io_config(ConfigSource.EEPROM)
print(io_config.to_dict())
```

---

### I2C: Configure, Read, Write, Write_Read (i2c.py)
**Configure I2C (in EEPROM for next power-on):**
```python
from pymcp2222.mcp2222device import MCP2222Device
from pymcp2222.i2c import I2CParams, I2CSpeed

dev = MCP2222Device()
params = I2CParams(I2CSpeed.FREQ_400KHZ, timeout=100)
dev.set_i2c_power_on_config(params)

# Get I2C config from EEPROM/SRAM
i2c_params_eeprom = dev.get_i2c_config(ConfigSource.EEPROM)
print("I2C EEPROM config:", i2c_params_eeprom.to_dict())
i2c_params_sram = dev.get_i2c_config(ConfigSource.SRAM)
print("I2C SRAM config:", i2c_params_sram.to_dict())
```

**I2C Runtime Operations:**
```python
dev.open()
dev.i2c.configure(params)
dev.i2c.write(0x55, [0xA0, 0xB1, 0x02])
data = dev.i2c.read(0x55, 2)
print("I2C read result:", list(data))
data2 = dev.i2c.write_read(0x55, [0xA0, 0xB1], 2)
print("I2C write_read result:", list(data2))
dev.close()
```

**I2C Line Status / Bus Recovery:**
```python
status = dev.i2c.get_scl_sda_status()
print("SCL High:", status.scl_high, "SDA High:", status.sda_high)
success = dev.i2c.bus_recovery()
print("Bus recovery:", "Released" if success else "Failed")
```

---

### SPI: Configure, Write, Read, Exchange (spi.py)
**Write SPI settings to EEPROM (power-on config):**
```python
from pymcp2222.mcp2222device import MCP2222Device
from pymcp2222.spi import SPIParams, SPISpeed, SPIMode, SpiCs, SpiCsPolarity

dev = MCP2222Device()
params = SPIParams(speed=SPISpeed.FREQ_3MHZ, mode=SPIMode.MODE0,
    cs=SpiCs.CS1, polarity=SpiCsPolarity.ACTIVE_LOW, delay_us=100)
dev.set_spi_power_on_config(params)

# Get SPI config from EEPROM/SRAM
spi_params_eeprom = dev.get_spi_config(ConfigSource.EEPROM)
print("SPI EEPROM config:", spi_params_eeprom.to_dict())
spi_params_sram = dev.get_spi_config(ConfigSource.SRAM)
print("SPI SRAM config:", spi_params_sram.to_dict())
```

**Configure runtime SPI and exchange data:**
```python
dev.open()
dev.spi.configure(SPISpeed.FREQ_3MHZ, SPIMode.MODE0, SpiCsPolarity.ACTIVE_LOW, SpiCs.CS1, delay_us=100)
dev.spi.write([0xAA, 0xBB])
read_bytes = dev.spi.read(4)
print("SPI read result:", list(read_bytes))
echo = dev.spi.exchange([0x01, 0x02, 0x03, 0x04])
print("SPI exchange result:", list(echo))
dev.close()
```

---

### Device Configuration APIs (mcp2222device.py)

**Set/get manufacturer/product/serial [max 30 characters]**
```python
dev.set_manufacturer("Microchip Inc.")
print(dev.get_manufacturer())
dev.set_product_name("My Product")
print(dev.get_product_name())
dev.set_serial_number("SN0010002")
print(dev.get_serial_number())
```

**Set USB config (VID/PID, current, flags):**
```python
from pymcp2222.mcp2222device import USBParams, USBDevcfg
usbparams = USBParams(
    vid=0x1234, pid=0x5678,
    devcfg=USBDevcfg(self_powered=True, remote_wakeup=False, serial_number_enabled=True),
    max_current=250)
dev.set_usb_params(usbparams)
cfg = dev.get_usb_params()
print(cfg)
```

**Change/enable/disable password [8 characters], lock config, factory reset, soft reset:**
```python
dev.enable_password("abcd1234")
dev.disable_password("abcd1234")
dev.lock_config("abcd1234")
dev.unlock_config("abcd1234")
dev.change_password("abcd1234", "4321dcba")
dev.reset_to_factory()
dev.soft_reset()
```

**Permanently lock config (requires serial):**
```python
dev.permanent_lock("SERIAL")
```

**Get protection level:**
```python
lvl = dev.get_protection_level()
print(lvl.description)
```

**Get Revision ID:**
```python
id = dev.get_rev_id()
print(id.value)
```

---

## Additional Information
- Full CLI reference: `pymcp2222 --help`
- CLI + Python API for all device/IO/I2C/SPI/config operations.
- [MCP2222 Product Page](https://www.microchip.com/en-us/product/MCP2222)
# Changelog

## [1.0.1] - August 2026

Initial public release.
