# 86Duino CLI Reference

## Purpose

This reference document provides supplementary lookup information for the `hermes-86duino-cli` skill, focusing on:
- Common board-name colloquialisms and their candidate FQBNs
- The 86Duino board list obtained from this machine's actual `board listall` output
- Executable-name differences between Windows and macOS
- Common command templates
- Port-detection examples for Windows and macOS
- Common failure modes and recommended response patterns

> Note: this document is reference material; it does not replace the main skill's execution rules. At runtime, always defer to the actual `board listall` output, real filesystem presence, and explicit user confirmation.

## Local Discovery Notes

I have actually inspected the `86Duino_Coding` folder on the Desktop of this macOS machine.

The actual executable found is:
```text
/Users/acen/Desktop/86Duino_Coding/86duino-cli
```

> Note: on this machine the file found is `86duino-cli`, not `86duino-cli.exe`. When the skill executes on a real machine, always defer to the actual filename present.

Actual execution command:
```bash
cd /Users/acen/Desktop/86Duino_Coding
./86duino-cli board listall
```

The 86Duino board list below comes from that on-machine query and, per your request, omits all Arduino entries.

## Executable Name Compatibility

The CLI filename can differ across platforms:

- macOS / Linux: usually `86duino-cli`
- Windows: usually `86duino-cli.exe`

Handling principles:
- If the actual filename is `86duino-cli`, invoke it as `./86duino-cli`
- If the actual filename is `86duino-cli.exe`, invoke it as `86duino-cli.exe`
- Do not forcibly rewrite the macOS `86duino-cli` into `.exe`
- Before actually executing, defer to the name that exists on the filesystem

## Actual 86Duino Board List From This Machine

Below are the **86Duino-related boards** actually listed by `./86duino-cli board listall` on this machine:

| Board Name | FQBN |
|---|---|
| 86Duino DUO | `86duino:x86:86DuinoEX2` |
| 86Duino EduCake | `86duino:x86:EduCake` |
| 86Duino ONE | `86duino:x86:86DuinoONE` |
| 86Duino QEC | `86duino:x86:86DuinoQEC` |
| 86Duino QEC15 | `86duino:x86:86DuinoQEC15` |
| 86Duino QEC7 | `86duino:x86:86DuinoQEC7` |
| 86Duino QEC9 | `86duino:x86:86DuinoQEC9` |
| 86Duino QECM02 | `86duino:x86:86DuinoQECM02` |
| 86Duino QECM2 | `86duino:x86:86DuinoQECM2` |
| 86Duino QECPPC104 | `86duino:x86:86DuinoQECPPC104` |
| 86Duino QECPPC15 | `86duino:x86:86DuinoQECPPC15` |
| 86Duino QECPPC9 | `86duino:x86:86DuinoQECPPC9` |
| 86Duino ZERO | `86duino:x86:86DuinoZERO` |

## Common Board Name Mapping

The table below is only a "best-effort initial guess" and does not replace an actual query.

| User phrasing | Candidate board / interpretation | Candidate FQBN | Notes |
|---|---|---|---|
| QEC board | 86Duino QEC | `86duino:x86:86DuinoQEC` | Still verify with `board listall` |
| QEC 7-inch board | 86Duino QEC7 | `86duino:x86:86DuinoQEC7` | Still verify with `board listall` |
| QEC 9-inch board | 86Duino QEC9 | `86duino:x86:86DuinoQEC9` | Still verify with `board listall` |
| QEC 15-inch board | 86Duino QEC15 | `86duino:x86:86DuinoQEC15` | Still verify with `board listall` |
| QEC M02 | 86Duino QECM02 | `86duino:x86:86DuinoQECM02` | Still verify with `board listall` |
| QEC M2 | 86Duino QECM2 | `86duino:x86:86DuinoQECM2` | Still verify with `board listall` |
| QEC PPC104 | 86Duino QECPPC104 | `86duino:x86:86DuinoQECPPC104` | Still verify with `board listall` |
| QEC PPC15 | 86Duino QECPPC15 | `86duino:x86:86DuinoQECPPC15` | Still verify with `board listall` |
| QEC PPC9 | 86Duino QECPPC9 | `86duino:x86:86DuinoQECPPC9` | Still verify with `board listall` |
| DUO | 86Duino DUO | `86duino:x86:86DuinoEX2` | Name is not intuitive; pay extra attention to the FQBN |
| ONE | 86Duino ONE | `86duino:x86:86DuinoONE` | Still verify with `board listall` |
| ZERO | 86Duino ZERO | `86duino:x86:86DuinoZERO` | Still verify with `board listall` |
| EduCake | 86Duino EduCake | `86duino:x86:EduCake` | Be careful when the FQBN naming does not track the board name |
| "flash" / "burn" | upload | N/A | Equivalent to upload in this skill |
| "rebuild" / "clean build" | clean build | N/A | Equivalent to `compile --clean` in this skill |

## Board Resolution Procedure

### Step 1: Query the board list
On this machine, prefer the actual executable present:
```bash
cd /Users/acen/Desktop/86Duino_Coding
./86duino-cli board listall
```

If running in other environments:
- macOS / Linux: try `./86duino-cli board listall` first
- Windows: try `86duino-cli.exe board listall` first

### Step 2: Find candidates in the output
On this machine, the actual 86Duino output looks like:
```text
86Duino DUO                      86duino:x86:86DuinoEX2
86Duino EduCake                  86duino:x86:EduCake
86Duino ONE                      86duino:x86:86DuinoONE
86Duino QEC                      86duino:x86:86DuinoQEC
86Duino QEC15                    86duino:x86:86DuinoQEC15
86Duino QEC7                     86duino:x86:86DuinoQEC7
86Duino QEC9                     86duino:x86:86DuinoQEC9
86Duino QECM02                   86duino:x86:86DuinoQECM02
86Duino QECM2                    86duino:x86:86DuinoQECM2
86Duino QECPPC104                86duino:x86:86DuinoQECPPC104
86Duino QECPPC15                 86duino:x86:86DuinoQECPPC15
86Duino QECPPC9                  86duino:x86:86DuinoQECPPC9
86Duino ZERO                     86duino:x86:86DuinoZERO
```

### Step 3: Match the user's board description
Handling principles:
1. First match against any board name explicitly given by the user
2. If only a colloquialism is available, find the closest candidate
3. If multiple candidates remain plausible, list the candidate Board Names and FQBNs and ask the user to confirm
4. If no reasonable candidate exists, do not guess

## Common Command Templates

### 1) List boards
macOS / Linux:
```bash
cd /Users/acen/Desktop/86Duino_Coding
./86duino-cli board listall
```

Windows:
```bash
86duino-cli.exe board listall
```

### 2) Compile
macOS / Linux:
```bash
./86duino-cli compile --fqbn <FQBN> <PROJECT_PATH> --verbose
```

Windows:
```bash
86duino-cli.exe compile --fqbn <FQBN> <PROJECT_PATH> --verbose
```

### 3) Clean rebuild
macOS / Linux:
```bash
./86duino-cli compile --fqbn <FQBN> <PROJECT_PATH> --clean --verbose
```

Windows:
```bash
86duino-cli.exe compile --fqbn <FQBN> <PROJECT_PATH> --clean --verbose
```

### 4) Compile and upload
macOS / Linux:
```bash
./86duino-cli compile --fqbn <FQBN> --port <PORT> --upload <PROJECT_PATH> --verbose
```

Windows:
```bash
86duino-cli.exe compile --fqbn <FQBN> --port <PORT> --upload <PROJECT_PATH> --verbose
```

## Project Path Handling Notes

### Common user phrasing
- `the sketch_mar24b folder on the desktop`
- `it's in Downloads/arduino_cli/sketch_mar24b`
- `a folder on the desktop`

### Handling principles
- If the user gives a colloquial location, you may first derive a plausible absolute path
- For example, "the sketch_mar24b folder on the desktop" usually corresponds to:
  - Windows: `C:\Users\<USER>\Desktop\sketch_mar24b`
  - macOS: `~/Desktop/sketch_mar24b`
- However, before actually executing, verify in the tool that the directory exists
- If it does not exist, clearly tell the user instead of pretending the path is valid

## Port Detection Reference

### Windows detection target
Look under "Device Manager > Ports (COM & LPT)" for an item whose name begins with:
- `Prolific PL2303GC`

### Windows example
```text
Prolific PL2303GC USB Serial COM Port (COM6)
```

Available port:
```text
COM6
```

### macOS (Apple Silicon) detection target
List `/dev/tty.*` and look for a name that contains or begins with:
- `PL2303`

### macOS example
```text
/dev/tty.Bluetooth-Incoming-Port
/dev/tty.debug-console
/dev/tty.PL2303G-USBtoUART1120
```

Available port:
```text
/dev/tty.PL2303G-USBtoUART1120
```

## Multi-Port Handling

If multiple PL2303 devices are detected at the same time:
- Do not pick one arbitrarily
- Unless exactly one is an obvious correct candidate
- Otherwise present the candidates and let the user confirm

Suggested response template:
```text
I found multiple possible PL2303 serial ports. Please tell me which one to use so I can proceed with the upload.
```

## Common Failure Cases

### 1) Cannot find `86Duino_Coding`
This means the required folder is missing from the Desktop.

Suggested response:
```text
I notice that the 86Duino_Coding folder is not on the Desktop. It should contain 86duino-cli (or 86duino-cli.exe on Windows). Please create this folder, place the correct CLI executable inside, and then notify me so I can continue.
```

### 2) Cannot find the executable 86Duino CLI
This means the folder may exist, but the required executable does not.

Suggested response:
```text
I found the 86Duino_Coding folder, but the executable 86duino-cli (or 86duino-cli.exe on Windows) is not inside. Please put the correct CLI file in and I will continue.
```

### 3) Cannot find a PL2303 port
This means the cable may not be plugged in, the driver may not be ready, or the device is not recognized by the system.

Suggested response:
```text
I cannot find a PL2303 serial port on your system. Have you forgotten to plug in the cable?
```

### 4) Board name cannot be uniquely matched
This means additional confirmation of the model is needed.

Suggested response:
```text
I found multiple possible matching boards. Please confirm which one you are using so I can pick the correct FQBN.
```

### 5) Upload failure
This means the workflow must stop immediately.

Handling principles:
- Stop subsequent steps immediately
- Report the raw error output to the user
- Do not pretend the upload succeeded

## Response Fragments

### Missing project path and board model
```text
Please provide the absolute path of the 86Duino project and the target board name so I can look up the corresponding FQBN and start compiling.
```

### Missing port
```text
I need to obtain an available PL2303 serial port before I can upload the program to the board.
```

### Need to use an additional parameter
```text
I need to use an additional 86duino-cli / arduino-cli-compatible parameter next: <PARAMETER>, because <REASON>. If you agree, I will proceed.
```

## Quick Checklist

- [ ] Confirmed `86Duino_Coding` exists on the Desktop
- [ ] Confirmed the actual executable exists (e.g., `86duino-cli` or `86duino-cli.exe`)
- [ ] Obtained the absolute project path
- [ ] Looked up the candidate FQBN via `board listall`
- [ ] Handled ambiguous board-name cases
- [ ] If uploading, obtained a valid port
- [ ] If there are multiple ports, asked the user to confirm
- [ ] Used `--verbose`
- [ ] If an upload failed, stopped and reported the raw error