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

> The signal as UART, SPI and I2C operations, with the expected RX responses: the Oryx Signal Format (.osf).

Step-based exports describe **levels**: at which step each channel changes.
The **Oryx Signal Format (.osf)** describes the same thing as **operations**: *write
`3F 0A` on TX at step 4*, *expect `4F 4B 0A` on RX*, *read two bytes from
0x48*. A device can run them with its peripherals (hardware UART, SPI and I2C)
and validate what it receives without walking every step.

## When it shows up

In **Export**, as the first option and marked **Recommended**, when every
channel going into the file (that has a drawing) belongs to a **UART**,
**SPI** or **I2C** bus Oryx can read. If there is any other kind of channel —a
PWM, a hand-drawn channel with no protocol, an analog signal— or something
that cannot be expressed without losing information (a byte with a deliberate
parity error, SPI Dual/Quad/Octal or DDR), it does not show up and the usual
formats remain.

It is available on every plan. The file downloads as `.osf`: it is JSON inside, so any JSON reader opens it.

## Structure

One document shared by every protocol, versioned:

| Field | What it is |
| - | - |
| `format`, `version` | `"oryx.osf"` and `1` |
| `project` | Name and length in steps |
| `timebase` | `unit: "step"`. `stepUs` only if you entered the step time in the metadata; otherwise `null`: Oryx never makes up timings |
| `channels` | Each channel with `id` (`c1`…), `index` (its place in the file, which is its pin), `name` and `direction` (`tx`, `rx` or `io`) |
| `buses` | One per bus, with its `protocol`, its settings and which channel plays each line |
| `sequence` | The operations, in start order |
| `validation` | Edge tolerance and maximum response delay, in steps (`null` = the whole lap) |

Every operation has an `[at, end)` interval in steps. **Two operations whose
intervals overlap run at the same time** (two buses talking at once). `after`
points to the request an operation answers.

### Operations

| Protocol | `op` | Fields |
| - | - | - |
| UART | `write` / `expect` | `line` (`tx`/`rx`), `data` (bytes), `charGapSteps` |
| SPI | `transfer` | `device`, `mosi`, `miso`, `expect` (which lines are validated) |
| I2C | `write` | `address`, `data`, `ackAddress`, `ackData` |
| I2C | `read` | `address`, `expect` (what should be read), `ackAddress` |

I2C operations may carry `tenBit` (10-bit address) and `repeatedStart` (they
end with a repeated START instead of STOP).

## Example: UART with a response

```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 }
}
```

## Example: SPI full duplex

```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` is `controller` when Oryx drives the clock (the usual case). With the
clock set to RX, the bus is exported as `peripheral`.

## Example: I2C write and read

```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] }
]
```

## Example: several protocols at once

UART, SPI and I2C in one document. SPI and the I2C read start while the UART
write is still going, and the UART response follows its request:

```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" }
]
```

## Example: back-to-back transactions

```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" }
]
```

## Validating a file

The JSON schema (draft 2020-12) is published at
`https://oryx.mechatronstudio.com/schemas/oryx-signal-format-1.json` and every file
names it in `$schema`. Any JSON Schema validator checks it; on top of that,
Oryx checks that every reference exists (channels, buses, devices, `after`)
before downloading the file.

> [!NOTE]
>
> A new version of the format changes `version`. A version 1 reader should
> reject a number it does not know instead of guessing.

## From steps to time

Everything is in steps, like the rest of Oryx. When running, the step time is
set by the device (or by `stepUs`, if exported): on UART, `bitSteps` × step
time is the length of a bit (9600 baud = 104.17 µs per bit); on SPI and I2C,
`clockHalfSteps` × 2 × step time is the clock period.


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