Expand description
§PSICOSE-1B
A no_std, heapless framework for reliable byte links: wire protocol,
pump, windowing, and P2P sessions. You compose the layers; nothing
allocates. Zero crate dependencies — use psicose::… is only PSICOSE.
P2P is not a separate crate. Node, PeerId, PeerTable,
PeerLink, hello negotiation, and fragmentation live in this package
on top of the same 4-byte frame. Examples call into this motor — they
do not invent an external P2P and pass connections in.
§Framework layers
exemplos / application / boards/*
│
▼
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, or Wire harness)| Layer | Entry points |
|---|---|
| Wire frame / CRC / SEQ | Frame, crc8 |
| Stop-and-wait / window | Pump, WindowedPump, Wire::copy |
| Hardware demux | LinkFace |
| P2P session + peers | Node, PeerLink, establish |
§Non-negotiable properties
#![no_std],#![forbid(unsafe_code)], zero dependencies. No heap, noVec, no third-party crates in the dependency graph.- Constant memory regardless of transfer size.
- The wire frame is fixed at
protocol::FRAME_LEN= 4 bytes:TYPE(1) | SEQ(1) | DATA(1) | CRC(1). - Reliability is the protocol’s job. ACK, NACK, SEQ, CRC-8, retry.
Start with prelude. Map: docs/API.md. Hardware: docs/HARDWARE.md.
Spec: docs/PROTOCOL.md.
§What you import (use psicose::…)
Prefer prelude. Everything below is a psicose type — no foreign
crates appear in the public API.
| Reach for | When |
|---|---|
Node | P2P entry — identity, neighbors, connect / accept |
LinkFace | Hardware demux: one UART → Pump TX/RX ends |
Wire | In-memory A↔B harness (tests). Not the 4-byte frame. |
Wire::copy | Stop-and-wait copy through the motor |
establish / send_message | Cooperative P2P helpers |
PeerLink | Live link (prefer Node) |
SessionConfig | Hello offer — DEFAULT, FORUM, SECURE |
Pump / WindowedPump | Reliability over your ByteTransport |
Frame / crc8 | Speak the 4-byte envelope yourself |
SliceSource / SliceSink | &[u8] / &mut [u8] as byte ends |
ByteTransport | You implement this for UART/SPI/radio |
§Minimal P2P example
use psicose::prelude::*;
let wire = Wire::new();
let (pump_a, pump_b) = wire.link_pumps();
let mut alice = Node::<4>::new(PeerId::from_label(b"alice"));
let mut bob = Node::<4>::new(PeerId::from_label(b"bob"));
let mut a = match alice.connect(pump_a) {
Ok(link) => link,
Err(_) => return,
};
let mut b = bob.accept(pump_b);
assert!(establish(&mut a, &mut alice, &mut b, &mut bob));
assert_eq!(alice.established(), 1);
assert_eq!(bob.established(), 1);§Threat model (short)
CRC-8 detects accidental corruption. It does not authenticate. Confidentiality/authenticity are outside this crate — seal messages in your application before they enter the transport if needed.
Modules§
- actors
- Cooperative orchestration above the wire protocol, still inside this crate.
- error
- Crate-wide error type.
- fault
- Fault injection: a heapless wrapper that deliberately damages the wire.
- p2p
- The P2P layer — part of the PSICOSE motor, not an external stack.
- prelude
- The names you write:
use psicose::prelude::*; - protocol
- The wire-level building blocks of PSICOSE-1B: frames, CRC, and sequence
numbers. This module has no knowledge of transports or state machines —
it only knows how to turn
(type, seq, data)into 4 trustworthy bytes and back. - pump
- Cooperative session pump: one RX step, one TX step, never a loop.
- rx
- The receive side: validates incoming DATA frames, ACKs the in-order ones, NACKs the corrupted ones, and transparently re-ACKs duplicate retransmissions without re-delivering the byte to the application.
- stream
- Application data is bytes. The 4-byte frame is only the envelope.
- timeout
- Retry and timeout policy.
- transport
- Transport-layer traits and the hardware demux.
- tx
- Stop-and-wait sender.
- window
- Selective-repeat window (
N ≤ 8), stillno_stdand heapless.
Structs§
- Capabilities
- Feature bits announced in the hello.
- Defragmenter
- Rebuilds one message into a caller-owned buffer, one payload byte at a time.
- Duplex
Full - The heapless ring had no room.
- Duplex
Port - One half of one peer: either the sender port or the receiver port.
- Duplex
Wire - Two lanes (A→B and B→A). Interior mutability so four ports share it.
- FaceRx
- RX half of a
LinkFace: writes ACK/NACK out; reads DATA/control frames. - FaceTx
- TX half of a
LinkFace: writes frames out; reads ACK/NACK. - Fragmenter
- Cuts a caller-owned message into
header + chunkfragments. - Frame
- A single, fixed-size PSICOSE-1B frame.
- Frame
Assembler - A fixed-size, stack-allocated buffer that fills up one byte at a time
and yields a decoded
Frame(or aFrameError) once full. - Half
Duplex - Stages one frame, then writes it as a single burst.
- Idle
Budget - Ceiling on consecutive polls with no application-level progress.
- Link
Face - Demux one physical
ByteTransportinto Pump TX/RX ends. - Message
Header - Per-fragment header. Payload bytes, never part of the 4-byte frame.
- Message
Id - Identifies one message inside a stream. Wraps mod 65536; the
transport
SEQ(u8) is a different counter for a different problem. - Node
- One local endpoint of the PSICOSE framework.
- NopDirection
- No external pin. Frames are still released four bytes at a time.
- Page
Link - Streams a blob as pages of at most
Nbytes over a windowed turn. - Peer
Entry - One occupied slot: the session bookkeeping for a single neighbor.
- PeerId
- 64-bit peer identity.
- Peer
Link - Connector or listener over one
WindowedPump(N = MAX_WINDOW). - Peer
Session - One logical link between two peers, above one PSICOSE session.
- Peer
Table [Option<PeerEntry>; N]of neighbors.1 ≤ N ≤ 8.- Pump
- One session: a
Senderand aReceiverdriven by the same poll. - Receiver
- A stop-and-wait PSICOSE-1B receiver, symmetric to
Sender. - Retry
Policy - Governs how long a
Senderwaits for an ACK before retransmitting, and how many times it will retry before giving up. - Sender
- A stop-and-wait PSICOSE-1B sender.
- Sequence
- A monotonically increasing (mod 256) sequence counter.
- Session
Config - What a peer offers before DATA flows. Serialized as 4 payload bytes.
- Session
Stats - Session counters.
Copy, stack-only, no logging. - Slice
Full - The destination slice had no room for the next byte.
- Slice
Sink - Borrowed byte sink. The caller owns the buffer; PSICOSE does not.
- Slice
Source - Borrowed byte source. The caller owns the buffer; PSICOSE does not.
- Stream
Id - Identifies a logical conversation over one link.
- Turn
- Stop-and-wait pump that alternates who may open a session.
- Window
Turn - Hardware turn: both peers send, and DATA uses the window of 8.
- Windowed
Pump - Cooperative pump over a selective-repeat window (
N ≤ 8). - Windowed
Receiver - Selective-repeat receiver with a compile-time window of
Nframes. - Windowed
Sender - Selective-repeat sender with a compile-time window of
Nframes. - Wire
- In-memory duplex harness (
DuplexWire) for tests and examples.
Enums§
- Defrag
Error - Why a
Defragmenterrejected a byte. - Error
- Errors produced by PSICOSE-1B’s TX/RX state machines.
- Face
Error - Error from a
LinkFaceport. - Frame
Error - Errors that can occur while decoding raw bytes into a
Frame. - Frame
Type - The role a frame plays on the wire.
- Handshake
Error - Why a hello was rejected.
- Header
Error - Why a serialized header was rejected.
- Link
Error - Errors from a live link.
- Link
Event - Outcome of one
PeerLink::poll. - Page
Event - What one
PageLink::pollobserved. - Poll
Outcome - What happened as a result of one
Receiver::pollcall. - Pump
Event - Outcome of one cooperative
Pump::poll. - RxState
- The receiver’s current state. Exposed via
Receiver::statefor diagnostics/logging. - Session
State - Where the session is in its life cycle.
- Stream
Error - Error from a source-to-sink transfer: either the link or the application reader/writer.
- Table
Error - Why a table operation failed.
- Turn
Event - What one
Turn::pollobserved. - TxPoll
- Outcome of one
Sender::poll. - TxState
- Transmitter state.
- Wire
Copy Error - Why
DuplexWire::copystopped early.
Constants§
- CRC8_
POLY - The generator polynomial used by every CRC computation in this crate.
- FRAME_
LEN - Total size in bytes of a serialized frame. Fixed and known at compile time.
- HEADER_
LEN - Serialized size of a
MessageHeader, in payload bytes. - HELLO_
LEN - Hello size on the wire:
PeerId::LEN+SessionConfig::WIRE_LEN. - MAX_
PEERS - Hard ceiling. Bigger is still heapless; we refuse a core table that looks like a routing daemon.
- MAX_
WINDOW - Hard ceiling. Bigger is still heapless; we refuse more RX reorder state than eight payload bytes.
- PAYLOAD_
LEN - Application payload per DATA frame, in bytes. Always exactly 8 bits.
- PROTOCOL_
VERSION - Version this crate speaks. Carried in the hello, never in the frame.
Traits§
- Byte
Sink - A write-only destination for bytes — the mirror image of
ByteSource. - Byte
Source - A read-only source of bytes — e.g. a file, a flash region, or a sensor buffer being streamed out one byte at a time.
- Byte
Transport - A byte-oriented, non-blocking, bidirectional link.
- Line
Direction - Drives the external direction pin (RS-485 DE/RE, radio TX/RX switch).
Functions§
- crc8
- Computes the CRC-8 checksum of
bytes. - establish
- Poll both links until both report
LinkEvent::Established, or fail. - recv_
all - Write every delivered payload byte into
sinkuntil FINISH. - recv_
all_ budgeted recv_allwith anIdleBudgetso a silent peer cannot hang the loop.- recv_
all_ windowed - Windowed counterpart of
recv_all. - recv_
all_ windowed_ budgeted recv_all_windowedwith anIdleBudget.- recv_
bytes - Receive into a borrowed slice until FINISH.
- send_
all - Drain
srcthrough a stop-and-wait sender, then FINISH. - send_
all_ windowed - Drain
srcthrough a windowed sender, then FINISH. - send_
all_ windowed_ budgeted send_all_windowedwith anIdleBudgeton theWindowFullspin.- send_
bytes - Send a borrowed slice. The slice stays with the caller.
- send_
message - Fragment
bodyontxand rebuild intoinboxviarx(same wire).
Type Aliases§
- W8Receiver
- Window of 8 — the named PSICOSE-W8 receiver.
- W8Sender
- Window of 8 — the named PSICOSE-W8 sender.