# MpyTool - Sublime Text Plugin

Sublime Text 4 plugin for MicroPython development.

Seamlessly upload and run MicroPython code on your microcontroller directly from Sublime Text. No more switching between editor and terminal.

![MpyTool Deploy](screenshots/mpytool-sublime.png)

## Why MpyTool?

- **One-click deploy** - Write code, hit a shortcut, see it running on device
- **Instant feedback** - Monitor serial output without leaving the editor
- **Project-based workflow** - Configure once, deploy anywhere
- **Multiple devices** - Switch between boards effortlessly

## Features

- **Auto-detection** - Finds `.mpyproject` from current file upward
- **Manual selection** - Switch between multiple projects
- **Port selection** - Prompts when multiple devices connected or configured port unavailable
- **Compile to .mpy** - Optional bytecode compilation for faster imports and less RAM usage
- **Run current file** - Execute current Python file directly on device
- **Multiple reset modes** - Soft, machine, RTS, bootloader
- **Status bar** - Shows active project name
- **Backup/Restore** - Save and restore device filesystem
- **Terminus integration** - REPL inside Sublime Text (falls back to external terminal)

## Quick Start

1. Install [mpytool](https://github.com/pavelrevak/mpytool) CLI: `pip install mpytool`
2. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
3. Run `MPY: New Project...` to create `.mpyproject` in your project root
4. Use `MPY: Deploy to Device` (`Cmd+Option+U`) to upload and run

## Installation

### Package Control (recommended)

1. Open Command Palette
2. Run `Package Control: Install Package`
3. Search for `mpytool`

### Manual

Clone or download to Sublime Text Packages directory:

```bash
# macOS
cd ~/Library/Application\ Support/Sublime\ Text/Packages
git clone https://github.com/pavelrevak/mpytool-sublime.git

# Linux
cd ~/.config/sublime-text/Packages
git clone https://github.com/pavelrevak/mpytool-sublime.git
```

## Commands

All commands available via Command Palette (`Cmd+Shift+P`) with `MPY:` prefix.

| Command | Description |
|---------|-------------|
| **Deploy to Device** | Upload files + reset + monitor output |
| **Sync to Device** | Upload files + reset (no monitor) |
| **Run Current File** | Run current .py file on device |
| **Monitor** | Watch serial output |
| **Open REPL** | Interactive Python console |
| **Reset Device** | Soft/machine/hardware reset |
| **List Files** | Show file tree on device |
| **Device Info** | Show device information |
| **Backup Device** | Download all files to `.backup/` |
| **Restore Backup** | Upload `.backup/` to device |
| **Erase Device** | Remove all files from device |
| **New Project...** | Create `.mpyproject` file |
| **Project Settings** | Open `.mpyproject` for editing |
| **Select Project...** | Choose active project |
| **Select Port...** | Choose serial port for project |
| **Stop** | Stop running process |

## Keyboard Shortcuts

| macOS | Windows/Linux | Command |
|-------|---------------|---------|
| `Cmd+Option+U` | `Ctrl+Alt+U` | Deploy to Device |
| `Cmd+Option+M` | `Ctrl+Alt+M` | Monitor |

## Sidebar Menu

Right-click on files/folders → **MicroPython**:

- **New Project...** - Create new project here
- **Project Settings** - Open project configuration
- **Set as Active Project** - Set this project as active
- **Copy to Device...** - Upload file or folder
- **Add to Deploy** - Add to deploy configuration
- **Add to Exclude** - Add to exclude list
- **Add to Other Project...** - Add to another project's deploy

## Configuration

### .mpyproject

Create `.mpyproject` in your project root:

```json
{
    "name": "my-project",
    "port": "auto",
    "compile": true,
    "deploy": {
        "": ["./"]
    },
    "exclude": ["__pycache__", "*.pyc", ".backup"]
}
```

| Field | Description |
|-------|-------------|
| `name` | Project name (shown in status bar) |
| `port` | Serial port or `"auto"` for auto-detection |
| `compile` | Compile .py to .mpy before upload (requires mpy-cross) |
| `deploy` | Map of device paths → local sources |
| `exclude` | Patterns to exclude from upload |

### Deploy Format

Device paths use mpytool `:` prefix convention — paths are relative to device CWD
(default `/`). Use `/` prefix for absolute paths (e.g. `"/lib/"` → `:/lib/`).

Deploy supports two modes based on destination path:

**Directory mode** - destination is `""` or ends with `/`:
```json
"deploy": {
    "": ["./"],                    // upload to device CWD
    "lib/": ["mylib/", "utils.py"] // upload multiple items to lib/
}
```

**Rename mode** - destination doesn't end with `/`:
```json
"deploy": {
    "main.py": "src/app.py",       // upload and rename file
    "lib/driver": "../drivers/v2"  // upload and rename directory
}
```

### Deploy Examples

```json
// Upload entire project to device CWD
"deploy": {
    "": ["./"]
}

// Upload specific files to specific locations
"deploy": {
    "": ["main.py", "boot.py"],
    "lib/": ["lib/", "../shared/utils.py"]
}

// Upload with rename
"deploy": {
    "": ["./"],
    "config.json": "config_prod.json"
}
```

### Plugin Settings

`Preferences → Package Settings → MpyTool → Settings`:

```json
{
    "mpytool_path": "mpytool",
    "deploy_on_save": false
}
```

| Setting | Description |
|---------|-------------|
| `mpytool_path` | Path to mpytool executable |
| `deploy_on_save` | Auto-deploy file on save (default: `false`) |

### Deploy on Save

When `deploy_on_save` is enabled, saving a file automatically deploys it to device if:
- File is within project sources (defined in `deploy`)
- File doesn't match any `exclude` pattern

Enable globally in settings or per-project in `.mpyproject`:

```json
{
    "deploy_on_save": true,
    "deploy": {"": ["./"]}
}
```

## Requirements

- Sublime Text 4 (build 4065+)
- [mpytool](https://github.com/pavelrevak/mpytool) CLI
- Optional: [Terminus](https://packagecontrol.io/packages/Terminus) for in-editor REPL

## License

MIT