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

# Reception (RX channels)

> Draw the response you expect, run it on the ESP32 and see whether it arrived, arrived wrong or never arrived.

A channel can **transmit** or **receive**. What you draw or generate on a
**TX** channel is what the device outputs; what you draw on an **RX** channel
is what you **expect to receive**. When running, the device outputs the TX
channels, listens to the RX ones and Oryx compares what arrived with the
drawing.

Drawing and editing are the same for both: the difference is only what the
device does with each channel.

| Direction | Label | What the device does |
| - | - | - |
| **Transmit** | `TX ↑` | Outputs the drawing on the channel's pin (as always) |
| **Receive** | `RX ↓` | Does not drive the line: listens to it (or, in analog, measures it with the ADC) and compares it with the drawing |
| **Shared** | `TX/RX ↕` | Outputs its own part and listens to the other side's, open drain (I2C SDA) |

> [!NOTE]
>
> Reception is available on **every plan**, Basic included: setting up RX
> channels, running, comparing responses, seeing the diagnostics and exporting
> with reception data.

## Switching a channel

**1. Open the channel settings**

On the channel's name card, the button on the right (the palette, or the
`TX`/`RX` label once the project already has receiving channels).

**2. Pick the direction**

**TX**, **RX** or **TX/RX**. The drawing does not change.

You can also change it in **Channels** (the organizer), from the same color
popover. The change is saved with the project, undone with `Ctrl + Z`, and it
travels when duplicating, sharing, saving as a template, importing and
exporting.

While no channel receives, the timeline looks as always. With at least one,
every channel shows its `TX ↑` or `RX ↓` label next to its name: you tell them
apart by the text and the arrow, not by color, which stays the signal's.

### Generators set the direction for you

| Generator | Channels |
| - | - |
| **UART** | `TX` transmits, `RX` receives |
| **SPI** | Clock, MOSI, CS and D/C transmit; `MISO` receives (Oryx is the controller) |
| **I2C** | `SCL` transmits; `SDA` is shared (`TX/RX`) |
| PWM, Step/Dir, encoders, CKP/CMP, waves, equations | Transmit |

The direction is set when the generator **takes** the channel. If you change
it by hand afterwards, it is kept: editing messages or regenerating does not
overwrite it. Channels you create by hand start as TX.

> [!TIP]
>
> To test from the **SPI peripheral side** (Oryx answers on MISO and listens to
> MOSI), flip the channels by hand: clock, MOSI and CS to RX, MISO to TX. The
> structured export then reports the *peripheral* role.

## A TX/RX conversation with UART

**1. Build the request**

In the UART generator, write the message on **TX** (for example `AT\r`).

**2. Draw the expected response**

Write on **RX** the response the device should send back (`OK\r\n`), where
you expect it in time. The RX channel is already set to receive.

**3. Run**

Open **Device**, connect the ESP32 and press **Start**. The device outputs
TX and listens to RX during the signal's first lap.

**4. Read the result**

The **Reception** section of the panel shows the verdict of each RX
channel, with what was expected and what was received. **Capture another
lap** repeats the test without stopping the signal.

Wire the **device's TX** to the pin of Oryx's **RX** channel, and the
**device's RX** to the pin of the **TX** channel, with a common ground.

## Results

| Verdict | Meaning |
| - | - |
| **Correct** | What was expected arrived |
| **Incorrect** | Something else arrived: another value, extra data, extra edges |
| **No response** | Nothing valid arrived in the captured lap (or, on I2C, nobody acknowledged the address) |
| **Incomplete** | What arrived matches, but the end is missing |
| **Communication error** | Reception had an identifiable failure: parity, framing, break |
| **Capture failure** | The problem was the capture, not the response: the signal stopped mid-lap, the link dropped, or more edges arrived than the device can store |

Each verdict comes with its cause when the capture shows it:

| Cause | Example |
| - | - |
| Unexpected value | *expected 0x4B 'K', received 0x4E 'N'* |
| Wrong length | *3 items expected, 2 received* |
| Timeout | *nothing arrived during the captured lap* |
| Parity / framing / break | *framing error in character 2* |
| NACK | *nobody acknowledged in transfer 1* |
| Missing or extra edge | *a ↑ edge was missing near step 11* (signals without a protocol) |
| Out of tolerance | *out of tolerance in 15.8 % of the samples* (analog) |
| Different frequency | *4 cycles expected, 8 received* (analog) |

Oryx does not claim a cause the device cannot see: for example, it does not
report a CRC if the protocol has none.

### How it compares

* **UART, SPI and I2C are compared by content**: bytes, MISO words, addresses,
  reads and acknowledgements, with the same interpreters that draw the
  editor's bars. A response that arrives somewhat later than drawn is still
  correct.
* **Signals without a protocol are compared edge by edge**: each expected edge
  must show up, in the same direction, within **1 step** of where it was drawn.
* **Analog signals are compared against the curve**: each sample must fall
  within **5 % of full scale** (0.165 V) of the drawn curve, at some point
  within 1 step. Up to 2 % of samples outside is taken as noise and only
  flagged. Cycles are also counted to report a different frequency.
* Expected and received are shown together in a small drawing, with the
  differences marked.

### SPI and I2C

* **SPI**: the device outputs clock, MOSI and CS, and compares every MISO word
  with the drawn one.
* **I2C**: the device outputs SCL and drives SDA **open drain**. On writes it
  releases the line on the acknowledgements; on reads, on the bytes the
  peripheral sends. What arrives is compared as transfers (address, data,
  ACK/NACK). The bus needs its pull-up resistors.

## Analog signals

In an analog project, an **RX** channel is the curve you expect to
**measure**. When running it is not output by the DAC: the device measures it
with its ADC while playing the TX channels, one lap per start, like in
digital. An analog project may have only RX channels: the device outputs
nothing and measures for as long as the curve lasts.

| Input | Classic ESP32 | ESP32-S3 |
| - | - | - |
| 1st | GPIO 34 | GPIO 1 |
| 2nd | GPIO 35 | GPIO 2 |
| 3rd | GPIO 32 | GPIO 8 |
| 4th | GPIO 33 | GPIO 9 |

> [!NOTE]
>
> The **ESP32-S3** has no DAC: in analog it outputs nothing, but it **does
> measure**. With an S3, the TX channels of an analog signal are not output (the
> panel says so) and RX channels are measured as usual. Handy to use it as a
> meter for a signal another device generates.

RX channels take those inputs in order, and the panel shows each one next to
its channel. The channel height is **0 to 3.3 V** at the pin, the same scale
the DAC outputs: a curve drawn at mid height expects 1.65 V.

* Each lap takes up to **2000 samples per input**, spread across the lap and
  at most one every **200 µs** (less often with several inputs). The panel
  says how many steps apart the samples were: if the curve changes faster than
  that, lower the speed.
* It measures with **ADC1** and the chip's calibration. The ESP32 ADC is
  inaccurate near 0 V and above \~3.1 V: leave some margin at the ends.

## Requirements and limits

| What | Detail |
| - | - |
| Firmware | The link firmware **with reception**. An older one does not listen: if the signal has RX channels, Oryx does not send it and says so, so the device never drives a line the other side owns |
| Channels | Digital: only channels with a pin (the first 8). Analog: up to 4 (the ADC inputs) |
| Analog | The classic ESP32 outputs and measures; the S3 only measures. Up to 2000 samples per lap and input, at most one every 200 µs; useful range \~0.1–3.1 V |
| Speed | Each edge is stamped by an interrupt (a few µs of accuracy). With steps under **10 µs** the capture may shift edges: the panel warns about it |
| Capture | The first lap of each start, from its beginning. Changing the speed in the middle of a captured lap shifts it |
| I2C | No clock stretching: the device drives SCL |
| SPI | One line per direction (no Dual/Quad/Octal capture) |
| microSD player | Does not receive. If a file has RX channels, those pins stay inputs and are not driven |

> [!WARNING]
>
> ESP32 outputs are **3.3 V**. A 5 V device needs level shifting on the lines
> that reach the board.

## Exporting with reception

* **Oryx Signal Format (.osf)**: when the whole signal is UART, SPI or I2C, it is offered
  as the recommended option. It describes operations (write, expect, read)
  with the expected responses. See [Oryx Signal Format (.osf)](https://docs.oryx.mechatronstudio.com/en/export/protocol-json.md).
* **Step-based TXT, CSV and JSON**: they carry which columns are RX. See
  [Digital format](https://docs.oryx.mechatronstudio.com/en/export/digital-format.md#rx-channels).


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