psicose 0.2.2

no_std, heapless reliable byte transport: 1-byte payload, 4-byte frame, stop-and-wait and windowed (N ≤ 8).
Documentation

PSICOSE-1B

crates.io docs.rs license

English · Português (Brasil)

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%.

[dependencies]
psicose = "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, SEQ wraparound (255 → 0), assembler, OutBuf (one wire byte per poll).
  • tx / rx — stop-and-wait. START / FINISH wait 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, or struct bytes are all just a ByteSource. The frame is not the application type.
  • fault — FaultyTransport for adversarial tests.
  • actors — cooperative System for 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.

cargo run --example jpeg_over_uart
cargo run --example firmware_flash
cargo run --example sensor_telemetry
cargo run --example radio_windowed
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 psicose::Frame;

let frame = Frame::data(0, 0xAA);
assert_eq!(Frame::from_bytes(frame.to_bytes()), Ok(frame));

Tests

cargo +1.75.0 test

See tests/end_to_end.rs, tests/hostile.rs, and tests/windowed.rs.

License

Licensed under either of

at your option.