﻿# Workstation4AD3S

Настольное Java-приложение (UI на FlatLaf) для разработки, отладки, программирования
и тестирования микросхемы преобразователя угол→код **5400ТР065А-022**
(АО «Дизайн Центр «Союз»»). Приложение подключается к микросхеме через
**ESP32-S3 мост** по USB (виртуальный COM-порт) и предоставляет графический
интерфейс для чтения/записи регистров, просмотра графиков, прошивки OTP-памяти,
запуска ассемблерных программ на внутренних RISC-процессорах чипа и других операций.

Прошивка моста (ESP-IDF, C++): <https://github.com/DCsoyuz/ad3s/tree/main/ad3s_prog_esp32>

---

## Запуск

### Windows

Дважды кликните на `Workstation4ad3s-X.X.X.bat`

### Linux / macOS

```bash
chmod +x Workstation4ad3s-X.X.X.sh
./Workstation4ad3s-X.X.X.sh
```

Скрипт автоматически ищет Java и запускает JAR. Если Java не найдена —
появится сообщение с инструкцией (см. раздел «Установка Java» ниже).

### Командная строка

```bash
java -jar Workstation4ad3s-X.X.X.jar               # обычный запуск
java -jar Workstation4ad3s-X.X.X.jar --restore        # сбросить раскладку окон
```

- `--restore` — удаляет сохранённую раскладку окон, при следующем запуске
  панели вернутся к расположению по умолчанию.

---

## Сборка и отладка из исходников (IntelliJ IDEA)

Если нужно запустить приложение из исходников (например, для отладки), удобнее всего использовать бесплатную **IntelliJ IDEA Community Edition**.

> **Важно про версию IDEA.** В последних версиях IntelliJ IDEA (2025.3 и новее) на основной странице загрузки **Community Edition больше нет** — осталась только платная Ultimate и бесплатная «core»-сборка с другим набором функций. Классическая Community Edition доступна в архиве предыдущих версий — берите **2025.2** (последняя полноценная Community Edition):
> **<https://www.jetbrains.com/idea/download/other/>** → выберите версию **2025.2** → **Community Edition** (`.exe` — Windows, `.tar.gz` — Linux, `.dmg` — macOS).

Пошагово:

1. **Установите и запустите IntelliJ IDEA Community.**
2. **Откройте проект**: `File → Open…` → укажите каталог `workstation4ad3s` (с файлом `pom.xml`).
3. **JDK (Java 17+)**: при первом открытии IDEA предложит выбрать SDK. Проще всего скачать JDK прямо из IDE: `File → Project Structure → SDK → Add SDK → Download JDK` → версия **17** (например, Eclipse Temurin / OpenJDK) → **Download**. Либо укажите уже установленную JDK 17.
4. **Maven**: зависимости подтягиваются автоматически из центрального Maven-репозитория. Если не подгрузились — выполните **Reload All Maven Projects** (иконка ⟳ на панели Maven, или правой кнопкой по `pom.xml → Maven → Reload Project`).
5. **Запуск/отладка**: откройте класс `Main` (метод `main` — точка входа) → правой кнопкой мыши → **Run 'Main'** (или **Debug 'Main'** для отладки с точками останова). IDEA сама соберёт проект и запустит приложение.

---

## Требования

- **Java 17** или новее.
- **ESP32-S3** с прошивкой `ad3s_prog_esp32` (USB↔SPI мост).
- **USB-кабель с передачей данных** (не зарядный).
- **Плата или модуль** с микросхемой 5400ТР065А-022, подключённой к ESP32
  по SPI (минимум: MOSI, MISO, SCLK, CS).

Скрипт запуска ищет Java в следующем порядке:

1. Вложенная папка `jre/` (портативная версия — см. ниже)
2. Переменная окружения `JAVA_HOME`
3. Команда `java` в системном `PATH`
4. Поиск `java.exe` в `C:\Program Files\` (только Windows)

Если Java не найдена — скрипт покажет сообщение и не запустится.

## Как установить Java

**Где взять JDK 17 (Microsoft OpenJDK 17):**

- **FTP (офлайн — для рабочих ПК без интернета):** <https://ftp.dcsoyuz.ru/soft/workstation4ad3s/jdk/> — установщики Windows (`.msi`, `.exe`, x64 и ARM64) и архивы Linux (`.tar.gz`, x64 и ARM64).
- **Сайт Microsoft (онлайн):** <https://learn.microsoft.com/ru-ru/java/openjdk/download>
- **Eclipse Temurin / Adoptium:** <https://adoptium.net/>

### Вариант 1: Портативный JDK (рекомендуется, без установки)

Скачайте JDK 17 в виде архива (.zip для Windows, .tar.gz для Linux) и
распакуйте в папку `jre/` рядом со скриптом запуска. Название папки `jre/`
условное — внутри распакованный JDK (отдельной JRE 17 не существует); скрипт
запуска ищет именно эту папку.

Структура:
```
Workstation4ad3s-X.X.X.bat
Workstation4ad3s-X.X.X.sh
Workstation4ad3s-X.X.X.jar
jre/
  bin/
    java          (Linux)
    java.exe      (Windows)
```

Архивы JDK 17 (`.zip` для Windows, `.tar.gz` для Linux) — см. источники в начале раздела. На FTP для Linux есть готовый `microsoft-jdk-17.0.19-linux-x64.tar.gz`; для Windows на FTP только установщики (`.msi`/`.exe`), поэтому `.zip`-архив берите на сайте Microsoft или Adoptium.

**Windows:** скачайте `.zip`, распакуйте содержимое в папку `jre/`.
**Linux:**
```bash
mkdir jre
tar -xzf *.tar.gz -C jre --strip-components=1
```

### Вариант 2: Установка Java в систему

Установите JDK/JRE любым установщиком (.msi, .deb, .rpm).
После установки убедитесь что `JAVA_HOME` указывает на папку JDK/JRE,
либо что `java` доступна в `PATH`.

Проверка (откройте новый терминал):
```
Windows:  echo %JAVA_HOME%
Linux:    echo $JAVA_HOME
java -version
```

Должно показать путь к JDK/JRE и версию 17 или выше.

**Linux (Ubuntu/Debian):** `sudo apt install openjdk-17-jre`
**Linux (Fedora/RHEL):** `sudo dnf install java-17-openjdk`

---

## Подключение к оборудованию

### 1. Прошивка ESP32 моста

Загрузите и прошейте ESP32-S3 прошивкой `ad3s_prog_esp32`:
<https://github.com/DCsoyuz/ad3s/tree/main/ad3s_prog_esp32>
Инструкция по сборке и прошивке — в README репозитория `ad3s_prog_esp32`.

### 2. Подключение микросхемы

Подключите 5400ТР065А-022 к ESP32 по SPI:

| Сигнал ESP32 | Сигнал чипа | Описание              |
|--------------|-------------|------------------------|
| MOSI         | SDI         | данные ESP32 → чип     |
| MISO         | SDO         | данные чип → ESP32     |
| SCLK         | SCLK        | тактовый сигнал        |
| CS           | SSTR        | строб кадра (выбор чипа) |

Дополнительно (опционально):
STANDBY, VPP, SAMPLE, VC, NSEN, 2 канала квадратурных энкодеров (ENC1, ENC2).

SPI: режим 0, частота по умолчанию **10 МГц** (меняется в приложении).

### 3. Запуск приложения и подключение

1. Подключите ESP32 к ПК по USB.
2. Определите COM-порт в «Диспетчере устройств» (Windows) или `ls /dev/tty*` (Linux).
3. Запустите `Workstation4ad3s-X.X.X.bat` (или `.sh`).
4. В левой панели в выпадающем списке выберите COM-порт ESP32.
5. Нажмите **Open COM**.

После подключения можно читать и писать регистры микросхемы через
панель «Terminal».

---

## Обзор интерфейса

Приложение использует систему докируемых панелей. Все панели можно
открывать, закрывать, отцеплять и перемещать. Раскладка сохраняется между
запусками в файл `dock_layout.xml`.

### Левая панель

- **ConnectPanel** — выбор COM-порта, подключение, кнопки ParseAll /
  Program / Verify / Clean log.
- **File Tree** — навигатор по файлам проекта (hex, asm, txt,
  mode.config). Файлы отмечаются галочками для операции программирования.
- **MenuBar** — меню File, Options, Help.

### Основные вкладки

| Вкладка          | Назначение                                                   |
|-------------------|--------------------------------------------------------------|
| **Terminal**      | Таблица регистров, редактирование значений, чтение/запись    |
| **Asm Editor**    | Текстовый редактор с подсветкой синтаксиса, поиск, брейкпоинты |
| **GraphView**     | Осциллограф — 4 канала, 2 графика (Coord / Vel), FIFO 256 точек |
| **HandTap**       | Анализатор сигналов HandTap (sin/cos, exi), 2 графика         |
| **Debugger CPUs** | Отладка RISC-процессоров CPU1/CPU2: пошаговое выполнение, брейкпоинты, буферы |

### Нижняя панель

- **Console** — системный лог (stdout/stderr), с номерами строк, копирование, очистка.

---

## Основные функции

### Чтение и запись регистров (Terminal)

Панель «Terminal» — основная рабочая область:

- **Таблица базовой RAM** (96 регистров, адреса 0–95): три столбца на регистр
  (адрес, имя, значение). Ячейки редактируемые, принимают hex-ввод.
  Правый клик по значению → «Read value» (одиночное чтение) или
  «Write value» (одиночная запись).
- **Main Registers** — основные регистры (AFE_config, Mode_config,
  ADC_config, CMP_lth, IC_addr и др.) в виде закладок.
- **Handler Registers C1/C2** — регистры обоих каналов: ExoStngs, EXInc,
  InputStngs, ExPhShft, KonturStngs, Mask, ResCntrl, KampS/C, KbiasS/C,
  fbias, Zero, Amp_th, Stat и др.
- **Memory Editor** — кнопки Read/Write базовой RAM, Standby, VPP 9V,
  nReset, Watch OTP, SPI Speed, загрузка/сохранение значений.

### Программирование файлов (ParseAll / Program / Verify)

1. В дереве файлов отметьте галочками нужные файлы (hex/asm/txt + mode.config).
2. **ParseAll** — разбирает все файлы и генерирует hex-выход.
3. **Program** — записывает отмеченные файлы в микросхему (последовательно,
   блоками с проверкой).
4. **Verify** — перечитывает данные из микросхемы и сравнивает с ожидаемыми.

Формат файлов:
- `.txt` — определения значений регистров (адрес=значение).
- `.asm` — ассемблерные программы для внутренних RISC-процессоров чипа.
- `mode.config` — конфигурация файла (тип, адрес, флаги программирования).

### Графики в реальном времени (GraphView)

- **2 графика**: верхний (Coord) и нижний (Vel), каждый с 2 сериями.
- **4 канала**: каждый настраивается — адрес, имя (legend), разрядность
  (numBits), знаковый/беззнаковый, включение/выключение.
- **Курсор** — клик по графику ставит вертикальную линию, показывает
  значения всех серий в точке курсора. Правый клик — снять курсор.
- **Масштаб** — авто-масштаб по Y или ручной (Ymin/Ymax).
- **Detector** — встроенный анализатор: загружает программу из
  `detector_asm/` в CPU1, переключает режимы H1/H2.
- **Сохранение данных** — экспорт отсчётов в файл.

### HandTap анализатор

- 2 графика: значения (sin/cos) и 1-битные сигналы (exi, exi_recovered).
- Настройка адреса, канала (H1/H2), триггера, порога.
- Курсоры на обоих графиках, масштабирование, сохранение в файл.

### Отладчик RISC-процессоров (Debugger CPUs)

- **CPU1 / CPU2**: запуск, останов, пошаговое выполнение, single step,
  выполнение с адреса.
- **Брейкпоинты** — 2 адреса на CPU, включение/выключение.
- **Чтение памяти**: CPU Mem (512/1024), Buf1 (768), Buf2 (1280).
- **Таблица буферов** — 128 слов в виде сетки 8×16.
- Включение/отключение CPU, сброс.

### Программирование OTP-памяти

- **Create BOTP** — генерация `rom_BOTP.hex` из текущих значений регистров.
- **Prog BOTP** — программирование BOTP (однократное программируемое ПЗУ).
- **Create U22b** — генерация `rom_u22b.hex` (регистры PLL и INIT).
- **Prog UOTP** — программирование UOTP (пользовательское OTP, с подачей VPP 9V).
- **Verify BOTP** — верификация запрограммированных данных.
- Управление питанием: Standby, VPP 9V, nReset.

### Энкодеры

Меню Options → Encoder:

- Чтение ENC1/ENC2 (32-битные значения) и C1/C2 Coord.
- Настройка prescaler, velocity resolution, coordinate resolution, LBW.
- Авто-обновление (50 мс).

### Batch Writer

Меню Options → BatchWriter:

- Таблица пошаговой записи: шаг, адрес, значение, имя регистра.
- 20 строк, radio-кнопка для выбора текущего шага.
- Импорт/экспорт CSV.
- Последовательное выполнение всех шагов с верификацией.

### Запись потока (Record)

Меню Options → Record:

- 9 пар адресов (чётный/нечётный), режим 14b14.
- Запись в текстовый файл с метками времени (~1 мс интервал).
- Независимый COM-порт.

### Генерация кода

Из меню Terminal (кнопки внизу Memory Editor):

| Кнопка             | Выходной файл          | Описание                                  |
|--------------------|------------------------|-------------------------------------------|
| Store Values to TXT| `base_ram.txt`         | Экспорт значений базовой RAM              |
| Create BOTP        | `rom_BOTP.hex`         | Hex-файл для BOTP-программирования        |
| Create Poke        | `poke_reg.sv`          | UVM register poke sequence                |
| Generate Defines   | `ad3s_defines.v`       | Verilog `define макросы адресов/значений  |
| Generate RDL       | `ad3s_regs.rdl`        | SystemRDL описание регистров              |
| Generate Env Files  | `*.sv`                 | SystemVerilog enum-файлы для UVM          |
| Create HTML Docs   | `*.html`               | HTML-документация по регистрам            |

### Утилиты

- **Float Helper** (Options → Float Helper) — конвертер вещественных чисел в hex
  с selectable разрядностью (4–32 бита). Несколько панелей одновременно.
- **Test Window** (Options → Test Window) — LED вкл/выкл, поиск IC-адреса
  (сканирование адресов 1–255), установка скорости SPI.
- **ParallelSpiView** — двухканальный DMA-осциллограф с триггером, настройкой VC/SDI
  (открывается через меню Options → ParallelSpiView).
- **Help → Registers** — встроенная HTML-документация по всем регистрам
  с полнотекстовым поиском.

---

## Структура дистрибутива

```
Workstation4ad3s-X.X.X.bat      — скрипт запуска (Windows)
Workstation4ad3s-X.X.X.sh      — скрипт запуска (Linux/macOS)
Workstation4ad3s-X.X.X.jar      — приложение (fat JAR)
risc_programs/
  dma_asm/                       — программа для режима ParallelSpiView
  handtap_asm/                   — программа для HandTap анализа
  detector_asm/                  — программа для детекторного анализатора
  user_asm/                      — пользовательская ассемблерная программа
matlab/
  plot_wave_data.m               — MATLAB-скрипт для отрисовки записанных данных
README.md                        — этот файл
```

---

## Конфигурация

При первом запуске создаётся файл `config.properties` рядом с JAR.
Он хранит: выбранный COM-порт, пути к файлам, настройки каналов графиков,
параметры HandTap, состояние закладок и другие пользовательские настройки.

Файл `dock_layout.xml` сохраняет расположение и размеры панелей.
Удалите его или запустите с `--restore` для сброса раскладки.

---

## Частые проблемы

| Симптом | Решение |
|---------|---------|
| При клике на .bat ничего не происходит | Установите Java 17 (см. раздел выше). Откройте .bat в текстовом редакторе и запустите `java -jar ...` вручную из командной строки, чтобы увидеть ошибку. |
| «Java not found» | Установите Java или распакуйте JDK 17 в папку `jre/` рядом со скриптом. |
| Нет COM-порта в выпадающем списке | ESP32 не подключена, кабель без данных, или не установлен драйвер (CP210x/CH340). Проверьте Диспетчер устройств. |
| Не удаётся прочитать регистры | Проверьте подключение SPI, что NRESET отпущен, что прошивка ESP32 загружена и работает. |
| Графики не обновляются | Нажмите «Loading...» для старта. Убедитесь что каналы включены (галочки) и адреса правильные. |
| Не программируется BOTP | Убедитесь что VPP 9V включен, чип не в standby, nReset отпущен. |
| Панели пропали / окно пустое | Help → Restore Window или запустите с `--restore`. |

---

## Системные требования

- **Windows** 10/11, **Linux** (Ubuntu 20.04+ / Fedora 36+), **macOS** 11+
- **Java** 17+
- **RAM:** 512 МБ минимально, 1 ГБ рекомендуется
- **Дисплей:** 1280×720 минимально, 1920×1080 рекомендуется

---

## Связанные ресурсы

- **Прошивка ESP32 моста (ad3s_prog_esp32):**
  <https://github.com/DCsoyuz/ad3s/tree/main/ad3s_prog_esp32>
- **Спецификация микросхемы 5400ТР065А-022:**
  <https://support.dcsoyuz.ru/docs/5400TP065A-022/ad3s-main>
