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)
- `-d, --device <DEVICE>` - Select specific device (index, port, or type)
  - Examples: `1`, `/dev/ttyACM0`, `pro`, `prov2`, `truerng`
- `-l, --list` - List all available TrueRNG devices
- `-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.

### Device Selection

When multiple TrueRNG devices are connected, you can select a specific device using the `-d` option:

- **By index**: Use the device number from `--list` (e.g., `-d 1`, `-d 2`)
- **By port path**: Use the full device path (e.g., `-d /dev/ttyACM0`)
- **By device type**: Use device type keywords:
  - `truerng` - Select original TrueRNG device
  - `pro` - Select TrueRNGpro device
  - `prov2` - Select TrueRNGproV2 device

```bash
# List all available devices
./truerng --list

# Use first device from list
./truerng -d 1 -n 1MB

# Use specific port
./truerng -d /dev/ttyACM1 -n 512K

# Use TrueRNGpro device
./truerng -d pro -n 2MB -f hex
```

### Examples

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

# List available devices
./truerng --list

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

# Generate 2.5MB using specific device and pipe to another program
./truerng -d 2 -n 2.5MB | xxd

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

# Generate 512KB as hex and save to file using specific port
./truerng -d /dev/ttyACM0 -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
- **Multiple devices**: Automatically detects and warns when multiple devices are present

### Multiple Device Handling

When multiple TrueRNG devices are connected:
- Without `-d` option: Uses the first available device with a warning
- With `-d` option: Uses the specified device
- Use `--list` to see all available devices and their details

## 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

### Device Listing
```bash
./truerng --list
Available TrueRNG devices:
  1. TrueRNGproV2 at /dev/ttyACM0 (VID:04D8 PID:EBB5)
  2. TrueRNG at /dev/ttyACM2 (VID:04D8 PID:F5FE)
```

### 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
=======
```

### Multiple Device Warning
```
Multiple TrueRNG devices found - using first available
(Use -d option to select specific device or --list to see all)
TrueRNG - True Random Number Generator
==================================================
TrueRNGproV2 Found
Using port: /dev/ttyACM0
...
```

### 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)
  -d, --device <DEVICE>    Select specific device (index, port, or type)
                           Examples: 1, /dev/ttyACM0, pro, prov2
  -l, --list               List all available TrueRNG devices
  -q, --quiet              Suppress statistics/progress
  -v, --verbose            Show detailed device information
  -h, --help               Show this help message

Device Selection:
  When multiple devices are present, use -d to select:
    -d 1                   Select first device from list
    -d /dev/ttyACM1        Select by port path
    -d pro                 Select TrueRNGpro device
    -d prov2               Select TrueRNGproV2 device
    -d truerng             Select original TrueRNG device

Examples:
  truerng --list                            # List available devices
  truerng -n 1K -f hex                      # Use first available device
  truerng -d 2 -n 1MB                       # Use second device from list
  truerng -d /dev/ttyACM1 -n 512K           # Use specific port
  truerng -d pro -n 1GB -o random.dat       # Use TrueRNGpro device