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.
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.2 — 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/FINISHwait for ACK. - 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.
Not yet: SessionId in the 4-byte frame, UART/SPI/CAN/radio, File.
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.
Example (frame envelope)
use Frame;
let frame = data;
assert_eq!;
Tests
See tests/end_to_end.rs, tests/hostile.rs, and tests/windowed.rs.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.