PSICOSE-1B
A no_std, heapless, deterministic, byte-oriented transport protocol.
Payload is 1 byte. The wire frame is 4 bytes. Those are not the same
thing.
┌──────┬─────┬─────┬───────┐
│ TYPE │ SEQ │ DATA│ CRC │ ← frame = 4 bytes (overhead + payload)
└──────┴─────┴─────┴───────┘
▲
└── application payload: exactly 8 bits
Best-case efficiency before ACKs: 1/4 = 25%. Stop-and-wait (DATA+ACK): 1/8 = 12.5%.
[]
= "0.2"
No features, no dependencies. MSRV: Rust 1.75 (rust-toolchain.toml).
Docs: docs.rs/psicose · spec: PROTOCOL.md
(pt-BR)
Why
Most transfer protocols hold the whole message in memory. PSICOSE never does: it moves one payload byte at a time. Memory is a few frames on the stack, whether you send 4 bytes of config or a 4 GB file.
Status (0.2.3 — experimental)
- protocol — CRC-8, 4-byte frame, semantic validation,
SEQwraparound (255 → 0), assembler,OutBuf(one wire byte per poll). - tx / rx — stop-and-wait.
START/FINISH/ABORTwait for ACK. - pump — cooperative
Pump(rx.pollthentx.poll, no inner loop) +SessionStats(bytes_delivered,frames_sent,retries,nacks,duplicates,crc_errors,ticks). - window — selective-repeat
WindowedSender<_, N>/WindowedReceiver<_, N>,1 ≤ N ≤ 8. Aliases:W8Sender,W8Receiver. - transport —
ByteTransport/ByteSource/ByteSink. - stream — any bytes through the envelope:
SliceSource/SliceSink,send_all/recv_all(stop-and-wait and windowed). JPEG, a file, flash, a sensor, orstructbytes are all just aByteSource. The frame is not the application type. - fault —
FaultyTransportfor adversarial tests. - actors — cooperative
Systemfor N links on one thread. - p2p — same crate, same budget.
use psicose::prelude::*. See below.
Not yet: routing / gossip / store-and-forward, UART/SPI/CAN/radio,
File.
Layers
APPLICATION
│
┌──────────▼──────────┐
│ p2p │
│ PeerId / Session │
│ Stream / Message │
└──────────┬──────────┘
│ payload bytes
┌──────────▼──────────┐
│ transport │
│ TYPE|SEQ|DATA|CRC │
│ START/FINISH/ABORT │
│ Pump / Stats │
└──────────┬──────────┘
│
ByteTransport
The transport does not know what a peer or a forum post is. The P2P layer does not grow the 4-byte frame.
API
use *;
| You write | Meaning |
|---|---|
PeerId::from([0xAA; 8]) |
8-byte identity. Never in the 4-byte frame. |
PeerTable::<4>::new(id) |
Neighbors, 1 ≤ N ≤ 8. Default: window 8 + STREAM. |
PeerTable::with(id, cfg) |
Same table, explicit SessionConfig. |
SessionConfig::offer(4, features) |
Hello config. Version is PROTOCOL_VERSION. |
Capabilities::STREAM | Capabilities::WINDOW |
Feature bits. CRC is not negotiated. |
Wire::new().pumps() |
In-memory A↔B. ACK/NACK → TX, DATA/START/FINISH/ABORT → RX. |
Pump::on(tx, rx) |
Same wrapping on a UART / SPI / radio. |
PeerLink::connect / accept |
START + 12-byte hello both ways. |
link.offer(byte) |
DATA after Established. |
link.poll(&mut table) |
One cooperative step. Never loops. |
PollOutcome::is_closed() |
FINISH or ABORT ended the transfer. |
Wire hello is 12 payload bytes: PeerId (8) | ver (1) | window (1) | features (2).
PeerSession is bookkeeping only (≤ 128 B). StreamId / MessageId are
not SEQ.
use *;
let wire = new;
let = wire.pumps;
let mut alice = new;
let mut bob = new;
let mut a = match connect ;
let mut b = accept;
let _ = ;
Override the default offer with
PeerTable::with(id, SessionConfig::offer(4, Capabilities::STREAM | Capabilities::WINDOW)).
The 4-byte envelope is still just this:
use Frame;
let frame = data;
assert_eq!;
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
Any data, not just frames
The 4-byte frame is the envelope. Application data is always bytes:
JPEG File Flash Sensor firmware.bin your struct
└───────┴───────┴────────┴──────────────┘
│
ByteSource ← you implement this
│ 1 byte at a time
▼
PSICOSE ← never owns the blob
│
ByteSink
psicose::File is not in this crate. A JPEG and a 4 GB file use the
same path: implement ByteSource / ByteSink (or use SliceSource /
SliceSink when the caller already holds the buffer).
Examples
Runnable stand-ins for problems this crate is meant to solve. The "UART"
and "radio" are in-memory rings; swap End for your driver.
| Example | Real problem | What PSICOSE sees |
|---|---|---|
jpeg_over_uart |
OV2640-class camera RAM → host file over UART | JPEG bytes |
firmware_flash |
Host firmware.bin → MCU NOR flash, 1 byte programmed at a time |
file bytes |
sensor_telemetry |
DHT22 + battery ADC packed struct over a slow radio | 8-byte sample |
radio_windowed |
300-byte EEPROM dump; first DATA frame dropped | bytes, window N=8 |
firmware_flash implements ByteSource on std::fs::File — that is the
pattern for a 4 GB image. The crate still never owns the file.
Tests
See tests/end_to_end.rs, tests/hostile.rs, tests/windowed.rs,
tests/pump.rs, and tests/p2p.rs.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.