Python API

Several messages are defined in ams_messages module, however most of them are wrapped in methods inside ams_module module. Recommended usage is:

Use AMSSerialModule class to send and receive messages

Use messages to read parameters and attributes read from the board

Check out the Python examples section for more information how to use API.

class ams_module.AMSSerialModule(*args, port='COM1', baudrate: int = 1000000, read_timeout=0.1, rx_max_queue_len=0, **kwargs)

Represents serial AMS-DIG-PROC board.

clear_reset_flag()

Clears reset flag.

flush_input()

Drops all not yet read messages from rx queue and clears input buffers.

flush_output()

Sends all not yet sent messages and buffers to the serial device.

processing_buffer_decimation(slot_id: int, ratio: int)

Configures slot for buffer decimation.

Args:

slot_id (int):

Number of slot, starting from 0

ratio (int):

Defines how many buffers will be skipped. For example value 4 means that every 4th buffer will be passed to the output.

processing_buffer_iir(slotId: int, weight: float)

Configures slot for buffer-wise infinite impulse response filter. Every n’th sample from input buffer will be averaged with every n’th sample from previous output buffer.

Args:

slotID (int):

Number of slot, starting from 0.

weight (float):

Weight for the IIR filter.

processing_disable()

Disables all processing slots

processing_oversampling(slot_id: int, ratio: int, output_samples: int)

Configures slot for oversampling, including averaging. Usefull if full sample rate is not desired, i.e. when working with mechanical choppers or pulsing heaters.

CAUTION: ratio * output_samples has to be multiple of input buffer length

Args:

slot_id (int):

Number of slot, starting from 0.

ratio (int):

Ratio of oversampling. Has to be power of 2. For example value 4 means that there will be 4 times less samples in the output buffer.

output_samples (int):

Number of samples in the output buffer. Has to be lower or equal 2048

processing_peak_peak(slot_id: int)

Configures slot for peak-peak measurement

Args:

slot_id (int):

Number of slot, starting from 0

processing_read(slotID: int)

Reads processing parameters for given slotID

Args:

slotID (int):

Number of slot, starting from 0.

processing_sample_iir(slotId: int, weight: float)

Configures slot for sample-wise infinite impulse response algorithm. Each sample will be calculated based on the following formula:

\[X = X_{previous} * weight + X_{new} * (1 - weight)\]

Args:

slotID (int):

Number of slot, starting from 0.

weight (float):

weight for IIR filter.

processing_simple_average(slotId: int)

Configures slot for simple average. Whole input buffer will be averaged and stored as single sample in the output buffer.

Args:

slotID (int):

Number of slot, starting from 0.

processing_slots = 4

Number of available processing slots

read_config(msgId: MessageIds)

Reads config for specified msgId. Can be used with MessageIds.MESSAGE_CONFIGURE_* values

Args:

msgId (MessageIds):

One of MessageIds.MESSAGE_CONFIGURE*

read_one_message(msgClasses=None, block=True, timeout=0.1, latest=False)

Reads one message from rx queue. If msgClasses are provided, all non matching messages will be dropped.

Args:

msgClasses (list or single class from ams_messages):

If set it will filter only specified messages.

block (bool, optional):

Set to False to return immadietly when there is no message in rx queue. Defaults to True

timeout (float, optional):

Timeout in seconds. Defaults to 0.1.

latest (bool, optional):

By default oldest message from rx queue will be returned. Set this argument to True to obtain only latest message and clear queue. Defaults to False.

Returns:

AbstractMessage subclass:

Subclass of AbstractMessage with received message or None.

List of subclasses:

MessageOutputData

MessageStatus

MessageConfig*

MessageProcessing*

MessageWorkmode*

read_workmode()

Reads currently configures workmode and it’s settings. The board will answer with one of the MessageIds.MESSAGE_MODE_* message.

reference_voltage = 3.3

Reference voltage for built-in ADC

reset()

Resets the board. Reset flag will be set to one.

save_config()

Saves configuration to non-volatile memory. This includes only MessageIds.MESSAGE_CONFIGURE* settings.

set_detector_temperature(temperature: int)

Sets expected temperature of the IR detector.

Args:

temperature (int):

Expected temperature of the IR detector, in Kelvins. Set to zero to disable temperature controller.

set_samplerate(physicalSampleRate: int)

Configures physical sample rate. Use it only if you know what you are doing, since lowering sample rate decreases signal to noise ratio

Args:

physicalSampleRate (int):

Physical sample rate. Has to be greater or equal 300_000 and lower or equal 7_000_000

wait_for_temperature_stabilization()

workmode_freerunning(samples_count=0)

Starts FREERUNNING workmode.

Args:

samples_count (int, optional):

Total number of samples to acquire. Has to be a muptiple of 2048. The module will enter STOP mode after collecting all samples. If zero, the module will stay in FREERUNNING mode. Defaults to 0.

workmode_simulation(samples: list, sample_size: SampleSize, noise_rms: float, period: int)

Enters SIMULATION workmode. In this mode preconfigured set of samples will be sent periodically. Additional noise can be added to the samples.

Args:

samples (list):

List of samples that will be sent by the module.

sample_size (SampleSize):

Size of the samples.

noise_rms (float):

RMS of noise that will be added to the output samples.

period (int):

Period in seconds

workmode_stop()

Enters STOP workmode. Stops data acquisition.

workmode_trigger_input(samples_count, delay)

Starts TRIGGER_INPUT workmode. The module will start sampling after trigger event with defined delay. After collecting defined number of samples and sending them to the host, it will wait for next trigger event.

Args:

samples_count (int):

Total number of samples to acquire after single trigger event. Has to be a multiple of 2048.

delay (float):

Delay between trigger event and start of sampling [in seconds].

workmode_trigger_output(samples_count, period, delay)

Starts TRIGGER_OUTPUT workmode. The module will start sampling and generate trigger event after defined delay. After collecting defined number of samples and sending them to the host, it will generate next trigger with defined period.

Args:

samples_count (int):

Number of samples to acquire after single trigger output event. Has to be a multiple of 2048.

period (float):

Period of trigger events in seconds. Keep in mind that real period can be longer due to limitations of UART interface.

delay (float):

Delay between starting of data acquisition and trigger event [in seconds]

class ams_messages.MessageOutputData(*args, **kwargs)

Message with samples measured by the ADC.

data: [<class 'list'>, None] = None

Will contain list of raw samples

voltages: [<class 'list'>, None] = None

Will contain numpy array of measured voltages

class ams_messages.MessageStatus(*args, **kwargs)

Will be sent periodically by the board.

Instances of this class will have the following members:

Reset_flag:

Indicates whether board was reset since last clearing of this flag.

Configuration_unsaved:

Indicates wheter some configuration was changed and is not written to non-volatile memory

Sampling_state:

Set if ADC is armed

Processing_state:

Set if there are unprocessed data in the processing pipeline

Data_overflow_counter:

Incremented each time the module drops data in the processing pipeline or transmission block

Messages_received_counter:

Incremented with each correctly received message

Detector_temperature:

Temperature of the detector in mK

Temperature_ok:

Set when temperature of the detector is stable and close to requested

class ams_messages.AbstractWorkmode

Usefull to pass to read_one_message method to filter only messages with workmode settings.

class ams_messages.MessageWorkmodeFreerunning(*args, **kwargs)

Describes freerunning workmode.

Attributes:

samples_count:

Number of samples to acquire. If zero - acquisition will never stop.

class ams_messages.MessageWorkmodeStop(*args, **kwargs)

Describes stop workmode

class ams_messages.MessageWorkmodeTriggerInput(*args, **kwargs)

Describes trigger input workmode.

Attributes:

samples_count:

Number of samples to acquire with single trigger event.

delay:

Delay between trigger event and start of acquisition, in microseconds.

edge:

Edge of the event. Only rising edge (=1) is supported.

class ams_messages.MessageWorkmodeTriggerOutput(*args, **kwargs)

Describes trigger output workmode.

Attributes:

samples_count:

Number of samples to acquire with single trigger event.

delay:

Delay between start of acquisition and trigger event, in microseconds.

period:

Period of the trigger event, in microseconds.

edge:

Edge of the event. Only rising edge (=1) is supported.