> For the complete documentation index, see [llms.txt](https://xrho.gitbook.io/rho/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xrho.gitbook.io/rho/rho-railway/3-railway.md).

# Overview

**Take any shared medium — LoRa, USB, UDP, serial — and make point-to-point connections possible.**

Railway is the foundation of Rho. It defines two primitives: the **Cart** (the universal packet) and the **Station** (the universal I/O port). Everything else in Rho builds on these two abstractions.

## Why "Railway"?

Think of a physical railway network:

* **Carts** carry cargo along tracks. They have a source, a destination, and a payload.
* **Stations** are where carts are loaded, unloaded, and redirected. They connect to other stations via tracks (hooks).

Rho's Railway works the same way. A `Cart` is a self-contained message with addresses, metadata, and payload. A `Station` is a programmable I/O port that can receive, send, and forward carts.

## Core Idea

Most networking libraries assume a point-to-point channel already exists (a TCP connection, a UDP socket pair). Railway assumes nothing. It takes a **shared bus** — a medium where multiple entities coexist — and provides addressing, multiplexing, and optional encryption on top.

This makes Railway the right abstraction for:

* **LoRa radio** — Multiple devices share a frequency band
* **USB bus** — Multiple endpoints on a shared bus
* **UDP multicast** — Multiple receivers on a multicast group
* **Serial UART** — Two devices on a wire
* **Shared memory** — Multiple processes on the same machine

## Quick Example

```cpp
#include <Rho/Railway.hpp>

using namespace Rho;

// Create two stations
Station alice;
Station bob;

// Hook them together (bidirectional)
alice.hook(bob);

// Alice listens for carts
alice.onCart([](Cart& c) {
    printf("Alice received: %s\n", c.payload.c_str());
});

// Bob sends a cart
Cart greeting;
greeting.payload = "Hello from Bob";
bob.push(greeting);
// → Alice received: Hello from Bob
```

That's it. Two stations, one hook, carts flow. No sockets, no ports, no IP addresses. The abstraction works at the lowest level and scales to the highest.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xrho.gitbook.io/rho/rho-railway/3-railway.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.