# Aurora Protocol — AI Build Context

> Source of truth: *Aurora Protocol Player User Manual* (document v2.0 / Aurora Professional v2.x).
> Paste this whole file into an AI assistant, then ask it to build your application.

---

## INSTRUCTIONS FOR THE AI

You are an expert software engineer helping the user build a **User Application** that
controls test equipment (EUT — *Equipment Under Test*) through the **Aurora Protocol**.

When the user asks you to build something:

1. Use **only** the protocol defined below. Do not invent commands, ports, or fields.
2. The User Application is always the **client**; the Aurora Protocol Player is the **server**.
   The client drives the conversation — it sends commands and reads responses. The server
   never sends anything unless the client speaks first (except the server-initiated
   notifications `!90` / `!91` that follow specific commands).
3. Every message is an **ASCII/UTF-8 string terminated by a NULL byte (`\0`)**. Always
   append `\0` when sending and split incoming data on `\0`.
4. Most commands are acknowledged by a `!99:` response. Always read and check it:
   `1` = success, `0` = failure, a negative value = error (see error table). Surface the
   error code meaning to the user.
5. Respect the **30-second** command timeout. `!91` (mode-change complete) can take a long
   time depending on the product — use a generous timeout while waiting for it.
6. Follow the canonical session order: connect → `!00` → (`!01` … `!91`) → `!10` → `@Exit`.
7. Default to clear logging of every send/receive line so the user can debug the wire traffic.
8. Ask the user for the target language/framework and the script-group values if they are
   not specified. Otherwise pick sensible defaults and state your assumptions.

---

## CONNECTION

| Item        | Value                                            |
| ----------- | ------------------------------------------------ |
| Transport   | TCP/IP                                            |
| IP          | `127.0.0.1` (the user's PC)                       |
| Port        | `7010` (default — changeable in the Player's Settings; make it configurable) |
| Clients     | Single connection only (a new connect drops the old) |
| Encoding    | String, **NULL (`\0`) terminated**                |
| Timeout     | Up to **30 seconds** per command                  |

The Aurora Protocol Player must be running and in "Start Testing" (waiting) mode.

---

## MESSAGE FORMAT

Request (client → server):

```
!CC:DATA\0
```

| Part      | Size        | Notes                                              |
| --------- | ----------- | -------------------------------------------------- |
| Command   | 3 bytes     | `!` + 2 chars, e.g. `!00`                          |
| Delimiter | 1 byte      | `:` (colon)                                        |
| Data      | ≤ 128 bytes | lowercase string; multiple items separated by `,` |

Response (server → client):

```
!99:N\0
```

| Part      | Size       | Notes                                  |
| --------- | ---------- | -------------------------------------- |
| Command   | 3 bytes    | `!99`                                  |
| Delimiter | 1 byte     | `:`                                    |
| Data      | ≤ 64 bytes | numeric (`0` fail, `1` ok, `<0` error) |

Command ranges:

- `!00`–`!10` — client → server, test control
- `!30`–`!39` — client → server, EUT-independent helpers (e.g. OCR)
- `!90`–`!99` — server → client, notifications & responses
- `@Exit`      — session control

---

## COMMAND REFERENCE

### `!00:` — Start test (send basic info)
Send immediately after connecting. Carries the certification test type (logged as base info).
- Request: `!00:<info>`  — test type is one of `KC`, `CE`, `FCC`
- Response: `!99:1` (ok) / `!99:0` (fail) / `!99:<0` (error)
- Example: `→ !00:KC인증시험` then `← !99:1`

### `!01:` — Run script group(s)
Runs script groups created in Aurora Script Editor, in order, using the comma-separated values.
- Request: `!01:<group1>,<group2>,...`
- Rules: extra values (no matching script) are ignored; fewer values run only that many groups;
  values are case-insensitive.
- Response: `!99:1` acknowledges receipt. When the run **completes**, the server later sends
  `!91:` (see below).
- Example: `→ !01:0,2.4G,11b,HT20,TX,long,` then `← !99:1` … `← !91:1`
- On a bad item the server returns `!99:-4 <index>,<value>` (e.g. `!99:-4 2,5.2g`).

### `!02:` — Reboot / initialize EUT
Send before the User Application initializes/reboots the EUT. Convention: do this after
`!01:` returns failure (`0`) **two or more** times.
- Request: `!02:<command>` — `reboot`, `initialize`, …
- Response: `!99:1` / `!99:0` / `!99:<0`. After it is ready again, the server sends `!90:1`.
- NOTE: in the current Player version `!02:` is **ACK-only** — the protocol response is sent
  but the actual reboot/initialize action will be provided in a future version. Do not assume
  the EUT actually rebooted just because `!99:1` came back.

### `!03:` — Retry mode change
Re-issue a mode change after `!01:` failed. Same data as `!01:`, different command value.
- Request: `!03:1`  (1 = rechange)
- Response: `!99:1` / `!99:0` / `!99:<0`. Then `!91:` reports the new result.

### `!04:` — Stop
`!01:` auto-runs both the `Stop` and `Start` script groups. Use `!04:` to move an EUT that is
running (`Start`) back into the `Stop` state.
- Request: `!04:stop`  (the word `stop` is optional; `!04:` alone works)
- Response: `!99:1` / `!99:0` / `!99:<0`

### `!10:` — Test complete
The final command of a test. (`!00:` starts a test; `!10:` ends it.)
- Request: `!10:complete`
- Response: `!99:1` / `!99:0` / `!99:<0`

### `!30:` — OCR recognize (EUT-independent)
Recognize characters in a region of an image file and compare to a string.
- Request: `!30:<path>,<option>,<x>,<y>,<width>,<height>,<compareText>`
  - path: absolute image file path
  - option: `0` letters+digits, `1` digits only
  - x, y: region start; width: from x; height: from y
  - compareText: string to compare against the recognized text
- Response: first `!99:1` (ok) — then `!31:` with the result. If `!99:0`/error, `!31:` is NOT sent.
- Example: `→ !30:c:\image\a0.png,0,10,10,100,23,TestString` → `← !99:1` → `← !31:1,TestString,1`
- NOTE: in the current Player version `!30:` is **ACK-only** — the protocol response is sent
  but the actual OCR action will be provided in a future version.

### `!31:` — OCR result (server → client)
Sent right after `!99:1` for a `!30:` request.
- Format: `!31:<result>,<recognitionText>,<compareResult>`
  - result: `0` fail, `1` success, `<0` error
  - recognitionText: recognized string (on success)
  - compareResult: `0` mismatch, `1` match
- Error codes: `-14` command string conversion error · `-41` file open failed / not found ·
  `-42` x/y/width/height region is outside the image (region error)

### `!90:` — Test ready (server → client)
Sent after a reboot/initialize once the Player confirms it can run a test.
- Format: `!90:1`  (`1` ok, `<0` error)

### `!91:` — Mode change complete (server → client)
Sent after `!01:`/`!03:` finishes; tells the client to start measuring. May take a long time.
- Format: `!91:1`  (`1` ok, `0` mode-change error → you can retry with `!03:`, `<0` other error)

### `!99:` — Common response (server → client)
The acknowledgement for nearly every client command.
- Format: `!99:N`  (`0` fail, `1` success, `<0` error)
- Error codes:
  - `-1` invalid command parse error (protocol syntax error)
  - `-2` command did not start with `!`
  - `-3` received a mode-change command before `!00:` base info
  - `-4` one of the `!01:` item values is invalid → `!99:-4 <index>,<value>`
  - `-30` `!30` has too few parameters (parse error)

### `@Exit` — Stop waiting (end session)
Same as clicking "Stop" in the Player. The session ends and no further communication is
possible until the operator clicks "Start Testing" again.
- Request: `@Exit`

---

## CANONICAL SESSION (start → finish)

```
(connect TCP 127.0.0.1:7010)
→  !00:KC인증시험
←  !99:1
→  !01:0,2.4G,11b
←  !99:1
←  !91:1                 # mode change complete → start measuring
   ... (measure) ...
→  !04:stop              # optional: move EUT to Stop state
←  !99:1
→  !10:complete
←  !99:1
→  @Exit
(connection closes)
```

Retry branch (mode change failed):

```
→  !01:0,2.4G,11b
←  !99:1
←  !91:0                 # mode change failed
→  !03:1                 # retry
←  !99:1
←  !91:1                 # ok now
```

Reboot branch (after repeated !01 failures):

```
→  !02:reboot
←  !99:1
←  !90:1                 # ready again
```

---

## MINIMAL PYTHON EXAMPLE (reference — adapt as requested)

```python
import socket

HOST, PORT = "127.0.0.1", 7010

class AuroraClient:
    def __init__(self, host=HOST, port=PORT, timeout=30):
        self.sock = socket.create_connection((host, port), timeout=timeout)
        self.buf = b""

    def send(self, msg: str):
        print(f"→ {msg}")
        self.sock.sendall(msg.encode("utf-8") + b"\x00")

    def recv(self) -> str:
        # read until NULL terminator
        while b"\x00" not in self.buf:
            chunk = self.sock.recv(256)
            if not chunk:
                raise ConnectionError("server closed the connection")
            self.buf += chunk
        line, _, self.buf = self.buf.partition(b"\x00")
        msg = line.decode("utf-8", "replace")
        print(f"← {msg}")
        return msg

    def expect_ok(self) -> int:
        # read a !99 response, return its integer value (raises on error)
        msg = self.recv()                 # e.g. "!99:1" or "!99:-4 2,5.2g"
        body = msg.split(":", 1)[1].strip().split()[0]
        code = int(body.split(",")[0])
        if code < 0:
            raise RuntimeError(f"Aurora error {code} ({msg})")
        return code

    def close(self):
        self.sock.close()

def run_kc_test():
    c = AuroraClient()
    try:
        c.send("!00:KC인증시험"); c.expect_ok()
        c.send("!01:0,2.4G,11b");  c.expect_ok()
        c.recv()                  # wait for !91 (mode change complete) — may be slow
        c.send("!10:complete");    c.expect_ok()
        c.send("@Exit")
    finally:
        c.close()

if __name__ == "__main__":
    run_kc_test()
```

---

## QUICK REFERENCE TABLE

| Cmd     | Dir   | Meaning                          | Typical data        | Ack     |
| ------- | ----- | -------------------------------- | ------------------- | ------- |
| `!00:`  | C→S   | Start test / base info           | `KC` `CE` `FCC`     | `!99`   |
| `!01:`  | C→S   | Run script group(s)              | `v1,v2,...`         | `!99` + `!91` |
| `!02:`  | C→S   | Reboot / initialize EUT          | `reboot`            | `!99` + `!90` |
| `!03:`  | C→S   | Retry mode change                | `1`                 | `!99` + `!91` |
| `!04:`  | C→S   | Stop                             | `stop` (optional)   | `!99`   |
| `!10:`  | C→S   | Test complete                    | `complete`          | `!99`   |
| `!30:`  | C→S   | OCR recognize region             | `path,opt,x,y,w,h,text` | `!99` + `!31` |
| `!31:`  | S→C   | OCR result                       | `result,text,match` | —       |
| `!90:`  | S→C   | Test ready                       | `1`                 | —       |
| `!91:`  | S→C   | Mode change complete             | `1`/`0`             | —       |
| `!99:`  | S→C   | Common response / error          | `0`/`1`/`<0`        | —       |
| `@Exit` | C→S   | End session                      | —                   | —       |