Preliminary User Guide (Dec 2018) - IanSB/RGBtoHDMI GitHub Wiki

Contents

Overview

The RGBtoHDMI interface converts the RGB video from the BBC Micro or Electron to HDMI video compatible with most modern TV/Monitors. The interface comprises a Raspberry Pi Zero and a specially designed Hat containing a small CPLD. Custom firmware on the Raspberry Pi, in conjunction with the CPLD, is able to correctly sample each of the Beeb's video modes to give a pixel-perfect rendition.

images/IMG_1390.JPG

This is the second revision of the manual and covers additional features in the December 2018 release:

  • A redesigned (multi-line) menu system that is easier to navigate
  • Deinterlacing (of Mode 7, multiple algorithms)
  • Genlocking (and a VSync indicator)
  • Support for a wider range of systems (e.g. Atom, UK101) with widely varying video timings

Parts needed

  • An RGBtoHDMI hat (first 10 were made by hoglet), including:
    • A 6-pin DIN to 6-pin Molex KK cable (supplied with the hat)
    • 2x 11mm M2.5 spacered and 4x short M2.5 machine screws (supplied with the hat)
    • A 2-pin 0.1" header for the reset pins on the Pi (supplied with the hat)
  • A Raspberry Pi Zero (or Zero W, see note below) with the GPIO headers fitted (PiHut)
  • A Micro SDHC Card (2GB or larger) (PiHut)
  • A mini-HDMI to HDMI cable (or DVI if that is what your Monitor needs) (PiHut)
  • (Optional) A USB/3.3V Serial cable for debugging (PiHut)

Note: I've done a small amount of testing of the Pi Zero W and it does seem to work.

Note: The Pi 1, 2 and 3 models will not work.

Adding the reset header

If you want the reset button on the right of the hat to work, you will need to populate the 2-pin reset header on the Pi. A suitable header is supplied with the RGBtoHDMI hat. The header on the Pi is marked "run" as can be seen below:

images/IMG_1419.JPG

Downloading the software

  • Start with a blank Micro SD Card (it should be FAT32 formatted)
  • Download the latest release zip file from here
  • Unzip this to the SD Card (so all the files are in the root directory of the SD Card)

Configuring the software

Monitor resolution

On the SD Card, edit config.txt and make sure the section that matches your monitor resolution is uncommented, and the remaining ones are commented.

The default if 1920x1080:

## 1920x1080 @ 50Hz
##
## Scale by 1:2 - 672x540 => 1344x1080
##   l/r overscan = (1920-1344)/2  = 288
##   t/b overscan = (1080-1080)/2  =   0
##
hdmi_group=1
hdmi_mode=31
overscan_left=288
overscan_right=288
overscan_top=0
overscan_bottom=0

If you need any additional resolutions, let me know and I'll add them.

The complete config.txt file can be seen here.

Electron

Electron users need to also edit cmdline.txt on the SD Card. Specifically:

  • If you are using an Electron, set elk=1
  • If the Electron is Issue 2 or 4 (i.e. with low video levels), also set mux=1
# Important: All the properties must be on a single line, and no blank lines!
#
sampling06=3 sampling7=0,2,2,2,2,2,2,0,8,5 info=1 palette=0 deinterlace=6 scanlines=0 mux=0 elk=0 vsync=0 vlockmode=0 vlockline=5 nbuffers=2 debug=0 m7disable=0 keymap=123233 return=1

The complete cmdline.txt file can be seen here.

Connecting everything together

  • :warning: The Pi is powered from the Beeb via the RGB Cable. Do not ever power the Pi from a separate power supply

  • Plug the RGBtoHDMI hat into the Pi, making sure the connectors are aligned

  • Fit the two PCB spacers to the long edge of the Pi away from the connector with the 4x M2.5 machine screws. This is important as it stops the board flexing when the buttons are pressed. If you don't do this, you risk damaging the connector:

images/IMG_1417.JPG

  • Plug the Micro SD Card into the Pi

  • Connect 6-Pin DIN cable between the Beeb's RGB socket and the RGBtoHDMI hat. The connector is polarised and the red wire should be nearest the push switches.

  • Connect the the Mini HDMI cable between the Pi and the Monitor

Powering on

  • :warning: The Pi is powered from the Beeb via the RGB Cable. Do not ever power the Pi from a separate power supply

  • Switch on the Monitor first and select the HDMI input

  • Switch on the Beeb

  • After about two seconds you should see the "BBC Computer" startup message (possibly slightly fuzzy)

  • Press the right most of the three buttons (SW3) to run the Auto Calibration

  • Press the middle button (SW2) to run the HDMI Clock Calibration

User interface

RGBtoHDMI has a simple user interface that supports the following:

  • Selection of various features via a Menu system (more below)
  • HDMI Clock Calibration
  • Automatic Calibration

"Automatic Calibration" adjusts pixel sampling clock fed to the CPLD with the goal of minimising the number of pixel sampling errors.

"HDMI Clock Calibration" adjusts the HDMI clock such that the HDMI VSync frequency exactly matches the source VSync frequency. In addition, it enables a mode (called genlocking) where the HDMI clock is continually adjusted such that the two VSync signals stay phase-locked. By doing this, it's possible to use single buffering and avoid artefacts like tearing and stutter.

When there is no menu active the three buttons function as follows:

  • SW1 (left): bring up the main menu
  • SW2 (middle): run HDMI Clock Calibration
  • SW3 (right): run Automatic Calibration

When navigating through the menus, the three buttons function as follows:

  • SW1 (left): select the current menu item - if this is a leaf property then edit it's value
  • SW2 (middle): move up to previous menu item
  • SW3 (right): move down to next menu item

When editing a property value, the three buttons function as follows:

  • SW1 (left): done
  • SW2 (middle): decrease the value
  • SW3 (right): increase the value

If the buttons are held down, they will auto-repeat (in an exponential fashion) allowing large values to be changed efficiently.

The buttons may be redefined using the keymap property in cmdline.txt to suite how you choose to package your RGBtoHDMI.

In addition, there are two green status LEDs:

  • the left LED indicates the system is genlocked (flashing indicates genlock has not yet been acquired)
  • the right LED indicates Mode 7 has been detected, off in Modes 0..6

Main menu

images/IMG_1527.JPG

The main menu structure is as follows:

  • Info Menu
  • Processing Menu
  • Settings Menu
  • Geometry Menu
  • Sampling Menu
  • Return

All of the options that can be changed in the menus can also be set in the cmdline.txt file. So once you have experimented and determined what suites your system best, then they can be made persistent by updating that file. Please see the detailed comments there for more information.

Info menu

images/IMG_1528.JPG

The info menu has the following items:

  • Calibration Summary
  • Calibration Detail
  • Calibration Raw
  • Firmware Version
  • Credits
  • Return

The calibration items show successively more details about the results of the last "Automatic Calibration". This information is useful when you want to make the calibration persistent, by copying the various parameters to cmdline.txt. The complete cmdline.txt file can be seen here.

Processing menu

images/IMG_1529.JPG

The processing menu has the following items:

  • Deinterlace
  • Palette
  • Scanlines (On/Off)
  • Return

The Deinterlace option selects the deinterlace algorithm to be used in mode 7.

Currently the available options are:

  • None
  • Simple Bob (CRT-like)
  • Simple Motion Adaptive 1
  • Simple Motion Adaptive 2
  • Simple Motion Adaptive 3
  • Simple Motion Adaptive 4
  • Advanced Motion Adaptive

Advanced Motion Adaptive gives the best results, with two caveats:

  • it can amplify pixel errors, so is best used when the system is error free
  • it requires the correct setting of the delay parameter, which only exists in CPLDv2

The Palette option provides a choice of colour palettes:

  • Default
  • Inverse
  • Mono 1
  • Mono 2
  • Just Red
  • Just Green
  • Just Blue
  • Not Red
  • Not Green
  • Not Blue
  • Atom Colour Normal
  • Atom Colour Extended
  • Atom Colour Acorn
  • Atom Colour Mono

The Atom palettes are only relevant to the Atom specific version of RGBtoHDMI.

The Scanlines option selects whether you want visible scanlines or not.

Settings menu

images/IMG_1530.JPG

The settings menu has the following items:

  • Elk (On/Off)
  • Input Mux (On/Off)
  • VSync Indicator (On/Off)
  • VLock Mode
  • VLock Line
  • Num Buffers
  • Debug (On/Off)
  • Mode7 Disable (On/Off)
  • Return

The Elk setting slightly alters the way lines are captured. If you are using an Electron it should be set to on, otherwise set to off.

The Input Mux setting alters the voltage level threshold for the R/G/B inputs. If you are using an Electron Issue 2 or 4 you should set this to on, otherwise set to off.

The VSync indicator is a useful debugging tool so see if the HDMI VSync is locked to to the source VSync. When on, a red line will indicate the timing of the HDMI Vsync. If the HDMI and source VSyncs are at slightly different frequencies, then this red line will move up or down.

The VLock Mode setting has the following choices:

  • Unlocked
  • 2000 ppm Slow
  • 1000 ppm Slow
  • Locked (Exact) [ a.k.a. Genlocked ]
  • 1000 ppm Fast
  • 2000 ppm Fast

In Unlocked mode, no active adjustment is made to the HDMI clock. In all the other modes, the HDMI clock is controlled so the HDMI VSync rate matches the source VSync rate, with the specified deviation.

In Locked mode, the goal is to exactly lock the HDMI VSync to the Source VSync, such that it happens on exactly the same line in each successive frame. This is known as "Genlocking".

The VLock Line setting is used to set the target line for Locked mode. Typically this will be set to near the bottom of the screen (e.g. line 1), so that the possibility of visible tearing is eliminated.

The Num Buffers setting controls how many video field buffers are used:

  • Single Buffered
  • Double Buffered
  • Triple Buffered
  • Quad Buffered

In Mode 7, single buffered is always used, so this setting is only applicable to the other modes.

Each additional buffers adds one field (typically 20ms) of latency, but reduces visible tearing.

If single buffered is selected, then it's advisable to also set:

  • VLock Mode = Locked (Exact)
  • VLock Line = 5 otherwise, the on-screen menus will phase in and out.

The Debug setting highlights the active area of the screen in light grey. It can be useful to do this when experimenting with different screen geometries.

The Mode7 Disable setting disables the detection of mode 7. On a Beeb this setting should always be on. It's purpose is to allow use with non-Acorn machines, whose video timing may look like mode 7.

Geometry Menu

images/IMG_1531.JPG

The geometry menu has the following items:

  • H offset
  • V offset
  • H width
  • V height
  • FB width
  • FB height
  • FB bits/pixel
  • Clock freq
  • Line length
  • Clock tolerance

The purpose of these parameters is to allow RGBtoHDMI to be used with non-Acorn machines (i.e. with different video timings). For the Acorn BBC Model B, Master 128 and Electron the defaults should not need to be changed.

The H/V offset and H/V width parameters control the portion of the field that is sampled.

The FB width, FB height and FB bits/pixel parameters control the size of the Pi frame buffer used.

The Clock frequency specifies the nominal pixel sampling clock (in Hz). This should be either 6x or 8x the source pixel clock rate, with a maximum value of 100,000,000 (100MHz).

The Line length specifies the exact duration of a horizontal line (i.e. the HSync period) in units of sampling clocks.

The Clock tolerance specifies the maximum allowed deviation from the nominal sampling clock (in ppm). This is used by the sampling clock calibration code to determine when the video timing should be considered non-standard. In which case it will fall back to the last good value. Setting this to zero disables this behaviour.

For example, on the BBC Model B:

  • the pixel clock in Mode 0 is 16MHz
  • so the best sampling clock is 96MHz (6 * 16)
  • the HSync period is exactly 64us
  • so the line length is 6144 (64 * 96)

Once these parameters are set correctly, then the Automatic Calibration process will deal with any actual variation in clocks between the Pi and the source.

Sampling Menu

images/IMG_1532.JPG

The sampling menu has the following items:

  • All offsets
  • A offset
  • B offset
  • C offset
  • D offset
  • E offset
  • F offset
  • Half
  • Divider
  • Delay (added in CPLD v2)

These values are optimised during Automatic Calibration to minimise pixel sampling errors.

Automatic Calibration

Automatic Calibration is a process that allows RGBtoHDMI to optimise the precise pixel sampling offsets, resulting in as stable as possible an image. It is needed because of slight variations in timing between different machines.

The CPLD on RGBtoHDMI adjusts the pixel sampling offsets in units of 96MHz clocks (i.e. 10.4ns). Consequently, in a Mode 7 pixel (12MHz pixel clock) there are 8 possible sampling offsets, and in a Mode 0 pixel (16MHz pixel clock) there are 6 possible sample points. During calibration, the best value of these offsets is determined.

RGBtoHDMI holds two separate calibrations: one for Mode 7, the other for Modes 0..7. Whenever a mode change is detected, the CPLD is reloaded with the calibration appropriate for the mode.

When the system is initially powered up, the initial calibrations are loaded from cmdline.txt in the SD Card.

The steps involved in performing a calibration are:

  • Select the screen mode on the Beeb: use either Mode 0 or Mode 7
  • Bring up some static text / graphics (*HELP is usually sufficient)
  • Press the Auto Calibrate button (the right button)
  • Calibration takes just a few seconds

If you want to view the results of the calibration, navigate to the following menu:

  • Info / Calibration Summary

This page shows you the results of the calibration for the current screen mode.

images/IMG_1524.JPG

  • Info / Calibration Details

The page shows you the number of errors that occurred at each of the sampling offsets tested.

images/IMG_1525.JPG

You can see there is an offset where error-free sampling occurs.

  • Info / Calibration Raw

The page shows you the raw error data - sometimes useful in debugging.

images/IMG_1526.JPG

You can avoid having to perform a calibration every time the system powers up by copying the calibration results from the Calibration Summary screen into the cmdline.txt file.

There are two properties in that file that relate to calibration:

  • sampling06: this holds the calibration results for Modes 0..6
  • sampling7: this holds the calibration results for Mode 7

The calibration values should be in one of two formats:

  • if all six offsets are the same, then a single number will suffice
  • if some of the offsets are different, then the full calibration (eight numbers) needs to be entered.

Here's an example that shows both formats being used:

# Important: All the properties must be on a single line, and no blank lines!
#
sampling06=3 sampling7=0,2,3,1,2,2,2,8,5 info=1 palette=0 scanlines=0 mux=0 elk=0 debug=0

See the comments in cmdline.txt for further details.

Test programs

A Beeb .ssd with a few test programs is available here: https://github.com/hoglet67/RGBtoHDMI/releases

Here's a quick summary of those programs:

  • ASPTEST - Aspect Ratio Test, Modes 0..6, also varies sync pulse width
  • COLBARS - Colour bars (useful for testing the palette feature)
  • M0TEST - Mode 0 test screen, to check monitor isn't rescaling
  • M7TEST - Mode 7 test screen, text in various colours (use white to calibrate)
  • M7TEST1/2/3/4 - additional Mode 7 tests with "tricky" characters
  • MASTCFG - restores the default configuration of a Master

Known issues

Mode 7 on some Model B has twittering pixels

Some Model B's have a truly dreadful 6MHz clock, such that sampling certain pixels reliably is impossible. The can be improved greatly by reducing the value of C48 from 270pF to 100pF. See this Stardot post for more details.

Troubleshooting

I have VideoNuLA installed and this doesn't work well

  • RGBtoHDMI is not compatible with VideoNuLA, and probably never will be. It needs a "digital" RGB signal.

My Pi 1, Pi 2, Pi 3 doesn't work

  • that is expected, you need a Pi Zero or Pi Zero W

The Reset button doesn't work

  • Did you install the reset header on the Pi?

No image on the TV/Monitor:

  • Check the SD Card is plugged in fully
  • If pressing the right button (Auto Calibrate) causes the left LED to light for about 10 secs the Pi is running
  • Check the config.txt monitor resolution setting are appropriate for your monitor

The image is wrong aspect ratio

  • Check your TV/Monitor Aspect Ratio setting (on LG TVs, the JustScan setting is best)
  • Check the config.txt monitor resolution setting are appropriate for your monitor

The image is jittering up and down

  • Check the elk setting in cmdline.txt is set to 0 for a Beeb/Master and 1 for an Elk

After Auto Calibration there are still flickering pixels

  • If this is in Mode 7 on a Model B, then try reducing C48 on the Beeb board to 100pF
  • otherwise seek advise from Hoglet

After a HDMI Clock Calibration the system is not genlocked

  • This might happen if you try to use a 60Hz screen mode

After a HDMI Clock Calibration the screen goes black

  • This might happen if you try to use a 60Hz screen mode