Skip to content

Commit 50ed866

Browse files
InfarhInfarh
committed
Добавлен трекинг улучшений для MathCore.HackRF с предложениями по оптимизации API и упрощению потоковой обработки RX/TX
1 parent 8bd0320 commit 50ed866

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

‎docs/MathCore.HackRF-Agent-Tracking-Improvements.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Трекинг улучшений для MathCore.HackRF (сессия кодового агента)
2+
3+
## Метаданные сессии
4+
- Репозиторий-источник наблюдений: MathCore.DSP
5+
- Целевая библиотека для доработок: MathCore.HackRF
6+
- Контекст задачи: реализация end-to-end FM RX конвейера (HackRF One -> DSP -> NAudio)
7+
- Статус документа: рабочий трекинг для переноса в проект MathCore.HackRF
8+
9+
## Принцип отбора предложений
10+
- В документ включены только улучшения, которые реально уменьшат объем кода, повысят выразительность API или упростят потоковую обработку RX/TX.
11+
- Предложения привязаны к практическим проблемам, замеченным во время реализации FM-демо.
12+
- Идеи «ради улучшения» без прикладной пользы не включались.
13+
14+
## Наблюдаемые проблемы в текущем использовании API
15+
1. Инициализация RX-сценария многословна: ручной `Initialize/Shutdown`, создание `Device`, набор параметров, запуск сессии, ручная синхронизация завершения.
16+
2. Для типового кейса захвата блока IQ нужен дополнительный инфраструктурный код (буфер, счетчики, событие, таймаут).
17+
3. Сигнатура блочного callback удобна для производительности, но менее удобна для прикладных сценариев и обучения.
18+
4. Потоковая обработка хорошо покрыта для базовой RX-сессии, но не хватает high-level DSL для сборки конвейеров RX/TX и их композиции.
19+
5. Нет симметричного «богатого» набора high-level инструментов для TX-сценариев, аналогичных удобству RX-пайплайна.
20+
6. Не хватает встроенных средств диагностики потока на уровне библиотеки устройства (быстрые метрики, мониторинг очереди, удобный health snapshot).
21+
22+
## Предложения по улучшению
23+
24+
### HACKRF-001. High-level RX Capture API для сокращения шаблонного кода
25+
- Идея: добавить метод уровня `CaptureIqAsync(...)` с возвратом готового блока `byte[]` или `Memory<byte>`.
26+
- Минимальный интерфейс: параметры частоты, sample rate, gain, duration или samples count, timeout, cancellation token.
27+
- Польза: резко сокращает шаблонный код захвата в прикладных приложениях и туториалах.
28+
- Приоритет: высокий.
29+
- Риск: низкий.
30+
- Критерий готовности: типовой сценарий «захватить 1 сек IQ» выполняется 1-2 строками кода.
31+
32+
### HACKRF-002. Конфигурационный объект профиля устройства
33+
- Идея: добавить неизменяемый профиль `RxProfile`/`TxProfile` и метод `ApplyProfile(...)`.
34+
- Содержимое профиля: частота, sample rate, bandwidth, LNA/VGA, antenna power, queue policy.
35+
- Польза: код становится более выразительным и повторно используемым.
36+
- Приоритет: высокий.
37+
- Риск: низкий.
38+
- Критерий готовности: настройки устройства передаются одним объектом и легко логируются.
39+
40+
### HACKRF-003. Builder/Fluent API для запуска сессии
41+
- Идея: добавить fluent-конструктор вроде `device.Rx().WithProfile(...).WithQueue(...).OnError(...).Start(...)`.
42+
- Польза: более читаемый код запуска SDR-сценариев, меньше «технического шума».
43+
- Приоритет: средний.
44+
- Риск: средний.
45+
- Критерий готовности: код запуска RX/TX сессии читается как декларация конвейера.
46+
47+
### HACKRF-004. Async-stream API поверх callback (IAsyncEnumerable)
48+
- Идея: дать адаптер `GetRxBlocksAsync(...)` с `IAsyncEnumerable<RxBlock>`.
49+
- Польза: естественная интеграция с современным async/await кодом и backpressure-подходом.
50+
- Приоритет: высокий.
51+
- Риск: средний.
52+
- Критерий готовности: блоки RX можно обрабатывать через `await foreach` без ручной синхронизации.
53+
54+
### HACKRF-005. Расширенный набор TX-инструментов
55+
- Идея: добавить high-level TX pipeline: очередь кадров, pacing, underrun strategy presets, удобные producer adapters.
56+
- Польза: RX и TX становятся симметричными по удобству API, проще строить ретрансляцию и генераторы.
57+
- Приоритет: высокий.
58+
- Риск: средний.
59+
- Критерий готовности: типовой TX-сценарий запускается без ручного управления низкоуровневыми деталями.
60+
61+
### HACKRF-006. Готовые «канальные» адаптеры для RX->TX relay
62+
- Идея: добавить встроенные адаптеры relay с настраиваемой буферизацией, jitter control и телеметрией.
63+
- Польза: быстрее собирать устойчивые realtime-связки между устройствами.
64+
- Приоритет: средний.
65+
- Риск: средний.
66+
- Критерий готовности: relay-сценарий стартует через один конфиг и предоставляет метрики качества.
67+
68+
### HACKRF-007. Встроенный health snapshot и диагностические счетчики
69+
- Идея: расширить статистику сессий единым `GetHealthSnapshot()`.
70+
- Метрики: drop/underrun rate, queue utilization, callback latency p50/p95/p99, throughput, last errors.
71+
- Польза: упрощает отладку и эксплуатацию без внешней телеметрии.
72+
- Приоритет: высокий.
73+
- Риск: низкий.
74+
- Критерий готовности: пользователь получает компактный технический снимок состояния сессии одной командой.
75+
76+
### HACKRF-008. Удобные безопасные preset-политики
77+
- Идея: добавить предустановки (`RxPreset.BroadcastFm`, `RxPreset.WidebandScan` и т.д.) с валидными диапазонами параметров.
78+
- Польза: проще старт для студентов и новых пользователей, меньше конфигурационных ошибок.
79+
- Приоритет: средний.
80+
- Риск: низкий.
81+
- Критерий готовности: можно запустить FM RX одной preset-конфигурацией и точечными override.
82+
83+
### HACKRF-009. Улучшение XML-документации high-level API
84+
- Идея: для каждого нового high-level метода добавить полноценный блок `remarks` с рабочим примером.
85+
- Польза: снижается порог входа, быстрее интеграция в прикладные проекты.
86+
- Приоритет: высокий.
87+
- Риск: низкий.
88+
- Критерий готовности: ключевые методы имеют примеры end-to-end (RX capture, async stream, TX send).
89+
90+
## Что не предлагается специально
91+
- Низкоуровневые изменения драйвера без явной прикладной выгоды в пользовательском API.
92+
- Добавление сложных абстракций, если они не сокращают код и не улучшают читаемость типовых сценариев.
93+
94+
## Бэклог для переноса в MathCore.HackRF
95+
- [ ] HACKRF-001
96+
- [ ] HACKRF-002
97+
- [ ] HACKRF-003
98+
- [ ] HACKRF-004
99+
- [ ] HACKRF-005
100+
- [ ] HACKRF-006
101+
- [ ] HACKRF-007
102+
- [ ] HACKRF-008
103+
- [ ] HACKRF-009
104+
105+
## Рекомендуемый порядок реализации
106+
1. HACKRF-001
107+
2. HACKRF-002
108+
3. HACKRF-004
109+
4. HACKRF-007
110+
5. HACKRF-005
111+
6. HACKRF-003
112+
7. HACKRF-006
113+
8. HACKRF-008
114+
9. HACKRF-009
115+
116+
## Короткий вывод
117+
Предложения есть. Они практичные и напрямую направлены на три цели: более лаконичный код, более выразительный API и более удобную потоковую обработку как для RX, так и для TX.

0 commit comments

Comments
 (0)