PSICOSE-1B
no_std framework for tiny reliable links — wire + pump + window + P2P,
constant stack RAM, zero default deps.
Payload is 1 byte. Wire frame is 4 bytes. P2P (Node, PeerLink, hello,
fragmentation) is in this crate, on the same frame — not a bolt-on package.
Examples call into this motor; they do not invent an external P2P and pass
connections in.
┌──────┬─────┬─────┬───────┐
│ TYPE │ SEQ │ DATA│ CRC │ ← frame = 4 bytes
└──────┴─────┴─────┴───────┘
▲
└── application payload: exactly 8 bits
Best-case efficiency before ACKs: 1/4 = 25%. Stop-and-wait (DATA+ACK): 1/8 = 12.5%.
[]
= "0.4" # zero dependencies — API is only psicose::…
| Dependencies | none (always) |
| MSRV | Rust 1.75 |
| Safety | #![no_std] · #![forbid(unsafe_code)] · no heap |
| Docs | docs.rs/psicose |
| Spec | docs/PROTOCOL.md · pt-BR |
| API map | docs/API.md · pt-BR |
| Hardware | docs/HARDWARE.md · pt-BR |
On hardware (ESP32)
UART1 → your ByteTransport → LinkFace → Pump / Node
Wi‑Fi TCP → TcpPipe / TcpStream → LinkFace → Pump / Node
Concrete firmware (not published):
- UART:
boards/esp32-uart— TX=GPIO17, RX=GPIO16 @ 115200 - Wi‑Fi/TCP:
boards/esp32-wifi— STA + DHCP + TCP → PSICOSE
esp-hal / esp-radio live only in those board packages.
&&
# or: cd boards && cargo run -p esp32-wifi # needs SSID/PASSWORD/HOST
Host TCP smoke (no board): cargo run --example tcp_pair.
Wire is an in-memory test harness, not the on-wire frame.
Try in 30 seconds (host)
When to use
- UART / SPI / radio where RAM is scarce and you cannot buffer the whole message
- Firmware flash, camera JPEG, sensor samples, EEPROM dumps — anything as bytes
- You want stop-and-wait or selective-repeat (
N ≤ 8) with CRC + retry on the stack - Optional app-level crypto outside psicose when the link may be adversarial
When not to use
- You need high throughput / large frames (by design: 1 DATA byte per frame)
- You need routing, mesh, gossip, or store-and-forward (not in this crate)
- You only need a raw UART driver — implement
ByteTransport; PSICOSE sits above it
Why it exists
Most transfer stacks hold the whole message in memory. PSICOSE never does: memory is a few frames on the stack whether you send 4 bytes of config or a multi-gigabyte file. Reliability (ACK, NACK, SEQ, CRC-8, tick retry) is the protocol's job — not yours.
CRC-8 is noise detection, not authentication. Seal messages in your
application before the transport if an attacker may be on the wire. See
SECURITY.md.
Status (0.4 — usable)
- protocol — CRC-8, 4-byte frame,
SEQwraparound, assembler - tx / rx — stop-and-wait;
START/FINISH/ABORTwait for ACK - pump — cooperative
Pump+SessionStats(no inner loop) - window — selective-repeat
1 ≤ N ≤ 8(W8Sender/W8Receiver) - stream —
SliceSource/SliceSink,send_all/recv_all - p2p —
Node,PeerLink, hello, fragmentation (prelude) - LinkFace — demux one physical port into Pump TX/RX (hardware path)
- dependencies — none
Not in this crate: SoC HALs (esp-hal lives in boards/), File, routing / gossip, crypto.
Layers (one framework)
exemplos / application / boards/esp32-uart | boards/esp32-wifi
│
▼
psicose::Node ← motor entry
├─ PeerLink / PeerTable / hello
├─ Fragmenter / Defragmenter
▼
LinkFace / Wire::copy / Pump / WindowedPump
│ DATA 1 byte/frame + CRC-8 + ACK
▼
ByteTransport
├─ you implement on UART / SPI / radio
└─ Wire (in-memory test harness only)
Use hardware (LinkFace + your ByteTransport) or climb to P2P (Node) —
same crate, same frame. Wire is for host tests. Capabilities::WINDOW
is honoured by PeerLink after hello.
API sketch
use *;
| You write | Meaning |
|---|---|
PeerId::from_label(b"alice") |
8-byte identity (padded). Never in the 4-byte frame. |
Node::<4>::new(id) |
Framework entry: identity + neighbor table. |
Node::with(id, SessionConfig::FORUM) |
Hello: stream + window + forum + fragmentation. |
SessionConfig::SECURE |
FORUM + ENCRYPTION (advertise app crypto; seal yourself). |
Fragmenter / Defragmenter |
Cut any blob; rebuild into a stack buffer. |
Wire::new().copy(src, sink) |
Host harness stop-and-wait A→B (tests). |
LinkFace::new(port).pump() |
Hardware: demux one UART into Pump ends. |
Wire::new().link_pumps() |
In-memory A↔B for PeerLink (windowed). |
Pump::on(tx, rx) |
Same wrapping on a real UART / SPI / radio. |
node.connect / node.accept |
START + 12-byte hello both ways. |
establish / send_message |
Cooperative helpers inside the crate. |
use *;
let wire = new;
let = wire.link_pumps;
let mut alice = new;
let mut bob = new;
let mut a = match alice.connect ;
let mut b = bob.accept;
assert!;
Runnable: cargo run --example p2p_pair. Transport-only: ab_direct.
Tests: tests/forum.rs.
The 4-byte envelope alone:
use Frame;
let frame = data;
assert_eq!;
Any data, not just “messages”
JPEG File Flash Sensor firmware.bin your struct
└───────┴───────┴────────┴──────────────┘
│
ByteSource
│ 1 byte at a time
▼
PSICOSE ← never owns the blob
Examples
In-memory stand-ins; swap End for your driver.
| Example | Layer | What PSICOSE sees |
|---|---|---|
ab_direct |
transport (Pump) |
ping / pong bytes |
p2p_pair |
motor P2P (Node + PeerLink) |
hello + bytes fragmentados |
jpeg_over_uart |
transport | JPEG bytes |
firmware_flash |
transport | file bytes |
sensor_telemetry |
transport | 8-byte sample |
radio_windowed |
windowed transport | bytes, window N=8 |
Non-negotiables
#![no_std],#![forbid(unsafe_code)]- No
Vec,String,Box,Rc/Arc, no allocator, no async runtime - Every public type has a size known at compile time
- Reliability is the protocol's job, never the application's
Contributing / security
CONTRIBUTING.md— how to run tests and open PRsSECURITY.md— threat model and how to report issuesCHANGELOG.md
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.