> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oryx.mechatronstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oryx Signal Format (.osf)

> La señal como operaciones UART, SPI e I2C, con las respuestas RX esperadas: el formato Oryx Signal Format (.osf).

Las exportaciones por pasos describen **niveles**: en qué paso cambia cada
canal. El **Oryx Signal Format (.osf)** describe lo mismo como **operaciones**:
*escribir `3F 0A` por TX en el paso 4*, *esperar `4F 4B 0A` por RX*, *leer dos
bytes de 0x48*. Un equipo puede ejecutarlas con sus periféricos (UART, SPI e
I2C por hardware) y validar lo que recibe sin recorrer cada paso.

## Cuándo aparece

En **Exportar**, como primera opción y marcada **Recomendado**, cuando todos
los canales que van al archivo (y tienen dibujo) son de un bus **UART**,
**SPI** o **I2C** que Oryx sabe leer. Si hay otro tipo de canal —un PWM, un
canal dibujado a mano sin protocolo, una señal analógica— o algo que no se
puede decir sin perder información (un byte con la paridad mal a propósito,
SPI Dual/Quad/Octal o DDR), no aparece y quedan los formatos de siempre.

Está en todos los planes. El archivo se baja como `.osf`: es JSON por dentro, así que lo abre cualquier lector de JSON.

## Estructura

Un documento común a todos los protocolos, con versión:

| Campo | Qué es |
| - | - |
| `format`, `version` | `"oryx.osf"` y `1` |
| `project` | Nombre y largo en pasos |
| `timebase` | `unit: "step"`. `stepUs` solo si escribiste el tiempo de paso en los metadatos; si no, `null`: Oryx no inventa tiempos |
| `channels` | Cada canal con `id` (`c1`…), `index` (su lugar en el archivo, que es el pin), `name` y `direction` (`tx`, `rx` o `io`) |
| `buses` | Uno por bus, con su `protocol`, su configuración y qué canal hace de cada línea |
| `sequence` | Las operaciones en orden de comienzo |
| `validation` | Tolerancia de flancos y demora máxima de una respuesta, en pasos (`null` = toda la vuelta) |

Cada operación tiene un intervalo `[at, end)` en pasos. **Dos operaciones
cuyos intervalos se superponen corren a la vez** (dos buses que hablan al
mismo tiempo). `after` señala el pedido al que responde una operación.

### Operaciones

| Protocolo | `op` | Campos |
| - | - | - |
| UART | `write` / `expect` | `line` (`tx`/`rx`), `data` (bytes), `charGapSteps` |
| SPI | `transfer` | `device`, `mosi`, `miso`, `expect` (qué líneas se validan) |
| I2C | `write` | `address`, `data`, `ackAddress`, `ackData` |
| I2C | `read` | `address`, `expect` (lo que se espera leer), `ackAddress` |

Las operaciones I2C pueden llevar `tenBit` (dirección de 10 bits) y
`repeatedStart` (terminan con un START repetido en vez de STOP).

## Ejemplo: UART con respuesta

```json theme={"system"}
{
  "$schema": "https://oryx.mechatronstudio.com/schemas/oryx-signal-format-1.json",
  "format": "oryx.osf",
  "version": 1,
  "project": { "name": "uart", "steps": 160 },
  "timebase": { "unit": "step", "stepUs": null },
  "channels": [
    { "id": "c1", "index": 0, "name": "TX", "direction": "tx" },
    { "id": "c2", "index": 1, "name": "RX", "direction": "rx" }
  ],
  "buses": [
    {
      "id": "uart0", "protocol": "uart",
      "config": { "dataBits": 8, "parity": "none", "stopBits": 1, "bitOrder": "lsb", "idle": "high", "bitSteps": 1 },
      "lines": { "tx": "c1", "rx": "c2" }
    }
  ],
  "sequence": [
    { "id": "op1", "bus": "uart0", "op": "write", "line": "tx", "at": 4, "end": 24, "data": [63, 10], "charGapSteps": 0 },
    { "id": "op2", "bus": "uart0", "op": "expect", "line": "rx", "at": 60, "end": 90, "data": [79, 75, 10], "charGapSteps": 0, "after": "op1" }
  ],
  "validation": { "edgeToleranceSteps": 1, "latencySteps": null }
}
```

## Ejemplo: SPI con intercambio simultáneo

```json theme={"system"}
"buses": [
  {
    "id": "spi0", "protocol": "spi", "role": "controller",
    "config": { "clockHalfSteps": 1 },
    "lines": { "sclk": "c1", "mosi": "c2", "miso": "c3" },
    "devices": [
      { "id": "spi0.d0", "cs": "c4", "config": { "mode": 0, "bitOrder": "msb", "bits": 8, "csActiveHigh": false } }
    ]
  }
],
"sequence": [
  { "id": "op1", "bus": "spi0", "op": "transfer", "device": "spi0.d0", "at": 4, "end": 55,
    "mosi": [159, 0, 0], "miso": [255, 239, 64], "expect": ["miso"] }
]
```

`role` es `controller` cuando Oryx da el reloj (lo normal). Si el reloj está
en RX, el bus se exporta como `peripheral`.

## Ejemplo: I2C, escritura y lectura

```json theme={"system"}
"buses": [
  { "id": "i2c0", "protocol": "i2c", "role": "controller", "config": { "clockHalfSteps": 2 }, "lines": { "scl": "c2", "sda": "c1" } }
],
"sequence": [
  { "id": "op1", "bus": "i2c0", "op": "write", "at": 5, "end": 81, "address": 72, "ackAddress": true, "data": [0], "ackData": [true] },
  { "id": "op2", "bus": "i2c0", "op": "read", "at": 89, "end": 201, "address": 72, "ackAddress": true, "expect": [25, 128] }
]
```

## Ejemplo: varios protocolos a la vez

UART, SPI e I2C en un solo documento. La SPI y la lectura I2C empiezan
mientras sigue la escritura UART, y la respuesta UART sigue a su pedido:

```json theme={"system"}
"sequence": [
  { "id": "op1", "bus": "uart0", "op": "write", "line": "tx", "at": 2, "end": 12, "data": [65], "charGapSteps": 0 },
  { "id": "op2", "bus": "spi0", "op": "transfer", "device": "spi0.d0", "at": 4, "end": 39, "mosi": [5, 0], "miso": [255, 2], "expect": ["miso"] },
  { "id": "op3", "bus": "i2c0", "op": "read", "at": 11, "end": 87, "address": 80, "ackAddress": true, "expect": [171] },
  { "id": "op4", "bus": "uart0", "op": "expect", "line": "rx", "at": 30, "end": 40, "data": [6], "charGapSteps": 0, "after": "op1" }
]
```

## Ejemplo: transacciones seguidas

```json theme={"system"}
"sequence": [
  { "id": "op1", "bus": "uart0", "op": "write",  "line": "tx", "at": 4,   "end": 34,  "data": [65, 84, 13], "charGapSteps": 0 },
  { "id": "op2", "bus": "uart0", "op": "expect", "line": "rx", "at": 60,  "end": 80,  "data": [79, 75], "charGapSteps": 0, "after": "op1" },
  { "id": "op3", "bus": "uart0", "op": "write",  "line": "tx", "at": 150, "end": 190, "data": [65, 84, 73, 13], "charGapSteps": 0 },
  { "id": "op4", "bus": "uart0", "op": "expect", "line": "rx", "at": 230, "end": 270, "data": [79, 114, 121, 120], "charGapSteps": 0, "after": "op3" }
]
```

## Validar un archivo

El esquema JSON (draft 2020-12) está publicado en
`https://oryx.mechatronstudio.com/schemas/oryx-signal-format-1.json` y cada archivo
lo nombra en `$schema`. Cualquier validador de JSON Schema lo comprueba;
además, que cada referencia exista (canales, buses, dispositivos, `after`) lo
revisa Oryx antes de bajar el archivo.

> [!NOTE]
>
> Una versión nueva del formato cambia `version`. Un lector de la versión 1 debe
> rechazar un número que no conoce en vez de adivinar.

## Cómo pasar de pasos a tiempo

Todo va en pasos, como en el resto de Oryx. Al ejecutar, el tiempo de paso lo
decide el equipo (o `stepUs`, si se exportó): en UART, `bitSteps` × tiempo de
paso es la duración de un bit (9600 baudios = 104,17 µs por bit); en SPI e I2C,
`clockHalfSteps` × 2 × tiempo de paso es el período del reloj.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.