194 lines
28 KiB
Python
194 lines
28 KiB
Python
"""PWM envelope on up to three independent logic channels."""
|
|
import sigrokdecode as srd
|
|
from common.setgui_decoders.pwm_waveform import PwmChannel, NpcChannel, PhaseAnalysis # Общие ядра восстанавливают два уровня, стойку NPC и согласованный трёхфазный вектор без зависимости от интерфейса.
|
|
|
|
|
|
def short_frequency(value): # Компактная подпись сохраняет обе частоты даже при небольшой ширине электрического периода на экране.
|
|
if value is None: # Отсутствующее измерение не должно выглядеть как нулевая частота.
|
|
return '?' # Короткий знак оставляет место второму, доступному измерению.
|
|
scale, unit = (1000000, 'MHz') if value >= 1000000 else (1000, 'kHz') if value >= 1000 else (1, 'Hz') # Приставки СИ переводят герцы в кило- и мегагерцы без изменения физического значения.
|
|
return '{:.3g}{}'.format(value / scale, unit) # Три значащие цифры достаточны для обзорной подписи; полная точность остаётся в первой строке аннотации.
|
|
|
|
|
|
class Decoder(srd.Decoder):
|
|
api_version = 3
|
|
id = 'pwm_waveform'
|
|
name = 'PWM waveform'
|
|
longname = 'PWM waveform / sine reconstruction'
|
|
desc = 'Reconstructs normalized waveforms from PWM duty on 1-3 channels.'
|
|
license = 'gplv2+'
|
|
inputs = ['logic']
|
|
outputs = []
|
|
tags = ['Clock/timing', 'Util']
|
|
channels = ({'id': 'a', 'name': 'PWM A', 'desc': 'First PWM input'},)
|
|
optional_channels = (
|
|
{'id': 'b', 'name': 'PWM B', 'desc': 'Second PWM input'},
|
|
{'id': 'c', 'name': 'PWM C', 'desc': 'Third PWM input'},
|
|
*tuple({'id': ch + str(gate), 'name': ch.upper() + str(gate), 'desc': 'NPC ' + ch.upper() + ' S' + str(gate) + ' (top to bottom)'} for ch in 'abc' for gate in (2, 3, 4)), # Прежние A/B/C становятся S1 фаз; дополнительные девять входов завершают 12 затворов NPC, сохраняя совместимость записей DSL.
|
|
)
|
|
options = tuple(
|
|
{'id': 'active_' + ch, 'desc': 'PWM ' + ch.upper() + ' active level',
|
|
'default': 'high', 'values': ('high', 'low')} for ch in 'abc'
|
|
) + (
|
|
{'id': 'input_mode', 'desc': 'PWM topology / Схема ШИМ', 'default': 'two-level', 'values': ('two-level', 'npc-three-level')}, # NPC использует четыре затвора на фазу, обычный режим сохраняет один вход на фазу.
|
|
{'id': 'waveform_mode', 'desc': 'Waveform / Форма сигнала', 'default': 'envelope', 'values': ('envelope', 'switching')}, # Envelope выводит средние уровни, switching — оценку коммутационного напряжения непосредственно по состояниям затворов.
|
|
{'id': 'show_theta', 'desc': 'Theta ABC 0-360 deg / Угол вектора', 'default': 'no', 'values': ('no', 'yes')}, # θ является отдельной опцией и требует всех трёх восстановленных фаз.
|
|
{'id': 'show_carrier', 'desc': 'Calculated triangle / Расчётная несущая', 'default': 'no', 'values': ('no', 'yes')}, # Треугольник восстанавливается по периодам и не выдаётся за измеренную аналоговую несущую.
|
|
{'id': 'show_phase_angles', 'desc': 'Phase angles AB BC CA / Углы между фазами', 'default': 'no', 'values': ('no', 'yes')}, # Знаковые сдвиги фаз измеряются по одноимённым пересечениям огибающих.
|
|
{'id': 'waveform_layout', 'desc': 'Waveform layout / Вид графиков', 'default': 'split', 'values': ('split', 'combined')}, # Split сохраняет отдельную область каждого входа; combined совмещает цветные кривые на общей шкале −1…+1.
|
|
{'id': 'carrier_hz', 'desc': 'Carrier Hz (0 = edge-to-edge)', 'default': 0},
|
|
{'id': 'smoothing_ms', 'desc': 'Low-pass time constant (ms, 0 = off)', 'default': 0.0},
|
|
)
|
|
annotations = (
|
|
('wave-a', 'Wave A'), ('wave-b', 'Wave B'), ('wave-c', 'Wave C'),
|
|
('duty-a', 'Duty A'), ('duty-b', 'Duty B'), ('duty-c', 'Duty C'),
|
|
('frequency-a', 'PWM carrier / field A'), ('frequency-b', 'PWM carrier / field B'), ('frequency-c', 'PWM carrier / field C'), # Индексы 6–8 дополняют прежние аннотации, сохраняя контракт графических строк 0–2.
|
|
('theta', 'Theta ABC (deg)'), ('carrier', 'Calculated carrier'), ('phase-angles', 'Phase lag (deg)'), # Индексы 9–11 отделяют графические углы и несущую от числового измерения сдвигов.
|
|
('npc-unknown-a', 'NPC A unknown'), ('npc-unknown-b', 'NPC B unknown'), ('npc-unknown-c', 'NPC C unknown'), # Индексы 12–14 явно обозначают комбинации затворов, по которым напряжение не определяется.
|
|
)
|
|
annotation_rows = (
|
|
('wave_a', 'A: -1 .. +1', (0,)),
|
|
('wave_b', 'B: -1 .. +1', (1,)),
|
|
('wave_c', 'C: -1 .. +1', (2,)),
|
|
('duty_a', 'A duty / frequency', (3,)),
|
|
('duty_b', 'B duty / frequency', (4,)),
|
|
('duty_c', 'C duty / frequency', (5,)),
|
|
('frequency_a', 'A PWM carrier / field', (6,)), # Длинная аннотация охватывает полный период поля и показывает обе частоты канала A при обзорном масштабе.
|
|
('frequency_b', 'B PWM carrier / field', (7,)), # Независимый расчёт канала B сохраняет его собственную частоту и положение электрического периода.
|
|
('frequency_c', 'C PWM carrier / field', (8,)), # Для необязательного канала C строка заполняется только при фактическом подключении.
|
|
('wave_theta', 'Theta ABC: 0 .. 360 deg', (9,)), # Нормированный графический контракт переводится в электрические градусы подписью шкалы и числовыми аннотациями.
|
|
('wave_carrier', 'Calculated triangle / NPC pair', (10,)), # Одна общая строка показывает один треугольник для двух уровней или два смещённых треугольника NPC.
|
|
('phase_angles', 'Phase lag A->B / B->C / C->A (deg)', (11,)), # Положительное значение означает запаздывание второй указанной фазы.
|
|
('npc_unknown', 'NPC dead-time / unknown voltage', (12, 13, 14)), # Недопустимое состояние не маскируется фиктивным нулём коммутационного напряжения.
|
|
)
|
|
|
|
def __init__(self):
|
|
self.reset()
|
|
|
|
def reset(self):
|
|
self.samplerate = None
|
|
self.channels_state = {}
|
|
self._mode, self._npc = 'envelope', False # Старые сохранённые настройки продолжают открываться как обычная огибающая двухуровневого ШИМ.
|
|
self._show_theta = self._show_carrier = self._show_angles = False # Дополнительные расчётные строки включаются только явными опциями данного экземпляра.
|
|
self._phase_channels = {ch: (ch,) for ch in range(3)} # Прежняя нумерация A/B/C сохраняется для тестов, записей и обычного режима.
|
|
self._raw, self._theta_previous = {}, None # Координаты коммутаций и предыдущий θ принадлежат только текущему декодированию.
|
|
self._phase_analysis, self._last_pins = None, None # Согласование фаз и завершающий снимок не переносятся в следующую запись.
|
|
|
|
def metadata(self, key, value):
|
|
if key == srd.SRD_CONF_SAMPLERATE:
|
|
self.samplerate = value
|
|
|
|
def start(self):
|
|
self.out_ann = self.register(srd.OUTPUT_ANN)
|
|
|
|
def _update(self, pins):
|
|
self._last_pins = list(pins) # sigrok повторно использует свой кортеж; независимая копия нужна для корректного завершения окон.
|
|
for ch, state in self.channels_state.items():
|
|
inputs = [pins[index] for index in self._phase_channels[ch]] # В NPC одному восстановленному каналу соответствуют четыре физических входа.
|
|
level = state.state(inputs) if self._npc else (1 if bool(inputs[0]) == state.active_high else -1) # Двухуровневый уровень нормирован к ±1, а неопределённая комбинация NPC остаётся None.
|
|
if self._mode == 'switching' or self._npc: # Коммутационный график и предупреждения NPC используют ту же временную последовательность цифровых состояний.
|
|
self._switching(ch, level) # Неизвестные интервалы разрывают кривую и явно отмечаются отдельной аннотацией.
|
|
for event in state.update(self.samplenum, inputs if self._npc else inputs[0]): # Ядра получают собственный формат входа, сохраняя единый формат восстановленных результатов.
|
|
carrier = '{:.3f} Hz'.format(event['carrier_frequency']) if event['carrier_frequency'] is not None else 'unavailable' # Не подменяем измеренную несущую заданной частотой окна или устаревшим значением после исчезновения фронтов.
|
|
window = ' window={:.3f} Hz'.format(event['frequency']) if state.window else '' # Частота интегрирования обозначается отдельно и только в режиме заданной несущей.
|
|
label = 'D={:.3f}% PWM carrier={}{}'.format(event['duty'] * 100, carrier, window) # Подпись каждого периода явно связывает несущую с измеренными фронтами ШИМ.
|
|
if self._npc: # В NPC D является эквивалентным заполнением среднего уровня, а не временем включения одного ключа.
|
|
label = 'NPC mean={:+.6f} valid={:.3f}% PWM carrier={}{}'.format(2 * event['duty'] - 1, 100 * event['valid_fraction'], carrier, window) # Доля известного времени показывает влияние исключённых коммутационных пауз на оценку.
|
|
self.put(event['start'], event['end'], self.out_ann,
|
|
[3 + ch, [label, '{:.2f}%'.format(event['duty'] * 100)]])
|
|
field = event['field'] # Дополнительная строка появляется только после завершения полного электрического периода.
|
|
if field is not None: # Неполные периоды и постоянное заполнение не создают числового результата поля.
|
|
carrier = '{:.3f} Hz'.format(field['carrier_frequency']) if field['carrier_frequency'] is not None else 'unavailable' # Средняя несущая измеряется независимо от числа окон восстановления за период поля.
|
|
field_text = 'Field={:.3f} Hz'.format(field['frequency']) # Частота огибающей выражена в электрических герцах, без пересчёта в механические обороты.
|
|
carrier_short, field_short = short_frequency(field['carrier_frequency']), short_frequency(field['frequency']) # При обзорном масштабе приставки СИ позволяют одновременно прочитать несущую и поле.
|
|
self.put(field['start'], field['end'], self.out_ann, [6 + ch, ['PWM carrier={} {}'.format(carrier, field_text), 'PWM={} / {}'.format(carrier, field_text), 'PWM={} F={}'.format(carrier_short, field_short), '{}/{}'.format(carrier_short, field_short)]]) # Все варианты подписи сохраняют порядок «несущая / поле», включая самый короткий для узкого периода.
|
|
previous = event['previous']
|
|
if previous is not None and self._mode == 'envelope': # Переключение вида меняет только график; частоты и углы всегда рассчитываются по огибающим.
|
|
# Last label is the versioned native renderer contract.
|
|
self.put(previous[0], event['midpoint'], self.out_ann, [ch, [
|
|
'PWM {}: {:+.6f}'.format('ABC'[ch], event['value']),
|
|
'PWM1 {:.9f} {:.9f}'.format(previous[1], event['value'])]])
|
|
if self._show_carrier and ch == min(self.channels_state): # Общая расчётная несущая использует периоды первой подключённой фазы и не дублируется для B/C.
|
|
self._curve(10, event['start'], event['midpoint'], -1, 1, 'Calculated carrier') # Первая половина условного периода линейно поднимается от минимума к максимуму.
|
|
self._curve(10, event['midpoint'], event['end'], 1, -1, 'Calculated carrier') # Вторая половина завершает треугольник без накопления ошибки времени.
|
|
if self._phase_analysis is not None: # При выключенных угловых опциях согласование фаз не тратит время на длинных записях.
|
|
if event['previous'] is None: # Новая история огибающей означает начало записи либо разрыв неизвестного состояния NPC.
|
|
self._theta_previous = None # График θ не соединяется через интервал, где одна из фаз не была восстановлена.
|
|
vector = self._phase_analysis.add(ch, event) # Точки всех фаз интерполируются к общему наблюдавшемуся времени.
|
|
if self._show_theta and vector is not None: # Начальная неполная тройка фаз не создаёт угла пространственного вектора.
|
|
self._theta(vector) # Переход 360→0 разрывается на границе, сохраняя правильную пилообразную форму.
|
|
if self._show_angles and event['field'] is not None and ch == min(self.channels_state): # Один полный период опорной фазы задаёт интервал числового результата всех доступных пар.
|
|
angles = self._phase_analysis.differences(event['midpoint']) # Сдвиг вычисляется из фактических фазовых часов, а не из заданных 120 градусов.
|
|
if angles: # Устаревшие или ещё не измеренные пары не должны получать числовую подпись.
|
|
labels = [' '.join('{}={:+.3f} deg'.format(pair, value) for pair, value in angles.items()), ' / '.join('{:+.1f}'.format(value) for value in angles.values())] # Полная подпись сохраняет направление каждой пары; короткая следует порядку заголовка.
|
|
self.put(event['field']['start'], event['field']['end'], self.out_ann, [11, labels]) # Значения доступны на временной диаграмме, в таблице результатов и при экспорте.
|
|
|
|
def _curve(self, kind, start, end, a, b, label): # Все расчётные кривые используют существующий индекс экстремумов и контракт PWM1.
|
|
start, end = round(start), round(end) # Целые номера отсчётов требуются API аннотаций sigrok.
|
|
if end > start: # Пустой интервал не может быть сегментом индексированной кривой.
|
|
self.put(start, end, self.out_ann, [kind, [label, 'PWM1 {:.9f} {:.9f}'.format(max(-1, min(1, a)), max(-1, min(1, b)))]]) # Ограничение защищает нативный контракт нормированных значений от машинного округления.
|
|
|
|
def _switching(self, ch, level): # Импульсная осциллограмма строится по сменам состояний без выдуманных аналоговых выбросов.
|
|
previous = self._raw.get(ch) # Предыдущее состояние определяет уровень между двумя цифровыми событиями.
|
|
if previous is not None and self.samplenum > previous[0]: # Совпадающие события не создают отрицательную или нулевую длительность.
|
|
start, old = previous # Начало интервала и уровень относятся только к выбранной фазе.
|
|
if old is None: # Ни одна из трёх штатных комбинаций NPC не определяла напряжение на этом участке.
|
|
self.put(start, self.samplenum, self.out_ann, [12 + ch, ['NPC {}: unknown voltage / dead-time'.format('ABC'[ch]), 'unknown']]) # Неизвестное время остаётся видимым даже при выборе огибающей.
|
|
elif self._mode == 'switching': # Основная графическая строка может показывать коммутации вместо средней огибающей.
|
|
corner = self.samplenum - 1 if level is not None and level != old else self.samplenum # Фронт занимает один отсчёт, поскольку аналоговая скорость переключения не измерена.
|
|
self._curve(ch, start, max(start, corner), old, old, 'Switching {}: {:+d}'.format('ABC'[ch], old)) # Постоянный уровень сохраняет точную длительность между событиями захвата.
|
|
if level is not None and level != old: # Через неизвестный уровень не проводится выдуманный соединительный фронт.
|
|
self._curve(ch, max(start, corner), self.samplenum, old, level, 'Switching {} edge'.format('ABC'[ch])) # Нормированный переход отображается только в пределах разрешения записи.
|
|
self._raw[ch] = (self.samplenum, level) # Следующее событие продолжит график только от текущего достоверного состояния.
|
|
|
|
def _theta(self, vector): # Угол общего вектора выводится отдельно от углов между фазами.
|
|
sample, angle = vector['sample'], vector['theta'] # Координата соответствует единому времени A/B/C после интерполяции.
|
|
previous = self._theta_previous # Предыдущая точка нужна для графика и обнаружения циклического перехода через нуль.
|
|
if angle is not None and previous is not None: # Нулевая амплитуда или разрыв не соединяются произвольным направлением вектора.
|
|
start, old = previous # Угол выражен в градусах до преобразования в нативную шкалу −1…+1.
|
|
if abs(angle - old) <= 180: # Обычный участок не пересекает границу электрического оборота.
|
|
self._curve(9, start, sample, old / 180 - 1, angle / 180 - 1, 'Theta={:.3f} deg'.format(angle)) # Подпись содержит физическую величину, а renderer получает нормированные концы.
|
|
else: # Циклическое значение должно сбрасываться вертикально, а не проходить ложные промежуточные углы.
|
|
forward = old > angle # Направление определяет границу +360→0 либо 0→+360.
|
|
delta = angle - old + (360 if forward else -360) # Кратчайшее изменение восстанавливает непрерывный угол на одном малом интервале.
|
|
boundary = start + ((360 if forward else 0) - old) * (sample - start) / delta # Линейная интерполяция определяет момент перехода через границу оборота.
|
|
self._curve(9, start, boundary, old / 180 - 1, 1 if forward else -1, 'Theta wrap') # Первая часть заканчивается на достигнутой границе шкалы.
|
|
self._curve(9, boundary, sample, -1 if forward else 1, angle / 180 - 1, 'Theta={:.3f} deg'.format(angle)) # Вторая часть начинается с противоположного края без ложной диагонали.
|
|
self._theta_previous = (sample, angle) if angle is not None else None # Неопределённое направление явно разрывает историю угла.
|
|
|
|
def decode(self):
|
|
if not self.samplerate:
|
|
raise ValueError('Cannot decode without samplerate.')
|
|
self._npc = self.options.get('input_mode', 'two-level') == 'npc-three-level' # Отсутствующая опция старой записи сохраняет прежнюю схему одного входа на фазу.
|
|
self._mode = self.options.get('waveform_mode', 'envelope') # Вид кривой не меняет численные измерения заполнения, частот и углов.
|
|
self._show_theta, self._show_carrier, self._show_angles = (self.options.get(key, 'no') == 'yes' for key in ('show_theta', 'show_carrier', 'show_phase_angles')) # Все дополнительные расчёты включаются независимо в настройках одного анализатора.
|
|
self._phase_channels = {ch: (ch, 3 + ch * 3, 4 + ch * 3, 5 + ch * 3) if self._npc else (ch,) for ch in range(3)} # S1 сохраняет прежние индексы A/B/C, а S2…S4 последовательно занимают девять новых входов.
|
|
for ch, indices in self._phase_channels.items(): # Неполная стойка NPC не должна трактоваться как неподключённый или нулевой уровень фазы.
|
|
connected = [self.has_channel(index) for index in indices] # Наличие проверяется для каждого физического затвора отдельно.
|
|
if any(connected) and not all(connected): # Каждая используемая фаза NPC требует всех четырёх управляющих сигналов.
|
|
raise ValueError('NPC phase {} requires all four gates S1..S4 (top to bottom).'.format('ABC'[ch])) # Понятная ошибка предотвращает неверную реконструкцию из неполных входов.
|
|
channel_class = NpcChannel if self._npc else PwmChannel # Один и тот же экземпляр декодера поддерживает две схемы без отдельного анализатора.
|
|
self.channels_state = {ch: channel_class(self.samplerate, # Тип канала определяет преобразование цифровых состояний в средний уровень.
|
|
self.options['active_' + 'abc'[ch]] == 'high',
|
|
self.options['carrier_hz'], self.options['smoothing_ms'])
|
|
for ch in range(3) if self.has_channel(ch)}
|
|
if self._show_theta and len(self.channels_state) != 3: # Для угла пространственного вектора нужны три реальные огибающие, а не предположение о симметричной нагрузке.
|
|
raise ValueError('Theta requires all three phases A/B/C.') # Отсутствующая фаза не достраивается искусственной синусоидой.
|
|
if self._show_angles and len(self.channels_state) < 2: # Межфазный угол невозможно измерить по одному подключённому входу.
|
|
raise ValueError('Phase angles require at least two phases.') # В двухфазной записи рассчитываются только доступные пары.
|
|
self._phase_analysis = PhaseAnalysis(self.samplerate) if self._show_theta or self._show_angles else None # Выключенные опции сохраняют прежнюю стоимость обработки обычного ШИМ.
|
|
pins = list(self.wait({}))
|
|
self._update(pins)
|
|
while True:
|
|
conditions = [{index: 'e'} for ch in self.channels_state for index in self._phase_channels[ch]] # В NPC пробуждение вызывается каждым затвором, включая короткие dead-time и запрещённые комбинации.
|
|
boundaries = [s.next_boundary() for s in self.channels_state.values()
|
|
if s.next_boundary() is not None]
|
|
if boundaries:
|
|
conditions.append({'skip': max(1, min(boundaries) - self.samplenum)})
|
|
pins = list(self.wait(conditions))
|
|
self._update(pins)
|
|
|
|
def end(self):
|
|
if self.channels_state and self._last_pins is not None: # Последний снимок содержит все двенадцать затворов NPC либо прежние входы A/B/C.
|
|
self._update(self._last_pins) # Завершаются только полные окна и постоянные участки; отсутствующие фронты и неполные периоды не выдумываются.
|