Struct Trng 

#[non_exhaustive]
pub struct Trng { /* private fields */ }

Available on crate feature unstable only.

True Random Number Generator (TRNG)

The Trng struct represents a true random number generator that combines the randomness from the hardware RNG and an ADC. This struct provides methods to generate random numbers and fill buffers with random bytes. Due to pulling the entropy source from the ADC, it uses the associated registers, so to use TRNG we need to “occupy” the ADC peripheral.

To generate true random numbers, an instance of TrngSource is required. Once created, you can create Trng instances at any time, as long as the TrngSource is alive.

Example

use esp_hal::rng::{Trng, TrngSource};

let mut buf = [0u8; 16];

// ADC is not available from now
let trng_source = TrngSource::new(peripherals.RNG, peripherals.ADC1.reborrow());

let trng = Trng::try_new()?;

// Generate true random numbers
trng.read(&mut buf);
let true_random_number = trng.random();

// Downgrade to Rng to allow disabling the TrngSource
let rng = trng.downgrade();

// Drop the true random number source. ADC is available now.
core::mem::drop(trng_source);

let mut adc1_config = AdcConfig::new();
let mut adc1_pin = adc1_config.enable_pin(peripherals.GPIO3, Attenuation::_11dB);
let mut adc1 = Adc::new(peripherals.ADC1, adc1_config);
let pin_value = adc1.read_oneshot(&mut adc1_pin)?;

// Now we can only generate pseudo-random numbers...
rng.read(&mut buf);
let pseudo_random_number = rng.random();

// ... but the ADC is available for use.
let pin_value: u16 = adc1.read_oneshot(&mut adc1_pin)?;

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Implementations

impl Trng

pub fn try_new() -> Result<Self, TrngError>

Attempts to create a new True Random Number Generator (TRNG) instance.

This function returns a new Trng instance on success, or an error if the TrngSource is not active.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn random(&self) -> u32

Returns a new, random u32 integer.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn read(&self, buffer: &mut [u8])

Fills the provided buffer with random bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn downgrade(self) -> Rng

Downgrades the Trng instance to a Rng instance.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl Clone for Trng

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Trng

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Trng

fn default() -> Trng

Returns the “default value” for a type.

impl Drop for Trng

fn drop(&mut self)

Executes the destructor for this type.

impl RngCore for Trng

Compatibility with rand_core 0.6. Documentation can be found at https://docs.rs/rand_core/0.6.4/rand_core/trait.RngCore.html.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

Fill dest with random data.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Fill dest entirely with random data.

impl RngCore for Trng

Compatibility with rand_core 0.9. Documentation can be found at https://docs.rs/rand_core/0.9.5/rand_core/trait.RngCore.html.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

Fill dest with random data.

impl TryRng for Trng

Compatibility with rand_core 0.10

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Error = Infallible

The type returned in the event of a RNG error.

fn try_next_u32(&mut self) -> Result<u32, Self::Error>

Return the next random u32.

fn try_next_u64(&mut self) -> Result<u64, Self::Error>

Return the next random u64.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error>

Fill dst entirely with random data.

impl CryptoRng for Trng

Compatibility with rand_core 0.6. Documentation can be found at https://docs.rs/rand_core/0.6.4/rand_core/trait.CryptoRng.html.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl CryptoRng for Trng

Compatibility with rand_core 0.9. Documentation can be found at https://docs.rs/rand_core/0.9.5/rand_core/trait.CryptoRng.html.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl TryCryptoRng for Trng

Compatibility with rand_core 0.10

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.