Sapphire_ESP32/PROTOCOL.md

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).