seb-cli-tool/scripts/README.md

SEB CLI - Smart Embedded Board Configuration Tool - Cloud-First MCU Management

# SEB CLI MCU Upload Scripts

This directory contains scripts for uploading MCU YAML definitions to the SEB CLI cloud registry.

## Scripts Overview

### 1. `validate_mcus.py` - Validation Script
Validates all MCU YAML files in the `mcu_definitions/` directory.

```bash
python scripts/validate_mcus.py
```

**Features:**
- ✅ Validates YAML syntax
- ✅ Checks required MCU fields
- ✅ Verifies pin alternate functions
- ✅ Reports validation summary

### 2. `upload_mcu.py` - Single MCU Upload
Uploads a single MCU YAML definition to the cloud registry.

```bash
# Basic usage
python scripts/upload_mcu.py mcu_definitions/stm32f103c8t6.yaml

# With custom description
python scripts/upload_mcu.py mcu_definitions/atmega328p.yaml "Arduino Uno MCU"

# With custom manufacturer
python scripts/upload_mcu.py mcu_definitions/msp430g2553.yaml "TI LaunchPad MCU" "Texas Instruments"

# Mark as unofficial
python scripts/upload_mcu.py mcu_definitions/custom_mcu.yaml --unofficial
```

**Features:**
- 🔍 Automatic validation before upload
- 🏭 Auto-detects manufacturer from MCU family
- 📝 Auto-generates descriptions
- ⚙️ Configurable parameters
- 🚀 Direct upload to cloud registry

### 3. `upload_all_mcus.py` - Batch Upload
Uploads all MCU YAML definitions in the `mcu_definitions/` directory.

```bash
python scripts/upload_all_mcus.py
```

**Features:**
- 🔍 Validates all files first
- 📤 Batch upload with progress tracking
- ⏱️ Rate limiting to avoid API limits
- 📊 Upload summary report
- 💡 Post-upload CLI usage hints

## MCU YAML Structure

Your MCU YAML files should follow this structure:

```yaml
# MCU Configuration
mcu:
  name: mcu_name
  family: mcu_family
  package: package_type
  flash_size: flash_size
  ram_size: ram_size
  max_frequency: max_frequency

# Clock configuration
clock:
  frequencies: [1MHz, 8MHz, 16MHz]
  external_crystal: true
  internal_oscillator: true

# Pin alternate functions
pin_alternate_functions:
  PA0:
    UART2_TX: 7
    TIM2_CH1: 1
    ADC12_IN0: 0
  # ... more pins

# Peripheral configurations
peripherals:
  uart1:
    baudrate: 115200
    description: "Serial communication"
  # ... more peripherals

# Board information
board_info:
  name: "Board Name"
  description: "Board description"
  manufacturer: "Manufacturer Name"
  datasheet_url: "https://example.com/datasheet.pdf"
```

## Adding New MCUs

### Step 1: Create MCU Definition
1. Create a new YAML file in `mcu_definitions/`
2. Follow the structure above
3. Include all pin alternate functions
4. Add comprehensive peripheral configurations

### Step 2: Validate
```bash
python scripts/validate_mcus.py
```

### Step 3: Upload
```bash
# Upload single MCU
python scripts/upload_mcu.py mcu_definitions/your_mcu.yaml

# Or upload all MCUs
python scripts/upload_all_mcus.py
```

### Step 4: Test
```bash
# Switch back to main CLI directory
cd ..

# Test validation
python -m seb.cli.main validate your_mcu_name

# Test compilation
python -m seb.cli.main compile your_mcu_name --verbose
```

## Supported MCU Families

The scripts automatically detect manufacturers for these families:

- **STM32 Series** (STMicroelectronics)
  - `stm32f1`, `stm32f4`, `stm32l4`
- **AVR Series** (Microchip Technology)
  - `avr`
- **MSP430 Series** (Texas Instruments)
  - `msp430`, `tiva`
- **LPC Series** (NXP Semiconductors)
  - `lpc`, `kinetis`
- **RX Series** (Renesas Electronics)
  - `rx`, `ra`

## Error Handling

The scripts include comprehensive error handling:

- **Validation Errors**: Invalid YAML syntax, missing fields
- **Network Errors**: Connection issues, timeouts
- **API Errors**: Server errors, duplicate filenames
- **File Errors**: Missing files, permission issues

## Best Practices

1. **Always validate** before uploading
2. **Use descriptive names** for MCU files
3. **Include complete pin mappings** with alternate functions
4. **Add comprehensive documentation** in board_info section
5. **Test after upload** using the CLI
6. **Keep backups** of your YAML definitions

## Troubleshooting

### Upload Fails with "File Already Exists"
The MCU is already in the registry. Use the update command instead:
```bash
python -m seb.cli.main registry update <board_id> mcu_definitions/your_mcu.yaml
```

### Validation Fails
Check that your YAML file:
- Has valid YAML syntax
- Contains all required MCU fields
- Has proper indentation
- Uses correct data types

### Network Errors
- Check internet connection
- Verify registry URL is accessible
- Try again after a few minutes

## Contributing

When adding new MCUs:

1. Create comprehensive YAML definitions
2. Test validation locally
3. Upload to development environment first
4. Test with CLI before production
5. Document any special configurations