randomrad 1.0.0

Minimal hardware-backed randomness library for Python with ESP32 serial input and automatic file fallback.

randomrad - minimal package edition

randomrad is a small Python library that exposes a familiar random-like API while sourcing bytes from external entropy instead of a deterministic pseudo-random generator.

This folder contains the minimal package-style edition of the project. It is suitable for installation as a local package and for demonstrating the core API without the full GUI and report environment.

Features

• import randomrad as rr
• random-like functions such as randbytes, random, randint, choice, choices, shuffle and sample
• ESP32 hardware backend over serial
• automatic fallback to a file backend
• host-side hardware buffer for faster repeated small requests
• package-specific NotEnoughEntropy exception
• no seed or replay mode by design

Installation

Open PowerShell inside this folder:

cd randomrad_pypi
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .

Quick start

import randomrad as rr

print(rr.randbytes(32))
print(rr.random())
print(rr.randint(1, 10))
print(rr.choice(["a", "b", "c"]))
print(rr.last_effective_backend())
print(rr.last_backend_detail())

Backend modes

The backend is selected with environment variables.

RANDOMRAD_BACKEND=auto|hw|file
RANDOMRAD_PORT=COM3
RANDOMRAD_BAUD=115200
RANDOMRAD_SERIAL_TIMEOUT=2.0
RANDOMRAD_HW_MAX_CHUNK=1024
RANDOMRAD_HW_BUFFER_FILL=2048
RANDOMRAD_GENERATED_ENTROPY_DIR=generated_entropy
RANDOMRAD_FILE_SIZE=8192

auto

The library first tries the ESP32 hardware backend. If the device is not available, if the port cannot be opened, or if the response is invalid, the file backend is used automatically.

hw

Only the ESP32 backend is allowed. This is useful when testing the real device because errors are not hidden by fallback behavior.

file

Only the file backend is used. This is useful for development and automated tests on machines without an ESP32.

ESP32 serial protocol

The host sends:

R <n>\n

The ESP32 answers:

S <mode>\n
D <n>\n
<n raw bytes>

The optional status mode describes the ESP32-internal entropy path:

• adc
• fallback
• mixed

Included modules

• randomrad.__init__: public package surface
• randomrad.api: random-like user API
• randomrad.entropy: backend selection and fallback logic
• randomrad.exceptions: package-specific exceptions
• randomrad.backends.file_backend: file fallback backend
• randomrad.backends.hw_backend: ESP32 serial backend with buffering

Limitations

This package is an educational prototype. It is designed to demonstrate hardware-backed entropy, backend routing and statistical validation workflows. It should not be treated as certified cryptographic random number generation.