# Coherent Sapphire Laser Communication Protocol Specification

This document defines the serial communication protocol used by Coherent Sapphire lasers, as implemented in the Sapphire ESP32 Controller.

## 1. Physical Layer

- **Interface**: RS-232 (Requires TTL conversion for ESP32/Arduino)
- **Baud Rate**: 19200 bps
- **Data Bits**: 8
- **Parity**: None
- **Stop Bits**: 1
- **Flow Control**: None

## 2. Message Format

### 2.1 Commands
Commands are sent as ASCII strings terminated by a carriage return (`\r`) or a newline (`\n`). 

- **Queries**: Start with `?` (e.g., `?P`)
- **Settings**: Use `=` to assign values (e.g., `P=100.0`)

### 2.2 Responses
Responses are returned as ASCII strings, typically terminated by `\r\n`. 
- Some configurations may include a prompt character (`>`) at the start or end of a response.
- Responses may include a prefix such as `Sapphire -> ` depending on the device firmware version and settings.

---

## 3. Query Commands (Telemetry)

| Command | Description | Unit | Data Type |
| :--- | :--- | :--- | :--- |
| `?P` | Actual Output Power | mW | Float |
| `?C` | Laser Diode Current | A | Float |
| `?BT` | Baseplate Temperature | °C | Float |
| `?DT` | Laser Diode Temperature | °C | Float |
| `?PST` | Power Supply/Controller Temperature | °C | Float |
| `?DST` | Setpoint Temperature | °C | Float |
| `?STA` | System Status Code | - | Integer (See Sec 5) |
| `?FF` | Fault Flags | - | Bitmask (See Sec 6) |
| `?HH` | Laser Head Operating Hours | Hours | Integer |
| `?PSH` | Controller Operating Hours | Hours | Integer |
| `?WAVE` | Laser Wavelength | nm | Float |
| `?MINLP` | Minimum Rated Laser Power | mW | Float |
| `?MAXLP` | Maximum Rated Laser Power | mW | Float |
| `?DRC` | Diode Reserve Current | A | Float |

---

## 4. Control Commands

### 4.1 Power Control
- **Command**: `P=VALUE`
- **Example**: `P=50.5` sets the laser output to 50.5 mW.
- **Response**: Typically `OK` or the new value.

### 4.2 Configuration
- **Echo Control (`E`)**:
    - `E=0`: Disable command echo (recommended for automated controllers).
    - `E=1`: Enable command echo.
- **Prompt Control (`>`)**:
    - `>0`: Disable the `>` prompt character in responses.
    - `>1`: Enable the `>` prompt character.

---

## 5. Status Codes (`?STA`)

The `?STA` command returns an integer representing the current state of the laser:

| Code | State | Description |
| :--- | :--- | :--- |
| `1` | Start Up | Initializing electronics |
| `2` | Warmup | Bringing temperatures to setpoint |
| `3` | Standby | Ready to turn on |
| `4` | Laser On | Diode is active and emitting |
| `5` | Laser Ready | Stabilized and ready for use |
| `6` | Error | System fault detected |

---

## 6. Fault Flags (`?FF`)

The `?FF` command returns a bitmask representing internal diagnostics. Key bits identified:

- **Bit 8 (Value 256)**: **Warming**. Set during the thermal stabilization phase.
- **Bit 13 (Value 8192)**: **Ready/OK**. Indicates normal operation.
- **Other Values**: Any value other than `0` or `8192` usually indicates a fault condition.

---

## 7. Implementation Notes

### 7.1 Polling Rates
Coherent recommends a maximum polling rate of **1 Hz** (1000ms) for telemetry queries to ensure stability of the internal controller.

### 7.2 Connection Sequence
1. Send `?FF` to verify communication and check for initial faults.
2. Disable echo (`E=0`) and prompt (`>0`) for cleaner machine-to-machine parsing.
3. Query static parameters (`?WAVE`, `?MAXLP`, `?HH`) once at startup.
4. Enter a cyclic loop for dynamic telemetry (`?P`, `?C`, `?BT`, `?STA`).