API Reference¶
BarcodeTTL¶
Main interface for TTL barcode generation and decoding.
ttl_barcoder.BarcodeTTL
¶
Main interface for TTL barcode generation and decoding.
Constructs and owns a generator, encoder, and decoder whose parameters are all derived from a single BarcodeConfig so they stay in sync.
info
property
¶
Return a summary dict covering config, generator, and encoder parameters.
decode_edges(edge_timestamps, edge_levels)
¶
Decode edge timestamps to (timestamp, barcode_value) or None.
default_config()
classmethod
¶
Return the default BarcodeConfig instance.
get_multiple_sequences(count=1, interval_s=5.0, start_timestamp=None)
¶
Return timing sequences for multiple barcodes spaced interval_s apart.
For timestamp TTL the barcodes encode evenly spaced future times; for random TTL each barcode is independently random.
get_sequence(barcode=None)
¶
Return (level, duration_ms) timing sequence for hardware transmission.
get_sequence_from_timestamp(timestamp)
¶
Get timing sequence from a specific Unix timestamp (timestamp TTL only).
prepare()
¶
Capture wall time and return (barcode_value, wall_time, timing_sequence).
Wall time is captured before generate() so it matches the encoded timestamp.
recover_timestamp(barcode_value, reference_time=None)
¶
Recover original timestamp from barcode value with wraparound handling.
BarcodeConfig¶
Pydantic v2 configuration model. All fields are validated on construction.
ttl_barcoder.BarcodeConfig
¶
Bases: BaseModel
Barcode configuration with Pydantic v2 validation.
coverage_years
property
¶
Coverage in years (timestamp TTL only).
safety_ratio
property
¶
Safety ratio (bit_duration vs tolerance window).
total_duration_ms
property
¶
Total barcode duration in milliseconds.
default()
classmethod
¶
Create default configuration.
from_dict(config_dict)
classmethod
¶
Create configuration from dictionary.
info()
¶
Configuration summary as dictionary.
BarcodeDecoder¶
ttl_barcoder.BarcodeDecoder
¶
Decode edge timestamps back to barcode values.
Must be constructed with parameters that match the encoder that produced the signal. Use BarcodeConfig to keep encoder and decoder in sync.
decode_edges(edge_timestamps, edge_levels)
¶
Decode edge timestamps to (timestamp, barcode_value) or None on failure.
Generators¶
ttl_barcoder.TTLGenerator
¶
ttl_barcoder.TimestampGenerator
¶
Bases: TTLGenerator
Generate barcodes from Unix timestamps at configurable precision.
generate(timestamp=None)
¶
Generate barcode from timestamp (defaults to current time).
generate_sequence(count=1, interval_s=5.0, start_timestamp=None)
¶
Generate count barcodes spaced interval_s seconds apart.
recover_timestamp(barcode_value, reference_time=None)
¶
Recover Unix timestamp from a barcode value, resolving modular wraparound.
Checks the previous, current, and next bit-width windows relative to reference_time and returns the candidate closest to the reference.
ttl_barcoder.RandomGenerator
¶
Bases: TTLGenerator
Generate random n-bit barcode values using numpy.
generate(timestamp=None)
¶
Generate a random barcode value.
Utilities¶
ttl_barcoder.get_preset(name)
¶
Get a preset configuration by name.
ttl_barcoder.create_generator(config)
¶
Create TimestampGenerator or RandomGenerator from config.
Enums¶
ttl_barcoder.TTLType
¶
Bases: StrEnum
Type of barcode value to generate.
ttl_barcoder.TimestampPrecision
¶
Bases: StrEnum
Timestamp quantization precision.