Add Serial for Humans ELI5 intro page
Friendly introduction to serial concepts using everyday analogies: - Baud rate as conversation speed - Flow control as "wait, I'm not ready!" - Wires explained (TX/RX/GND) - Text vs binary encoding - When things go wrong cheat sheet Links throughout invite readers to "go deeper" into detailed pages. Positioned first in Tutorials sidebar for discoverability.
This commit is contained in:
parent
63a4169ffa
commit
c651dc4c5e
258
docs/src/content/docs/tutorials/serial-for-humans.mdx
Normal file
258
docs/src/content/docs/tutorials/serial-for-humans.mdx
Normal file
@ -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.
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: RS-232 vs RS-485"
|
||||||
|
description="The two main flavors of serial — one-on-one conversations vs. group chats"
|
||||||
|
href="/concepts/rs232-vs-rs485/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏎️ 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.
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: Timeout Tuning"
|
||||||
|
description="How long to wait for a response, and why baud rate affects it"
|
||||||
|
href="/guides/timeout-tuning/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✋ 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 |
|
||||||
|
|
||||||
|
<Aside type="tip" title="The gotcha">
|
||||||
|
XON/XOFF uses byte values 0x11 and 0x13 as the "wait" and "go" signals. If you're sending a file and it happens to contain those bytes... the receiver thinks you said "pause" when you didn't. Binary data + XON/XOFF = trouble.
|
||||||
|
</Aside>
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: Flow Control"
|
||||||
|
description="Software vs hardware flow control, and when to use each"
|
||||||
|
href="/concepts/flow-control/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔌 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
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<LinkCard
|
||||||
|
title="RS-232 Basics"
|
||||||
|
description="Modem lines, reset sequences, and Arduino connections"
|
||||||
|
href="/guides/rs232-basics/"
|
||||||
|
/>
|
||||||
|
<LinkCard
|
||||||
|
title="RS-485 & Modbus"
|
||||||
|
description="Multi-drop buses, addressing, and industrial protocols"
|
||||||
|
href="/guides/rs485-modbus/"
|
||||||
|
/>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 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) |
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: Encoding and Binary Data"
|
||||||
|
description="UTF-8 vs Latin-1, CRC checksums, and why encoding matters"
|
||||||
|
href="/concepts/encoding-and-binary/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⏱️ 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
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: Timeout Tuning"
|
||||||
|
description="Timeout types, slow device patterns, and how to debug no-response issues"
|
||||||
|
href="/guides/timeout-tuning/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔥 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 |
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: Troubleshooting"
|
||||||
|
description="Detailed error recovery, permission fixes, and reconnection patterns"
|
||||||
|
href="/guides/troubleshooting/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 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.
|
||||||
|
|
||||||
|
<LinkCard
|
||||||
|
title="Go deeper: File Transfers"
|
||||||
|
description="Protocol comparison, firmware uploads, and error recovery"
|
||||||
|
href="/guides/file-transfers/"
|
||||||
|
/>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Ready to Start?
|
||||||
|
|
||||||
|
Now that you know the basics, try talking to a real device:
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<LinkCard
|
||||||
|
title="Getting Started"
|
||||||
|
description="Install mcserial and connect to your first serial device"
|
||||||
|
href="/tutorials/getting-started/"
|
||||||
|
/>
|
||||||
|
<LinkCard
|
||||||
|
title="Loopback Testing"
|
||||||
|
description="Test your setup without any hardware"
|
||||||
|
href="/tutorials/loopback-testing/"
|
||||||
|
/>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 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
|
||||||
Loading…
x
Reference in New Issue
Block a user