diff --git a/docs/src/content/docs/tutorials/serial-for-humans.mdx b/docs/src/content/docs/tutorials/serial-for-humans.mdx new file mode 100644 index 0000000..3f3b33d --- /dev/null +++ b/docs/src/content/docs/tutorials/serial-for-humans.mdx @@ -0,0 +1,258 @@ +--- +title: Serial for Humans +description: Serial communication explained like you're five (with links to go deeper) +sidebar: + order: 0 +--- + +import { Card, CardGrid, LinkCard, Aside } from '@astrojs/starlight/components'; + +Serial communication sounds scary, but it's just devices having a conversation — one letter at a time. This page explains the core ideas using everyday analogies, then points you to the deep dives when you're ready. + +--- + +## 🗣️ What is Serial Communication? + +Imagine two people talking through a very narrow pipe. They can only pass one letter at a time, so to say "HELLO" they pass: + +``` +H → E → L → L → O +``` + +That's serial communication. One bit after another, in a line (serial = "in a series"). + +Your computer and a device agree on how fast to pass letters, how to know when a word starts and ends, and what to do if a letter gets mangled in the pipe. + + + +--- + +## 🏎️ Baud Rate: How Fast Are We Talking? + +**Baud rate** is how many signal changes per second. Think of it as the speed limit for the pipe. + +| Baud Rate | Letters per Second | Real-World Analogy | +|-----------|-------------------|-------------------| +| 9600 | ~960 | Casual conversation | +| 115200 | ~11,520 | Speed-talking auctioneer | +| 1000000 | ~100,000 | Two computers screaming at each other | + +If one side talks at 115200 and the other listens at 9600, it's like someone speed-reading to a toddler. Gibberish ensues. + + + +--- + +## ✋ Flow Control: "Wait, I'm Not Ready!" + +What happens when one side talks faster than the other can listen? The listener's "ears" fill up and they start missing words. + +**Flow control** is the listener saying "hold on!" (and later "okay, continue"). + +Two ways to do this: + +| Method | How It Works | Analogy | +|--------|--------------|---------| +| **XON/XOFF** | Send special "pause" and "resume" letters in the conversation | Saying "wait!" and "go!" out loud | +| **RTS/CTS** | Flip a physical switch to pause/resume | Holding up your hand to stop someone | + + + + + +--- + +## 🔌 Wires: The Physical Connection + +### RS-232: The One-on-One Chat + +RS-232 is like a phone call — two parties, direct connection, multiple wires for different purposes: + +| Wire | What It Does | Analogy | +|------|--------------|---------| +| **TX** | Transmit (you talk) | Your mouth | +| **RX** | Receive (you listen) | Your ear | +| **GND** | Ground (reference point) | Shared understanding of "zero" | +| **RTS/CTS** | Flow control | "Can I talk?" / "Yes, go ahead" | +| **DTR/DSR** | Presence detection | "Are you there?" / "Yes, I'm here" | + +At minimum, you need **TX, RX, and GND**. The rest are optional helpers. + +### RS-485: The Group Chat + +RS-485 is like a walkie-talkie channel — many devices, but only one can talk at a time: + +- **Two wires** (A and B) carry the signal +- Everyone listens; one device talks +- You need an **address** so devices know who's being asked +- **Termination resistors** at each end prevent signal echoes + + + + + + +--- + +## 📝 Text vs Binary: What Language Are We Speaking? + +Serial ports don't know if you're sending English text, emoji, or raw machine code. They just pass bytes. + +**Text mode** (like AT commands): +``` +AT+GMR\r\n +``` +Human-readable, uses characters like letters and newlines. + +**Binary mode** (like Modbus RTU): +``` +01 03 00 00 00 01 84 0A +``` +Machine-readable, exact byte values matter, no "text" interpretation. + +The **encoding** setting tells mcserial how to convert between strings and bytes: + +| Encoding | Use When | Example | +|----------|----------|---------| +| UTF-8 | Text protocols, console output | `"Hello"` → `48 65 6C 6C 6F` | +| Latin-1 | Binary protocols, raw bytes | `"\x01\x03"` → `01 03` (exact bytes) | + + + +--- + +## ⏱️ Timeouts: How Long to Wait? + +When you ask a device a question, how long do you wait for an answer before assuming it's not coming? + +- **Too short**: You give up before the device finishes thinking +- **Too long**: You stare at a dead device forever + +Rule of thumb: **2× the expected response time** is a safe starting point. + +Some devices are slow thinkers: +- GPS during cold start: 30-60 seconds to find satellites +- Flash memory writes: several seconds to complete +- Sleepy microcontrollers: may need a wake-up poke first + + + +--- + +## 🔥 When Things Go Wrong + +Serial communication fails in predictable ways. Here's the cheat sheet: + +| Symptom | Likely Cause | Quick Fix | +|---------|--------------|-----------| +| Garbage characters | Wrong baud rate | Match baud rates on both ends | +| No response at all | Device off, wrong port, or TX/RX swapped | Check connections, try other ports | +| Partial data, missing bytes | Buffer overflow (no flow control) | Enable RTS/CTS or XON/XOFF | +| "Permission denied" | Your user can't access the port | Add yourself to the `dialout` group | +| Works once, then stops | Port left open from last time | Close and reopen the port | + + + +--- + +## 📁 Sending Files: The Slow Way + +Before networks, people sent files over serial using protocols like XMODEM, YMODEM, and ZMODEM. These protocols: + +1. Break the file into chunks +2. Add error-checking to each chunk +3. Resend chunks that got corrupted +4. Reassemble at the other end + +**ZMODEM** is the best — it's fast, can resume interrupted transfers, and handles errors gracefully. + + + +--- + +## 🚀 Ready to Start? + +Now that you know the basics, try talking to a real device: + + + + + + +--- + +## 📚 The Full Map + +Here's everything in the docs, organized by how deep you want to go: + +### Just Getting Started +- [Getting Started](/tutorials/getting-started/) — Installation and first connection +- [Loopback Testing](/tutorials/loopback-testing/) — Test without hardware + +### Practical Guides +- [RS-232 Basics](/guides/rs232-basics/) — Arduino, modem lines, reset sequences +- [RS-485 & Modbus](/guides/rs485-modbus/) — Industrial buses, addressing +- [File Transfers](/guides/file-transfers/) — X/Y/ZMODEM protocols +- [Network Ports](/guides/network-ports/) — Serial over TCP/IP +- [Troubleshooting](/guides/troubleshooting/) — When things break +- [Timeout Tuning](/guides/timeout-tuning/) — Timing and slow devices + +### Deep Concepts +- [RS-232 vs RS-485](/concepts/rs232-vs-rs485/) — Fundamental differences +- [Flow Control](/concepts/flow-control/) — Preventing buffer overflows +- [Encoding & Binary](/concepts/encoding-and-binary/) — Text vs machine data + +### Reference +- [Common Tools](/reference/tools-common/) — Universal operations +- [RS-232 Tools](/reference/tools-rs232/) — Modem line control +- [RS-485 Tools](/reference/tools-rs485/) — Bus operations +- [File Transfer Tools](/reference/tools-file-transfer/) — X/Y/ZMODEM +- [URL Schemes](/reference/url-handlers/) — Network and virtual ports +- [Resources](/reference/resources/) — MCP resource URIs +- [Environment](/reference/environment/) — Configuration options