From e73ca5b092a9ed0c87394fc86a39d685c23a1a8b Mon Sep 17 00:00:00 2001
From: Ben <ben@ben.us.com>
Date: Sun, 15 Dec 2024 12:00:00 -0800
Subject: [PATCH] Add Sapphire protocol specification

---
 PROTOCOL.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 PROTOCOL.md

diff --git a/PROTOCOL.md b/PROTOCOL.md
new file mode 100644
index 0000000..c03cec9
--- /dev/null
+++ b/PROTOCOL.md
@@ -0,0 +1,101 @@
+# 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`).