pyqcc package
pyqcc.cmdctrl module reference
pyqcc cmdctrl module.
Copyright (C) 2024 Crypta Labs Ltd.
- class pyqcc.cmdctrl.device(interface: str, device_name: str)
Bases:
object
QRNG Cmd&Ctrl Device class
This is the class that implements the Cmd&Ctrl protocol for Crypta Labs QRNG devices. Provides the functions to execute device commands.
- Parameters:
interface (str) – communication interface to use (
"serial"
,"tcp"
or"tcpudp"
)device_name (str) – Device URI (e.g
"COM3"
or"/dev/ttyUSB0"
for serial devices, IP address for tcp/udp for network connected devices)
- Raises:
IOError – Unknown interface.
- close_comm()
Close the communication interface with the device
- command(cmd_code: int, payload=None) bool | bytes | None
Generic command function.
- Parameters:
cmd_code (int) – Command code.
payload (bytes, optional) – Command payload.
- Returns:
True if success but the response payload is empty. Response payload bytes if success and response payload present. None if failure.
- Return type:
True | dict | None
- Raises:
ValueError – Command code not valid.
RuntimeError – Unexpected byte received from the device.
- get_info() dict | None
Read the QRNG device information.
- Returns:
- If success, it returns a dictionary containing the device info fields (strings):
core_version
: QRNG core version (int).sw_version
: device firmware version (int).serial
: serial number (str).hw_info
: QRNG device hardware information (str).
If failure, returns None.
- Return type:
dict | None
- get_statistics() dict | None
Read the QRNG device statistics (since last reset).
- Returns:
- If success, returns a dictionary containing the statistics fields:
generated_bytes
: number of random bytes generated.repetition_count_failures
: how many times the repetition count health test had failed.adaptive_proportion_failures
: how many times the adaptive proportion health test had failed.bitcount_failures
: how many times the bitcount health test had failed.speed
: QRNG generation speed (bit/s)sensif_average
: current QOM output average.ledctrl_level
: current light source level (percent).
If failure, returns None.
- Return type:
dict | None
- get_status() dict | None
Read the QRNG device status.
- Returns:
- If success, it returns a dictionary containing the status fields:
started
: QRNG processing started, should be 1 if the QRNG device is operatingstartup_test_in_progress
: startup test not completedvoltage_low
: QRNG light source auto-calibration failure, the QOM output voltage is too lowvoltage_high
: QRNG light source auto-calibration failure, the QOM output voltage is too highvoltage_undefined
: The QOM output voltage keeps oscillating beyond auto-calibration control.bitcount
: Bit count health test failure present, this is a Crypta Labs custom test on the random data, it checks that the proportion between 1s and 0s in the random data doesn’t exceed a certain thresholdrepetition_count
: Repetition count health test failure present (see NIST SP 800-90B).adaptive_proportion
: Adaptive proportion health test failure present (see NIST SP 800-90B).ready_bytes
: Number of bytes ready to read.
If failure, returns None.
- Return type:
dict | None
- read_continuous(length: int) bytes | None
Read data from the QRNG device when the continuous mode is active.
Before calling this function the device must be in continuous mode, see
start_continuous()
- Parameters:
length (int) – How many bytes to read from the QRNG device. There is no limit to the number of bytes requested as the QRNG device is continuously sending random data.
- Returns:
Returns the random bytes received from the device. None if failure.
- Return type:
bytes | None
- read_signed(length: int) dict | None
Execute one shot signed reading of random data
The asymmetric key used to sign (and verify) the data is different for each specific QRNG device implementations. Check the QRNG device documentation for information on how to extract the public key from the device and check the signature.
Note
Not all the QRNG devices implement the signed read command. Current supported devices: QCicada, FW 5.13 and greater.
- Parameters:
length (int) – How many bytes to read from the QRNG device. Like the standard one shot read, the maximum allowed length is the current available bytes on the device, use
get_status()
method to check how many bytes are available.- Returns:
- If success, return a dictionary containing two items:
qrnd
: random bytes received from the device.signature
: bytes containing the raw signature.
Return None if failure.
- Return type:
dict | None
- start_continuous() bool | None
Start continuous mode.
When this command is issued, the QRNG device starts sending random data on the QRND channel. Then the caller can read the random data using
read_continuous()
method.- Returns:
True if success, None if failure.
- Return type:
True | None
- start_one_shot(length: int) bytes | None
Execute one shot reading.
- Parameters:
length (int) – how many bytes to read from the QRNG device, the maximum allowed length is the current available bytes on the device, use
get_status()
to check how many bytes are available.- Returns:
Return an array of size length containing the random data received from the device if success. None if failure.
- Return type:
bytes | None
- stop() bool | None
Stop continuous mode.
It fails if the continuous mode was not previously started.
- Returns:
True if success. None if failure.
- Return type:
True | None
- update_chunk(data) dict | None
Send firmware image chunk
This function must be called several times after
update_init()
to send the actual firmware. The caller can check the returnedupdate_status
andremaining
fields to check the status of the update. Each chunk is maximumUPDATE_MAX_CHUNK
bytes. When theupdate_status
field of the returned dictionary isUPDATE_STS_TRANSFER_IN_PROGRESS
it means that the device is expecting to receive the remaining part of the firmware and theremaining
field indicates how many bytes are left to be transferred. When the firmware is completely transferred the status isUPDATE_STS_TRANSFER_COMPLETED
, that means the FW update procedure is complete.- Parameters:
data (bytes) – Firmware image chunk bytes
- Returns:
- If success, it returns a dictionary containing the update status fields
update_status
: status of the updateremaining
: How many bytes left to transfer.
If failure, returns None.
- Return type:
dict | None
- update_init(image_size) dict | None
Initialize firmware update
- Parameters:
image_size (int) – Size of the firmware image (in bytes).
- Returns:
- If success, it returns a dictionary containing the update status fields:
update_status
: status of the update, if the update procedure can start it should beUPDATE_STS_READY
.remaining
: How many bytes left to transfer, this should be the image size.
If failure, returns None.
- Return type:
dict | None