Skip to main content

Crate psicose

Crate psicose 

Source
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)
LayerEntry points
Wire frame / CRC / SEQFrame, crc8
Stop-and-wait / windowPump, WindowedPump, Wire::copy
Hardware demuxLinkFace
P2P session + peersNode, PeerLink, establish

§Non-negotiable properties

  • #![no_std], #![forbid(unsafe_code)], zero dependencies. No heap, no Vec, 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 forWhen
NodeP2P entry — identity, neighbors, connect / accept
LinkFaceHardware demux: one UART → Pump TX/RX ends
WireIn-memory A↔B harness (tests). Not the 4-byte frame.
Wire::copyStop-and-wait copy through the motor
establish / send_messageCooperative P2P helpers
PeerLinkLive link (prefer Node)
SessionConfigHello offer — DEFAULT, FORUM, SECURE
Pump / WindowedPumpReliability over your ByteTransport
Frame / crc8Speak the 4-byte envelope yourself
SliceSource / SliceSink&[u8] / &mut [u8] as byte ends
ByteTransportYou 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), still no_std and heapless.

Structs§

Capabilities
Feature bits announced in the hello.
Defragmenter
Rebuilds one message into a caller-owned buffer, one payload byte at a time.
DuplexFull
The heapless ring had no room.
DuplexPort
One half of one peer: either the sender port or the receiver port.
DuplexWire
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 + chunk fragments.
Frame
A single, fixed-size PSICOSE-1B frame.
FrameAssembler
A fixed-size, stack-allocated buffer that fills up one byte at a time and yields a decoded Frame (or a FrameError) once full.
HalfDuplex
Stages one frame, then writes it as a single burst.
IdleBudget
Ceiling on consecutive polls with no application-level progress.
LinkFace
Demux one physical ByteTransport into Pump TX/RX ends.
MessageHeader
Per-fragment header. Payload bytes, never part of the 4-byte frame.
MessageId
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.
PageLink
Streams a blob as pages of at most N bytes over a windowed turn.
PeerEntry
One occupied slot: the session bookkeeping for a single neighbor.
PeerId
64-bit peer identity.
PeerLink
Connector or listener over one WindowedPump (N = MAX_WINDOW).
PeerSession
One logical link between two peers, above one PSICOSE session.
PeerTable
[Option<PeerEntry>; N] of neighbors. 1 ≤ N ≤ 8.
Pump
One session: a Sender and a Receiver driven by the same poll.
Receiver
A stop-and-wait PSICOSE-1B receiver, symmetric to Sender.
RetryPolicy
Governs how long a Sender waits 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.
SessionConfig
What a peer offers before DATA flows. Serialized as 4 payload bytes.
SessionStats
Session counters. Copy, stack-only, no logging.
SliceFull
The destination slice had no room for the next byte.
SliceSink
Borrowed byte sink. The caller owns the buffer; PSICOSE does not.
SliceSource
Borrowed byte source. The caller owns the buffer; PSICOSE does not.
StreamId
Identifies a logical conversation over one link.
Turn
Stop-and-wait pump that alternates who may open a session.
WindowTurn
Hardware turn: both peers send, and DATA uses the window of 8.
WindowedPump
Cooperative pump over a selective-repeat window (N ≤ 8).
WindowedReceiver
Selective-repeat receiver with a compile-time window of N frames.
WindowedSender
Selective-repeat sender with a compile-time window of N frames.
Wire
In-memory duplex harness (DuplexWire) for tests and examples.

Enums§

DefragError
Why a Defragmenter rejected a byte.
Error
Errors produced by PSICOSE-1B’s TX/RX state machines.
FaceError
Error from a LinkFace port.
FrameError
Errors that can occur while decoding raw bytes into a Frame.
FrameType
The role a frame plays on the wire.
HandshakeError
Why a hello was rejected.
HeaderError
Why a serialized header was rejected.
LinkError
Errors from a live link.
LinkEvent
Outcome of one PeerLink::poll.
PageEvent
What one PageLink::poll observed.
PollOutcome
What happened as a result of one Receiver::poll call.
PumpEvent
Outcome of one cooperative Pump::poll.
RxState
The receiver’s current state. Exposed via Receiver::state for diagnostics/logging.
SessionState
Where the session is in its life cycle.
StreamError
Error from a source-to-sink transfer: either the link or the application reader/writer.
TableError
Why a table operation failed.
TurnEvent
What one Turn::poll observed.
TxPoll
Outcome of one Sender::poll.
TxState
Transmitter state.
WireCopyError
Why DuplexWire::copy stopped 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§

ByteSink
A write-only destination for bytes — the mirror image of ByteSource.
ByteSource
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.
ByteTransport
A byte-oriented, non-blocking, bidirectional link.
LineDirection
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 sink until FINISH.
recv_all_budgeted
recv_all with an IdleBudget so a silent peer cannot hang the loop.
recv_all_windowed
Windowed counterpart of recv_all.
recv_all_windowed_budgeted
recv_all_windowed with an IdleBudget.
recv_bytes
Receive into a borrowed slice until FINISH.
send_all
Drain src through a stop-and-wait sender, then FINISH.
send_all_windowed
Drain src through a windowed sender, then FINISH.
send_all_windowed_budgeted
send_all_windowed with an IdleBudget on the WindowFull spin.
send_bytes
Send a borrowed slice. The slice stays with the caller.
send_message
Fragment body on tx and rebuild into inbox via rx (same wire).

Type Aliases§

W8Receiver
Window of 8 — the named PSICOSE-W8 receiver.
W8Sender
Window of 8 — the named PSICOSE-W8 sender.