# Installation guide / Instrukcja instalacji

**[English](#english) | [Polski](#polski)**

---

<a id="english"></a>
## English

Requires **Windows**, a physical connection to the radio (USB, for the
reference IC-7300), and a few one-time settings both in the installer
and on the radio itself. None of it is hard, but skipping a step is the
most common cause of "it doesn't work."

### 1. Install

1. Download `HAMCTRL-Setup.exe` from the [latest release](../../releases/latest).
2. Run it and follow the installer. It bundles everything needed
   (Python runtime, the Rust audio engine, Opus codec) — no separate
   Python install required.
3. Windows/your antivirus may flag an unsigned installer from a new
   publisher — this is expected for a small open-source project with no
   code-signing certificate, not a sign of a problem.

### 2. First run

1. Launch HAMCTRL. It starts a local server and opens your browser at
   `https://localhost:8001`.
2. **The browser will warn about the certificate** ("Your connection
   isn't private" / a self-signed cert warning) — this is expected, the
   app generates its own certificate on first run so it can serve HTTPS
   (required for the microphone/TX-audio feature to work in the
   browser). Click **Advanced → Proceed to localhost**.
3. Log in with the default account: `admin` / `Admin1234!`
4. You'll immediately be asked to **set a new admin password** — the
   default cannot stay active. Pick one and continue.

### 3. Connect the radio

1. Plug the radio into the PC over USB (or the appropriate serial
   adapter for older models).
2. **On the radio itself**, in the CI-V menu:
   - Set the **CI-V baud rate to 115200** if you want the waterfall/scope
     (lower baud rates work for control-only, but the scope stream
     specifically requires 115200).
   - Set **CI-V USB Port → Unlink from REMOTE** (on the IC-7300, this is
     what actually lets a PC application read the scope data — without
     it you'll get radio control but no waterfall).
3. In HAMCTRL's **KONFIGURACJA / CONFIG** tab, pick your radio model and
   COM port, then connect.
4. If the radio doesn't respond, double check: correct COM port, matching
   baud rate on both ends, and that the radio is actually powered on —
   the app will attempt a wake-up sequence automatically, but can't help
   with a wrong port/baud/cable.

**Other radio models — needs Hamlib.** HAMCTRL talks CI-V directly (no
extra software) only for the radios with a built-in profile: IC-7300,
IC-7610, IC-705, IC-9100, IC-7100, IC-9700. Any other radio (older Icom
models, Yaesu, Kenwood, ...) goes through
[Hamlib](https://hamlib.github.io/)'s `rigctld`, which is **not**
bundled in the installer — download and install it separately (the
Windows build from the Hamlib site), then either let HAMCTRL find it
automatically (it looks in the default install paths and on `PATH`) or
point `.env`'s `HAMLIB_PATH` at `rigctld.exe` directly if you installed
it somewhere else.

### 4. Audio (for SSB voice and to hear the radio)

- Pick your RX (speaker/headphones) and TX (microphone) devices under
  **PROFIL**. If your radio provides USB audio directly (like the
  IC-7300), you can usually select it directly rather than a physical
  sound card.
- If audio ends up on the wrong output device (e.g. built-in speakers
  instead of headphones you plugged in later), explicitly pick the
  headphones by name in that same dropdown rather than leaving it on
  "Default" — the browser doesn't always re-detect a device you plugged
  in after the page already loaded.

### 5. Using it from another device on your network

Other computers/phones on the same LAN can reach the app at
`https://<this-PC's-LAN-IP>:8001` — check the console window HAMCTRL
opened at startup, it prints the exact URL. You may need to allow the
app through Windows Firewall the first time (Windows will usually prompt
for this automatically).

### 6. Optional: access from outside your network, COM-port bridge for other software

Both of these are more advanced, one-time setup steps. See the in-app
help text on the **INTERNET** and **KONFIGURACJA** tabs for the full
picture — covering every option here would make this guide longer than
it needs to be for a first install. The short version:

- **Quick internet access, no extra software**: a Cloudflare Quick
  Tunnel (under **INTERNET**) — gives you a working `https://...
  trycloudflare.com` address in seconds, nothing to install.
- **Your own domain with a real (non-self-signed) certificate**: needs
  [win-acme](https://www.win-acme.com/) installed separately — HAMCTRL
  does **not** bundle it. Certbot discontinued Windows support in
  February 2024, so win-acme is the replacement client. It has no
  installer — download the portable zip and extract `wacs.exe` to
  `C:\win-acme\`. Generating/renewing the certificate needs
  Administrator rights — use the **"Wygeneruj certyfikat (jako admin)"
  ("Generate certificate (as admin)")** shortcut created in the Start
  menu; it prompts for elevation (UAC) itself, you don't need to
  right-click it. Renewal afterward is automatic (a scheduled task,
  enabled by default at install time).
- **Virtual-COM-port bridge** for running CW Skimmer / Ham Radio Deluxe
  / Logger32 alongside HAMCTRL: requires
  [com0com](https://com0com.sourceforge.net/) on the client machine.

### 7. Optional: relay board (antenna switch, amplifier bypass, anything else you wire up)

The **ADMIN -> PRZEKAŹNIKI ARDUINO** panel drives 8 relays over a
serial text protocol (originally designed by Marcin Boboli, SP5IOU,
emulating the SDR220 relay set). What each relay is physically wired to
is entirely up to you — antenna switching, PA bypass, anything.

The Arduino firmware is bundled with HAMCTRL at
[`arduino/relay_sp5iou/`](arduino/relay_sp5iou/) — see that folder's own
README for the pin map, flashing instructions and the protocol. Flash it
to any Arduino with 8 free digital outputs, wire up an 8-channel relay
module, then enable it in **ADMIN** and pick the COM port.

### Troubleshooting

- **Browser keeps warning about the certificate on every visit**: normal
  for a self-signed cert — either click through it each time, or trust
  it manually in your OS/browser certificate store (optional, cosmetic
  only).
- **Radio connects but no waterfall**: almost always the CI-V baud
  rate/USB-port-unlink setting on the radio (step 3 above).
- **Can't reach it from another device**: check the Windows Firewall
  prompt wasn't dismissed/blocked, and that you're using the LAN IP
  printed at startup, not `localhost`.

---

<a id="polski"></a>
## Polski

Wymaga **Windows**, fizycznego połączenia z radiem (USB, dla
referencyjnego IC-7300) i kilku jednorazowych ustawień — zarówno w
instalatorze, jak i w samym radiu. Nic z tego nie jest trudne, ale
pominięcie kroku to najczęstsza przyczyna "nie działa".

### 1. Instalacja

1. Pobierz `HAMCTRL-Setup.exe` z [najnowszego wydania](../../releases/latest).
2. Uruchom i przejdź przez instalator. Zawiera wszystko co potrzebne
   (środowisko Python, silnik audio w Rust, kodek Opus) — osobna
   instalacja Pythona niepotrzebna.
3. Windows/antywirus może ostrzec przed niepodpisanym instalatorem od
   nowego wydawcy — to normalne dla małego projektu open source bez
   certyfikatu podpisu kodu, nie oznacza problemu.

### 2. Pierwsze uruchomienie

1. Uruchom HAMCTRL. Wystartuje lokalny serwer i otworzy przeglądarkę pod
   `https://localhost:8001`.
2. **Przeglądarka ostrzeże o certyfikacie** ("Połączenie nie jest
   prywatne" / ostrzeżenie o certyfikacie z podpisem własnym) — to
   oczekiwane, aplikacja generuje własny certyfikat przy pierwszym
   uruchomieniu, żeby móc działać po HTTPS (wymagane, żeby funkcja
   mikrofonu/audio TX działała w przeglądarce). Kliknij **Zaawansowane →
   Przejdź do localhost**.
3. Zaloguj się domyślnym kontem: `admin` / `Admin1234!`
4. Od razu zostaniesz poproszony o **ustawienie nowego hasła
   administratora** — domyślne nie może zostać aktywne. Wybierz nowe i
   kontynuuj.

### 3. Podłączenie radia

1. Podłącz radio do komputera przez USB (albo odpowiedni adapter
   szeregowy dla starszych modeli).
2. **W samym radiu**, w menu CI-V:
   - Ustaw **prędkość CI-V na 115200**, jeśli chcesz mieć
     wodospad/scope (niższe prędkości wystarczą do samego sterowania,
     ale strumień scope wymaga konkretnie 115200).
   - Ustaw **CI-V USB Port → Unlink from REMOTE** (w IC-7300 to właśnie
     to ustawienie pozwala aplikacji na PC czytać dane scope'a — bez
     tego będzie działać sterowanie radiem, ale nie wodospad).
3. W zakładce **KONFIGURACJA** w HAMCTRL wybierz model radia i port COM,
   po czym połącz.
4. Jeśli radio nie odpowiada, sprawdź: właściwy port COM, zgodną
   prędkość po obu stronach, i czy radio jest faktycznie włączone —
   aplikacja sama spróbuje sekwencji "budzenia" radia, ale nie pomoże
   przy złym porcie/prędkości/kablu.

**Inne modele radia — potrzebny Hamlib.** HAMCTRL rozmawia po CI-V
bezpośrednio (bez dodatkowego softu) tylko z radiami, dla których ma
gotowy profil: IC-7300, IC-7610, IC-705, IC-9100, IC-7100, IC-9700.
Każde inne radio (starsze modele Icom, Yaesu, Kenwood...) idzie przez
`rigctld` z [Hamlib](https://hamlib.github.io/), którego instalator
**nie zawiera** — pobierz i zainstaluj osobno (build dla Windows ze
strony Hamlib), a potem albo pozwól HAMCTRL znaleźć go samemu (szuka w
domyślnych ścieżkach instalacji i w `PATH`), albo wskaż `rigctld.exe`
wprost przez `HAMLIB_PATH` w pliku `.env`, jeśli zainstalowałeś go
gdzie indziej.

### 4. Audio (do SSB i żeby słyszeć radio)

- Wybierz urządzenie RX (głośnik/słuchawki) i TX (mikrofon) w zakładce
  **PROFIL**. Jeśli radio udostępnia audio bezpośrednio przez USB (jak
  IC-7300), zwykle można wybrać je wprost, bez fizycznej karty dźwiękowej.
- Jeśli dźwięk trafia na złe urządzenie wyjścia (np. wbudowane głośniki
  zamiast podłączonych później słuchawek), wybierz słuchawki jawnie po
  nazwie w tym samym polu, zamiast zostawiać "Domyślne" — przeglądarka
  nie zawsze wykrywa urządzenie podłączone już po załadowaniu strony.

### 5. Korzystanie z innego urządzenia w sieci

Inne komputery/telefony w tej samej sieci lokalnej mogą wejść na
aplikację pod adresem `https://<IP-tego-komputera-w-sieci>:8001` —
dokładny adres jest wypisany w oknie konsoli, które HAMCTRL otwiera przy
starcie. Przy pierwszym uruchomieniu może być potrzebne zezwolenie
aplikacji w Zaporze Windows (Windows zwykle sam o to zapyta).

### 6. Opcjonalnie: dostęp spoza sieci, mostek COM dla innego softu

Oba to bardziej zaawansowane, jednorazowe ustawienia. Pełny opis
zobacz w tekście pomocy w samej aplikacji, w zakładkach **INTERNET** i
**KONFIGURACJA** — opisanie tu każdej opcji wydłużyłoby ten poradnik
ponad potrzeby pierwszej instalacji. Wersja skrócona:

- **Szybki dostęp z internetu, bez dodatkowego softu**: Cloudflare
  Quick Tunnel (zakładka **INTERNET**) — działający adres
  `https://...trycloudflare.com` w kilka sekund, nic nie trzeba
  instalować.
- **Własna domena z prawdziwym certyfikatem** (nie self-signed):
  potrzebny osobno zainstalowany [win-acme](https://www.win-acme.com/) —
  HAMCTRL go **nie** dołącza. Certbot zakończył wsparcie dla Windows w
  lutym 2024, więc win-acme jest jego następcą. Bez instalatora —
  pobierz portable zip i rozpakuj `wacs.exe` do `C:\win-acme\`.
  Generowanie/odnawianie certyfikatu wymaga uprawnień administratora —
  użyj skrótu **"Wygeneruj certyfikat (jako
  admin)"** w menu Start; sam poprosi o podniesienie uprawnień (UAC),
  nie trzeba klikać prawym przyciskiem. Późniejsze odnawianie jest
  automatyczne (zadanie w Harmonogramie, włączone domyślnie przy
  instalacji).
- **Mostek wirtualnych portów COM** do uruchomienia CW Skimmer / Ham
  Radio Deluxe / Logger32 równolegle z HAMCTRL: wymaga
  [com0com](https://com0com.sourceforge.net/) na komputerze klienckim.

### 7. Opcjonalnie: płytka przekaźnikowa (przełącznik antenowy, bypass wzmacniacza, cokolwiek innego)

Panel **ADMIN -> PRZEKAŹNIKI ARDUINO** steruje 8 przekaźnikami przez
protokół tekstowy po porcie szeregowym (oryginalny projekt Marcina
Boboli, SP5IOU, emulujący zestaw przekaźników SDR220). Do czego
fizycznie podłączysz każdy przekaźnik — przełącznik antenowy, bypass
wzmacniacza, cokolwiek — to już Twoja sprawa.

Firmware na Arduino jest dołączony do HAMCTRL w
[`arduino/relay_sp5iou/`](arduino/relay_sp5iou/) — pełny opis pinów,
instrukcja wgrywania i protokół w README tego folderu. Wgraj na
dowolne Arduino z 8 wolnymi wyjściami cyfrowymi, podłącz 8-kanałowy
moduł przekaźnikowy, potem włącz w **ADMIN** i wybierz port COM.

### Rozwiązywanie problemów

- **Przeglądarka wciąż ostrzega o certyfikacie przy każdej wizycie**:
  normalne dla certyfikatu z podpisem własnym — albo klikaj "dalej" za
  każdym razem, albo zaufaj mu ręcznie w magazynie certyfikatów
  systemu/przeglądarki (opcjonalne, tylko kosmetyczne).
- **Radio się łączy, ale nie ma wodospadu**: prawie zawsze to ustawienie
  prędkości CI-V / Unlink from REMOTE w samym radiu (krok 3 powyżej).
- **Nie da się połączyć z innego urządzenia**: sprawdź czy prośba Zapory
  Windows nie została odrzucona/zablokowana, i czy używasz adresu IP w
  sieci lokalnej wypisanego przy starcie, a nie `localhost`.