true_rng/README.md

# TrueRNG C Implementation

This is a C equivalent of the Python `main.py` script for reading data from TrueRNG devices.

## Overview

The program reads random data from a TrueRNG device via serial port, counts the number of ones and zeros in the data, and provides flexible output options including multiple formats and size specifications.

## Supported Devices

- TrueRNG (PID: 04D8, HID: F5FE)
- TrueRNGpro (PID: 16D0, HID: 0AA0)  
- TrueRNGproV2 (PID: 04D8, HID: EBB5)

## Requirements

- Linux system with termios support
- GCC compiler
- TrueRNG device connected via USB
- Appropriate permissions to access the serial device (may need root or proper udev rules)

## Building

```bash
make
```

Or manually:
```bash
gcc -Wall -Wextra -std=c99 -O2 -o truerng main.c
```

## Usage

### Basic Usage

```bash
./truerng
```

### Command Line Options

```bash
./truerng [OPTIONS]
```

**Options:**
- `-n, --bytes <N>` - Number of bytes to generate (default: 1048576)
  - Supports size suffixes: K, MB, GB, TB (case-insensitive)
  - Examples: `1024`, `1K`, `2.5MB`, `1GB`, `512k`, `1tb`
- `-f, --format <FORMAT>` - Output format: binary, hex, base64, decimal
  - Default: binary when piped, hex in interactive mode
- `-o, --output <FILE>` - Output filename (works with all formats)
- `-q, --quiet` - Suppress statistics/progress output
- `-v, --verbose` - Show detailed device information
- `-h, --help` - Show help message

### Size Suffixes

The `-n` option supports convenient size suffixes (case-insensitive):
- **K** or **KB**: Kilobytes (1024 bytes)
- **M** or **MB**: Megabytes (1,048,576 bytes)
- **G** or **GB**: Gigabytes (1,073,741,824 bytes)
- **T** or **TB**: Terabytes (1,099,511,627,776 bytes)

Decimal values are supported: `1.5MB`, `2.5GB`, etc.

### Examples

```bash
# Basic usage - interactive mode with hex output
./truerng

# Generate 1KB of data in hex format
./truerng -n 1K -f hex

# Generate 2.5MB and pipe to another program
./truerng -n 2.5MB | xxd

# Save 1GB of binary data to file quietly
./truerng -n 1GB -o random.dat -q

# Generate 512KB as hex and save to file
./truerng -n 512K -f hex -o output.hex

# Generate base64 output with verbose device info
./truerng -n 1MB -f base64 -v

# Backward compatibility - plain numbers still work
./truerng -n 1048576 -f binary
```

### Output Formats

- **binary**: Raw binary data (default for piped output)
- **hex**: Hexadecimal representation (default for interactive mode)
- **base64**: Base64 encoded output
- **decimal**: Decimal byte values

### Modes

The program automatically detects the execution context:
- **Interactive mode**: Shows progress, statistics, and defaults to hex output
- **Piped mode**: Optimized for piping, defaults to binary output
- **File output**: Can be combined with any format using `-o` option

## Configuration

You can modify the following constants in [`main.c`](main.c:34):

- `BLOCKSIZE`: Number of bytes to read per block (default: 1024)

## Permissions

On Linux, you may need to set proper permissions for the serial device:

```bash
sudo chmod 666 /dev/ttyUSB0  # Replace with your device
```

Or add your user to the dialout group:
```bash
sudo usermod -a -G dialout $USER
```

## Differences from Python Version

The C implementation:
- Uses native Linux serial port APIs instead of pyserial
- Implements USB device detection via sysfs
- Uses lookup tables for efficient bit counting
- Provides enhanced command line interface with size suffixes
- Supports multiple output formats (binary, hex, base64, decimal)
- Provides equivalent functionality with better performance

## Sample Output

### Interactive Mode
```
TrueRNG - True Random Number Generator
==================================================
TrueRNGproV2 Found
Using port: /dev/ttyACM0
Generating: 1024 bytes
Starting data collection...
1024/1024 Bytes Read at 504.19 Kbytes/s

Results
=======
Total time: 0.02 seconds
Total Ones:  4072
Total Zeros: 4120
Total Bits:  8192
Extra zeros: 48
=======
```

### Piped Mode with Verbose
```
TrueRNG - True Random Number Generator
Mode: Piped (Verbose)
==================================================
TrueRNGproV2 Found
Using port: /dev/ttyACM0
Generating: 2048 bytes
Starting data collection...
2048/2048 Bytes Read at 462.17 Kbytes/s

Results
=======
Total time: 0.04 seconds
Total Ones:  8144
Total Zeros: 8248
Total Bits:  16392
Extra zeros: 104
=======
```

### Quiet Mode
```bash
./truerng -n 1K -o data.bin -q
# No output - data saved silently to data.bin
```

### Help Output
```bash
./truerng --help
TrueRNG - True Random Number Generator
Usage: truerng [OPTIONS]

Options:
  -n, --bytes <N>          Number of bytes to generate (default: 1048576)
                           Supports suffixes: K, MB, GB, TB (e.g., 1K, 2.5MB, 1GB)
  -f, --format <FORMAT>    Output format: binary, hex, base64, decimal (default: binary when piped, interactive otherwise)
  -o, --output <FILE>      Output filename (ignored in piped mode)
  -q, --quiet              Suppress statistics/progress
  -v, --verbose            Show detailed device information
  -h, --help               Show this help message

Examples:
  truerng -n 1024 -f hex                    # Interactive mode with hex output
  truerng -n 1K -f hex                      # Same as above using K suffix
  truerng -n 2.5MB | xxd                    # Piped mode with MB suffix
  truerng -n 1GB -o random.dat -q           # Save 1GB to file quietly
  truerng -n 512K -f hex -o output.hex      # Save 512KB as hex to file