88 lines
15 KiB
Python
88 lines
15 KiB
Python
"""Восстановление сигма-дельта потока DATA/CLK с децимацией sinc1, sinc2 или sinc3.""" # Адаптер использует API sigrok версии 3 и переносимое ядро фильтра.
|
|
import math # Проверка конечности исключает NaN и бесконечности в масштабе напряжения и частоте захвата.
|
|
import sigrokdecode as srd # DSView предоставляет каналы, ожидание фронтов и вывод аннотаций.
|
|
from common.setgui_decoders.sigma_delta import SigmaDeltaFilter # Установщик переносит каноническое ядро в закрытый пакет DSView.
|
|
|
|
|
|
class Decoder(srd.Decoder): # Один экземпляр анализирует один однобитный модулятор с отдельной тактовой линией.
|
|
api_version = 3 # Этот контракт поддерживается штатным libsigrokdecode DSView.
|
|
id = 'sigma_delta' # Постоянный идентификатор используется установщиком, меню и сохранёнными сессиями.
|
|
name = 'Sigma-delta' # Короткое имя доступно в штатном поиске декодеров DSView.
|
|
longname = 'Sigma-delta / PDM with clock' # Полное имя уточняет формат однобитного потока с внешним CLK.
|
|
desc = 'Reconstructs a clocked 1-bit sigma-delta stream using sinc1/2/3 decimation.' # Описание отличает вход модулятора от готовых слов АЦП по SPI.
|
|
license = 'gplv2+' # Лицензия согласована с соседними адаптерами sigrok.
|
|
inputs = ['logic'] # Декодер подключается непосредственно к цифровым линиям захвата.
|
|
outputs = ['sigma_delta'] # Структурированные отсчёты могут использоваться последующим Python-декодером.
|
|
tags = ['Util'] # Общая категория поддерживается стандартными установками sigrok.
|
|
channels = ( # Оба сигнала обязательны, поскольку плотность единиц измеряется по тактам, а не длительности импульсов.
|
|
{'id': 'data', 'name': 'DATA', 'desc': 'Sigma-delta bit stream'}, # Первый вход содержит уровень однобитного модулятора.
|
|
{'id': 'clk', 'name': 'CLK', 'desc': 'Modulator clock'}, # Второй вход определяет моменты приёма DATA.
|
|
) # Отдельные экземпляры декодера позволяют анализировать несколько модуляторов с общим CLK.
|
|
options = ( # Настройки сохраняются обычным механизмом DSView без внешних файлов.
|
|
{'id': 'clock_edge', 'desc': 'Sampling edge', 'default': 'rising', 'values': ('rising', 'falling')}, # Фронт выбирается согласно документации подключённого модулятора.
|
|
{'id': 'filter', 'desc': 'Decimation filter', 'default': 'sinc3', 'values': ('sinc1', 'sinc2', 'sinc3')}, # Более высокий порядок сильнее подавляет высокочастотную составляющую потока.
|
|
{'id': 'decimation', 'desc': 'Decimation / OSR (clock cycles)', 'default': 256}, # R входных тактов формируют один выходной отсчёт; допустимы значения 1–65536.
|
|
{'id': 'invert', 'desc': 'Invert DATA', 'default': 'no', 'values': ('no', 'yes')}, # Инверсия меняет полярность до прохождения фильтра.
|
|
{'id': 'full_scale', 'desc': 'Bipolar full-scale input (V)', 'default': 1.0}, # Это идеальный вход при 100 процентах единиц, а не обязательно напряжение питания или опоры.
|
|
) # По умолчанию напряжение численно совпадает с нормированной амплитудой при масштабе ±1 В.
|
|
annotations = ( # Числовые строки работают и в standalone DSView без специальной нативной отрисовки.
|
|
('value', 'Normalized value'), # Индекс ноль показывает восстановленную биполярную амплитуду.
|
|
('voltage', 'Input voltage'), # Индекс один показывает амплитуду с заданным физическим масштабом.
|
|
('density', 'Filtered one density'), # Индекс два даёт фильтрованную плотность единиц для диагностики полярности.
|
|
('rate', 'Clock / output rate'), # Индекс три связывает частоту захваченного CLK с выходной частотой децимации.
|
|
) # Аннотации создаются на каждый установившийся полный выходной блок.
|
|
annotation_rows = ( # Каждая величина имеет независимую строку в таблице результатов.
|
|
('value', 'Value: -1 .. +1', (0,)), # Диапазон соответствует идеальным крайним плотностям ноль и единица.
|
|
('voltage', 'Input voltage', (1,)), # Размерность напряжения указана и в подписи каждого отсчёта.
|
|
('density', 'Filtered density', (2,)), # Для sinc2/3 это взвешенная плотность, а не простое число единиц последнего блока.
|
|
('rate', 'CLK / output rate', (3,)), # Частота доступна только при наличии метаданных частоты захвата.
|
|
) # Порядок строк сохраняет совпадение с индексами классов аннотаций.
|
|
|
|
def __init__(self): # DSView создаёт объект до передачи параметров и метаданных.
|
|
self.reset() # Новый анализ не наследует состояние предыдущего захвата.
|
|
|
|
def reset(self): # Частота захвата может отсутствовать: амплитуду всё равно можно восстановить по CLK.
|
|
self.samplerate = None # Пока метаданные не получены, частоты в герцах не вычисляются.
|
|
|
|
def metadata(self, key, value): # Частота захвата приходит отдельным сообщением движка sigrok.
|
|
if key == srd.SRD_CONF_SAMPLERATE: # Остальные метаданные не относятся к переводу номеров отсчётов в секунды.
|
|
if not math.isfinite(value) or value <= 0: # Частота должна быть конечной положительной величиной в отсчётах в секунду.
|
|
raise ValueError('Samplerate must be finite and positive.') # Некорректные метаданные не должны порождать деление на ноль.
|
|
self.samplerate = value # Частота используется только для измерений CLK и выходного потока.
|
|
|
|
def start(self): # Выходы регистрируются после создания объекта и до вызова decode.
|
|
self.out_ann = self.register(srd.OUTPUT_ANN) # Аннотации остаются доступны обычному окну результатов DSView.
|
|
self.out_python = self.register(srd.OUTPUT_PYTHON) # Числа передаются без потерь от форматирования текстовых подписей.
|
|
|
|
def decode(self): # Ожидание только выбранных фронтов уменьшает число обращений к движку захвата.
|
|
if not self.has_channel(0) or not self.has_channel(1): # Достоверное восстановление требует и DATA, и тактовой линии.
|
|
raise ValueError('Both DATA and CLK channels are required.') # Служебное значение отсутствующего входа нельзя считать реальными битами.
|
|
filters = {'sinc1': 1, 'sinc2': 2, 'sinc3': 3} # Отображение фиксирует число каскадов без разбора произвольной строки.
|
|
if self.options['filter'] not in filters or self.options['clock_edge'] not in ('rising', 'falling') or self.options['invert'] not in ('no', 'yes'): # Повреждённая сохранённая сессия должна явно сообщать о неверной настройке.
|
|
raise ValueError('Invalid filter, sampling edge or DATA polarity.') # Не подставляем другой режим фильтрации незаметно для пользователя.
|
|
state = SigmaDeltaFilter(self.options['decimation'], filters[self.options['filter']], self.options['invert'] == 'yes') # Ядро проверяет целочисленный OSR и сбрасывает память CIC.
|
|
full_scale = float(self.options['full_scale']) # Физический масштаб задаётся положительным напряжением идеального верхнего предела.
|
|
if not math.isfinite(full_scale) or full_scale <= 0: # Нулевой и неконечный масштаб делают физический результат бессмысленным.
|
|
raise ValueError('Bipolar full-scale input must be finite and positive.') # Отрицательная полярность задаётся отдельной опцией инверсии DATA.
|
|
edge = 'r' if self.options['clock_edge'] == 'rising' else 'f' # API sigrok обозначает нарастающий и спадающий фронты буквами r и f.
|
|
block_start, previous_sample = None, None # Границы блока и предыдущий такт нужны для аннотаций и измерения частоты.
|
|
while True: # Завершение захвата останавливает wait штатным механизмом sigrok без дополнения неполного блока.
|
|
pins = list(self.wait({1: edge})) # Копируем уровни выбранного фронта в список: DSView повторно заполняет внутренний tuple и требует освобождать его до следующего wait.
|
|
sample = self.samplenum # Номер отсчёта задаёт фактически наблюдавшееся время фронта.
|
|
if state.phase == 0: # Первый бит очередного блока определяет его начало независимо от прогрева фильтра.
|
|
block_start = sample # Начальный уровень записи до первого фронта не считается битом.
|
|
event = state.feed(pins[0]) # В фильтр поступает именно дискретный уровень DATA, без интегрирования ширины импульса.
|
|
if event is not None: # Первые N минус один блоков и неполные окна намеренно не создают результата.
|
|
intervals = state.decimation - 1 # Между R захваченными фронтами находится R минус один полный период CLK.
|
|
elapsed = sample - block_start if intervals else sample - previous_sample if previous_sample is not None else 0 # При R=1 частота измеряется между соседними выходными отсчётами.
|
|
clock = self.samplerate * (intervals or 1) / elapsed if self.samplerate and elapsed > 0 else None # Начальный одиночный фронт не позволяет достоверно измерить частоту.
|
|
event.update(voltage=event['value'] * full_scale, clock_hz=clock, output_hz=clock / state.decimation if clock is not None else None) # Напряжение и частота вычисляются из фильтрованной амплитуды и захваченного CLK.
|
|
event.update(decimation=state.decimation, order=state.order) # Структурированный результат содержит параметры для однозначной интерпретации кода.
|
|
self.put(block_start, sample, self.out_ann, [0, ['Value={:+.6f} code={}/{}'.format(event['value'], event['code'], event['gain']), '{:+.6f}'.format(event['value'])]]) # Точная шкала кода явно показывает усиление R**N.
|
|
self.put(block_start, sample, self.out_ann, [1, ['Input={:+.9g} V'.format(event['voltage']), '{:+.6g} V'.format(event['voltage'])]]) # Физическое значение сохраняет знак биполярного модулятора.
|
|
self.put(block_start, sample, self.out_ann, [2, ['Filtered ones={:.6f}%'.format(event['density'] * 100), '{:.3f}%'.format(event['density'] * 100)]]) # Множитель сто переводит долю единиц в проценты.
|
|
if clock is not None: # Без частоты захвата вывод амплитуды продолжается, а строка герц остаётся пустой.
|
|
self.put(block_start, sample, self.out_ann, [3, ['CLK={:.9g} Hz output={:.9g} Hz'.format(clock, event['output_hz'])]]) # Частота децимации равна частоте CLK, делённой на OSR.
|
|
self.put(block_start, sample, self.out_python, ['SAMPLE', event]) # Следующий декодер получает один пакет на каждый действительный результат фильтра.
|
|
previous_sample = sample # Запоминаем предыдущий реальный фронт даже во время начального установления.
|