ATV RX controller firmware V1.16
================================

Firmware for the DigiBB controller board (ESP32 DevKit V1, ILI9341 320x240 display, rotary encoder with push
button) as the front panel of the ATV receiver. Look and feel after the DigiBB controller by PE1MUD and PE1OBW,
used with their permission.

Files
-----
  ATV-RX-Controller-V1.16.bin   the complete firmware: write it at address 0x0
  flash.bat                    double-click it: it shows the COM ports, asks which one and writes the firmware
  esptool.exe                  Espressif's flash tool for Windows (v4.8.1, GPLv2: esptool-LICENSE.txt)
  sim_atvd.py                  pretends to be the receiver over USB, to try the display without the receiver
  PROTOCOL.md                  the serial protocol between the controller and the receiver

Updating from the receiver (controller V1.6 or newer, receiver V1.0.1 or newer)
--------------------------------------------------------------------------------
  Easiest, once the controller runs V1.6: open the receiver's web page, tab Firmware, Controller, "Choose .bin and
  update" and choose ATV-RX-Controller-V1.16.bin from this zip. It goes over the serial link; no USB needed. If the new
  version does not reach the receiver within 90 s, the controller goes back to its previous version by itself.
  The first time (controller older than V1.6): flash over USB as below.

Flashing, option 1: in the browser (nothing to install)
--------------------------------------------------------
  1. Connect the ESP32 with a USB cable. Windows needs the CP210x driver (Silicon Labs) if no COM port appears.
  2. Open https://espressif.github.io/esptool-js/ in Chrome or Edge.
  3. Baudrate 460800, press Connect and choose the COM port of the ESP32.
     (If it does not connect: hold the BOOT button on the ESP32 while pressing Connect.)
  4. Flash Address 0x0, choose ATV-RX-Controller-V1.16.bin, press Program.
  5. When it is done, press the EN button on the ESP32 (or unplug and plug in again).

Flashing, option 2: flash.bat
-----------------------------
  1. Unpack the whole zip to a folder (do not start it from inside the zip).
  2. Connect the ESP32 and double-click flash.bat. It lists the COM ports; type the one of the ESP32 (COM5, or just 5)
     and press Enter. Not sure which one? Unplug the ESP32, start flash.bat again and see which port is gone.
  3. If it does not connect: hold the BOOT button on the ESP32 until it starts writing.
  4. When it says Done, press the EN button on the ESP32 (or unplug and plug in again).
  (From a command prompt "flash.bat COM5" also works.)

Connecting to the receiver
--------------------------
  The controller talks to the receiver over a serial line (5 Mbaud) on the two pins that the DigiBB board
  normally uses for I2C to the baseband (GPIO 21 and 22). On the receiver side this is connector JP5 pin 7 and 9,
  on the output board connector J5 (GND, SER_OUT, SER_IN, 5V). Which wire is transmit and which is receive does
  not matter: the controller finds it out by itself within a few seconds.
  Controller V1.6 belongs to receiver firmware V1.0.0 (5 Mbaud link). With much older receiver firmware (before V0.9.177)
  the controller says "Receiver firmware too old". (Controller V1.0 is the continuation of the test versions 1.x .. 4.4.)

Using it
--------
  After switching on, until the receiver has started, the controller shows "Waiting for SDR" (a mast with radio
  waves and the seconds since switching on); when the receiver answers, "SDR found" and then the picture.
  Screens, one after the other with a click when nothing is selected:
    picture -> main screen -> memories and LNBs -> settings -> picture
  Hold the knob pressed for 1,5 s on the main, memory or settings screen: straight back to the picture.
  On every screen: turn the knob to move over the items; one position has nothing selected.
  Colours on the main, memory and settings screens (as the DigiBB):
    nothing selected     all text white on black
    in the menu          white = can be chosen, yellow on blue = selected, green = cannot be chosen
    changing a value     black on yellow
  Click on an item to change it (black on yellow), turn to change the value, click again when done (yellow on blue).
  Editing a name (DigiBB style): click = cursor (blue box), turn = move it, click = change that character (red
  box), turn = choose the character, click = keep it; click again without moving = done.

  Picture screen: the received picture fills the display (320 x 240). Turning the knob opens a half transparent menu
  over the picture (with frequency, level, MagicSync and S/N at the top and the IF spectrum, 40 MHz around the received
  frequency, at the bottom); turn to move over its items, click to use one:
    M01 name                           click, turn = look through the stored memories ("*" = the active one),
                                       click = load it
    Seek                               click, then turn = seek up or down (it stops by itself on a station; turn the
                                       other way to reverse); click = stop / done
    Video  IF spectrum  BB spectrum    click = show that on this display (the chosen one is underlined)
  The menu disappears 5 s after the last touch (a memory being chosen is then not loaded). While someone watches the
  receiver's RTSP stream
  there is no picture here ("RTSP stream running - no picture"): both at once do not fit in the receiver. The green bar of 2 pixels at the right-hand edge is the RF level (0 to 80 dBuV, full height); the two
  bars at the left-hand edge (on a black strip of 5 pixels) are the audio levels L and R (PPM, +6 to -60 dB, red above
  0 dB) of the audio that is chosen (NICAM, FM, or with NICAM > FM the one playing). A click (when the menu is not
  shown and it is not seeking) goes to the main screen. A long press (0,6 s) switches the picture: video -> IF spectrum -> BB spectrum -> video (the
  same setting as "Picture" on the memory/LNB screen; the chosen spectrum is named at the top right). While the picture
  is a spectrum there is no spectrum overlay when seeking.

  Main screen: PPM meters (NICAM L/R, FM L/R) on the left, on the right:
    M01:PI6ATV           the memory: turn = look at the stored ones ("*" = the active one), click = load it
    IN1:10.475,000MHz    input and frequency: turn = 1 MHz steps
    LNB: name            the LNB in use (or none)
    Fine / AFC           turn = fine tuning in 25 kHz steps
    ID: PI6ATV           the station name sent with NICAM
    Audio NICAM > FM     turn = NICAM, NICAM > FM or FM; the source that plays is underlined (none: nothing received)
    C/N, Level           with bars
    Seek                 turn = seek up or down (turn again = stop)

  Memories and LNBs:
    Memory   number (Active = the one in use, View = another stored one, Empty), name, action: UPDATE / DELETE
             (active memory), LOAD / DELETE (another one) or STORE (an empty one); the click that ends the action
             carries it out. UPDATE and STORE save the current settings (input, LNB, frequency, supply, ...).
    Input    IN1 / IN2, the LNB (none or one from the list), the frequency (1 MHz steps)
    Supply   13 V (V) or 18 V (H), 22 kHz on / off
    LNB edit which LNB (LNB1, LNB2 ... or New: click on the name to add one), its name, its LO in GHz (edit it digit
             by digit, as a name)
    LO       below or above (the LO is below or above the received frequency); Delete: turn to DELETE?, click = gone
    Noise    the noise filter of the picture: off, light, medium, strong or auto (auto: chosen by the receiver on the
             C/N: below 10 dB light, below 6 dB medium, below 2 dB strong, back 2 dB higher, off while seeking;
             "now ..." shows which)
    Picture  what the picture screen shows: video, IF spectrum or BB spectrum (the spectrum as the receiver draws it for
             RTSP, scaled to this display). Waveform and vectorscope: on the web page.
             Kept in the controller.
    Brightness, Gamma, Saturation   the picture on this display only (the receiver and its web page do not change):
             brightness -50 .. +50, gamma 0,5 .. 2,5, saturation 0 .. 200 %. Done inside the JPEG decoder's colour
             conversion (its tables and factors), so they cost no time per picture.
    Backlight 2 .. 20 as on the DigiBB (PWM 190 Hz, 20 = always on, the default).
             These four are kept in the controller (also after switching off; flashing the complete firmware resets them).

  Settings screen: AFC, NICAM > FM at (bit errors per second; "off" = only when the NICAM lock is lost), back to
  NICAM after (seconds), OSD line (Off, On, or Auto: shown for 10 s after choosing a memory or finding a station), Display (normal or upside down, kept in the controller), firmware, IP address, temperatures, controller version with
  "knob: full / half / quarter" (how it counts the clicks of the knob: when one click moves two lines or more, it learned
  wrongly). On the "Waiting for SDR" screen a long press also turns the display upside down (as on the DigiBB).
  After 15 s without touching, the selection disappears.
  Rotary encoders differ: one click can be a full, a half or a quarter quadrature cycle. The controller finds this out
  by itself from the positions the knob rests in (after a few clicks; a half-cycle encoder may skip a step or two the
  very first time) and remembers it. Changed the encoder? Hold the knob pressed while switching on: it learns again.
  Turning the wrong way round: strap GPIO 15 to GND (as on the DigiBB board).
  The frame and the thick lines turn orange when the receiver gets warm (75 °C) and red when it stopped because of
  overheating (80 °C; it starts again below 65 °C). On the picture screen a label at the top right says "HOT 77°C"
  (orange) or "TOO HOT 81°C" (red).

Trying without the receiver
---------------------------
  pip install pyserial
  python sim_atvd.py COM5
  The display then shows a simulated receiver; what you do with the knob is printed in the window.
